Struct PyReadonlyArray

Source

pub struct PyReadonlyArray<'py, T, D>where
    T: Element,
    D: Dimension,
{ /* private fields */ }

Expand description

Read-only borrow of an array.

An instance of this type ensures that there are no instances of PyReadwriteArray, i.e. that only shared references into the interior of the array can be created safely.

See the module-level documentation for more.

Implementations§

Source §

impl<'py, T, D> PyReadonlyArray<'py, T, D>
where T: Element, D: Dimension,

Source

pub fn as_array(&self) -> ArrayView<'_, T, D>

Provides an immutable array view of the interior of the NumPy array.

Source

pub fn as_slice(&self) -> Result<&[T], NotContiguousError>

Provide an immutable slice view of the interior of the NumPy array if it is contiguous.

Source

pub fn get(&self, index: I) -> Option<&T>
where I: NpyIndex<Dim = D>,

Provide an immutable reference to an element of the NumPy array if the index is within bounds.

Source §

impl<'py, N, D> PyReadonlyArray<'py, N, D>
where N: Scalar + Element, D: Dimension,

Source

pub fn try_as_matrix<R, C, RStride, CStride>( &self, ) -> Option<MatrixView<'_, N, R, C, RStride, CStride>>
where R: Dim, C: Dim, RStride: Dim, CStride: Dim,

Try to convert this array into a nalgebra::MatrixView using the given shape and strides.

Note that nalgebra’s types default to Fortan/column-major standard strides whereas NumPy creates C/row-major strides by default. Furthermore, array views created by slicing into existing arrays will often have non-standard strides.

If you do not fully control the memory layout of a given array, e.g. at your API entry points, it can be useful to opt into nalgebra’s support for dynamic strides, for example

use pyo3::{py_run, ffi::c_str};
use numpy::{get_array_module, PyReadonlyArray2};
use nalgebra::{MatrixView, Const, Dyn};

#[pyfunction]
fn sum_standard_layout<'py>(py: Python<'py>, array: PyReadonlyArray2<'py, f64>) -> Option<f64> {
    let matrix: Option<MatrixView<f64, Const<2>, Const<2>>> = array.try_as_matrix();
    matrix.map(|matrix| matrix.sum())
}

#[pyfunction]
fn sum_dynamic_strides<'py>(py: Python<'py>, array: PyReadonlyArray2<'py, f64>) -> Option<f64> {
    let matrix: Option<MatrixView<f64, Const<2>, Const<2>, Dyn, Dyn>> = array.try_as_matrix();
    matrix.map(|matrix| matrix.sum())
}

Python::attach(|py| {
    let np = py.eval(c_str!("__import__('numpy')"), None, None)?;
    let sum_standard_layout = wrap_pyfunction!(sum_standard_layout)(py)?;
    let sum_dynamic_strides = wrap_pyfunction!(sum_dynamic_strides)(py)?;

    py_run!(py, np sum_standard_layout, r"assert sum_standard_layout(np.ones((2, 2), order='F')) == 4.");
    py_run!(py, np sum_standard_layout, r"assert sum_standard_layout(np.ones((2, 2, 2))[:,:,0]) is None");

    py_run!(py, np sum_dynamic_strides, r"assert sum_dynamic_strides(np.ones((2, 2), order='F')) == 4.");
    py_run!(py, np sum_dynamic_strides, r"assert sum_dynamic_strides(np.ones((2, 2, 2))[:,:,0]) == 4.");
})

Source §

impl<'py, N> PyReadonlyArray<'py, N, Ix1>
where N: Scalar + Element,

Source

pub fn as_matrix(&self) -> DMatrixView<'_, N, Dyn, Dyn>

Convert this one-dimensional array into a nalgebra::DMatrixView using dynamic strides.

§Panics

Panics if the array has negative strides.

Source §

impl<'py, N> PyReadonlyArray<'py, N, Ix2>
where N: Scalar + Element,

Source

pub fn as_matrix(&self) -> DMatrixView<'_, N, Dyn, Dyn>

Convert this two-dimensional array into a nalgebra::DMatrixView using dynamic strides.

§Panics

Panics if the array has negative strides.

Methods from Deref<Target = Bound<'py, PyArray<T, D>>>§

Source

pub fn cast(&self) -> Result<&Bound<'py, U>, DowncastError<'_, 'py>>
where U: PyTypeCheck,

Cast this to a concrete Python type or pyclass.

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

For extracting a Rust-only type, see extract.

This performs a runtime type check using the equivalent of Python’s isinstance(self, U).

§Example: Casting to a specific Python object

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

Python::attach(|py| {
    let dict = PyDict::new(py);
    assert!(dict.is_instance_of::<PyAny>());
    let any = dict.as_any();

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

§Example: Getting a reference to a pyclass

This is useful if you want to mutate a Py<PyAny> that might actually be a pyclass.

use pyo3::prelude::*;

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

Python::attach(|py| {
    let class = Bound::new(py, Class { i: 0 })?.into_any();

    let class_bound: &Bound<'_, Class> = class.cast()?;

    class_bound.borrow_mut().i += 1;

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

Source

pub fn cast_exact(&self) -> Result<&Bound<'py, U>, DowncastError<'_, 'py>>
where U: PyTypeInfo,

Cast this to a concrete Python type or pyclass (but not a subclass of it).

It is almost always better to use cast because it accounts for Python subtyping. Use this method only when you do not want to allow subtypes.

The advantage of this method over cast is that it is faster. The implementation of cast_exact uses the equivalent of the Python expression type(self) is U, whereas cast uses isinstance(self, U).

For extracting a Rust-only type, see extract.

§Example: Casting to a specific Python object but not a subtype

use pyo3::prelude::*;
use pyo3::types::{PyBool, PyInt};

Python::attach(|py| {
    let b = PyBool::new(py, true);
    assert!(b.is_instance_of::<PyBool>());
    let any: &Bound<'_, PyAny> = b.as_any();

    // `bool` is a subtype of `int`, so `cast` will accept a `bool` as an `int`
    // but `cast_exact` will not.
    assert!(any.cast::<PyInt>().is_ok());
    assert!(any.cast_exact::<PyInt>().is_err());

    assert!(any.cast_exact::<PyBool>().is_ok());
});

Source

pub unsafe fn cast_unchecked(&self) -> &Bound<'py, U>

Converts this to a concrete Python type without checking validity.

§Safety

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

Source

pub fn borrow(&self) -> 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.

§Examples

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

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

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

§Panics

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

Source

pub fn borrow_mut(&self) -> PyRefMut<'py, T>
where T: PyClass<Frozen = False>,

Mutably borrows the value T.

This borrow lasts while the returned PyRefMut exists.

§Examples

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

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

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

§Panics

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

Source

pub fn try_borrow(&self) -> 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.

Source

pub fn try_borrow_mut(&self) -> 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.

Source

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,
}

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

    let py_counter = Bound::new(py, counter).unwrap();

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

Source

pub fn as_super(&self) -> &Bound<'py, <T as PyClassImpl>::BaseType>

Upcast this Bound<PyClass> to its base type by reference.

If this type defined an explicit base class in its pyclass declaration (e.g. #[pyclass(extends = BaseType)]), the returned type will be &Bound<BaseType>. If an explicit base class was not declared, the return value will be &Bound<PyAny> (making this method equivalent to as_any).

This method is particularly useful for calling methods defined in an extension trait that has been implemented for Bound<BaseType>.

See also the into_super method to upcast by value, and the PyRef::as_super/PyRefMut::as_super methods for upcasting a pyclass that has already been borrowed.

§Example: Calling a method defined on the `Bound` base type

use pyo3::prelude::*;

#[pyclass(subclass)]
struct BaseClass;

trait MyClassMethods<'py> {
    fn pyrepr(&self) -> PyResult<String>;
}
impl<'py> MyClassMethods<'py> for Bound<'py, BaseClass> {
    fn pyrepr(&self) -> PyResult<String> {
        self.call_method0("__repr__")?.extract()
    }
}

#[pyclass(extends = BaseClass)]
struct SubClass;

Python::attach(|py| {
    let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
    assert!(obj.as_super().pyrepr().is_ok());
})