Deprecate the wrappers of the array iterator API.

Author: adamreichold

CHANGELOG.md

@@ -7,6 +7,7 @@
   - Fixed downcasting ignoring element type and dimensionality ([#265](https://github.com/PyO3/rust-numpy/pull/265))
   - `PyArray::new` is now `unsafe`, as it produces uninitialized arrays ([#220](https://github.com/PyO3/rust-numpy/pull/220))
   - `PyArray::iter`, `NpySingleIterBuilder::readwrite` and `NpyMultiIterBuilder::add_readwrite` are now `unsafe`, as they allow aliasing mutable references to be created ([#278/](https://github.com/PyO3/rust-numpy/pull/278))
+  - The `npyiter` module is deprecated as rust-ndarray's facilities for iteration are more flexible and performant ([#280](https://github.com/PyO3/rust-numpy/pull/280))
   - `PyArray::from_exact_iter` does not unsoundly trust `ExactSizeIterator::len` any more ([#262](https://github.com/PyO3/rust-numpy/pull/262))
   - `PyArray::as_cell_slice` was removed as it unsoundly interacts with `PyReadonlyArray` allowing safe code to violate aliasing rules ([#260](https://github.com/PyO3/rust-numpy/pull/260))
   - `rayon` feature is now removed, and directly specifying the feature via `ndarray` dependency is recommended ([#250](https://github.com/PyO3/rust-numpy/pull/250))

src/array.rs

@@ -23,6 +23,7 @@ use crate::convert::{ArrayExt, IntoPyArray, NpyIndex, ToNpyDims, ToPyArray};
 use crate::dtype::{Element, PyArrayDescr};
 use crate::error::{DimensionalityError, FromVecError, NotContiguousError, TypeError};
 use crate::npyffi::{self, npy_intp, NPY_ORDER, PY_ARRAY_API};
+#[allow(deprecated)]
 use crate::npyiter::{NpySingleIter, NpySingleIterBuilder, ReadWrite};
 use crate::readonly::PyReadonlyArray;
 use crate::slice_container::PySliceContainer;
@@ -1079,6 +1080,10 @@ impl<T: Element> PyArray<T, Ix1> {
     ///
     /// The iterator will produce mutable references into the array which must not be
     /// aliased by other references for the life time of the iterator.
+    #[deprecated(
+        note = "The wrappers of the array iterator API are deprecated, please use ndarray's `ArrayBase::iter_mut` instead."
+    )]
+    #[allow(deprecated)]
     pub unsafe fn iter<'py>(&'py self) -> PyResult<NpySingleIter<'py, T, ReadWrite>> {
         NpySingleIterBuilder::readwrite(self).build()
     }

src/lib.rs

@@ -56,6 +56,7 @@ pub use crate::convert::{IntoPyArray, NpyIndex, ToNpyDims, ToPyArray};
 pub use crate::dtype::{dtype, Complex32, Complex64, Element, PyArrayDescr};
 pub use crate::error::{DimensionalityError, FromVecError, NotContiguousError, TypeError};
 pub use crate::npyffi::{PY_ARRAY_API, PY_UFUNC_API};
+#[allow(deprecated)]
 pub use crate::npyiter::{
     IterMode, NpyIterFlag, NpyMultiIter, NpyMultiIterBuilder, NpySingleIter, NpySingleIterBuilder,
 };

src/npyiter.rs

@@ -3,6 +3,12 @@
 //! This module exposes two iterators:
 //! [NpySingleIter](./struct.NpySingleIter.html) and
 //! [NpyMultiIter](./struct.NpyMultiIter.html).
+#![deprecated(
+    note = "The wrappers of the array iterator API are deprecated, please use ndarray's iterators like `Lanes` and `Zip` instead."
+)]
+
+use pyo3::{prelude::*, PyNativeType};
+
 use crate::npyffi::{
     array::PY_ARRAY_API,
     npy_intp, npy_uint32,
@@ -14,7 +20,6 @@ use crate::npyffi::{
     NPY_ITER_ZEROSIZE_OK,
 };
 use crate::{Element, PyArray, PyArrayDyn, PyReadonlyArray};
-use pyo3::{prelude::*, PyNativeType};
 
 use std::marker::PhantomData;
 use std::os::raw::*;

src/readonly.rs

@@ -1,9 +1,12 @@
 //! Readonly arrays
-use crate::npyffi::NPY_ARRAY_WRITEABLE;
-use crate::{Element, NotContiguousError, NpyIndex, PyArray};
 use ndarray::{ArrayView, Dimension, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6, IxDyn};
 use pyo3::{prelude::*, types::PyAny, AsPyPointer};
 
+use crate::npyffi::NPY_ARRAY_WRITEABLE;
+#[allow(deprecated)]
+use crate::npyiter::{NpySingleIter, NpySingleIterBuilder, Readonly};
+use crate::{Element, NotContiguousError, NpyIndex, PyArray};
+
 /// Readonly reference of [`PyArray`](../array/struct.PyArray.html).
 ///
 /// This struct ensures that the internal array is not writeable while holding `PyReadonlyArray`.
@@ -135,8 +138,12 @@ impl<'py, T: Element, D: Dimension> PyReadonlyArray<'py, T, D> {
 
     /// Iterates all elements of this array.
     /// See [NpySingleIter](../npyiter/struct.NpySingleIter.html) for more.
-    pub fn iter(self) -> PyResult<crate::NpySingleIter<'py, T, crate::npyiter::Readonly>> {
-        crate::NpySingleIterBuilder::readonly(self).build()
+    #[deprecated(
+        note = "The wrappers of the array iterator API are deprecated, please use ndarray's `ArrayBase::iter` instead."
+    )]
+    #[allow(deprecated)]
+    pub fn iter(self) -> PyResult<NpySingleIter<'py, T, Readonly>> {
+        NpySingleIterBuilder::readonly(self).build()
     }
 
     pub(crate) fn destruct(self) -> (&'py PyArray<T, D>, bool) {

tests/iter.rs

@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use ndarray::array;
 use numpy::{NpyMultiIterBuilder, NpySingleIterBuilder, PyArray};
 use pyo3::PyResult;