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

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

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

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

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

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