Text and dates¶

say ¶

say(template: Template) -> str

Make text from a t-string. Each value shows by what it is, as describe explains.

A conversion !r in the t-string gives the repr of the value. A format after a colon goes to describe.

Parameters:

Name	Type	Description	Default
`template`	`Template`	A Python 3.14 t-string. An example is `t"{fact} came out {outcome}"`.	required

Returns:

Type	Description
`str`	The text.

Example

from scriptt.world import say

report = today.one(Task, id="t2")
say(t"Today, {report} is {report.status}.")
# -> 'Today, task t2 is open.'
say(t"The mean is {17.490000000001:.3}.")  # 'The mean is 17.5.'

describe ¶

describe(value: Any, spec: str = '') -> str

Write 1 value as text by what it is. say calls this for each value of a t-string.

A value with a __describe__ method uses it. The other values follow these rules.

A number shows its significant figures.
A date shows as "8 Oct 2026".
An enum shows its value.
A list shows as "a, b and c".
Any other value uses format.

Parameters:

Name	Type	Description	Default
`value`	`Any`	The value to write.	required
`spec`	`str`	The format that follows the colon in `{value:spec}`. The default is an empty text. It means no format. A number takes `.3` for 3 significant figures. A date takes a `strftime` format. Text takes `58` to pad it to 58 characters.	`''`

Returns:

Type	Description
`str`	The text of the value.

Example

import datetime as dt
from scriptt.world import describe

describe(1.5000000001)  # -> '1.5'
describe(dt.date(2026, 11, 2))  # -> '2 Nov 2026'
describe(["a", "b", "c"])  # -> 'a, b and c'
describe(True)  # -> 'yes'
describe(Status.DONE)  # -> 'done'

significant ¶

significant(
    value: float,
    digits: int | None = None,
    *,
    grouping: bool = True,
) -> str

Write a number with its significant figures only, and with no float noise.

digits gives at most that number of significant figures.
Without digits, a value that is exact to 0 or 1 or 2 decimals keeps them. Any other value shows 4 significant figures.
A value under 0.0001 is written with an exponent. An example is 1.5e-09.

Parameters:

Name	Type	Description	Default
`value`	`float`	The number.	required
`digits`	`int \| None`	The most significant figures to show. The default `None` means the rules above.	`None`
`grouping`	`bool`	Whether to put a comma between thousands. The default is `True`. Use `False` for a repr.	`True`

Returns:

Type	Description
`str`	The number as text.

Example

from scriptt.world import significant

significant(276.85)  # -> '276.85'
significant(2.5266666)  # -> '2.527'
significant(0.19166, 2)  # -> '0.19'
significant(12345678.0)  # -> '12,345,678'
significant(12345678.0, grouping=False)  # -> '12345678'

relative ¶

relative(
    earlier_or_later: date | datetime | None,
    reference: date | datetime | None,
) -> str

Say how a date stands to a reference date. An example is "3 days before".

Only the calendar day counts. A time of day is ignored. A fact that is true for all time has no start date. If either date is None, the text says that the time is not known.

Parameters:

Name	Type	Description	Default
`earlier_or_later`	`date \| datetime \| None`	The date to describe. A `datetime.date` or `datetime.datetime` or `None`.	required
`reference`	`date \| datetime \| None`	The date to compare with. A `datetime.date` or `datetime.datetime` or `None`.	required

Returns:

Type	Description
`str`	One of these texts.
`str`	"3 days before"
`str`	"1 day after"
`str`	"on the same day as"
`str`	"at a time not known relative to"

Example

import datetime as dt
from scriptt.world import relative

relative(dt.date(2026, 11, 2), dt.date(2026, 11, 4))  # -> '2 days before'
relative(dt.date(2026, 11, 4), dt.date(2026, 11, 4))
# -> 'on the same day as'
relative(None, dt.date(2026, 11, 4))  # -> 'at a time not known relative to'

when ¶

when(
    value: Moment, *, base: datetime | None = None
) -> datetime

Read a moment and give a datetime.datetime with no time zone. Use it for the known argument and for any other time.

ISO 8601 text is read first, so "2026-10-08" is always 8 Oct. Text with a time zone is changed to UTC. This makes 2 times from 2 zones compare correctly. Text with no zone is taken as written. Give every known time in 1 zone or with its zone.

"2026/10/08" and "2026.10.08" are year first too. "2026-10" is 1 Oct.
A date with no time gives midnight.
dateparser reads other text. Examples are "8 Oct 2026", "10 Oct 2026 22:02" and "yesterday".

Parameters:

Name	Type	Description	Default
`value`	`Moment`	The moment. Give a `datetime.datetime`, a `datetime.date` or text. A `datetime` with a time zone is changed to UTC.	required
`base`	`datetime \| None`	The time that relative text such as "yesterday" counts from. The default `None` means now.	`None`

Returns:

Type	Description
`datetime`	The moment as a `datetime.datetime` with no time zone.

Raises:

Type	Description
`ValueError`	The text is not a date. This includes a bare year ("2026"). It also includes ISO-shaped text that is not a date ("2026-13-01") and a number-only date that could be day/month or month/day ("8/10/2026").
`TypeError`	`value` is not a date, a datetime or text.

Example

from scriptt.world import when

when("2 Nov 2026")  # -> datetime.datetime(2026, 11, 2, 0, 0)
when("2 Nov 2026 09:00")  # -> datetime.datetime(2026, 11, 2, 9, 0)
when("2026-11-02T09:00-07:00")  # -> datetime.datetime(2026, 11, 2, 16, 0)

Moment ¶

Moment = date | datetime | str

A date or a time, in any of 3 forms: a datetime.date, a datetime.datetime, or text.

Text can be ISO 8601 ("2026-10-08"), or words such as "8 Oct 2026", "10 Oct 2026 22:02" or "yesterday". Every date argument of the library takes a Moment and reads it with when.

diagram ¶

diagram(*kinds: type[Fact]) -> str

Draw fact types as a Mermaid class diagram. Each type shows its fields. A + stands before each key field. An arrow goes from each Ref field to the type it points to. An arrow also goes from a subtype to the type it extends.

Parameters:

Name	Type	Description	Default
`*kinds`	`type[Fact]`	The types to draw. An arrow is drawn only between types that you give.	`()`

Returns:

Type	Description
`str`	The diagram as Mermaid text for a `mermaid` code block or for `marimo.mermaid`.

Example

from scriptt.world import Fact, Key, Ref, diagram


class TodoList(Fact):
    name: Key[str]


class Task(Fact):
    id: Key[str]
    list: Ref[TodoList]


print(diagram(TodoList, Task))
# classDiagram
#   class TodoList {
#     +name str
#   }
#   ...
#   Task --> TodoList : list