plotcli-py 0.1.0__tar.gz

plotcli_py-0.1.0/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+plotcli is a terminal plotting library for Python using Unicode Braille characters, block elements, or ASCII. It has zero dependencies and is designed for CLI workflows.
+
+## Commands
+
+```bash
+# Run the CLI directly
+python plotcli.py line -e "[x**2 for x in range(20)]"
+python plotcli.py fn "sin(x)" 0 6.28
+
+# Install globally with uv
+uv tool install .
+
+# Run without installing
+uvx plotcli fn "sin(x)" 0 6.28
+
+# Build distribution
+uv build
+```
+
+## Architecture
+
+Single-file architecture (`plotcli.py`) with these main components:
+
+- **Canvas Classes** (lines 86-222): Three rendering backends
+  - `BrailleCanvas`: High-resolution (2x4 dots per cell, 8x effective resolution)
+  - `BlockCanvas`: Medium-resolution (half-block chars, 2x vertical resolution)
+  - `AsciiCanvas`: Maximum compatibility (1x1, uses `*`)
+
+- **Plot Class** (lines 283-520): Main plotting interface
+  - Manages series data, axis bounds, rendering
+  - Uses Bresenham's algorithm for line drawing
+  - Auto-detects terminal size
+
+- **Convenience Functions** (lines 525-599): `scatter()`, `line()`, `bar()`, `histogram()`, `density()`, `boxplot()`, `function_plot()`
+
+- **Data Parsing** (lines 649-756): Handles piped data, CSV files, JSON, Python expressions
+
+- **CLI** (lines 761-978): argparse-based interface with multiple data input methods
+
+## Key Patterns
+
+- Color handling uses ANSI escape codes via `colorize()` function
+- All plots normalize data to pixel coordinates via `normalize()` function
+- The `Plot` class supports multiple series with different types
+- Boxplot uses `compute_boxplot_stats()` for IQR-based statistics

plotcli_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 plotcli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plotcli_py-0.1.0/PKG-INFO

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: plotcli-py
+Version: 0.1.0
+Summary: Terminal plotting using Unicode Braille/Block/ASCII. Zero dependencies. Pipe data, plot math functions, read CSV -- all from the CLI.
+Project-URL: Homepage, https://github.com/wowave/plotcli-py
+Project-URL: Repository, https://github.com/wowave/plotcli-py
+License-Expression: MIT
+License-File: LICENSE
+Keywords: braille,chart,cli,graph,plot,terminal,unicode,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# plotcli
+
+Terminal plotting in Python using Unicode Braille characters, block elements, or ASCII. Zero dependencies. Designed for CLI workflows and AI coding assistants like Claude Code.
+
+Inspired by the R [plotcli](https://github.com/cheuerde/plotcli) package and Julia's [UnicodePlots.jl](https://github.com/JuliaPlots/UnicodePlots.jl).
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install plotcli
+
+# With pip
+pip install plotcli
+
+# Or run directly without installing
+uvx plotcli fn "sin(x)" 0 6.28
+```
+
+## Quick Start
+
+```bash
+# Pipe data
+echo "1 4 9 16 25 36 49 64 81 100" | plotcli line
+
+# Plot a math function
+plotcli fn "sin(x)" 0 6.28
+
+# From a Python expression
+plotcli scatter -e "[(x, x**2) for x in range(50)]"
+
+# From a CSV file
+plotcli line -f data.csv -x time -y value
+
+# Pipe from other commands
+seq 100 | awk '{print sin($1/10)}' | plotcli line
+```
+
+## Examples
+
+### Line Plot
+
+```bash
+echo "1 4 9 16 25 36 49 64 81 100" | plotcli line --title "Squares"
+```
+```
+                               Squares
+           ┌───────────────────────────────────────────────────────┐
+       100 ┤                                                    ⢀⠤⠊│
+           │                                                  ⡠⠒⠁  │
+      80.2 ┤                                               ⡠⠔⠉     │
+           │                                            ⡠⠔⠉        │
+      60.4 ┤                                        ⢀⡠⠔⠉           │
+           │                                     ⣀⠤⠒⠁              │
+y          │                                 ⢀⡠⠔⠊                  │
+      40.6 ┤                             ⣀⠤⠔⠊⠁                     │
+           │                         ⣀⠤⠒⠉                          │
+      20.8 ┤                   ⣀⡠⠤⠒⠊⠉                              │
+           │           ⢀⣀⡠⠤⠔⠒⠊⠉                                    │
+         1 ┤⣀⣀⣀⡠⠤⠤⠤⠔⠒⠊⠉⠁                                           │
+           └───────────────────────────────────────────────────────┘
+            0           2.25          4.5         6.75            9
+                                       x
+```
+
+### Math Functions
+
+```bash
+plotcli fn "sin(x)" 0 6.28 --title "Sine Wave"
+```
+```
+                              Sine Wave
+           ┌───────────────────────────────────────────────────────┐
+         1 ┤         ⣀⠴⠒⠋⠉⠉⠙⠒⠤⣀                                    │
+           │      ⢀⡴⠋⠁        ⠈⠳⢄                                  │
+       0.6 ┤    ⢀⡤⠋              ⠑⣄                                │
+           │   ⢠⠊                 ⠈⠱⡄                              │
+f      0.2 ┤ ⢀⠜⠁                    ⠘⢆                             │
+(          │⢠⠊                        ⠱⡄                           │
+x          │⠁                          ⠘⢆                        ⣠⠋│
+)     -0.2 ┤                             ⠱⡄                     ⡔⠁ │
+           │                              ⠈⢆⡀                 ⡠⠋   │
+      -0.6 ┤                                ⠙⢄              ⣠⠚⠁    │
+           │                                  ⠑⢦⡀        ⢀⣠⠞⠁      │
+        -1 ┤                                    ⠉⠒⠤⣄⣀⣀⣠⠤⠖⠋         │
+           └───────────────────────────────────────────────────────┘
+            0           1.57         3.14         4.71          6.28
+                                       x
+```
+
+Built-in math: `sin`, `cos`, `tan`, `sqrt`, `log`, `exp`, `pi`, `e`, and Python's `math` module.
+
+```bash
+plotcli fn "exp(-x/5) * cos(x*2)" 0 15 --title "Damped Oscillation"
+plotcli fn "x**3 - 3*x" -3 3 --title "Cubic"
+plotcli fn "log(x)" 0.1 10 --title "Logarithm"
+```
+
+### Histogram
+
+```bash
+plotcli hist -e "[random.gauss(0,1) for _ in range(500)]" --title "Normal Distribution"
+```
+```
+                         Normal Distribution
+           ┌───────────────────────────────────────────────────────┐
+        62 ┤                       ⣿⡇                              │
+           │                       ⣿⡇⢸⣿                            │
+      49.6 ┤                 ⢰⣶    ⣿⡇⢸⣿ ⣿⡇⢰⣶                       │
+           │                 ⢸⣿    ⣿⡇⢸⣿ ⣿⡇⢸⣿                       │
+c     37.2 ┤                 ⢸⣿ ⢰⣶ ⣿⡇⢸⣿ ⣿⡇⢸⣿                       │
+o          │               ⣀⡀⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿                       │
+u          │            ⢰⣶ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿                       │
+n     24.8 ┤            ⢸⣿ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⣀⡀ ⣤⡄                 │
+t          │          ⣶⡆⢸⣿ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⣿⡇ ⣿⡇                 │
+      12.4 ┤    ⢰⣶    ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⣿⡇ ⣿⡇⢠⣤ ⣶⡆            │
+           │  ⣀⡀⢸⣿ ⢠⣤ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⣿⡇ ⣿⡇⢸⣿ ⣿⡇⢠⣤ ⣤⡄       │
+         0 ┤⣶ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⢸⣿ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⣿⡇ ⣿⡇⢸⣿ ⣿⡇⢸⣿ ⣿⡇ ⣀⡀⢀⣀ ⣶│
+           └───────────────────────────────────────────────────────┘
+          -2.48         -1.06        0.36         1.78           3.2
+                                       x
+```
+
+### Density Plot
+
+```bash
+plotcli density -e "[random.gauss(0,1) for _ in range(1000)]" --title "Kernel Density"
+```
+```
+                            Kernel Density
+           ┌───────────────────────────────────────────────────────┐
+      0.38 ┤                       ⢀⠤⠒⠊⠉⠉⠢⢄                        │
+           │                      ⢰⠁       ⢣                       │
+       0.3 ┤                     ⢠⠃         ⢣                      │
+d          │                     ⡎           ⢣                     │
+e     0.23 ┤                    ⡜             ⢣                    │
+n          │                   ⡰⠁              ⠑⡄                  │
+s          │                 ⢀⠎                 ⠘⡄                 │
+i     0.15 ┤                ⢀⠎                   ⠱⡀                │
+t          │               ⢀⠎                     ⢣                │
+y     0.08 ┤              ⢠⠊                       ⠱⡀              │
+           │           ⢀⠤⠒⠁                         ⠈⠑⠤⡀           │
+   1.7e-05 ┤⣀⣀⣀⣀⣀⣀⣀⡠⠤⠔⠊⠁                               ⠈⠑⠢⠤⠤⢄⣀⣀⣀⣀⣀⣀│
+           └───────────────────────────────────────────────────────┘
+          -4.01         -2.01        -0.02        1.97          3.96
+                                       x
+```
+
+### Boxplot
+
+```bash
+plotcli boxplot \
+  -e "[[random.gauss(m, 1+i*0.3) for _ in range(100)] for i, m in enumerate([0, 3, 7])]" \
+  --title "Boxplots"
+```
+```
+                               Boxplots
+           ┌───────────────────────────────────────────────────────┐
+     10.45 ┤                                           ⠈⠉⢹⠉⠉       │
+           │                                             ⢸         │
+      7.83 ┤                                         ⡖⠒⠒⠒⠚⠒⠒⠒⠒⡆    │
+           │                           ⢀             ⡏⠉⠉⠉⠉⠉⠉⠉⠉⡇    │
+v     5.22 ┤                         ⠐⠒⢲⠒⠒           ⠉⠉⠉⠉⢹⠉⠉⠉⠉⠁    │
+a          │                           ⢸                 ⢸         │
+l          │                       ⣖⣒⣒⣒⣚⣒⣒⣒⣒⡆          ⢀⣀⣸⣀⣀       │
+u      2.6 ┤       ⠒⠒⡖⠒⠂           ⠧⠤⠤⠤⢤⠤⠤⠤⠤⠇            ⠐         │
+e          │    ⢀⣀⣀⣀⣀⣇⣀⣀⣀⣀             ⢸                           │
+     -0.02 ┤    ⢸⣒⣒⣒⣒⣒⣒⣒⣒⣺           ⠐⠒⠚⠒⠒                         │
+           │         ⡇                                             │
+     -2.63 ┤       ⠉⠉⡉⠉⠁                                           │
+           └───────────────────────────────────────────────────────┘
+                   box_1             box_2             box_3
+                                       x
+```
+
+### Scatter Plot
+
+```bash
+plotcli scatter \
+  -e "[(x, x**1.5 + random.gauss(0,5)) for x in range(40)]" \
+  --title "Noisy Power Law"
+```
+
+### Heatmap
+
+```bash
+plotcli heatmap \
+  -e "[[math.sin(r/3+c/3) for c in range(20)] for r in range(10)]" \
+  --title "Heatmap"
+```
+
+## Canvas Types
+
+Three rendering backends with different resolution/compatibility tradeoffs:
+
+### Braille (default) -- highest resolution
+```bash
+plotcli fn "sin(x)" 0 6.28 --canvas braille
+```
+Uses Unicode Braille patterns (U+2800-U+28FF). Each character cell contains a 2x4 dot grid, giving **8x** the effective resolution of ASCII.
+
+### Block -- medium resolution
+```bash
+plotcli fn "sin(x)" 0 6.28 --canvas block
+```
+```
+                             Block Canvas
+           ┌───────────────────────────────────────────────────────┐
+         1 ┤         ▄▄█▀▀▀▀█▄▄                                    │
+           │       ▄█▀        ▀▀▄                                  │
+       0.6 ┤     ▄▀▀             █▄                                │
+           │   ▄█▀                 █▄                              │
+f      0.2 ┤  █▀                    ▀█▄                            │
+(          │▄█                        █▄                           │
+x          │▀                          ▀█                        █▀│
+)     -0.2 ┤                             █▄                    ▄█  │
+           │                              ▀█                 ▄█▀   │
+      -0.6 ┤                                ▀█             ▄▄▀     │
+           │                                  ▀█▄        ▄█▀       │
+        -1 ┤                                    ▀▀█▄▄▄▄█▀▀         │
+           └───────────────────────────────────────────────────────┘
+```
+Uses half-block characters (▀ ▄ █) for 2x vertical resolution.
+
+### ASCII -- maximum compatibility
+```bash
+plotcli fn "sin(x)" 0 6.28 --canvas ascii
+```
+```
+                             ASCII Canvas
+           ┌───────────────────────────────────────────────────────┐
+         1 ┤          ********                                     │
+           │       ****      ****                                  │
+       0.6 ┤     ***            ***                                │
+           │   ***                ***                              │
+f      0.2 ┤  **                    **                             │
+(          │**                        **                           │
+x          │*                          **                        **│
+)     -0.2 ┤                             **                    **  │
+           │                              ***                ***   │
+      -0.6 ┤                                ***            ***     │
+           │                                  ****      ****       │
+        -1 ┤                                     ********          │
+           └───────────────────────────────────────────────────────┘
+```
+Works in any terminal. Uses `*` for data points.
+
+## Data Input
+
+| Method | Example |
+|--------|---------|
+| **Pipe values** | `echo "1 4 9 16" \| plotcli line` |
+| **Pipe lines** | `seq 50 \| plotcli line` |
+| **x,y pairs** | `echo -e "1,2\n3,4\n5,6" \| plotcli scatter -d ","` |
+| **Expression** | `plotcli line -e "[x**2 for x in range(20)]"` |
+| **Tuple list** | `plotcli scatter -e "[(x, sin(x)) for x in range(50)]"` |
+| **CSV file** | `plotcli line -f data.csv -x time -y price` |
+| **JSON** | `echo '[1,4,9,16]' \| plotcli line -j` |
+| **Math function** | `plotcli fn "sin(x)*exp(-x/5)" 0 20` |
+| **Shell pipeline** | `curl -s api \| jq '.[].value' \| plotcli line` |
+
+## Options
+
+```
+-W, --width       Canvas width in characters (auto-detected)
+-H, --height      Canvas height in characters (auto-detected)
+-t, --title       Plot title
+--x-label         X-axis label
+--y-label         Y-axis label
+-c, --color       Series color (red, green, blue, yellow, magenta, cyan, ...)
+--canvas          braille (default), block, or ascii
+--xlim MIN MAX    X-axis limits
+--ylim MIN MAX    Y-axis limits
+--bins N          Number of histogram bins
+--no-legend       Hide legend
+-d, --delimiter   Input delimiter
+-j, --json        Parse stdin as JSON
+-e, --eval        Python expression for data
+-f, --file        CSV/TSV file path
+-x, --x-col       X column name or index
+-y, --y-col       Y column name or index
+```
+
+## Use with Claude Code
+
+plotcli is designed for AI-assisted CLI workflows. Claude Code can generate and display plots inline:
+
+```
+> Plot a sine wave
+
+$ plotcli fn "sin(x)" 0 6.28 --title "Sine Wave"
+
+> Show me the distribution of file sizes in this directory
+
+$ find . -type f -exec stat -f%z {} \; | plotcli hist --title "File Sizes" --bins 20
+
+> Visualize the CSV data
+
+$ plotcli scatter -f measurements.csv -x temperature -y pressure --title "T vs P"
+```
+
+To make `plotcli` available globally for Claude Code:
+
+```bash
+uv tool install plotcli          # install globally via uv
+# or
+pip install plotcli              # install globally via pip
+```
+
+## Python API
+
+```python
+import plotcli
+
+# Quick one-liners
+plotcli.line(range(10), [x**2 for x in range(10)], title="Squares").show()
+plotcli.scatter(xs, ys, title="My Data", canvas_type="braille").show()
+plotcli.histogram(data, bins=20, title="Distribution").show()
+plotcli.density(data, title="KDE").show()
+plotcli.boxplot([group_a, group_b], names=["A", "B"]).show()
+plotcli.function_plot("sin(x)*x", 0, 10).show()
+
+# Multi-series
+from plotcli import Plot
+p = Plot(title="Comparison", width=60, height=15)
+p.add(x1, y1, "line", color="blue", name="model")
+p.add(x2, y2, "scatter", color="red", name="data")
+p.show()
+
+# Get string output (no print)
+output = p.render()
+```
+
+## License
+
+LGPL-3.0 (same as the original R plotcli)
+
+## Credits
+
+Python port inspired by [plotcli](https://github.com/cheuerde/plotcli) by Claas Heuer, which was in turn inspired by [UnicodePlots.jl](https://github.com/JuliaPlots/UnicodePlots.jl).