Add ownership-moving variants of readonly and readwrite

The additional `PyArray` methods `try_into_readonly` and
`try_into_readwrite` allow directly moving the ownership of the `Bound`
pointer backing a `PyArray` into the relevant view type.  This both a)
avoids reference counting overhead and b) allows methods on
`PyReadwriteArray` (like `resize`) that _require_ unique pointer
referencing, not just unique active borrows to function without the user
having to manually drop the base guard.

Author: jakelishman

src/array.rs

@@ -714,7 +714,7 @@ unsafe fn clone_elements<T: Element>(py: Python<'_>, elems: &[T], data_ptr: &mut
 
 /// Implementation of functionality for [`PyArray<T, D>`].
 #[doc(alias = "PyArray")]
-pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
+pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> + Sized {
     /// Access an untyped representation of this array.
     fn as_untyped(&self) -> &Bound<'py, PyUntypedArray>;
 
@@ -956,12 +956,33 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
         T: Element,
         D: Dimension;
 
+    /// Consume `self` into an immutable borrow of the NumPy array
+    fn try_into_readonly(self) -> Result<PyReadonlyArray<'py, T, D>, BorrowError>
+    where
+        T: Element,
+        D: Dimension;
+
     /// Get an immutable borrow of the NumPy array
     fn try_readonly(&self) -> Result<PyReadonlyArray<'py, T, D>, BorrowError>
     where
         T: Element,
         D: Dimension;
 
+    /// Consume `self` into an immutable borrow of the NumPy array
+    ///
+    /// # Panics
+    ///
+    /// Panics if the allocation backing the array is currently mutably borrowed.
+    ///
+    /// For a non-panicking variant, use [`try_readonly`][Self::try_into_readonly].
+    fn into_readonly(self) -> PyReadonlyArray<'py, T, D>
+    where
+        T: Element,
+        D: Dimension,
+    {
+        self.try_into_readonly().unwrap()
+    }
+
     /// Get an immutable borrow of the NumPy array
     ///
     /// # Panics
@@ -977,12 +998,36 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
         self.try_readonly().unwrap()
     }
 
+    /// Consume `self` into an mutable borrow of the NumPy array
+    fn try_into_readwrite(self) -> Result<PyReadwriteArray<'py, T, D>, BorrowError>
+    where
+        T: Element,
+        D: Dimension;
+
     /// Get a mutable borrow of the NumPy array
     fn try_readwrite(&self) -> Result<PyReadwriteArray<'py, T, D>, BorrowError>
     where
         T: Element,
         D: Dimension;
 
+    /// Consume `self` into an mutable borrow of the NumPy array
+    ///
+    /// # Panics
+    ///
+    /// Panics if the allocation backing the array is currently borrowed or
+    /// if the array is [flagged as][flags] not writeable.
+    ///
+    /// For a non-panicking variant, use [`try_readwrite`][Self::try_readwrite].
+    ///
+    /// [flags]: https://numpy.org/doc/stable/reference/generated/numpy.ndarray.flags.html
+    fn into_readwrite(self) -> PyReadwriteArray<'py, T, D>
+    where
+        T: Element,
+        D: Dimension,
+    {
+        self.try_into_readwrite().unwrap()
+    }
+
     /// Get a mutable borrow of the NumPy array
     ///
     /// # Panics
@@ -1467,20 +1512,36 @@ impl<'py, T, D> PyArrayMethods<'py, T, D> for Bound<'py, PyArray<T, D>> {
         slice.map(|slc| T::vec_from_slice(self.py(), slc))
     }
 
+    fn try_into_readonly(self) -> Result<PyReadonlyArray<'py, T, D>, BorrowError>
+    where
+        T: Element,
+        D: Dimension,
+    {
+        PyReadonlyArray::try_new(self)
+    }
+
     fn try_readonly(&self) -> Result<PyReadonlyArray<'py, T, D>, BorrowError>
     where
         T: Element,
         D: Dimension,
     {
-        PyReadonlyArray::try_new(self.clone())
+        self.clone().try_into_readonly()
+    }
+
+    fn try_into_readwrite(self) -> Result<PyReadwriteArray<'py, T, D>, BorrowError>
+    where
+        T: Element,
+        D: Dimension,
+    {
+        PyReadwriteArray::try_new(self)
     }
 
     fn try_readwrite(&self) -> Result<PyReadwriteArray<'py, T, D>, BorrowError>
     where
         T: Element,
         D: Dimension,
     {
-        PyReadwriteArray::try_new(self.clone())
+        self.clone().try_into_readwrite()
     }
 
     unsafe fn as_array(&self) -> ArrayView<'_, T, D>

src/borrow/mod.rs

@@ -606,6 +606,11 @@ where
     ///
     /// Safe wrapper for [`PyArray::resize`].
     ///
+    /// Note that as this mutates a pointed-to object, you cannot hold multiple
+    /// pointers to the array simultaneously; if you begin with a [`PyArray`],
+    /// you will need to use [`PyArrayMethods::into_readwrite`] instead of
+    /// the shared-reference variant.
+    ///
     /// # Example
     ///
     /// ```
@@ -616,7 +621,7 @@ where
     ///     let pyarray = PyArray::arange(py, 0, 10, 1);
     ///     assert_eq!(pyarray.len(), 10);
     ///
-    ///     let pyarray = pyarray.readwrite();
+    ///     let pyarray = pyarray.into_readwrite();
     ///     let pyarray = pyarray.resize(100).unwrap();
     ///     assert_eq!(pyarray.len(), 100);
     /// });
@@ -722,7 +727,7 @@ mod tests {
                 .cast_into::<PyArray1<f64>>()
                 .unwrap();
 
-            let exclusive = array.readwrite();
+            let exclusive = array.into_readwrite();
             assert!(exclusive.resize(100).is_err());
         });
     }
@@ -732,7 +737,7 @@ mod tests {
         Python::attach(|py| {
             let array = PyArray::<f64, _>::zeros(py, 10, false);
 
-            let exclusive = array.readwrite();
+            let exclusive = array.into_readwrite();
             assert!(exclusive.resize(10).is_ok());
         });
     }

tests/borrow.rs

@@ -341,7 +341,7 @@ fn resize_using_exclusive_borrow() {
         let array = PyArray::<f64, _>::zeros(py, 3, false);
         assert_eq!(array.shape(), [3]);
 
-        let mut array = array.readwrite();
+        let mut array = array.into_readwrite();
         assert_eq!(array.as_slice_mut().unwrap(), &[0.0; 3]);
 
         let mut array = array.resize(5).unwrap();