ddp_utils.console.spinner

import ddp_utils.console.spinner

Provide sentinel-aware spinner configuration and three rendering backends.

SimpleSpinner participates in the shared Console or layout renderer registry, SmoothSpinner writes a carriage-return line directly to stdout, and RichSpinner owns a transient Rich Live display.

Examples

Provide sentinel-aware spinner configuration and three rendering backends:

with create_spinner("Loading", type="simple") as spinner:
    perform_work()

class ddp_utils.console.spinner.SpinnerConfig(type: Any = UNSET, frames: Any = UNSET, interval: Any = UNSET, spinner_color: Any = UNSET, text_color: Any = UNSET, position: Any = UNSET, format_str: Any = UNSET, template: Any = UNSET)

Bases: object

Independent configuration for Spinner.

Unlike a plain dataclass, this class preserves explicitness metadata. That allows merge()/configure() to stay honest even when the incoming value is equal to the class default.

Examples

Independent configuration for Spinner:

config = SpinnerConfig(interval=0.2, spinner_color="cyan")

Initialize spinner appearance while preserving which values were explicit.

Each omitted argument uses the UNSET sentinel and receives its class default.

Parameters

Name	Type	Description
type	str	Spinner backend name or configured spinner type.
frames	List[str] | None	Optional animation frame sequence; an empty sequence restores defaults.
interval	float	Delay in seconds between animation frames.
spinner_color	str	Color applied to the animated glyph.
text_color	str	Color applied to the adjacent message.
position	str	Spinner placement, normalized to left or right.
format_str	str | None	Format containing spinner and message placeholders.
template	List[Tuple[str, str]] | None	Explicit sequence of rendering parts.

Examples

Initialize spinner appearance while preserving which values were explicit:

config = SpinnerConfig(type="smooth", interval=0.2)

is_explicit(name: str) → bool

Return True if the field was explicitly provided / overridden.

Parameters

Name	Type	Description
name	str	Configuration field name.

Returns

Type	Description
bool	True when the field was explicitly supplied or overridden.

Examples

Return True if the field was explicitly provided / overridden:

explicit = config.is_explicit("interval")

copy() → SpinnerConfig

Return a full copy preserving values and explicitness metadata.

Returns

Type	Description
SpinnerConfig	Independent configuration preserving values and explicitness.

Examples

Return a full copy preserving values and explicitness metadata:

cloned = config.copy()

to_kwargs() → Dict[str, Any]

Return config as kwargs payload.

Explicitness metadata is included under a reserved internal key so that merge(**config.to_kwargs()) preserves sentinel-aware semantics.

Returns

Type	Description
Dict[str, Any]	Keyword payload including reserved explicitness metadata.

Examples

Return config as kwargs payload:

options = config.to_kwargs()

merge(**overrides) → SpinnerConfig

Return a merged config copy.

Rules:

• None values are ignored (backward-compatible behavior);

• “__explicit_fields__” may be supplied to preserve explicitness;

• absent explicit metadata means all applied override fields are explicit.

Parameters

Name	Description
overrides	Configuration overrides; None values are ignored.

Returns

Type	Description
SpinnerConfig	Merged configuration copy; the original is unchanged.

Examples

Return a merged config copy:

updated = config.merge(interval=0.05, spinner_color="cyan")

class ddp_utils.console.spinner.BaseSpinner(message: str = 'Loading.', frames: List[str] | None = None, interval: float | None = None, spinner_color: str | None = None, text_color: str | None = None, position: str | None = None, format_str: str | None = None, template: List[Tuple[str, str]] | None = None, console: Console | None = None, layout: ConsoleLayout | None = None, config: SpinnerConfig | None = None)

Bases: object

Provide shared configuration, template parsing, and rendering state for spinners.

Examples

Provide shared configuration, template parsing, and rendering state for spinners:

spinner = BaseSpinner("Loading", interval=0.2)

Initialize spinner.

Constructor kwargs are explicit overrides over the provided/base config.

Parameters

Name	Type	Description
message	str	Text displayed beside the animated glyph.
frames	Optional[List[str]]	Optional animation frame sequence; an empty sequence restores defaults.
interval	Optional[float]	Delay in seconds between animation frames.
spinner_color	Optional[str]	Color applied to the animated glyph.
text_color	Optional[str]	Color applied to the adjacent message.
position	Optional[str]	Spinner placement, normalized to left or right.
format_str	Optional[str]	Format containing spinner and message placeholders.
template	Optional[List[Tuple[str, str]]]	Explicit sequence of rendering parts.
console	Optional[Console]	Console used for coordinated rendering and cursor access.
layout	Optional[ConsoleLayout]	Optional layout that owns the status renderer.
config	Optional[SpinnerConfig]	Optional base spinner configuration.

Examples

Initialize spinner:

spinner = BaseSpinner("Loading", position="right")

render_line() → str

Render one visible spinner line.

Returns

Type	Description
str	ANSI-styled line padded or truncated to terminal width.

Examples

Render one visible spinner line:

line = spinner.render_line()

update_message(new_message: str)

Change the spinner’s message text.

Parameters

Name	Type	Description
new_message	str	Replacement message text.

Examples

Change the spinner’s message text:

spinner.update_message(new_message="Almost done")

set_spinner_color(color: str)

Set the color used for the spinner glyph.

Parameters

Name	Type	Description
color	str	Replacement color name.

Examples

Set the color used for the spinner glyph:

spinner.set_spinner_color(color="cyan")

set_text_color(color: str)

Set the color used for the message text.

Parameters

Name	Type	Description
color	str	Replacement color name.

Examples

Set the color used for the message text:

spinner.set_text_color(color="cyan")

set_frames(frames: List[str])

Replace the animation frame sequence, or reset to the default frames.

Parameters

Name	Type	Description
frames	List[str]	Optional animation frame sequence; an empty sequence restores defaults.

Examples

Replace the animation frame sequence, or reset to the default frames:

spinner.set_frames(frames=[".", "..", "..."])

set_interval(interval: float)

Set the delay in seconds between animation frames.

Parameters

Name	Type	Description
interval	float	Delay in seconds between animation frames.

Examples

Set the delay in seconds between animation frames:

spinner.set_interval(interval=0.2)

set_template(template: List[Tuple[str, str]])

Replace the render template with explicit (part, style) pairs.

Parameters

Name	Type	Description
template	List[Tuple[str, str]]	Explicit sequence of rendering parts.

Examples

Replace the render template with explicit (part, style) pairs:

spinner.set_template(template=[("spinner", "{spinner} "), ("message", "{message}")])

set_format(format_str: str)

Set the spinner’s layout from a format string, parsing it into a template.

Parameters

Name	Type	Description
format_str	str	Format containing spinner and message placeholders.

Examples

Set the spinner’s layout from a format string, parsing it into a template:

spinner.set_format(format_str="{spinner} {message}")

start()

Start animating the spinner. Must be implemented by subclasses.

Raises

Exception	Description
NotImplementedError	A concrete backend must implement startup.

Examples

Start animating the spinner. Must be implemented by subclasses:

SimpleSpinner("Loading").start()

stop()

Stop animating the spinner. Must be implemented by subclasses.

Raises

Exception	Description
NotImplementedError	A concrete backend must implement shutdown.

Examples

Stop animating the spinner. Must be implemented by subclasses:

SimpleSpinner("Loading").stop()

class ddp_utils.console.spinner.SimpleSpinner(message='Loading.', frames=None, interval=None, spinner_color=None, text_color=None, position=None, format_str=None, template=None, console=None, layout=None, config=None)

Bases: BaseSpinner

Render an animated status line through a console or layout.

The spinner registers a coordinated renderer, advances frames on its worker thread, and requests redraws without writing an independent terminal line.

Examples

Create a spinner for explicit lifecycle management:

spinner = SimpleSpinner("Loading")

Initialize a spinner rendered through a Console or layout renderer registry.

Parameters

Name	Description
message	Text displayed beside the animated glyph.
frames	Optional animation frame sequence; an empty sequence restores defaults.
interval	Delay in seconds between animation frames.
spinner_color	Color applied to the animated glyph.
text_color	Color applied to the adjacent message.
position	Spinner placement, normalized to left or right.
format_str	Format containing spinner and message placeholders.
template	Explicit sequence of rendering parts.
console	Console used for coordinated rendering and cursor access.
layout	Optional layout that owns the status renderer.
config	Optional base spinner configuration.

Examples

Initialize a spinner rendered through a Console or layout renderer registry:

spinner = SimpleSpinner("Loading", interval=0.2)

start() → None

Register the spinner’s renderer and start its animation thread.

Examples

Register the spinner’s renderer and start its animation thread:

spinner.start()

stop() → None

Stop the animation thread and unregister the spinner’s renderer.

Examples

Stop the animation thread and unregister the spinner’s renderer:

spinner.stop()

close() → None

Alias for stop().

Examples

Alias for stop():

spinner.close()

update_message(new_message: str) → None

Change the spinner’s message text and trigger a redraw.

Parameters

Name	Type	Description
new_message	str	Replacement message text.

Examples

Change the spinner’s message text and trigger a redraw:

spinner.update_message(new_message="Almost done")

set_spinner_color(color: str) → None

Set the spinner glyph color and trigger a redraw.

Parameters

Name	Type	Description
color	str	Replacement color name.

Examples

Set the spinner glyph color and trigger a redraw:

spinner.set_spinner_color(color="cyan")

set_text_color(color: str) → None

Set the message text color and trigger a redraw.

Parameters

Name	Type	Description
color	str	Replacement color name.

Examples

Set the message text color and trigger a redraw:

spinner.set_text_color(color="cyan")

set_interval(interval: float) → None

Set the delay in seconds between animation frames.

Parameters

Name	Type	Description
interval	float	Delay in seconds between animation frames.

Examples

Set the delay in seconds between animation frames:

spinner.set_interval(interval=0.2)

set_frames(frames: List[str]) → None

Replace the animation frame sequence and trigger a redraw.

Parameters

Name	Type	Description
frames	List[str]	Optional animation frame sequence; an empty sequence restores defaults.

Examples

Replace the animation frame sequence and trigger a redraw:

spinner.set_frames(frames=[".", "..", "..."])

set_position(position: str) → None

Set spinner position and rebuild its derived template when allowed.

An invalid value is normalized to left. Explicit template or format customization is preserved. A registered spinner requests an immediate coordinated redraw after updating its configuration.

Parameters

Name	Type	Description
position	str	Spinner placement, normalized to left or right.

Examples

Move the spinner glyph after its message:

spinner.set_position(position="right")

set_template(template: List[Tuple[str, str]]) → None

Replace the render template with explicit (part, style) pairs and trigger a redraw.

Parameters

Name	Type	Description
template	List[Tuple[str, str]]	Explicit sequence of rendering parts.

Examples

Replace the render template with explicit (part, style) pairs and trigger a redraw:

spinner.set_template(template=[("spinner", "{spinner} "), ("message", "{message}")])

set_format(format_str: str) → None

Set the spinner’s layout from a format string and trigger a redraw.

Parameters

Name	Type	Description
format_str	str	Format containing spinner and message placeholders.

Examples

Set the spinner’s layout from a format string and trigger a redraw:

spinner.set_format(format_str="{spinner} {message}")

configure(config: SpinnerConfig | None = None, **kwargs) → None

Reconfigure spinner at runtime.

If template/format are not explicitly provided, position still controls the derived default template.

Parameters

Name	Type	Description
config	SpinnerConfig | None	Optional base spinner configuration.
kwargs		Keyword constructor options forwarded to the selected backend.

Examples

Reconfigure spinner at runtime:

spinner.configure(SpinnerConfig(interval=0.2), text_color="cyan")

get_config() → SpinnerConfig

Return a copy of the current spinner configuration.

Returns

Type	Description
SpinnerConfig	Independent copy of the current configuration.

Examples

Return a copy of the current spinner configuration:

config = spinner.get_config()

finish(message: str | None = None) → None

Optionally publish a final message and remove the live spinner.

Parameters

Name	Type	Description
message	str | None	Optional stable completion line written after removal.

Examples

Finish a manually managed spinner cleanly:

spinner.finish("Browser ready")

remove() → None

Remove the spinner from its owning console or group.

Examples

Clear a spinner without printing a final line:

spinner.remove()

class ddp_utils.console.spinner.SmoothSpinner(message: str = 'Loading.', frames: List[str] | None = None, interval: float | None = None, spinner_color: str | None = None, text_color: str | None = None, position: str | None = None, format_str: str | None = None, template: List[Tuple[str, str]] | None = None, console: Console | None = None, layout: ConsoleLayout | None = None, config: SpinnerConfig | None = None)

Bases: BaseSpinner

Animate a carriage-return status line directly through stdout.

This backend runs its own thread and is intended for output without an active shared layout or footer.

Examples

Animate a carriage-return status line directly through stdout:

spinner = SmoothSpinner("Loading")

Initialize spinner.

Constructor kwargs are explicit overrides over the provided/base config.

Parameters

Name	Type	Description
message	str	Text displayed beside the animated glyph.
frames	Optional[List[str]]	Optional animation frame sequence; an empty sequence restores defaults.
interval	Optional[float]	Delay in seconds between animation frames.
spinner_color	Optional[str]	Color applied to the animated glyph.
text_color	Optional[str]	Color applied to the adjacent message.
position	Optional[str]	Spinner placement, normalized to left or right.
format_str	Optional[str]	Format containing spinner and message placeholders.
template	Optional[List[Tuple[str, str]]]	Explicit sequence of rendering parts.
console	Optional[Console]	Console used for coordinated rendering and cursor access.
layout	Optional[ConsoleLayout]	Optional layout that owns the status renderer.
config	Optional[SpinnerConfig]	Optional base spinner configuration.

Examples

Initialize spinner:

spinner = BaseSpinner("Loading", position="right")

start()

Start the animation thread if it isn’t already running.

Examples

Start the animation thread if it isn’t already running:

spinner.start()

stop()

Stop the animation thread, clear the rendered line and wait for it to exit.

Examples

Stop the animation thread, clear the rendered line and wait for it to exit:

spinner.stop()

update_message(new_message)

Change the spinner’s message text.

Parameters

Name	Description
new_message	Replacement message text.

Examples

Change the spinner’s message text:

spinner.update_message(new_message="Almost done")

class ddp_utils.console.spinner.RichSpinner(*args, **kwargs)

Bases: BaseSpinner

Animate a transient Rich Live display in a background thread.

Use this backend when Rich already owns terminal rendering.

Examples

Animate a transient Rich Live display in a background thread:

spinner = RichSpinner("Loading")

Initialize shared spinner state and Rich live-display handles.

Parameters

Name	Description
args	Positional constructor or context-exit arguments forwarded unchanged.
kwargs	Keyword constructor options forwarded to the selected backend.

Examples

Initialize shared spinner state and Rich live-display handles:

spinner = RichSpinner("Loading", interval=0.2)

start()

Start a transient rich Live display and begin animating it in a background thread.

Raises

Exception	Description
ImportError	Rich is unavailable in the runtime environment.

Examples

Start a transient rich Live display and begin animating it in a background thread:

spinner.start()

update_message(new_message)

Change the spinner’s message text and refresh the live display.

Parameters

Name	Description
new_message	Replacement message text.

Examples

Change the spinner’s message text and refresh the live display:

spinner.update_message(new_message="Almost done")

set_spinner_color(color)

Set the spinner glyph color and refresh the live display.

Parameters

Name	Description
color	Replacement color name.

Examples

Set the spinner glyph color and refresh the live display:

spinner.set_spinner_color(color="cyan")

set_text_color(color)

Set the message text color and refresh the live display.

Parameters

Name	Description
color	Replacement color name.

Examples

Set the message text color and refresh the live display:

spinner.set_text_color(color="cyan")

set_frames(frames)

Replace the animation frame sequence and refresh the live display.

Parameters

Name	Description
frames	Optional animation frame sequence; an empty sequence restores defaults.

Examples

Replace the animation frame sequence and refresh the live display:

spinner.set_frames(frames=[".", "..", "..."])

set_template(template)

Replace the render template and refresh the live display.

Parameters

Name	Description
template	Explicit sequence of rendering parts.

Examples

Replace the render template and refresh the live display:

spinner.set_template(template=[("spinner", "{spinner} "), ("message", "{message}")])

set_format(format_str)

Set the spinner’s layout from a format string and refresh the live display.

Parameters

Name	Description
format_str	Format containing spinner and message placeholders.

Examples

Set the spinner’s layout from a format string and refresh the live display:

spinner.set_format(format_str="{spinner} {message}")

stop()

Stop the animation thread and tear down the rich Live display.

Examples

Stop the animation thread and tear down the rich Live display:

spinner.stop()

ddp_utils.console.spinner.create_spinner(message: str = 'Loading.', *, type: str = 'simple', **kwargs) → BaseSpinner

Create the spinner backend selected by its type name.

Parameters

Name	Type	Description
message	str	Text displayed beside the animated glyph.
type	str	Spinner backend name or configured spinner type.
kwargs		Keyword constructor options forwarded to the selected backend.

Returns

Type	Description
BaseSpinner	New SimpleSpinner, SmoothSpinner, or RichSpinner instance.

Raises

Exception	Description
ValueError	The requested spinner type is unknown.

Examples

Create the spinner backend selected by its type name:

spinner = create_spinner("Loading", type="smooth")

ddp_utils.console.spinner.Spinner

alias of SimpleSpinner