Expand description
Raw FFI declarations for Python’s C API.
PyO3 can be used to write native Python modules or run Python code and modules from Rust.
This crate just provides low level bindings to the Python interpreter. It is meant for advanced users only - regular PyO3 users shouldn’t need to interact with this crate at all.
The contents of this crate are not documented here, as it would entail basically copying the documentation from CPython. Consult the Python/C API Reference Manual for up-to-date documentation.
Safety
The functions in this crate lack individual safety documentation, but generally the following apply:
- Pointer arguments have to point to a valid Python object of the correct type, although null pointers are sometimes valid input.
- The vast majority can only be used safely while the GIL is held.
- Some functions have additional safety requirements, consult the Python/C API Reference Manual for more information.
Feature flags
PyO3 uses feature flags to enable you to opt-in to additional functionality. For a detailed description, see the Features chapter of the guide.
Optional feature flags
The following features customize PyO3’s behavior:
abi3: Restricts PyO3’s API to a subset of the full Python API which is guaranteed by PEP 384 to be forward-compatible with future Python versions.extension-module: This will tell the linker to keep the Python symbols unresolved, so that your module can also be used with statically linked Python interpreters. Use this feature when building an extension module.
rustc environment flags
PyO3 uses rustc’s --cfg flags to enable or disable code used for different Python versions.
If you want to do this for your own crate, you can do so with the pyo3-build-config crate.
Py_3_7,Py_3_8,Py_3_9,Py_3_10: Marks code that is only enabled when compiling for a given minimum Python version.Py_LIMITED_API: Marks code enabled when theabi3feature flag is enabled.PyPy- Marks code enabled when compiling for PyPy.
Minimum supported Rust and Python versions
PyO3 supports the following software versions:
- Python 3.7 and up (CPython and PyPy)
- Rust 1.48 and up
Example: Building Python Native modules
PyO3 can be used to generate a native Python module. The easiest way to try this out for the
first time is to use maturin. maturin is a tool for building and publishing Rust-based
Python packages with minimal configuration. The following steps set up some files for an example
Python module, install maturin, and then show how to build and import the Python module.
First, create a new folder (let’s call it string_sum) containing the following two files:
Cargo.toml
[lib]
name = "string_sum"
crate-type = ["cdylib"]
[dependencies.pyo3-ffi]
version = "*"
features = ["extension-module"]src/lib.rs
use std::os::raw::c_char;
use std::ptr;
use pyo3_ffi::*;
#[allow(non_snake_case)]
#[no_mangle]
pub unsafe extern "C" fn PyInit_string_sum() -> *mut PyObject {
let init = PyModuleDef {
m_base: PyModuleDef_HEAD_INIT,
m_name: "string_sum\0".as_ptr() as *const c_char,
m_doc: std::ptr::null(),
m_size: 0,
m_methods: std::ptr::null_mut(),
m_slots: std::ptr::null_mut(),
m_traverse: None,
m_clear: None,
m_free: None,
};
let mptr = PyModule_Create(Box::into_raw(Box::new(init)));
let version = env!("CARGO_PKG_VERSION");
PyModule_AddObject(
mptr,
"__version__\0".as_ptr() as *const c_char,
PyUnicode_FromStringAndSize(version.as_ptr() as *const c_char, version.len() as isize),
);
let wrapped_sum_as_string = PyMethodDef {
ml_name: "sum_as_string\0".as_ptr() as *const c_char,
ml_meth: PyMethodDefPointer {
_PyCFunctionFast: sum_as_string
},
ml_flags: METH_FASTCALL,
ml_doc: "returns the sum of two integers as a string\0".as_ptr() as *const c_char,
};
// PyModule_AddObject can technically fail.
// For more involved applications error checking may be necessary
PyModule_AddObject(
mptr,
"sum_as_string\0".as_ptr() as *const c_char,
PyCFunction_NewEx(
Box::into_raw(Box::new(wrapped_sum_as_string)),
std::ptr::null_mut(),
PyUnicode_InternFromString("string_sum\0".as_ptr() as *const c_char),
),
);
let all = ["__all__\0", "__version__\0", "sum_as_string\0"];
let pyall = PyTuple_New(all.len() as isize);
for (i, obj) in all.iter().enumerate() {
PyTuple_SET_ITEM(
pyall,
i as isize,
PyUnicode_InternFromString(obj.as_ptr() as *const c_char),
)
}
PyModule_AddObject(mptr, "__all__\0".as_ptr() as *const c_char, pyall);
mptr
}
pub unsafe extern "C" fn sum_as_string(
_self: *mut PyObject,
args: *mut *mut PyObject,
nargs: Py_ssize_t,
) -> *mut PyObject {
if nargs != 2 {
return raise_type_error("sum_as_string() expected 2 positional arguments");
}
let arg1 = *args;
if PyLong_Check(arg1) == 0 {
return raise_type_error("sum_as_string() expected an int for positional argument 1");
}
let arg1 = PyLong_AsLong(arg1);
if !PyErr_Occurred().is_null() {
return ptr::null_mut()
}
let arg2 = *args.add(1);
if PyLong_Check(arg2) == 0 {
return raise_type_error("sum_as_string() expected an int for positional argument 2");
}
let arg2 = PyLong_AsLong(arg2);
if !PyErr_Occurred().is_null() {
return ptr::null_mut()
}
let res = (arg1 + arg2).to_string();
PyUnicode_FromStringAndSize(res.as_ptr() as *const c_char, res.len() as isize)
}
#[cold]
#[inline(never)]
fn raise_type_error(msg: &str) -> *mut PyObject {
unsafe {
let err_msg =
PyUnicode_FromStringAndSize(msg.as_ptr() as *const c_char, msg.len() as isize);
PyErr_SetObject(PyExc_TypeError, err_msg);
Py_DECREF(err_msg);
};
std::ptr::null_mut()
}With those two files in place, now maturin needs to be installed. This can be done using
Python’s package manager pip. First, load up a new Python virtualenv, and install maturin
into it:
$ cd string_sum
$ python -m venv .env
$ source .env/bin/activate
$ pip install maturinNow build and execute the module:
$ maturin develop
$ python
>>> import string_sum
>>> string_sum.sum_as_string(5, 20)
'25'As well as with maturin, it is possible to build using setuptools-rust or
manually. Both offer more flexibility than maturin but require further
configuration.
Using Python from Rust
To embed Python into a Rust binary, you need to ensure that your Python installation contains a shared library. The following steps demonstrate how to ensure this (for Ubuntu).
To install the Python shared library on Ubuntu:
sudo apt install python3-devWhile most projects use the safe wrapper provided by pyo3,
you can take a look at the orjson library as an example on how to use pyo3-ffi directly.
For those well versed in C and Rust the tutorials from the CPython documentation
can be easily converted to rust as well.
Modules
Structs
Structure representing a datetime.datetime without a tzinfo member.
Structure representing a datetime.time without a tzinfo member.
Structure representing a datetime.date
Structure representing a datetime.datetime.
Structure representing a datetime.timedelta.
Structure representing a datetime.time.
struct _frame as typedef’ed in pyframe.h
Enums
Constants
Maximum number of dimensions
Set if the type allows subclassing
Objects support garbage collection (see objimp.h)
Set if the type implements the vectorcall protocol (PEP 590)
Objects support type attribute cache
Set if the type object is dynamically allocated
Set if the type is ‘ready’ – fully initialized
Set while the type is being ‘readied’, to prevent recursive ready calls
Statics
built-in ‘object’
built-in ‘super’
built-in ‘type’
Functions
Returns a pointer to a PyDateTime_CAPI instance
Check if op is a PyDateTimeAPI.DateTimeType or subtype.
Check if op’s type is exactly PyDateTimeAPI.DateTimeType.
Retrieve the fold component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 1]
Retrieve the hour component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 23]
Retrieve the microsecond component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 999999]
Retrieve the minute component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 59]
Retrieve the second component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 59]
Retrieve the tzinfo component of a PyDateTime_DateTime.
Returns a pointer to a PyObject that should be either NULL or an instance
of a datetime.tzinfo subclass.
Retrieve the days component of a PyDateTime_Delta.
Retrieve the seconds component of a PyDateTime_Delta.
Retrieve the seconds component of a PyDateTime_Delta.
Retrieve the day component of a PyDateTime_Date or PyDateTime_DateTime.
Returns a signed integer in the interval [1, 31].
Retrieve the month component of a PyDateTime_Date or PyDateTime_DateTime.
Returns a signed integer in the range [1, 12].
Retrieve the year component of a PyDateTime_Date or PyDateTime_DateTime.
Returns a signed integer greater than 0.
Populates the PyDateTimeAPI object
Retrieve the fold component of a PyDateTime_Time.
Returns a signed integer in the interval [0, 1]
Retrieve the hour component of a PyDateTime_Time.
Returns a signed integer in the interval [0, 23]
Retrieve the microsecond component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 999999]
Retrieve the minute component of a PyDateTime_Time.
Returns a signed integer in the interval [0, 59]
Retrieve the second component of a PyDateTime_DateTime.
Returns a signed integer in the interval [0, 59]
Retrieve the tzinfo component of a PyDateTime_Time.
Returns a pointer to a PyObject that should be either NULL or an instance
of a datetime.tzinfo subclass.
Type Check macros
Check if op’s type is exactly PyDateTimeAPI.DateType.
Check if op is a PyDateTimeAPI.DetaType or subtype.
Check if op’s type is exactly PyDateTimeAPI.DeltaType.
Macro, trading safety for speed
Macro, only to be used to fill in brand new lists
Test if an object has a GC head
Check if op is a PyDateTimeAPI.TZInfoType or subtype.
Check if op’s type is exactly PyDateTimeAPI.TZInfoType.
Check if op is a PyDateTimeAPI.TimeType or subtype.
Check if op’s type is exactly PyDateTimeAPI.TimeType.
Macro, trading safety for speed
Macro, only to be used to fill in brand new tuples
Test if a type has a GC head
Test if a type supports weak references
Type Definitions
Unions
Function types used to implement Python callables.