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_bound<T: 'static + Send + AssertNotZeroSized>( py: Python<'_>, value: T, name: Option<CString>, ) -> PyResult<Bound<'_, Self>>

👎Deprecated since 0.23.0: renamed to PyCapsule::new

Deprecated name for PyCapsule::new.

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 fn new_bound_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>>

👎Deprecated since 0.23.0: renamed to PyCapsule::new_with_destructor

Deprecated name for PyCapsule::new_with_destructor.

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 AsRef<PyAny> for PyCapsule

fn as_ref(&self) -> &PyAny

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for PyCapsule

type Target = PyAny

The resulting type after dereferencing.

fn deref(&self) -> &PyAny

Dereferences the value.

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_bound(obj: &Bound<'_, PyAny>) -> bool

👎Deprecated since 0.23.0: renamed to PyTypeInfo::is_type_of

Deprecated name for PyTypeInfo::is_type_of.

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

Returns the safe abstraction over the type object.

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

👎Deprecated since 0.23.0: renamed to PyTypeInfo::type_object

Deprecated name for PyTypeInfo::type_object.

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

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

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

Checks if object is an instance of this type.

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

👎Deprecated since 0.23.0: renamed to PyTypeInfo::is_exact_type_of

Deprecated name for PyTypeInfo::is_exact_type_of.

impl DerefToPyAny for PyCapsule