README.rst
1Easy progress reporting for Python
2==================================
3
4|pypi|
5
6|demo|
7
8.. |pypi| image:: https://img.shields.io/pypi/v/progress.svg
9 :target: https://pypi.org/project/progress/
10.. |demo| image:: https://raw.github.com/verigak/progress/master/demo.gif
11 :alt: Demo
12
13Bars
14----
15
16There are 7 progress bars to choose from:
17
18- ``Bar``
19- ``ChargingBar``
20- ``FillingSquaresBar``
21- ``FillingCirclesBar``
22- ``IncrementalBar``
23- ``PixelBar``
24- ``ShadyBar``
25
26To use them, just call ``next`` to advance and ``finish`` to finish:
27
28.. code-block:: python
29
30 from progress.bar import Bar
31
32 bar = Bar('Processing', max=20)
33 for i in range(20):
34 # Do some work
35 bar.next()
36 bar.finish()
37
38or use any bar of this class as a context manager:
39
40.. code-block:: python
41
42 from progress.bar import Bar
43
44 with Bar('Processing', max=20) as bar:
45 for i in range(20):
46 # Do some work
47 bar.next()
48
49The result will be a bar like the following: ::
50
51 Processing |############# | 42/100
52
53To simplify the common case where the work is done in an iterator, you can
54use the ``iter`` method:
55
56.. code-block:: python
57
58 for i in Bar('Processing').iter(it):
59 # Do some work
60
61Progress bars are very customizable, you can change their width, their fill
62character, their suffix and more:
63
64.. code-block:: python
65
66 bar = Bar('Loading', fill='@', suffix='%(percent)d%%')
67
68This will produce a bar like the following: ::
69
70 Loading |@@@@@@@@@@@@@ | 42%
71
72You can use a number of template arguments in ``message`` and ``suffix``:
73
74========== ================================
75Name Value
76========== ================================
77index current value
78max maximum value
79remaining max - index
80progress index / max
81percent progress * 100
82avg simple moving average time per item (in seconds)
83elapsed elapsed time in seconds
84elapsed_td elapsed as a timedelta (useful for printing as a string)
85eta avg * remaining
86eta_td eta as a timedelta (useful for printing as a string)
87========== ================================
88
89Instead of passing all configuration options on instatiation, you can create
90your custom subclass:
91
92.. code-block:: python
93
94 class FancyBar(Bar):
95 message = 'Loading'
96 fill = '*'
97 suffix = '%(percent).1f%% - %(eta)ds'
98
99You can also override any of the arguments or create your own:
100
101.. code-block:: python
102
103 class SlowBar(Bar):
104 suffix = '%(remaining_hours)d hours remaining'
105 @property
106 def remaining_hours(self):
107 return self.eta // 3600
108
109
110Spinners
111========
112
113For actions with an unknown number of steps you can use a spinner:
114
115.. code-block:: python
116
117 from progress.spinner import Spinner
118
119 spinner = Spinner('Loading ')
120 while state != 'FINISHED':
121 # Do some work
122 spinner.next()
123
124There are 5 predefined spinners:
125
126- ``Spinner``
127- ``PieSpinner``
128- ``MoonSpinner``
129- ``LineSpinner``
130- ``PixelSpinner``
131
132Installation
133============
134
135Download from PyPi
136
137.. code-block:: shell
138
139 pip install progress
140
141
142Other
143=====
144
145There are a number of other classes available too, please check the source or
146subclass one of them to create your own.
147
148
149License
150=======
151
152progress is licensed under ISC
153
