Metadata-Version: 2.4
Name: termplotx
Version: 0.1.0
Summary: Beautiful terminal charts using only the Python standard library
Author-email: Aman Mukati <amanmukati2002@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/amanmukati09/termplot
Project-URL: Documentation, https://github.com/amanmukati09/termplot#readme
Project-URL: Repository, https://github.com/amanmukati09/termplot
Project-URL: Bug Tracker, https://github.com/amanmukati09/termplot/issues
Project-URL: Changelog, https://github.com/amanmukati09/termplot/blob/main/CHANGELOG.md
Keywords: terminal,cli,chart,plot,visualization,sparkline,ascii,ansi,tui,data-science
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy>=1.21; extra == "numpy"
Provides-Extra: windows
Requires-Dist: colorama>=0.4.6; extra == "windows"
Provides-Extra: all
Requires-Dist: numpy>=1.21; extra == "all"
Requires-Dist: colorama>=0.4.6; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: numpy>=1.21; extra == "dev"
Requires-Dist: colorama>=0.4.6; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# termplotx

**Beautiful terminal charts using only the Python standard library.**

`termplotx` renders crisp charts directly in your terminal — no matplotlib, no
browser, **zero required dependencies**. It's built for ML engineers, data
scientists, and DevOps folks who live in SSH sessions, CI logs, Jupyter
terminals, or just want a quick plot without leaving the shell.

> **Note on the name:** the import name and the install name are both
> `termplotx` (the shorter `termplot` was already taken on PyPI).

```text
   200 ┤              ╭───╮
       │          ╭───╯   ╰╮
   145 ┤   ╭──────╯        ╰────
       │╭──╯
    90 ┤╯
       └────────────────────────
        Jan      Mar       May
```

- 📈 **Sparklines** — inline mini charts for metrics: `▂▅▃▇▁▆`
- 📊 **Line charts** — single and multi-series, high-res braille rendering
- 📊 **Bar charts** — horizontal and vertical
- 📉 **Histograms** — auto or fixed bins (NumPy-accelerated if installed)
- ✨ **Scatter plots** — braille sub-pixel resolution
- 🔥 **Heatmaps** — truecolor or shade-glyph fallback
- ⏱️ **Live charts** — update in place with ANSI escapes
- 🎨 **Themes** — `dark`, `light`, `neon`, `minimal`
- 📐 **Responsive** — auto-detects terminal width/height
- 🪟 **Cross-platform** — Linux, macOS, Windows (auto-enables ANSI)
- 🧩 **Typed** — ships `py.typed`, great Pylance/mypy experience

---

## Table of contents

- [Install](#install)
- [Quick start](#quick-start)
- [Charts](#charts)
  - [Sparklines](#sparklines)
  - [Line charts](#line-charts)
  - [Bar charts](#bar-charts)
  - [Histograms](#histograms)
  - [Scatter plots](#scatter-plots)
  - [Heatmaps](#heatmaps)
  - [Live charts](#live-charts)
- [Themes & color](#themes--color)
- [Loading data](#loading-data)
- [Command-line interface](#command-line-interface)
- [How it adapts to your terminal](#how-it-adapts-to-your-terminal)
- [API reference](#api-reference)
- [Optional dependencies](#optional-dependencies)
- [FAQ](#faq)
- [Development](#development)
- [License](#license)

---

## Install

```bash
pip install termplotx
```

Optional extras:

```bash
pip install "termplotx[numpy]"     # faster histogram binning
pip install "termplotx[windows]"   # colorama for older Windows consoles
pip install "termplotx[all]"       # everything optional
```

`termplotx` requires **Python 3.9+** and has **no required dependencies**.

---

## Quick start

```python
import termplotx as tp

# A sparkline for a row of metrics
print(tp.sparkline([1, 5, 3, 9, 2, 7, 4, 8]))

# A line chart
import math
print(tp.line([math.sin(i / 5) for i in range(60)], title="sine wave"))

# A bar chart
print(tp.bar([120, 150, 90, 170, 200], labels=["Jan", "Feb", "Mar", "Apr", "May"]))
```

Every function returns a **plain string**, so you can `print` it, log it, write
it to a file, put it in an f-string, or embed it in a TUI.

---

## Charts

### Sparklines

Compact, one-line charts — perfect for dashboards, log lines, and metrics.

```python
tp.sparkline([1, 5, 3, 9, 2, 7])           # ▁▅▃█▂▆
tp.sparkline(values, width=20)             # resample to 20 chars
tp.sparkline(values, min=0, max=100)       # fixed scale
tp.sparkline(values, theme="neon")         # colored
```

### Line charts

```python
# Single series
print(tp.line(values, title="latency (ms)", width=70, height=15))

# Multiple series with a legend
print(tp.line(
    [series_a, series_b],
    labels=["train", "val"],
    title="loss",
))

# Custom x-axis and fixed y-range
print(tp.line(y, x=timestamps, y_min=0, y_max=1))
```

```text
          loss
   0.9996 ┤⡠⠊⠉⠒⠤⡀          ⢀⠔⠊⠉⠒⡄
          │⡜      ⠈⢆      ⡠⠃     ⠱⡀
 -2.08e-4 ┤          ⠘⡄  ⡎          ⢣
       -1 ┤            ⠉            ⠈
          └────────────────────────
           0          29.5        59
           ■ train  ■ val
```

### Bar charts

```python
# Horizontal (default)
print(tp.bar([3, 7, 2, 9], labels=["a", "b", "c", "d"]))
print(tp.barh(values, labels))             # explicit

# Vertical (columns)
print(tp.barv([3, 7, 2, 9, 5], labels=["a", "b", "c", "d", "e"], height=8))

# Or dispatch by keyword
print(tp.bar(values, labels, orientation="vertical"))
```

```text
  a ████████                 3
 bb ██████████████████▋      7
ccc █████▍                   2
  d ████████████████████████ 9
```

### Histograms

```python
print(tp.histogram(samples))               # automatic bin count
print(tp.histogram(samples, bins=20))      # fixed bins
```

```text
[-2.84, -2.15) █▋                              3
[-2.15, -1.46) ███▏                            6
[-1.46, -0.77) ███████████████▊               30
[-0.77, -0.08) ███████████████████████▋       45
[-0.08,  0.61) ██████████████████████████████ 57
```

Install the `numpy` extra for faster binning on large arrays — the output is
identical either way.

### Scatter plots

```python
print(tp.scatter(xs, ys, title="x vs y", width=60, height=20))
```

### Heatmaps

```python
matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
print(tp.heatmap(matrix, row_labels=["r1", "r2", "r3"], col_labels=["a", "b", "c"]))
```

With color it paints each cell with a gradient background; without color it
falls back to shade glyphs `░▒▓█`.

### Live charts

Update a chart **in place** without scrolling the terminal:

```python
import random, time
import termplotx as tp

window = []
with tp.LiveChart() as chart:
    for _ in range(100):
        window.append(random.random())
        window = window[-60:]
        chart.update(tp.sparkline(window, min=0, max=1, width=60))
        time.sleep(0.1)
```

Or use the convenience loop:

```python
tp.live(lambda: tp.sparkline(next_window()), frames=200, interval=0.1)
```

---

## Themes & color

Four built-in themes: **`dark`** (default), **`light`**, **`neon`**, **`minimal`**.

```python
tp.line(values, theme="neon")
tp.bar(values, labels, theme="light")
```

Color is **auto-detected** from the output stream. You can force it:

```python
tp.sparkline(values, color=True)    # force on
tp.sparkline(values, color=False)   # force off (e.g. for log files)
```

`termplotx` honors the [`NO_COLOR`](https://no-color.org) and `FORCE_COLOR`
environment variables.

---

## Loading data

`termplotx` reads many formats out of the box via `tp.load`:

```python
table = tp.load("data.csv")        # CSV (header auto-detected)
table = tp.load("data.tsv")        # TSV
table = tp.load("data.json")       # list / list-of-lists / list-of-dicts / dict-of-lists
table = tp.load("data.txt")        # whitespace/newline-separated numbers
table = tp.load("-")               # read from stdin

# Columns by name or index
prices = table.column_floats("price")
first  = table.column_floats(0)

print(tp.line(prices, title="price"))
```

---

## Command-line interface

```bash
# Inline numbers
termplotx sparkline 1 5 3 9 2 7

# From files (column by name or index)
termplotx line   data.csv --column price --title "Price"
termplotx bar    data.csv --label name --column score
termplotx hist   data.csv -c value --bins 20
termplotx scatter data.csv --x lon --y lat
termplotx heatmap matrix.csv

# Auto-detect a sensible chart from the data shape
termplotx plot data.csv

# Pipe data in
cat metrics.txt | termplotx sparkline -
psql -c "..." | termplotx line -
```

Common flags: `--theme`, `--color` / `--no-color`, `--ascii`, `--width`,
`--height`, `--title`, `--column/-c` (repeatable), `--format`.

Run `termplotx <command> --help` for the full list.

---

## How it adapts to your terminal

- **Width/height** are auto-detected (`shutil.get_terminal_size`) and respect
  `COLUMNS`/`LINES`; pass `width=`/`height=` to override.
- **Color** is emitted only when the output is an interactive TTY (so piped or
  redirected output stays clean), unless you force it.
- **Unicode** glyphs are used when the stream can encode them; otherwise charts
  fall back to ASCII automatically. Force ASCII with `unicode=False` or the
  `TERMPLOT_ASCII=1` environment variable.
- **Windows**: ANSI is enabled automatically via colorama (if installed) or a
  built-in ctypes fallback — nothing to configure.

---

## API reference

| Function | Description |
|---|---|
| `sparkline(data, *, width, min, max, color, theme, unicode)` | One-line sparkline |
| `line(data, x=None, *, labels, width, height, title, y_min, y_max, ...)` | Line chart (1D or list of series) |
| `bar(values, labels=None, *, orientation="horizontal", ...)` | Bar chart dispatcher |
| `barh(values, labels=None, *, width, show_values, ...)` | Horizontal bars |
| `barv(values, labels=None, *, height, bar_width, gap, ...)` | Vertical bars |
| `histogram(data, bins=None, *, width, show_counts, ...)` | Histogram |
| `scatter(x, y, *, width, height, title, ...)` | Scatter plot |
| `heatmap(matrix, *, row_labels, col_labels, cell_width, ...)` | 2D heatmap |
| `LiveChart(stream=None, *, hide_cursor=True)` | Context manager for in-place updates |
| `live(render, *, frames=None, interval=0.2)` | Convenience live loop |
| `load(path, *, fmt=None)` | Load CSV/TSV/JSON/TXT/stdin into a `Table` |
| `THEMES`, `get_theme(name)` | Theme registry |
| `terminal_size()`, `supports_color()`, `supports_unicode()` | Terminal helpers |

All chart functions return `str`.

---

## Optional dependencies

| Extra | Installs | Enables |
|---|---|---|
| `numpy` | numpy | Faster histogram binning |
| `windows` | colorama | ANSI on older Windows consoles |
| `all` | numpy + colorama | Everything optional |
| `dev` | pytest, build, twine, … | Development & release |

None are required — the core is pure standard library.

---

## FAQ

**Why is there no color in my logs / CI output?**
That's intentional — color is disabled for non-TTY streams so files and CI logs
stay clean. Use `color=True` (or `FORCE_COLOR=1`) to force it.

**I see `?` boxes / garbled characters.**
Your terminal can't render the Unicode glyphs. Pass `unicode=False` or set
`TERMPLOT_ASCII=1` for ASCII-only output.

**Does it work in Jupyter?**
Yes — in a terminal-attached kernel. Printed strings show up fine; truecolor
depends on the front-end.

---

## Development

```bash
git clone https://github.com/amanmukati09/termplot
cd termplot
python -m venv .venv
.venv\Scripts\activate            # Windows
# source .venv/bin/activate        # macOS/Linux
pip install -e ".[dev]"
pytest
```

See [`INSTRUCTIONS.md`](INSTRUCTIONS.md) for the complete build-and-publish
walkthrough.

---

## License

[MIT](LICENSE) © 2026 Aman Mukati
