Struct numpy::PyReadonlyArray [−][src]
pub struct PyReadonlyArray<'py, T, D> { /* fields omitted */ }
Expand description
Readonly reference of PyArray
.
This struct ensures that the internal array is not writeable while holding PyReadonlyArray
.
We use a simple trick for this: modifying the internal flag of the array when creating
PyReadonlyArray
and recover the original flag when it drops.
So, importantly, it does not recover the original flag when it does not drop
(e.g., by the use of IntoPy::intopy
or std::mem::forget
)
and then the internal array remains readonly.
Example
In this example, we get a ‘temporal’ readonly array and the internal array becomes writeble again after it drops.
use numpy::{PyArray, npyffi::NPY_ARRAY_WRITEABLE}; pyo3::Python::with_gil(|py| { let py_array = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap(); { let readonly = py_array.readonly(); // The internal array is not writeable now. pyo3::py_run!(py, py_array, "assert not py_array.flags['WRITEABLE']"); } // After the `readonly` drops, the internal array gets writeable again. pyo3::py_run!(py, py_array, "assert py_array.flags['WRITEABLE']"); });
However, if we convert the PyReadonlyArray
directly into PyObject
,
the internal array remains readonly.
use numpy::{PyArray, npyffi::NPY_ARRAY_WRITEABLE}; use pyo3::{IntoPy, PyObject, Python}; pyo3::Python::with_gil(|py| { let py_array = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap(); let obj: PyObject = { let readonly = py_array.readonly(); // The internal array is not writeable now. pyo3::py_run!(py, py_array, "assert not py_array.flags['WRITEABLE']"); readonly.into_py(py) }; // The internal array remains readonly. pyo3::py_run!(py, py_array, "assert py_array.flags['WRITEABLE']"); });
Implementations
Returns the immutable view of the internal data of PyArray
as slice.
Returns ErrorKind::NotContiguous
if the internal array is not contiguous.
Example
use numpy::{PyArray, PyArray1}; use pyo3::types::IntoPyDict; pyo3::Python::with_gil(|py| { let py_array = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap(); let readonly = py_array.readonly(); assert_eq!(readonly.as_slice().unwrap(), &[0, 1, 2, 3]); let locals = [("np", numpy::get_array_module(py).unwrap())].into_py_dict(py); let not_contiguous: &PyArray1<i32> = py .eval("np.arange(10)[::2]", Some(locals), None) .unwrap() .downcast() .unwrap(); assert!(not_contiguous.readonly().as_slice().is_err()); });
Get the immutable view of the internal data of PyArray
, as
ndarray::ArrayView
.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let array = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap(); let readonly = array.readonly(); assert_eq!(readonly.as_array(), array![[0, 1], [2, 3]]); });
Get an immutable reference of the specified element, with checking the passed index is valid.
See NpyIndex for what types you can use as index.
If you pass an invalid index to this function, it returns None
.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let arr = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap().readonly(); assert_eq!(*arr.get([1, 0, 3]).unwrap(), 11); assert!(arr.get([2, 0, 3]).is_none()); });
For fixed dimension arrays, passing an index with invalid dimension causes compile error.
use numpy::PyArray; pyo3::Python::with_gil(|py| { let arr = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap().readonly(); let a = arr.get([1, 2]); // Compile Error! });
However, for dinamic arrays, we cannot raise a compile error and just returns None
.
use numpy::PyArray; pyo3::Python::with_gil(|py| { let arr = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap().readonly(); let arr = arr.to_dyn().readonly(); assert!(arr.get([1, 2].as_ref()).is_none()); });
Iterates all elements of this array. See NpySingleIter for more.
Methods from Deref<Target = PyArray<T, D>>
Gets a raw PyArrayObject
pointer.
Returns dtype
of the array.
Counterpart of array.dtype
in Python.
Example
pyo3::Python::with_gil(|py| { let array = numpy::PyArray::from_vec(py, vec![1, 2, 3i32]); let dtype = array.dtype(); assert_eq!(dtype.get_datatype().unwrap(), numpy::DataType::Int32); });
Returns a temporally unwriteable reference of the array.
Returns true
if the internal data of the array is C-style contiguous
(default of numpy and ndarray) or Fortran-style contiguous.
Example
use pyo3::types::IntoPyDict; pyo3::Python::with_gil(|py| { let array = numpy::PyArray::arange(py, 0, 10, 1); assert!(array.is_contiguous()); let locals = [("np", numpy::get_array_module(py).unwrap())].into_py_dict(py); let not_contiguous: &numpy::PyArray1<f32> = py .eval("np.zeros((3, 5))[::2, 4]", Some(locals), None) .unwrap() .downcast() .unwrap(); assert!(!not_contiguous.is_contiguous()); });
Returns true
if the internal data of the array is Fortran-style contiguous.
Returns true
if the internal data of the array is C-style contiguous.
Get Py<PyArray>
from &PyArray
, which is the owned wrapper of PyObject.
You can use this method when you have to avoid lifetime annotation to your function args
or return types, like used with pyo3’s pymethod
.
Example
use numpy::PyArray1; fn return_py_array() -> pyo3::Py<PyArray1<i32>> { pyo3::Python::with_gil(|py| PyArray1::zeros(py, [5], false).to_owned()) } let array = return_py_array(); pyo3::Python::with_gil(|py| { assert_eq!(array.as_ref(py).readonly().as_slice().unwrap(), &[0, 0, 0, 0, 0]); });
Returns the number of dimensions in the array.
Same as numpy.ndarray.ndim
Example
use numpy::PyArray3; pyo3::Python::with_gil(|py| { let arr = PyArray3::<f64>::new(py, [4, 5, 6], false); assert_eq!(arr.ndim(), 3); });
Returns a slice which contains how many bytes you need to jump to the next row.
Same as numpy.ndarray.strides
Example
use numpy::PyArray3; pyo3::Python::with_gil(|py| { let arr = PyArray3::<f64>::new(py, [4, 5, 6], false); assert_eq!(arr.strides(), &[240, 48, 8]); });
Returns a slice which contains dimmensions of the array.
Same as numpy.ndarray.shape
Example
use numpy::PyArray3; pyo3::Python::with_gil(|py| { let arr = PyArray3::<f64>::new(py, [4, 5, 6], false); assert_eq!(arr.shape(), &[4, 5, 6]); });
Returns the immutable view of the internal data of PyArray
as slice.
Please consider the use of safe alternatives
(PyReadonlyArray::as_slice
, as_cell_slice
or to_vec
) instead of this.
Safety
If the internal array is not readonly and can be mutated from Python code, holding the slice might cause undefined behavior.
Returns the view of the internal data of PyArray
as &[Cell<T>]
.
Returns the view of the internal data of PyArray
as mutable slice.
Safety
If another reference to the internal data exists(e.g., &[T]
or ArrayView
),
it might cause undefined behavior.
In such case, please consider the use of as_cell_slice
,
Get the immutable reference of the specified element, with checking the passed index is valid.
Please consider the use of safe alternatives
(PyReadonlyArray::get
or get_owned
) instead of this.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let arr = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap(); assert_eq!(*unsafe { arr.get([1, 0, 3]) }.unwrap(), 11); });
Safety
If the internal array is not readonly and can be mutated from Python code, holding the slice might cause undefined behavior.
Get the immutable reference of the specified element, without checking the passed index is valid.
See NpyIndex for what types you can use as index.
Passing an invalid index can cause undefined behavior(mostly SIGSEGV).
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let arr = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap(); assert_eq!(unsafe { *arr.uget([1, 0, 3]) }, 11); });
Same as uget, but returns &mut T
.
Get dynamic dimensioned array from fixed dimension array.
Returns the copy of the internal data of PyArray
to Vec
.
Returns ErrorKind::NotContiguous
if the internal array is not contiguous.
See also as_slice
Example
use numpy::PyArray2; use pyo3::types::IntoPyDict; pyo3::Python::with_gil(|py| { let locals = [("np", numpy::get_array_module(py).unwrap())].into_py_dict(py); let array: &PyArray2<i64> = py .eval("np.array([[0, 1], [2, 3]], dtype='int64')", Some(locals), None) .unwrap() .downcast() .unwrap(); assert_eq!(array.to_vec().unwrap(), vec![0, 1, 2, 3]); });
Get the immutable view of the internal data of PyArray
, as
ndarray::ArrayView
.
Please consider the use of safe alternatives
(PyReadonlyArray::as_array
or to_array
) instead of this.
Safety
If the internal array is not readonly and can be mutated from Python code,
holding the ArrayView
might cause undefined behavior.
Get a copy of PyArray
as
ndarray::Array
.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let py_array = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap(); assert_eq!( py_array.to_owned_array(), array![[0, 1], [2, 3]] ) });
Extends or trancates the length of 1 dimension PyArray.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let pyarray = PyArray::arange(py, 0, 10, 1); assert_eq!(pyarray.len(), 10); pyarray.resize(100).unwrap(); assert_eq!(pyarray.len(), 100); });
Iterates all elements of this array. See NpySingleIter for more.
Copies self into other
, performing a data-type conversion if necessary.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0); let pyarray_i = PyArray::<i64, _>::new(py, [3], false); assert!(pyarray_f.copy_to(pyarray_i).is_ok()); assert_eq!(pyarray_i.readonly().as_slice().unwrap(), &[2, 3, 4]); });
Cast the PyArray<T>
to PyArray<U>
, by allocating a new array.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0); let pyarray_i = pyarray_f.cast::<i32>(false).unwrap(); assert!(pyarray_f.copy_to(pyarray_i).is_ok()); assert_eq!(pyarray_i.readonly().as_slice().unwrap(), &[2, 3, 4]); });
Construct a new array which has same values as self, same matrix order, but has different
dimensions specified by dims
.
Since a returned array can contain a same pointer as self, we highly recommend to drop an
old array, if this method returns Ok
.
Example
use numpy::PyArray; pyo3::Python::with_gil(|py| { let array = PyArray::from_exact_iter(py, 0..9); let array = array.reshape([3, 3]).unwrap(); assert_eq!(array.readonly().as_array(), array![[0, 1, 2], [3, 4, 5], [6, 7, 8]]); assert!(array.reshape([5]).is_err()); });
pub fn reshape_with_order<'py, ID, D2>(
&'py self,
dims: ID,
order: NPY_ORDER
) -> PyResult<&'py PyArray<T, D2>> where
ID: IntoDimension<Dim = D2>,
D2: Dimension,
pub fn reshape_with_order<'py, ID, D2>(
&'py self,
dims: ID,
order: NPY_ORDER
) -> PyResult<&'py PyArray<T, D2>> where
ID: IntoDimension<Dim = D2>,
D2: Dimension,
Same as reshape, but you can change the order of returned matrix.
Trait Implementations
Performs the conversion.
Auto Trait Implementations
impl<'py, T, D> !RefUnwindSafe for PyReadonlyArray<'py, T, D>
impl<'py, T, D> !Send for PyReadonlyArray<'py, T, D>
impl<'py, T, D> !Sync for PyReadonlyArray<'py, T, D>
impl<'py, T, D> Unpin for PyReadonlyArray<'py, T, D>
impl<'py, T, D> !UnwindSafe for PyReadonlyArray<'py, T, D>