formatting — text formatting helpers

tempura/formatting.py holds small string helpers used by the docs-facing examples to print compact summaries. There is no physics or math here; it exists so the worked examples can show readable output without repeating formatting boilerplate.

Helpers

format_mapping_block(...) renders a titled, indented key: value block (used for ROI and gate-voltage summaries), format_sequence_inline(...) renders a short comma-separated list, and format_voltage(...) formats a scalar with a sign and a trailing V. An optional value_formatter lets the mapping helper reuse format_voltage for voltage tables.

API

formatting

Small formatting helpers shared by docs-facing examples.

format_mapping_block(title, values, *, value_formatter=None)

Return a compact multi-line block for one keyed mapping.

Parameters:

Name	Type	Description	Default
title	str	Heading shown on the first line of the block.	required
values	Mapping[str, object]	Mapping whose items should be rendered one per line.	required
value_formatter	Callable[[object], object] | None	Optional callable used to format each mapping value before it is converted to text.	None

Returns:

Type	Description
str	Multi-line string containing title plus one indented key: value
str	line per mapping entry, or "{title}: none" for an empty mapping.

Source code in tempura/formatting.py

def format_mapping_block(
    title: str,
    values: Mapping[str, object],
    *,
    value_formatter: Callable[[object], object] | None = None,
) -> str:
    """Return a compact multi-line block for one keyed mapping.

    Args:
        title: Heading shown on the first line of the block.
        values: Mapping whose items should be rendered one per line.
        value_formatter: Optional callable used to format each mapping value
            before it is converted to text.

    Returns:
        Multi-line string containing ``title`` plus one indented ``key: value``
        line per mapping entry, or ``"{title}: none"`` for an empty mapping.
    """
    if not values:
        return f"{title}: none"

    formatter = str if value_formatter is None else value_formatter
    lines = [f"{title}:"]
    for key, value in values.items():
        lines.append(f"  {key}: {formatter(value)}")
    return "\n".join(lines)

format_sequence_inline(title, values)

Return one short inline summary for a sequence.

Parameters:

Name	Type	Description	Default
title	str	Label shown before the rendered sequence.	required
values	Sequence[object]	Ordered values to render inline.	required

Returns:

Type	Description
str	Single-line string containing title plus a comma-separated value
str	list, or "{title}: none" for an empty sequence.

Source code in tempura/formatting.py

def format_sequence_inline(
    title: str,
    values: Sequence[object],
) -> str:
    """Return one short inline summary for a sequence.

    Args:
        title: Label shown before the rendered sequence.
        values: Ordered values to render inline.

    Returns:
        Single-line string containing ``title`` plus a comma-separated value
        list, or ``"{title}: none"`` for an empty sequence.
    """
    if not values:
        return f"{title}: none"
    return f"{title}: {', '.join(str(value) for value in values)}"

format_voltage(value)

Return one scalar voltage with a sign and units.

Parameters:

Name	Type	Description	Default
value	object	Scalar value that can be converted to float.	required

Returns:

Type	Description
str	Signed voltage string with two decimal places and a trailing " V".

Source code in tempura/formatting.py

def format_voltage(value: object) -> str:
    """Return one scalar voltage with a sign and units.

    Args:
        value: Scalar value that can be converted to ``float``.

    Returns:
        Signed voltage string with two decimal places and a trailing ``" V"``.
    """
    return f"{float(value):+.2f} V"