etaprogress
===========

Draw progress bars with room for colors and display rates and ETAs in your console applications. ETA library is its own
class so it may be used in other non-console applications. ETAs calculated with simple linear regression.

This library supports both defined and undefined progress bars. Undefined progress bars are those that do not have a
"total size". Similar to when wget downloads a file with an unknown file size. Due to this, undefined progress bars
have no percent and no ETA. Defined progress bars are the usual progress bars with percentages and ETAs.

* Python 2.6, 2.7, 3.3, and 3.4 supported on Linux and OS X.
* Python 2.7, 3.3, and 3.4 supported on Windows (both 32 and 64 bit versions of Python).

Tested on Windows XP and Windows 10 technical preview.

.. image:: https://img.shields.io/appveyor/ci/Robpol86/etaprogress.svg?style=flat-square
   :target: https://ci.appveyor.com/project/Robpol86/etaprogress
   :alt: Build Status Windows

.. image:: https://img.shields.io/travis/Robpol86/etaprogress/master.svg?style=flat-square
   :target: https://travis-ci.org/Robpol86/etaprogress
   :alt: Build Status

.. image:: https://img.shields.io/codecov/c/github/Robpol86/etaprogress/master.svg?style=flat-square
   :target: https://codecov.io/github/Robpol86/etaprogress
   :alt: Coverage Status

.. image:: https://img.shields.io/pypi/v/etaprogress.svg?style=flat-square
   :target: https://pypi.python.org/pypi/etaprogress/
   :alt: Latest Version

.. image:: https://img.shields.io/pypi/dm/etaprogress.svg?style=flat-square
   :target: https://pypi.python.org/pypi/etaprogress/
   :alt: Downloads

Quickstart
----------

Install:

.. code:: bash

    pip install etaprogress


Example Implementations
-----------------------

.. image:: https://github.com/Robpol86/etaprogress/raw/master/example.gif?raw=true
   :alt: Example Scripts Screenshot

Source code for examples: `example.py <https://github.com/Robpol86/etaprogress/blob/master/example.py>`_,
`example_colors.py <https://github.com/Robpol86/etaprogress/blob/master/example_colors.py>`_,
and `example_wget.py <https://github.com/Robpol86/etaprogress/blob/master/example_wget.py>`_

Usage
-----

If all you need is a progress bar with an ETA, you only have to import a class in the ``etaprogress.progress`` module.
To get the progress bar itself just cast to string or print the instance.

Simple Usage
````````````

.. code:: python

    import time
    from etaprogress.progress import ProgressBar
    total = 5
    bar = ProgressBar(total, max_width=40)
    for i in range(total + 1):
        bar.numerator = i
        print bar
        time.sleep(1)

.. code::

      0% (0/5) [               ] eta --:-- -
     20% (1/5) [###            ] eta 00:05 \
     40% (2/5) [######         ] eta 00:04 |
     60% (3/5) [#########      ] eta 00:03 /
     80% (4/5) [############   ] eta 00:02 -
    100% (5/5) [###############] eta 00:00 \

Of course that's not a very good progress bar animation. Here's a better one with ``print_function``:

.. code:: python

    from __future__ import print_function
    import sys
    import time
    from etaprogress.progress import ProgressBar
    total = 5
    bar = ProgressBar(total, max_width=40)
    for i in range(total + 1):
        bar.numerator = i
        print(bar, end='\r')
        sys.stdout.flush()
        time.sleep(1)
    print()

.. code::

    100% (5/5) [###############] eta 00:00 \

Terminal Colors Support
```````````````````````

Colors are supported using `colorclass <https://github.com/Robpol86/colorclass>`_. Take a look at
`example_colors.py <https://github.com/Robpol86/etaprogress/blob/master/example_colors.py>`_ on how to implement
colorful progress bars. You may have to subclass one of the ProgressBar classes (or even BaseProgressBar) to add colors
to every nook and cranny of a progress bar.

Class Attributes
````````````````

There are five different progress bar classes with visual differences:

* ``ProgressBar`` -- a simple progress bar.
* ``ProgressBarBits`` -- similar to ``ProgressBar`` but converts numbers to bits, kilobits, etc.
* ``ProgressBarBytes`` -- similar to ``ProgressBar`` but converts numbers to bytes, kibibytes (kilobytes), etc.
* ``ProgressBarWget`` -- a progress bar that looks like the one in the GNU ``wget`` application.
* ``ProgressBarYum`` -- a progress bar that looks like the one in CentOS/RHEL 7 ``yum`` utility.

============== =============================================================================================================================
Name           Description/Notes
============== =============================================================================================================================
``max_width``  Limit number of characters shown (by default the full progress bar takes up the entire terminal width).
``eta_every``  Calculate and cache the ETA string after this many numerator setting iteration. Default is every iter.
``force_done`` For undefined progress bars this indicates that the progress has completed.
``filename``   'ProgressBarYum' only. The string to display before the progress bar. Limited to whatever space is available in the terminal.
============== =============================================================================================================================

Class Properties
````````````````

=============== =======================================================================================================================================================
Name            Description/Notes
=============== =======================================================================================================================================================
``denominator`` Returns the denominator of the progress bars. The same value provided when instantiating.
``done``        Returns True if the progress has completed.
``numerator``   Read/write. Returns the numerator as an integer or sets a new numerator. When setting a numerator it must be equal to or greater than the previous one.
``percent``     Returns the percent as a float.
``rate``        Returns the rate of the progress as a float.
``undefined``   Return True if the progress bar is undefined.
=============== =======================================================================================================================================================

Changelog
---------

1.1.1
`````

* Fixed broken setup.py file.

1.1.0
`````

* Added Windows support.

1.0.0
`````

* Initial release.
