Skip to main content

Generate sparklines for numbers using Unicode characters only.

Project description

https://img.shields.io/github/actions/workflow/status/deeplook/sparklines/lint-test.yml https://img.shields.io/pypi/pyversions/sparklines.svg https://img.shields.io/pypi/v/sparklines.svg https://static.pepy.tech/badge/sparklines/month https://img.shields.io/pypi/status/sparklines.svg https://img.shields.io/pypi/format/sparklines.svg https://img.shields.io/pypi/l/sparklines.svg

This Python package implements Edward Tufte’s concept of sparklines, but limited to text only e.g. like this: ▃▁▄▁▅█▂▅ (this I likely not displayed correctly in every browser). You can find more information about sparklines on Wikipedia. This code was mainly developed for running simple plausibility tests in sensor networks as shown in fig. 1 below:

example usecase with sensor values

Fig. 1: Example usecase for such “sparklines” on the command-line, showing IoT sensor values (generating code not included here).

Due to limitations of available Unicode characters this works best when all values are positive. And even then true sparklines that look more like lines and less like bars are a real challenge, because they would need multiple characters with a single horizontal line on different vertical positions. This would work only with a dedicated font, which is way beyond the scope of this tool and which would significantly complicate its usage. So we stick to these characters: “▁▂▃▄▅▆▇█”, and use a blank for missing values.

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):

https://asciinema.org/a/5xwfvcrrk09fy3ml3a8n67hep.png

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

From PyPI (Recommended)

You can install this package from the Python Package Index using pip:

pip install sparklines

From Source

To install from source, clone this repository and install it:

git clone https://github.com/deeplook/sparklines.git
cd sparklines
pip install .

Development Installation

For development work, install in editable mode with development dependencies:

git clone https://github.com/deeplook/sparklines.git
cd sparklines
pip install -e ".[dev]"

After installing, you will have access system-wide (or in your virtual environment if you have used one) to the sparklines command-line tool, as well as the Python module for programmatic use.

Test

To run the test suite, download and unpack this repository or clone it, and run the command pytest tests in the unpacked archive in the downloaded repository 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 show better what you should expect than the copied sample code thereafter:

example interactive invocation

Fig. 2: Example invocation from a Python and an IPython session.

Command-Line

Here are two sample invocations from the command-line, copied into this README:

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

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

Programmatic

And here are sample invocations from interactive Python sessions, copied into this README. The main function to use programmatically is sparklines.sparklines():

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

  • wrapping long sparklines at some max. length

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sparklines-0.7.0.tar.gz (155.7 kB view details)

Uploaded Source

Built Distribution

sparklines-0.7.0-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

File details

Details for the file sparklines-0.7.0.tar.gz.

File metadata

  • Download URL: sparklines-0.7.0.tar.gz
  • Upload date:
  • Size: 155.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for sparklines-0.7.0.tar.gz
Algorithm Hash digest
SHA256 efd2ff5126dac53ea4212c1e225f286beaf1907b35204465b65010db2eec4b2a
MD5 a7379b31e5875f654d5eda4af165b891
BLAKE2b-256 1d28ef17c14c68e85b1f987d9ad64aa24f62592154f100206a097ffc545e4510

See more details on using hashes here.

Provenance

The following attestation bundles were made for sparklines-0.7.0.tar.gz:

Publisher: publish-to-pypi.yml on deeplook/sparklines

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sparklines-0.7.0-py3-none-any.whl.

File metadata

  • Download URL: sparklines-0.7.0-py3-none-any.whl
  • Upload date:
  • Size: 9.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for sparklines-0.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6683f3b908c48412f09eb361a714f841e41e7d90ca82ec12e6453e483d560d2c
MD5 b2bb1a6f819fdf80b760f449ed7ac4b8
BLAKE2b-256 c3cfeccac3ac4687ee710b87df8a0e224f5230d346f315aae6656040eb688814

See more details on using hashes here.

Provenance

The following attestation bundles were made for sparklines-0.7.0-py3-none-any.whl:

Publisher: publish-to-pypi.yml on deeplook/sparklines

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page