Skip to content

instants

instants #

Instants on a page, shown in the reader's own time zone.

  1. Ship. An instant leaves Python as its ISO form, never formatted: in markup as <time class="cg-instant"> (label_html), in a component's data as {"instant": iso} (label_json).
  2. Show. The script every page carries in its head (markup.LOCAL) defines cgLocal(iso) and cgText(label) for component scripts and rewrites every cg-instant element once the page has loaded, so a page carries no time zone of its own.

instant_of(value) #

value as an instant when it is one — a datetime or a cg.Time — else None.

Source code in capturegraph-ui/capturegraph_ui/core/instants.py
def instant_of(value: object) -> datetime | None:
    """``value`` as an instant when it is one — a ``datetime`` or a ``cg.Time`` — else ``None``."""
    if isinstance(value, cg.Time):
        return value.value
    return value if isinstance(value, datetime) else None

label_html(value) #

value as markup: an instant as a <time> the page shows locally, else its caption.

Source code in capturegraph-ui/capturegraph_ui/core/instants.py
def label_html(value: object) -> str:
    """``value`` as markup: an instant as a ``<time>`` the page shows locally, else its caption."""
    when = instant_of(value)
    if when is None:
        return text(caption(value))
    iso = when.isoformat()
    return element("time", {"class": "cg-instant", "datetime": iso}, text(iso))

label_json(value) #

value as a component script's label: {"instant": iso} for an instant, else text.

Source code in capturegraph-ui/capturegraph_ui/core/instants.py
def label_json(value: object) -> cg.JSONValue:
    """``value`` as a component script's label: ``{"instant": iso}`` for an instant, else text."""
    if value is None:
        return None
    when = instant_of(value)
    return caption(value) if when is None else {"instant": when.isoformat()}