Metadata-Version: 1.1
Name: progressist
Version: 0.0.1
Summary: Minimalist and pythonic progress bar
Home-page: https://github.com/yohanboniface/progressist
Author: Yohan Boniface
Author-email: hi@yohanboniface.me
License: WTFPL
Description: # Progressist
        
        Minimalist and pythonic progress bar.
        
        
        ## Install
        
            pip install progressist
        
        ## Usage
        
            from progressist import ProgressBar
            bar = ProgressBar(total=mytotalstuff)
            for item in mystuff:
                # do_stuff
                bar.update()
        
        Or use `bar.iter` transparently
        
            for item in bar.iter(mystuff):
                do_stuff
        
        It comes with a default rendering that is enough for starting, but it's made to be
        customised very easily: just writting a template string:
        
            bar = ProgressBar(total=mytotalstuff, template='{prefix} {progress} ETA: {eta}')
        
        It's just plain [python formatting](https://docs.python.org/3.4/library/string.html#formatspec)
        so you can use any valid string formatting to take control over the appearance.
        For example:
        
            bar = ProgressBar(total=mytotalstuff, template='{progress} {percent:.2%} ETA: {eta:%H:%M:%S}')
        
        You can also just change the fill character:
        
            bar = ProgressBar(total=mytotalstuff, done_char='#')
        
        You can change the progress logic itself, for example to use a spinner (included):
        
            bar = ProgressBar(total=mytotalstuff, progress='{spinner}')
            # 'progress' kwarg must return a valid template variable.
            # included ones are {bar} and {spinner}
        
        You can step by more than one at a time:
        
            for item in mystuff:
                amount = do_stuff()
                bar.update(step=amount)
        
        You can add more template vars by subclassing `ProgressBar`:
        
            class MyBar(ProgressBar):
        
                @property
                def swap(self):
                    return psutil.swap_memory().total
        
            bar = MyBar(total=20, template='{prefix} {progress} Swap usage: {swap}')
        
        If you are using the same configuration at different places, create a subclass and
        set its configuration as class properties:
        
            class MyBar(ProgressBar):
                template = ('Download |{animation}| {done:B}/{total:B}')
                done_char = '⬛'
        
            bar = MyBar()
        
        You want to compute yourself the done part?
        
            bar.update(done=myvar / othervar * another)
        
        Or the target total may change during process?
        
            bar.update(total=newcomputedtotal)
        
        See [examples](https://github.com/yohanboniface/progressist/blob/master/examples.py) for inspiration.
        
        To run examples, when git cloned the repository, simply run:
        
            python examples.py
        
        If you want to run only one example, add its name to the command line:
        
            python examples.py example_download
        
        
        ## Parameters
        
        You can set all of those parameters either as class properties:
        
            class MyBar(ProgressBar):
                done_char = 'x'
        
            bar = Bar()
        
        Or at init:
        
            bar = ProgressBar(done_char='x')
        
        Or at update:
        
            bar = Bar()
            bar.update(prefix='Finishing')
        
        | name  | default | description |
        | ----- | ------ | ------------- |
        | done_char | `=` | Char used for filling the progress bar |
        | remain_char | `' '` (a space) | Char used for filling the empty portion of the progress bar |
        | template | `{prefix} {progress} {percent} ({done}/{total})` | The template of the whole line |
        | prefix | `Progress:` | The leading label |
        | animation | '{progress}' | The actual widget used for progress, can be `{bar}`, `{spinner}` or `{stream}`
        | throttle | 0 | Minimum value between two `update` call to issue a render
        
        
        ## Built in template vars
        
        name      | description   | type | default formatting
        | ------  | ------------- | ------ | ---------------- |
        prefix    | Leading label in default template | string | str
        elapsed   | The elapsed time from the first iteration (in seconds) | int | as timedelta
        eta       | The computed ETA | datetime | `%H:%M:%S` if less than 24 hours, else `%Y-%m-%d %H:%M:%S`
        tta       | The estimated remaining time (time to arrival; in seconds) | int | as timedelta
        avg       | The average time per iteration, in seconds | float | `.2f`
        speed     | The average number of iterations per second | float | `.2f`
        done      | The number of done iterations | integer |
        total     | The total number of iterations to be done | integer |
        remaing   | The number of iterations remaining to be done | integer |
        percent   | The percent of iterations already done | float | `.2%`
        animation | The actual progress bar | template string (`{bar}`, `{spinner}` or `{stream}`) |
        
        
        ## Custom formatting
        
        We extend python default Formatter with some handy custom specs:
        
        - `B` type: render an int as human friendly bytes size. For example:
        
                > bar.total = 109830983
                > bar.template = '{total:B}'
                > bar.render()
                '104.7 MiB'
        
          You can still override the ndigits value:
        
                > bar.total = 109830983
                > bar.template = '{total:0.2B}'
                > bar.render()
                '104.74 MiB'
        
Keywords: progress bar
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
