Struct PyCapsule

pub struct PyCapsule(/* private fields */);

Represents a Python Capsule as described in Capsules:

This subtype of PyObject represents an opaque value, useful for C extension modules who need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

Values of this type are accessed via PyO3’s smart pointers, e.g. as Py<PyCapsule> or Bound<'py, PyCapsule>.

For APIs available on capsule objects, see the PyCapsuleMethods trait which is implemented for Bound<'py, PyCapsule>.

Example

use pyo3::{prelude::*, types::PyCapsule};
use std::ffi::CString;

#[repr(C)]
struct Foo {
    pub val: u32,
}

let r = Python::with_gil(|py| -> PyResult<()> {
    let foo = Foo { val: 123 };
    let name = CString::new("builtins.capsule").unwrap();

    let capsule = PyCapsule::new(py, foo, Some(name.clone()))?;

    let module = PyModule::import(py, "builtins")?;
    module.add("capsule", capsule)?;

    let cap: &Foo = unsafe { PyCapsule::import(py, name.as_ref())? };
    assert_eq!(cap.val, 123);
    Ok(())
});
assert!(r.is_ok());

Implementations

impl PyCapsule

pub fn new<T: 'static + Send + AssertNotZeroSized>( py: Python<'_>, value: T, name: Option<CString>, ) -> PyResult<Bound<'_, Self>>

Constructs a new capsule whose contents are value, associated with name. name is the identifier for the capsule; if it is stored as an attribute of a module, the name should be in the format "modulename.attribute".

It is checked at compile time that the type T is not zero-sized. Rust function items need to be cast to a function pointer (fn(args) -> result) to be put into a capsule.

Example

use pyo3::{prelude::*, types::PyCapsule};
use std::ffi::CString;

Python::with_gil(|py| {
    let name = CString::new("foo").unwrap();
    let capsule = PyCapsule::new(py, 123_u32, Some(name)).unwrap();
    let val = unsafe { capsule.reference::<u32>() };
    assert_eq!(*val, 123);
});

However, attempting to construct a PyCapsule with a zero-sized type will not compile:

use pyo3::{prelude::*, types::PyCapsule};
use std::ffi::CString;

Python::with_gil(|py| {
    let capsule = PyCapsule::new(py, (), None).unwrap();  // Oops! `()` is zero sized!
});

pub fn new_with_destructor<T: 'static + Send + AssertNotZeroSized, F: FnOnce(T, *mut c_void) + Send>( py: Python<'_>, value: T, name: Option<CString>, destructor: F, ) -> PyResult<Bound<'_, Self>>

Constructs a new capsule whose contents are value, associated with name.

Also provides a destructor: when the PyCapsule is destroyed, it will be passed the original object, as well as a *mut c_void which will point to the capsule’s context, if any.

The destructor must be Send, because there is no guarantee which thread it will eventually be called from.

pub unsafe fn import<'py, T>(py: Python<'py>, name: &CStr) -> PyResult<&'py T>

Imports an existing capsule.

The name should match the path to the module attribute exactly in the form of "module.attribute", which should be the same as the name within the capsule.

Safety

It must be known that the capsule imported by name contains an item of type T.

Trait Implementations

impl PyTypeInfo for PyCapsule

const NAME: &'static str = "PyCapsule"

Class name.

const MODULE: Option<&'static str>

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn is_type_of(obj: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl DerefToPyAny for PyCapsule