/monologue

Primary LanguagePythonOtherNOASSERTION

MONOLOGUE

This Python module offers an interface to unify:

  • logging
    basically, standard Python logging with some boilerplate removed.
  • progress information
    dots, loops count, completion percentages about an ongoing computation.

Contents

1   Licence

See COPYING: New BSD license (open to discussion).

2   Requirements and compatibility

Target to day is stock Python 2.5-7 with no requirement.

This works on Python 2.7/Linux.

Here be moreinfo.

3   Concept

This is meant to be 'easy' to use, even for non computer scientists and required to work well even on very minimal exotic platforms such as Windows console terminals.

The light from the most beautiful nebulae far up in the sky travels a long time to reach us; likewise, it may be that a lot of computational time separates you from the contemplation of an interesting result after you fed a program heaps of data (for instance, modelisation with scikit-learn).

It is good practice to impress the viewer with details about what's going on: informative messages and/or progress information. The purpose of this Python module is to help you do so.

3.1   Differences with stock logging

Some things are deliberately different from logging. This module will be logging to stdout by default.

Loggers defined here here have a verbosity setting: this integer has the opposite meaning of the "log level" from logging.

3.2   Progress information

All indicators below shown can be combined at will.

3.2.1   Running distance unknown

If your program is looping in the dark, searching for a solution with the loop number unknown, then maybe the best output you can do to say "hey, I'm alive, I'm digging that mine out" is a plain old dot every given number of steps:

.

Then, one minute later, another dot:

..

Many dots, and so on, you get it.

There is also a counter, that you can combine with dots:

..........
[Exciting computation] Iteration 1000 done
..........
[Exciting computation] Iteration 2000 done
...

Every logger can use a different dot character if you wish:

.....x..x....xxx..

3.2.2   Running distance known

It's fair, if you know your program is going to run through 42195 iterations a particular loop, to let the viewer know how far it's gone, proportionnaly:

[Exciting computation] 10 %
[Exciting computation] 20 %
...

You can also mix this with dots.

This uses the plain logging system.

3.2.3   Logging and progress combined

The combination of logging full lines and progress dots that are not individually followed with a newline character involves a trick to end the line before an informative message.

4   How to use

Here be docs; for now there only is a huge doctest.

5   Roadmap

  • Handle CR/LF as well as \n

    Read sys.platform, act accordingly.

  • Handle other streams than sys.stdout

    If progress dots are to be printed on random streams, the handling of newlines may be a little tricky. A workaround is that the dev uses separate loggers (different names) if they intend to log to files and show progress.

  • Lazy string formatting

    take advantage of this feature from logging (with a keyword)

  • easy access to a log format that includes timestamp

    with an on/off switch and strptime format

  • Color?

    I doubt this works on Windows.

  • Use configuration files?

    For some of the above features.

  • dot_string keyword in Logger.dot()?

    So the char, by default a dot, could be temporarily changed to indicate some info about how the ongoing computation:

    ...o...x..E......x

6   From ideas to bytes

Code monkey is Feth Arezki.

The idea behind this, and many ideas of how it should be done are Gael Varoquaux's. Also participated in the discussion, or motivated me: Olivier Grisel, Fabian Pedregosa, Nelle Varoquaux. See scikit-learn/scikit-learn#130