deprecate PyArray::arange

PyO3 · Mar 25, 2024 · 52e1330 · 52e1330
1 parent 7ed8268
commit 52e1330
Show file tree

Hide file tree

Showing 6 changed files with 67 additions and 58 deletions.
diff --git a/src/array.rs b/src/array.rs
@@ -81,12 +81,12 @@ use crate::untyped_array::{PyUntypedArray, PyUntypedArrayMethods};
 /// # Example
 ///
 /// ```
-/// use numpy::PyArray;
-/// use ndarray::array;
+/// use numpy::{PyArray, PyArrayMethods};
+/// use ndarray::{array, Array};
 /// use pyo3::Python;
 ///
 /// Python::with_gil(|py| {
-///     let pyarray = PyArray::arange(py, 0., 4., 1.).reshape([2, 2]).unwrap();
+///     let pyarray = PyArray::arange_bound(py, 0., 4., 1.).reshape([2, 2]).unwrap();
 ///     let array = array![[3., 4.], [5., 6.]];
 ///
 ///     assert_eq!(
@@ -640,11 +640,11 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     assert_eq!(unsafe { *pyarray.get([1, 0, 3]).unwrap() }, 11);
     /// });
@@ -668,11 +668,11 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     unsafe {
     ///         *pyarray.get_mut([1, 0, 3]).unwrap() = 42;
@@ -703,11 +703,11 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     assert_eq!(unsafe { *pyarray.uget([1, 0, 3]) }, 11);
     /// });
@@ -757,11 +757,11 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     ///
     /// # Example
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     assert_eq!(pyarray.get_owned([1, 0, 3]), Some(11));
     /// });
@@ -909,12 +909,12 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use ndarray::array;
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 4, 1).reshape([2, 2]).unwrap();
     ///
     ///     assert_eq!(
     ///         pyarray.to_owned_array(),
@@ -1239,10 +1239,10 @@ impl<T: Element, D> PyArray<T, D> {
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0);
+    ///     let pyarray_f = PyArray::arange_bound(py, 2.0, 5.0, 1.0);
     ///     let pyarray_i = unsafe { PyArray::<i64, _>::new_bound(py, [3], false) };
     ///
-    ///     assert!(pyarray_f.copy_to(pyarray_i.as_gil_ref()).is_ok());
+    ///     assert!(pyarray_f.copy_to(&pyarray_i).is_ok());
     ///
     ///     assert_eq!(pyarray_i.readonly().as_slice().unwrap(), &[2, 3, 4]);
     /// });
@@ -1260,11 +1260,11 @@ impl<T: Element, D> PyArray<T, D> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0);
+    ///     let pyarray_f = PyArray::arange_bound(py, 2.0, 5.0, 1.0);
     ///
     ///     let pyarray_i = pyarray_f.cast::<i32>(false).unwrap();
     ///
@@ -1359,28 +1359,36 @@ impl<T: Element, D> PyArray<T, D> {
 }
 
 impl<T: Element + AsPrimitive<f64>> PyArray<T, Ix1> {
+    /// Deprecated form of [`PyArray<T, Ix1>::arange_bound`]
+    #[deprecated(
+        since = "0.21.0",
+        note = "will be replaced by PyArray::arange_bound in the future"
+    )]
+    pub fn arange<'py>(py: Python<'py>, start: T, stop: T, step: T) -> &Self {
+        Self::arange_bound(py, start, stop, step).into_gil_ref()
+    }
     /// Return evenly spaced values within a given interval.
     ///
     /// See [numpy.arange][numpy.arange] for the Python API and [PyArray_Arange][PyArray_Arange] for the C API.
     ///
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 2.0, 4.0, 0.5);
+    ///     let pyarray = PyArray::arange_bound(py, 2.0, 4.0, 0.5);
     ///     assert_eq!(pyarray.readonly().as_slice().unwrap(), &[2.0, 2.5, 3.0, 3.5]);
     ///
-    ///     let pyarray = PyArray::arange(py, -2, 4, 3);
+    ///     let pyarray = PyArray::arange_bound(py, -2, 4, 3);
     ///     assert_eq!(pyarray.readonly().as_slice().unwrap(), &[-2, 1]);
     /// });
     /// ```
     ///
     /// [numpy.arange]: https://numpy.org/doc/stable/reference/generated/numpy.arange.html
     /// [PyArray_Arange]: https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_Arange
-    pub fn arange<'py>(py: Python<'py>, start: T, stop: T, step: T) -> &Self {
+    pub fn arange_bound(py: Python<'_>, start: T, stop: T, step: T) -> Bound<'_, Self> {
         unsafe {
             let ptr = PY_ARRAY_API.PyArray_Arange(
                 py,
@@ -1389,7 +1397,7 @@ impl<T: Element + AsPrimitive<f64>> PyArray<T, Ix1> {
                 step.as_(),
                 T::get_dtype_bound(py).num(),
             );
-            Self::from_owned_ptr(py, ptr)
+            Bound::from_owned_ptr(py, ptr).downcast_into_unchecked()
         }
     }
 }
@@ -1479,11 +1487,11 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     assert_eq!(unsafe { *pyarray.get([1, 0, 3]).unwrap() }, 11);
     /// });
@@ -1506,11 +1514,11 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     unsafe {
     ///         *pyarray.get_mut([1, 0, 3]).unwrap() = 42;
@@ -1540,11 +1548,11 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     assert_eq!(unsafe { *pyarray.uget([1, 0, 3]) }, 11);
     /// });
@@ -1601,11 +1609,11 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     ///
     /// # Example
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 16, 1).reshape([2, 2, 4]).unwrap();
     ///
     ///     assert_eq!(pyarray.get_owned([1, 0, 3]), Some(11));
     /// });
@@ -1739,12 +1747,12 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use ndarray::array;
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 4, 1).reshape([2, 2]).unwrap();
+    ///     let pyarray = PyArray::arange_bound(py, 0, 4, 1).reshape([2, 2]).unwrap();
     ///
     ///     assert_eq!(
     ///         pyarray.to_owned_array(),
@@ -1771,10 +1779,10 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0);
+    ///     let pyarray_f = PyArray::arange_bound(py, 2.0, 5.0, 1.0);
     ///     let pyarray_i = unsafe { PyArray::<i64, _>::new_bound(py, [3], false) };
     ///
-    ///     assert!(pyarray_f.copy_to(pyarray_i.as_gil_ref()).is_ok());
+    ///     assert!(pyarray_f.copy_to(&pyarray_i).is_ok());
     ///
     ///     assert_eq!(pyarray_i.readonly().as_slice().unwrap(), &[2, 3, 4]);
     /// });
@@ -1792,11 +1800,11 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray;
+    /// use numpy::{PyArray, PyArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray_f = PyArray::arange(py, 2.0, 5.0, 1.0);
+    ///     let pyarray_f = PyArray::arange_bound(py, 2.0, 5.0, 1.0);
     ///
     ///     let pyarray_i = pyarray_f.cast::<i32>(false).unwrap();
     ///

diff --git a/src/borrow/mod.rs b/src/borrow/mod.rs
@@ -66,13 +66,13 @@
 //! use pyo3::{types::IntoPyDict, Python};
 //!
 //! Python::with_gil(|py| {
-//!     let array = PyArray1::arange(py, 0.0, 10.0, 1.0);
-//!     let locals = [("array", array)].into_py_dict(py);
+//!     let array = PyArray1::arange_bound(py, 0.0, 10.0, 1.0);
+//!     let locals = [("array", array)].into_py_dict_bound(py);
 //!
-//!     let view1 = py.eval("array[:5]", None, Some(locals)).unwrap().downcast::<PyArray1<f64>>().unwrap();
-//!     let view2 = py.eval("array[5:]", None, Some(locals)).unwrap().downcast::<PyArray1<f64>>().unwrap();
-//!     let view3 = py.eval("array[::2]", None, Some(locals)).unwrap().downcast::<PyArray1<f64>>().unwrap();
-//!     let view4 = py.eval("array[1::2]", None, Some(locals)).unwrap().downcast::<PyArray1<f64>>().unwrap();
+//!     let view1 = py.eval_bound("array[:5]", None, Some(&locals)).unwrap().downcast_into::<PyArray1<f64>>().unwrap();
+//!     let view2 = py.eval_bound("array[5:]", None, Some(&locals)).unwrap().downcast_into::<PyArray1<f64>>().unwrap();
+//!     let view3 = py.eval_bound("array[::2]", None, Some(&locals)).unwrap().downcast_into::<PyArray1<f64>>().unwrap();
+//!     let view4 = py.eval_bound("array[1::2]", None, Some(&locals)).unwrap().downcast_into::<PyArray1<f64>>().unwrap();
 //!
 //!     {
 //!         let _view1 = view1.readwrite();
@@ -562,11 +562,11 @@ where
     /// # Example
     ///
     /// ```
-    /// use numpy::{PyArray, PyUntypedArrayMethods};
+    /// use numpy::{PyArray, PyArrayMethods, PyUntypedArrayMethods};
     /// use pyo3::Python;
     ///
     /// Python::with_gil(|py| {
-    ///     let pyarray = PyArray::arange(py, 0, 10, 1);
+    ///     let pyarray = PyArray::arange_bound(py, 0, 10, 1);
     ///     assert_eq!(pyarray.len(), 10);
     ///
     ///     let pyarray = pyarray.readwrite();

diff --git a/src/sum_products.rs b/src/sum_products.rs
@@ -171,10 +171,10 @@ where
 /// ```
 /// use pyo3::Python;
 /// use ndarray::array;
-/// use numpy::{einsum, pyarray, PyArray, PyArray2};
+/// use numpy::{einsum, pyarray, PyArray, PyArray2, PyArrayMethods};
 ///
 /// Python::with_gil(|py| {
-///     let tensor = PyArray::arange(py, 0, 2 * 3 * 4, 1).reshape([2, 3, 4]).unwrap();
+///     let tensor = PyArray::arange_bound(py, 0, 2 * 3 * 4, 1).reshape([2, 3, 4]).unwrap().into_gil_ref();
 ///     let another_tensor = pyarray![py, [20, 30], [40, 50], [60, 70]];
 ///
 ///     let result: &PyArray2<_> = einsum!("ijk,ji->ik", tensor, another_tensor).unwrap();

diff --git a/src/untyped_array.rs b/src/untyped_array.rs
@@ -126,13 +126,13 @@ impl PyUntypedArray {
     /// use pyo3::{types::IntoPyDict, Python};
     ///
     /// Python::with_gil(|py| {
-    ///     let array = PyArray1::arange(py, 0, 10, 1);
+    ///     let array = PyArray1::arange_bound(py, 0, 10, 1);
     ///     assert!(array.is_contiguous());
     ///
     ///     let view = py
-    ///         .eval("array[::2]", None, Some([("array", array)].into_py_dict(py)))
+    ///         .eval_bound("array[::2]", None, Some(&[("array", array)].into_py_dict_bound(py)))
     ///         .unwrap()
-    ///         .downcast::<PyArray1<i32>>()
+    ///         .downcast_into::<PyArray1<i32>>()
     ///         .unwrap();
     ///     assert!(!view.is_contiguous());
     /// });
@@ -293,13 +293,13 @@ pub trait PyUntypedArrayMethods<'py>: sealed::Sealed {
     /// use pyo3::{types::IntoPyDict, Python};
     ///
     /// Python::with_gil(|py| {
-    ///     let array = PyArray1::arange(py, 0, 10, 1);
+    ///     let array = PyArray1::arange_bound(py, 0, 10, 1);
     ///     assert!(array.is_contiguous());
     ///
     ///     let view = py
-    ///         .eval("array[::2]", None, Some([("array", array)].into_py_dict(py)))
+    ///         .eval_bound("array[::2]", None, Some(&[("array", array)].into_py_dict_bound(py)))
     ///         .unwrap()
-    ///         .downcast::<PyArray1<i32>>()
+    ///         .downcast_into::<PyArray1<i32>>()
     ///         .unwrap();
     ///     assert!(!view.is_contiguous());
     /// });

diff --git a/tests/array.rs b/tests/array.rs
@@ -129,7 +129,7 @@ fn zeros() {
 #[test]
 fn arange() {
     Python::with_gil(|py| {
-        let arr = PyArray::<f64, _>::arange(py, 0.0, 1.0, 0.1);
+        let arr = PyArray::<f64, _>::arange_bound(py, 0.0, 1.0, 0.1);
 
         assert_eq!(arr.ndim(), 1);
         assert_eq!(arr.dims(), Dim([10]));
@@ -488,10 +488,10 @@ fn to_owned_works() {
 #[test]
 fn copy_to_works() {
     Python::with_gil(|py| {
-        let arr1 = PyArray::arange(py, 2.0, 5.0, 1.0);
+        let arr1 = PyArray::arange_bound(py, 2.0, 5.0, 1.0);
         let arr2 = unsafe { PyArray::<i64, _>::new_bound(py, [3], false) };
 
-        arr1.copy_to(arr2.as_gil_ref()).unwrap();
+        arr1.copy_to(&arr2).unwrap();
 
         assert_eq!(arr2.readonly().as_slice().unwrap(), &[2, 3, 4]);
     });

diff --git a/tests/sum_products.rs b/tests/sum_products.rs
@@ -1,4 +1,4 @@
-use numpy::{array, dot, einsum, inner, pyarray, PyArray0, PyArray1, PyArray2};
+use numpy::{array, dot, einsum, inner, pyarray, PyArray0, PyArray1, PyArray2, PyArrayMethods};
 use pyo3::Python;
 
 #[test]
@@ -56,9 +56,10 @@ fn test_inner() {
 #[test]
 fn test_einsum() {
     Python::with_gil(|py| {
-        let a = PyArray1::<i32>::arange(py, 0, 25, 1)
+        let a = PyArray1::<i32>::arange_bound(py, 0, 25, 1)
             .reshape([5, 5])
-            .unwrap();
+            .unwrap()
+            .into_gil_ref();
         let b = pyarray![py, 0, 1, 2, 3, 4];
         let c = pyarray![py, [0, 1, 2], [3, 4, 5]];