devela::_dep::pyo3::types

Struct PyCapsule

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

Available on crate features dep_pyo3 and std only.

Expand description

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>( py: Python<'_>, value: T, name: Option<CString>, ) -> Result<Bound<'_, PyCapsule>, PyErr> ⓘ
where T: 'static + Send + AssertNotZeroSized,

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>( py: Python<'_>, value: T, name: Option<CString>, ) -> Result<Bound<'_, PyCapsule>, PyErr> ⓘ
where T: 'static + Send + AssertNotZeroSized,

👎Deprecated since 0.23.0: renamed to PyCapsule::new

Deprecated name for PyCapsule::new.

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

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, F>( py: Python<'_>, value: T, name: Option<CString>, destructor: F, ) -> Result<Bound<'_, PyCapsule>, PyErr> ⓘ
where T: 'static + Send + AssertNotZeroSized, F: FnOnce(T, *mut c_void) + Send,

👎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, ) -> Result<&'py T, PyErr> ⓘ

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.