Struct PyReadwriteArray

Source

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

Expand description

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§

Source §

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

Source

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

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

Source

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.

Source

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

Source

pub fn make_nonwriteable(self) -> PyReadonlyArray<'py, T, D>

Clear the WRITEABLE flag from the underlying NumPy array.

Calling this will prevent any further PyReadwriteArrays from being taken out. Python space can reset this flag, unless the additional flag OWNDATA is unset. Such an array can be created from Rust space by using PyArray::borrow_from_array_bound.

Source §

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

Source

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.

Source §

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

Source

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.

Source §

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

Source

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.

Source §

impl<'py, T> PyReadwriteArray<'py, T, Ix1>
where T: Element,

Source

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

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

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

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

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 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::with_gil(|py| {
    let obj = Bound::new(py, (SubClass, BaseClass)).unwrap();
    assert!(obj.as_super().pyrepr().is_ok());
})

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 send( &self, value: &Bound<'py, PyAny>, ) -> Result<PySendResult<'py>, PyErr>

Sends a value into a python generator. This is the equivalent of calling generator.send(value) in Python. This resumes the generator and continues its execution until the next yield or return statement. If the generator exits without returning a value, this function returns a StopException. The first call to send must be made with None as the argument to start the generator, failing to do so will raise a TypeError.