Sparklines (Text-based Unicode)

0.7.0 · active · verified Fri Apr 10

Sparklines is a Python library that generates text-only sparklines using Unicode characters. It's designed for displaying compact, inline visualizations of numerical data, primarily suitable for command-line interfaces or plain text environments. The current version is 0.7.0. Releases are infrequent, focusing on stability and minor enhancements.

Warnings

gotcha Sparklines generated by this library are purely text-based using Unicode characters. Their visual representation is heavily dependent on the terminal, console, or font used for display. Inconsistent font support or terminal settings can lead to misaligned or incorrect rendering.
Fix: Test rendering in target environments. Ensure a Unicode-compatible font and terminal are used. Consider adjusting `num_lines` for simpler output if display issues persist.
gotcha While negative values are technically supported, the visual representation can be misleading. Since the sparkline uses character heights to denote magnitude, negative values might not intuitively convey 'below zero' compared to graphical charts. The output is optimized for positive ranges.
Fix: For data with significant negative values, consider normalizing your data to a positive range before passing it to `sparklines`, or use a different visualization library if precise negative value representation is critical. The library can issue warnings for negative values if configured.
gotcha Achieving 'true' sparklines that appear as smooth lines rather than character-block patterns is challenging with this text-only approach. Unicode character limitations mean that highly granular or continuous line representations are not possible without dedicated font support, which is outside the scope of this tool.
Fix: Adjust expectations for text-based visualizations. If smooth, high-resolution line graphs are required, a graphical plotting library (e.g., Matplotlib, Plotly) should be used instead.

Install

pip install sparklines Install from PyPI

Imports

sparklines
```
from sparklines import sparklines
```

Quickstart

The `sparklines` function takes a list of numbers and returns an iterable of strings, each representing a line of the sparkline. You can iterate over these lines to print a multi-line sparkline. Optional arguments allow for customization like setting minimum/maximum values, number of output lines, and character styles.

from sparklines import sparklines

data = [1, 2, 3, 4, 5.0, None, 3, 2, 1, 0, 0, 0, 1, 2, 3, 4, 5, 4, 3, 2, 1]

for line in sparklines(data):
    print(line)

# Example with options
print('\nSparkline with custom range and fill:')
for line in sparklines(data, minimum=0, maximum=5, num_lines=2, fill='█', dot='●'):
    print(line)

view raw JSON →