| Name | rerun-notebook JSON |
| Version |
0.26.1
JSON |
| download |
| home_page | None |
| Summary | Implementation helper for running rerun-sdk in notebooks |
| upload_time | 2025-10-21 15:22:41 |
| 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+Wasm 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 assets
Even though `rerun_notebook` ships with the assets bundled in, by default it will try to load them 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.
The assets are:
- `re_viewer_bg.wasm`, which is our Viewer compiled to Wasm, and
- `widget.js`, which is the glue code used to bind it to a Jupyter widget.
Both can be built in the [`rerun`](https://github.com/rerun-io/rerun) repository by running `pixi run py-build-notebook`.
### Inlined assets
Setting:
```
RERUN_NOTEBOOK_ASSET=inline
```
Will cause `rerun_notebook` to directly transmit the inlined assets 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. The browser cannot cache the resulting
JS/Wasm, so it ends up spending a lot more time loading it in every output cell.
### Locally served assets
Setting:
```
RERUN_NOTEBOOK_ASSET=serve-local
```
Will cause `rerun_notebook` to launch a thread serving the assets 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.
The JS and Wasm are served separately, so the Wasm can be stream-compiled, resulting in much faster
startup times. Both can also be cached by the browser.
### Manually hosted assets
Setting:
```
RERUN_NOTEBOOK_ASSET=https://your-hosted-asset-url.com/widget.js
```
Will cause `rerun_notebook` to load the assets from the provided URL. This is the most flexible way to
use the widget, but requires you to host the asset yourself.
Note that we require the URL to point to a `widget.js` file, but the Wasm file must be accessible from
a URL directly adjacent to it. Your server should provide both files:
- `https://your-hosted-asset-url.com/widget.js`
- `https://your-hosted-asset-url.com/re_viewer_bg.wasm`
The `rerun_notebook` package has a minimal server that can be used to serve the assets manually by running:
```
python -m rerun_notebook serve
```
However, any hosting platform can be used to serve the assets, 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
Run the `pixi run py-build-notebook` build command any time you make changes to the Viewer or TypeScript code.
Changing python code only requires restarting the Jupyter kernel.
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+Wasm 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 assets\n\nEven though `rerun_notebook` ships with the assets bundled in, by default it will try to load them from\n`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\nThe assets are:\n- `re_viewer_bg.wasm`, which is our Viewer compiled to Wasm, and\n- `widget.js`, which is the glue code used to bind it to a Jupyter widget.\n\nBoth can be built in the [`rerun`](https://github.com/rerun-io/rerun) repository by running `pixi run py-build-notebook`.\n\n### Inlined assets\n\nSetting:\n```\nRERUN_NOTEBOOK_ASSET=inline\n```\nWill cause `rerun_notebook` to directly transmit the inlined assets 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. The browser cannot cache the resulting\nJS/Wasm, so it ends up spending a lot more time loading it in every output cell.\n\n### Locally served assets\n\nSetting:\n```\nRERUN_NOTEBOOK_ASSET=serve-local\n```\nWill cause `rerun_notebook` to launch a thread serving the assets 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\nThe JS and Wasm are served separately, so the Wasm can be stream-compiled, resulting in much faster\nstartup times. Both can also be cached by the browser.\n\n### Manually hosted assets\n\nSetting:\n```\nRERUN_NOTEBOOK_ASSET=https://your-hosted-asset-url.com/widget.js\n```\nWill cause `rerun_notebook` to load the assets from the provided URL. This is the most flexible way to\nuse the widget, but requires you to host the asset yourself.\n\nNote that we require the URL to point to a `widget.js` file, but the Wasm file must be accessible from\na URL directly adjacent to it. Your server should provide both files:\n\n- `https://your-hosted-asset-url.com/widget.js`\n- `https://your-hosted-asset-url.com/re_viewer_bg.wasm`\n\nThe `rerun_notebook` package has a minimal server that can be used to serve the assets manually by running:\n```\npython -m rerun_notebook serve\n```\n\nHowever, any hosting platform can be used to serve the assets, 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\nRun the `pixi run py-build-notebook` build command any time you make changes to the Viewer or TypeScript code.\nChanging python code only requires restarting the Jupyter kernel.\n",
"bugtrack_url": null,
"license": "MIT OR Apache-2.0",
"summary": "Implementation helper for running rerun-sdk in notebooks",
"version": "0.26.1",
"project_urls": null,
"split_keywords": [
"notebook",
" rerun"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fb291f887b78707687b94bce2010838ea08ea7af6930229e22711c059e2b687c",
"md5": "6174274ea7e22d14d0ad3e1924251a0a",
"sha256": "57542090c0781c570c4b1903d27d28887a3883b0d0dfe13ab3b9b5e4ad2d8157"
},
"downloads": -1,
"filename": "rerun_notebook-0.26.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "6174274ea7e22d14d0ad3e1924251a0a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12499137,
"upload_time": "2025-10-21T15:22:41",
"upload_time_iso_8601": "2025-10-21T15:22:41.989263Z",
"url": "https://files.pythonhosted.org/packages/fb/29/1f887b78707687b94bce2010838ea08ea7af6930229e22711c059e2b687c/rerun_notebook-0.26.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 15:22:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "rerun-notebook"
}
