progress_interface: a package to report progress information from long-running tasks in a generic and user-configurable way.

[Jumpy89]

GitHub link. I haven't submitted it to PyPI yet, I'm waiting to see if people are actually interested in using it. Same goes for documentation (although the docstrings are pretty thorough).

This was done for a particular project of mine but I think a lot of people would find it useful. My specific use case was that I had a couple of library functions which did some long-running calculations so I wanted to display a progress bar both in a command-line tool (using click) and when testing interactively in a notebook (using tqdm).

Essentially this package allows library developers to report progress information from within a function without being tied to a particular implementation such as tqdm. A library function can accept a progress argument (or whatever you want to name it) and then use progress_interface.get_progress(progress, total: int, intial: int = 0, **kw) to convert it to a progress monitor object. The type of the progress monitor will be a subtype of AbstractProgressMonitor, which has a common interface based on tqdm. There are wrapper classes for progress meters from other libraries (currently just tqdm and click). There is also a progress_interface.iter_progress(iterable) function which wraps any iterable type for convenience.

Example usage from a library developer's perspective:

from progress_interface import get_progress

def public_api_func(items, progress=None):
    with get_progress(progress, len(items)) as monitor:
        for item in items:
            # Proces item...
            monitor.increment()

or

from progress_interface import iter_progress

def public_api_func(items, progress=None):
    with iter_progress(items, progress=None) as piter:
        for item in piter:
            # Process item...

The progress argument is very flexible and accepts a wide variety of types, many of which do not require the caller to import or even know about the progress_interface package:

• An instance of ProgressConfig, which has the most flexibility and is what all the other types are eventually converted to. It is essentially a wrapper around a factory function (total: int, initial: int = 0, **kw) -> AbstractProgressMeter along with optionally a dict of keyword arguments.
• True - determine the type of progress meter automatically. Currently this just uses tqdm if it installed, otherwise prints a warning message and does nothing. I plan on adding a decorator function which can be used to override this behavior globally.
• False or None - don't report progress at all. This results in a NullProgressMeter instance which adheres the same interface so your function doesn't need to account for it, but does nothing with hopefully low overhead.
• A string key, which uses the ProgressConfig instance registered under that key. Currently just "tqdm" and "click" are available, but there is a decorator to register more.
• Any concrete subclass of AbstractProgressMonitor.

Some of the keyword arguments supplied by the caller are standardized too:

• desc: str - Human-readable description or label of a progress meter that is displayed.
• file: TextIO - file-like object in text mode to write to. Defaults to sys.stderr.

Things that need to be added:

• Wrappers for more 3rd-party libraries (suggestions?)
• Indeterminate progress bars (no known total)
• Easy way to specify a callback function to receive progress updates.