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