Package 'rpyodide'

Start a session backed by a local CPython

Description

Runs rpyodide's Python bridge in a regular Python process instead of Pyodide, talking to it over stdin and stdout. Everything else works the same way, so code written for rpyodide (and rpyodide itself) can be tested outside webR, for example on CRAN or in continuous integration. This needs the processx package and Python 3.8 or later.

Usage

cpython_start(name = "cpython", python = find_python(), activate = TRUE)

find_python()

Arguments

name	Session name.
python	Path to the Python executable. By default, the RPYODIDE_PYTHON environment variable if it is set, otherwise the first of python3 and python found on the PATH.
activate	Make this the active session?

Details

Differences from Pyodide sessions: packages come from the Python installation (use pip; py_install() and py_require() can't install them), files aren't copied because Python shares R's file system, and the Python version is the local one.

Value

The session, invisibly.

Functions

• find_python(): The Python executable cpython_start() uses by default, or "" if there is none.

See Also

pyodide_start() for Python in webR.

Examples

if (nzchar(find_python()) && requireNamespace("processx", quietly = TRUE)) {
  cpython_start("example")
  py_eval("1 + 1", session = "example")
  pyodide_stop("example")
}

---

Default Pyodide distribution URL

Description

Pyodide is loaded from this URL unless pyodide_url is given to pyodide_start(). Set options(rpyodide.pyodide_url = ...) to change it. The URL must end in / and contain pyodide.mjs.

Usage

default_pyodide_url()

Value

A character string.

---

Import a Python module

Description

Imports a module, loading it from the Pyodide distribution first if necessary. Use $ to get its attributes.

Usage

import(module, convert = TRUE, session = NULL)

import_main(convert = TRUE, session = NULL)

import_builtins(convert = TRUE, session = NULL)

Arguments

module	Module name, e.g. "numpy" or "os.path".
convert	Convert values returned from this module to R?
session	Pyodide session; defaults to the active one.

Value

A Python module object.

Examples

## Not run: 
np <- import("numpy")
np$linspace(0, 1, 5L)

## End(Not run)

---

Is an object a Python object?

Description

Is an object a Python object?

Usage

is_py_object(x)

Arguments

x	An R object.

Value

TRUE if x refers to an object in a Pyodide session.

---

Is R running in webR?

Description

Is R running in webR?

Usage

is_webr()

Value

TRUE when R is webR (R compiled to WebAssembly).

---

The Python ⁠__main__⁠ module

Description

py$name gets a variable from Python's ⁠__main__⁠ module in the active session, and py$name <- value sets one.

Usage

py

Format

An object of class pyodide_main.

---

Is Python available?

Description

Is Python available?

Usage

py_available(initialize = FALSE)

Arguments

initialize

Start the default session if none is running?

Value

TRUE if a Pyodide session is running (or was started).

---

Python configuration

Description

Python configuration

Usage

py_config(session = NULL)

Arguments

session

Pyodide session; defaults to the active one.

Value

A list with the Python and Pyodide versions and loaded packages.

---

Install Python packages

Description

Installs packages into a Pyodide session with micropip. Packages built for Pyodide (such as numpy, pandas and scikit-learn) come from the Pyodide distribution; others come from PyPI and must be pure Python or have WebAssembly wheels.

Usage

py_install(packages, deps = TRUE, session = NULL)

Arguments

packages	Package names, optionally with version specifiers.
deps	Also install the packages' dependencies? Use FALSE for packages whose pinned dependencies can't be met in Pyodide, after installing compatible versions of those dependencies yourself.
session	Pyodide session; defaults to the active one.

Value

NULL, invisibly.

---

The last Python error

Description

The last Python error

Usage

py_last_error()

Value

A list with the Python exception type, message and traceback, or NULL if there hasn't been an error.

---

List installed Python packages

Description

List installed Python packages

Usage

py_list_packages(session = NULL)

Arguments

session

Pyodide session; defaults to the active one.

Value

A data frame of package names, versions and sources.

---

Is a Python module available?

Description

Is a Python module available?

Usage

py_module_available(module, session = NULL)

Arguments

module	Module name.
session	Pyodide session; defaults to the active one.

Value

TRUE if the module can be imported, either because it is installed or because it is in the Pyodide distribution.

---

Work with Python objects

Description

Low-level accessors for Python objects. Usually you use $, [[ and [ instead: x$attr, x[["attr"]] and x[key] (Python x[key], 0-based).

Usage

py_get_attr(x, name)

py_set_attr(x, name, value)

py_has_attr(x, name)

py_list_attributes(x)

py_get_item(x, key)

py_set_item(x, key, value)

py_call(x, ...)

py_len(x)

py_str(x)

py_repr(x)

Arguments

x	A Python object.
name	Attribute name.
value	An R value or Python object.
key	An item key or index.
...	Arguments for the call; named arguments become keyword arguments.

---

Declare Python requirements

Description

Like reticulate::py_require(): declare the Python packages (and Python version) that your code needs, before or after Python has started. Requirements are kept per session and accumulate across calls.

Usage

py_require(
  packages = NULL,
  python_version = NULL,
  deps = TRUE,
  action = c("add", "remove", "set"),
  session = NULL
)

Arguments

packages	Package requirements, such as "numpy" or "pandas>=2". Packages in the Pyodide distribution are used when available; others come from PyPI and must be pure Python or have WebAssembly wheels. Requiring a package that is already listed replaces its version specifier.
python_version	Python version constraints, such as ">=3.12", "3.14" or ">=3.12,<3.15".
deps	Install the packages' dependencies too? Packages required with deps = FALSE are kept in a separate list and installed after the others, without their dependencies. Use this for packages whose pinned dependencies (or Requires-Python) can't be met in Pyodide, and require compatible versions of those dependencies normally.
action	"add" to add requirements, "remove" to remove them (by package name) or "set" to replace the list.
session	Session name. Defaults to the active session, or "default" if no session has started.

Details

• Before the session starts, requirements are only recorded. When pyodide_start() runs (or Python is first used), they are all installed with a single micropip call and the Python version is checked.

• After the session has started, new packages are installed right away. Packages that are already loaded can't be removed, so action = "remove" and action = "set" must not drop packages from a running session; stop it with pyodide_stop() first.

Requirements survive pyodide_stop(), so restarting a session installs them again.

Each Pyodide release ships exactly one Python version, so python_version can't choose an interpreter. It is a check: if the session's Python doesn't satisfy it, py_require() (or pyodide_start()) fails. To get a different Python, start the session with a different pyodide_url.

Value

With no packages or python_version, the session's requirements. Otherwise they are returned invisibly.

Examples

py_require(c("numpy", "pandas>=2"), session = "example")
py_require(python_version = ">=3.12", session = "example")
py_require(session = "example")

---

Run Python code

Description

py_run_string() runs code in the ⁠__main__⁠ module, like reticulate::py_run_string(). py_eval() evaluates a single expression and returns its value. Pyodide packages that the code imports (for example numpy) are loaded automatically. Anything printed by Python appears in R.

Usage

py_run_string(code, convert = TRUE, session = NULL)

py_run_file(file, convert = TRUE, session = NULL)

py_eval(code, convert = TRUE, session = NULL)

Arguments

code	Python code.
convert	Convert results to R values where possible? If FALSE, Python objects are returned.
session	Pyodide session; defaults to the active one.
file	A file in webR's virtual file system.

Value

py_run_string() and py_run_file() return the ⁠__main__⁠ module, invisibly. py_eval() returns the value of the expression.

---

Copy a file into Pyodide's file system

Description

webR and Pyodide have separate virtual file systems. Files whose absolute paths are passed to Python as arguments are copied automatically (see the rpyodide.mirror_files option); use py_upload() to copy other files, such as Python modules to import.

Usage

py_upload(from, to = normalizePath(from, mustWork = TRUE), session = NULL)

Arguments

from	Path of a file in webR's file system.
to	Path in Pyodide's file system. Directories are created as needed.
session	Pyodide session; defaults to the active one.

Value

to, invisibly.

---

List Pyodide sessions

Description

List Pyodide sessions

Usage

pyodide_sessions()

Value

A data frame with one row per session.

---

Start a Pyodide session

Description

Starts a Python interpreter (Pyodide) in its own web worker. Each session is an independent Python environment with its own packages and globals, so several sessions can act like separate virtual environments. Python functions use the active session unless told otherwise. A "default" session is started automatically the first time Python is used.

Usage

pyodide_start(
  name = "default",
  packages = character(),
  pyodide_url = default_pyodide_url(),
  lockfile_url = NULL,
  activate = TRUE,
  timeout = 300
)

Arguments

name	Session name.
packages	Packages to require for this session; they are added to its py_require() list and installed once Python has started.
pyodide_url	URL of the Pyodide distribution.
lockfile_url	Optional URL of a pyodide-lock.json to pin package versions for this session.
activate	Make this the active session?
timeout	Seconds to wait for Pyodide to start.

Value

The session, invisibly.

---

Stop a Pyodide session

Description

Terminates the session's worker (or, for cpython_start() sessions, its Python process). Python objects from that session can no longer be used.

Usage

pyodide_stop(name = .rpyodide$active)

Arguments

name	Session name.

Value

NULL, invisibly.

---

Convert between R and Python

Description

r_to_py() converts an R value to a Python object; py_to_r() converts a Python object to an R value. Vectors of length one become Python scalars, longer vectors become lists, named vectors and lists become dicts, matrices and arrays become NumPy arrays and data frames become pandas DataFrames. Use I() to send a length-one vector as a list.

Usage

r_to_py(x, convert = FALSE, session = NULL)

py_to_r(x)

Arguments

x	An R value or Python object.
convert	For r_to_py(), should values returned from the new object be converted to R?
session	Pyodide session; defaults to the active one.

Value

r_to_py() returns a Python object; py_to_r() returns an R value.

---

Python tuples and dicts

Description

Python tuples and dicts

Usage

tuple(..., session = NULL)

dict(..., session = NULL)

Arguments

...	Values for the tuple, or name = value pairs for the dict.
session	Pyodide session; defaults to the active one.

Value

A Python object.

---

Choose the active Pyodide session

Description

Choose the active Pyodide session

Usage

use_pyodide(name, ...)

Arguments

name	Name of a session started with pyodide_start(). If it hasn't been started yet, it is started.
...	Passed to pyodide_start() when the session is new.

Value

The previously active session name, invisibly.

---