API Reference¶
Classes¶
-
class
enlighten.
Manager
(stream=None, counter_class=Counter, **kwargs)¶ Parameters: - stream (file object) -- Output stream. If
None
, defaults tosys.stdout
- counter_class (class) -- Progress bar class (Default:
Counter
) - set_scroll (bool) -- Enable scroll area redefinition (Default:
True
) - companion_stream (file object) -- See companion_stream
below. (Default:
None
) - enabled (bool) -- Status (Default: True)
- no_resize (bool) -- Disable resizing support
- kwargs (dict) -- Any additional keyword arguments
will be used as default values when
counter()
is called.
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
andsys.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: - position (int) -- Line number counting from the bottom of the screen
- kwargs (dict) -- Any additional keyword arguments
are passed to
Counter
Returns: Instance of counter class
Return type: Get a new progress bar instance
If
position
is specified, the counter's position can change dynamically if additional counters are called without aposition
argument.
- stream (file object) -- Output stream. If
-
class
enlighten.
Counter
(**kwargs)¶ Parameters: - additional_fields (dict) -- Additional fields used for formating
- bar_format (str) -- Progress bar format, see Format below
- count (int) -- Initial count (Default: 0)
- counter_format (str) -- Counter format, see Format below
- color (str) -- Series color as a string or RGB tuple see Series Color
- 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)
- offset (int) -- Number of non-printable characters to account for when formatting
- 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 theManager.counter()
method or, when a standalone progress bar for simple applications is required, theCounter
class can be called directly. The output stream will default tosys.stdout
unlessstream
is set.Note
With the default values for
bar_format
andcounter_format
,floats
can not be used fortotal
,count
, or provided toupdate()
. In order to usefloats
, provide custom formats tobar_format
andcounter_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 tototal
, 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'
Series Color
The characters specified by
series
will be displayed in the terminal's current foreground color. This can be overwritten with thecolor
argument.color
can be specified asNone
, astring
or, an iterable of three integers, 0 - 255, describing an RGB color.For backward compatibility, a color can be expressed as an integer 0 - 255, but this is deprecated in favor of named or RGB colors.
If a terminal is not capable of 24-bit color, and is given a color outside of its range, the color will be downconverted to a supported color.
Valid colors for 8 color terminals:
- black
- blue
- cyan
- green
- magenta
- red
- white
- yellow
Additional colors for 16 color terminals:
- bright_black
- bright_blue
- bright_cyan
- bright_green
- bright_magenta
- bright_red
- bright_white
- bright_yellow
See this chart for a complete list of supported color strings.
Note
If an invalid color is specified, an
AttributeError
will be raisedFormat
If
total
isNone
orcount
becomes higher thantotal
, 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 ofcount
- desc(
str
) - Value ofdesc
- desc_pad(
str
) - A single space ifdesc
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 ofunit
- unit_pad(
str
) - A single space ifunit
is set, otherwise empty
Additional fields for
bar_format
only:- bar(
str
) - Progress bar draw with characters fromseries
- eta(
str
) - Estimated time to completion - len_total(
int
) - Length oftotal
when converted to a string - percentage(
float
) - Percentage complete - total(
int
) - Value oftotal
Addition fields for
counter_format
only:- fill(
str
) - blank spaces, number needed to fill line
Additional fields when subcounters are used:
- count_n (
int
) - Current value ofcount
- count_0(
int
) - Remaining count after deducting counts for all subcounters - percentage_n (
float
) - Percentage complete (bar_format
only) - percentage_0(
float
) - Remaining percentage after deducting percentages for all subcounters (bar_format
only)
Note
n denotes the order the subcounter was added starting at 1. For example, count_1 is the count for the first subcounter added and count_2 is the count for the second subcounter added.
Additional fields when
add_subcounter()
is called withall_fields
set toTrue
:- eta_n (
str
) - Estimated time to completion (bar_format
only) - rate_n (
float
) - Average increments per second since parent was created
User-defined fields:
Theadditional_fields
parameter can be used to pass a dictionary of additional user-defined fields. The dictionary values can be updated after initialization to allow for dynamic fields. Any fields that share names with built-in fields are ignored.Offset
When
offset
isNone
, the width of the bar portion of the progress bar and the fill characters for counter will be automatically determined, taking into account terminal escape sequences that may be included in the string.Under special circumstances, and to permit backward compatibility,
offset
may be explicitly set to anint
value. When explicitly set, automatic detection of escape sequences is disabled.Instance Attributes
-
add_subcounter
(color, count=0, all_fields=False)¶ Parameters: - color (str) -- Series color as a string or RGB tuple see Series Color
- count (int) -- Initial count (Default: 0)
- all_fields (bool) -- Populate
rate
andeta
formatting fields (Default: False)
Returns: Subcounter instance
Return type: Add a subcounter for multicolored progress bars
-
clear
(flush=True)¶ Parameters: flush (bool) -- Flush stream after clearing progress bar (Default:True) Clear progress bar
-
close
(clear=False)¶ Do final refresh and remove from manager
If
leave
is True, the default, the effect is the same asrefresh()
.
-
color
¶ Color property Preferred to be a string or iterable of three integers for RGB Single integer supported for backwards compatibility
-
format
(width=None, elapsed=None)¶ Parameters: Returns: Formatted progress bar or counter
Return type: Format progress bar or counter
-
refresh
(flush=True, elapsed=None)¶ Parameters: Redraw progress bar
-
subcount
¶ Sum of counts from all subcounters
-
class
enlighten.
SubCounter
(parent, color=None, count=0, all_fields=False)¶ A child counter for multicolored progress bars.
This class tracks a portion of multicolored progress bar and should be initialized through
Counter.add_subcounter()
Instance Attributes
-
update
(incr=1, force=False)¶ Parameters: Increment progress bar and redraw
Both this counter and the parent are incremented.
Progress bar is only redrawn if min_delta seconds past since the last update on the parent.
-
update_from
(source, incr=1, force=False)¶ Parameters: - source (
SubCounter
) --SubCounter
orCounter
to increment from - incr (int) -- Amount to increment
count
(Default: 1) - force (bool) -- Force refresh even if
min_delta
has not been reached
Move a value to this counter from another counter.
source
must be the parentCounter
instance or aSubCounter
with the same parent- source (
-
Functions¶
-
enlighten.
get_manager
(stream=None, counter_class=Counter, **kwargs)¶ Parameters: - stream (file object) -- Output stream. If
None
, defaults tosys.stdout
- counter_class (class) -- Progress bar class (Default:
Counter
) - kwargs (dict) -- Any additional keyword arguments will passed to the manager class.
Returns: Manager instance
Return type: Convenience function to get a manager instance
If
stream
is not attached to a TTY, theManager
instance is disabled.- stream (file object) -- Output stream. If