ubelt.progiter module

ProgIter now exists in a standalone pip-installable module. The source code lives in its own github repo here: https://github.com/Erotemic/progiter

class ubelt.progiter.ProgIter(iterable=None, desc=None, total=None, freq=1, initial=0, eta_window=64, clearline=True, adjust=True, time_thresh=2.0, show_times=True, enabled=True, verbose=None, stream=None, chunksize=None, **kwargs)[source]

Bases: progiter.progiter._TQDMCompat, progiter.progiter._BackwardsCompat

Prints progress as an iterator progresses

Variables:
  • iterable (iterable) – An iterable iterable
  • desc (str) – description label to show with progress
  • total (int) – Maximum length of the process (estimated from iterable if not specified)
  • freq (int) – How many iterations to wait between messages.
  • adjust (bool) – if True freq is adjusted based on time_thresh
  • eta_window (int) – number of previous measurements to use in eta calculation
  • clearline (bool) – if true messages are printed on the same line
  • adjust – if True freq is adjusted based on time_thresh
  • time_thresh (float) – desired amount of time to wait between messages if adjust is True otherwise does nothing
  • show_times (bool) – shows rate, eta, and wall (defaults to True)
  • initial (int) – starting index offset (defaults to 0)
  • stream (file) – defaults to sys.stdout
  • enabled (bool) – if False nothing happens.
  • chunksize (int) – indicates that each iteration processes a batch of this size. Iteration rate is displayed in terms of single-items.
  • verbose (int) – verbosity mode 0 - no verbosity, 1 - verbosity with clearline=True and adjust=True 2 - verbosity without clearline=False and adjust=True 3 - verbosity without clearline=False and adjust=False

Note

Either use ProgIter in a with statement or call prog.end() at the end of the computation if there is a possibility that the entire iterable may not be exhausted.

Note

ProgIter is an alternative to tqdm. The main difference between ProgIter and tqdm is that ProgIter does not use threading where as tqdm does. ProgIter is simpler than tqdm and thus more stable in certain circumstances. However, tqdm is recommended for the majority of use cases.

Note

The ProgIter API will change to become inter-compatible with tqdm.

SeeAlso:
tqdm - https://pypi.python.org/pypi/tqdm
Reference:
http://datagenetics.com/blog/february12017/index.html

Example

>>> 
>>> import progiter
>>> def is_prime(n):
...     return n >= 2 and not any(n % i == 0 for i in range(2, n))
>>> for n in progiter.ProgIter(range(100), verbose=1):
>>>     # do some work
>>>     is_prime(n)
100/100... rate=... Hz, total=..., wall=... EST
set_extra(extra)[source]

specify a custom info appended to the end of the next message

Todo

  • [ ] extra is a bad name; come up with something better and rename

Example

>>> import progiter
>>> prog = progiter.ProgIter(range(100, 300, 100), show_times=False, verbose=3)
>>> for n in prog:
>>>     prog.set_extra('processesing num {}'.format(n))
0/2...
1/2...processesing num 100
2/2...processesing num 200
step(inc=1)[source]

Manually step progress update, either directly or by an increment.

Parameters:
  • idx (int) – current step index (default None) if specified, takes precidence over inc
  • inc (int) – number of steps to increment (defaults to 1)

Example

>>> import progiter
>>> n = 3
>>> prog = progiter.ProgIter(desc='manual', total=n, verbose=3)
>>> # Need to manually begin and end in this mode
>>> prog.begin()
>>> for _ in range(n):
...     prog.step()
>>> prog.end()

Example

>>> import progiter
>>> n = 3
>>> # can be used as a context manager in manual mode
>>> with progiter.ProgIter(desc='manual', total=n, verbose=3) as prog:
...     for _ in range(n):
...         prog.step()
begin()[source]

Initializes information used to measure progress

end()[source]
format_message()[source]

builds a formatted progres message with the current values. This contains the special characters needed to clear lines.

Example

>>> self = ProgIter(clearline=False, show_times=False)
>>> print(repr(self.format_message()))
'    0/?... \n'
>>> self.begin()
>>> self.step()
>>> print(repr(self.format_message()))
' 1/?... \n'

Example

>>> self = ProgIter(chunksize=10, total=100, clearline=False,
>>>                 show_times=False, microseconds=True)
>>> # hack, microseconds=True for coverage, needs real test
>>> print(repr(self.format_message()))
' 0.00% of 10x100... \n'
>>> self.begin()
>>> self.update()  # tqdm alternative to step
>>> print(repr(self.format_message()))
' 1.00% of 10x100... \n'
ensure_newline()[source]

use before any custom printing when using the progress iter to ensure your print statement starts on a new line instead of at the end of a progress line

Example

>>> # Unsafe version may write your message on the wrong line
>>> import progiter
>>> prog = progiter.ProgIter(range(4), show_times=False, verbose=1)
>>> for n in prog:
...     print('unsafe message')
 0/4...  unsafe message
 1/4...  unsafe message
unsafe message
unsafe message
 4/4...
>>> # apparently the safe version does this too.
>>> print('---')
---
>>> prog = progiter.ProgIter(range(4), show_times=False, verbose=1)
>>> for n in prog:
...     prog.ensure_newline()
...     print('safe message')
 0/4...
safe message
 1/4...
safe message
safe message
safe message
 4/4...
display_message()[source]

Writes current progress to the output stream