sparklines 0.4.2

Sample output

This is a recorded sample session illustrating how to use sparklines (as GitHub doesn’t render embedded Asciinema recordings you’ll see here an image pointing to the respective asciicast):

Here is some example output on the command-line (please note that in some browsers the vertical alignment of these block characters might be displayed slightly wrong, the same effect can be seen for other repos referenced below):

Examples for the code below:

$ sparklines 2 7 1 8 2 8 1 8
▂▇▁█▂█▁█
$ echo 2 7 1 8 2 8 1 8 | sparklines
▂▇▁█▂█▁█
$ sparklines < numbers.txt
▂▇▁█▂█▁█
$ sparklines 0 2. 1e0
▁█▅

Installation

You can install this package using pip install sparklines from the Python Package Index. You can also clone this repository and install it via python setup.py install or pip install -e .. After installing, you will have access system-wide (or in your virtualenv if you have used that) to sparklines, programmatically as well as via a command-line tool with the same name.

Test

To run the (still very small) “test suite”, download and unpack this repository or clone it, and run the command python setup.py test in the unpacked archive. This will use a minified version of the pytest package included in this package in the file test/runtests.py. If you have the excellent pytest package installed you can also run py.test test from the downloaded repository’s root folder.

Usage

Please note that the samples below might look a little funky (misaligned or even colored) in some browsers, but it should be totally fine when you print this in your terminal, Python or IPython session or your Python IDE of choice. Figure 2 below might sshow better what you should expect than the copied sample code thereafter:

$ sparklines 1 2 3 4 5.0 null 3 2 1
▁▃▅▆█ ▅▃▁

$ sparklines -n 2 1 2 3 4 5.0 null 3 2 1
  ▁▅█ ▁
▁▅███ █▅▁

In [1]: from sparklines import sparklines

In [2]: for line in sparklines([1, 2, 3, 4, 5.0, None, 3, 2, 1]):
   ...:     print(line)
   ...:
▁▃▅▆█ ▅▃▁

In [3]: for line in sparklines([1, 2, 3, 4, 5.0, None, 3, 2, 1], num_lines=2):
    print(line)
   ...:
  ▁▅█ ▁
▁▅███ █▅▁

References

This code was inspired by Zach Holman’s spark, converted to a Python module by Kenneth Reitz as spark.py and by RegKrieg to a Python package named pysparklines. And Roger Allen provides an even shorter spark.py.

But since it is so short and easy to code in Python we can add a few nice extra features I was missing, like:

• increasing resolution with multiple output lines per sparkline

• showing gaps in input numbers for missing data

• issuing warnings for negative values (allowed, but misleading)

• highlighting values exceeding some threshold with a different color (if termcolor package is available)

• wrapping long sparklines at some max. length

• (todo) adding separator characters like : at regular intervals