README.md
1[![Build Status](https://travis-ci.org/rasbt/pyprind.svg?branch=master)](https://travis-ci.org/rasbt/pyprind)
2[![Coverage Status](https://coveralls.io/repos/rasbt/pyprind/badge.svg?branch=master&service=github)](https://coveralls.io/github/rasbt/pyprind?branch=master)
3![Python 2.7](https://img.shields.io/badge/python-2.7-blue.svg)
4![Python 3](https://img.shields.io/badge/python-3-blue.svg)
5[![License](https://img.shields.io/badge/license-new%20BSD-blue.svg)](https://github.com/rasbt/pyprind/blob/master/LICENSE.txt)
6
7
8
9# PyPrind (Python Progress Indicator)
10
11
12The `PyPrind` (Python Progress Indicator) module provides a **progress bar** and a
13**percentage indicator** object that let you track the progress of a loop structure or other iterative computation.
14Typical applications include the processing of large data sets to provide an intuitive estimate
15at runtime about the progress of the computation.
16
17
18
19![PyPrind Demo](./images/pyprind-1.gif "PyPrind Demo")
20
21<br>
22
23#### Progress Bars and Percentage Generators
24
25```python
26import pyprind
27
28for i in pyprind.prog_bar(range(n)):
29 time.sleep(timesleep) # your computation here
30```
31```
320% 100%
33[##############################] | ETA: 00:00:00
34Total time elapsed: 00:00:05
35```
36
37<br>
38<br>
39
40```python
41for i in pyprind.prog_percent(range(n)):
42 time.sleep(timesleep) # your computation here
43```
44
45```
46[10 %] Time elapsed: 00:00:01 | ETA: 00:00:04
47```
48
49#### While-loops
50
51The `ProgBar` and `ProgPercent` classes also support while loops if desired.
52The objects are updated inside the loop using the `update` method as shown below:
53
54```python
55import random
56import pyprind
57import time
58
59timesleep = 0.05
60random.seed(1)
61collection = set()
62
63n = 100
64bar = pyprind.ProgBar(n, track_time=False, title='while example')
65
66while len(collection) < n:
67 r = random.randint(0, 10**5)
68 if r % 7 and r not in collection:
69 collection.add(r)
70 bar.update()
71 time.sleep(timesleep)
72
73print(bar)
74```
75```
76while example
770% 100%
78[##############################]
79Title: while example
80 Started: 09/07/2016 13:06:58
81 Finished: 09/07/2016 13:07:03
82 Total time elapsed: 00:00:05
83```
84
85
86<br>
87<br>
88
89<a id='advanced_tracking'>
90
91#### Advanced Tracking
92
93If you have the `psutil` package installed, you can set the `monitor=True` to track CPU and memory usage:
94
95```python
96bar = pyprind.ProgBar(n, monitor=True)
97for i in range(n):
98 time.sleep(timesleep) # your computation here
99 bar.update()
100print(bar)
101```
102
103```
1040% 100%
105[##############################] | ETA: 00:00:00
106Total time elapsed: 00:00:05
107Title:
108 Started: 09/07/2016 13:14:09
109 Finished: 09/07/2016 13:14:14
110 Total time elapsed: 00:00:05
111 CPU %: 1.90
112 Memory %: 0.48
113```
114
115<br>
116<br>
117
118#### Choose Your Favorite Bar Style
119
120```python
121bar = pyprind.ProgBar(n, bar_char='█')
122for i in range(n):
123 time.sleep(0.1) # do some computation
124 bar.update()
125```
126
127```
1280% 100%
129[██████████████████████████████] | ETA: 00:00:00
130Total time elapsed: 00:00:10
131```
132
133#### Note to PyCharm users
134
135If you are using the PyCharm IDE, you need to pass the `sys.stdout` or `sys.err`
136as a `stream` argument to display the progress indicators correctly in the IDE. For example,
137
138```python
139import sys
140
141bar = pyprind.ProgBar(n, stream=sys.stdout)
142for i in range(n):
143 time.sleep(0.1) # do some computation
144 bar.update()
145```
146
147<br>
148<br>
149
150###[View more examples in an IPython Demo Notebook](http://nbviewer.ipython.org/github/rasbt/pyprind/blob/master/examples/pyprind_demo.ipynb)
151
152
153<br>
154<br>
155
156
157<a id='sections'>
158
159# Sections
160
161
162- [Installation](#installation)
163- [Documentation](#documentation)
164- [Examples](#examples)
165- [Contact](#contact)
166- [Changelog](https://raw.githubusercontent.com/rasbt/pyprind/master/CHANGELOG.txt)
167
168
169<p><a id="installation"></a></p>
170
171<br>
172<br>
173<br>
174
175# Installation
176
177[[back to top](#sections)]
178
179The most convenient way to install PyPrind is via tools like `pip` or `easy_install`:
180
181- `pip install pyprind`
182
183- `easy_install pyprind`
184
185
186
187PyPrind comes without any dependencies except for the optional [psutil](https://pypi.python.org/pypi/psutil) to [monitor CPU and memory usages](#advanced_tracking). You can install `psutil` via `pip install psutil` or install it automatically with PyPrind:
188 `pip install pyprind -r requirements.txt`
189
190
191
192Alternatively, you can install PyPrind the classic way: Download the package from the Python Package Index [https://pypi.python.org/pypi/PyPrind](https://pypi.python.org/pypi/PyPrind), unzip it,
193navigate into the unzipped directory, and use the command
194
195`python setup.py install`
196
197
198
199
200<p><a id="documentation"></a></p>
201<br>
202<br>
203<br>
204
205# Documentation
206
207[[back to top](#sections)]
208
209
210
211PyPrind consists of two class objects that can visualize the progress of a computation on the output screen.
212Progress bars are available via `ProgBar`, and percentage indicators can be used via a `ProgPercent`.
213
214```python
215 n = 10000000
216 bar = pyprind.ProgBar(n) # 1) initialization with number of iterations
217 for i in range(n):
218 # do some computation
219 bar.update() # 2) update the progress visualization
220```
221
222Alternatively, the progress can be tracked via the equivalent generator functions `prog_bar` and `prog_percent`:
223
224```python
225 for i in pyprind.prog_bar(range(n)):
226 # do something
227 pass
228```
229
230
231<br>
232
233#### Complete Parameter of Parameters and Options
234
235##### ProgBar
236
237*`ProgBar(iterations, track_time=True, width=30, bar_char='#',
238 stream=2, title='', monitor=False, update_interval=None))`*
239
240- iterations : `int`
241 Number of iterations for the iterative computation.
242- track_time : `bool` (default: `True`)
243 Prints elapsed time when loop has finished.
244- width : `int` (default: 30)
245 Sets the progress bar width in characters.
246- stream : `int` (default: 2).
247 Setting the output stream.
248 Takes `1` for stdout, `2` for stderr, or a custom stream object
249- title : `str` (default: `''`)
250 Setting a title for the progress bar.
251- monitor : `bool` (default: `False`)
252 Monitors CPU and memory usage if `True` (requires `psutil` package).
253- update_interval : float or int (default: `None`)
254 The update_interval in seconds controls how often the progress
255 is flushed to the screen.
256 Automatic mode if `update_interval=None`.
257
258##### ProgPercent
259
260*`ProgPercent(iterations, track_time=True,
261 stream=2, title='', monitor=False, update_interval=None)`*
262
263- iterations : `int`
264 Number of iterations for the iterative computation.
265- track_time : `bool` (default: `True`)
266 Prints elapsed time when loop has finished.
267- stream : `int` (default: 2).
268 Setting the output stream.
269 Takes `1` for stdout, `2` for stderr, or a custom stream object
270- title : `str` (default : `''`).
271 Setting a title for the percentage indicator.
272- monitor : `bool` (default: `False`)
273 Monitors CPU and memory usage if `True` (requires `psutil` package).
274- update_interval : float or int (default: `None`)
275 The update_interval in seconds controls how often the progress
276 is flushed to the screen.
277 Automatic mode if `update_interval=None`.
278
279##### update method
280
281*`update(iterations=1, item_id=None, force_flush=False)`*
282
283- iterations : int (default: `1`)
284 default argument can be changed to integer values
285 `>=1` in order to update the progress indicators more than once
286 per iteration.
287- item_id : str (default: `None`)
288 Print an item_id sring behind the progress bar
289- force_flush : bool (default: `False`)
290 If True, flushes the progress indicator to the output screen
291 in each iteration.
292
293<br>
294
295
296<p><a id="examples"></a></p>
297
298<br>
299<br>
300<br>
301
302# Examples
303
304[[back to top](#sections)]
305
306Examples for using the progress bar and percentage indicator objects can be found in the [IPython Demo Notebook](https://github.com/rasbt/pyprind/blob/master/examples/pyprind_demo.ipynb).
307
308<p><a id="contact"></a></p>
309
310<br>
311<br>
312<br>
313
314
315
316