marimo-export 0.0.0__tar.gz → 0.0.2__tar.gz

{marimo_export-0.0.0 → marimo_export-0.0.2}/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -186,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 marimo team
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

marimo_export-0.0.2/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: marimo-export
+Version: 0.0.2
+Summary: Precompute and read verified exports of selected marimo notebook results.
+Keywords: cache,export,marimo,notebook
+Author: marimo team
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Requires-Dist: cryptography==50.0.1
+Requires-Dist: idna==3.19
+Requires-Dist: marimo==0.24.0
+Requires-Dist: msgspec>=0.20
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: pydantic>=2,<3
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: altair>=5,<7 ; extra == 'all'
+Requires-Dist: anywidget>=0.9,<1 ; extra == 'all'
+Requires-Dist: pyarrow>=15 ; extra == 'all'
+Requires-Dist: vl-convert-python>=1.8 ; extra == 'all'
+Requires-Dist: anywidget>=0.9,<1 ; extra == 'anywidget'
+Requires-Dist: altair>=5,<7 ; extra == 'charts'
+Requires-Dist: vl-convert-python>=1.8 ; extra == 'charts'
+Requires-Dist: pyarrow>=15 ; extra == 'parquet'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://marimo-team.github.io/marimo-export/
+Project-URL: Documentation, https://marimo-team.github.io/marimo-export/
+Project-URL: Repository, https://github.com/marimo-team/marimo-export
+Project-URL: Issues, https://github.com/marimo-team/marimo-export/issues
+Provides-Extra: all
+Provides-Extra: anywidget
+Provides-Extra: charts
+Provides-Extra: parquet
+Description-Content-Type: text/markdown
+
+# marimo-export
+
+The `marimo-export` Python package plans, prepares, writes, opens, and verifies
+notebook exports from saved [marimo](https://marimo.io/) notebooks or named live sessions.
+
+[uv](https://docs.astral.sh/uv/) adds the package to a Python project:
+
+```bash
+uv add marimo-export
+```
+
+The package requires Python 3.10 or newer, is tested on Python 3.10 through
+3.14, and installs the marimo release pinned by its package metadata.
+
+The examples use the repository's
+[`report.py`](https://github.com/marimo-team/marimo-export/blob/main/examples/quickstart/report.py)
+and
+[`report.export.yaml`](https://github.com/marimo-team/marimo-export/blob/main/examples/quickstart/report.export.yaml).
+Download both files into the current directory before running them.
+
+## Run the CLI from PyPI
+
+```bash
+uvx marimo-export build report.py \
+  --spec report.export.yaml \
+  --output dist/report
+uvx marimo-export verify dist/report
+```
+
+`build` prepares missing states, writes the export, verifies every declared
+asset, and closes the notebook process it started.
+
+## Build from Python
+
+```python
+from pathlib import Path
+
+from marimo_export import ExportSpec, build
+
+Path("dist").mkdir(exist_ok=True)
+spec = ExportSpec.from_file("report.export.yaml")
+result = build("report.py", spec=spec, output="dist/report")
+
+print(result.path)
+```
+
+A matching later call with a new destination or `replace=True` can reuse the
+prepared export before notebook startup.
+
+## Read the export
+
+```python
+from marimo_export import open_export, verify_export
+
+export = open_export("dist/report")
+summary = export.state("monthly").output("summary").json()
+verified = verify_export("dist/report")
+
+print(dict(summary))
+print(verified.states, verified.outputs)
+```
+
+```text
+{'days': 30, 'label': 'Last 30 days'}
+2 2
+```
+
+Opening validates canonical `index.json` and leaves asset data lazy. Complete
+verification reads every declared asset and returns exported-state,
+state-output-pair, unique-asset, and verified-byte counts. The example has two
+states and one output name, so `verified.outputs` is `2`.
+
+## Capture a live session
+
+After opening `report.py` in a running marimo server, `capture()` borrows the
+named session and returns a leased `PreparedExport`:
+
+```python
+from marimo_export import ExportSpec, capture
+
+spec = ExportSpec.from_file("report.export.yaml")
+
+with capture(
+    "http://127.0.0.1:2718",
+    session="SESSION_ID",
+    spec=spec,
+) as prepared:
+    prepared.write("dist/report", replace=True)
+```
+
+`replace=True` replaces the complete destination directory. Keep unrelated
+application files outside `dist/report`.
+
+Use `marimo-export inspect SERVER` to find session IDs. The selected session
+remains active after capture. The live notebook environment and the client must
+load the same marimo-export implementation and exporter dependencies.
+
+## Install output exporters
+
+Install the optional families selected by your `ExportSpec`:
+
+```bash
+uv add "marimo-export[charts,parquet,anywidget]"
+```
+
+The base package supports JSON, native marimo values, and custom exporter
+callables. The optional families add Altair and PNG charts, Parquet tables, and
+AnyWidget bundles.
+
+## Learn the complete API
+
+- [Getting started](https://marimo-team.github.io/marimo-export/guide/getting-started)
+- [Python API](https://marimo-team.github.io/marimo-export/reference/python-api)
+- [Choose states and outputs](https://marimo-team.github.io/marimo-export/guide/choose-states)
+- [CLI reference](https://marimo-team.github.io/marimo-export/reference/cli)
+- [Use notebook exports with agents](https://marimo-team.github.io/marimo-export/guide/agents-and-automation)
+
+Preparing an export executes notebook code with the notebook environment's file,
+credential, network, and package access.

marimo_export-0.0.2/README.md

@@ -0,0 +1,119 @@
+# marimo-export
+
+The `marimo-export` Python package plans, prepares, writes, opens, and verifies
+notebook exports from saved [marimo](https://marimo.io/) notebooks or named live sessions.
+
+[uv](https://docs.astral.sh/uv/) adds the package to a Python project:
+
+```bash
+uv add marimo-export
+```
+
+The package requires Python 3.10 or newer, is tested on Python 3.10 through
+3.14, and installs the marimo release pinned by its package metadata.
+
+The examples use the repository's
+[`report.py`](https://github.com/marimo-team/marimo-export/blob/main/examples/quickstart/report.py)
+and
+[`report.export.yaml`](https://github.com/marimo-team/marimo-export/blob/main/examples/quickstart/report.export.yaml).
+Download both files into the current directory before running them.
+
+## Run the CLI from PyPI
+
+```bash
+uvx marimo-export build report.py \
+  --spec report.export.yaml \
+  --output dist/report
+uvx marimo-export verify dist/report
+```
+
+`build` prepares missing states, writes the export, verifies every declared
+asset, and closes the notebook process it started.
+
+## Build from Python
+
+```python
+from pathlib import Path
+
+from marimo_export import ExportSpec, build
+
+Path("dist").mkdir(exist_ok=True)
+spec = ExportSpec.from_file("report.export.yaml")
+result = build("report.py", spec=spec, output="dist/report")
+
+print(result.path)
+```
+
+A matching later call with a new destination or `replace=True` can reuse the
+prepared export before notebook startup.
+
+## Read the export
+
+```python
+from marimo_export import open_export, verify_export
+
+export = open_export("dist/report")
+summary = export.state("monthly").output("summary").json()
+verified = verify_export("dist/report")
+
+print(dict(summary))
+print(verified.states, verified.outputs)
+```
+
+```text
+{'days': 30, 'label': 'Last 30 days'}
+2 2
+```
+
+Opening validates canonical `index.json` and leaves asset data lazy. Complete
+verification reads every declared asset and returns exported-state,
+state-output-pair, unique-asset, and verified-byte counts. The example has two
+states and one output name, so `verified.outputs` is `2`.
+
+## Capture a live session
+
+After opening `report.py` in a running marimo server, `capture()` borrows the
+named session and returns a leased `PreparedExport`:
+
+```python
+from marimo_export import ExportSpec, capture
+
+spec = ExportSpec.from_file("report.export.yaml")
+
+with capture(
+    "http://127.0.0.1:2718",
+    session="SESSION_ID",
+    spec=spec,
+) as prepared:
+    prepared.write("dist/report", replace=True)
+```
+
+`replace=True` replaces the complete destination directory. Keep unrelated
+application files outside `dist/report`.
+
+Use `marimo-export inspect SERVER` to find session IDs. The selected session
+remains active after capture. The live notebook environment and the client must
+load the same marimo-export implementation and exporter dependencies.
+
+## Install output exporters
+
+Install the optional families selected by your `ExportSpec`:
+
+```bash
+uv add "marimo-export[charts,parquet,anywidget]"
+```
+
+The base package supports JSON, native marimo values, and custom exporter
+callables. The optional families add Altair and PNG charts, Parquet tables, and
+AnyWidget bundles.
+
+## Learn the complete API
+
+- [Getting started](https://marimo-team.github.io/marimo-export/guide/getting-started)
+- [Python API](https://marimo-team.github.io/marimo-export/reference/python-api)
+- [Choose states and outputs](https://marimo-team.github.io/marimo-export/guide/choose-states)
+- [CLI reference](https://marimo-team.github.io/marimo-export/reference/cli)
+- [Use notebook exports with agents](https://marimo-team.github.io/marimo-export/guide/agents-and-automation)
+
+Preparing an export executes notebook code with the notebook environment's file,
+credential, network, and package access.

marimo_export-0.0.2/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["uv_build>=0.11.28,<0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "marimo-export"
+version = "0.0.2"
+description = "Precompute and read verified exports of selected marimo notebook results."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography==50.0.1",
+    "idna==3.19",
+    "marimo==0.24.0",
+    "msgspec>=0.20",
+    "numpy>=1.23.5",
+    "pydantic>=2,<3",
+    "PyYAML>=6.0.1",
+]
+keywords = [
+    "cache",
+    "export",
+    "marimo",
+    "notebook",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[[project.authors]]
+name = "marimo team"
+
+[project.urls]
+Homepage = "https://marimo-team.github.io/marimo-export/"
+Documentation = "https://marimo-team.github.io/marimo-export/"
+Repository = "https://github.com/marimo-team/marimo-export"
+Issues = "https://github.com/marimo-team/marimo-export/issues"
+
+[project.scripts]
+marimo-export = "marimo_export.cli:main"
+
+[project.entry-points."marimo.kernel.lifespan"]
+marimo-export = "marimo_export._marimo.entrypoints:kernel_lifespan"
+
+[project.optional-dependencies]
+anywidget = ["anywidget>=0.9,<1"]
+charts = [
+    "altair>=5,<7",
+    "vl-convert-python>=1.8",
+]
+parquet = ["pyarrow>=15"]
+all = [
+    "altair>=5,<7",
+    "anywidget>=0.9,<1",
+    "pyarrow>=15",
+    "vl-convert-python>=1.8",
+]

marimo_export-0.0.2/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["uv_build>=0.11.28,<0.13.0"]
+build-backend = "uv_build"
+
+[project]
+name = "marimo-export"
+version = "0.0.2"
+description = "Precompute and read verified exports of selected marimo notebook results."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "marimo team" }]
+requires-python = ">=3.10"
+dependencies = [
+  "cryptography==50.0.1",
+  "idna==3.19",
+  "marimo==0.24.0",
+  "msgspec>=0.20",
+  "numpy>=1.23.5",
+  "pydantic>=2,<3",
+  "PyYAML>=6.0.1",
+]
+keywords = ["cache", "export", "marimo", "notebook"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://marimo-team.github.io/marimo-export/"
+Documentation = "https://marimo-team.github.io/marimo-export/"
+Repository = "https://github.com/marimo-team/marimo-export"
+Issues = "https://github.com/marimo-team/marimo-export/issues"
+
+[project.scripts]
+marimo-export = "marimo_export.cli:main"
+
+[project.entry-points."marimo.kernel.lifespan"]
+marimo-export = "marimo_export._marimo.entrypoints:kernel_lifespan"
+
+[project.optional-dependencies]
+anywidget = ["anywidget>=0.9,<1"]
+charts = ["altair>=5,<7", "vl-convert-python>=1.8"]
+parquet = ["pyarrow>=15"]
+all = ["altair>=5,<7", "anywidget>=0.9,<1", "pyarrow>=15", "vl-convert-python>=1.8"]

marimo_export-0.0.2/src/marimo_export/__init__.py

@@ -0,0 +1,76 @@
+"""Create and read verified exports of prepared marimo notebook results."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from marimo_export._identity import implementation_identity as _implementation_identity
+
+_LOADED_SOURCE_IDENTITY = _implementation_identity()
+
+if TYPE_CHECKING:
+    from marimo_export._build import build
+    from marimo_export._services.capture_export import capture
+    from marimo_export._services.plan_export import plan
+    from marimo_export._services.prepare_export import prepare
+    from marimo_export.planning import ExportPlan
+    from marimo_export.prepared import PreparedExport
+    from marimo_export.progress import ProgressEvent
+    from marimo_export.reader import NotebookExport, open_export
+    from marimo_export.repository import ExportRepository
+    from marimo_export.result import ExportResult
+    from marimo_export.spec import ExportSpec, OutputSpec, StateSpace
+    from marimo_export.verification import VerificationResult, verify_export
+
+_EXPORTS = {
+    "ExportPlan": ("marimo_export.planning", "ExportPlan"),
+    "ExportRepository": ("marimo_export.repository", "ExportRepository"),
+    "ExportResult": ("marimo_export.result", "ExportResult"),
+    "ExportSpec": ("marimo_export.spec", "ExportSpec"),
+    "NotebookExport": ("marimo_export.reader", "NotebookExport"),
+    "OutputSpec": ("marimo_export.spec", "OutputSpec"),
+    "PreparedExport": ("marimo_export.prepared", "PreparedExport"),
+    "ProgressEvent": ("marimo_export.progress", "ProgressEvent"),
+    "StateSpace": ("marimo_export.spec", "StateSpace"),
+    "VerificationResult": ("marimo_export.verification", "VerificationResult"),
+    "build": ("marimo_export._build", "build"),
+    "capture": ("marimo_export._services.capture_export", "capture"),
+    "open_export": ("marimo_export.reader", "open_export"),
+    "plan": ("marimo_export._services.plan_export", "plan"),
+    "prepare": ("marimo_export._services.prepare_export", "prepare"),
+    "verify_export": ("marimo_export.verification", "verify_export"),
+}
+
+__all__ = (
+    "ExportPlan",
+    "ExportRepository",
+    "ExportResult",
+    "ExportSpec",
+    "NotebookExport",
+    "OutputSpec",
+    "PreparedExport",
+    "ProgressEvent",
+    "StateSpace",
+    "VerificationResult",
+    "build",
+    "capture",
+    "open_export",
+    "plan",
+    "prepare",
+    "verify_export",
+)
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_name, attribute = _EXPORTS[name]
+    except KeyError as error:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from error
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__})

marimo_export-0.0.2/src/marimo_export/_blob_asset.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import cast
+
+import msgspec
+
+from marimo_export._json import JsonObject, canonical_bytes, portable_json_object
+from marimo_export._media_type import MAX_BLOB_METADATA_JSON_BYTES, validate_media_type
+from marimo_export._portable import validate_portable_basename
+
+_FIELDS = ("data", "media_type", "filename", "metadata")
+
+
+@dataclass(frozen=True, slots=True)
+class BlobAssetEnvelope:
+    """The verified native marimo BlobAsset MessagePack envelope."""
+
+    data: bytes
+    media_type: str | None
+    filename: str | None
+    metadata: JsonObject
+
+
+def decode_blob_asset(
+    data: bytes,
+    *,
+    maximum_bytes: int | None = None,
+) -> BlobAssetEnvelope:
+    """Strictly decode the exact MessagePack shape emitted by marimo."""
+
+    if not isinstance(data, bytes):
+        raise TypeError("BlobAsset MessagePack must be bytes")
+    if maximum_bytes is not None and (
+        not isinstance(maximum_bytes, int) or isinstance(maximum_bytes, bool) or maximum_bytes <= 0
+    ):
+        raise TypeError("maximum_bytes must be a positive integer")
+    if maximum_bytes is not None and len(data) > maximum_bytes:
+        raise ValueError(f"BlobAsset MessagePack exceeds the {maximum_bytes} byte limit")
+
+    try:
+        decoded = msgspec.msgpack.decode(data)
+    except msgspec.DecodeError as error:
+        raise ValueError("BlobAsset is invalid MessagePack") from error
+    if not isinstance(decoded, dict) or tuple(decoded) != _FIELDS:
+        raise ValueError("BlobAsset does not use the native four-field envelope")
+    if msgspec.msgpack.encode(decoded) != data:
+        raise ValueError("BlobAsset MessagePack is not canonical")
+
+    payload = decoded["data"]
+    media_type = decoded["media_type"]
+    filename = decoded["filename"]
+    metadata = decoded["metadata"]
+    if not isinstance(payload, bytes):
+        raise ValueError("BlobAsset data must be bytes")
+    if media_type is not None:
+        try:
+            media_type = validate_media_type(media_type, "BlobAsset media_type")
+        except (TypeError, ValueError) as error:
+            raise ValueError("BlobAsset media_type is invalid") from error
+    if filename is not None:
+        try:
+            filename = validate_portable_basename(filename, "BlobAsset filename")
+        except (TypeError, ValueError) as error:
+            raise ValueError("BlobAsset filename is invalid") from error
+    try:
+        metadata_object = portable_json_object(metadata, "BlobAsset metadata")
+    except (TypeError, ValueError) as error:
+        raise ValueError("BlobAsset metadata must be portable JSON") from error
+    if len(canonical_bytes(metadata_object)) > MAX_BLOB_METADATA_JSON_BYTES:
+        raise ValueError(
+            f"BlobAsset metadata exceeds {MAX_BLOB_METADATA_JSON_BYTES} canonical JSON bytes"
+        )
+
+    return BlobAssetEnvelope(
+        data=payload,
+        media_type=cast(str | None, media_type),
+        filename=cast(str | None, filename),
+        metadata=metadata_object,
+    )
+
+
+__all__ = ["BlobAssetEnvelope", "decode_blob_asset"]

marimo_export-0.0.2/src/marimo_export/_build.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from marimo_export._delivery import preflight_export_destination
+from marimo_export._services.prepare_export import prepare
+from marimo_export.progress import ProgressEvent
+from marimo_export.repository import ExportRepository
+from marimo_export.result import ExportResult
+from marimo_export.spec import ExportSpec, StrPath
+
+
+def build(
+    notebook: StrPath,
+    *,
+    spec: ExportSpec,
+    output: StrPath,
+    repository: ExportRepository | None = None,
+    timeout: float = 30.0,
+    replace: bool = False,
+    progress: Callable[[ProgressEvent], None] | None = None,
+    cancelled: Callable[[], bool] | None = None,
+) -> ExportResult:
+    """Prepare, write, and verify one notebook export."""
+
+    preflight_export_destination(output, replace=replace)
+    with prepare(
+        notebook,
+        spec=spec,
+        repository=repository,
+        timeout=timeout,
+        progress=progress,
+        cancelled=cancelled,
+    ) as prepared:
+        return prepared.write(output, replace=replace, progress=progress)
+
+
+__all__ = ["build"]

marimo_export-0.0.2/src/marimo_export/_cell_ids.py

@@ -0,0 +1,28 @@
+"""Normalize Marimo cell identifiers at adapter boundaries."""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+_MAX_CELL_ID_BYTES = 1_024
+_UUID_LENGTH = 36
+
+
+def canonical_cell_id(value: object) -> str:
+    """Remove Marimo's external UUIDv4 scope from one native cell ID."""
+
+    cell_id = str(value)
+    if not cell_id or len(cell_id.encode("utf-8")) > _MAX_CELL_ID_BYTES:
+        raise ValueError("cell ID must be a bounded non-empty string")
+    if len(cell_id) <= _UUID_LENGTH:
+        return cell_id
+    prefix = cell_id[:_UUID_LENGTH]
+    suffix = cell_id[_UUID_LENGTH:]
+    try:
+        external = UUID(prefix, version=4)
+    except ValueError:
+        return cell_id
+    return suffix if suffix and str(external) == prefix else cell_id
+
+
+__all__ = ["canonical_cell_id"]

marimo_export-0.0.2/src/marimo_export/_cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line parsing, delegation, rendering, and failure policy."""