Glossary

Many of the terms used in this guide are common to the Python or Rust ecosystem, and accordingly can be found in the Python Glossary, Rust Glossary, or Cargo Glossary.

Below are some terms that are particularly relevant to PyO3 and either are not found in the above glossaries or have a specific meaning in the context of PyO3:

attached

To call into the Python interpreter from Rust, the Rust thread must have an associated Python thread state which is “attached” to the Python interpreter. This is a safety invariant required by the Python C API, which ensures that the Python interpreter can handle exceptions, avoid data races with the garbage collector, etc. The Python::attach method is used to attach the current thread to the Python interpreter and obtain a Python token which can be used to call Python APIs.

extension module

A Python module which is implemeted using native code (e.g. C, C++ or Rust) instead of Python. See also CPython’s documentation on creating extension modules.

GIL-enabled Python

The (current, as of Python 3.14) default build of Python, which depends on the GIL for thread safety.

This was historically the only thread safety strategy before the introduction of free-threaded Python.

Python token

PyO3’s Python<'py> type, which can only exist when the current thread is attached to the Python interpreter. This type is used to call Python APIs and ensures that the safety invariants required by the Python C API are upheld.

smart pointer

Pointers which automatically manage the memory they point to. In particular this guide refers to PyO3’s smart pointers Py<T>, Bound<'py, T>, and Borrowed<'a, 'py, T> which point to Python objects and use Python reference counting to ensure correct memory management.

See also the Rust book’s chapter on smart pointers.

wheel

A precompiled Python package format. Wheels are the standard way to distribute native code in Python packages for common operating systems and Python versions, which avoid the need for users to compile from source. The alternative is known as the “source distribution”, or “sdist”, which requires users to compile the code as part of package installation.