plotly-print 0.2.2__tar.gz → 0.2.3__tar.gz

plotly_print-0.2.3/.cursor/rules/global.mdc

@@ -0,0 +1,52 @@
+---
+description: Coding standards for plotly-print (Python package + QuickJS micro-DOM)
+alwaysApply: true
+---
+
+# Project standards
+
+Python package + QuickJS micro-DOM under `src/plotly_print/js/`. Source of truth: `pyproject.toml` (Python >= 3.12, uv). Package layout and entry points: `.cursor/rules/map.mdc`.
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+## Before writing code
+
+Read the task and the code it touches, trace the real flow end to end, then stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse it.
+3. Does the standard library already do this? Use it.
+4. Does an already-declared dependency solve it? Use it.
+5. Can this be one boring line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Bug fix = root cause, not symptom. Grep every caller of the function you touch and fix the shared function once.
+
+## Toolchain
+
+- Do not add a dependency unless it is declared in `pyproject.toml` (or the lockfile). Prefer stdlib.
+- Ruff via `pyproject.toml`. After Python edits: `poe format`. After Markdown: `poe format_docs`.
+- No JS formatter/linter; match `micro_dom.js`. Never hand-edit vendored Plotly bundles.
+
+## Comments and docs
+
+- No docstrings except on base/abstract contracts and complex functions that need them.
+- No unnecessary comments; if needed, explain why, not what.
+- No section-divider comments in classes/functions (allowed in test classes). Group by proximity.
+
+## Language
+
+Shared: ASCII only in identifiers/comments/docs (no emojis). No unnecessary imports.
+
+Python: type-hint every function/method; f-strings; join with `/` on `Path` (avoid extra wrappers).
+
+## Quality
+
+- Deletion over addition. Boring over clever. Fewest files; shortest working diff after understanding the problem.
+- No unrequested abstractions, boilerplate, or dependencies. Question complex asks: does Y cover it?
+- Prefer the edge-case-correct stdlib approach when sizes match.
+- Deliberate ceilings: `ponytail:` comment naming the ceiling and upgrade path.
+- Non-trivial logic: one smallest test that fails if it breaks. Run `poe test` before claiming done.
+- No secrets, `.env`, or local virtualenvs in commits.
+
+Not lazy about: understanding the problem, trust-boundary validation, error handling that prevents data loss, security, anything explicitly requested.

{plotly_print-0.2.2 → plotly_print-0.2.3}/.cursor/rules/javascript.mdc

@@ -10,7 +10,8 @@ First-party runtime JS lives under `src/plotly_print/js/`. It runs inside QuickJ
 
 ## Do not edit
 
-- `plotly_comprehensive_2d.js` and any other vendored Plotly/plotly.js bundle. Treat as opaque third-party input.
+- `plotly_comprehensive_2d.js` (and any vendored Plotly bundle): opaque; in `.cursorignore`. Do not Read/Grep the whole file.
+- Need a call shape: Shell `rg -n 'pattern' src/plotly_print/js/plotly_comprehensive_2d.js | head` (cap hits). Never open whole-file.
 - Only change first-party files such as `micro_dom.js`.
 
 ## Style (match `micro_dom.js`)

plotly_print-0.2.3/.cursor/rules/map.mdc

@@ -0,0 +1,34 @@
+---
+description: Package map — start here; avoid re-exploring the tree
+alwaysApply: true
+---
+
+# Package map
+
+Browser-less Plotly static export: QuickJS + micro-DOM + vendored Plotly 2D → SVG → resvg raster.
+
+## Flow
+
+`core.to_svg` / `to_image` / `write_image` → `engine.PrintEngine` (QuickJS) → eval `micro_dom.js` + vendored Plotly → SVG → `raster.py` for png/jpeg/webp.
+
+`plotly_hook.register` patches Plotly `to_image` / `write_image`.
+
+## Files
+
+| Path | Job |
+|------|-----|
+| `core.py` | Public API; figure → JSON |
+| `engine.py` | QuickJS lifecycle; canvas→PNG; typed arrays |
+| `fonts.py` | Text metrics callable into JS |
+| `raster.py` | SVG → raster (resvg) |
+| `plotly_hook.py` | Monkeypatch Plotly |
+| `js/micro_dom.js` | First-party DOM/SVG stubs (**edit here**) |
+| `js/plotly_comprehensive_2d.js` | Vendored; **never** Read/Grep whole file (`.cursorignore`) |
+
+Start from this map. Open only listed files unless the task is outside `src/plotly_print/`.
+
+## Tests / commands / scratch
+
+- `tests/test_svg_*.py` → micro-DOM; chart `test_*.py` → render; `test_kaleido_*` → visual parity
+- `poe format` | `poe test` | `poe benchmark` | `poe format_docs`
+- Scratch under `.artifacts/` (gitignored); do not commit

plotly_print-0.2.3/.cursorignore

@@ -0,0 +1,2 @@
+# Vendored Plotly.js (~2MB). Never index or open whole-file; capped rg via Shell if needed.
+src/plotly_print/js/plotly_comprehensive_2d.js

plotly_print-0.2.3/AGENTS.md

@@ -0,0 +1,17 @@
+# Agent instructions
+
+plotly-print: Python package + QuickJS micro-DOM for browser-less Plotly static export.
+
+## Tooling
+
+- **All AI IDEs:** start from this file and the package map.
+- **Cursor:** rules in [`.cursor/rules/`](.cursor/rules/). Do not duplicate them here.
+
+## Standards (Cursor)
+
+- Map (always-on): `.cursor/rules/map.mdc`
+- Coding standards (always-on): `.cursor/rules/global.mdc`
+- JavaScript (`src/plotly_print/js/`): `.cursor/rules/javascript.mdc`
+- Markdown (`.md`): `.cursor/rules/markdown.mdc`
+
+Vendored Plotly bundle is listed in `.cursorignore` — do not open it whole-file.

{plotly_print-0.2.2 → plotly_print-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plotly-print
-Version: 0.2.2
+Version: 0.2.3
 Summary: Lightweight, browser-less static image exporter for Plotly
 Project-URL: Homepage, https://github.com/roman-kaczanowski/plotly-print
 Project-URL: Repository, https://github.com/roman-kaczanowski/plotly-print

{plotly_print-0.2.2 → plotly_print-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plotly-print"
-version = "0.2.2"
+version = "0.2.3"
 description = "Lightweight, browser-less static image exporter for Plotly"
 readme = "README.md"
 license = "MIT"

{plotly_print-0.2.2 → plotly_print-0.2.3}/src/plotly_print/engine.py

@@ -4,6 +4,7 @@ import base64
 import io
 import json
 import re
+import struct
 import threading
 from pathlib import Path
 from typing import Any
@@ -69,6 +70,69 @@ def _encode_canvas_to_png(width: int, height: int, commands_json: str) -> str:
     return f'data:image/png;base64,{b64}'
 
 
+# QuickJS throws on the out-of-bounds Uint8Array write plotly.js uses to drop
+# base64 padding when decoding {'dtype', 'bdata'}. Expand those specs to lists
+# before they reach the engine. Bytes are little-endian, matching the typed
+# arrays plotly.js builds on the hosts this package runs on.
+_TYPED_ARRAY_DTYPES = {
+    'i1': 'b',
+    'u1': 'B',
+    'i2': 'h',
+    'u2': 'H',
+    'i4': 'i',
+    'u4': 'I',
+    'f4': 'f',
+    'f8': 'd',
+}
+
+
+def _decode_typed_array(spec: dict[str, Any]) -> list[Any] | None:
+    dtype = spec.get('dtype')
+    bdata = spec.get('bdata')
+    if not isinstance(dtype, str) or not isinstance(bdata, str):
+        return None
+    code = _TYPED_ARRAY_DTYPES.get(dtype)
+    if code is None:
+        return None
+    shape = spec.get('shape')
+    if 'shape' in spec and not isinstance(shape, (str, int)):
+        return None
+
+    raw = base64.b64decode(bdata)
+    width = struct.calcsize(code)
+    if len(raw) % width:
+        raise ValueError(f'typed array byte length {len(raw)} is not a multiple of {width} for dtype {dtype}')
+    flat = list(struct.unpack(f'<{len(raw) // width}{code}', raw))
+    if shape is None:
+        return flat
+    dims = [int(part) for part in str(shape).split(',') if part.strip()]
+    return _reshape_row_major(flat, dims)
+
+
+def _reshape_row_major(flat: list[Any], dims: list[int]) -> list[Any]:
+    size = 1
+    for dim in dims:
+        size *= dim
+    if size != len(flat):
+        joined = ','.join(str(dim) for dim in dims)
+        raise ValueError(f'typed array shape {joined} does not match {len(flat)} values')
+    if len(dims) <= 1:
+        return flat
+    span = size // dims[0]
+    return [_reshape_row_major(flat[index * span : (index + 1) * span], dims[1:]) for index in range(dims[0])]
+
+
+def _expand_typed_arrays(value: Any) -> Any:
+    if isinstance(value, dict):
+        decoded = _decode_typed_array(value)
+        if decoded is not None:
+            return decoded
+        return {key: _expand_typed_arrays(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_expand_typed_arrays(item) for item in value]
+    return value
+
+
 class PrintEngine:
     def __init__(self) -> None:
         self.font_manager = get_default_font_manager()
@@ -155,8 +219,8 @@ class PrintEngine:
         if height is not None:
             layout_copy['height'] = height
 
-        data_json = json.dumps(data, cls=PlotlyJSONEncoder)
-        layout_json = json.dumps(layout_copy, cls=PlotlyJSONEncoder)
+        data_json = json.dumps(_expand_typed_arrays(data), cls=PlotlyJSONEncoder)
+        layout_json = json.dumps(_expand_typed_arrays(layout_copy), cls=PlotlyJSONEncoder)
 
         self.context.eval(f'var __plotly_print_data = {json.dumps(data_json)};')
         self.context.eval(f'var __plotly_print_layout = {json.dumps(layout_json)};')

{plotly_print-0.2.2 → plotly_print-0.2.3}/tests/test_json_types.py

@@ -2,6 +2,7 @@
 
 import datetime as dt
 import decimal
+import json
 
 import numpy as np
 import pandas as pd
@@ -9,6 +10,7 @@ import plotly.graph_objects as go
 import pytest
 
 import plotly_print
+from plotly_print.engine import _expand_typed_arrays
 
 
 @pytest.mark.parametrize(
@@ -135,6 +137,62 @@ def test_non_json_values_render(name, fig):
     assert png.startswith(b'\x89PNG')
 
 
+def test_typed_array_specs_expand_to_plain_values():
+    x = np.array([1.5, -2.25], dtype=np.float64)
+    y = np.array([-1, 2, 3, 4], dtype=np.int8)
+    color = np.array([0.25, 0.5], dtype=np.float32)
+    size = np.array([10, 20], dtype=np.uint16)
+    z = np.arange(4, dtype=np.float64).reshape(2, 2)
+    fig = go.Figure(
+        data=[
+            go.Scatter(x=x, y=y, marker={'color': color, 'size': size}),
+            go.Heatmap(z=z),
+        ]
+    )
+
+    expanded = _expand_typed_arrays(fig.to_dict())
+
+    assert expanded['data'][0]['x'] == x.tolist()
+    assert expanded['data'][0]['y'] == y.tolist()
+    assert expanded['data'][0]['marker']['color'] == color.tolist()
+    assert expanded['data'][0]['marker']['size'] == size.tolist()
+    assert expanded['data'][1]['z'] == z.tolist()
+
+
+@pytest.mark.parametrize('source', ['figure', 'to_dict', 'json'])
+def test_padded_numpy_bdata_renders(source):
+    # 22 float64 values are 176 bytes, which is not a multiple of 3, so the
+    # base64 payload has padding that used to crash QuickJS.
+    values = np.arange(22, dtype=float)
+    fig = go.Figure(
+        data=[go.Scatter(x=values, y=values, mode='lines+markers')],
+        layout=go.Layout(width=400, height=300, title='Bdata'),
+    )
+    if source == 'to_dict':
+        fig = fig.to_dict()
+    elif source == 'json':
+        fig = json.loads(fig.to_json())
+
+    svg = plotly_print.to_svg(fig)
+    assert '<svg' in svg
+    assert 'Bdata' in svg
+    assert 'class="point"' in svg
+
+
+def test_padded_pandas_and_heatmap_render():
+    series = pd.Series(np.arange(22, dtype=float))
+    figures = [
+        go.Figure(data=[go.Scatter(x=series, y=series**2)], layout=go.Layout(width=400, height=300)),
+        go.Figure(
+            data=[go.Heatmap(z=np.arange(4, dtype=float).reshape(2, 2))], layout=go.Layout(width=400, height=300)
+        ),
+        go.Figure(data=[go.Bar(y=np.array([1, 2], dtype=np.int16))], layout=go.Layout(width=400, height=300)),
+    ]
+    for fig in figures:
+        svg = plotly_print.to_svg(fig)
+        assert '<svg' in svg
+
+
 def test_hooked_to_image_with_decimal_values():
     plotly_print.register()
 

{plotly_print-0.2.2 → plotly_print-0.2.3}/uv.lock

@@ -536,7 +536,7 @@ wheels = [
 
 [[package]]
 name = "plotly-print"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "pillow" },

plotly_print-0.2.2/.cursor/rules/artifacts.mdc

@@ -1,14 +0,0 @@
----
-description: Gitignored local output directory for agents
-alwaysApply: true
----
-
-# `.artifacts/`
-
-The repo root `.artifacts/` directory is **gitignored**. Use it for:
-
-- LLM research notes, comparison reports, scratch exports, and other **temporary local artifacts**
-
-Do not commit files under `.artifacts/`. Nothing there is shipped on PyPI or in the wheel.
-
-When generating research or large binary outputs for the user to review (outside the benchmark), prefer paths under `.artifacts/` unless they ask for another location.

plotly_print-0.2.2/.cursor/rules/global.mdc

@@ -1,72 +0,0 @@
----
-description: Coding standards for plotly-print (Python package + QuickJS micro-DOM)
-alwaysApply: true
----
-
-# Project standards
-
-plotly-print is a Python package (cookiecutter-python-seed layout) plus first-party QuickJS JavaScript under `src/plotly_print/js/` (micro-DOM for static Plotly rendering). Treat `pyproject.toml` as the source of truth for toolchain, Python version, and dependencies. Minimum Python version is 3.12. Use uv to lock, sync, build, and bump versions.
-
-JS-specific conventions: `.cursor/rules/javascript.mdc` (applies under `src/plotly_print/js/`).
-
-You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
-
-## Before writing code
-
-Read the task and the code it touches, trace the real flow end to end, then stop at the first rung that holds:
-
-1. Does this need to be built at all? (YAGNI)
-2. Does it already exist in this codebase? Reuse it.
-3. Does the standard library already do this? Use it.
-4. Does an already-declared dependency solve it? Use it.
-5. Can this be one boring line? Make it one line.
-6. Only then: write the minimum code that works.
-
-Bug fix = root cause, not symptom. Grep every caller of the function you touch and fix the shared function once.
-
-## Toolchain
-
-- Match existing layout: `src/` for packages, `tests/` for tests, application entry points as already configured.
-- Do not add a dependency unless it is declared in `pyproject.toml` (or the project's lockfile). Prefer stdlib over a new package.
-- Python style is enforced by Ruff. Follow `pyproject.toml`; the points below are the ones to apply consistently even when Ruff cannot.
-- After editing Python files, run `poe format`.
-- After editing Markdown files, run `poe format_docs`.
-- There is no JS formatter/linter task; match `micro_dom.js` style. Do not hand-edit vendored Plotly bundles.
-
-## Comments and docs
-
-- No docstrings except on base/abstract classes and methods (the contract for implementors) and on complex functions where extra explanation genuinely helps.
-- No unnecessary comments. Code should be self-explanatory. If a comment is needed, explain why, not what.
-- No section-divider comments inside classes or functions. Group related methods by proximity. Dividers are allowed only in test classes.
-
-## Language
-
-Shared (Python and JS):
-
-- ASCII only in identifiers, comments, and docs. No emojis. Non-ASCII letters are allowed only when the content is actually in another language (e.g. Polish, Russian).
-- No unnecessary imports.
-
-Python:
-
-- Type-hint every function and method. Do not nest annotations so deeply that they hurt readability.
-- Use f-strings for all string formatting.
-- Avoid unnecessary `Path` wrappers; join with `/` on `Path` objects.
-
-## Quality
-
-- Use `poe format` / `poe format_docs` instead of hand-formatting style (Python/Markdown).
-- Deletion over addition. Boring over clever. Fewest files possible. Shortest working diff wins, after you understand the problem.
-- No abstractions, boilerplate, or dependencies that weren't requested.
-- Question complex requests: "Do you actually need X, or does Y cover it?"
-- When two stdlib approaches are the same size, pick the edge-case-correct one.
-- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n^2) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
-- Non-trivial logic leaves one runnable check: the smallest test that fails if the logic breaks. Trivial one-liners need no new test. Run the project's test command before claiming work is done.
-- Do not commit secrets, `.env` files, or local virtualenvs.
-
-Not lazy about: understanding the problem, input validation at trust boundaries, error handling that prevents data loss, security, anything explicitly requested.
-
-## Agents
-
-- Keep this file for conventions that should always apply.
-- Put path-specific Cursor rules in additional `.mdc` files in this directory.
-- Keep `AGENTS.md` as a short index that points here.

plotly_print-0.2.2/AGENTS.md

@@ -1,15 +0,0 @@
-# Agent instructions
-
-This project was generated from **cookiecutter-python-seed**, with first-party QuickJS JavaScript for Plotly static rendering.
-
-## Tooling
-
-- **All AI IDEs:** follow this file.
-- **Cursor:** project rules live in [`.cursor/rules/`](.cursor/rules/). This file is the index; do not duplicate those rules here.
-
-## Standards
-
-- Always-on: `.cursor/rules/global.mdc`
-- JavaScript (`src/plotly_print/js/`): `.cursor/rules/javascript.mdc`
-- Markdown (`.md` files): `.cursor/rules/markdown.mdc`
-- Local scratch output: `.cursor/rules/artifacts.mdc`