Skip to main content

Progress Tracker

Progress tracking with Rich tree visualization and live updates.

Classes​

StepTracker​

Track and render hierarchical steps with Rich tree visualization.

Supports live auto-refresh via an attached refresh callback and provides a fluent interface for step management.

Methods​

add_step​
add_step(self, key: str, label: str, parent: Optional[str] = None) -> 'StepTracker'

Add a step to the tracking tree.

Parameters:

  • key (str, required) - Unique identifier for the step
  • label (str, required) - Display label for the step
  • parent (Optional, optional) - Parent step key (None for root level)

Returns: StepTracker

attach_refresh​
attach_refresh(self, callback: Callable[[], NoneType]) -> 'StepTracker'

Attach refresh callback for live updates.

Parameters:

  • callback (Callable, required) - Function to call when display needs refreshing

Returns: StepTracker

complete_step​
complete_step(self, key: str, detail: str = '') -> 'StepTracker'

Mark step as completed successfully.

Parameters:

  • key (str, required) - Step identifier
  • detail (str, optional) - Optional completion message

Returns: StepTracker

create_default​
create_default(title: str = 'Progress') -> 'StepTracker'

Factory method for default configuration.

Parameters:

  • title (str, optional) - Title for the progress tree - Default: Progress

Returns: StepTracker

error_step​
error_step(self, key: str, detail: str = '') -> 'StepTracker'

Mark step as failed with error.

Parameters:

  • key (str, required) - Step identifier
  • detail (str, optional) - Error message

Returns: StepTracker

render​
render(self) -> rich.tree.Tree

Render current state as Rich tree.

Returns: Tree

skip_step​
skip_step(self, key: str, detail: str = '') -> 'StepTracker'

Mark step as skipped.

Parameters:

  • key (str, required) - Step identifier
  • detail (str, optional) - Skip reason

Returns: StepTracker

start_live_display​
start_live_display(self, refresh_per_second: float = 4, transient: bool = True) -> 'StepTracker'

Start live updating display.

Parameters:

  • refresh_per_second (float, optional) - Update frequency - Default: 4
  • transient (bool, optional) - Whether display disappears when stopped - Default: True

Returns: StepTracker

start_step​
start_step(self, key: str, detail: str = '') -> 'StepTracker'

Mark step as in progress with live updates.

Parameters:

  • key (str, required) - Step identifier
  • detail (str, optional) - Optional detail message

Returns: StepTracker

stop_live_display​
stop_live_display(self, show_final: bool = True) -> 'StepTracker'

Stop live display and optionally show final state.

Parameters:

  • show_final (bool, optional) - Whether to print final tree state - Default: True

Returns: StepTracker

update_step​
update_step(self, key: str, detail: str) -> 'StepTracker'

Update step detail message without changing status.

Parameters:

  • key (str, required) - Step identifier
  • detail (str, required) - New detail message

Returns: StepTracker