yera.runtime.blocks.spinner
Emit mutable progress state for a bounded operation.
A spinner begins with an active state, may emit replacement state snapshots,
and resolves when its context exits. Normal completion includes elapsed time;
an exception, failed app exit, or explicit fail() call selects the failed
terminal appearance without suppressing the underlying exception.
Symbols
SpinnerStream
_StreamHandleManage progress snapshots and terminal state for one spinner block.
Entering the context emits the active state and starts elapsed-time measurement. Updates replace any supplied presentation fields. Leaving the context emits either the configured successful state or a failed state, followed by the block's terminal event.
Methods
SpinnerStream.__init__
__init__(
block_id: str,
initial_message: str | None = None,
glyph: str = 'run',
colour: NamedColour = 'orange',
end_message: str | None = None,
end_glyph: str = 'check',
end_colour: NamedColour = 'green',
)Initialize a spinner stream.
Parameters
Identity shared by all spinner updates.
Message shown while work is active.
Glyph shown while active.
Colour shown while active.
Message shown after successful completion.
Glyph shown after successful completion.
Colour shown after successful completion.
SpinnerStream.__enter__
__enter__()Start the spinner and open its block scope.
Returns
This active spinner handle.
SpinnerStream.__exit__
__exit__(
exc_type: type[BaseException],
exc_value: BaseException | None,
traceback: TracebackType,
)Finish the spinner and close its block scope.
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 block.
SpinnerStream.update
update(
message: str | None = None,
glyph: str | None = None,
colour: NamedColour | None = None,
) → NoneUpdate any supplied part of the spinner's active state.
Parameters
Replacement message, or None to retain the current one.
Replacement glyph, or None to retain the current one.
Replacement colour, or None to retain the current one.
SpinnerStream.fail
fail(
message: str = 'Failed',
) → NoneResolve the spinner with a failed terminal appearance.
Calling this method does not raise an exception or end the surrounding block immediately. The failed state is emitted when the spinner context exits, allowing callers to handle expected failures without exception-based control flow.
Parameters
Message shown in the failed terminal state.