This release is a pre-release and may not be stable for production use.
gofish-python
A Python wrapper for the GoFish graphics library. Both the mid-level chart API and the low-level mark/operator API are supported. (See notes/design.md and notes/implementation.md for more details.)
Installation
pip install --pre gofish-graphics
The latest stable release on PyPI is old and lags far behind development. The docs at
gofish.graphics describe the current dev
builds, which are published on every change to main. You must include the --pre
flag, otherwise pip installs the outdated stable release.
The package is imported as gofish:
from gofish import chart
See the getting started docs for a full introduction.
Usage
from gofish import chart, spread, stack, rect
# Create a chart specification
data = [{"lake": "A", "species": "B", "count": 10}]
c = (
chart(data, axes=True)
.flow(
spread("lake", dir="x", spacing=64),
stack("species", dir="y", spacing=0),
)
.mark(rect(h="count", fill="species"))
)
# Convert to JSON IR
ir = c.to_ir()
print(ir)
# {
# "data": None,
# "operators": [
# {"type": "spread", "field": "lake", "dir": "x", "spacing": 64},
# {"type": "stack", "field": "species", "dir": "y", "spacing": 0}
# ],
# "mark": {"type": "rect", "h": "count", "fill": "species"},
# "options": {"axes": True}
# }
IR Format
The JSON IR has the following structure:
{
"data": null,
"operators": [
{ "type": "spread", "field": "lake", "dir": "x", "spacing": 8 },
{ "type": "derive", "lambdaId": "uuid-here" },
{ "type": "stack", "field": "species", "dir": "y" }
],
"mark": { "type": "rect", "h": "count", "fill": "species" },
"options": {}
}
Development
Note: This package uses uv for fast package management and testing.
Prerequisites
- Python 3.10+
- uv - Fast Python package manager
- Node.js (for building the widget bundle)
- pnpm (for managing Node.js dependencies)
Development Install
cd packages/gofish-python
uv pip install -e .
Installing Node.js Dependencies
If you need to build the widget bundle, install Node.js dependencies:
pnpm install
Building the Widget Bundle
The widget bundle is a self-contained JavaScript module that includes all dependencies. Build it with:
# From the package directory
pnpm run build:widget
# Or directly with Node.js
node build-widget.mjs
This will:
- Bundle the TypeScript widget source (
widget-src/index.ts) - Include all dependencies (gofish-graphics, solid-js, apache-arrow)
- Output to
gofish/_static/widget.esm.js
Note: The build process will automatically use gofish-graphics/dist/index.js if available, otherwise it falls back to the package import. Make sure gofish-graphics is built first if you're developing locally.
Running Tests
Python Unit Tests
# Install with test dependencies
uv pip install -e ".[test]"
# Run all tests
uv run pytest
# Or run directly if installed
pytest
# Run specific test file
pytest tests/test_ast.py
# Run with verbose output
pytest -v
Jupyter Notebook Tests
The package includes Jupyter notebooks for interactive testing:
tests/test_ir.ipynb- Tests for IR generationtests/test_rendering.ipynb- Tests for widget rendering
To run these:
# Start Jupyter
jupyter notebook
# Or use the provided script (if available)
./run_notebook.sh
Development Workflow
-
Install dependencies:
uv pip install -e ".[test]" pnpm install
-
Make changes to Python code or widget TypeScript source
-
Build widget (if you modified widget code):
pnpm run build:widget
-
Run tests:
pytest
-
Test in Jupyter (optional):
jupyter notebook tests/test_rendering.ipynb
1 maintainer
Metadata
1 maintainer
Release files for gofish-graphics 0.1.1.dev20261005
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gofish_graphics-0.1.1.dev20261005.tar.gz | 1.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gofish_graphics-0.1.1.dev20261005-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.4 MB
Release files / gofish_graphics-0.1.1.dev20261005.tar.gz
| Download URL | gofish_graphics-0.1.1.dev20261005.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b63fd365e68b200cda9d1b4854011d5ec7a9377aaddaeb81c8976bfb3303eda3
|
|
BLAKE2b-256 checksum How to use checksums |
4d8a7f518e571d008b192d7263d54017c6f5f53525bda063f82847c2051f81da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logRelease files / gofish_graphics-0.1.1.dev20261005-py3-none-any.whl
| Download URL | gofish_graphics-0.1.1.dev20261005-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d87af68cc552175446bb7d15fc212c8d018685dc1a2b0a77b6309f4d134895b6
|
|
BLAKE2b-256 checksum How to use checksums |
6534a1afdc5de46487d08104f8f99f1fa8e266869839c0ee3ad181aca7cddb38
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency log
