plotlet 0.4.0__tar.gz → 0.6.0__tar.gz

plotlet-0.6.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: plotlet
+Version: 0.6.0
+Summary: Python library for reproducible, multi-panel scientific figures, with byte-identical output across machines and an extension API for custom plot types.
+Author: gitbamboo42
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gitbamboo42/plotlet
+Project-URL: Repository, https://github.com/gitbamboo42/plotlet
+Project-URL: Issues, https://github.com/gitbamboo42/plotlet/issues
+Keywords: plot,svg,scientific,visualization,jupyter,reproducible
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fonttools>=4.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: resvg_py>=0.3
+Provides-Extra: dev
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pandas; extra == "test"
+Provides-Extra: pdf
+Requires-Dist: cairosvg; extra == "pdf"
+Dynamic: license-file
+
+# plotlet
+
+plotlet is a Python library for reproducible, multi-panel scientific figures. Byte-identical output across machines, a standard plotting vocabulary, and a first-class extension story for custom plot types.
+
+## Documentation
+
+Hands-on tour with executable examples:
+
+- [notebooks/00_introduction.ipynb](notebooks/00_introduction.ipynb) — long-form data, aesthetic inheritance, layering, composition (more topic notebooks in [`notebooks/`](notebooks/))
+
+Reference docs in [`docs/`](docs/):
+
+- [API reference](docs/API.md) — mark methods, frame options, scales, tick overrides
+- [Philosophy](docs/PHILOSOPHY.md) — what's in core, what's not, and why
+- [Subplots](docs/SUBPLOTS.md) — multi-panel composition, shared scales
+- [Coordinates](docs/COORDINATES.md) — Circular, custom non-Cartesian projections
+- [Extending](docs/EXTENDING.md) — write your own plot type
+- [Themes](docs/THEMES.md) — visual presets
+- [AI attributes](docs/AI_ATTRS.md) — `data-plotlet-*` schema for automation
+
+Reference plot types beyond the standard vocabulary ship in the separate [`plotlet-extensions`](https://github.com/gitbamboo42/plotlet-extensions) package (single-file artists — sankey, alluvial, raincloud, upset_plot, …; `pip install plotlet-extensions`, then `import plotlet.extensions.<name>`) and in the [`plotlet-cookbook`](https://github.com/gitbamboo42/plotlet-cookbook) repo (multi-file, domain-specific projects). A few extensions the core tests depend on still ship in core under [`src/plotlet/extensions/`](src/plotlet/extensions/).
+
+## For AI assistants
+
+Compact, vendor-neutral onboarding docs live in [`skills/`](skills/):
+
+- [`skills/users.md`](skills/users.md) — for AI tools generating plotlet code on a user's behalf.
+- [`skills/developers.md`](skills/developers.md) — for AI (or human) contributors working on plotlet itself. Symlink as `CLAUDE.md` / `.cursorrules` / `AGENTS.md` as your tool expects.
+
+## Dependencies
+
+plotlet supports Python 3.10+.
+
+Required: `fonttools`, `scipy` (regression, qq, CI error bands, clustering/dendrogram), `resvg_py` (PNG rendering — prebuilt wheels, no system libraries). numpy / pandas / polars inputs work transparently.
+
+Optional: `cairosvg` for PDF export (`pip install plotlet[pdf]`).
+
+## Installation
+
+```bash
+pip install plotlet
+```
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest tests/                  # check vs. committed baselines
+pytest tests/ --update         # regenerate (review the diff!)
+```
+
+## Development
+
+Development takes place on GitHub. Please submit bugs to the issue tracker with a reproducible example.
+
+## License
+
+MIT

plotlet-0.6.0/README.md

@@ -0,0 +1,58 @@
+# plotlet
+
+plotlet is a Python library for reproducible, multi-panel scientific figures. Byte-identical output across machines, a standard plotting vocabulary, and a first-class extension story for custom plot types.
+
+## Documentation
+
+Hands-on tour with executable examples:
+
+- [notebooks/00_introduction.ipynb](notebooks/00_introduction.ipynb) — long-form data, aesthetic inheritance, layering, composition (more topic notebooks in [`notebooks/`](notebooks/))
+
+Reference docs in [`docs/`](docs/):
+
+- [API reference](docs/API.md) — mark methods, frame options, scales, tick overrides
+- [Philosophy](docs/PHILOSOPHY.md) — what's in core, what's not, and why
+- [Subplots](docs/SUBPLOTS.md) — multi-panel composition, shared scales
+- [Coordinates](docs/COORDINATES.md) — Circular, custom non-Cartesian projections
+- [Extending](docs/EXTENDING.md) — write your own plot type
+- [Themes](docs/THEMES.md) — visual presets
+- [AI attributes](docs/AI_ATTRS.md) — `data-plotlet-*` schema for automation
+
+Reference plot types beyond the standard vocabulary ship in the separate [`plotlet-extensions`](https://github.com/gitbamboo42/plotlet-extensions) package (single-file artists — sankey, alluvial, raincloud, upset_plot, …; `pip install plotlet-extensions`, then `import plotlet.extensions.<name>`) and in the [`plotlet-cookbook`](https://github.com/gitbamboo42/plotlet-cookbook) repo (multi-file, domain-specific projects). A few extensions the core tests depend on still ship in core under [`src/plotlet/extensions/`](src/plotlet/extensions/).
+
+## For AI assistants
+
+Compact, vendor-neutral onboarding docs live in [`skills/`](skills/):
+
+- [`skills/users.md`](skills/users.md) — for AI tools generating plotlet code on a user's behalf.
+- [`skills/developers.md`](skills/developers.md) — for AI (or human) contributors working on plotlet itself. Symlink as `CLAUDE.md` / `.cursorrules` / `AGENTS.md` as your tool expects.
+
+## Dependencies
+
+plotlet supports Python 3.10+.
+
+Required: `fonttools`, `scipy` (regression, qq, CI error bands, clustering/dendrogram), `resvg_py` (PNG rendering — prebuilt wheels, no system libraries). numpy / pandas / polars inputs work transparently.
+
+Optional: `cairosvg` for PDF export (`pip install plotlet[pdf]`).
+
+## Installation
+
+```bash
+pip install plotlet
+```
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest tests/                  # check vs. committed baselines
+pytest tests/ --update         # regenerate (review the diff!)
+```
+
+## Development
+
+Development takes place on GitHub. Please submit bugs to the issue tracker with a reproducible example.
+
+## License
+
+MIT

{plotlet-0.4.0 → plotlet-0.6.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [build-system]
-requires = ["setuptools>=64", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "plotlet"
-version = "0.4.0"
-description = "Python library for SVG plots, with multi-panel composition and an extension API for custom plot types."
+version = "0.6.0"
+description = "Python library for reproducible, multi-panel scientific figures, with byte-identical output across machines and an extension API for custom plot types."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -16,7 +16,6 @@ authors = [
 keywords = [
     "plot",
     "svg",
-    "matplotlib",
     "scientific",
     "visualization",
     "jupyter",
@@ -31,12 +30,14 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Visualization",
     "Topic :: Multimedia :: Graphics",
 ]
 dependencies = [
   "fonttools>=4.0",
   "scipy>=1.10",
+  "resvg_py>=0.3",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +45,17 @@ dev = [
   "jupyter",
   "nbconvert",
 ]
+test = [
+  "pytest>=7",
+  "pandas",
+]
+pdf = [
+  "cairosvg",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
 
 [project.urls]
 Homepage = "https://github.com/gitbamboo42/plotlet"
@@ -52,6 +64,10 @@ Issues = "https://github.com/gitbamboo42/plotlet/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+namespaces = true
 
 [tool.setuptools.package-data]
-plotlet = ["spec.json", "fonts/*.ttf"]
+# draw/fonts/*.txt are the font licenses — DejaVu (Bitstream Vera–derived)
+# and Arimo (SIL OFL 1.1) both require the license text to accompany
+# redistribution, so they must ship in the wheel next to the TTFs.
+plotlet = ["spec.json", "themes/*.json", "draw/fonts/*.ttf", "draw/fonts/*.txt", "_datasets/*.csv"]

plotlet-0.6.0/src/plotlet/__init__.py

@@ -0,0 +1,71 @@
+"""plotlet — pure-Python deferred-rendering SVG plot library.
+
+    import plotlet as pt
+    c = pt.chart(df, title="...", xlabel="x", ylabel="y", legend=True, gridlines=True)
+    c.line(x="time", y="value", color="series")
+    c                         # auto-renders in Jupyter
+
+Chart methods chain for incremental composition:
+
+    df = {"x": [1, 2, 3], "y": [1, 4, 9]}
+    c = pt.chart()
+    c.line(df, x="x", y="y", label="squares")
+    c.title("Hello").legend().gridlines(True)
+    c
+"""
+from ._spec import SPEC
+from .draw import TAB10, palette, list_palettes
+from .draw import colormap, list_colormaps, register_colormap
+from . import artists  # noqa: F401  — registers built-in artists on import
+from .chart import Chart, Layout, chart, grid
+from .legend import legend
+from .registry import ArtistSpec, add_artist, artist_table, declare_coord_support
+from .sectors import Sectors
+from .layout_diagram import layout_diagram
+from .themes import load_theme, list_themes, register_theme
+from .facet import facet, FacetGrid
+from .datasets import load_dataset, list_datasets
+from .cluster import linkage, linkage_split, SplitTree
+from .formatters import (register_formatter, list_formatters,
+                         superscript, subscript)
+from ._coord_registry import register_coord_codec
+from ._journal import (to_journal, from_journal, to_json, from_json,
+                       JournalNode, Journal)
+from ._ir import to_ir, from_ir, resolve_ir, FigureIR, IRNode
+from . import draw, utils
+
+
+def __getattr__(name):
+    # The one render-half class in the top-level namespace stays a lazy
+    # import so that `import plotlet` loads only the recording half —
+    # the render half loads on first render (or first touch of this
+    # name). Enforced by tests/test_import_boundary.py.
+    if name == "CircularCoordinate":
+        from .render.coordinates import CircularCoordinate
+        return CircularCoordinate
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = ["chart", "Chart", "Layout", "SPEC", "TAB10",
+           "palette", "list_palettes",
+           "colormap", "list_colormaps", "register_colormap",
+           "grid", "legend",
+           "ArtistSpec", "add_artist", "artist_table", "declare_coord_support",
+           "CircularCoordinate", "Sectors",
+           "layout_diagram",
+           "load_theme", "list_themes", "register_theme",
+           "facet", "FacetGrid",
+           "load_dataset", "list_datasets",
+           "linkage", "linkage_split", "SplitTree",
+           "register_formatter", "list_formatters",
+           "superscript", "subscript",
+           "to_json", "from_json", "register_coord_codec",
+           "to_journal", "from_journal", "JournalNode", "Journal",
+           "to_ir", "from_ir", "FigureIR", "IRNode", "resolve_ir",
+           "draw", "utils"]
+
+# Single source of truth: pyproject.toml. importlib.metadata reads it at
+# runtime from the installed package metadata (works for `pip install` and
+# `pip install -e .` alike). Migrating to setuptools_scm later doesn't
+# touch this code — it just changes how pyproject.toml's version is set.
+from importlib.metadata import version as _pkg_version
+__version__ = _pkg_version("plotlet")

plotlet-0.6.0/src/plotlet/_coord_registry.py

@@ -0,0 +1,50 @@
+"""Coord codec registry — a neutral home for the `class_name → class` map
+that both `serialize.py` and `_journal.py` need for round-tripping coord
+objects like `CircularCoordinate`.
+
+Lives here rather than in either consumer so that removing one of them
+later (e.g. retiring the JSON tree serializer once the journal covers
+the same ground) doesn't leave the registry orphaned. The public API
+`plotlet.register_coord_codec` re-exports from this module directly.
+"""
+from __future__ import annotations
+
+
+# Populated by `register_coord_codec`; coord classes register themselves
+# at their definition site (or serialize.py registers built-ins on module
+# import, for the ones that ship with plotlet).
+_COORD_REGISTRY: dict[str, type] = {}
+
+
+def register_coord_codec(cls: type) -> type:
+    """Register `cls` as a serializable coord. The class must define
+    `_to_dict(self) -> dict` and `_from_dict(cls, dict) -> cls`. Returns
+    `cls` so this can be used as a decorator."""
+    if not hasattr(cls, "_to_dict") or not hasattr(cls, "_from_dict"):
+        raise TypeError(
+            f"register_coord_codec: {cls.__name__} must define "
+            f"`_to_dict` and `_from_dict`."
+        )
+    _COORD_REGISTRY[cls.__name__] = cls
+    return cls
+
+
+def resolve_coord(name: str) -> type:
+    """Look up a coord class by registered name, importing the built-in
+    coord module on first miss — built-ins register at their definition
+    site, and nothing else guarantees that module has been imported when
+    a `{"$coord": ...}` envelope arrives from JSON in a fresh process."""
+    try:
+        return _COORD_REGISTRY[name]
+    except KeyError:
+        pass
+    from .render import coordinates  # noqa: F401 — registers built-ins
+    try:
+        return _COORD_REGISTRY[name]
+    except KeyError:
+        raise KeyError(
+            f"unknown coordinate {name!r}. Registered coords: "
+            f"{sorted(_COORD_REGISTRY)}. Custom coord classes must be "
+            f"imported (and registered via `register_coord_codec`) before "
+            f"a figure referencing them is decoded."
+        ) from None

plotlet-0.6.0/src/plotlet/_datasets/anscombe.csv

@@ -0,0 +1,45 @@
+dataset,x,y
+I,10.0,8.04
+I,8.0,6.95
+I,13.0,7.58
+I,9.0,8.81
+I,11.0,8.33
+I,14.0,9.96
+I,6.0,7.24
+I,4.0,4.26
+I,12.0,10.84
+I,7.0,4.82
+I,5.0,5.68
+II,10.0,9.14
+II,8.0,8.14
+II,13.0,8.74
+II,9.0,8.77
+II,11.0,9.26
+II,14.0,8.1
+II,6.0,6.13
+II,4.0,3.1
+II,12.0,9.13
+II,7.0,7.26
+II,5.0,4.74
+III,10.0,7.46
+III,8.0,6.77
+III,13.0,12.74
+III,9.0,7.11
+III,11.0,7.81
+III,14.0,8.84
+III,6.0,6.08
+III,4.0,5.39
+III,12.0,8.15
+III,7.0,6.42
+III,5.0,5.73
+IV,8.0,6.58
+IV,8.0,5.76
+IV,8.0,7.71
+IV,8.0,8.84
+IV,8.0,8.47
+IV,8.0,7.04
+IV,8.0,5.25
+IV,19.0,12.5
+IV,8.0,5.56
+IV,8.0,7.91
+IV,8.0,6.89

plotlet-0.6.0/src/plotlet/_datasets/flights.csv

@@ -0,0 +1,145 @@
+year,month,passengers
+1949,January,112
+1949,February,118
+1949,March,132
+1949,April,129
+1949,May,121
+1949,June,135
+1949,July,148
+1949,August,148
+1949,September,136
+1949,October,119
+1949,November,104
+1949,December,118
+1950,January,115
+1950,February,126
+1950,March,141
+1950,April,135
+1950,May,125
+1950,June,149
+1950,July,170
+1950,August,170
+1950,September,158
+1950,October,133
+1950,November,114
+1950,December,140
+1951,January,145
+1951,February,150
+1951,March,178
+1951,April,163
+1951,May,172
+1951,June,178
+1951,July,199
+1951,August,199
+1951,September,184
+1951,October,162
+1951,November,146
+1951,December,166
+1952,January,171
+1952,February,180
+1952,March,193
+1952,April,181
+1952,May,183
+1952,June,218
+1952,July,230
+1952,August,242
+1952,September,209
+1952,October,191
+1952,November,172
+1952,December,194
+1953,January,196
+1953,February,196
+1953,March,236
+1953,April,235
+1953,May,229
+1953,June,243
+1953,July,264
+1953,August,272
+1953,September,237
+1953,October,211
+1953,November,180
+1953,December,201
+1954,January,204
+1954,February,188
+1954,March,235
+1954,April,227
+1954,May,234
+1954,June,264
+1954,July,302
+1954,August,293
+1954,September,259
+1954,October,229
+1954,November,203
+1954,December,229
+1955,January,242
+1955,February,233
+1955,March,267
+1955,April,269
+1955,May,270
+1955,June,315
+1955,July,364
+1955,August,347
+1955,September,312
+1955,October,274
+1955,November,237
+1955,December,278
+1956,January,284
+1956,February,277
+1956,March,317
+1956,April,313
+1956,May,318
+1956,June,374
+1956,July,413
+1956,August,405
+1956,September,355
+1956,October,306
+1956,November,271
+1956,December,306
+1957,January,315
+1957,February,301
+1957,March,356
+1957,April,348
+1957,May,355
+1957,June,422
+1957,July,465
+1957,August,467
+1957,September,404
+1957,October,347
+1957,November,305
+1957,December,336
+1958,January,340
+1958,February,318
+1958,March,362
+1958,April,348
+1958,May,363
+1958,June,435
+1958,July,491
+1958,August,505
+1958,September,404
+1958,October,359
+1958,November,310
+1958,December,337
+1959,January,360
+1959,February,342
+1959,March,406
+1959,April,396
+1959,May,420
+1959,June,472
+1959,July,548
+1959,August,559
+1959,September,463
+1959,October,407
+1959,November,362
+1959,December,405
+1960,January,417
+1960,February,391
+1960,March,419
+1960,April,461
+1960,May,472
+1960,June,535
+1960,July,622
+1960,August,606
+1960,September,508
+1960,October,461
+1960,November,390
+1960,December,432