Struct numpy::borrow::PyReadwriteArray

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

Read-write borrow of an array.

An instance of this type ensures that there are no instances of PyReadonlyArray and no other instances of PyReadwriteArray, i.e. that only a single exclusive reference into the interior of the array can be created safely.

See the module-level documentation for more.

Implementations

impl<'py, T, D> PyReadwriteArray<'py, T, D>

where T: Element, D: Dimension,

pub fn as_array_mut(&mut self) -> ArrayViewMut<'_, T, D>

Provides a mutable array view of the interior of the NumPy array.

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

Provide a mutable slice view of the interior of the NumPy array if it is contiguous.

pub fn get_mut<I>(&mut self, index: I) -> Option<&mut T>

where I: NpyIndex<Dim = D>,

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

impl<'py, N, D> PyReadwriteArray<'py, N, D>

where N: Scalar + Element, D: Dimension,

pub fn try_as_matrix_mut<R, C, RStride, CStride>( &self ) -> Option<MatrixViewMut<'_, N, R, C, RStride, CStride>>

where R: Dim, C: Dim, RStride: Dim, CStride: Dim,

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

See PyReadonlyArray::try_as_matrix for a discussion of the memory layout requirements.

impl<'py, N> PyReadwriteArray<'py, N, Ix1>

where N: Scalar + Element,

pub fn as_matrix_mut(&self) -> DMatrixViewMut<'_, N, Dyn, Dyn>

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

Panics

Panics if the array has negative strides.

impl<'py, N> PyReadwriteArray<'py, N, Ix2>

where N: Scalar + Element,

pub fn as_matrix_mut(&self) -> DMatrixViewMut<'_, N, Dyn, Dyn>

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

Panics

Panics if the array has negative strides.

impl<'py, T> PyReadwriteArray<'py, T, Ix1>

where T: Element,

pub fn resize<ID: IntoDimension>(self, dims: ID) -> PyResult<Self>

Extends or truncates the dimensions of an array.

Safe wrapper for PyArray::resize.

Example

use numpy::{PyArray, PyArrayMethods, PyUntypedArrayMethods};
use pyo3::Python;

Python::with_gil(|py| {
    let pyarray = PyArray::arange_bound(py, 0, 10, 1);
    assert_eq!(pyarray.len(), 10);

    let pyarray = pyarray.readwrite();
    let pyarray = pyarray.resize(100).unwrap();
    assert_eq!(pyarray.len(), 100);
});

Methods from Deref<Target = PyReadonlyArray<'py, T, D>>

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

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

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

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

pub fn get<I>(&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.

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;
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::with_gil(|py| {
    let np = py.eval("__import__('numpy')", None, None).unwrap();
    let sum_standard_layout = wrap_pyfunction!(sum_standard_layout)(py).unwrap();
    let sum_dynamic_strides = wrap_pyfunction!(sum_dynamic_strides)(py).unwrap();

    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.");
});

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.

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

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][Self::get] is available.

Examples

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

Python::with_gil(|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.

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::with_gil(|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.

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][Self::get] is available.

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.

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][macro@crate::pyclass] and Sync.

Examples

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

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

Python::with_gil(|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);
});

pub fn py(&self) -> Python<'py>

Returns the GIL token associated with this object.

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 as_any(&self) -> &Bound<'py, PyAny>

Helper to cast to Bound<'py, PyAny>.

pub fn as_borrowed<'a>(&'a self) -> Borrowed<'a, 'py, T>

Casts this Bound<T> to a Borrowed<T> smart pointer.

pub fn as_unbound(&self) -> &Py<T>

Removes the connection for this Bound<T> from the GIL, allowing it to cross thread boundaries, without transferring ownership.

pub fn as_gil_ref(&'py self) -> &'py <T as HasPyGilRef>::AsRefTarget

where T: HasPyGilRef,

Casts this Bound<T> as the corresponding “GIL Ref” type.

This is a helper to be used for migration from the deprecated “GIL Refs” API.

Trait Implementations

impl<'py, T, D> Debug for PyReadwriteArray<'py, T, D>

where T: Element, D: Dimension,

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

Formats the value using the given formatter.

impl<'py, T, D> Deref for PyReadwriteArray<'py, T, D>

where T: Element, D: Dimension,

type Target = PyReadonlyArray<'py, T, D>

The resulting type after dereferencing.

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

Dereferences the value.

impl<'py, T, D> Drop for PyReadwriteArray<'py, T, D>

where T: Element, D: Dimension,

fn drop(&mut self)

Executes the destructor for this type.

impl<'py, T: Element, D: Dimension> FromPyObject<'py> for PyReadwriteArray<'py, T, D>

fn extract_bound(obj: &Bound<'py, PyAny>) -> PyResult<Self>

Extracts Self from the bound smart pointer obj.

fn extract(ob: &'py PyAny) -> Result<Self, PyErr>

Extracts Self from the source GIL Ref obj.