plotlet 0.5.0__tar.gz → 0.6.4__tar.gz

plotlet-0.6.4/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: plotlet
+Version: 0.6.4
+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, built for AI authorship: figures are written, inspected, and verified as data, not pixels. Byte-identical output across machines, a standard plotting vocabulary, built-in Cartesian and circular coordinate systems, and an easy way to add your own plot types.
+
+## Documentation
+
+Online documentation is available at [gitbamboo42.github.io/plotlet](https://gitbamboo42.github.io/plotlet/).
+
+The docs include a [tutorial](https://gitbamboo42.github.io/plotlet/tutorial.html), a [plot-type reference](https://gitbamboo42.github.io/plotlet/reference.html), a [cookbook](https://gitbamboo42.github.io/plotlet/cookbook.html), an [extensions gallery](https://gitbamboo42.github.io/plotlet/extensions.html), [deep-dive guides](https://gitbamboo42.github.io/plotlet/docs-api.html), and a [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html).
+
+## Dependencies
+
+plotlet supports Python 3.10+.
+
+Required: `fonttools`, `scipy`, `resvg_py`. numpy / pandas / polars inputs work transparently.
+
+Optional: `cairosvg` for PDF export (`pip install plotlet[pdf]`).
+
+## Installation
+
+```bash
+pip install plotlet
+```
+
+## For AI assistants
+
+Tell your assistant to run plotlet's `skill()` and follow it. The guides, docs, and worked examples ship inside the installed package; the [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html) shows the full workflow.
+
+## Development
+
+Development takes place on GitHub. Please submit bugs to the issue tracker with a reproducible example.
+
+## License
+
+MIT

plotlet-0.6.4/README.md

@@ -0,0 +1,35 @@
+# plotlet
+
+plotlet is a Python library for reproducible, multi-panel scientific figures, built for AI authorship: figures are written, inspected, and verified as data, not pixels. Byte-identical output across machines, a standard plotting vocabulary, built-in Cartesian and circular coordinate systems, and an easy way to add your own plot types.
+
+## Documentation
+
+Online documentation is available at [gitbamboo42.github.io/plotlet](https://gitbamboo42.github.io/plotlet/).
+
+The docs include a [tutorial](https://gitbamboo42.github.io/plotlet/tutorial.html), a [plot-type reference](https://gitbamboo42.github.io/plotlet/reference.html), a [cookbook](https://gitbamboo42.github.io/plotlet/cookbook.html), an [extensions gallery](https://gitbamboo42.github.io/plotlet/extensions.html), [deep-dive guides](https://gitbamboo42.github.io/plotlet/docs-api.html), and a [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html).
+
+## Dependencies
+
+plotlet supports Python 3.10+.
+
+Required: `fonttools`, `scipy`, `resvg_py`. numpy / pandas / polars inputs work transparently.
+
+Optional: `cairosvg` for PDF export (`pip install plotlet[pdf]`).
+
+## Installation
+
+```bash
+pip install plotlet
+```
+
+## For AI assistants
+
+Tell your assistant to run plotlet's `skill()` and follow it. The guides, docs, and worked examples ship inside the installed package; the [page for AI agents](https://gitbamboo42.github.io/plotlet/agents.html) shows the full workflow.
+
+## Development
+
+Development takes place on GitHub. Please submit bugs to the issue tracker with a reproducible example.
+
+## License
+
+MIT

{plotlet-0.5.0 → plotlet-0.6.4}/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.5.0"
-description = "Python library for SVG plots, with multi-panel composition and an extension API for custom plot types."
+version = "0.6.4"
+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"]
@@ -30,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]
@@ -45,6 +47,10 @@ dev = [
 ]
 test = [
   "pytest>=7",
+  "pandas",
+]
+pdf = [
+  "cairosvg",
 ]
 
 [tool.pytest.ini_options]
@@ -58,6 +64,14 @@ Issues = "https://github.com/gitbamboo42/plotlet/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+namespaces = true
 
 [tool.setuptools.package-data]
-plotlet = ["spec.json", "themes/*.json", "draw/fonts/*.ttf", "_datasets/*.csv"]
+# 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", "_datasets/*.npz",
+           # AI onboarding: pt.skill() reads skills/, and the guides point
+           # at the shipped docs/ and examples/ so an installed package is
+           # self-sufficient — no repo clone, no web access needed.
+           "skills/*.md", "docs/*.md", "examples/*.py"]

plotlet-0.6.4/src/plotlet/__init__.py

@@ -0,0 +1,76 @@
+"""plotlet — pure-Python deferred-rendering SVG plot library.
+
+    import plotlet as pt
+    from plotlet import aes
+
+    c = pt.chart(df, title="...", xlabel="x", ylabel="y", legend=True, gridlines=True)
+    c.add_line(aes(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.add_line(df, aes(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 .record.chart import Chart, Layout, chart, grid
+from .utils import aes
+from .record.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 .record.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 .record.journal import (to_journal, from_journal, to_json, from_json,
+                       JournalNode, Journal)
+from .record.figure_ir import to_ir, from_ir, FigureIR, IRNode
+from .skill import skill
+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._coord_circular 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",
+           "skill",
+           "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.4/src/plotlet/_coord_registry.py

@@ -0,0 +1,55 @@
+"""Coord codec registry — the `class_name → class` map behind
+`{"$coord": ...}` envelopes, for coord objects like
+`CircularCoordinate`.
+
+`record/journal.py` encodes a coord object to its class name;
+`_json_layer._decode` turns the name back into the class via
+`resolve_coord`, which imports the built-in coord module on the first
+miss so cold processes decode without a prior render. The render half
+reads the map too (`render/_validate.py` cross-checks the `container`
+flag, `render/resolved_ir.py` rehydrates coords), so the registry sits
+at the package root, where `record/` and `render/` may both import it.
+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 _coord_circular  # 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.4/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.4/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