rich.progress¶
- class rich.progress.BarColumn(bar_width=40, style='bar.back', complete_style='bar.complete', finished_style='bar.finished', pulse_style='bar.pulse', table_column=None)[source]¶
Renders a visual progress bar.
- Parameters
bar_width (Optional[int], optional) – Width of bar or None for full width. Defaults to 40.
style (StyleType, optional) – Style for the bar background. Defaults to “bar.back”.
complete_style (StyleType, optional) – Style for the completed bar. Defaults to “bar.complete”.
finished_style (StyleType, optional) – Style for a finished bar. Defaults to “bar.finished”.
pulse_style (StyleType, optional) – Style for pulsing bars. Defaults to “bar.pulse”.
- class rich.progress.DownloadColumn(binary_units=False, table_column=None)[source]¶
Renders file size downloaded and total, e.g. ‘0.5/2.3 GB’.
- Parameters
- class rich.progress.MofNCompleteColumn(separator='/', table_column=None)[source]¶
Renders completed count/total, e.g. ‘ 10/1000’.
Best for bounded tasks with int quantities.
Space pads the completed count so that progress length does not change as task progresses past powers of 10.
- Parameters
- class rich.progress.Progress(*columns, console=None, auto_refresh=True, refresh_per_second=10, speed_estimate_period=30.0, transient=False, redirect_stdout=True, redirect_stderr=True, get_time=None, disable=False, expand=False)[source]¶
Renders an auto-updating progress bar(s).
- Parameters
console (Console, optional) – Optional Console instance. Default will an internal Console instance writing to stdout.
auto_refresh (bool, optional) – Enable auto refresh. If disabled, you will need to call refresh().
refresh_per_second (Optional[float], optional) – Number of times per second to refresh the progress information or None to use default (10). Defaults to None.
speed_estimate_period (float) – (float, optional): Period (in seconds) used to calculate the speed estimate. Defaults to 30.
transient (bool) – (bool, optional): Clear the progress on exit. Defaults to False.
redirect_stdout (bool) – (bool, optional): Enable redirection of stdout, so
print
may be used. Defaults to True.redirect_stderr (bool) – (bool, optional): Enable redirection of stderr. Defaults to True.
get_time (Optional[Callable[[], float]]) – (Callable, optional): A callable that gets the current time, or None to use Console.get_time. Defaults to None.
disable (bool, optional) – Disable progress display. Defaults to False
expand (bool, optional) – Expand tasks table to fit width. Defaults to False.
columns (Union[str, ProgressColumn]) –
- add_task(description, start=True, total=100.0, completed=0, visible=True, **fields)[source]¶
Add a new ‘task’ to the Progress display.
- Parameters
description (str) – A description of the task.
start (bool, optional) – Start the task immediately (to calculate elapsed time). If set to False, you will need to call start manually. Defaults to True.
total (float, optional) – Number of total steps in the progress if known. Set to None to render a pulsing animation. Defaults to 100.
completed (int, optional) – Number of steps completed so far. Defaults to 0.
visible (bool, optional) – Enable display of the task. Defaults to True.
**fields (str) – Additional data fields required for rendering.
- Returns
An ID you can use when calling update.
- Return type
TaskID
- advance(task_id, advance=1)[source]¶
Advance task by a number of steps.
- Parameters
task_id (TaskID) – ID of task.
advance (float) – Number of steps to advance. Default is 1.
- Return type
None
- classmethod get_default_columns()[source]¶
- Get the default columns used for a new Progress instance:
a text column for the description (TextColumn)
the bar itself (BarColumn)
a text column showing completion percentage (TextColumn)
an estimated-time-remaining column (TimeRemainingColumn)
If the Progress instance is created without passing a columns argument, the default columns defined here will be used.
You can also create a Progress instance using custom columns before and/or after the defaults, as in this example:
- progress = Progress(
SpinnerColumn(), *Progress.default_columns(), “Elapsed:”, TimeElapsedColumn(),
)
This code shows the creation of a Progress display, containing a spinner to the left, the default columns, and a labeled elapsed time column.
- Return type
Tuple[ProgressColumn, …]
- open(file: Union[str, PathLike[str], bytes], mode: typing_extensions.Literal[rb], buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, *, total: Optional[int] = None, task_id: Optional[TaskID] = None, description: str = 'Reading...') BinaryIO [source]¶
- open(file: Union[str, PathLike[str], bytes], mode: Union[typing_extensions.Literal[r], typing_extensions.Literal[rt]], buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, *, total: Optional[int] = None, task_id: Optional[TaskID] = None, description: str = 'Reading...') TextIO
Track progress while reading from a binary file.
- Parameters
path (Union[str, PathLike[str]]) – The path to the file to read.
mode (str) – The mode to use to open the file. Only supports “r”, “rb” or “rt”.
buffering (int) – The buffering strategy to use, see
io.open()
.encoding (str, optional) – The encoding to use when reading in text mode, see
io.open()
.errors (str, optional) – The error handling strategy for decoding errors, see
io.open()
.newline (str, optional) – The strategy for handling newlines in text mode, see
io.open()
.total (int, optional) – Total number of bytes to read. If none given, os.stat(path).st_size is used.
task_id (TaskID) – Task to track. Default is new task.
description (str, optional) – Description of task, if new task is created.
- Returns
A readable file-like object in binary mode.
- Return type
BinaryIO
- Raises
ValueError – When an invalid mode is given.
- remove_task(task_id)[source]¶
Delete a task if it exists.
- Parameters
task_id (TaskID) – A task ID.
- Return type
None
- reset(task_id, *, start=True, total=None, completed=0, visible=None, description=None, **fields)[source]¶
Reset a task so completed is 0 and the clock is reset.
- Parameters
task_id (TaskID) – ID of task.
start (bool, optional) – Start the task after reset. Defaults to True.
total (float, optional) – New total steps in task, or None to use current total. Defaults to None.
completed (int, optional) – Number of steps completed. Defaults to 0.
visible (bool, optional) – Enable display of the task. Defaults to True.
description (str, optional) – Change task description if not None. Defaults to None.
**fields (str) – Additional data fields required for rendering.
- Return type
None
- start_task(task_id)[source]¶
Start a task.
Starts a task (used when calculating elapsed time). You may need to call this manually, if you called
add_task
withstart=False
.- Parameters
task_id (TaskID) – ID of task.
- Return type
None
- stop_task(task_id)[source]¶
Stop a task.
This will freeze the elapsed time on the task.
- Parameters
task_id (TaskID) – ID of task.
- Return type
None
- track(sequence, total=None, task_id=None, description='Working...', update_period=0.1)[source]¶
Track progress by iterating over a sequence.
- Parameters
sequence (Sequence[ProgressType]) – A sequence of values you want to iterate over and track progress.
total (Optional[float]) – (float, optional): Total number of steps. Default is len(sequence).
task_id (Optional[TaskID]) – (TaskID): Task to track. Default is new task.
description (str) – (str, optional): Description of task, if new task is created.
update_period (float, optional) – Minimum time (in seconds) between calls to update(). Defaults to 0.1.
- Returns
An iterable of values taken from the provided sequence.
- Return type
Iterable[ProgressType]
- update(task_id, *, total=None, completed=None, advance=None, description=None, visible=None, refresh=False, **fields)[source]¶
Update information associated with a task.
- Parameters
task_id (TaskID) – Task id (returned by add_task).
total (float, optional) – Updates task.total if not None.
completed (float, optional) – Updates task.completed if not None.
advance (float, optional) – Add a value to task.completed if not None.
description (str, optional) – Change task description if not None.
visible (bool, optional) – Set visible flag if not None.
refresh (bool) – Force a refresh of progress information. Default is False.
**fields (Any) – Additional data fields required for rendering.
- Return type
None
- wrap_file(file, total=None, *, task_id=None, description='Reading...')[source]¶
Track progress file reading from a binary file.
- Parameters
file (BinaryIO) – A file-like object opened in binary mode.
total (int, optional) – Total number of bytes to read. This must be provided unless a task with a total is also given.
task_id (TaskID) – Task to track. Default is new task.
description (str, optional) – Description of task, if new task is created.
- Returns
A readable file-like object in binary mode.
- Return type
BinaryIO
- Raises
ValueError – When no total value can be extracted from the arguments or the task.
- class rich.progress.ProgressColumn(table_column=None)[source]¶
Base class for a widget to use in progress display.
- class rich.progress.ProgressSample(timestamp, completed)[source]¶
Sample of progress for a given time.
- property completed¶
Number of steps completed.
- property timestamp¶
Timestamp of sample.
- class rich.progress.RenderableColumn(renderable='', *, table_column=None)[source]¶
A column to insert an arbitrary column.
- Parameters
- class rich.progress.SpinnerColumn(spinner_name='dots', style='progress.spinner', speed=1.0, finished_text=' ', table_column=None)[source]¶
A column with a ‘spinner’ animation.
- Parameters
spinner_name (str, optional) – Name of spinner animation. Defaults to “dots”.
style (StyleType, optional) – Style of spinner. Defaults to “progress.spinner”.
speed (float, optional) – Speed factor of spinner. Defaults to 1.0.
finished_text (TextType, optional) – Text used when task is finished. Defaults to ” “.
- class rich.progress.Task(id, description, total, completed, _get_time, finished_time=None, visible=True, fields=<factory>, finished_speed=None, _lock=<factory>)[source]¶
Information regarding a progress task.
This object should be considered read-only outside of the
Progress
class.- Parameters
- property elapsed: Optional[float]¶
Time elapsed since task was started, or
None
if the task hasn’t started.- Type
Optional[float]
- id: TaskID¶
Task ID associated with this task (used in Progress methods).
- property percentage: float¶
Get progress of task as a percentage. If a None total was set, returns 0
- Type
- property remaining: Optional[float]¶
Get the number of steps remaining, if a non-None total was set.
- Type
Optional[float]
- start_time: Optional[float] = None¶
Time this task was started, or None if not started.
- Type
Optional[float]
- stop_time: Optional[float] = None¶
Time this task was stopped, or None if not stopped.
- Type
Optional[float]
- class rich.progress.TaskProgressColumn(text_format='[progress.percentage]{task.percentage:>3.0f}%', text_format_no_percentage='', style='none', justify='left', markup=True, highlighter=None, table_column=None, show_speed=False)[source]¶
Show task progress as a percentage.
- Parameters
text_format (str, optional) – Format for percentage display. Defaults to “[progress.percentage]{task.percentage:>3.0f}%”.
text_format_no_percentage (str, optional) – Format if percentage is unknown. Defaults to “”.
style (StyleType, optional) – Style of output. Defaults to “none”.
justify (JustifyMethod, optional) – Text justification. Defaults to “left”.
markup (bool, optional) – Enable markup. Defaults to True.
highlighter (Optional[Highlighter], optional) – Highlighter to apply to output. Defaults to None.
table_column (Optional[Column], optional) – Table Column to use. Defaults to None.
show_speed (bool, optional) – Show speed if total is unknown. Defaults to False.
- class rich.progress.TextColumn(text_format, style='none', justify='left', markup=True, highlighter=None, table_column=None)[source]¶
A column containing text.
- Parameters
- class rich.progress.TimeRemainingColumn(compact=False, elapsed_when_finished=False, table_column=None)[source]¶
Renders estimated time remaining.
- Parameters
- class rich.progress.TransferSpeedColumn(table_column=None)[source]¶
Renders human readable transfer speed.
- rich.progress.open(file: Union[str, PathLike[str], bytes], mode: Union[typing_extensions.Literal[rt], typing_extensions.Literal[r]], buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, *, total: Optional[int] = None, description: str = 'Reading...', auto_refresh: bool = True, console: Optional[Console] = None, transient: bool = False, get_time: Optional[Callable[[], float]] = None, refresh_per_second: float = 10, style: Union[str, Style] = 'bar.back', complete_style: Union[str, Style] = 'bar.complete', finished_style: Union[str, Style] = 'bar.finished', pulse_style: Union[str, Style] = 'bar.pulse', disable: bool = False) AbstractContextManager[TextIO] [source]¶
- rich.progress.open(file: Union[str, PathLike[str], bytes], mode: typing_extensions.Literal[rb], buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, *, total: Optional[int] = None, description: str = 'Reading...', auto_refresh: bool = True, console: Optional[Console] = None, transient: bool = False, get_time: Optional[Callable[[], float]] = None, refresh_per_second: float = 10, style: Union[str, Style] = 'bar.back', complete_style: Union[str, Style] = 'bar.complete', finished_style: Union[str, Style] = 'bar.finished', pulse_style: Union[str, Style] = 'bar.pulse', disable: bool = False) AbstractContextManager[BinaryIO]
Read bytes from a file while tracking progress.
- Parameters
path (Union[str, PathLike[str], BinaryIO]) – The path to the file to read, or a file-like object in binary mode.
mode (str) – The mode to use to open the file. Only supports “r”, “rb” or “rt”.
buffering (int) – The buffering strategy to use, see
io.open()
.encoding (str, optional) – The encoding to use when reading in text mode, see
io.open()
.errors (str, optional) – The error handling strategy for decoding errors, see
io.open()
.newline (str, optional) – The strategy for handling newlines in text mode, see
io.open()
total – (int, optional): Total number of bytes to read. Must be provided if reading from a file handle. Default for a path is os.stat(file).st_size.
description (str, optional) – Description of task show next to progress bar. Defaults to “Reading”.
auto_refresh (bool, optional) – Automatic refresh, disable to force a refresh after each iteration. Default is True.
transient – (bool, optional): Clear the progress on exit. Defaults to False.
console (Console, optional) – Console to write to. Default creates internal Console instance.
refresh_per_second (float) – Number of times per second to refresh the progress information. Defaults to 10.
style (StyleType, optional) – Style for the bar background. Defaults to “bar.back”.
complete_style (StyleType, optional) – Style for the completed bar. Defaults to “bar.complete”.
finished_style (StyleType, optional) – Style for a finished bar. Defaults to “bar.finished”.
pulse_style (StyleType, optional) – Style for pulsing bars. Defaults to “bar.pulse”.
disable (bool, optional) – Disable display of progress.
encoding – The encoding to use when reading in text mode.
- Returns
A context manager yielding a progress reader.
- Return type
ContextManager[BinaryIO]
- rich.progress.track(sequence, description='Working...', total=None, auto_refresh=True, console=None, transient=False, get_time=None, refresh_per_second=10, style='bar.back', complete_style='bar.complete', finished_style='bar.finished', pulse_style='bar.pulse', update_period=0.1, disable=False, show_speed=True)[source]¶
Track progress by iterating over a sequence.
- Parameters
sequence (Iterable[ProgressType]) – A sequence (must support “len”) you wish to iterate over.
description (str, optional) – Description of task show next to progress bar. Defaults to “Working”.
total (Optional[float]) – (float, optional): Total number of steps. Default is len(sequence).
auto_refresh (bool, optional) – Automatic refresh, disable to force a refresh after each iteration. Default is True.
transient (bool) – (bool, optional): Clear the progress on exit. Defaults to False.
console (Console, optional) – Console to write to. Default creates internal Console instance.
refresh_per_second (float) – Number of times per second to refresh the progress information. Defaults to 10.
style (StyleType, optional) – Style for the bar background. Defaults to “bar.back”.
complete_style (StyleType, optional) – Style for the completed bar. Defaults to “bar.complete”.
finished_style (StyleType, optional) – Style for a finished bar. Defaults to “bar.finished”.
pulse_style (StyleType, optional) – Style for pulsing bars. Defaults to “bar.pulse”.
update_period (float, optional) – Minimum time (in seconds) between calls to update(). Defaults to 0.1.
disable (bool, optional) – Disable display of progress.
show_speed (bool, optional) – Show speed if total isn’t known. Defaults to True.
- Returns
An iterable of the values in the sequence.
- Return type
Iterable[ProgressType]
- rich.progress.wrap_file(file, total, *, description='Reading...', auto_refresh=True, console=None, transient=False, get_time=None, refresh_per_second=10, style='bar.back', complete_style='bar.complete', finished_style='bar.finished', pulse_style='bar.pulse', disable=False)[source]¶
Read bytes from a file while tracking progress.
- Parameters
file (Union[str, PathLike[str], BinaryIO]) – The path to the file to read, or a file-like object in binary mode.
total (int) – Total number of bytes to read.
description (str, optional) – Description of task show next to progress bar. Defaults to “Reading”.
auto_refresh (bool, optional) – Automatic refresh, disable to force a refresh after each iteration. Default is True.
transient (bool) – (bool, optional): Clear the progress on exit. Defaults to False.
console (Console, optional) – Console to write to. Default creates internal Console instance.
refresh_per_second (float) – Number of times per second to refresh the progress information. Defaults to 10.
style (StyleType, optional) – Style for the bar background. Defaults to “bar.back”.
complete_style (StyleType, optional) – Style for the completed bar. Defaults to “bar.complete”.
finished_style (StyleType, optional) – Style for a finished bar. Defaults to “bar.finished”.
pulse_style (StyleType, optional) – Style for pulsing bars. Defaults to “bar.pulse”.
disable (bool, optional) – Disable display of progress.
- Returns
A context manager yielding a progress reader.
- Return type
ContextManager[BinaryIO]