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

class SpinnerStream — Manage progress snapshots and terminal state for one spinner block.

SpinnerStream

Inherits: _StreamHandle

Manage 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

__init__ — Initialize a spinner stream.
__enter__ — Start the spinner and open its block scope.
__exit__ — Finish the spinner and close its block scope.
update — Update any supplied part of the spinner's active state.
fail — Resolve the spinner with a failed terminal appearance.

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

block_id
type: str

Identity shared by all spinner updates.

initial_message
type: str | None = None

Message shown while work is active.

glyph
type: str = 'run'

Glyph shown while active.

colour
type: NamedColour = 'orange'

Colour shown while active.

end_message
type: str | None = None

Message shown after successful completion.

end_glyph
type: str = 'check'

Glyph shown after successful completion.

end_colour
type: NamedColour = 'green'

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

exc_type
type: type[BaseException]

Type of exception leaving the context, if any.

exc_value
type: BaseException | None

Exception leaving the context, if any.

traceback
type: TracebackType

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,
) → None

Update any supplied part of the spinner's active state.

Parameters

message
type: str | None = None

Replacement message, or None to retain the current one.

glyph
type: str | None = None

Replacement glyph, or None to retain the current one.

colour
type: NamedColour | None = None

Replacement colour, or None to retain the current one.

SpinnerStream.fail

fail(
    message: str = 'Failed',
) → None

Resolve 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
type: str = 'Failed'

Message shown in the failed terminal state.