yera.runtime.blocks.section

Emit a mutable container for related nested output blocks.

Opening a section establishes its block identity as the parent of output emitted inside the context. State snapshots can update its title, glyph, and colour while it remains open. Closing the context emits the terminal event after its children have completed.

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

__init__ — Initialize a closed section with its first visual state.
__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.__init__

__init__(
    block_id: str,
    title: str,
    summary: str | None,
    auto_collapse: bool,
    glyph: str,
    colour: NamedColour | None,
) → None

Initialize a closed section with its first visual state.

Parameters

block_id
type: str

Unique identifier used to correlate the section's events.

title
type: str

Heading shown in the section header.

summary
type: str | None

Optional summary shown after the section completes.

auto_collapse
type: bool

Whether renderers should collapse the completed section.

glyph
type: str

Registered glyph shown alongside the section title.

colour
type: NamedColour | None

Optional named colour applied to the section heading.

Section.__enter__

__enter__() → Section

Open the section scope and emit its structural metadata.

Returns

type: Section

This active section handle.

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.

Parameters

exc_type
type: type[BaseException] | None

Type of exception leaving the context, if any.

exc_value
type: BaseException | None

Exception leaving the context, if any.

traceback
type: TracebackType | None

Traceback associated with the exception, if any.

Returns

type: bool

False so exceptions propagate from the managed section.

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.