gofish-python 0.1.0

Python wrapper for GoFish Graphics - JavaScript is the source of truth for rendering

GoFish Python

Python wrapper for GoFish Graphics, a declarative charting library.

Important: JavaScript is the source of truth for all rendering, layout, and reactivity. This Python package provides a syntax-similar API that translates Python calls to JavaScript execution. All interactive and animated graphics are handled by SolidJS in JavaScript.

Installation

Using pip

# Install the package
pip install gofish-python

# Install a JavaScript bridge (choose one):
pip install pythonmonkey  # Recommended
# OR
pip install jsbridge

Using uv (Recommended)

# Install uv: https://github.com/astral-sh/uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the package
uv pip install gofish-python

# Install a JavaScript bridge (choose one):
uv pip install pythonmonkey  # Recommended
# OR
uv pip install jsbridge

You also need the GoFish JavaScript bundle. Either:

1. Install it as a sibling package in your monorepo
2. Set GOFISH_JS_PATH environment variable to the dist directory
3. The package will try to auto-detect it in common locations

Quick Start

from gofish import chart, spread, rect

# Data
alphabet = [
    {"letter": "A", "frequency": 28},
    {"letter": "B", "frequency": 55},
    {"letter": "C", "frequency": 43},
]

# Create chart (JavaScript executes all rendering)
chart(alphabet).flow(spread("letter", dir="x")).mark(rect(h="frequency")).render(w=500, h=300, axes=True)

Architecture

JavaScript as Source of Truth

This wrapper follows the same pattern as Plotly and Bokeh:

• Python: Provides the API, data, and configuration
• JavaScript: Handles all rendering, layout computation, and reactivity

All GoFish features work through JavaScript:

• SolidJS reactivity for animations
• Interactive graphics via DOM events
• Complex layouts and coordinate transforms
• SVG rendering

How It Works

1. Python API: You write Python code with syntax similar to JS GoFish
2. Translation: Python calls are converted to JavaScript function calls
3. Execution: JavaScript (via bridge) executes GoFish code
4. Rendering: SolidJS renders interactive SVG to DOM or HTML

Usage

Basic Chart

from gofish import chart, spread, rect

data = [{"x": 1, "y": 10}, {"x": 2, "y": 20}]

chart(data).flow(spread("x", dir="x")).mark(rect(h="y")).render(w=500, h=300)

Stacked Bar Chart

from gofish import chart, spread, stack, rect

chart(data).flow(
    spread("category", dir="x"),
    stack("series", dir="y")
).mark(rect(h="value", fill="series")).render(w=500, h=300, axes=True)

With Pandas

import pandas as pd
from gofish import chart, spread, rect

df = pd.DataFrame({
    "category": ["A", "B", "C"],
    "value": [10, 20, 30]
})

chart(df).flow(spread("category", dir="x")).mark(rect(h="value")).render()

Jupyter Notebooks

from gofish import chart, spread, rect, display_jupyter

node = chart(data).flow(spread("x", dir="x")).mark(rect(h="y"))
display_jupyter(node, w=500, h=300, axes=True)

API Reference

Core Functions

• chart(data, **options) - Create a new chart
• ChartBuilder.flow(*operators) - Add operators
• ChartBuilder.mark(mark) - Apply a mark
• GoFishNode.render(**options) - Render the chart

Operators

• spread(field, dir="x", ...) - Spread groups
• stack(field, dir="y", ...) - Stack groups
• scatter(field, x, y, ...) - Scatter plot positioning
• group(field) - Group by field
• derive(fn) - Transform data
• normalize(field) - Normalize values
• repeat(field) - Repeat items
• log(label) - Debug logging

Marks

• rect(w, h, fill, ...) - Rectangles
• circle(r, fill, ...) - Circles
• line(stroke, ...) - Lines
• area(stroke, opacity, ...) - Areas
• scaffold(w, h, ...) - Invisible guides
• select(layer_name) - Select from layer

Development

Setup with uv (Recommended)

# Clone repository
git clone <repo-url>
cd packages/gofish-python

# Install uv: https://github.com/astral-sh/uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install in development mode with all dependencies
uv sync

# This installs:
# - Package in editable mode
# - Dev dependencies (pytest, black, mypy)
# - Optional dependencies available via extras

Setup with pip (Alternative)

# Clone repository
git clone <repo-url>
cd packages/gofish-python

# Install in development mode
pip install -e ".[dev]"

# Install JavaScript bridge
pip install pythonmonkey

Building GoFish JS Bundle

The Python wrapper needs the compiled GoFish JavaScript bundle:

# In packages/gofish-graphics
pnpm install
pnpm build

Development Commands

# Run tests
uv run pytest
# or
make test

# Format code
uv run black gofish_python/

# Type checking
uv run mypy gofish_python/

# Build distribution
uv build
# or
make build

# Clean build artifacts
make clean

Publishing

See PUBLISHING.md for detailed publishing instructions.

Quick version:

# 1. Update version in pyproject.toml
# 2. Build
uv build
# or
make build

# 3. Publish to PyPI
uv publish
# or
make publish

# Or test on TestPyPI first
make testpypi

Limitations

1. JavaScript Bridge Required: You must install either pythonmonkey or jsbridge
2. JS Bundle Required: The GoFish JavaScript bundle must be available
3. DOM Environment: For interactive rendering, a DOM (browser/Jupyter) is needed
4. Performance: Python↔JavaScript interop has overhead; complex animations may be slower

Future Work

• Better DOM-less rendering (static SVG export)
• Improved error messages
• Type hints and type checking
• More comprehensive examples
• Event handling from Python
• Animation control from Python

License

MIT