pyobservablejs 0.1.2__tar.gz → 0.2.0__tar.gz

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/.agent-plugin/skills/pyobservablejs/SKILL.md

@@ -125,20 +125,20 @@ still produce an empty or misleading chart. Follow
 
 ## Choose the access path
 
-| Task                                              | API or reference                                                       |
-| ------------------------------------------------- | ---------------------------------------------------------------------- |
-| Change Python inputs                              | `notebook.update_variables(patch)`                                     |
-| Replace the Python-owned environment              | `notebook.replace_variables(mapping)`                                  |
-| Restore authored computation                      | `notebook.reset_variables(*names)`                                     |
-| Check or raise browser failures                   | `view.diagnostics`, `view.raise_for_errors()`, `await view.ready()`    |
-| Read a selected cell's preview                    | `state.result("chart").values`                                         |
-| Find source, dependencies, and imports            | `view.inspection`, `notebook.cells`                                    |
-| List tables or read exact data                    | `view.datasets`, `await view.read(...)`, [data.md](references/data.md) |
-| Configure hosts or live code-mode editing         | [hosts.md](references/hosts.md)                                        |
-| Compose views, use files, import or export source | [workflows.md](references/workflows.md)                                |
+| Task                                              | API or reference                                                                    |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Change Python inputs                              | `notebook.update_variables(patch)`                                                  |
+| Replace the Python-owned environment              | `notebook.replace_variables(mapping)`                                               |
+| Restore authored computation                      | `notebook.reset_variables(*names)`                                                  |
+| Check or raise browser failures                   | `view.diagnostics`, `view.raise_for_errors()`, `await view.ready()`                 |
+| Read a selected cell's preview                    | `state.result("chart").values`                                                      |
+| Find source, dependencies, and imports            | `view.inspection`, `notebook.cells`                                                 |
+| List tables or read exact data                    | `view.datasets`, `await view.data[name].to_python()`, [data.md](references/data.md) |
+| Configure hosts or live code-mode editing         | [hosts.md](references/hosts.md)                                                     |
+| Compose views, use files, import or export source | [workflows.md](references/workflows.md)                                             |
 
 Strings passed to `state.result()` and `notebook.view()` are cell keys.
-Strings passed to `view.read()` are JavaScript variable names. Keep that
+Strings passed to `view.data[name]` are JavaScript variable names. Keep that
 distinction explicit in code.
 
 Let `obs.errors.ObservableError` subclasses propagate when the agent needs a

pyobservablejs-0.2.0/.agent-plugin/skills/pyobservablejs/references/data.md

@@ -0,0 +1,79 @@
+# Inspect source and extract data
+
+Use `notebook.cells`, `notebook.files`, `notebook.data`, and `notebook.graph`.
+Cell keys identify authored cells. Data names identify JavaScript variables.
+Conversions return Python objects and dataframes directly.
+
+```python
+notebook.cells["chart"].source
+notebook.files["sales.csv"].url
+notebook.data.names()
+notebook.graph.upstream("chart")
+frame = notebook.data["sales"].to_polars(columns=["category", "value"], limit=1000)
+```
+
+Notebook data and graph inspection use the optional server extra. The default
+engine is Deno. Network access is enabled by default; use
+`notebook.data.using(network=False)` for offline execution. Use `notebook.data.using(engine="chromium")` for
+actual browser capabilities. A notebook owns its lazy executions and closes
+them through `close()` or its context manager.
+
+## Widget route
+
+A displayed view uses anywidget and needs no Deno:
+
+```python
+names = await view.data.names()
+frame = await view.data["sales"].to_polars()
+rows = await view.data["sales"].to_python(limit=10)
+graph = await view.graph.snapshot()
+```
+
+Reads cover the view's evaluated cells and hidden dependencies. They work with
+`capture_state=False`. In Jupyter, await reads after display. In marimo, schedule
+an async task and let the executing cell finish, as described in [hosts.md](hosts.md).
+
+For passive reactive observation, `view.inspection`, `view.datasets`, and
+`view.diagnostics` publish readonly snapshots through traitlets. `view.state`
+contains bounded previews, not full dataframe exports.
+
+## Discovery and provenance
+
+```python
+catalog = await view.data.discover()
+for dataset in catalog.datasets:
+    print(dataset.name, await dataset.describe())
+frame = await catalog.datasets["sales"].to_polars()
+```
+
+Discovery retains datasets when independent cells fail. Inspect `catalog.errors`
+and `catalog.pending`. Discovered references pin value revisions and reject
+stale reads. Direct `view.data[name]` references request the current value.
+
+`describe()` reports kind, schema, row count, and native versus sampled schema
+metadata. A sampled schema may not include every type or column in later rows.
+`reference.sources` contains known static file and literal URL references, not
+proof of actual fetches or exhaustive lineage. It is `None` before analysis is
+available on an async reference.
+
+## Conversions and files
+
+Use `to_python()`, `to_polars()`, `to_pandas()`, or `to_arrow()`. Install the target
+library. Evaluated pandas conversion also requires PyArrow. Polars consumes IPC
+directly. Use `columns`, `offset`, `limit`, and `path` to bound reads. A conversion
+returns one coherent detached value or raises, rather than silently truncating.
+
+```python
+raw = notebook.files["sales.csv"].read_bytes()
+frame = notebook.files["sales.csv"].to_polars()
+config = notebook.files["config.json"].to_python()
+raw_from_browser = await view.files["sales.csv"].read_bytes()
+```
+
+Notebook file operations use Python I/O and need no Deno. View file operations use
+the originating browser. Pass `format=` when filename, content type, and content
+signatures cannot establish the parser. For advanced parsing, pass `read_bytes()`
+to the dataframe library's own reader.
+
+Headless data and Python files are synchronous by default. Their explicit async
+accessors are `notebook.data.aio` and `notebook.files.aio`.

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/.agent-plugin/skills/pyobservablejs/references/diagnose.md

@@ -72,7 +72,7 @@ that operation's exception:
 
 ```python
 try:
-    result = await view.read("visible", format="rows", limit=10)
+    result = await view.data["visible"].to_python(limit=10)
 except obs.errors.ObservableError as error:
     operation_diagnostics = [asdict(diagnostic) for diagnostic in error.diagnostics]
     raise
@@ -103,7 +103,7 @@ the failed check.
 For the starter's `chart` key:
 
 ```python
-print(notebook.cell("chart").source)
+print(notebook.cells["chart"].source)
 inspection = view.inspection
 if inspection is not None:
     chart = inspection.graph.cell("chart")
@@ -137,9 +137,9 @@ import can have `source=None` and `resolved=None`.
 For the starter, `visible` is the transformed table consumed by the chart:
 
 ```python
-sample = await view.read("visible", format="rows", limit=10)
-count = await view.read("rowCount", format="json")
-print(sample.data, count.data)
+sample = await view.data["visible"].to_python(limit=10)
+count = await view.data["rowCount"].to_python()
+print(sample, count)
 ```
 
 Expect two rows and count `2` at `minimum=0`, then one row and count `1` at

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/.agent-plugin/skills/pyobservablejs/references/hosts.md

@@ -6,7 +6,7 @@ Read [SKILL.md](../SKILL.md) for the object model and first chart.
 
 Use the notebook project's dependency manager or the host's package-management
 API. Apply that project's version pins and lockfile policy. Install `pyarrow`
-when Python must decode Arrow exports with `NotebookRead.to_arrow()`.
+when using `reference.to_arrow()` or evaluated `reference.to_pandas()`.
 
 Check the running kernel, which may differ from a terminal environment:
 
@@ -48,8 +48,8 @@ Run checkpoints and reads in a later cell:
 
 ```python
 state = await view.ready(timeout=30)
-count = await view.read("rowCount", format="json")
-print(count.data)
+count = await view.data["rowCount"].to_python()
+print(count)
 ```
 
 Jupyter can process widget replies while this call awaits. `ready()` waits for
@@ -130,7 +130,7 @@ errors such as duplicate Python definitions must be fixed in the host cells.
 
 Current marimo processes widget replies on the same command loop as ordinary
 cell and code-mode execution. Top-level async syntax does not make a direct
-`await view.ready()` or `await view.read(...)` safe inside that executing call.
+`await view.ready()` or `await view.data[name].to_python()` safe inside that executing call.
 Start the request, return control, and consume its result later.
 
 For reactive data reads, use two separate Python cells. The producer starts a
@@ -145,7 +145,7 @@ get_data, set_data = mo.state(None)
 
 async def load_rows():
     try:
-        set_data(await view.read("visible", format="rows", limit=10))
+        set_data(await view.data["visible"].to_python(limit=10))
     except Exception as error:
         set_data(error)
 
@@ -160,7 +160,7 @@ data = get_data()
 if isinstance(data, Exception):
     raise data
 if data is not None:
-    print(data.data)
+    print(data)
 ```
 
 The displayed `view` comes from the starter. A `None` value means the request
@@ -214,7 +214,7 @@ else:
     print("Browser checkpoint pending")
 ```
 
-Use the same container for one-off `view.read(...)` tasks. Cancel unfinished
+Use the same container for one-off `view.data[name].to_python()` tasks. Cancel unfinished
 tasks and remove consumed entries. Delete a temporary helper cell through
 `ctx.delete_cell(...)` inside a context when finished, or retain it for repeated
 checks. Do not spin in the same execution waiting for `task.done()`.

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/.agent-plugin/skills/pyobservablejs/references/workflows.md

@@ -132,8 +132,8 @@ and its dependencies as executable code with the host page's privileges.
 imported = obs.Notebook.from_observablehq("@d3/bar-chart", timeout=10)
 ```
 
-This fetches a public Observable document in Python. The displayed browser view
-then resolves its runtime modules and attachments. Inspect `imported.cells`
+This fetches the source model from a public Observable page in Python. The
+displayed browser view then resolves notebook modules and attachments. Inspect `imported.cells`
 before choosing a selection. Use canonical handles for anonymous cells.
 
 For an already loaded document mapping:
@@ -143,9 +143,10 @@ imported = obs.Notebook.from_observablehq_document(document)
 ```
 
 Read JSON or compressed dataset storage with the data tooling appropriate to
-that storage, then supply the document mapping. Preserve its `id` and `version`
-to retain import provenance and dependency resolution. `source_document` holds
-the original record, while `cells` describe the prepared Notebook Kit form.
+that storage, then supply the document mapping. Preserve `id`, `version`, and
+`resolutions` to retain import provenance and declared dependency pins.
+`source_document` holds the original record, while `cells` describe the
+prepared Notebook Kit form.
 Keep corpus samples and diagnostics in the user's designated artifact location.
 
 ## Export and finish

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/NOTICE

@@ -73,7 +73,7 @@ THE SOFTWARE.
 Packages
 
 - @observablehq/inspector 5.0.1 (ISC)
-- @observablehq/runtime 6.0.0 (ISC)
+- @observablehq/runtime 6.0.1 (ISC)
 
 -------------------------------------------------------------------------------
 
@@ -307,7 +307,7 @@ THE SOFTWARE.
 ===============================================================================
 Packages
 
-- anywidget-bundle 0.0.1 (MIT)
+- anywidget-bundle 0.1.1 (MIT)
 
 -------------------------------------------------------------------------------
 
@@ -467,7 +467,7 @@ EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ===============================================================================
 Packages
 
-- es-module-lexer 2.3.1 (MIT)
+- es-module-lexer 2.3.2 (MIT)
 
 -------------------------------------------------------------------------------
 
@@ -906,3 +906,8 @@ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+The optional server runtime includes the Playwright driver under Apache-2.0.
+Its LICENSE, NOTICE, and ThirdPartyNotices.txt accompany the driver in
+observablejs/static/server/driver/. Chromium is installed into the Playwright
+browser cache when first requested.

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pyobservablejs
-Version: 0.1.2
-Summary: Observable JavaScript notebooks as reusable Python widgets
+Version: 0.2.0
+Summary: Observable notebooks as Python widgets and headless computations
 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
@@ -21,9 +21,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.11
 Requires-Dist: agent-plugins>=0.2
-Requires-Dist: anywidget-bundle==0.0.1
+Requires-Dist: anywidget-bundle==0.1.1
 Requires-Dist: anywidget>=0.11.0
 Requires-Dist: traitlets>=5
+Provides-Extra: server
+Requires-Dist: deno<3,>=2.9.6; extra == 'server'
 Description-Content-Type: text/markdown
 
 # pyobservablejs
@@ -73,6 +75,18 @@ trust, since their JavaScript runs in the host page.
 
 **Experimental:** the API may change between releases.
 
+## Run headlessly
+
+Install `pyobservablejs[server]` to inspect and evaluate notebooks in Python
+scripts and services:
+
+```python
+print(notebook.with_variables(threshold=0.5).data["doubled"].to_python())
+```
+
+Read Python values, Polars or pandas dataframes, Arrow tables, and attachment bytes
+through the data and file namespaces. [Headless Python guide](https://peter-gy.github.io/pyobservablejs/guide/server/).
+
 ## Build on it
 
 - **Compose views.** `notebook.view("result")` displays the result and evaluates

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/README.md

@@ -45,6 +45,18 @@ trust, since their JavaScript runs in the host page.
 
 **Experimental:** the API may change between releases.
 
+## Run headlessly
+
+Install `pyobservablejs[server]` to inspect and evaluate notebooks in Python
+scripts and services:
+
+```python
+print(notebook.with_variables(threshold=0.5).data["doubled"].to_python())
+```
+
+Read Python values, Polars or pandas dataframes, Arrow tables, and attachment bytes
+through the data and file namespaces. [Headless Python guide](https://peter-gy.github.io/pyobservablejs/guide/server/).
+
 ## Build on it
 
 - **Compose views.** `notebook.view("result")` displays the result and evaluates

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/hatch_build.py

@@ -28,6 +28,9 @@ class CustomBuildHook(BuildHookInterface):
         static = Path(self.root, "src", "observablejs", "static")
         required = (
             static / "index.js",
+            static / "server" / "server.js",
+            static / "server" / "browser" / "browser.js",
+            static / "server" / "driver" / "index.mjs",
             static / "anywidget.json",
             static / "chunks" / "app.js",
         )

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "agent_plugins.build.hatchling"
 
 [project]
 name = "pyobservablejs"
-version = "0.1.2"
-description = "Observable JavaScript notebooks as reusable Python widgets"
+version = "0.2.0"
+description = "Observable notebooks as Python widgets and headless computations"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE", "NOTICE"]
@@ -13,7 +13,7 @@ authors = [{ name = "Peter Ferenc Gyarmati", email = "dev.petergy@gmail.com" }]
 maintainers = [{ name = "Peter Ferenc Gyarmati", email = "dev.petergy@gmail.com" }]
 requires-python = ">=3.11,<3.15"
 keywords = ["anywidget", "jupyter", "marimo", "notebooks", "observable", "visualization"]
-dependencies = ["agent-plugins>=0.2", "anywidget>=0.11.0", "anywidget-bundle==0.0.1", "traitlets>=5"]
+dependencies = ["agent-plugins>=0.2", "anywidget>=0.11.0", "anywidget-bundle==0.1.1", "traitlets>=5"]
 classifiers = [
 	"Programming Language :: Python :: 3",
 	"Programming Language :: Python :: 3 :: Only",
@@ -24,6 +24,9 @@ classifiers = [
 	"License :: OSI Approved :: MIT License",
 ]
 
+[project.optional-dependencies]
+server = ["deno>=2.9.6,<3"]
+
 [project.urls]
 Homepage = "https://github.com/peter-gy/pyobservablejs"
 Documentation = "https://peter-gy.github.io/pyobservablejs/"

{pyobservablejs-0.1.2 → pyobservablejs-0.2.0}/src/observablejs/__init__.py

@@ -11,8 +11,9 @@ from ._factories import (
     view_from_observablehq_document,
 )
 from ._graph import CellInfo, DependencyEdge, NotebookGraph
-from ._notebook import Notebook, NotebookCell, NotebookView
+from ._notebook import Notebook, NotebookCell
 from ._themes import NOTEBOOK_THEMES
+from ._view import NotebookView
 
 __version__ = _version("pyobservablejs")