concurrent.interpreters — Multiple interpreters in the same process

Added in version 3.14.

Source code: Lib/concurrent/interpreters.py

---

Introduction

The concurrent.interpreters module constructs higher-level interfaces on top of the lower level _interpreters module.

See also

Isolating Extension Modules

how to update an extension module to support multiple interpreters

PEP 554

PEP 734

PEP 684

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

Key details

Before we dive into examples, there are a small number of details to keep in mind about using multiple interpreters:

• isolated, by default

• no implicit threads

• not all PyPI packages support use in multiple interpreters yet

In the context of multiple interpreters, “isolated” means that different interpreters do not share any state. In practice, there is some process-global data they all share, but that is managed by the runtime.

Reference

This module defines the following functions:

concurrent.interpreters.list_all()

Return a list of Interpreter objects, one for each existing interpreter.

concurrent.interpreters.get_current()

Return an Interpreter object for the currently running interpreter.

concurrent.interpreters.get_main()

Return an Interpreter object for the main interpreter.

concurrent.interpreters.create()

Initialize a new (idle) Python interpreter and return a Interpreter object for it.

Interpreter objects

class concurrent.interpreters.Interpreter(id)

A single interpreter in the current process.

Generally, Interpreter shouldn’t be called directly. Instead, use create() or one of the other module functions.

id

(read-only)

The interpreter’s ID.

whence

(read-only)

A string describing where the interpreter came from.

is_running()

Return True if the interpreter is currently executing code in its __main__ module and False otherwise.

close()

Finalize and destroy the interpreter.

prepare_main(ns=None, **kwargs)

Bind “shareable” objects in the interpreter’s __main__ module.

exec(code, /, dedent=True)

Run the given source code in the interpreter (in the current thread).

call(callable, /, *args, **kwargs)

Return the result of calling running the given function in the interpreter (in the current thread).

call_in_thread(callable, /, *args, **kwargs)

Run the given function in the interpreter (in a new thread).

Exceptions

exception concurrent.interpreters.InterpreterError

This exception, a subclass of Exception, is raised when an interpreter-related error happens.

exception concurrent.interpreters.InterpreterNotFoundError

This exception, a subclass of InterpreterError, is raised when the targeted interpreter no longer exists.

exception concurrent.interpreters.ExecutionFailed

This exception, a subclass of InterpreterError, is raised when the running code raised an uncaught exception.

excinfo

A basic snapshot of the exception raised in the other interpreter.

exception concurrent.interpreters.NotShareableError

This exception, a subclass of TypeError, is raised when an object cannot be sent to another interpreter.

Basic usage

Creating an interpreter and running code in it:

from concurrent import interpreters

interp = interpreters.create()

# Run in the current OS thread.

interp.exec('print("spam!")')

interp.exec("""if True:
    print('spam!')
    """)

from textwrap import dedent
interp.exec(dedent("""
    print('spam!')
    """))

def run():
    print('spam!')

interp.call(run)

# Run in new OS thread.

t = interp.call_in_thread(run)
t.join()