term-sparkline 📈

Adaptive high-definition (1px Retina) and Unicode-based inline sparklines for modern terminals.

Designed specifically for CLI tables, financial monitoring dashboards, and real-time metric trackers.

✨ Features

• Adaptive Terminal Detection: Automatically selects the best rendering protocol:
  • iTerm2 / WezTerm / Ghostty: Renders ultra-fine, anti-aliased 1-pixel inline graphics directly in a single text row.
  • Kitty: Uses Kitty graphics protocol.
  • Sixel: Pure Python Sixel encoding for Linux servers, Foot, and classic terminals.
  • Fallback / Standard Terminals: Gracefully degrades to smooth Unicode Braille vector curves (⡠⠤⠒⠊⠉) or classic Block bars ( ▂▃▅▇).
• Financial Visualization Extras:
  • Technical Indicators Overlay: ma_sparkline(prices, windows=[5, 20]) for Moving Averages & bollinger_sparkline(prices) for Bollinger Bands.
  • Multi-Series / Benchmark Comparison: Overlay dual curves (e.g. Stock vs Benchmark Index).
  • Split-Color across Baseline: Automatically colors segments above baseline as Red and below as Green.
  • Mini Candlesticks (OHLC): Renders miniature inline candlestick charts.
  • Mini Volume Bars: Single-line volume histogram bars.
  • Extremum Highlighting: Accent markers on highest (peak) and lowest (trough) values.
  • 24-bit TrueColor Gradients: Smooth ANSI TrueColor gradient in Braille & Block text modes.
  • Area Gradient Fill: Semi-transparent smooth gradient area beneath the curve.
  • Reference Baseline: Subtle dotted baseline for previous close / zero level.
  • End-point Highlight Dot: Prominently marks the latest live price tick.
  • Auto Color & Market Palettes: Automatic color calculation (palette="cn" for Red Up/Green Down, palette="us" for Green Up/Red Down).
• Streaming & Export Tools:
  • LiveSparkline: High-performance circular buffer for streaming real-time live tickers.
  • Animated GIF Export: to_gif(series, "trend.gif") creates lightweight animated cumulative drawing GIFs.
  • SVG & HTML / Jupyter Export: Standalone SVG vector or inline HTML for Jupyter Notebook (_repr_html_).
• Ecosystem Ready:
  • Textual Widget: Drop-in SparklineWidget for interactive terminal applications.
  • Rich Renderable: Pass Sparkline directly into Table.add_row().
  • Pandas & Polars Extensions: Direct series.sparkline() accessor support for both Dataframe engines.
• Zero-Friction & Lightweight: Zero required dependencies (optional Pillow for inline images).
• CLI Utility & Interactive Demo: Ready to use as a standalone command-line tool with built-in sparkline --demo.

📦 Installation

pip install "term-sparkline[image]"

(Without [image], it functions in pure-text Unicode Braille/Block mode with zero dependencies).

🚀 Quick Start

Interactive Demo

Run the built-in terminal showcase to preview all rendering styles and live streaming:

sparkline --demo

Python API

from term_sparkline import sparkline

prices = [10.2, 10.3, 10.1, 10.5, 10.8, 10.7, 11.2, 11.0, 11.5]

# Auto-detects terminal, applies area fill, reference baseline and end-point dot
chart = sparkline(
    prices,
    fill=True,
    baseline=10.5,
    show_dot=True,
    palette="cn"  # Red for rise, Green for fall
)

print(f"600519 贵州茅台  1680.50  +2.15%  {chart}")

Polars & Pandas Integration

import polars as pl
import term_sparkline

s = pl.Series("price", [10, 12, 11, 15, 18, 22])
print(s.sparkline(fill=True, show_dot=True))

Integration with rich

from rich.table import Table
from rich.console import Console
from term_sparkline import Sparkline

console = Console()
table = Table(title="Live Stock Watcher")

table.add_column("Symbol", justify="center")
table.add_column("Price", justify="right")
table.add_column("Change", justify="right")
table.add_column("Trend (Sparkline)", justify="left")

table.add_row("600519", "1680.50", "+2.15%", Sparkline([10, 12, 11, 15, 18], fill=True, show_dot=True))
table.add_row("000001", "11.20", "-1.32%", Sparkline([18, 16, 14, 12, 11], fill=True, show_dot=True))

console.print(table)

Animated GIF Export

from term_sparkline import to_gif

to_gif([10, 12, 11, 15, 18, 22], filepath="sparkline.gif")

CLI Usage

# Pass numbers with baseline and area fill
sparkline 10 12 11 15 18 22 --baseline 12 --fill --dot

# Or pipe from other tools
echo "10,12,11,15,18,22" | sparkline --palette us

📄 License

MIT