Examples

Basic REPL

.. py-repl::

Light theme, minimal

.. py-repl::
   :theme: catppuccin-latte
   :no-header:
   :no-banner:

Startup script

The :src: option loads a Python script into the REPL namespace. If the script defines a setup() function, its output is shown when the REPL starts.

Startup script:

message = "Hello from the startup script!"


def setup():
    print(message)
    print("Try: message")

RST content:

.. py-repl::
   :src: _static/setup.py

Rendered result:

Replay session

Inline directive content should follow Doctest-style (>>> / ...) and is used as replay prompts.

.. py-repl::
   :no-header:
   :no-banner:

   >>> x = 2 + 2
   >>> print(f"{x=}")
   >>> x * 10
   >>> class Foo:
   ...     x = 1
   ...
   >>> Foo()

Combine a silent bootstrap file with a visible replay body:

.. py-repl::
   :src: _static/setup.py
   :no-header:

   >>> print(message)

Use :replay: on :src: to source a file as replay.

Source script:

greeting = "Hello from replay mode"
print(greeting)
greeting.upper()

RST content:

.. py-repl::
   :src: _static/replay_demo.py
   :replay:
   :no-header:
   :no-banner:

Rendered result:

Autodoc

When pyrepl_doctest_blocks = "autodoc", doctest examples in documented APIs become interactive REPLs. Set pyrepl_autodoc_packages to install the documented package from a Pyodide-compatible wheel (or PyPI name) and automatically import the documented object before replay:

# conf.py
html_static_path = ["_static"]
pyrepl_autodoc_packages = "_static/wheels/pyrepl_test_pkg-1.0.0-py3-none-any.whl"

Autodoc still imports the package on the host at build time (for example via pip install -e ".[docs]" in this repository).

Source module:

RST content:

.. autofunction:: pyrepl_test_pkg.demo.example_generator

Rendered result:

pyrepl_test_pkg.demo.example_generator(n)

Generators yield values useful for iteration.

Example

Local Pyodide wheels

The same wheel can be referenced manually from .. py-repl:: when you want a standalone REPL without autodoc:

.. py-repl::
   :packages: _static/wheels/pyrepl_test_pkg-1.0.0-py3-none-any.whl
   :no-header:
   :no-banner:

   >>> import pyrepl_test_pkg
   >>> pyrepl_test_pkg.ping()