Metadata-Version: 2.4
Name: pyobservablejs
Version: 0.2.1
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
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.15,>=3.11
Requires-Dist: agent-plugins>=0.2
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

`pyobservablejs` brings reactive [Observable notebooks](https://observablehq.com/notebook-kit/)
to Python. Build cells, charts, and browser inputs, or import an existing notebook.
Display the whole notebook or selected cells in JupyterLab, marimo, VS Code,
Colab, and other [anywidget](https://anywidget.dev/) hosts.

![An interactive notebook built from Python](https://files.peter.gy/projects/pyobservablejs/assets/from-code.gif)

[Try it in your browser](https://molab.marimo.io/github/peter-gy/pyobservablejs/blob/main/examples/from-code.py/wasm?utm_source=pyobservablejs)
· [Quickstart](https://peter-gy.github.io/pyobservablejs/guide/quickstart/)
· [Examples](https://peter-gy.github.io/pyobservablejs/examples/)
· [API reference](https://peter-gy.github.io/pyobservablejs/reference/)

## Start

Install in a Python 3.11 through 3.14 notebook environment:

```sh
pip install pyobservablejs
```

Create an input and a result that updates when it changes:

```python
import observablejs as obs

notebook = obs.Notebook(
    obs.ojs(
        "viewof threshold = Inputs.range([0, 1], {value: 0.5, step: 0.1})",
        key="control",
    ),
    obs.js(
        "const doubled = threshold * 2; display(md`Doubled: **${doubled}**`);",
        key="result",
    ),
)
view = notebook.view()
view
```

Cells run in the browser through [Notebook Kit](https://observablehq.com/notebook-kit/).
Its `Inputs` library loads from the network. Use notebook and module sources you
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
  its dependencies. [Select and arrange cells](https://peter-gy.github.io/pyobservablejs/guide/display/cells/).
- **Connect Python.** `notebook.update_variables({"threshold": 0.8})` updates
  mounted views. Read named results through `view.state`.
  [Send values and read results](https://peter-gy.github.io/pyobservablejs/guide/connect/).
- **Bring notebooks and data.** Load Notebook Kit HTML, public ObservableHQ
  notebooks, local files, and JavaScript modules.
  [Create and import notebooks](https://peter-gy.github.io/pyobservablejs/guide/create/).
- **Inspect and extract.** Browse cells, imports, attachments, and dependencies.
  Read datasets as Arrow or projected rows.
  [Inspect notebook data](https://peter-gy.github.io/pyobservablejs/guide/connect/inspect-notebooks/).
- **Work with agents.** The installed package carries instructions that match
  its API. [Read the packaged skill](https://peter-gy.github.io/pyobservablejs/guide/agents/)
  or the [documentation map](https://peter-gy.github.io/pyobservablejs/llms.txt).

[Documentation](https://peter-gy.github.io/pyobservablejs/)
· [Troubleshooting](https://peter-gy.github.io/pyobservablejs/guide/troubleshooting/)
· [Contributing](https://github.com/peter-gy/pyobservablejs/blob/main/development_docs/development.md)
· [MIT license](https://github.com/peter-gy/pyobservablejs/blob/main/LICENSE)

Built on Observable's [Notebook Kit](https://github.com/observablehq/notebook-kit)
and [anywidget](https://github.com/manzt/anywidget).
[`pyobsplot`](https://github.com/juba/pyobsplot) informed the Python variable API.
