progress#

class pythonning.progress.DownloadProgressBar(*args, **kwargs)#

Bases: ProgressBar

A progress bar for downloads, expressed in MB units.

Recommended usage with pythonning.web.download.download_file.

Note the prefix and suffix argument are already consumed.

__init__(*args, **kwargs)#
add_progress(progress_amount: float, new_maximum: float | None = None)#

Make the bar progress by the given amount.

Amount is expressed in the same unit as given during instancing to the max value. As such amount given can’t be bigger than this value.

Parameters:

  • progress_amount – same unit as maximum value

  • new_maximum – optionally change the maximum value of the progress bar

bar_after = '| '#
bar_before = ' |'#
bar_empty = ' '#
bar_fill = '█'#
byte_to_MB = 9.5367e-07#
end()#

Stop the progress bar, so it doesn’t update anymore.

Recommended to always be called.

property max_value: float#
property min_value: float#
set_cursor_visibility(visible: bool)#

Add or remove a special character that make the stream cursor visible or not.

set_progress(total_progress: float, new_maximum: float | None = None)#

Make the bar move up to the given value.

Value is expressed in the same unit as given during instancing to the max value. As such the value given can’t be bigger than the max.

Parameters:

  • total_progress – same unit as maximum value

  • new_maximum – optionally change the maximum value of the progress bar

show_progress(block_number, block_size, total_size)#

To be used as callback during a download operation.

Parameters:

  • block_number – current block being downloaded, variable over time.

  • block_size – size of each download block, static over time.

  • total_size – total size of all the block to download, static over time. might not be provided which correspond to a value < 1.

start()#

Display the progress bar for the first time.

Not mandatory to be called.

update()#

Visually update the progress bar.

Called automatically but can be manually called to increase refresh rate.

class pythonning.progress.ProgressBar(min_value: float = 0.0, max_value: float = 1.0, width: int = 32, prefix: str = '', suffix: str = '', stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, hide_cursor: bool = True)#

Bases: object

A simple progress bar displayed in the given stream.

The recommended usage is to start() the progress, then call add_progress() during the measured process, and finished by calling end().

You can also create an “infinite” progress bar by not calling add_progress or set_progress and just calling update() instead.

Tips: you can add coloring by adding the color special character in the prefix and suffix strings.

Text Formatting

Prefix and suffix are formatted with the following tokens :

  • bar_min: minimal value of the bar specified by user

  • bar_max: maximal value of the bar specified by user

  • bar_index: the current value of the bar

  • elapsed_time: amount of time since first progress call, in seconds.

String are formatted as usual with the str.format function.

Example:

suffix="[{bar_index:<2n}/{bar_max}] elapsed {elapsed_time:.2f}s"

Changing style

To change the bar style you can subclass it and override the class attributes.

Example:

class MyProgressBar(ProgressBar):
    bar_fill = "#"

Future improvement

  • Missing time estimation features.

Parameters:

  • min_value – value that is considered the start of the progress bar

  • max_value – value that is considered the end of the progress bar

  • width – width of the progress bar in number of characters, excluding contextual info

  • prefix – string to format and add before the progress bar. see formatting documentation.

  • suffix – string to format and add after the progress bar. see formatting documentation.

  • stream – IO object to write the progress bar to

  • hide_cursor – hide blinking cursor in stdout while the progress bar is displaying

__init__(min_value: float = 0.0, max_value: float = 1.0, width: int = 32, prefix: str = '', suffix: str = '', stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, hide_cursor: bool = True)#
add_progress(progress_amount: float, new_maximum: float | None = None)#

Make the bar progress by the given amount.

Amount is expressed in the same unit as given during instancing to the max value. As such amount given can’t be bigger than this value.

Parameters:

  • progress_amount – same unit as maximum value

  • new_maximum – optionally change the maximum value of the progress bar

bar_after = '| '#
bar_before = ' |'#
bar_empty = ' '#
bar_fill = '█'#
end()#

Stop the progress bar, so it doesn’t update anymore.

Recommended to always be called.

property max_value: float#
property min_value: float#
set_cursor_visibility(visible: bool)#

Add or remove a special character that make the stream cursor visible or not.

set_progress(total_progress: float, new_maximum: float | None = None)#

Make the bar move up to the given value.

Value is expressed in the same unit as given during instancing to the max value. As such the value given can’t be bigger than the max.

Parameters:

  • total_progress – same unit as maximum value

  • new_maximum – optionally change the maximum value of the progress bar

start()#

Display the progress bar for the first time.

Not mandatory to be called.

update()#

Visually update the progress bar.

Called automatically but can be manually called to increase refresh rate.

pythonning.progress.catch_download_progress(**kwargs)#

A context manager to display a Download progress bar and handle its cleaning.

Make sure any stdout call (print, loggers) are done after the context manager has exit.

Example:

print("starting download")
with catch_progress() as progressbar:
    download_file(step_callback=progressbar.show_progress)
print("downloading finished")
Parameters:

kwargs – kwargs passed to DownloadProgressBar (prefix and suffix are already consumed).