Metadata-Version: 2.4
Name: sparklines
Version: 1.0.0
Summary: Generate sparklines for numbers using Unicode characters only.
Project-URL: Homepage, https://github.com/deeplook/sparklines
Project-URL: Issues, https://github.com/deeplook/sparklines/issues
Project-URL: CI, https://github.com/deeplook/sparklines/actions
Project-URL: Changelog, https://github.com/deeplook/sparklines/blob/main/CHANGELOG.md
Project-URL: Repository, https://github.com/deeplook/sparklines.git
Project-URL: Documentation, https://github.com/deeplook/sparklines
Author-email: Dinu Gherman <gherman@darwin.in-berlin.de>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: chart,tool,visualization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Other Audience
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Requires-Dist: termcolor>=2.4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'test'
Description-Content-Type: text/markdown

# Sparklines

[![Build](https://img.shields.io/github/actions/workflow/status/deeplook/sparklines/lint-test.yml)](https://pypi.org/project/sparklines)
[![Python versions](https://img.shields.io/pypi/pyversions/sparklines.svg)](https://pypi.org/project/sparklines)
[![PyPI version](https://img.shields.io/pypi/v/sparklines.svg)](https://pypi.org/project/sparklines/)
[![Downloads](https://static.pepy.tech/badge/sparklines/month)](https://pepy.tech/project/sparklines)
[![Status](https://img.shields.io/pypi/status/sparklines.svg)](https://pypi.org/project/sparklines)
[![Format](https://img.shields.io/pypi/format/sparklines.svg)](https://pypi.org/project/sparklines)
[![License](https://img.shields.io/pypi/l/sparklines.svg)](https://pypi.org/project/sparklines)
[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/deeplook)

Sparklines brings Edward Tufte's [sparklines] to your terminal — compact Unicode bar charts like ▃▁▄▁▅█▂▅, right in your shell or Python code. Originally built for sanity-checking sensor data in IoT networks, it works anywhere you need a quick visual summary of a sequence of numbers.

<p align="center">
  <img src="https://raw.githubusercontent.com/deeplook/sparklines/main/example_sensors.png" width="100%" alt="example usecase with sensor values">
  <br>
  <em>Example usecase for such "sparklines" on the command-line,
  showing IoT sensor values (generating code not included here).</em>
</p>

Positive values work best, but negatives are fully supported: mixed data auto-splits into two rows, all-negative data renders as downward bars (see [Mixed and negative datasets] below). True line-style sparklines would require a dedicated font — out of scope here. We use "▁▂▃▄▅▆▇█" for values and a blank for missing ones.

## Use cases

**Finance** — stock price history, daily P&L (bipolar: gains above, losses below), trading volume spikes, bid-ask spread over a session.

**IoT** — temperature and humidity sensors, power consumption per circuit, air quality index, battery charge on remote devices.

**DevOps & SRE** — request rate and error rate per minute, CI build duration trend, queue depth, replica lag.

**Data Science & ML** — training loss and validation accuracy per epoch, gradient norms, data drift score, inference latency after a deployment.

**Agentic computing** — token usage and cost per API call, context window fill level, cache hit rate, tool-call frequency per agent loop iteration.

**Health & Fitness** — heart rate during exercise, sleep quality over weeks, blood glucose across a day, daily caloric balance.

## Sample output

A recorded demo session — click the image to play it on [Asciinema]:

[![asciicast](https://asciinema.org/a/gXARhhEIskCsI4Xz.png)](https://asciinema.org/a/gXARhhEIskCsI4Xz)


## Installation

**From PyPI**

```bash
pip install sparklines
```

**On macOS with Homebrew**

```bash
brew tap deeplook/sparklines
brew install sparklines
```

**With uv**

```bash
uvx sparklines 2 7 1 8 2 8 1 8
```

Or install it into your `uv` tool environment:

```bash
uv tool install sparklines
```

**From Source**

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

**Development**

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


## Usage

### Python

```python
from sparklines import sparklines

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

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


### Mixed and negative datasets

Mixed positive/negative data is split automatically — no flags needed:

```python
from sparklines import sparklines

data = [50, 30, 80, -20, -60, -10, 40, 10]
for line in sparklines(data):
    print(line)
# ▅▄█   ▄▂
#    ▔▀▔
```

All-negative data renders as inverted (downward) bars automatically.

**`-n` / `--num-lines`**

| Form | Behaviour |
|------|-----------|
| integer (default `1`) | total rows, split proportionally; shared scale |
| `auto` | smallest row count for an exact proportional split |
| `up:down` (e.g. `2:1`) | explicit per-side layout; independent scaling |

```console
$ sparklines -n auto 1 2 3 -1 -2 -3 0 4 5 6
       ▃▆█
▄▆█   ▁███
   ▔▔▀
$ sparklines -n 2:1  1 2 3 -1 -2 -3 0 4 5 6
       ▃▆█
▄▆█   ▁███
   ▔▀█
```

**`--zero`**: `up` (default) places zeros on the positive baseline; `none` renders them as gaps.

```console
$ sparklines --zero up   0 1 2 -1 -2 0
▁▄█  ▁
   ▀█
$ sparklines --zero none 0 1 2 -1 -2 0
 ▄█
   ▀█
```

Downward bars use ANSI reverse video for full 8-level resolution. Falls back to `▔▀█` when `NO_COLOR`, `ANSI_COLORS_DISABLED`, or `TERM=dumb` is set.


## References

Inspired by Zach Holman's [spark](https://github.com/holman/spark), with prior Python ports by Kenneth Reitz ([spark.py](https://raw.githubusercontent.com/kennethreitz/spark.py/master/spark.py)), RedKrieg ([pysparklines](https://github.com/RedKrieg/pysparklines)), and Roger Allen ([shorter spark.py](https://gist.githubusercontent.com/rogerallen/1368454/raw/b17e96b56ae881621a9f3b1508ca2e7fde3ec93e/spark.py)).

This package adds:

- multi-line rendering for higher resolution (-n)
- gaps for missing values (None)
- auto-split for mixed positive/negative data
- inverted bars for all-negative data
- proportional row allocation (-n auto)
- explicit per-side layout (-n up:down)
- zero handling (--zero up / --zero none)
- colour emphasis via --emphasize
- line wrapping via --wrap

[Asciinema]: https://asciinema.org
[Python Package Index]: https://pypi.python.org/pypi/sparklines/
[uv]: https://docs.astral.sh/uv/
[sparklines]: http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR
[Mixed and negative datasets]: #mixed-and-negative-datasets
