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
Section
_StreamHandleMutable 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
Section.__init__
__init__(
block_id: str,
title: str,
summary: str | None,
auto_collapse: bool,
glyph: str,
colour: NamedColour | None,
) → NoneInitialize a closed section with its first visual state.
Parameters
Unique identifier used to correlate the section's events.
Heading shown in the section header.
Optional summary shown after the section completes.
Whether renderers should collapse the completed section.
Registered glyph shown alongside the section title.
Optional named colour applied to the section heading.
Section.__enter__
__enter__() → SectionOpen the section scope and emit its structural metadata.
Returns
This active section handle.
Section.__exit__
__exit__(
exc_type: type[BaseException] | None,
exc_value: BaseException | None,
traceback: TracebackType | None,
) → boolClose the section after all nested blocks have finished.
Parameters
Type of exception leaving the context, if any.
Exception leaving the context, if any.
Traceback associated with the exception, if any.
Returns
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,
) → NoneUpdate 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
Replacement title, or None to retain the current title.
Replacement registered glyph, or None to retain the current
glyph.
Replacement named colour, "default" to restore the neutral
appearance, or None to retain the current colour.
Raises
If the section is not currently open.
If the requested glyph is not registered.
Section.success
success(
title: str | None = None,
) → NoneApply 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
Optional replacement title.
Section.error
error(
title: str | None = None,
) → NoneApply 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
Optional replacement title.