3.7. lars.progress - Rendering Progress

This module provides a wrapper that outputs simple progress meters to the command line based on source file positions, or an arbitrary counter. The ProgressMeter class is the major element that this module provides.

3.7.1. Classes

class lars.progress.ProgressMeter(fileobj=None, value=0, total=None, max_wait=0.1, stream=sys.stderr, mode='w', style=BarStyle, hide_on_finish=True)[source]

This class provides a simple means of rendering a progress meter at the command line. It can be driven either with a file object (in which case the current position of the file is used) or with an arbitrary value (which your code must provide). In the case of a file-object, the file must be seekable (so that the class can determine the overall length of the file). If fileobj is not specified, then total must be specified.

The class is intended to be used as a context manager. Upon entry it will render an initial progress meter, and will update it at reasonable intervals (dictated by the max_wait parameter) in response to calls to the update() method. When you leave the context, the progress meter will be automatically erased if hide_on_finish is True (which it is by default).

Within the context, the hide() and show() methods can be used to temporarily hide and show the progress meter (in order to display some status text, for example).

Parameters:
  • fileobj (file) – A file-like object from which to determine progress
  • value (int) – An arbitrary value from which to determine progress
  • total (int) – In the case that value is set, this must be set to the maximum value that value will take
  • max_wait (float) – The minimum length of time that must elapse before a screen update is permitted
  • stream (file) – The stream object that output should be written to, defaults to stderr
  • style – A reference to a class which will be used to render the progress meter, defaults to BarStyle
  • hide_on_finish (bool) – If True (the default), the progress meter will be erased when the context exits
hide()[source]

Hide the progress bar from the console (or whatever the output stream is connected to).

show()[source]

Show the progress bar on the console (or whatever the output stream is connected to).

update(value=None)[source]

Update the progress bar to position value (which must be less than the total value passed to the constructor).

class lars.progress.SpinnerStyle(meter)[source]

A ProgressMeter style that renders a simple spinning line.

class lars.progress.PercentageStyle(meter)[source]

A ProgressMeter style that renders a simple percentage counter.

class lars.progress.EllipsisStyle(meter)[source]

A ProgressMeter style that renders an looping series of dots.

class lars.progress.BarStyle(meter)[source]

A ProgressMeter style that renders a full progress bar and percentage.

class lars.progress.HashStyle(meter)[source]

A ProgressMeter style for those that remember FTP’s hash command!

3.7.2. Examples

The most basic usage of this class is as follows:

import io
from lars import iis, csv, progress

with io.open('logs\iis.txt', 'rb') as infile, \
        io.open('iis.csv', 'wb') as outfile, \
        progress.ProgressMeter(infile) as meter, \
        iis.IISSource(infile) as source, \
        csv.CSVTarget(outfile) as target:
    for row in source:
        target.write(row)
        meter.update()

Note that you do not need to worry about the detrimental performance effects of calling update() too often; the class ensures that repeated calls are ignored until max_wait seconds have elapsed since the last update.

Alternatively, if you wish to update according to, say, the number of files to process you could use something like the following example (which also demonstrates temporarily hiding the progress meter in order to show the current filename):

import os
import io
from lars import iis, csv, progress
from pathlib import Path

files = list(Path('.').iterdir())
with progress.ProgressMeter(total=len(files),
                            style=progress.BarStyle) as meter:
    for file_num, file_name in enumerate(files):
        meter.hide()
        print "Processing %s" % file_name
        meter.show()
        with file_name.open('rb') as infile, \
                file_name.with_suffix('.csv').open('wb') as outfile, \
                iis.IISSource(infile) as source, \
                csv.CSVTarget(outfile) as target:
            for row in source:
                target.write(row)
        meter.update(file_num)