Metadata-Version: 2.5
Name: term-sparkline
Version: 0.5.0
Summary: Adaptive high-definition and text-based inline sparklines for modern terminals
Author: brwchen
License: MIT
License-File: LICENSE
Keywords: charts,cli,finance,iterm2,kitty,monitoring,sparkline,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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 :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: pillow>=9.0.0; extra == 'all'
Provides-Extra: image
Requires-Dist: pillow>=9.0.0; extra == 'image'
Provides-Extra: test
Requires-Dist: pillow>=9.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# 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**:
  - **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.
  - **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 Vector Export**: Easily export sparklines to standalone SVG strings or files via `to_svg(series)`.
- **Ecosystem Ready**:
  - **`Rich` & `Textual`**: 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

```bash
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:

```bash
sparkline --demo
```

### Python API

```python
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

```python
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`

```python
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

```python
from term_sparkline import to_gif

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

### CLI Usage

```bash
# 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
