inline marimo WASM notebooks for interactive examples

[koaning]

What is your suggestion?

I am working on a marimo sphinx plugin (very much WIP now) that allows folks to add directives so that users may interactively play with code on the site. This is all running via WASM.

At the moment you're able to able to add directives via:

.. marimo:: path/to/notebook.py
   :height: 800px
   :width: 100%
   :theme: light

I also want to make an edit to it so that the user may press a button before any iframe is loaded. Right now the iframe auto-loads and that's not ideal for mobile users because it does cause a bunch of browser compute.

For altair?

Would this feature be something of interest to the altair project? I've been looking for a nice use-case for this project and I'll gladly put in the time to get it to work nicely on the docs here if folks are interested in it.

If folks are interested, any preference on where to place these examples?

Have you considered any alternative solutions?

No response

[mattijn]

Thanks for sharing the work you are doing on the marimo sphinx plugin! Maybe you have seen it already, but within the altair documentation we also found a way to integrate pyscript already to render/visualise/test the effect of different altair themes on-the-fly.

See https://altair-viz.github.io/user_guide/customization.html#built-in-themes, open the ▶ Show Vega-Altair Theme Test and changing the theme will re-render the altair specification through pyscript.

It was introduced in this PR #3630, at the core it is just this in plain html: #3630 (comment)

Redefining the specification input of the examples, so these become more accessible via direct modifications by users is definitely interesting! I would be in favour of adding a run button at the bottom. It might need to land in https://github.com/vega/sphinxext-altair to be useful to a broader group of users, while the current example page is coming from here: https://github.com/vega/altair/blob/main/sphinxext/altairgallery.py

Also, it might be a good idea to first bump Altair within pyodide to version 6.0.0 (currently 5.5.0), so you will have access to the from altair.datasets import data module (and not have a dependency on the archived python package vega_datasets).

Anyways, great work and thanks for raising this issue!

[joelostblom]

I think this would be great and very useful for readers! In addition to what @mattijn mentioned, I actually started a similar effort a few years ago via JupyterLite, but didn't have time to complete it, see #2593 for some details and discussion.

In brief, I think we need to decide if we want pyodide to load in the background when the page loads (like in quarto live), or if we want the load to trigger with the press of a button on a code cell as you mentioned (like for panel). I'm leaning towards the latter as both you and @mattijn seemed to prefer as well. Previously I have wanted this play button to make the code editable on the same page, but I think it would be fine if it just opens a new window with the example as an editable notebook (maybe with access to all examples in a file tab or similar? so that the user does need to reload all dependencies for each example in the gallery they want to try out.).

Since your extension is new we would also want to make sure it works robustly with the docs since a lot of users would be affected if something goes awry. Likewise, I would be curious what the maintenance effort looks like and to what degree you would be willing to be involved in it.

Again, exciting initiative and I hope it can lead to interactive examples in the Altair docs!

[koaning]

I just added a feature to the sphinx marimo plugin that allows you to add a button that prevents the auto-load.

https://koaning.github.io/sphinx-marimo/examples.html

Would something like this work? It's still early days for the plugin so I can take any feedback into account here. I think preventing the iframe from loading initially is best for docs pages, it's not exactly mobile friendly otherwise.

Note: it should also be easy to allow the user to open it up in a new tab, or on molab even if that's something you'd be open to.

[koaning]

I figured I might try and build an altair site that marimo to convert the code snippets to notebooks but noticed that it won't build because marimo expects narwhals v2. Just to check, is altair planning to adopt narwhals v2 at some point in the future or is there a reason why it sticks to v1?

[joelostblom]

Just to check, is altair planning to adopt narwhals v2 at some point in the future or is there a reason why it sticks to v1?

I don't think there is any restriction to not use v2 in altair; our pyproject.toml indicates that anything equal to or above 1.27.1 goes:

altair/pyproject.toml

Line 23 in ae5579b

"narwhals>=1.27.1"

[koaning]

d0h. False alarm, my bad! My venvs were acting up.

I am working on a branch now that has a preview of marimo usage inside of the altair docs though. Will let y'all know when I have a preview ready.

[koaning]

Also, it might be a good idea to first bump Altair within pyodide to version 6.0.0 (currently 5.5.0), so you will have access to the from altair.datasets import data module

@mattijn is there an ETA for this? I'm doing some prep work and have indeed found that some of the examples won't automatically run right now because of this.

[mattijn]

You and me are equally qualified (as is anyone else) to create a PR at pyodide. I'm not really sure anymore who did this previously. @joelostblom, do you remember which PR this was, as an inspirational example for someone to do a contribution there🥳

[koaning]

TIL.

I didn't know anyone could submit. It seems like one locally needs to build altair to pyodide and produce a file like this. I don't mind having a stab at it, unless folks are already working on this.

[koaning]

To generate a new file I think it's just uv pip instal pyodide-build followed by:

pyodide skeleton pypi altair

I toyed around locally and was able to generate this meta.yaml file.

package:
  name: altair
  version: 6.0.0
  top-level:
    - altair
source:
  url: https://files.pythonhosted.org/packages/py3/a/altair/altair-6.0.0-py3-none-any.whl
  sha256: 09ae95b53d5fe5b16987dccc785a7af8588f2dca50de1e7a156efa8a461515f8
about:
  home: https://altair-viz.github.io/
  PyPI: https://pypi.org/project/altair
  summary: "Vega-Altair: A declarative statistical visualization library for Python."
  license:
    'Copyright (c) 2015-2025, Vega-Altair Developers All rights reserved.  Redistribution
    and use in source and binary forms, with or without modification, are permitted
    provided that the following conditions are met:  * Redistributions of source code
    must retain the above copyright notice, this list of conditions and the following
    disclaimer.  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution.  * Neither the name of
    vega-altair nor the names of its contributors may be used to endorse or promote
    products derived from this software without specific prior written permission.  THIS
    SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
    EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
    IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
    IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
    OF SUCH DAMAGE. '
extra:
  recipe-maintainers:
    - joelostblom
requirements:
  run:
    - typing-extensions
    - Jinja2
    - jsonschema
    - packaging
    - narwhals

@joelostblom if you like I can make the PR, but figured it best to first double-check and confirm with you this looks cool? I've kept your name on it, after all.

[koaning]

Actually ... why would altair need to be added to pyodide like this? Can't it pull directly from pypi? All the dependencies seem to be without any rust libraries that need to be specifically compiled.

[mattijn]

Yeah, you are right. You can install version 6 already using micropip.

But if it is added to pyodide, then you do not need to install it manually first.

[joelostblom]

Although Altair is installable via micropip, it is convenient to have it included in the base pyodide image (especially for people just trying out pyodide and not knowing much about micropip) which was the motivation for adding it in pyodide/pyodide#4579.

Here is an example of how I upgraded to 5.4.1. The upgrade to 5.5.0 was then done automatically together with a bunch of other packages. So I'm not sure if the right path now is to make a PR with the recipe you created or wait for them to update all package for the next pyodide release. Since you have already put together a meta.yaml file (which I can't see anything wrong with), the most straightforward approach might just be to create the PR and see if that is still accepted for updated individual packages or if they do it all at once themselves nowadays (unless you find some docs on what they prefer of course).