| Name | rerun-notebook JSON |
| Version |
0.21.0
JSON |
| download |
| home_page | None |
| Summary | Implementation helper for running rerun-sdk in notebooks |
| upload_time | 2024-12-18 14:11:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT OR Apache-2.0 |
| keywords |
notebook
rerun
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `rerun-notebook`
Part of the [Rerun](https://github.com/rerun-io/rerun) project.
## What?
`rerun-notebook` is a support package for [`rerun-sdk`](https://pypi.org/project/rerun-sdk/)'s notebook integration. This is an implementation package that shouldn't be directly interacted with. It is typically installed using the `notebook` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras) of `rerun-sdk`:
```sh
pip install "rerun-sdk[notebook]"
```
## Why a separate package?
There are several reasons for this package to be separate from the main `rerun-sdk` package:
- `rerun-notebook` includes the JS distribution of the Rerun viewer (~31MiB). Adding it to the main `rerun-sdk` package would double its file size.
- `rerun-notebook` uses [hatch](https://hatch.pypa.io/) as package backend, and benefits from the [hatch-jupyter-builder](https://github.com/jupyterlab/hatch-jupyter-builder) plug-in. Since `rerun-sdk` must use [Maturin](https://www.maturin.rs), it would make the package management more complex.
- Developer experience: building `rerun-notebook` implies building `rerun_js`, which is best avoided when iterating on `rerun-sdk` outside of notebook environments.
## Ways to access the widget asset
Even though `rerun_notebook` ships with the widget asset bundled in, by default it will try to load the asset
from `https://app.rerun.io`. This is because the way anywiget transmits the asset at the moment results in
[a memory leak](https://github.com/manzt/anywidget/issues/613) of the entire module for each cell execution.
If your network does not allow you to access `app.rerun.io`, the behavior can be changed by setting the
the `RERUN_NOTEBOOK_ASSET` environment variable before you import `rerun_notebook`. This variable must
be set prior to your import because `AnyWidget` stores the resource on the widget class instance
once at import time.
### Inlined asset
Setting:
```
RERUN_NOTEBOOK_ASSET=inline
```
Will cause `rerun_notebook` to directly transmit the inlined asset to the widget over Jupyter comms.
This will be the most portable way to use the widget, but is currently known to leak memory and
has some performance issues in environments such as Google colab.
### Locally served asset
Setting:
```
RERUN_NOTEBOOK_ASSET=serve-local
```
Will cause `rerun_notebook` to launch a thread serving the asset from the local machine during
the lifetime of the kernel. This will be the best way to use the widget in a notebook environment
when your notebook server is running locally.
### Manually hosted asset
Setting:
```
RERUN_NOTEBOOK_ASSET=https://your-hosted-asset-url.com/widget.js
```
Will cause `rerun_notebook` to load the asset from the provided URL. This is the most flexible way to
use the widget, but requires you to host the asset yourself.
The `rerun_notebook` package has a minimal server that can be used to serve the asset nanually by running:
```
python -m rerun_notebook serve
```
However, any hosting platform can be used to serve the asset, as long as it is accessible to the notebook
and has appropriate CORS headers set. See: `asset_server.py` for a simple example.
## Run from source
Use Pixi:
```sh
# install rerun-sdk from source with the "notebook" extra
pixi run -e examples py-build-notebook
# run jupyter
pixi run -e examples jupyter notebook
```
## Development
Create a virtual environment and install `rerun-notebook` in *editable* mode with the
optional development dependencies:
```sh
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```
You then need to install the JavaScript dependencies and run the development server.
```sh
npm install
npm run dev
```
Open `example.ipynb` in JupyterLab, VS Code, or your favorite editor
to start developing. Changes made in `js/` will be reflected
in the notebook.
Raw data
{
"_id": null,
"home_page": null,
"name": "rerun-notebook",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "notebook, rerun",
"author": null,
"author_email": "\"Rerun.io\" <opensource@rerun.io>",
"download_url": null,
"platform": null,
"description": "# `rerun-notebook`\n\nPart of the [Rerun](https://github.com/rerun-io/rerun) project.\n\n## What?\n\n`rerun-notebook` is a support package for [`rerun-sdk`](https://pypi.org/project/rerun-sdk/)'s notebook integration. This is an implementation package that shouldn't be directly interacted with. It is typically installed using the `notebook` [extra](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras) of `rerun-sdk`:\n\n```sh\npip install \"rerun-sdk[notebook]\"\n```\n\n## Why a separate package?\n\nThere are several reasons for this package to be separate from the main `rerun-sdk` package:\n\n- `rerun-notebook` includes the JS distribution of the Rerun viewer (~31MiB). Adding it to the main `rerun-sdk` package would double its file size.\n- `rerun-notebook` uses [hatch](https://hatch.pypa.io/) as package backend, and benefits from the [hatch-jupyter-builder](https://github.com/jupyterlab/hatch-jupyter-builder) plug-in. Since `rerun-sdk` must use [Maturin](https://www.maturin.rs), it would make the package management more complex.\n- Developer experience: building `rerun-notebook` implies building `rerun_js`, which is best avoided when iterating on `rerun-sdk` outside of notebook environments.\n\n## Ways to access the widget asset\n\nEven though `rerun_notebook` ships with the widget asset bundled in, by default it will try to load the asset\nfrom `https://app.rerun.io`. This is because the way anywiget transmits the asset at the moment results in\n[a memory leak](https://github.com/manzt/anywidget/issues/613) of the entire module for each cell execution.\n\nIf your network does not allow you to access `app.rerun.io`, the behavior can be changed by setting the\nthe `RERUN_NOTEBOOK_ASSET` environment variable before you import `rerun_notebook`. This variable must\nbe set prior to your import because `AnyWidget` stores the resource on the widget class instance\nonce at import time.\n\n### Inlined asset\nSetting:\n```\nRERUN_NOTEBOOK_ASSET=inline\n```\nWill cause `rerun_notebook` to directly transmit the inlined asset to the widget over Jupyter comms.\nThis will be the most portable way to use the widget, but is currently known to leak memory and\nhas some performance issues in environments such as Google colab.\n\n### Locally served asset\nSetting:\n```\nRERUN_NOTEBOOK_ASSET=serve-local\n```\nWill cause `rerun_notebook` to launch a thread serving the asset from the local machine during\nthe lifetime of the kernel. This will be the best way to use the widget in a notebook environment\nwhen your notebook server is running locally.\n\n### Manually hosted asset\nSetting:\n```\nRERUN_NOTEBOOK_ASSET=https://your-hosted-asset-url.com/widget.js\n```\nWill cause `rerun_notebook` to load the asset from the provided URL. This is the most flexible way to\nuse the widget, but requires you to host the asset yourself.\n\nThe `rerun_notebook` package has a minimal server that can be used to serve the asset nanually by running:\n```\npython -m rerun_notebook serve\n```\n\nHowever, any hosting platform can be used to serve the asset, as long as it is accessible to the notebook\nand has appropriate CORS headers set. See: `asset_server.py` for a simple example.\n\n## Run from source\n\nUse Pixi:\n\n```sh\n# install rerun-sdk from source with the \"notebook\" extra\npixi run -e examples py-build-notebook\n\n# run jupyter\npixi run -e examples jupyter notebook\n```\n\n\n## Development\n\nCreate a virtual environment and install `rerun-notebook` in *editable* mode with the\noptional development dependencies:\n\n```sh\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n```\n\nYou then need to install the JavaScript dependencies and run the development server.\n\n```sh\nnpm install\nnpm run dev\n```\n\nOpen `example.ipynb` in JupyterLab, VS Code, or your favorite editor\nto start developing. Changes made in `js/` will be reflected\nin the notebook.\n",
"bugtrack_url": null,
"license": "MIT OR Apache-2.0",
"summary": "Implementation helper for running rerun-sdk in notebooks",
"version": "0.21.0",
"project_urls": null,
"split_keywords": [
"notebook",
" rerun"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f7890af559403afb6f254c77f5c2b1547e24af208215d4602bb368b36ef4eac",
"md5": "b877a058652af5f2b7a27904db6722b8",
"sha256": "e747586e46bd77bc5dcbc34ff585913c88d7a876ff8f66f4b36647182fae8e2a"
},
"downloads": -1,
"filename": "rerun_notebook-0.21.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b877a058652af5f2b7a27904db6722b8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 9187958,
"upload_time": "2024-12-18T14:11:21",
"upload_time_iso_8601": "2024-12-18T14:11:21.158457Z",
"url": "https://files.pythonhosted.org/packages/4f/78/90af559403afb6f254c77f5c2b1547e24af208215d4602bb368b36ef4eac/rerun_notebook-0.21.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 14:11:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "rerun-notebook"
}
