Python console embedded in docs

Hi, I wanted to share an idea. The Python documentation contains many code snippets that illustrate the described syntax and behaviours of the language and standard libraries. I think having embedded Python console in the docs to let execute the snippets and play with them, would raise the value of docs for its users.

When I think of how it could look like in practice, I see an extra element for the console, similar to a new email composing window in Gmail. A tab or window floating on bottom right of the page. The REPL snippets could have a new action button – “Execute in the console”, which would move the code into the console and execute it live. The console would be a REPL, which would let rerun the commands line by line and modify them.

Pyodide or PyScript should be a good fit for this feature. What do you think?


I think this would be cool, though some examples may have to be checked since they may depend on earlier examples.

Then again this could also easily lead to more load (and potential for security issues) on the hosting.

If I just look at it as a user, it’s almost like turning the docs into an IPython notebook and that is cool and useful.

You would need two versions of the doc if this is implemented.

One version that is just static web pages that can be packaged for local installation. I do this on macOS and Fedora from the official packages.

The other version with the embedded console.

1 Like

I have thought about sometime doing something like this by combining pieces of IDLE and turtledemo. Turtledemo has two side-by-side panes – python turtle code in a tk Text window on the left and a turtle canvas on the right.

In IDLE, Help => IDLE Doc displays a local copy of the IDLE web page in an IDLE read-only subclass of a tk Text widget. I does so by running the html text through a html-to-tk converter that knows enough html for this page. I expect the converter would have to be augmented to display other pages. This would replace the turtledemo Text. This would not require a separate version of the docs.

IDLE’s Shell combines a subclass of code.InteractiveInterprer for its logic and a version of IDLE’s Text subclass for its GUI. A version of this would replace the turtle canvas. New glue code to connect the panes would be needed.

1 Like

Pyodide and PyScript base on WebAssembly, which is a widely supported standard and describes a memory-safe, sandboxed execution environment. Therefore I don’t really see the potential for security issues.

Pyodide could be potentially vendored along with the docs and it also can work offline. Though it is quite big: the full package is 200+MB in size.

Downloading the console files should be optional, for saving the bandwidth for users with worse internet connections.

Pydantic’s docs use a Pyodide-based plugin by @samuelcolvin:

Before clicking run:

After clicking run:


See GitHub - samuelcolvin/mkdocs-run-code for how this is implemented.

1 Like

I’m looking forward to two PyCon US 2024 talks:

They can bring valuable input connected with this topic. Also @JeffGlass is an author of the sphinx_pyscript package.

1 Like

Thanks @maciek - we’re looking forward to it as well!

Little point - I’m actually not the author of Sphinx_PyScript, though I’m hoping to make some contributions there. I am the author of mkdocs-pyscript, which is similar to the Pydantic docs but leverages PyScript’s ability to run code in worker threads to improve use experience.


For comparison, here’s some unofficial release notes for Go which have runnable snippets:


It’s great to see the interactivity in the mkdocs and sphinx ecosystems. The Jupyter community has used Jupyter Book, nbsphinx, and over the years to increase the ability to run code in documentation. Looking forward to the talks at PyCon.