Module

utils.live_progress

Live progress display system with profile-aware output.

Provides in-place progress updates that minimize terminal scrolling while showing appropriate detail for each user profile.

View source
3 Classes

Classes

PhaseStatus
Status of a build phase.
0

Status of a build phase.

Inherits from Enum
PhaseProgress dataclass
Track progress for a single build phase.
2

Track progress for a single build phase.

Attributes

Name Type Description
name str
status PhaseStatus
current int
total int | None
current_item str
elapsed_ms float
start_time float | None
metadata dict[str, Any]
recent_items list[str]

Methods 2

get_percentage
Get completion percentage.
0 float | None 
def get_percentage(self) -> float | None

Get completion percentage.

Returns

float | None

get_elapsed_str
Get formatted elapsed time string.
0 str 
def get_elapsed_str(self) -> str

Get formatted elapsed time string.

Returns

str

LiveProgressManager
Manager for live progress updates across build phases. Features: - Profile-aware display (Writer/T…
15

Manager for live progress updates across build phases.

Features:

  • Profile-aware display (Writer/Theme-Dev/Developer)
  • In-place updates (no scrolling)
  • Graceful fallback for CI/non-TTY
  • Context manager for clean setup/teardown

Methods 5

add_phase
Register a new phase.
3 None 
def add_phase(self, phase_id: str, name: str, total: int | None = None) -> None

Register a new phase.

Parameters 3
phase_id str

Unique identifier for the phase
name str

Display name for the phase
total int | None

Total number of items to process (if known)
start_phase
Mark phase as running.
1 None 
def start_phase(self, phase_id: str) -> None

Mark phase as running.

Parameters 1
phase_id str

Phase identifier
update_phase
Update phase progress.
3 None 
def update_phase(self, phase_id: str, current: int | None = None, current_item: str | None = None, **metadata: Any) -> None

Update phase progress.

Parameters 3
phase_id str

Phase identifier
current int | None

Current progress count
current_item str | None

Current item being processed **metadata: Additional metadata to track
complete_phase
Mark phase as complete.
2 None 
def complete_phase(self, phase_id: str, elapsed_ms: float | None = None) -> None

Mark phase as complete.

Parameters 2
phase_id str

Phase identifier
elapsed_ms float | None

Total elapsed time in milliseconds (optional)
fail_phase
Mark phase as failed.
2 None 
def fail_phase(self, phase_id: str, error: str) -> None

Mark phase as failed.

Parameters 2
phase_id str

Phase identifier
error str

Error message
Internal Methods 10
__init__
Initialize live progress manager.
3 None 
def __init__(self, profile: BuildProfile, console: Console | None = None, enabled: bool = True)

Initialize live progress manager.

Parameters 3
profile BuildProfile

Build profile (Writer/Theme-Dev/Developer)
console Console | None

Rich console instance (creates one if not provided)
enabled bool

Whether live progress is enabled
__enter__
Enter context manager.
0 LiveProgressManager 
def __enter__(self) -> LiveProgressManager

Enter context manager.

Returns

LiveProgressManager

__exit__
Exit context manager.
3 None 
def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) -> None

Exit context manager.

Parameters 3
exc_type type[BaseException] | None
exc_val BaseException | None
exc_tb TracebackType | None
_update_display
Update the live display or print fallback.
1 None 
def _update_display(self, force: bool = False) -> None

Update the live display or print fallback.

Parameters 1
force bool
_render
Render the progress display based on profile.
0 RenderableType 
def _render(self) -> RenderableType

Render the progress display based on profile.

Returns

RenderableType

_render_writer
Compact display for writers. Shows: phase name, progress bar, current count, c…
0 RenderableType 
def _render_writer(self) -> RenderableType

Compact display for writers.

Shows: phase name, progress bar, current count, current item

Returns

RenderableType

_render_theme_dev
Detailed display with recent items for theme developers. Shows: progress bar, …
0 RenderableType 
def _render_theme_dev(self) -> RenderableType

Detailed display with recent items for theme developers.

Shows: progress bar, recent items, elapsed time

Returns

RenderableType

_render_developer
Full observability display for developers. Shows: all phases, metrics, perform…
0 RenderableType 
def _render_developer(self) -> RenderableType

Full observability display for developers.

Shows: all phases, metrics, performance stats

Returns

RenderableType

_get_status_icon
Get icon for phase status.
1 str 
def _get_status_icon(self, status: PhaseStatus) -> str

Get icon for phase status.

Parameters 1
status PhaseStatus
Returns

str

_print_fallback
Fallback for non-TTY environments (CI, redirected output). Prints traditional …
0 None 
def _print_fallback(self) -> None

Fallback for non-TTY environments (CI, redirected output).

Prints traditional sequential output with minimal updates.