README.rst
1.. start-badges
2
3| |docs| |travis| |codecov|
4| |linux| |windows| |mac| |bsd|
5| |pypi| |supported-versions| |supported-implementations|
6| |Fedora| |EPEL| |Arch| |Debian| |Ubuntu| |Anaconda|
7
8.. |docs| image:: https://img.shields.io/readthedocs/python-enlighten.svg?style=plastic&logo=read-the-docs
9 :target: https://python-enlighten.readthedocs.org
10 :alt: Documentation Status
11
12.. |travis| image:: https://img.shields.io/travis/Rockhopper-Technologies/enlighten.svg?style=plastic&logo=travis
13 :target: https://travis-ci.org/Rockhopper-Technologies/enlighten
14 :alt: Travis-CI Build Status
15
16.. |codecov| image:: https://img.shields.io/codecov/c/github/Rockhopper-Technologies/enlighten.svg?style=plastic&logo=codecov
17 :target: https://codecov.io/gh/Rockhopper-Technologies/enlighten
18 :alt: Coverage Status
19
20.. |pypi| image:: https://img.shields.io/pypi/v/enlighten.svg?style=plastic&logo=pypi
21 :alt: PyPI Package latest release
22 :target: https://pypi.python.org/pypi/enlighten
23
24.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/enlighten.svg?style=plastic&logo=pypi
25 :alt: Supported versions
26 :target: https://pypi.python.org/pypi/enlighten
27
28.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/enlighten.svg?style=plastic&logo=pypi
29 :alt: Supported implementations
30 :target: https://pypi.python.org/pypi/enlighten
31
32.. |linux| image:: https://img.shields.io/badge/Linux-yes-success?style=plastic&logo=linux
33 :alt: Linux supported
34 :target: https://pypi.python.org/pypi/enlighten
35
36.. |windows| image:: https://img.shields.io/badge/Windows-yes-success?style=plastic&logo=windows
37 :alt: Windows supported
38 :target: https://pypi.python.org/pypi/enlighten
39
40.. |mac| image:: https://img.shields.io/badge/MacOS-yes-success?style=plastic&logo=apple
41 :alt: MacOS supported
42 :target: https://pypi.python.org/pypi/enlighten
43
44.. |bsd| image:: https://img.shields.io/badge/BSD-yes-success?style=plastic&logo=freebsd
45 :alt: BSD supported
46 :target: https://pypi.python.org/pypi/enlighten
47
48.. |Fedora| image:: https://img.shields.io/fedora/v/python3-enlighten?color=lightgray&logo=Fedora&style=plastic&label=Fedora
49 :alt: Latest Fedora Version
50 :target: https://src.fedoraproject.org/rpms/python-enlighten
51
52.. |EPEL| image:: https://img.shields.io/fedora/v/python3-enlighten/epel8?color=lightgray&label=EPEL&logo=EPEL
53 :alt: Latest EPEL Version
54 :target: https://src.fedoraproject.org/rpms/python-enlighten
55
56.. |Arch| image:: https://img.shields.io/aur/version/python-enlighten?color=lightgray&logo=Arch%20Linux&style=plastic&label=Arch
57 :alt: Latest Arch Linux Version
58 :target: https://aur.archlinux.org/packages/python-enlighten
59
60.. |Debian| image:: https://img.shields.io/debian/v/enlighten/sid?color=lightgray&logo=Debian&style=plastic&label=Debian
61 :alt: Latest Debian Version
62 :target: https://packages.debian.org/source/sid/enlighten
63
64.. |Ubuntu| image:: https://img.shields.io/ubuntu/v/enlighten?color=lightgray&logo=Ubuntu&style=plastic&label=Ubuntu
65 :alt: Latest Ubuntu Version
66 :target: https://launchpad.net/ubuntu/+source/enlighten
67
68.. |Anaconda| image:: https://img.shields.io/conda/vn/conda-forge/enlighten?color=lightgrey&label=Anaconda&logo=Conda%20Forge&style=plastic
69 :alt: Latest Conda Forge Version
70 :target: https://anaconda.org/conda-forge/enlighten
71
72.. end-badges
73
74Overview
75========
76
77Enlighten Progress Bar is a console progress bar library for Python.
78
79The main advantage of Enlighten is it allows writing to stdout and stderr without any
80redirection or additional code. Just print or log as you normally would.
81
82Enlighten also includes experimental support for Jupyter Notebooks.
83
84|
85
86.. image:: https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/doc/_static/demo.gif
87 :target: http://python-enlighten.readthedocs.io/en/stable/examples.html
88
89The code for this animation can be found in
90`demo.py <https://github.com/Rockhopper-Technologies/enlighten/blob/master/examples/demo.py>`__
91in
92`examples <https://github.com/Rockhopper-Technologies/enlighten/tree/master/examples>`__.
93
94Documentation
95=============
96
97https://python-enlighten.readthedocs.io
98
99Installation
100============
101
102PIP
103---
104
105.. code-block:: console
106
107 $ pip install enlighten
108
109
110RPM
111---
112
113Fedora and EL8 (RHEL/CentOS)
114^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115
116(EPEL_ repositories must be configured_ for EL8)
117
118.. code-block:: console
119
120 $ dnf install python3-enlighten
121
122EL7 (RHEL/CentOS)
123^^^^^^^^^^^^^^^^^
124
125(EPEL_ repositories must be configured_)
126
127.. code-block:: console
128
129 $ yum install python2-enlighten
130 $ yum install python36-enlighten
131
132
133PKG
134---
135
136Arch Linux
137^^^^^^^^^^
138
139.. code-block:: console
140
141 $ pacman -S python-enlighten
142
143
144DEB
145---
146
147Debian and Ubuntu
148^^^^^^^^^^^^^^^^^
149.. code-block:: console
150
151 $ apt-get install python3-enlighten
152
153
154.. _EPEL: https://fedoraproject.org/wiki/EPEL
155.. _configured: https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F
156
157
158Conda
159-----
160
161.. code-block:: console
162
163 $ conda install -c conda-forge enlighten
164
165
166Examples
167========
168
169Basic
170-----
171
172For a basic status bar, invoke the Counter_ class directly.
173
174.. code-block:: python
175
176 import time
177 import enlighten
178
179 pbar = enlighten.Counter(total=100, desc='Basic', unit='ticks')
180 for num in range(100):
181 time.sleep(0.1) # Simulate work
182 pbar.update()
183
184Advanced
185--------
186
187To maintain multiple progress bars simultaneously or write to the console, a manager is required.
188
189Advanced output will only work when the output stream, ``sys.stdout`` by default,
190is attached to a TTY. get_manager_ can be used to get a manager instance.
191It will return a disabled Manager_ instance if the stream is not attached to a TTY
192and an enabled instance if it is.
193
194.. code-block:: python
195
196 import time
197 import enlighten
198
199 manager = enlighten.get_manager()
200 ticks = manager.counter(total=100, desc='Ticks', unit='ticks')
201 tocks = manager.counter(total=20, desc='Tocks', unit='tocks')
202
203 for num in range(100):
204 time.sleep(0.1) # Simulate work
205 print(num)
206 ticks.update()
207 if not num % 5:
208 tocks.update()
209
210 manager.stop()
211
212Counters
213--------
214
215The Counter_ class has two output formats, progress bar and counter.
216
217The progress bar format is used when a total is not ``None`` and the count is less than the
218total. If neither of these conditions are met, the counter format is used:
219
220.. code-block:: python
221
222 import time
223 import enlighten
224
225 counter = enlighten.Counter(desc='Basic', unit='ticks')
226 for num in range(100):
227 time.sleep(0.1) # Simulate work
228 counter.update()
229
230
231Additional Examples
232-------------------
233* `basic <https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/examples/basic.py>`__ - Basic progress bar
234* `context manager <https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/examples/context_manager.py>`__ - Managers and counters as context managers
235* `floats <https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/examples/floats.py>`__ - Support totals and counts that are ``floats``
236* `multicolored <https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/examples/multicolored.py>`__ - Multicolored progress bars
237* `multiple with logging <https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/examples/multiple_logging.py>`__ - Nested progress bars and logging
238* `FTP downloader <https://raw.githubusercontent.com/Rockhopper-Technologies/enlighten/master/examples/ftp_downloader.py>`__ - Show progress downloading files from FTP
239
240Customization
241-------------
242
243Enlighten is highly configurable. For information on modifying the output, see the
244Series_ and Format_ sections of the Counter_ documentation.
245
246.. _Counter: http://python-enlighten.readthedocs.io/en/stable/api.html#enlighten.Counter
247.. _Manager: http://python-enlighten.readthedocs.io/en/stable/api.html#enlighten.Manager
248.. _get_manager: http://python-enlighten.readthedocs.io/en/stable/api.html#enlighten.get_manager
249.. _Format: http://python-enlighten.readthedocs.io/en/stable/api.html#counter-format
250.. _Series: http://python-enlighten.readthedocs.io/en/stable/api.html#series
251.. _EPEL: https://fedoraproject.org/wiki/EPEL
252.. _configured: https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F
253
