pyobservablejs 0.0.1__tar.gz → 0.0.2__tar.gz

pyobservablejs-0.0.2/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: pyobservablejs
+Version: 0.0.2
+Summary: Observable JavaScript notebooks as reusable Python widgets
+Project-URL: Homepage, https://github.com/peter-gy/pyobservablejs
+Project-URL: Documentation, https://peter-gy.github.io/pyobservablejs/
+Project-URL: Source, https://github.com/peter-gy/pyobservablejs
+Project-URL: Issues, https://github.com/peter-gy/pyobservablejs/issues
+Author-email: Peter Ferenc Gyarmati <dev.petergy@gmail.com>
+Maintainer-email: Peter Ferenc Gyarmati <dev.petergy@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: anywidget,jupyter,marimo,notebooks,observable,visualization
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: anywidget-bundle==0.0.1
+Requires-Dist: anywidget>=0.11.0
+Requires-Dist: traitlets>=5
+Description-Content-Type: text/markdown
+
+# pyobservablejs
+
+[![CI](https://github.com/peter-gy/pyobservablejs/actions/workflows/ci.yml/badge.svg)](https://github.com/peter-gy/pyobservablejs/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyobservablejs.svg)](https://pypi.org/project/pyobservablejs/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyobservablejs.svg)](https://pypi.org/project/pyobservablejs/)
+[![License](https://img.shields.io/pypi/l/pyobservablejs.svg)](https://github.com/peter-gy/pyobservablejs/blob/main/LICENSE)
+
+`pyobservablejs` brings interactive Observable notebooks into Python workflows.
+Author a notebook in Python or load an existing one, render the views you need,
+and keep its controls and results connected to your Python code.
+
+Use it in JupyterLab, marimo, VS Code notebooks, Google Colab, and other
+environments that support [anywidget](https://anywidget.dev/).
+
+## Quick start
+
+Python 3.11 or newer is required.
+
+```sh
+uv add pyobservablejs marimo
+uv run marimo edit notebook.py
+```
+
+### Existing Observable notebook
+
+```python
+import marimo as mo
+import observablejs as obs
+
+notebook = obs.Notebook.from_observablehq("@d3/world-tour")
+mo.ui.anywidget(notebook.view())
+```
+
+`@d3/world-tour` resolves to
+[observablehq.com/@d3/world-tour](https://observablehq.com/@d3/world-tour).
+
+### Author an interactive notebook
+
+```python
+import marimo as mo
+import observablejs as obs
+
+notebook = obs.Notebook(
+    obs.html(
+        """
+        <h2>Palmer penguins</h2>
+        <p>Choose a species to filter the chart.</p>
+        """
+    ),
+    obs.ojs(
+        """
+        viewof species = Inputs.select(
+          ["All", ...new Set(penguins.map((d) => d.species))],
+          {label: "Species", value: "All"}
+        )
+        """,
+        key="species_control",
+    ),
+    obs.js(
+        """
+        Plot.dot(
+          species === "All"
+            ? penguins
+            : penguins.filter((d) => d.species === species),
+          {
+            x: "culmen_length_mm",
+            y: "culmen_depth_mm",
+            fill: "species",
+            tip: true
+          }
+        ).plot({
+          height: 320,
+          color: {legend: true},
+          x: {grid: true, label: "Bill length (mm)"},
+          y: {grid: true, label: "Bill depth (mm)"}
+        })
+        """,
+        key="penguins_plot",
+    ),
+)
+
+mo.ui.anywidget(notebook.view())
+```
+
+`penguins`, `Inputs`, and `Plot` come from Notebook Kit. Changing the `viewof`
+selection recomputes the plot in the browser.
+
+## Cells, views, and inputs
+
+`Notebook` accepts four kinds of cells:
+
+| Helper          | Cell source                      |
+| --------------- | -------------------------------- |
+| `obs.js(...)`   | Standard Notebook Kit JavaScript |
+| `obs.ojs(...)`  | Observable JavaScript            |
+| `obs.md(...)`   | Markdown                         |
+| `obs.html(...)` | HTML                             |
+
+Top-level declarations in JavaScript cells form a reactive graph: when a value
+changes, every cell that references it runs again.
+
+_View_ means two things. In Python, `.view()` creates a renderable
+`NotebookView` widget. In a JavaScript cell, `view(input)` displays a browser
+input and defines its reactive value.
+
+| Call                          | Result                                                            |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `notebook.view()`             | A `NotebookView` that renders every cell.                         |
+| `notebook.view(cells=[...])`  | A composite view of selected cells and their hidden dependencies. |
+| `notebook.cell(0).view()`     | A focused view of one cell and its hidden dependencies.           |
+| `view(input)` inside `obs.js` | A browser input whose value other cells can reference.            |
+
+Create one view per place a notebook appears in the host. Views from the same
+notebook stay connected: Python variable updates reach all of them, and named
+`viewof` inputs share supported values across views.
+
+## Python variables
+
+Pass Python values to the browser through `variables`:
+
+```python
+import observablejs as obs
+
+notebook = obs.Notebook(
+    obs.js('html`<p>Threshold: <strong>${threshold}</strong></p>`'),
+    variables={"threshold": 0.75},
+)
+
+full_view = notebook.view()
+full_view
+```
+
+While the view stays mounted, call `notebook.update_variables(threshold=0.9)`
+to update the value.
+
+After the view renders, read browser values through `values` or `cell_values`
+and inspect dependency metadata through `graph`.
+
+## Load Notebook Kit HTML
+
+Load a Notebook Kit HTML document:
+
+```python
+from pathlib import Path
+
+import observablejs as obs
+
+path = Path("chart.html")
+notebook = obs.Notebook.from_html(
+    path.read_text(encoding="utf-8"),
+    base_path=path.parent,
+    embed_file_attachments=True,
+    rewrite_imports=True,
+)
+```
+
+## Documentation
+
+- [Quickstart](https://peter-gy.github.io/pyobservablejs/quickstart/)
+- [Mental model](https://peter-gy.github.io/pyobservablejs/mental-model/)
+- [Recipes](https://peter-gy.github.io/pyobservablejs/recipes/)
+- [API reference](https://peter-gy.github.io/pyobservablejs/reference/)
+
+## Acknowledgements
+
+Thanks to the Observable team for [Notebook
+Kit](https://github.com/observablehq/notebook-kit), which provides the notebook
+APIs and runtime used throughout this project.
+[`pyobsplot`](https://github.com/juba/pyobsplot) informed the Python variable
+API, and [Trevor Manz](https://github.com/manzt)'s anywidget composition demo
+shaped the widget design.
+
+## License
+
+MIT

pyobservablejs-0.0.2/README.md

@@ -0,0 +1,175 @@
+# pyobservablejs
+
+[![CI](https://github.com/peter-gy/pyobservablejs/actions/workflows/ci.yml/badge.svg)](https://github.com/peter-gy/pyobservablejs/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyobservablejs.svg)](https://pypi.org/project/pyobservablejs/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyobservablejs.svg)](https://pypi.org/project/pyobservablejs/)
+[![License](https://img.shields.io/pypi/l/pyobservablejs.svg)](https://github.com/peter-gy/pyobservablejs/blob/main/LICENSE)
+
+`pyobservablejs` brings interactive Observable notebooks into Python workflows.
+Author a notebook in Python or load an existing one, render the views you need,
+and keep its controls and results connected to your Python code.
+
+Use it in JupyterLab, marimo, VS Code notebooks, Google Colab, and other
+environments that support [anywidget](https://anywidget.dev/).
+
+## Quick start
+
+Python 3.11 or newer is required.
+
+```sh
+uv add pyobservablejs marimo
+uv run marimo edit notebook.py
+```
+
+### Existing Observable notebook
+
+```python
+import marimo as mo
+import observablejs as obs
+
+notebook = obs.Notebook.from_observablehq("@d3/world-tour")
+mo.ui.anywidget(notebook.view())
+```
+
+`@d3/world-tour` resolves to
+[observablehq.com/@d3/world-tour](https://observablehq.com/@d3/world-tour).
+
+### Author an interactive notebook
+
+```python
+import marimo as mo
+import observablejs as obs
+
+notebook = obs.Notebook(
+    obs.html(
+        """
+        <h2>Palmer penguins</h2>
+        <p>Choose a species to filter the chart.</p>
+        """
+    ),
+    obs.ojs(
+        """
+        viewof species = Inputs.select(
+          ["All", ...new Set(penguins.map((d) => d.species))],
+          {label: "Species", value: "All"}
+        )
+        """,
+        key="species_control",
+    ),
+    obs.js(
+        """
+        Plot.dot(
+          species === "All"
+            ? penguins
+            : penguins.filter((d) => d.species === species),
+          {
+            x: "culmen_length_mm",
+            y: "culmen_depth_mm",
+            fill: "species",
+            tip: true
+          }
+        ).plot({
+          height: 320,
+          color: {legend: true},
+          x: {grid: true, label: "Bill length (mm)"},
+          y: {grid: true, label: "Bill depth (mm)"}
+        })
+        """,
+        key="penguins_plot",
+    ),
+)
+
+mo.ui.anywidget(notebook.view())
+```
+
+`penguins`, `Inputs`, and `Plot` come from Notebook Kit. Changing the `viewof`
+selection recomputes the plot in the browser.
+
+## Cells, views, and inputs
+
+`Notebook` accepts four kinds of cells:
+
+| Helper          | Cell source                      |
+| --------------- | -------------------------------- |
+| `obs.js(...)`   | Standard Notebook Kit JavaScript |
+| `obs.ojs(...)`  | Observable JavaScript            |
+| `obs.md(...)`   | Markdown                         |
+| `obs.html(...)` | HTML                             |
+
+Top-level declarations in JavaScript cells form a reactive graph: when a value
+changes, every cell that references it runs again.
+
+_View_ means two things. In Python, `.view()` creates a renderable
+`NotebookView` widget. In a JavaScript cell, `view(input)` displays a browser
+input and defines its reactive value.
+
+| Call                          | Result                                                            |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `notebook.view()`             | A `NotebookView` that renders every cell.                         |
+| `notebook.view(cells=[...])`  | A composite view of selected cells and their hidden dependencies. |
+| `notebook.cell(0).view()`     | A focused view of one cell and its hidden dependencies.           |
+| `view(input)` inside `obs.js` | A browser input whose value other cells can reference.            |
+
+Create one view per place a notebook appears in the host. Views from the same
+notebook stay connected: Python variable updates reach all of them, and named
+`viewof` inputs share supported values across views.
+
+## Python variables
+
+Pass Python values to the browser through `variables`:
+
+```python
+import observablejs as obs
+
+notebook = obs.Notebook(
+    obs.js('html`<p>Threshold: <strong>${threshold}</strong></p>`'),
+    variables={"threshold": 0.75},
+)
+
+full_view = notebook.view()
+full_view
+```
+
+While the view stays mounted, call `notebook.update_variables(threshold=0.9)`
+to update the value.
+
+After the view renders, read browser values through `values` or `cell_values`
+and inspect dependency metadata through `graph`.
+
+## Load Notebook Kit HTML
+
+Load a Notebook Kit HTML document:
+
+```python
+from pathlib import Path
+
+import observablejs as obs
+
+path = Path("chart.html")
+notebook = obs.Notebook.from_html(
+    path.read_text(encoding="utf-8"),
+    base_path=path.parent,
+    embed_file_attachments=True,
+    rewrite_imports=True,
+)
+```
+
+## Documentation
+
+- [Quickstart](https://peter-gy.github.io/pyobservablejs/quickstart/)
+- [Mental model](https://peter-gy.github.io/pyobservablejs/mental-model/)
+- [Recipes](https://peter-gy.github.io/pyobservablejs/recipes/)
+- [API reference](https://peter-gy.github.io/pyobservablejs/reference/)
+
+## Acknowledgements
+
+Thanks to the Observable team for [Notebook
+Kit](https://github.com/observablehq/notebook-kit), which provides the notebook
+APIs and runtime used throughout this project.
+[`pyobsplot`](https://github.com/juba/pyobsplot) informed the Python variable
+API, and [Trevor Manz](https://github.com/manzt)'s anywidget composition demo
+shaped the widget design.
+
+## License
+
+MIT

{pyobservablejs-0.0.1 → pyobservablejs-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyobservablejs"
-version = "0.0.1"
+version = "0.0.2"
 description = "Observable JavaScript notebooks as reusable Python widgets"
 readme = "README.md"
 license = "MIT"

pyobservablejs-0.0.2/src/observablejs/_cell_ids.py

@@ -0,0 +1,41 @@
+"""JavaScript-safe notebook cell ID allocation."""
+
+from __future__ import annotations
+
+import dataclasses
+
+_MAX_SAFE_CELL_ID = (1 << 53) - 1
+
+
+def _is_safe_cell_id(value: object) -> bool:
+    return (
+        isinstance(value, int)
+        and not isinstance(value, bool)
+        and 1 <= value <= _MAX_SAFE_CELL_ID
+    )
+
+
+@dataclasses.dataclass
+class _CellIdAllocator:
+    reserved: set[int]
+    next_id: int = 1
+
+    def advance_past(self, cell_id: int) -> None:
+        if cell_id >= self.next_id:
+            self.next_id = cell_id + 1
+
+    def allocate(self) -> int:
+        cell_id = self._find(self.next_id, _MAX_SAFE_CELL_ID)
+        if cell_id is None:
+            cell_id = self._find(1, min(self.next_id - 1, _MAX_SAFE_CELL_ID))
+        if cell_id is None:
+            raise ValueError("Notebook has no available JavaScript-safe cell id")
+        self.reserved.add(cell_id)
+        self.next_id = cell_id + 1
+        return cell_id
+
+    def _find(self, start: int, stop: int) -> int | None:
+        candidate = max(start, 1)
+        while candidate <= stop and candidate in self.reserved:
+            candidate += 1
+        return candidate if candidate <= stop else None

{pyobservablejs-0.0.1 → pyobservablejs-0.0.2}/src/observablejs/_cells.py

@@ -7,6 +7,7 @@ import textwrap
 from collections.abc import Mapping
 from typing import Any, NotRequired, TypedDict, cast
 
+from ._cell_ids import _MAX_SAFE_CELL_ID, _is_safe_cell_id
 from ._serialize import SCRIPT_TYPES, Mode
 
 
@@ -27,8 +28,7 @@ class Cell:
     """Notebook Kit cell authored from Python source.
 
     Source strings are dedented and stripped of leading or trailing newlines
-    unless ``raw=True``. ``to_spec`` returns the JSON shape consumed by Notebook
-    Kit and by the bundled anywidget renderer.
+    unless ``raw=True``.
     """
 
     source: str
@@ -37,24 +37,47 @@ class Cell:
     name: str | None = None
     display: bool = True
     raw: bool = False
+    id: int | None = None
+    pinned: bool = False
+    output: str | None = None
     notebookkit_attrs: Mapping[str, Any] = dataclasses.field(default_factory=dict)
 
     def __post_init__(self) -> None:
         if not isinstance(self.source, str):
             raise TypeError("cell source must be a string")
+        if self.mode not in SCRIPT_TYPES:
+            raise ValueError(f"Unsupported Observable cell mode: {self.mode!r}")
+        if self.id is not None and (
+            not isinstance(self.id, int) or isinstance(self.id, bool)
+        ):
+            raise TypeError("cell id must be an integer or None")
+        if self.id is not None and not _is_safe_cell_id(self.id):
+            raise ValueError(f"cell id must be between 1 and {_MAX_SAFE_CELL_ID}")
+        attrs = dict(self.notebookkit_attrs)
+        collisions = {
+            "hidden",
+            "id",
+            "key",
+            "mode",
+            "name",
+            "output",
+            "pinned",
+            "value",
+        } & set(attrs)
+        if collisions:
+            names = ", ".join(sorted(collisions))
+            raise ValueError(
+                f"notebookkit_attrs cannot override first-class cell options: {names}"
+            )
+        object.__setattr__(self, "notebookkit_attrs", attrs)
         if self.raw:
             return
         source = textwrap.dedent(self.source).strip("\n")
         object.__setattr__(self, "source", source)
 
-    def to_spec(self, id: int) -> NotebookCellSpec:
-        """Return this cell in Notebook Kit's JSON cell shape."""
-
-        if self.mode not in SCRIPT_TYPES:
-            raise ValueError(f"Unsupported Observable cell mode: {self.mode!r}")
-        attrs = dict(self.notebookkit_attrs)
+    def _to_spec(self, generated_id: int) -> NotebookCellSpec:
         spec: dict[str, Any] = {
-            "id": attrs.pop("id", id),
+            "id": self.id if self.id is not None else generated_id,
             "value": self.source,
             "mode": self.mode,
         }
@@ -62,20 +85,24 @@ class Cell:
             spec["name"] = self.name
         if not self.display:
             spec["hidden"] = True
-        for key, value in attrs.items():
+        if self.pinned:
+            spec["pinned"] = True
+        if self.output is not None:
+            spec["output"] = self.output
+        for key, value in self.notebookkit_attrs.items():
             if value is not None:
                 spec[key] = value
         return cast(NotebookCellSpec, spec)
 
 
-CellInput = str | Cell
 NotebookCellInput = Cell
 
 
 def ojs(
-    source: CellInput,
+    source: str,
     *,
     key: str | None = None,
+    name: str | None = None,
     display: bool = True,
     raw: bool = False,
     id: int | None = None,
@@ -89,6 +116,7 @@ def ojs(
         source,
         mode="ojs",
         key=key,
+        name=name,
         display=display,
         raw=raw,
         id=id,
@@ -99,9 +127,10 @@ def ojs(
 
 
 def js(
-    source: CellInput,
+    source: str,
     *,
     key: str | None = None,
+    name: str | None = None,
     display: bool = True,
     raw: bool = False,
     id: int | None = None,
@@ -115,6 +144,7 @@ def js(
         source,
         mode="js",
         key=key,
+        name=name,
         display=display,
         raw=raw,
         id=id,
@@ -125,9 +155,10 @@ def js(
 
 
 def md(
-    source: CellInput,
+    source: str,
     *,
     key: str | None = None,
+    name: str | None = None,
     display: bool = True,
     raw: bool = False,
     id: int | None = None,
@@ -141,6 +172,7 @@ def md(
         source,
         mode="md",
         key=key,
+        name=name,
         display=display,
         raw=raw,
         id=id,
@@ -151,9 +183,10 @@ def md(
 
 
 def html(
-    source: CellInput,
+    source: str,
     *,
     key: str | None = None,
+    name: str | None = None,
     display: bool = True,
     raw: bool = False,
     id: int | None = None,
@@ -167,6 +200,7 @@ def html(
         source,
         mode="html",
         key=key,
+        name=name,
         display=display,
         raw=raw,
         id=id,
@@ -177,10 +211,11 @@ def html(
 
 
 def _source_cell(
-    source: CellInput,
+    source: str,
     *,
     mode: Mode,
     key: str | None = None,
+    name: str | None = None,
     display: bool = True,
     raw: bool = False,
     id: int | None = None,
@@ -188,35 +223,19 @@ def _source_cell(
     output: str | None = None,
     notebookkit_attrs: Mapping[str, Any] | None = None,
 ) -> Cell:
-    if isinstance(source, Cell):
-        if any(
-            [
-                key is not None,
-                display is not True,
-                mode != source.mode,
-                raw,
-                id is not None,
-                pinned,
-                output is not None,
-                notebookkit_attrs,
-            ]
-        ):
-            raise TypeError("Cannot override an existing Cell")
-        return source
     if not isinstance(source, str):
-        raise TypeError("notebook cells must be strings or Cell objects")
+        raise TypeError("cell source must be a string")
     return Cell(
         source=source,
         mode=mode,
         key=key,
+        name=name,
         display=display,
         raw=raw,
-        notebookkit_attrs=_cell_attrs(
-            notebookkit_attrs,
-            id=id,
-            pinned=pinned,
-            output=output,
-        ),
+        id=id,
+        pinned=pinned,
+        output=output,
+        notebookkit_attrs={} if notebookkit_attrs is None else notebookkit_attrs,
     )
 
 
@@ -226,26 +245,3 @@ def coerce_cell(source: NotebookCellInput) -> Cell:
     raise TypeError(
         "notebook cells must be created with obs.ojs, obs.js, obs.md, or obs.html"
     )
-
-
-def _cell_attrs(
-    notebookkit_attrs: Mapping[str, Any] | None,
-    *,
-    id: int | None,
-    pinned: bool,
-    output: str | None,
-) -> dict[str, Any]:
-    out = {} if notebookkit_attrs is None else dict(notebookkit_attrs)
-    collisions = {"hidden", "id", "mode", "output", "pinned", "value"} & set(out)
-    if collisions:
-        names = ", ".join(sorted(collisions))
-        raise ValueError(
-            f"notebookkit_attrs cannot override first-class cell options: {names}"
-        )
-    if id is not None:
-        out["id"] = id
-    if pinned:
-        out["pinned"] = True
-    if output is not None:
-        out["output"] = output
-    return out

{pyobservablejs-0.0.1 → pyobservablejs-0.0.2}/src/observablejs/_graph.py

@@ -66,11 +66,13 @@ class NotebookGraph:
         defined.update(name for cell in self.cells for name in cell.runtime_outputs)
         return tuple(name for name in self.references if name not in defined)
 
-    def cell(self, index: int) -> CellInfo | None:
+    def cell(self, index: int) -> CellInfo:
+        """Return the cell at ``index`` in the notebook definition."""
+
         for cell in self.cells:
             if cell.index == index:
                 return cell
-        return None
+        raise IndexError("notebook graph cell index out of range")
 
     def cell_for_variable(self, variable: str) -> CellInfo:
         matches = [cell for cell in self.cells if variable in cell.defines]