import io import sys import typing import warnings from abc import ABC, abstractmethod from collections import deque from dataclasses import dataclass, field from datetime import timedelta from io import RawIOBase, UnsupportedOperation from math import ceil from mmap import mmap from operator import length_hint from os import PathLike, stat from threading import Event, RLock, Thread from types import TracebackType from typing import (
Any,
BinaryIO,
Callable,
ContextManager,
Deque,
Dict,
Generic,
Iterable,
List,
NamedTuple,
NewType,
Optional,
Sequence,
TextIO,
Tuple,
Type,
TypeVar,
Union,
)
if sys.version_info >= (3, 8): from typing import Literal else: from typing_extensions import Literal # pragma: no cover
if sys.version_info >= (3, 11): from typing import Self else: from typing_extensions import Self # pragma: no cover
from . import filesize, get_console from .console import Console, Group, JustifyMethod, RenderableType from .highlighter import Highlighter from .jupyter import JupyterMixin from .live import Live from .progress_bar import ProgressBar from .spinner import Spinner from .style import StyleType from .table import Column, Table from .text import Text, TextType
TaskID = NewType("TaskID", int)
ProgressType = TypeVar("ProgressType")
GetTimeCallable = Callable[[], float]
_I = typing.TypeVar("_I", TextIO, BinaryIO)
class _TrackThread(Thread): """A thread to periodically update progress."""
Args:
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: (float, optional): Total number of steps. Default is len(sequence).
completed (int, optional): Number of steps completed so far. Defaults to 0.
auto_refresh (bool, optional): Automatic refresh, disable to force a refresh after each iteration. Default isTrue.
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".
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:
Iterable[ProgressType]: An iterable of the values in the sequence.
Args:
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 isTrue.
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.
Returns:
ContextManager[BinaryIO]: A context manager yielding a progress reader.
Args:
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 :func:`io.open`.
encoding (str, optional): The encoding to use when reading in text mode, see :func:`io.open`.
errors (str, optional): The error handling strategy for decoding errors, see :func:`io.open`.
newline (str, optional): The strategy for handling newlines in text mode, see :func:`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 isTrue.
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 (str, optional): The encoding to use when reading in text mode.
Returns:
ContextManager[BinaryIO]: A context manager yielding a progress reader.
class SpinnerColumn(ProgressColumn): """A column with a 'spinner' animation.
Args:
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 " ". """
def render(self, task: "Task") -> Text:
_text = self.text_format.format(task=task) if self.markup:
text = Text.from_markup(_text, style=self.style, justify=self.justify) else:
text = Text(_text, style=self.style, justify=self.justify) if self.highlighter:
self.highlighter.highlight(text) return text
class BarColumn(ProgressColumn): """Renders a visual progress bar.
Args:
bar_width (Optional[int], optional): Width of bar orNonefor 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". """
def render(self, task: "Task") -> ProgressBar: """Gets a progress bar widget for a task.""" return ProgressBar(
total=max(0, task.total) if task.total isnotNoneelseNone,
completed=max(0, task.completed),
width=Noneif self.bar_width isNoneelse max(1, self.bar_width),
pulse=not task.started,
animation_time=task.get_time(),
style=self.style,
complete_style=self.complete_style,
finished_style=self.finished_style,
pulse_style=self.pulse_style,
)
class TimeElapsedColumn(ProgressColumn): """Renders time elapsed."""
def render(self, task: "Task") -> Text: """Show time elapsed."""
elapsed = task.finished_time if task.finished else task.elapsed if elapsed isNone: return Text("-:--:--", style="progress.elapsed")
delta = timedelta(seconds=max(0, int(elapsed))) return Text(str(delta), style="progress.elapsed")
class TaskProgressColumn(TextColumn): """Show task progress as a percentage.
Args:
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. """
@classmethod def render_speed(cls, speed: Optional[float]) -> Text: """Render the speed in iterations per second.
Args:
task (Task): A Task object.
Returns:
Text: Text object containing the task speed. """ if speed isNone: return Text("", style="progress.percentage")
unit, suffix = filesize.pick_unit_and_suffix(
int(speed),
["", "×10³", "×10⁶", "×10⁹", "×10¹²"],
1000,
)
data_speed = speed / unit return Text(f"{data_speed:.1f}{suffix} it/s", style="progress.percentage")
def render(self, task: "Task") -> Text: if task.total isNoneand self.show_speed: return self.render_speed(task.finished_speed or task.speed)
text_format = (
self.text_format_no_percentage if task.total isNoneelse self.text_format
)
_text = text_format.format(task=task) if self.markup:
text = Text.from_markup(_text, style=self.style, justify=self.justify) else:
text = Text(_text, style=self.style, justify=self.justify) if self.highlighter:
self.highlighter.highlight(text) return text
class TimeRemainingColumn(ProgressColumn): """Renders estimated time remaining.
Args:
compact (bool, optional): Render MM:SS when time remaining is less than an hour. Defaults to False.
elapsed_when_finished (bool, optional): Render time elapsed when the task is finished. Defaults to False. """
# Only refresh twice a second to prevent jitter
max_refresh = 0.5
def get_time(self) -> float: """float: Get the current time, in seconds.""" return self._get_time()
@property def started(self) -> bool: """bool: Check if the task as started.""" return self.start_time isnotNone
@property def remaining(self) -> Optional[float]: """Optional[float]: Get the number of steps remaining, if a non-None total was set.""" if self.total isNone: returnNone return self.total - self.completed
@property def elapsed(self) -> Optional[float]: """Optional[float]: Time elapsed since task was started, or ``None`` if the task hasn't started.""" if self.start_time isNone: returnNone if self.stop_time isnotNone: return self.stop_time - self.start_time return self.get_time() - self.start_time
@property def finished(self) -> bool: """Check if the task has finished.""" return self.finished_time isnotNone
@property def percentage(self) -> float: """float: Get progress of task as a percentage. If a None total was set, returns 0""" ifnot self.total: return 0.0
completed = (self.completed / self.total) * 100.0
completed = min(100.0, max(0.0, completed)) return completed
@property def speed(self) -> Optional[float]: """Optional[float]: Get the estimated speed in steps per second.""" if self.start_time isNone: returnNone with self._lock:
progress = self._progress ifnot progress: returnNone
total_time = progress[-1].timestamp - progress[0].timestamp if total_time == 0: returnNone
iter_progress = iter(progress)
next(iter_progress)
total_completed = sum(sample.completed for sample in iter_progress)
speed = total_completed / total_time return speed
@property def time_remaining(self) -> Optional[float]: """Optional[float]: Get estimated time to completion, or ``None`` if no data.""" if self.finished: return 0.0
speed = self.speed ifnot speed: returnNone
remaining = self.remaining if remaining isNone: returnNone
estimate = ceil(remaining / speed) return estimate
class Progress(JupyterMixin): """Renders an auto-updating progress bar(s).
Args:
console (Console, optional): Optional Console instance. Defaults to 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 orNone to use default (10). Defaults to None.
speed_estimate_period: (float, optional): Period (in seconds) used to calculate the speed estimate. Defaults to 30.
transient: (bool, optional): Clear the progress on exit. Defaults to False.
redirect_stdout: (bool, optional): Enable redirection of stdout, so ``print`` may be used. Defaults to True.
redirect_stderr: (bool, optional): Enable redirection of stderr. Defaults to True.
get_time: (Callable, optional): A callable that gets the current time, orNone 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. """
@classmethod def get_default_columns(cls) -> Tuple[ProgressColumn, ...]: """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, asin this example:
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 (
TextColumn("[progress.description]{task.description}"),
BarColumn(),
TaskProgressColumn(),
TimeRemainingColumn(),
)
@property def tasks(self) -> List[Task]: """Get a list of Task instances.""" with self._lock: return list(self._tasks.values())
@property def task_ids(self) -> List[TaskID]: """A list of task IDs.""" with self._lock: return list(self._tasks.keys())
@property def finished(self) -> bool: """Check if all tasks have been completed.""" with self._lock: ifnot self._tasks: returnTrue return all(task.finished for task in self._tasks.values())
def track(
self,
sequence: Union[Iterable[ProgressType], Sequence[ProgressType]],
total: Optional[float] = None,
completed: int = 0,
task_id: Optional[TaskID] = None,
description: str = "Working...",
update_period: float = 0.1,
) -> Iterable[ProgressType]: """Track progress by iterating over a sequence.
Args:
sequence (Sequence[ProgressType]): A sequence of values you want to iterate over and track progress.
total: (float, optional): Total number of steps. Default is len(sequence).
completed (int, optional): Number of steps completed so far. Defaults to 0.
task_id: (TaskID): Task to track. Default is new task.
description: (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:
Iterable[ProgressType]: An iterable of values taken from the provided sequence. """ if total isNone:
total = float(length_hint(sequence)) orNone
if self.live.auto_refresh: with _TrackThread(self, task_id, update_period) as track_thread: for value in sequence: yield value
track_thread.completed += 1 else:
advance = self.advance
refresh = self.refresh for value in sequence: yield value
advance(task_id, 1)
refresh()
Args:
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:
BinaryIO: A readable file-like object in binary mode.
Raises:
ValueError: When no total value can be extracted from the arguments or the task. """ # attempt to recover the total from the task
total_bytes: Optional[float] = None if total isnotNone:
total_bytes = total elif task_id isnotNone: with self._lock:
total_bytes = self._tasks[task_id].total if total_bytes isNone: raise ValueError(
f"unable to get the total number of bytes, please specify 'total'"
)
# update total of task or create new task if task_id isNone:
task_id = self.add_task(description, total=total_bytes) else:
self.update(task_id, total=total_bytes)
Args:
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 :func:`io.open`.
encoding (str, optional): The encoding to use when reading in text mode, see :func:`io.open`.
errors (str, optional): The error handling strategy for decoding errors, see :func:`io.open`.
newline (str, optional): The strategy for handling newlines in text mode, see :func:`io.open`.
total (int, optional): Total number of bytes to read. Ifnone given, os.stat(path).st_size isused.
task_id (TaskID): Task to track. Default is new task.
description (str, optional): Description of task, if new task is created.
Returns:
BinaryIO: A readable file-like object in binary mode.
Raises:
ValueError: When an invalid mode is given. """ # normalize the mode (always rb, rt)
_mode = "".join(sorted(mode, reverse=False)) if _mode notin ("br", "rt", "r"): raise ValueError(f"invalid mode {mode!r}")
# patch buffering to provide the same behaviour as the builtin `open`
line_buffering = buffering == 1 if _mode == "br"and buffering == 1:
warnings.warn( "line buffering (buffering=1) isn't supported in binary mode, the default buffer size will be used",
RuntimeWarning,
)
buffering = -1 elif _mode in ("rt", "r"): if buffering == 0: raise ValueError("can't have unbuffered text I/O") elif buffering == 1:
buffering = -1
# attempt to get the total with `os.stat` if total isNone:
total = stat(file).st_size
# update total of task or create new task if task_id isNone:
task_id = self.add_task(description, total=total) else:
self.update(task_id, total=total)
# open the file in binary mode,
handle = io.open(file, "rb", buffering=buffering)
reader = _Reader(handle, self, task_id, close_handle=True)
# wrap the reader in a `TextIOWrapper` if text mode if mode in ("r", "rt"): return io.TextIOWrapper(
reader,
encoding=encoding,
errors=errors,
newline=newline,
line_buffering=line_buffering,
)
return reader
def start_task(self, task_id: TaskID) -> None: """Start a task.
Starts a task (used when calculating elapsed time). You may need to call this manually, if you called ``add_task`` with ``start=False``.
Args:
task_id (TaskID): ID of task. """ with self._lock:
task = self._tasks[task_id] if task.start_time isNone:
task.start_time = self.get_time()
def stop_task(self, task_id: TaskID) -> None: """Stop a task.
This will freeze the elapsed time on the task.
Args:
task_id (TaskID): ID of task. """ with self._lock:
task = self._tasks[task_id]
current_time = self.get_time() if task.start_time isNone:
task.start_time = current_time
task.stop_time = current_time
Args:
task_id (TaskID): Task id (returned by add_task).
total (float, optional): Updates task.total ifnotNone.
completed (float, optional): Updates task.completed ifnotNone.
advance (float, optional): Add a value to task.completed ifnotNone.
description (str, optional): Change task description ifnotNone.
visible (bool, optional): Set visible flag ifnotNone.
refresh (bool): Force a refresh of progress information. Default isFalse.
**fields (Any): Additional data fields required for rendering. """ with self._lock:
task = self._tasks[task_id]
completed_start = task.completed
if total isnotNoneand total != task.total:
task.total = total
task._reset() if advance isnotNone:
task.completed += advance if completed isnotNone:
task.completed = completed if description isnotNone:
task.description = description if visible isnotNone:
task.visible = visible
task.fields.update(fields)
update_completed = task.completed - completed_start
popleft = _progress.popleft while _progress and _progress[0].timestamp < old_sample_time:
popleft() if update_completed > 0:
_progress.append(ProgressSample(current_time, update_completed)) if (
task.total isnotNone and task.completed >= task.total and task.finished_time isNone
):
task.finished_time = task.elapsed
if refresh:
self.refresh()
def reset(
self,
task_id: TaskID,
*,
start: bool = True,
total: Optional[float] = None,
completed: int = 0,
visible: Optional[bool] = None,
description: Optional[str] = None,
**fields: Any,
) -> None: """Reset a task so completed is 0 and the clock is reset.
Args:
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, orNone 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 ifnotNone. Defaults to None.
**fields (str): Additional data fields required for rendering. """
current_time = self.get_time() with self._lock:
task = self._tasks[task_id]
task._reset()
task.start_time = current_time if start elseNone if total isnotNone:
task.total = total
task.completed = completed if visible isnotNone:
task.visible = visible if fields:
task.fields = fields if description isnotNone:
task.description = description
task.finished_time = None
self.refresh()
def advance(self, task_id: TaskID, advance: float = 1) -> None: """Advance task by a number of steps.
Args:
task_id (TaskID): ID of task.
advance (float): Number of steps to advance. Default is 1. """
current_time = self.get_time() with self._lock:
task = self._tasks[task_id]
completed_start = task.completed
task.completed += advance
update_completed = task.completed - completed_start
old_sample_time = current_time - self.speed_estimate_period
_progress = task._progress
popleft = _progress.popleft while _progress and _progress[0].timestamp < old_sample_time:
popleft() while len(_progress) > 1000:
popleft()
_progress.append(ProgressSample(current_time, update_completed)) if (
task.total isnotNone and task.completed >= task.total and task.finished_time isNone
):
task.finished_time = task.elapsed
task.finished_speed = task.speed
def refresh(self) -> None: """Refresh (render) the progress information.""" ifnot self.disable and self.live.is_started:
self.live.refresh()
def get_renderable(self) -> RenderableType: """Get a renderable for the progress display."""
renderable = Group(*self.get_renderables()) return renderable
def get_renderables(self) -> Iterable[RenderableType]: """Get a number of renderables for the progress display."""
table = self.make_tasks_table(self.tasks) yield table
def make_tasks_table(self, tasks: Iterable[Task]) -> Table: """Get a table to render the Progress display.
Args:
tasks (Iterable[Task]): An iterable of Task instances, one per row of the table.
Returns:
Table: A table instance. """
table_columns = (
(
Column(no_wrap=True) if isinstance(_column, str) else _column.get_table_column().copy()
) for _column in self.columns
)
table = Table.grid(*table_columns, padding=(0, 1), expand=self.expand)
for task in tasks: if task.visible:
table.add_row(
*(
(
column.format(task=task) if isinstance(column, str) else column(task)
) for column in self.columns
)
) return table
def __rich__(self) -> RenderableType: """Makes the Progress class itself renderable.""" with self._lock: return self.get_renderable()
def add_task(
self,
description: str,
start: bool = True,
total: Optional[float] = 100.0,
completed: int = 0,
visible: bool = True,
**fields: Any,
) -> TaskID: """Add a new 'task' to the Progress display.
Args:
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:
TaskID: An ID you can use when calling `update`. """ with self._lock:
task = Task(
self._task_index,
description,
total,
completed,
visible=visible,
fields=fields,
_get_time=self.get_time,
_lock=self._lock,
)
self._tasks[self._task_index] = task if start:
self.start_task(self._task_index)
new_task_index = self._task_index
self._task_index = TaskID(int(self._task_index) + 1)
self.refresh() return new_task_index
def remove_task(self, task_id: TaskID) -> None: """Delete a task if it exists.
Args:
task_id (TaskID): A task ID.
""" with self._lock: del self._tasks[task_id]
if __name__ == "__main__": # pragma: no coverage import random import time
from .panel import Panel from .rule import Rule from .syntax import Syntax from .table import Table
syntax = Syntax( '''def loop_last(values: Iterable[T]) -> Iterable[Tuple[bool, T]]: """Iterate and generate a tuple with a flag for last value."""
iter_values = iter(values) try:
previous_value = next(iter_values) except StopIteration: return for value in iter_values: yieldFalse, previous_value
previous_value = value yieldTrue, previous_value''', "python",
line_numbers=True,
)
progress_renderables = [ "Text may be printed while the progress bars are rendering.",
Panel("In fact, [i]any[/i] renderable will work"), "Such as [magenta]tables[/]...",
table, "Pretty printed structures...",
{"type": "example", "text": "Pretty printed"}, "Syntax...",
syntax,
Rule("Give it a try!"),
]
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung und die Messung sind noch experimentell.