Skip to content

columns

columns #

Chart columns: one value per point, named, and shipped to the page by kind.

  1. Name. named_columns turns arrays of records into named columns, one per field the record type marks with a cg.Quantity, labelled from it ("Temperature (°C)").
  2. Encode. encode ships a column by the kind of its values: numbers as numbers, instants as epoch milliseconds; anything unrecorded is None.

Kind = Literal['number', 'instant'] #

How a column's values read: plain numbers, or instants in time.

Source = cg.Array | Mapping[str, cg.Array] #

An array of records, or columns already named.

Encoded dataclass #

A column as the page receives it.

Attributes:

Name Type Description
kind Kind

How the values read.

values list[float | None]

One number per point (epoch milliseconds for an instant), None where unrecorded.

Source code in capturegraph-ui/capturegraph_ui/charts/columns.py
@dataclass(frozen=True)
class Encoded:
    """A column as the page receives it.

    Attributes:
        kind: How the values read.
        values: One number per point (epoch milliseconds for an instant), ``None`` where unrecorded.
    """

    kind: Kind
    values: list[float | None]

encode(column) #

column shipped by kind: an instants column when every recorded value is a time.

encode(cg.Array([1, None, 2.5])).values  # [1.0, None, 2.5]
Source code in capturegraph-ui/capturegraph_ui/charts/columns.py
def encode(column: cg.Array | list[object]) -> Encoded:
    """``column`` shipped by kind: an instants column when every recorded value is a time.

    ```python
    encode(cg.Array([1, None, 2.5])).values  # [1.0, None, 2.5]
    ```
    """
    values = [_unwrapped(item) for item in column]
    recorded = [value for value in values if value is not None]
    if recorded and all(isinstance(value, datetime) for value in recorded):
        return Encoded(
            "instant",
            [value.timestamp() * 1000 if isinstance(value, datetime) else None for value in values],
        )
    return Encoded(
        "number",
        [
            float(value)
            if isinstance(value, (int, float)) and not isinstance(value, bool)
            else None
            for value in values
        ],
    )

named_columns(*sources) #

Every source's columns by label, and the fixed span of each that declares one.

Parameters:

Name Type Description Default
*sources Source

Arrays of records — each field marked with a cg.Quantity becomes a column — or dicts of columns already named.

()

Returns:

Type Description
tuple[dict[str, Array], dict[str, tuple[float, float]]]

The columns in source order, and the spans their quantities fix.

Raises:

Type Description
ValueError

If two columns share a label.

Source code in capturegraph-ui/capturegraph_ui/charts/columns.py
def named_columns(*sources: Source) -> tuple[dict[str, cg.Array], dict[str, tuple[float, float]]]:
    """Every source's columns by label, and the fixed span of each that declares one.

    Args:
        *sources: Arrays of records — each field marked with a ``cg.Quantity``
            becomes a column — or dicts of columns already named.

    Returns:
        The columns in source order, and the spans their quantities fix.

    Raises:
        ValueError: If two columns share a label.
    """
    columns: dict[str, cg.Array] = {}
    spans: dict[str, tuple[float, float]] = {}
    for source in sources:
        named = dict(source) if isinstance(source, Mapping) else _record_columns(source, spans)
        for label, column in named.items():
            if label in columns:
                raise ValueError(f"two columns are labelled {label!r}")
            columns[label] = column
    return columns, spans