API Reference

Classes

class enlighten.Manager(stream=None, counter_class=Counter, **kwargs)
Parameters:

Manager class for outputting progress bars to streams attached to TTYs

Progress bars are displayed at the bottom of the screen with standard output displayed above.

companion_stream

A companion stream is a file object that shares a TTY with the primary output stream. The cursor position in the companion stream will be moved in coordination with the primary stream.

If the value is None, sys.stdout and sys.stderr will be used as companion streams. Unless explicitly specified, a stream which is not attached to a TTY (the case when redirected to a file), will not be used as a companion stream.

counter(position=None, **kwargs)
Parameters:
Returns:

Instance of counter class
Return type:

Counter

Get a new progress bar instance

If position is specified, the counter's position can change dynamically if additional counters are called without a position argument.

stop()

Clean up and reset terminal

This method should be called when the manager and counters will no longer be needed.

Any progress bars that have leave set to True or have not been closed will remain on the console. All others will be cleared.

Manager and all counters will be disabled.

class enlighten.Counter(**kwargs)
Parameters:
  • bar_format (str) -- Progress bar format, see Format below
  • count (int) -- Initial count (Default: 0)
  • counter_format (str) -- Counter format, see Format below
  • desc (str) -- Description
  • enabled (bool) -- Status (Default: True)
  • leave (True) -- Leave progress bar after closing (Default: True)
  • manager (Manager) -- Manager instance. Creates instance if not specified
  • min_delta (float) -- Minimum time, in seconds, between refreshes (Default: 0.1)
  • series (sequence) -- Progression series, see Series below
  • stream (file object) -- Output stream. Not used when instantiated through a manager
  • total (int) -- Total count when complete
  • unit (str) -- Unit label

Progress bar and counter class

A Counter instance can be created with the Manager.counter() method or, when a standalone progress bar for simple applications is required, the Counter class can be called directly. The output stream will default to sys.stdout unless stream is set.

Note

With the default values for bar_format and counter_format, floats can not be used for total, count, or provided to update(). In order to use floats, provide custom formats to bar_format and counter_format. See Format below.

Series

The progress bar is constructed from the characters in series. series must be a sequence (str, list, tuple) containing single characters.

Default progress series (series):

' ▏▎▍▌▋▊▉█'

The first character is the fill character. When the count is 0, the bar will be made up of only this character. In the example below, characters 5 through 9 are fill characters.

The last character is the full character. When the count is equal to total, the bar will be made up of only this character. In the example below, characters 0 through 3 are full characters.

The remaining characters are fractional characters used to more accurately represent the transition between the full and fill characters. In the example below, character 4 is a fractional character.

'45% |████▋     |'
     '0123456789'

Format

If total is None or count becomes higher than total, the counter format will be used instead of the progress bar format.

Default counter format (counter_format):

'{desc}{desc_pad}{count:d} {unit}{unit_pad}{elapsed}, {rate:.2f}{unit_pad}{unit}/s]{fill}'

# Example output
'Loaded 30042 Files [00:01, 21446.45 Files/s]                                    '

Default progress bar format (bar_format):

'{desc}{desc_pad}{percentage:3.0f}%|{bar}| {count:{len_total}d}/{total:d} [{elapsed}<{eta}, {rate:.2f}{unit_pad}{unit}/s]'

# Example output
'Processing    22%|█████▊                   |  23/101 [00:27<01:32, 0.84 Files/s]'

Available fields:

  • count(int) - Current value of count
  • desc(str) - Value of desc
  • desc_pad(str) - A single space if desc is set, otherwise empty
  • elapsed(str) - Time elapsed since instance was created
  • rate(float) - Average increments per second since instance was created
  • unit(str) - Value of unit
  • unit_pad(str) - A single space if unit is set, otherwise empty

Addition fields for bar_format only:

  • bar(str) - Progress bar draw with characters from series
  • eta(str) - Estimated time to completion
  • len_total(int) - Length of total when converted to a string
  • percentage(float) - Percentage complete
  • total(int) - Value of total

Addition fields for counter_format only:

  • fill(str) - blank spaces, number needed to fill line

Instance Attributes

count

int - Current count

desc

str - Description

elapsed

float - Time since start (since last update if count`equals :py:attr:`total)

enabled

bool - Current status

manager

Manager - Manager Instance

position

int - Current position

total

int - Total count when complete

unit

str - Unit label

Functions

enlighten.get_manager(stream=None, counter_class=Counter, **kwargs)
Parameters:
Returns:

Manager instance
Return type:

Manager

Convenience function to get a manager instance

If stream is not attached to a TTY, the Manager instance is disabled.