Crate cpython

Rust bindings to the Python interpreter.

Ownership and Lifetimes

In Python, all objects are implicitly reference counted. In rust, we will use the PyObject type to represent a reference to a Python object.

The method clone_ref() (from trait PyClone) can be used to create additional references to the same Python object.

Because all Python objects potentially have multiple owners, the concept of Rust mutability does not apply to Python objects. As a result, this API will allow mutating Python objects even if they are not stored in a mutable Rust variable.

The Python interpreter uses a global interpreter lock (GIL) to ensure thread-safety. This API uses a zero-sized struct Python<'p> as a token to indicate that a function can assume that the GIL is held.

You obtain a Python instance by acquiring the GIL, and have to pass it into all operations that call into the Python runtime.

Python 2.7

The library will use the python3 bindings by default. To use the python2 bindings you must specific the python27 feature explicitly in your Cargo.toml.

[dependencies.cpython]
version = "*"
default-features = false
features = ["python27-sys"]

Error Handling

The vast majority of operations in this library will return PyResult<...>. This is an alias for the type Result<..., PyErr>.

A PyErr represents a Python exception. Errors within the rust-cpython library are also exposed as Python exceptions.

Example

use cpython::{Python, PyDict, PyResult};

fn main() {
    let gil = Python::acquire_gil();
    hello(gil.python()).unwrap();
}

fn hello(py: Python) -> PyResult<()> {
    let sys = py.import("sys")?;
    let version: String = sys.get(py, "version")?.extract(py)?;

    let locals = PyDict::new(py);
    locals.set_item(py, "os", py.import("os")?)?;
    let user: String = py.eval("os.getenv('USER') or os.getenv('USERNAME')", None, Some(&locals))?.extract(py)?;

    println!("Hello {}, I'm Python {}", user, version);
    Ok(())
}

Re-exports

pub use crate::py_class::CompareOp;

Modules

argparse

This module contains logic for parsing a python argument list. See also the macros py_argparse!, py_fn! and py_method!.

buffer

exc

This module contains the python exception types.

py_class

Macros

py_argparse

This macro is used to parse a parameter list into a set of variables.

py_capsule

Macro to retrieve a Python capsule pointing to an array of data, with a layer of caching.

py_capsule_fn

Macro to retrieve a function pointer capsule.

py_class

Defines new python extension class. A py_class! macro invocation generates code that declares a new Python class. Additionally, it generates a Rust struct of the same name, which allows accessing instances of that Python class from Rust.

py_exception

Defines a new exception type.

py_fn

Creates a Python callable object that invokes a Rust function.

py_module_initializer

pyobject_newtype

Structs

GILGuard

RAII type that represents the Global Interpreter Lock acquisition.

GILProtected

Mutex-like wrapper object for data that is protected by the Python GIL.

NoArgs

An empty struct that represents the empty argument list. Corresponds to the empty tuple () in Python.

PyBool

Represents a Python bool.

PyBytes

Represents a Python byte string. Corresponds to str in Python 2, and bytes in Python 3.

PyCapsule

Capsules are the preferred way to export/import C APIs between extension modules, see Providing a C API for an Extension Module.

PyDict

Represents a Python dict.

PyErr

Represents a Python exception that was raised.

PyFloat

Represents a Python float object.

PyInt

In Python 2.x, represents a Python long object. In Python 3.x, represents a Python int object. Both PyInt and PyLong refer to the same type on Python 3.x.

PyIterator

A python iterator object.

PyLeakedRef

An immutably borrowed reference to a leaked value.

PyLeakedRefMut

A mutably borrowed reference to a leaked value.

PyList

Represents a Python list.

PyLong

In Python 2.x, represents a Python long object. In Python 3.x, represents a Python int object. Both PyInt and PyLong refer to the same type on Python 3.x.

PyModule

Represents a Python module object.

PyNone

An empty struct that represents None in Python.

PyObject

Represents a reference to a Python object.

PySequence

Represents a reference to a python object supporting the sequence protocol.

PySet

Represents a Python set.

PySharedRef

A reference to PySharedRefCell owned by a Python object.

PySharedRefCell

A mutable memory location shareable immutably across Python objects.

PyString

Represents a Python string. Corresponds to basestring in Python 2, and str in Python 3.

PyTuple

Represents a Python tuple object.

PyType

Represents a reference to a Python type object.

PyUnicode

Represents a Python string. Corresponds to basestring in Python 2, and str in Python 3.

Python

Marker type that indicates that the GIL is currently held.

PythonObjectDowncastError

UnsafePyLeaked

An immutable reference to PySharedRefCell value, not bound to lifetime.

Enums

PyStringData

Enum of possible Python string representations.

Traits

FromPyObject

FromPyObject is implemented by various types that can be extracted from a Python object.

NumberProtocol

Operations on numeric objects

ObjectProtocol

Trait that contains methods

PyClone

PyDrop

PythonObject

Trait implemented by all Python object types.

PythonObjectWithCheckedDowncast

Trait implemented by Python object types that allow a checked downcast.

PythonObjectWithTypeObject

Trait implemented by Python object types that have a corresponding type object.

RefFromPyObject

RefFromPyObject is implemented by various types that can be extracted as a reference from a Python object. Depending on the input object, the reference may point into memory owned by the Python interpreter; or into a temporary object.

ToPyObject

Conversion trait that allows various objects to be converted into Python objects.

Functions

prepare_freethreaded_python

Prepares the use of Python in a free-threaded context.

Type Aliases

PyResult

Represents the result of a Python call.

Py_hash_t

Py_ssize_t