`undr.display`#

Terminal progress bar.

Overview#

Classes#

`Display`	Display collects update messages and shows progress in a terminal.
`DisplayProgress`	Represents download or process progress.
`Speedometer`	Measures speed with multiple samples and a sliding window.
`Status`	Keeps track of download and process progress for a dataset.
`Tag`	Label and icon representing an action in a terminal.

Functions#

`format_bold`	Surrounds the message with ANSI escape characters for bold formatting.
`format_dim`	Surrounds the message with ANSI escape characters for dim formatting.
`format_error`	Adds a red cross mark in front of the message.
`format_info`	Adds a kangaroo icon in front of the message.
`progress_bar`	Generates a progress bar compatible with terminals.
`speeds`	Calculates the total speed for multiple datasets.

Attributes#

ANSI_COLORS_ENABLED

Module Contents#

undr.display.ANSI_COLORS_ENABLED#

class undr.display.Display(statuses: list[Status], output_interval: float, download_speed_samples: int, process_speed_samples: int, download_tag: Tag, process_tag: Tag)#

Display collects update messages and shows progress in a terminal.

Parameters:

statuses (list[Status]) – Initial statuses for all datasets.
output_interval (float) – Time between refreshes in seconds.
download_speed_samples (int) – Size of the sliding window for download speed calculations.
process_speed_samples (int) – Size of the sliding window for process speed calculations.
download_tag (Tag) – Label and icon for the download action.
process_tag (Tag) – Label and icon for the process action.

__enter__() → Display#

Enables the use of the “with” statement.

Returns:: A display context that calls close() on exit.
Return type:: Display

__exit__(type: Type[BaseException] | None, value: BaseException | None, traceback: types.TracebackType | None)#

Enables the use of the “with” statement.

Parameters:

type (Optional[Type[BaseException]]) – None if the context exits without an exception, and the raised exception’s class otherwise.
value (Optional[BaseException]) – None if the context exits without an exception, and the raised exception otherwise.
traceback (Optional[types.TracebackType]) – None if the context exits without an exception, and the raised exception’s traceback otherwise.

close()#

Terminates the worker thread.

This function is called automatically if display is used as a context manager.

messages(statuses: list[Status]) → list[Status]#

Consumes messages until the queue is empty.

This function consumes messages until the queue is empty, not closed. More messages are likely to be queued after this function returns.

Parameters:: statuses (list[Status]) – Current statuses, will be modified in-place. Use copy.deepcopy() to preserve the original list.
Raises:: RuntimeError – if a message in the queue is not undr.decode.Progress, undr.remote.Progress, undr.json_index_tasks.IndexLoaded or undr.json_index_tasks.DirectoryScanned.
Returns:: Updated statuses.
Return type:: list[Status]

output(statuses: list[Status], average: bool, download_speed: float, process_speed: float)#

Called by the worker to generate the terminal text.

Parameters:

statuses (list[Status]) – Current datasets statuses.
average (bool) – Whether the provided speeds are averages, typically used after all the actions are complete.
download_speed (float) – Current or average download speed in bytes per second.
process_speed (float) – Current or average process speed in bytes per second.

push(message: Any)#

Processes update messages.

Ignores messages that are not undr.decode.Progress, undr.remote.Progress, undr.json_index_tasks.IndexLoaded or undr.json_index_tasks.DirectoryScanned.

Parameters:: message (Any) – Message from a worker.

target()#: Worker thread implementation.

time_left(statuses: list[Status], download_speed: float, process_speed: float) → float | None#

Estimates the time left to complete the download and process actions.

Parameters:

statuses (list[Status]) – Current datasets statuses.
download_speed (float) – Current speed in bytes per second.
process_speed (float) – Current speed in bytes per second.

Returns:

Estimated time left in second or None if at least one dataset is still being indexed or if the download and process speeds are zero.

Return type:

Optional[float]

class undr.display.DisplayProgress#

Represents download or process progress.

current_bytes: int#: Number of bytes currently downloaded or processed.

final_bytes: int#: Total number of bytes to download or process.

initial_bytes: int#: Number of bytes already downloaded or processed when the action started.

class undr.display.Speedometer(maximum_samples: int)#

Measures speed with multiple samples and a sliding window.

Parameters:: maximum_samples (int) – Number of samples. Fewer samples are used for the first few speed estimations, until that number is reached.

__repr__() → str#: Return repr(self).

add_sample(sample: float)#

Passes a new sample to the speedometer.

Parameters:: sample (float) – Speed sample in bytes per second.

value() → float#

Current speed value in bytes per second.

Returns:: Mean value of the samples.
Return type:: float

class undr.display.Status#

Keeps track of download and process progress for a dataset.

current_index_files: int#: Number of index files downloaded so far.

download: DisplayProgress#

Represents download progress.

Ignored if the mode is undr.install_mode.Mode.REMOTE.

final_index_files: int#

Total number of index files.

This number may increase as more index files are discovered while indexing.

indexing: bool#: Whether the dataset has been indexed.

mode: undr.install_mode.Mode#: Dataset installation mode.

path_id: pathlib.PurePosixPath#: Path ID of the dataset’s base directory.

process: DisplayProgress#

Represents process progress

Ignored if the mode is undr.install_mode.Mode.REMOTE or undr.install_mode.Mode.LOCAL.

complete() → bool#

Checks whether actions are complete for this dataset.

Returns:: Whether all actions are complete.
Return type:: bool

classmethod from_path_id_and_mode(path_id: pathlib.PurePosixPath, dataset_mode: undr.install_mode.Mode)#

Initializes a status from a path ID and a mode.

Parameters:

path_id (pathlib.PurePosixPath) – The dataset’s base directory.
dataset_mode (install_mode.Mode) – The installation mode.

Returns:

Default initial status.

Return type:

Status

is_parent_of(path_id: pathlib.PurePosixPath) → bool#

Checks whether the dataset represented by this status is a parent of the given resource.

This can be used to assign messages from a given resource to the right dataset.

Parameters:: path_id (pathlib.PurePosixPath) – The path ID of the resource that may be a child of this dataset.
Returns:: Whether this dataset is a parent of the resource.
Return type:: bool

label() → str#: Returns the dataset’s name.

progress_and_representation(download_tag: Tag, process_tag: Tag) → tuple[tuple[float, float] | None, str]#

Returns download and process progress in bytes and a string representation of these values.

Parameters:

download_tag (Tag) – Icon and label for the download action.
process_tag (Tag) – Icon and label for the process action.

Returns:

The first entry is None if the dataset is being indexed. Otherwise, the first entry is the progress in bytes. The second entry is the string representation of progress, which is always not None.

Return type:

tuple[tuple[float, float], str]

speeds(previous_status: Status, interval: float) → tuple[float, float]#

Calculates download and process speeds.

Parameters:

previous_status (Status) – Past status used to calculate progress variation.
interval (float) – Time since the previous status in seconds.

Returns:

download speed and process speed in bytes per second.

Return type:

tuple[float, float]

class undr.display.Tag#

Label and icon representing an action in a terminal.

icon: str#: The action’s icon, typically a single non-ASCII UTF-8 character.

label: str#: The action label.

undr.display.format_bold(message: str) → str#

Surrounds the message with ANSI escape characters for bold formatting.

Parameters:: message (str) – A message to be displayed in a terminal.
Returns:: The message surrounded with ANSI escape characters, or the original message if the environment variable ANSI_COLORS_DISABLED is set.
Return type:: str

undr.display.format_dim(message: str) → str#

Surrounds the message with ANSI escape characters for dim formatting.

Parameters:: message (str) – A message to be displayed in a terminal.
Returns:: The message surrounded with ANSI escape characters, or the original message if the environment variable ANSI_COLORS_DISABLED is set.
Return type:: str

undr.display.format_error(message: str) → str#

Adds a red cross mark in front of the message.

Parameters:: message (str) – A message to be displayed in a terminal.
Returns:: The message with a prefix.
Return type:: str

undr.display.format_info(message: str) → str#

Adds a kangaroo icon in front of the message.

Parameters:: message (str) – A message to be displayed in a terminal.
Returns:: The message with a prefix.
Return type:: str

undr.display.progress_bar(width: int, progress: tuple[float, float] | None) → str#

Generates a progress bar compatible with terminals.

Parameters:

width (int) – The progress bar width in characters.
progress (Optional[tuple[float, float]]) – None yields an indeterminate progress bar, a tuple returns a two-levels progress bar (bottom and top). The tuple values must be in the range [0, 1]. Use the same value twice to generate a simple (one-level) progress bar.

Returns:

The progress bar as a string, without line breaks.

Return type:

str

undr.display.speeds(previous_statuses: list[Status], statuses: list[Status], interval: float) → tuple[float, float]#

Calculates the total speed for multiple datasets.

Parameters:

previous_statuses (list[Status]) – Past statuses used to calculate progress variation.
statuses (list[Status]) – Current statuses, must be the same length as previous_statuses.
interval (float) – Time since the previous statuses in seconds.

Returns:

Overall download speed and process speed in bytes per second.

Return type:

tuple[float, float]

undr.display#

Overview#

Classes#

Functions#

Attributes#

Module Contents#

`undr.display`#