yera.runtime.blocks.section

Collapsible section block implementation.

Symbols

class Section — Mutable context manager that groups related output blocks.

Section

Inherits: _StreamHandle

Mutable context manager that groups related output blocks.

A section establishes itself as the parent of blocks emitted within its context. Its title, glyph, and colour can be updated while it is open. Calling success() or error() applies the corresponding standard appearance without closing the context.

Section objects are created through yera.section rather than instantiated directly.

Methods

__enter__ — Open the section scope and emit its structural metadata.
__exit__ — Close the section after all nested blocks have finished.
update — Update the section's current visual state.
success — Apply the standard successful section appearance.
error — Apply the standard erroneous section appearance.

Section.__enter__

__enter__() → Section

Open the section scope and emit its structural metadata.

Section.__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) → bool

Close the section after all nested blocks have finished.

Section.update

update(
    title: str | None = None,
    glyph: str | None = None,
    colour: NamedColour | Literal['default'] | None = None,
) → None

Update the section's current visual state.

Every update emits a complete section snapshot while retaining properties that were not supplied. Passing "default" as the colour restores the section's default neutral appearance.

Parameters

title
type: str | None = None

Replacement title, or None to retain the current title.

glyph
type: str | None = None

Replacement registered glyph, or None to retain the current glyph.

colour
type: NamedColour | Literal['default'] | None = None

Replacement named colour, "default" to restore the neutral appearance, or None to retain the current colour.

Raises

RuntimeError

If the section is not currently open.

ValueError

If the requested glyph is not registered.

Section.success

success(
    title: str | None = None,
) → None

Apply the standard successful section appearance.

The section remains open and may continue receiving child output. If no title is supplied, its current title is preserved.

Parameters

title
type: str | None = None

Optional replacement title.

Section.error

error(
    title: str | None = None,
) → None

Apply the standard erroneous section appearance.

The section remains open and may continue receiving child output. If no title is supplied, its current title is preserved.

Parameters

title
type: str | None = None

Optional replacement title.