deprecate PyArray::arange

PyO3 · Mar 25, 2024 · c2a3c39 · c2a3c39
1 parent 31f1eef
commit c2a3c39
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 64 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!(
@@ -641,11 +641,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);
     /// });
@@ -669,11 +669,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;
@@ -704,11 +704,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);
     /// });
@@ -758,11 +758,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));
     /// });
@@ -910,12 +910,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(),
@@ -1241,10 +1241,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]);
     /// });
@@ -1262,11 +1262,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();
     ///
@@ -1362,28 +1362,37 @@ 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>(py: Python<'py>, start: T, stop: T, step: T) -> Bound<'py, Self> {
         unsafe {
             let ptr = PY_ARRAY_API.PyArray_Arange(
                 py,
@@ -1392,7 +1401,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()
         }
     }
 }
@@ -1482,11 +1491,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);
     /// });
@@ -1509,11 +1518,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;
@@ -1543,11 +1552,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);
     /// });
@@ -1604,11 +1613,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));
     /// });
@@ -1742,12 +1751,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(),
@@ -1774,10 +1783,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]);
     /// });
@@ -1795,11 +1804,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
@@ -62,17 +62,17 @@
 //! The second example shows that non-overlapping and interleaved views are also supported.
 //!
 //! ```rust
-//! use numpy::PyArray1;
-//! use pyo3::{types::IntoPyDict, Python};
+//! use numpy::{PyArray1, PyArrayMethods};
+//! use pyo3::{types::{IntoPyDict, PyAnyMethods}, 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
@@ -122,17 +122,17 @@ impl PyUntypedArray {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray1;
-    /// use pyo3::{types::IntoPyDict, Python};
+    /// use numpy::{PyArray1, PyUntypedArrayMethods};
+    /// use pyo3::{types::{IntoPyDict, PyAnyMethods}, 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());
     /// });
@@ -289,17 +289,17 @@ pub trait PyUntypedArrayMethods<'py>: Sealed {
     /// # Example
     ///
     /// ```
-    /// use numpy::PyArray1;
-    /// use pyo3::{types::IntoPyDict, Python};
+    /// use numpy::{PyArray1, PyUntypedArrayMethods};
+    /// use pyo3::{types::{IntoPyDict, PyAnyMethods}, 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]);
     });