Struct Lattice

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

Wrapper for https://docs.blender.org/api/latest/bpy.types.Lattice.html

Methods from Deref<Target = PyObject>

pub fn as_ref<'py>( &'py self, _py: Python<'py>, ) -> &'py <T as PyTypeInfo>::AsRefTarget

Borrows a GIL-bound reference to the contained T.

By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python<'py> for any of its methods, which makes calling methods on it more ergonomic.

For native types, this reference is &T. For pyclasses, this is &PyCell<T>.

Note that the lifetime of the returned reference is the shortest of &self and Python<'py>. Consider using Py::into_ref instead if this poses a problem.

Examples

Get access to &PyList from Py<PyList>:

Python::with_gil(|py| {
    let list: Py<PyList> = PyList::empty(py).into();
    let list: &PyList = list.as_ref(py);
    assert_eq!(list.len(), 0);
});

Get access to &PyCell<MyClass> from Py<MyClass>:

#[pyclass]
struct MyClass {}

Python::with_gil(|py| {
    let my_class: Py<MyClass> = Py::new(py, MyClass {}).unwrap();
    let my_class_cell: &PyCell<MyClass> = my_class.as_ref(py);
    assert!(my_class_cell.try_borrow().is_ok());
});

pub fn as_ptr(&self) -> *mut PyObject

Returns the raw FFI pointer represented by self.

Safety

Callers are responsible for ensuring that the pointer does not outlive self.

The reference is borrowed; callers should not decrease the reference count when they are finished with the pointer.

pub fn borrow<'py>(&'py self, py: Python<'py>) -> PyRef<'py, T>

Immutably borrows the value T.

This borrow lasts while the returned PyRef exists. Multiple immutable borrows can be taken out at the same time.

For frozen classes, the simpler get is available.

Equivalent to self.as_ref(py).borrow() - see PyCell::borrow.

Examples

#[pyclass]
struct Foo {
    inner: u8,
}

Python::with_gil(|py| -> PyResult<()> {
    let foo: Py<Foo> = Py::new(py, Foo { inner: 73 })?;
    let inner: &u8 = &foo.borrow(py).inner;

    assert_eq!(*inner, 73);
    Ok(())
})?;

Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use try_borrow.

pub fn borrow_mut<'py>(&'py self, py: Python<'py>) -> PyRefMut<'py, T>

where T: PyClass<Frozen = False>,

Mutably borrows the value T.

This borrow lasts while the returned PyRefMut exists.

Equivalent to self.as_ref(py).borrow_mut() - see PyCell::borrow_mut.

Examples

#[pyclass]
struct Foo {
    inner: u8,
}

Python::with_gil(|py| -> PyResult<()> {
    let foo: Py<Foo> = Py::new(py, Foo { inner: 73 })?;
    foo.borrow_mut(py).inner = 35;

    assert_eq!(foo.borrow(py).inner, 35);
    Ok(())
})?;

Panics

Panics if the value is currently borrowed. For a non-panicking variant, use try_borrow_mut.

pub fn try_borrow<'py>( &'py self, py: Python<'py>, ) -> Result<PyRef<'py, T>, PyBorrowError>

Attempts to immutably borrow the value T, returning an error if the value is currently mutably borrowed.

The borrow lasts while the returned PyRef exists.

This is the non-panicking variant of borrow.

For frozen classes, the simpler get is available.

Equivalent to self.as_ref(py).borrow_mut() - see PyCell::try_borrow.

pub fn try_borrow_mut<'py>( &'py self, py: Python<'py>, ) -> Result<PyRefMut<'py, T>, PyBorrowMutError>

where T: PyClass<Frozen = False>,

Attempts to mutably borrow the value T, returning an error if the value is currently borrowed.

The borrow lasts while the returned PyRefMut exists.

This is the non-panicking variant of borrow_mut.

Equivalent to self.as_ref(py).try_borrow_mut() - see PyCell::try_borrow_mut.

pub fn get(&self) -> &T

where T: PyClass<Frozen = True> + Sync,

Provide an immutable borrow of the value T without acquiring the GIL.

This is available if the class is frozen and Sync.

Examples

use std::sync::atomic::{AtomicUsize, Ordering};

#[pyclass(frozen)]
struct FrozenCounter {
    value: AtomicUsize,
}

let cell  = Python::with_gil(|py| {
    let counter = FrozenCounter { value: AtomicUsize::new(0) };

    Py::new(py, counter).unwrap()
});

cell.get().value.fetch_add(1, Ordering::Relaxed);

pub fn is<U>(&self, o: &U) -> bool

where U: AsPyPointer,

Returns whether self and other point to the same object. To compare the equality of two objects (the == operator), use eq.

This is equivalent to the Python expression self is other.

pub fn get_refcnt(&self, _py: Python<'_>) -> isize

Gets the reference count of the ffi::PyObject pointer.

pub fn clone_ref(&self, py: Python<'_>) -> Py<T>

Makes a clone of self.

This creates another pointer to the same object, increasing its reference count.

You should prefer using this method over Clone if you happen to be holding the GIL already.

Examples

use pyo3::prelude::*;
use pyo3::types::PyDict;

Python::with_gil(|py| {
    let first: Py<PyDict> = PyDict::new(py).into();
    let second = Py::clone_ref(&first, py);

    // Both point to the same object
    assert!(first.is(&second));
});

pub fn is_none(&self, _py: Python<'_>) -> bool

Returns whether the object is considered to be None.

This is equivalent to the Python expression self is None.

pub fn is_ellipsis(&self) -> bool

Returns whether the object is Ellipsis, e.g. ....

This is equivalent to the Python expression self is ....

pub fn is_true(&self, py: Python<'_>) -> Result<bool, PyErr>

Returns whether the object is considered to be true.

This is equivalent to the Python expression bool(self).

pub fn extract<'p, D>(&'p self, py: Python<'p>) -> Result<D, PyErr>

where D: FromPyObject<'p>,

Extracts some type from the Python object.

This is a wrapper function around FromPyObject::extract().

pub fn getattr<N>( &self, py: Python<'_>, attr_name: N, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPy<Py<PyString>>,

Retrieves an attribute value.

This is equivalent to the Python expression self.attr_name.

If calling this method becomes performance-critical, the intern! macro can be used to intern attr_name, thereby avoiding repeated temporary allocations of Python strings.

Example: intern!ing the attribute name

#[pyfunction]
fn version(sys: Py<PyModule>, py: Python<'_>) -> PyResult<PyObject> {
    sys.getattr(py, intern!(py, "version"))
}

pub fn setattr<N, V>( &self, py: Python<'_>, attr_name: N, value: V, ) -> Result<(), PyErr>

where N: IntoPy<Py<PyString>>, V: IntoPy<Py<PyAny>>,

Sets an attribute value.

This is equivalent to the Python expression self.attr_name = value.

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern attr_name.

Example: intern!ing the attribute name

#[pyfunction]
fn set_answer(ob: PyObject, py: Python<'_>) -> PyResult<()> {
    ob.setattr(py, intern!(py, "answer"), 42)
}

pub fn call( &self, py: Python<'_>, args: impl IntoPy<Py<PyTuple>>, kwargs: Option<&PyDict>, ) -> Result<Py<PyAny>, PyErr>

Calls the object.

This is equivalent to the Python expression self(*args, **kwargs).

pub fn call1( &self, py: Python<'_>, args: impl IntoPy<Py<PyTuple>>, ) -> Result<Py<PyAny>, PyErr>

Calls the object with only positional arguments.

This is equivalent to the Python expression self(*args).

pub fn call0(&self, py: Python<'_>) -> Result<Py<PyAny>, PyErr>

Calls the object without arguments.

This is equivalent to the Python expression self().

pub fn call_method<N, A>( &self, py: Python<'_>, name: N, args: A, kwargs: Option<&PyDict>, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPy<Py<PyString>>, A: IntoPy<Py<PyTuple>>,

Calls a method on the object.

This is equivalent to the Python expression self.name(*args, **kwargs).

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn call_method1<N, A>( &self, py: Python<'_>, name: N, args: A, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPy<Py<PyString>>, A: IntoPy<Py<PyTuple>>,

Calls a method on the object with only positional arguments.

This is equivalent to the Python expression self.name(*args).

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn call_method0<N>( &self, py: Python<'_>, name: N, ) -> Result<Py<PyAny>, PyErr>

where N: IntoPy<Py<PyString>>,

Calls a method on the object with no arguments.

This is equivalent to the Python expression self.name().

To avoid repeated temporary allocations of Python strings, the intern! macro can be used to intern name.

pub fn downcast<'p, T>( &'p self, py: Python<'p>, ) -> Result<&'p T, PyDowncastError<'p>>

where T: PyTryFrom<'p>,

Downcast this PyObject to a concrete Python type or pyclass.

Note that you can often avoid downcasting yourself by just specifying the desired type in function or method signatures. However, manual downcasting is sometimes necessary.

For extracting a Rust-only type, see Py::extract.

Example: Downcasting to a specific Python object

use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::with_gil(|py| {
    let any: PyObject = PyDict::new(py).into();

    assert!(any.downcast::<PyDict>(py).is_ok());
    assert!(any.downcast::<PyList>(py).is_err());
});

Example: Getting a reference to a pyclass

This is useful if you want to mutate a PyObject that might actually be a pyclass.

use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::with_gil(|py| {
    let class: PyObject = Py::new(py, Class { i: 0 }).unwrap().into_py(py);

    let class_cell: &PyCell<Class> = class.downcast(py)?;

    class_cell.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})

pub unsafe fn downcast_unchecked<'p, T>(&'p self, py: Python<'p>) -> &'p T

where T: PyTryFrom<'p>,

Casts the PyObject to a concrete Python object type without checking validity.

Safety

Callers must ensure that the type is valid or risk type confusion.

pub fn as_bytes<'a>(&'a self, _py: Python<'_>) -> &'a [u8]

Gets the Python bytes as a byte slice. Because Python bytes are immutable, the result may be used for as long as the reference to self is held, including when the GIL is released.

pub fn as_ref<'py>(&'py self, _py: Python<'py>) -> &'py PyIterator

Borrows a GIL-bound reference to the PyIterator. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

pub fn as_ref<'py>(&'py self, _py: Python<'py>) -> &'py PyMapping

Borrows a GIL-bound reference to the PyMapping. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

pub fn as_ref<'py>(&'py self, _py: Python<'py>) -> &'py PySequence

Borrows a GIL-bound reference to the PySequence. By binding to the GIL lifetime, this allows the GIL-bound reference to not require Python for any of its methods.

let seq: Py<PySequence> = PyList::empty(py).as_sequence().into();
let seq: &PySequence = seq.as_ref(py);
assert_eq!(seq.len().unwrap(), 0);

Trait Implementations

impl BpyID for Lattice

fn asset_data<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

fn is_embedded_data(&self, py: Python<'_>) -> PyResult<bool>

fn is_evaluated(&self, py: Python<'_>) -> PyResult<bool>

fn is_library_indirect(&self, py: Python<'_>) -> PyResult<bool>

fn is_missing(&self, py: Python<'_>) -> PyResult<bool>

fn is_runtime_data(&self, py: Python<'_>) -> PyResult<bool>

fn set_is_runtime_data(&mut self, py: Python<'_>, value: bool) -> PyResult<()>

fn library<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

fn library_weak_reference<'py>( &'py self, py: Python<'py>, ) -> PyResult<&'py PyAny>

fn name(&self, py: Python<'_>) -> PyResult<String>

fn set_name(&mut self, py: Python<'_>, value: &str) -> PyResult<()>

fn name_full(&self, py: Python<'_>) -> PyResult<String>

fn original<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

fn override_library<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

fn preview<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

fn tag(&self, py: Python<'_>) -> PyResult<bool>

fn set_tag(&mut self, py: Python<'_>, value: bool) -> PyResult<()>

fn use_extra_user(&self, py: Python<'_>) -> PyResult<bool>

fn set_use_extra_user(&mut self, py: Python<'_>, value: bool) -> PyResult<()>

fn use_fake_user(&self, py: Python<'_>) -> PyResult<bool>

fn set_use_fake_user(&mut self, py: Python<'_>, value: bool) -> PyResult<()>

fn users(&self, py: Python<'_>) -> PyResult<u32>

fn evaluated_get<'py>( &'py self, py: Python<'py>, depsgraph: &PyAny, ) -> PyResult<&'py PyAny>

fn copy<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

fn asset_mark(&self, py: Python<'_>) -> PyResult<()>

fn asset_clear(&self, py: Python<'_>) -> PyResult<()>

fn asset_generate_preview(&self, py: Python<'_>) -> PyResult<()>

fn override_create<'py>( &'py self, py: Python<'py>, remap_local_usages: bool, ) -> PyResult<&'py PyAny>

fn override_hierarchy_create<'py>( &'py self, py: Python<'py>, scene: Scene<'_>, view_layer: ViewLayer, reference: Option<impl BpyID>, do_fully_editable: bool, ) -> PyResult<&'py PyAny>

fn override_template_create(&self, py: Python<'_>) -> PyResult<()>

fn user_clear(&self, py: Python<'_>) -> PyResult<()>

fn user_remap(&self, py: Python<'_>, new_id: impl BpyID) -> PyResult<()>

fn make_local<'py>( &'py self, py: Python<'py>, clear_proxy: bool, ) -> PyResult<&'py PyAny>

fn user_of_id(&self, py: Python<'_>, id: impl BpyID) -> PyResult<u32>

fn animation_data_create<'py>( &'py self, py: Python<'py>, ) -> PyResult<&'py PyAny>

fn animation_data_clear(&self, py: Python<'_>) -> PyResult<()>

fn update_tag(&self, py: Python<'_>, refresh: HashSet<String>) -> PyResult<()>

fn preview_ensure<'py>(&'py self, py: Python<'py>) -> PyResult<&'py PyAny>

impl Clone for Lattice

fn clone(&self) -> Lattice

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Lattice

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Lattice

type Target = Py<PyAny>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Lattice

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for Lattice

fn fmt(&self, _derive_more_display_formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&PyAny> for Lattice

fn from(value: &PyAny) -> Self

Converts to this type from the input type.

impl From<Py<PyAny>> for Lattice

fn from(value: PyObject) -> Self

Converts to this type from the input type.

impl FromPyObject<'_> for Lattice

fn extract(value: &PyAny) -> PyResult<Self>

Extracts Self from the source PyObject.

impl ToPyObject for Lattice

fn to_object(&self, py: Python<'_>) -> PyObject

Converts self into a Python object.

impl TryFrom<&Object> for Lattice

type Error = BlError

The type returned in the event of a conversion error.

fn try_from(value: &Object) -> BlResult<Self>

Performs the conversion.

impl TryFrom<Object> for Lattice

type Error = BlError

The type returned in the event of a conversion error.

fn try_from(value: Object) -> BlResult<Self>

Performs the conversion.