numpy/borrow/
mod.rs

1//! Types to safely create references into NumPy arrays
2//!
3//! It is assumed that unchecked code - which includes unsafe Rust and Python - is validated by its author
4//! which together with the dynamic borrow checking performed by this crate ensures that
5//! safe Rust code cannot cause undefined behaviour by creating references into NumPy arrays.
6//!
7//! With these borrows established, [references to individual elements][PyReadonlyArray::get] or [reference-based views of whole array][PyReadonlyArray::as_array]
8//! can be created safely. These are then the starting point for algorithms iteraing over and operating on the elements of the array.
9//!
10//! # Examples
11//!
12//! The first example shows that dynamic borrow checking works to constrain
13//! both what safe Rust code can invoke and how it is invoked.
14//!
15//! ```rust
16//! # use std::panic::{catch_unwind, AssertUnwindSafe};
17//! #
18//! use numpy::{PyArray1, PyArrayMethods, npyffi::flags};
19//! use ndarray::Zip;
20//! use pyo3::{Python, Bound};
21//!
22//! fn add(x: &Bound<'_, PyArray1<f64>>, y: &Bound<'_, PyArray1<f64>>, z: &Bound<'_, PyArray1<f64>>) {
23//!     let x1 = x.readonly();
24//!     let y1 = y.readonly();
25//!     let mut z1 = z.readwrite();
26//!
27//!     let x2 = x1.as_array();
28//!     let y2 = y1.as_array();
29//!     let z2 = z1.as_array_mut();
30//!
31//!     Zip::from(x2)
32//!         .and(y2)
33//!         .and(z2)
34//!         .for_each(|x3, y3, z3| *z3 = x3 + y3);
35//!
36//!     // Will fail at runtime due to conflict with `x1`.
37//!     let res = catch_unwind(AssertUnwindSafe(|| {
38//!         let _x4 = x.readwrite();
39//!     }));
40//!     assert!(res.is_err());
41//! }
42//!
43//! Python::with_gil(|py| {
44//!     let x = PyArray1::<f64>::zeros(py, 42, false);
45//!     let y = PyArray1::<f64>::zeros(py, 42, false);
46//!     let z = PyArray1::<f64>::zeros(py, 42, false);
47//!
48//!     // Will work as the three arrays are distinct.
49//!     add(&x, &y, &z);
50//!
51//!     // Will work as `x1` and `y1` are compatible borrows.
52//!     add(&x, &x, &z);
53//!
54//!     // Will fail at runtime due to conflict between `y1` and `z1`.
55//!     let res = catch_unwind(AssertUnwindSafe(|| {
56//!         add(&x, &y, &y);
57//!     }));
58//!     assert!(res.is_err());
59//! });
60//! ```
61//!
62//! The second example shows that non-overlapping and interleaved views are also supported.
63//!
64//! ```rust
65//! use numpy::{PyArray1, PyArrayMethods};
66//! use pyo3::{types::{IntoPyDict, PyAnyMethods}, Python, ffi::c_str};
67//!
68//! # fn main() -> pyo3::PyResult<()> {
69//! Python::with_gil(|py| {
70//!     let array = PyArray1::arange(py, 0.0, 10.0, 1.0);
71//!     let locals = [("array", array)].into_py_dict(py)?;
72//!
73//!     let view1 = py.eval(c_str!("array[:5]"), None, Some(&locals))?.downcast_into::<PyArray1<f64>>()?;
74//!     let view2 = py.eval(c_str!("array[5:]"), None, Some(&locals))?.downcast_into::<PyArray1<f64>>()?;
75//!     let view3 = py.eval(c_str!("array[::2]"), None, Some(&locals))?.downcast_into::<PyArray1<f64>>()?;
76//!     let view4 = py.eval(c_str!("array[1::2]"), None, Some(&locals))?.downcast_into::<PyArray1<f64>>()?;
77//!
78//!     {
79//!         let _view1 = view1.readwrite();
80//!         let _view2 = view2.readwrite();
81//!     }
82//!
83//!     {
84//!         let _view3 = view3.readwrite();
85//!         let _view4 = view4.readwrite();
86//!     }
87//! #   Ok(())
88//! })
89//! # }
90//! ```
91//!
92//! The third example shows that some views are incorrectly rejected since the borrows are over-approximated.
93//!
94//! ```rust
95//! # use std::panic::{catch_unwind, AssertUnwindSafe};
96//! #
97//! use numpy::{PyArray2, PyArrayMethods};
98//! use pyo3::{types::{IntoPyDict, PyAnyMethods}, Python, ffi::c_str};
99//!
100//! # fn main() -> pyo3::PyResult<()> {
101//! Python::with_gil(|py| {
102//!     let array = PyArray2::<f64>::zeros(py, (10, 10), false);
103//!     let locals = [("array", array)].into_py_dict(py)?;
104//!
105//!     let view1 = py.eval(c_str!("array[:, ::3]"), None, Some(&locals))?.downcast_into::<PyArray2<f64>>()?;
106//!     let view2 = py.eval(c_str!("array[:, 1::3]"), None, Some(&locals))?.downcast_into::<PyArray2<f64>>()?;
107//!
108//!     // A false conflict as the views do not actually share any elements.
109//!     let res = catch_unwind(AssertUnwindSafe(|| {
110//!         let _view1 = view1.readwrite();
111//!         let _view2 = view2.readwrite();
112//!     }));
113//!     assert!(res.is_err());
114//! #   Ok(())
115//! })
116//! # }
117//! ```
118//!
119//! # Rationale
120//!
121//! Rust references require aliasing discipline to be maintained, i.e. there must always
122//! exist only a single mutable (aka exclusive) reference or multiple immutable (aka shared) references
123//! for each object, otherwise the program contains undefined behaviour.
124//!
125//! The aim of this module is to ensure that safe Rust code is unable to violate these requirements on its own.
126//! We cannot prevent unchecked code - this includes unsafe Rust, Python or other native code like C or Fortran -
127//! from violating them. Therefore the responsibility to avoid this lies with the author of that code instead of the compiler.
128//! However, assuming that the unchecked code is correct, we can ensure that safe Rust is unable to introduce mistakes
129//! into an otherwise correct program by dynamically checking which arrays are currently borrowed and in what manner.
130//!
131//! This means that we follow the [base object chain][base] of each array to the original allocation backing it and
132//! track which parts of that allocation are covered by the array and thereby ensure that only a single read-write array
133//! or multiple read-only arrays overlapping with that region are borrowed at any time.
134//!
135//! In contrast to Rust references, the mere existence of Python references or raw pointers is not an issue
136//! because these values are not assumed to follow aliasing discipline by the Rust compiler.
137//!
138//! This cannot prevent unchecked code from concurrently modifying an array via callbacks or using multiple threads,
139//! but that would lead to incorrect results even if the code that is interfered with is implemented in another language
140//! which does not require aliasing discipline.
141//!
142//! Concerning multi-threading in particular: While the GIL needs to be acquired to create borrows, they are not bound to the GIL
143//! and will stay active after the GIL is released, for example by calling [`allow_threads`][pyo3::Python::allow_threads].
144//! Borrows also do not provide synchronization, i.e. multiple threads borrowing the same array will lead to runtime panics,
145//! it will not block those threads until already active borrows are released.
146//!
147//! In summary, this crate takes the position that all unchecked code - unsafe Rust, Python, C, Fortran, etc. - must be checked for correctness by its author.
148//! Safe Rust code can then rely on this correctness, but should not be able to introduce memory safety issues on its own. Additionally, dynamic borrow checking
149//! can catch _some_ mistakes introduced by unchecked code, e.g. Python calling a function with the same array as an input and as an output argument.
150//!
151//! # Limitations
152//!
153//! Note that the current implementation of this is an over-approximation: It will consider borrows
154//! potentially conflicting if the initial arrays have the same object at the end of their [base object chain][base].
155//! Then, multiple conditions which are sufficient but not necessary to show the absence of conflicts are checked.
156//!
157//! While this is sufficient to handle common situations like slicing an array with a non-unit step size which divides
158//! the dimension along that axis, there are also cases which it does not handle. For example, if the step size does
159//! not divide the dimension along the sliced axis. Under such conditions, borrows are rejected even though the arrays
160//! do not actually share any elements.
161//!
162//! This does limit the set of programs that can be written using safe Rust in way similar to rustc itself
163//! which ensures that all accepted programs are memory safe but does not necessarily accept all memory safe programs.
164//! However, the unsafe method [`PyArray::as_array_mut`] can be used as an escape hatch.
165//! More involved cases like the example from above may be supported in the future.
166//!
167//! [base]: https://numpy.org/doc/stable/reference/c-api/types-and-structures.html#c.NPY_AO.base
168
169mod shared;
170
171use std::any::type_name;
172use std::fmt;
173use std::ops::Deref;
174
175use ndarray::{
176    ArrayView, ArrayViewMut, Dimension, IntoDimension, Ix0, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6, IxDyn,
177};
178use pyo3::{types::PyAnyMethods, Bound, FromPyObject, PyAny, PyResult};
179
180use crate::array::{PyArray, PyArrayMethods};
181use crate::convert::NpyIndex;
182use crate::dtype::Element;
183use crate::error::{BorrowError, NotContiguousError};
184use crate::npyffi::flags;
185use crate::untyped_array::PyUntypedArrayMethods;
186
187use shared::{acquire, acquire_mut, release, release_mut};
188
189/// Read-only borrow of an array.
190///
191/// An instance of this type ensures that there are no instances of [`PyReadwriteArray`],
192/// i.e. that only shared references into the interior of the array can be created safely.
193///
194/// See the [module-level documentation](self) for more.
195#[repr(transparent)]
196pub struct PyReadonlyArray<'py, T, D>
197where
198    T: Element,
199    D: Dimension,
200{
201    array: Bound<'py, PyArray<T, D>>,
202}
203
204/// Read-only borrow of a zero-dimensional array.
205pub type PyReadonlyArray0<'py, T> = PyReadonlyArray<'py, T, Ix0>;
206
207/// Read-only borrow of a one-dimensional array.
208pub type PyReadonlyArray1<'py, T> = PyReadonlyArray<'py, T, Ix1>;
209
210/// Read-only borrow of a two-dimensional array.
211pub type PyReadonlyArray2<'py, T> = PyReadonlyArray<'py, T, Ix2>;
212
213/// Read-only borrow of a three-dimensional array.
214pub type PyReadonlyArray3<'py, T> = PyReadonlyArray<'py, T, Ix3>;
215
216/// Read-only borrow of a four-dimensional array.
217pub type PyReadonlyArray4<'py, T> = PyReadonlyArray<'py, T, Ix4>;
218
219/// Read-only borrow of a five-dimensional array.
220pub type PyReadonlyArray5<'py, T> = PyReadonlyArray<'py, T, Ix5>;
221
222/// Read-only borrow of a six-dimensional array.
223pub type PyReadonlyArray6<'py, T> = PyReadonlyArray<'py, T, Ix6>;
224
225/// Read-only borrow of an array whose dimensionality is determined at runtime.
226pub type PyReadonlyArrayDyn<'py, T> = PyReadonlyArray<'py, T, IxDyn>;
227
228impl<'py, T, D> Deref for PyReadonlyArray<'py, T, D>
229where
230    T: Element,
231    D: Dimension,
232{
233    type Target = Bound<'py, PyArray<T, D>>;
234
235    fn deref(&self) -> &Self::Target {
236        &self.array
237    }
238}
239
240impl<'py, T: Element, D: Dimension> FromPyObject<'py> for PyReadonlyArray<'py, T, D> {
241    fn extract_bound(obj: &Bound<'py, PyAny>) -> PyResult<Self> {
242        let array = obj.downcast::<PyArray<T, D>>()?;
243        Ok(array.readonly())
244    }
245}
246
247impl<'py, T, D> PyReadonlyArray<'py, T, D>
248where
249    T: Element,
250    D: Dimension,
251{
252    pub(crate) fn try_new(array: Bound<'py, PyArray<T, D>>) -> Result<Self, BorrowError> {
253        acquire(array.py(), array.as_array_ptr())?;
254
255        Ok(Self { array })
256    }
257
258    /// Provides an immutable array view of the interior of the NumPy array.
259    #[inline(always)]
260    pub fn as_array(&self) -> ArrayView<'_, T, D> {
261        // SAFETY: Global borrow flags ensure aliasing discipline.
262        unsafe { self.array.as_array() }
263    }
264
265    /// Provide an immutable slice view of the interior of the NumPy array if it is contiguous.
266    #[inline(always)]
267    pub fn as_slice(&self) -> Result<&[T], NotContiguousError> {
268        // SAFETY: Global borrow flags ensure aliasing discipline.
269        unsafe { self.array.as_slice() }
270    }
271
272    /// Provide an immutable reference to an element of the NumPy array if the index is within bounds.
273    #[inline(always)]
274    pub fn get<I>(&self, index: I) -> Option<&T>
275    where
276        I: NpyIndex<Dim = D>,
277    {
278        unsafe { self.array.get(index) }
279    }
280}
281
282#[cfg(feature = "nalgebra")]
283impl<'py, N, D> PyReadonlyArray<'py, N, D>
284where
285    N: nalgebra::Scalar + Element,
286    D: Dimension,
287{
288    /// Try to convert this array into a [`nalgebra::MatrixView`] using the given shape and strides.
289    ///
290    /// Note that nalgebra's types default to Fortan/column-major standard strides whereas NumPy creates C/row-major strides by default.
291    /// Furthermore, array views created by slicing into existing arrays will often have non-standard strides.
292    ///
293    /// If you do not fully control the memory layout of a given array, e.g. at your API entry points,
294    /// it can be useful to opt into nalgebra's support for [dynamic strides][nalgebra::Dyn], for example
295    ///
296    /// ```rust
297    /// # use pyo3::prelude::*;
298    /// use pyo3::{py_run, ffi::c_str};
299    /// use numpy::{get_array_module, PyReadonlyArray2};
300    /// use nalgebra::{MatrixView, Const, Dyn};
301    ///
302    /// #[pyfunction]
303    /// fn sum_standard_layout<'py>(py: Python<'py>, array: PyReadonlyArray2<'py, f64>) -> Option<f64> {
304    ///     let matrix: Option<MatrixView<f64, Const<2>, Const<2>>> = array.try_as_matrix();
305    ///     matrix.map(|matrix| matrix.sum())
306    /// }
307    ///
308    /// #[pyfunction]
309    /// fn sum_dynamic_strides<'py>(py: Python<'py>, array: PyReadonlyArray2<'py, f64>) -> Option<f64> {
310    ///     let matrix: Option<MatrixView<f64, Const<2>, Const<2>, Dyn, Dyn>> = array.try_as_matrix();
311    ///     matrix.map(|matrix| matrix.sum())
312    /// }
313    ///
314    /// # fn main() -> pyo3::PyResult<()> {
315    /// Python::with_gil(|py| {
316    ///     let np = py.eval(c_str!("__import__('numpy')"), None, None)?;
317    ///     let sum_standard_layout = wrap_pyfunction!(sum_standard_layout)(py)?;
318    ///     let sum_dynamic_strides = wrap_pyfunction!(sum_dynamic_strides)(py)?;
319    ///
320    ///     py_run!(py, np sum_standard_layout, r"assert sum_standard_layout(np.ones((2, 2), order='F')) == 4.");
321    ///     py_run!(py, np sum_standard_layout, r"assert sum_standard_layout(np.ones((2, 2, 2))[:,:,0]) is None");
322    ///
323    ///     py_run!(py, np sum_dynamic_strides, r"assert sum_dynamic_strides(np.ones((2, 2), order='F')) == 4.");
324    ///     py_run!(py, np sum_dynamic_strides, r"assert sum_dynamic_strides(np.ones((2, 2, 2))[:,:,0]) == 4.");
325    /// #   Ok(())
326    /// })
327    /// # }
328    /// ```
329    #[doc(alias = "nalgebra")]
330    pub fn try_as_matrix<R, C, RStride, CStride>(
331        &self,
332    ) -> Option<nalgebra::MatrixView<'_, N, R, C, RStride, CStride>>
333    where
334        R: nalgebra::Dim,
335        C: nalgebra::Dim,
336        RStride: nalgebra::Dim,
337        CStride: nalgebra::Dim,
338    {
339        unsafe { self.array.try_as_matrix() }
340    }
341}
342
343#[cfg(feature = "nalgebra")]
344impl<'py, N> PyReadonlyArray<'py, N, Ix1>
345where
346    N: nalgebra::Scalar + Element,
347{
348    /// Convert this one-dimensional array into a [`nalgebra::DMatrixView`] using dynamic strides.
349    ///
350    /// # Panics
351    ///
352    /// Panics if the array has negative strides.
353    #[doc(alias = "nalgebra")]
354    pub fn as_matrix(&self) -> nalgebra::DMatrixView<'_, N, nalgebra::Dyn, nalgebra::Dyn> {
355        self.try_as_matrix().unwrap()
356    }
357}
358
359#[cfg(feature = "nalgebra")]
360impl<'py, N> PyReadonlyArray<'py, N, Ix2>
361where
362    N: nalgebra::Scalar + Element,
363{
364    /// Convert this two-dimensional array into a [`nalgebra::DMatrixView`] using dynamic strides.
365    ///
366    /// # Panics
367    ///
368    /// Panics if the array has negative strides.
369    #[doc(alias = "nalgebra")]
370    pub fn as_matrix(&self) -> nalgebra::DMatrixView<'_, N, nalgebra::Dyn, nalgebra::Dyn> {
371        self.try_as_matrix().unwrap()
372    }
373}
374
375impl<'py, T, D> Clone for PyReadonlyArray<'py, T, D>
376where
377    T: Element,
378    D: Dimension,
379{
380    fn clone(&self) -> Self {
381        acquire(self.array.py(), self.array.as_array_ptr()).unwrap();
382
383        Self {
384            array: self.array.clone(),
385        }
386    }
387}
388
389impl<'py, T, D> Drop for PyReadonlyArray<'py, T, D>
390where
391    T: Element,
392    D: Dimension,
393{
394    fn drop(&mut self) {
395        release(self.array.py(), self.array.as_array_ptr());
396    }
397}
398
399impl<'py, T, D> fmt::Debug for PyReadonlyArray<'py, T, D>
400where
401    T: Element,
402    D: Dimension,
403{
404    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
405        let name = format!(
406            "PyReadonlyArray<{}, {}>",
407            type_name::<T>(),
408            type_name::<D>()
409        );
410
411        f.debug_struct(&name).finish()
412    }
413}
414
415/// Read-write borrow of an array.
416///
417/// An instance of this type ensures that there are no instances of [`PyReadonlyArray`] and no other instances of [`PyReadwriteArray`],
418/// i.e. that only a single exclusive reference into the interior of the array can be created safely.
419///
420/// See the [module-level documentation](self) for more.
421#[repr(transparent)]
422pub struct PyReadwriteArray<'py, T, D>
423where
424    T: Element,
425    D: Dimension,
426{
427    array: Bound<'py, PyArray<T, D>>,
428}
429
430/// Read-write borrow of a zero-dimensional array.
431pub type PyReadwriteArray0<'py, T> = PyReadwriteArray<'py, T, Ix0>;
432
433/// Read-write borrow of a one-dimensional array.
434pub type PyReadwriteArray1<'py, T> = PyReadwriteArray<'py, T, Ix1>;
435
436/// Read-write borrow of a two-dimensional array.
437pub type PyReadwriteArray2<'py, T> = PyReadwriteArray<'py, T, Ix2>;
438
439/// Read-write borrow of a three-dimensional array.
440pub type PyReadwriteArray3<'py, T> = PyReadwriteArray<'py, T, Ix3>;
441
442/// Read-write borrow of a four-dimensional array.
443pub type PyReadwriteArray4<'py, T> = PyReadwriteArray<'py, T, Ix4>;
444
445/// Read-write borrow of a five-dimensional array.
446pub type PyReadwriteArray5<'py, T> = PyReadwriteArray<'py, T, Ix5>;
447
448/// Read-write borrow of a six-dimensional array.
449pub type PyReadwriteArray6<'py, T> = PyReadwriteArray<'py, T, Ix6>;
450
451/// Read-write borrow of an array whose dimensionality is determined at runtime.
452pub type PyReadwriteArrayDyn<'py, T> = PyReadwriteArray<'py, T, IxDyn>;
453
454impl<'py, T, D> Deref for PyReadwriteArray<'py, T, D>
455where
456    T: Element,
457    D: Dimension,
458{
459    type Target = PyReadonlyArray<'py, T, D>;
460
461    fn deref(&self) -> &Self::Target {
462        // SAFETY: Exclusive references decay implictly into shared references.
463        unsafe { &*(self as *const Self as *const Self::Target) }
464    }
465}
466impl<'py, T, D> From<PyReadwriteArray<'py, T, D>> for PyReadonlyArray<'py, T, D>
467where
468    T: Element,
469    D: Dimension,
470{
471    fn from(value: PyReadwriteArray<'py, T, D>) -> Self {
472        let array = value.array.clone();
473        ::std::mem::drop(value);
474        Self::try_new(array)
475            .expect("releasing an exclusive reference should immediately permit a shared reference")
476    }
477}
478
479impl<'py, T: Element, D: Dimension> FromPyObject<'py> for PyReadwriteArray<'py, T, D> {
480    fn extract_bound(obj: &Bound<'py, PyAny>) -> PyResult<Self> {
481        let array = obj.downcast::<PyArray<T, D>>()?;
482        Ok(array.readwrite())
483    }
484}
485
486impl<'py, T, D> PyReadwriteArray<'py, T, D>
487where
488    T: Element,
489    D: Dimension,
490{
491    pub(crate) fn try_new(array: Bound<'py, PyArray<T, D>>) -> Result<Self, BorrowError> {
492        acquire_mut(array.py(), array.as_array_ptr())?;
493
494        Ok(Self { array })
495    }
496
497    /// Provides a mutable array view of the interior of the NumPy array.
498    #[inline(always)]
499    pub fn as_array_mut(&mut self) -> ArrayViewMut<'_, T, D> {
500        // SAFETY: Global borrow flags ensure aliasing discipline.
501        unsafe { self.array.as_array_mut() }
502    }
503
504    /// Provide a mutable slice view of the interior of the NumPy array if it is contiguous.
505    #[inline(always)]
506    pub fn as_slice_mut(&mut self) -> Result<&mut [T], NotContiguousError> {
507        // SAFETY: Global borrow flags ensure aliasing discipline.
508        unsafe { self.array.as_slice_mut() }
509    }
510
511    /// Provide a mutable reference to an element of the NumPy array if the index is within bounds.
512    #[inline(always)]
513    pub fn get_mut<I>(&mut self, index: I) -> Option<&mut T>
514    where
515        I: NpyIndex<Dim = D>,
516    {
517        unsafe { self.array.get_mut(index) }
518    }
519
520    /// Clear the [`WRITEABLE` flag][writeable] from the underlying NumPy array.
521    ///
522    /// Calling this will prevent any further [PyReadwriteArray]s from being taken out.  Python
523    /// space can reset this flag, unless the additional flag [`OWNDATA`][owndata] is unset.  Such
524    /// an array can be created from Rust space by using [PyArray::borrow_from_array_bound].
525    ///
526    /// [writeable]: https://numpy.org/doc/stable/reference/c-api/array.html#c.NPY_ARRAY_WRITEABLE
527    /// [owndata]: https://numpy.org/doc/stable/reference/c-api/array.html#c.NPY_ARRAY_OWNDATA
528    pub fn make_nonwriteable(self) -> PyReadonlyArray<'py, T, D> {
529        // SAFETY: consuming the only extant mutable reference guarantees we cannot invalidate an
530        // existing reference, nor allow the caller to keep hold of one.
531        unsafe {
532            (*self.as_array_ptr()).flags &= !flags::NPY_ARRAY_WRITEABLE;
533        }
534        self.into()
535    }
536}
537
538#[cfg(feature = "nalgebra")]
539impl<'py, N, D> PyReadwriteArray<'py, N, D>
540where
541    N: nalgebra::Scalar + Element,
542    D: Dimension,
543{
544    /// Try to convert this array into a [`nalgebra::MatrixViewMut`] using the given shape and strides.
545    ///
546    /// See [`PyReadonlyArray::try_as_matrix`] for a discussion of the memory layout requirements.
547    #[doc(alias = "nalgebra")]
548    pub fn try_as_matrix_mut<R, C, RStride, CStride>(
549        &self,
550    ) -> Option<nalgebra::MatrixViewMut<'_, N, R, C, RStride, CStride>>
551    where
552        R: nalgebra::Dim,
553        C: nalgebra::Dim,
554        RStride: nalgebra::Dim,
555        CStride: nalgebra::Dim,
556    {
557        unsafe { self.array.try_as_matrix_mut() }
558    }
559}
560
561#[cfg(feature = "nalgebra")]
562impl<'py, N> PyReadwriteArray<'py, N, Ix1>
563where
564    N: nalgebra::Scalar + Element,
565{
566    /// Convert this one-dimensional array into a [`nalgebra::DMatrixViewMut`] using dynamic strides.
567    ///
568    /// # Panics
569    ///
570    /// Panics if the array has negative strides.
571    #[doc(alias = "nalgebra")]
572    pub fn as_matrix_mut(&self) -> nalgebra::DMatrixViewMut<'_, N, nalgebra::Dyn, nalgebra::Dyn> {
573        self.try_as_matrix_mut().unwrap()
574    }
575}
576
577#[cfg(feature = "nalgebra")]
578impl<'py, N> PyReadwriteArray<'py, N, Ix2>
579where
580    N: nalgebra::Scalar + Element,
581{
582    /// Convert this two-dimensional array into a [`nalgebra::DMatrixViewMut`] using dynamic strides.
583    ///
584    /// # Panics
585    ///
586    /// Panics if the array has negative strides.
587    #[doc(alias = "nalgebra")]
588    pub fn as_matrix_mut(&self) -> nalgebra::DMatrixViewMut<'_, N, nalgebra::Dyn, nalgebra::Dyn> {
589        self.try_as_matrix_mut().unwrap()
590    }
591}
592
593impl<'py, T> PyReadwriteArray<'py, T, Ix1>
594where
595    T: Element,
596{
597    /// Extends or truncates the dimensions of an array.
598    ///
599    /// Safe wrapper for [`PyArray::resize`].
600    ///
601    /// # Example
602    ///
603    /// ```
604    /// use numpy::{PyArray, PyArrayMethods, PyUntypedArrayMethods};
605    /// use pyo3::Python;
606    ///
607    /// Python::with_gil(|py| {
608    ///     let pyarray = PyArray::arange(py, 0, 10, 1);
609    ///     assert_eq!(pyarray.len(), 10);
610    ///
611    ///     let pyarray = pyarray.readwrite();
612    ///     let pyarray = pyarray.resize(100).unwrap();
613    ///     assert_eq!(pyarray.len(), 100);
614    /// });
615    /// ```
616    pub fn resize<ID: IntoDimension>(self, dims: ID) -> PyResult<Self> {
617        // SAFETY: Ownership of `self` proves exclusive access to the interior of the array.
618        unsafe {
619            self.array.resize(dims)?;
620        }
621
622        let py = self.array.py();
623        let ptr = self.array.as_array_ptr();
624
625        // Update the borrow metadata to match the shape change.
626        release_mut(py, ptr);
627        acquire_mut(py, ptr).unwrap();
628
629        Ok(self)
630    }
631}
632
633impl<'py, T, D> Drop for PyReadwriteArray<'py, T, D>
634where
635    T: Element,
636    D: Dimension,
637{
638    fn drop(&mut self) {
639        release_mut(self.array.py(), self.array.as_array_ptr());
640    }
641}
642
643impl<'py, T, D> fmt::Debug for PyReadwriteArray<'py, T, D>
644where
645    T: Element,
646    D: Dimension,
647{
648    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
649        let name = format!(
650            "PyReadwriteArray<{}, {}>",
651            type_name::<T>(),
652            type_name::<D>()
653        );
654
655        f.debug_struct(&name).finish()
656    }
657}
658
659#[cfg(test)]
660mod tests {
661    use super::*;
662
663    use pyo3::{types::IntoPyDict, Python};
664
665    use crate::array::PyArray1;
666    use pyo3::ffi::c_str;
667
668    #[test]
669    fn test_debug_formatting() {
670        Python::with_gil(|py| {
671            let array = PyArray::<f64, _>::zeros(py, (1, 2, 3), false);
672
673            {
674                let shared = array.readonly();
675
676                assert_eq!(
677                    format!("{:?}", shared),
678                    "PyReadonlyArray<f64, ndarray::dimension::dim::Dim<[usize; 3]>>"
679                );
680            }
681
682            {
683                let exclusive = array.readwrite();
684
685                assert_eq!(
686                    format!("{:?}", exclusive),
687                    "PyReadwriteArray<f64, ndarray::dimension::dim::Dim<[usize; 3]>>"
688                );
689            }
690        });
691    }
692
693    #[test]
694    #[should_panic(expected = "AlreadyBorrowed")]
695    fn cannot_clone_exclusive_borrow_via_deref() {
696        Python::with_gil(|py| {
697            let array = PyArray::<f64, _>::zeros(py, (3, 2, 1), false);
698
699            let exclusive = array.readwrite();
700            let _shared = exclusive.clone();
701        });
702    }
703
704    #[test]
705    fn failed_resize_does_not_double_release() {
706        Python::with_gil(|py| {
707            let array = PyArray::<f64, _>::zeros(py, 10, false);
708
709            // The view will make the internal reference check of `PyArray_Resize` fail.
710            let locals = [("array", &array)].into_py_dict(py).unwrap();
711            let _view = py
712                .eval(c_str!("array[:]"), None, Some(&locals))
713                .unwrap()
714                .downcast_into::<PyArray1<f64>>()
715                .unwrap();
716
717            let exclusive = array.readwrite();
718            assert!(exclusive.resize(100).is_err());
719        });
720    }
721
722    #[test]
723    fn ineffective_resize_does_not_conflict() {
724        Python::with_gil(|py| {
725            let array = PyArray::<f64, _>::zeros(py, 10, false);
726
727            let exclusive = array.readwrite();
728            assert!(exclusive.resize(10).is_ok());
729        });
730    }
731}
numpy/borrow/mod.rs

numpy/borrow/
mod.rs
