Merge pull request #147 from kngwyu/unsafe-get

Introduce PyReadonlyArray::get and Make PyArray::get unsafe

Author: kngwyu

CHANGELOG.md

@@ -1,9 +1,13 @@
 # Changelog
+- Unreleased
+  - `PyArray::get` is now unsafe.
+  - Introduce `PyArray::get_owned` and `PyReadonlyArray::get`.
+
 - v0.10.0
-  - Remove `ErrorKind` and introduce some concrete error types
+  - Remove `ErrorKind` and introduce some concrete error types.
   - `PyArray::as_slice`, `PyArray::as_slice_mut`, `PyArray::as_array`, and `PyArray::as_array_mut` is now unsafe.
-  - Introduce `PyArray::as_cell_slice`, `PyArray::to_vec`, and `PyArray::to_owned_array`
-  - Rename `TypeNum` trait `Element`, and `NpyDataType` `DataType`
+  - Introduce `PyArray::as_cell_slice`, `PyArray::to_vec`, and `PyArray::to_owned_array`.
+  - Rename `TypeNum` trait `Element`, and `NpyDataType` `DataType`.
 
 - v0.9.0
   - Update PyO3 to 0.10.0

src/array.rs

@@ -77,19 +77,19 @@ use crate::types::Element;
 /// ```
 pub struct PyArray<T, D>(PyAny, PhantomData<T>, PhantomData<D>);
 
-/// one-dimensional array
+/// One-dimensional array.
 pub type PyArray1<T> = PyArray<T, Ix1>;
-/// two-dimensional array
+/// Two-dimensional array.
 pub type PyArray2<T> = PyArray<T, Ix2>;
-/// three-dimensional array
+/// Three-dimensional array.
 pub type PyArray3<T> = PyArray<T, Ix3>;
-/// four-dimensional array
+/// Four-dimensional array.
 pub type PyArray4<T> = PyArray<T, Ix4>;
-/// five-dimensional array
+/// Five-dimensional array.
 pub type PyArray5<T> = PyArray<T, Ix5>;
-/// six-dimensional array
+/// Six-dimensional array.
 pub type PyArray6<T> = PyArray<T, Ix6>;
-/// dynamic-dimensional array
+/// Dynamic-dimensional array.
 pub type PyArrayDyn<T> = PyArray<T, IxDyn>;
 
 /// Returns a array module.
@@ -117,6 +117,12 @@ impl<'a, T, D> std::convert::From<&'a PyArray<T, D>> for &'a PyAny {
     }
 }
 
+impl<T, D> IntoPy<PyObject> for PyArray<T, D> {
+    fn into_py(self, py: Python<'_>) -> PyObject {
+        unsafe { PyObject::from_borrowed_ptr(py, self.as_ptr()) }
+    }
+}
+
 impl<'a, T: Element, D: Dimension> FromPyObject<'a> for &'a PyArray<T, D> {
     // here we do type-check three times
     // 1. Checks if the object is PyArray
@@ -129,14 +135,13 @@ impl<'a, T: Element, D: Dimension> FromPyObject<'a> for &'a PyArray<T, D> {
             }
             &*(ob as *const PyAny as *const PyArray<T, D>)
         };
-        array.type_check()?;
-        Ok(array)
-    }
-}
-
-impl<T, D> IntoPy<PyObject> for PyArray<T, D> {
-    fn into_py(self, py: Python<'_>) -> PyObject {
-        unsafe { PyObject::from_borrowed_ptr(py, self.as_ptr()) }
+        let type_ = unsafe { (*(*array.as_array_ptr()).descr).type_num };
+        let dim = array.shape().len();
+        if T::is_same_type(type_) && D::NDIM.map(|n| n == dim).unwrap_or(true) {
+            Ok(array)
+        } else {
+            Err(ShapeError::new(type_, dim, T::DATA_TYPE, D::NDIM).into())
+        }
     }
 }
 
@@ -435,8 +440,10 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     }
 
     /// Returns the immutable view of the internal data of `PyArray` as slice.
-    /// Please consider the use of [`PyReadonlyArray::as_slice`](../struct.PyReadonlyArray.html)
-    /// instead of this.
+    ///
+    /// Please consider the use of safe alternatives
+    /// ([`PyReadonlyArray::as_slice`](../struct.PyReadonlyArray.html#method.as_slice)
+    /// , [`as_cell_slice`](#method.as_cell_slice) or [`to_vec`](#method.to_vec)) instead of this.
     ///
     /// # Safety
     /// If the internal array is not readonly and can be mutated from Python code,
@@ -491,47 +498,22 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
         IntoPyArray::into_pyarray(arr, py)
     }
 
-    /// Get an immutable reference of a specified element, with checking the passed index is valid.
+    /// Get the immutable reference of the specified element, with checking the passed index is valid.
     ///
-    /// See [NpyIndex](../convert/trait.NpyIndex.html) for what types you can use as index.
-    ///
-    /// If you pass an invalid index to this function, it returns `None`.
+    /// Please consider the use of safe alternatives
+    /// ([`PyReadonlyArray::get`](../struct.PyReadonlyArray.html#method.get)
+    /// or [`get_owned`](#method.get_owned)) instead of this.
     ///
-    /// # Example
-    /// ```
-    /// use numpy::PyArray;
-    /// let gil = pyo3::Python::acquire_gil();
-    /// let arr = PyArray::arange(gil.python(), 0, 16, 1).reshape([2, 2, 4]).unwrap();
-    /// assert_eq!(*arr.get([1, 0, 3]).unwrap(), 11);
-    /// assert!(arr.get([2, 0, 3]).is_none());
-    /// ```
-    ///
-    /// For fixed dimension arrays, passing an index with invalid dimension causes compile error.
-    /// ```compile_fail
-    /// use numpy::PyArray;
-    /// let gil = pyo3::Python::acquire_gil();
-    /// let arr = PyArray::arange(gil.python(), 0, 16, 1).reshape([2, 2, 4]).unwrap();
-    /// let a = arr.get([1, 2]); // Compile Error!
-    /// ```
-    ///
-    /// However, for dinamic arrays, we cannot raise a compile error and just returns `None`.
-    /// ```
-    /// use numpy::PyArray;
-    /// let gil = pyo3::Python::acquire_gil();
-    /// let arr = PyArray::arange(gil.python(), 0, 16, 1).reshape([2, 2, 4]).unwrap();
-    /// let arr = arr.to_dyn();
-    /// assert!(arr.get([1, 2].as_ref()).is_none());
-    /// ```
+    /// # Safety
+    /// If the internal array is not readonly and can be mutated from Python code,
+    /// holding the slice might cause undefined behavior.
     #[inline(always)]
-    pub fn get<Idx>(&self, index: Idx) -> Option<&T>
-    where
-        Idx: NpyIndex<Dim = D>,
-    {
+    pub unsafe fn get(&self, index: impl NpyIndex<Dim = D>) -> Option<&T> {
         let offset = index.get_checked::<T>(self.shape(), self.strides())?;
-        unsafe { Some(&*self.data().offset(offset)) }
+        Some(&*self.data().offset(offset))
     }
 
-    /// Get an immutable reference of a specified element, without checking the
+    /// Get the immutable reference of the specified element, without checking the
     /// passed index is valid.
     ///
     /// See [NpyIndex](../convert/trait.NpyIndex.html) for what types you can use as index.
@@ -573,14 +555,26 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
         unsafe { PyArray::from_borrowed_ptr(python, self.as_ptr()) }
     }
 
-    fn type_check(&self) -> Result<(), ShapeError> {
-        let truth = unsafe { (*(*self.as_array_ptr()).descr).type_num };
-        let dim = self.shape().len();
-        if T::is_same_type(truth) && D::NDIM.map(|n| n == dim).unwrap_or(true) {
-            Ok(())
-        } else {
-            Err(ShapeError::new(truth, dim, T::DATA_TYPE, D::NDIM))
-        }
+    /// Get the copy of the specified element in the array.
+    ///
+    /// See [NpyIndex](../convert/trait.NpyIndex.html) for what types you can use as index.
+    ///
+    /// # Example
+    /// ```
+    /// use numpy::PyArray2;
+    /// use pyo3::types::IntoPyDict;
+    /// let gil = pyo3::Python::acquire_gil();
+    /// let py = gil.python();
+    /// let locals = [("np", numpy::get_array_module(py).unwrap())].into_py_dict(py);
+    /// let array: &PyArray2<i64> = py
+    ///     .eval("np.array([[0, 1], [2, 3]], dtype='int64')", Some(locals), None)
+    ///     .unwrap()
+    ///     .downcast()
+    ///     .unwrap();
+    /// assert_eq!(array.to_vec().unwrap(), vec![0, 1, 2, 3]);
+    /// ```
+    pub fn get_owned(&self, index: impl NpyIndex<Dim = D>) -> Option<T> {
+        unsafe { self.get(index) }.cloned()
     }
 
     /// Returns the copy of the internal data of `PyArray` to `Vec`.
@@ -629,6 +623,10 @@ impl<T: Element, D: Dimension> PyArray<T, D> {
     /// Get the immutable view of the internal data of `PyArray`, as
     /// [`ndarray::ArrayView`](https://docs.rs/ndarray/latest/ndarray/type.ArrayView.html).
     ///
+    /// Please consider the use of safe alternatives
+    /// ([`PyReadonlyArray::as_array`](../struct.PyReadonlyArray.html#method.as_array)
+    /// or [`to_array`](#method.to_array)) instead of this.
+    ///
     /// # Safety
     /// If the internal array is not readonly and can be mutated from Python code,
     /// holding the `ArrayView` might cause undefined behavior.

src/lib.rs

@@ -1,4 +1,4 @@
-#![allow(clippy::missing_safety_doc, clippy::too_many_arguments)] // FIXME
+#![allow(clippy::missing_safety_doc)] // FIXME
 
 //! `rust-numpy` provides Rust interfaces for [NumPy C APIs](https://numpy.org/doc/stable/reference/c-api),
 //! especially for [ndarray](https://numpy.org/doc/stable/reference/arrays.ndarray.html) class.

src/npyffi/mod.rs

@@ -1,7 +1,7 @@
 //! Low-Level bindings for NumPy C API.
 //!
 //! https://numpy.org/doc/stable/reference/c-api
-#![allow(non_camel_case_types)]
+#![allow(non_camel_case_types, clippy::too_many_arguments)]
 
 use pyo3::{ffi, Python};
 use std::ffi::CString;

src/readonly.rs

@@ -1,6 +1,6 @@
 //! Readonly arrays
 use crate::npyffi::NPY_ARRAY_WRITEABLE;
-use crate::{Element, NotContiguousError, PyArray};
+use crate::{Element, NotContiguousError, NpyIndex, PyArray};
 use ndarray::{ArrayView, Dimension, Ix1, Ix2, Ix3, Ix4, Ix5, Ix6, IxDyn};
 use pyo3::{prelude::*, types::PyAny, AsPyPointer};
 
@@ -27,7 +27,7 @@ use pyo3::{prelude::*, types::PyAny, AsPyPointer};
 ///    // The internal array is not writeable now.
 ///    pyo3::py_run!(py, py_array, "assert not py_array.flags['WRITEABLE']");
 /// }
-/// // After `readonly` drops, the internal array gets writeable again.
+/// // After the `readonly` drops, the internal array gets writeable again.
 /// pyo3::py_run!(py, py_array, "assert py_array.flags['WRITEABLE']");
 /// ```
 /// However, if we convert the `PyReadonlyArray` directly into `PyObject`,
@@ -93,21 +93,57 @@ impl<'py, T: Element, D: Dimension> PyReadonlyArray<'py, T, D> {
     pub fn as_array(&self) -> ArrayView<'_, T, D> {
         unsafe { self.array.as_array() }
     }
+
+    /// Get an immutable reference of the specified element, with checking the passed index is valid.
+    ///
+    /// See [NpyIndex](../convert/trait.NpyIndex.html) for what types you can use as index.
+    ///
+    /// If you pass an invalid index to this function, it returns `None`.
+    ///
+    /// # Example
+    /// ```
+    /// use numpy::PyArray;
+    /// let gil = pyo3::Python::acquire_gil();
+    /// let arr = PyArray::arange(gil.python(), 0, 16, 1).reshape([2, 2, 4]).unwrap().readonly();
+    /// assert_eq!(*arr.get([1, 0, 3]).unwrap(), 11);
+    /// assert!(arr.get([2, 0, 3]).is_none());
+    /// ```
+    ///
+    /// For fixed dimension arrays, passing an index with invalid dimension causes compile error.
+    /// ```compile_fail
+    /// use numpy::PyArray;
+    /// let gil = pyo3::Python::acquire_gil();
+    /// let arr = PyArray::arange(gil.python(), 0, 16, 1).reshape([2, 2, 4]).unwrap().readonly();
+    /// let a = arr.get([1, 2]); // Compile Error!
+    /// ```
+    ///
+    /// However, for dinamic arrays, we cannot raise a compile error and just returns `None`.
+    /// ```
+    /// use numpy::PyArray;
+    /// let gil = pyo3::Python::acquire_gil();
+    /// let arr = PyArray::arange(gil.python(), 0, 16, 1).reshape([2, 2, 4]).unwrap();
+    /// let arr = arr.to_dyn().readonly();
+    /// assert!(arr.get([1, 2].as_ref()).is_none());
+    /// ```
+    #[inline(always)]
+    pub fn get(&self, index: impl NpyIndex<Dim = D>) -> Option<&T> {
+        unsafe { self.array.get(index) }
+    }
 }
 
-/// one-dimensional readonly array
+/// One-dimensional readonly array.
 pub type PyReadonlyArray1<'py, T> = PyReadonlyArray<'py, T, Ix1>;
-/// two-dimensional readonly array
+/// Two-dimensional readonly array.
 pub type PyReadonlyArray2<'py, T> = PyReadonlyArray<'py, T, Ix2>;
-/// three-dimensional readonly array
+/// Three-dimensional readonly array.
 pub type PyReadonlyArray3<'py, T> = PyReadonlyArray<'py, T, Ix3>;
-/// four-dimensional readonly array
+/// Four-dimensional readonly array.
 pub type PyReadonlyArray4<'py, T> = PyReadonlyArray<'py, T, Ix4>;
-/// five-dimensional readonly array
+/// Five-dimensional readonly array.
 pub type PyReadonlyArray5<'py, T> = PyReadonlyArray<'py, T, Ix5>;
-/// six-dimensional readonly array
+/// Six-dimensional readonly array.
 pub type PyReadonlyArray6<'py, T> = PyReadonlyArray<'py, T, Ix6>;
-/// dynamic-dimensional readonly array
+/// Dynamic-dimensional readonly array.
 pub type PyReadonlyArrayDyn<'py, T> = PyReadonlyArray<'py, T, IxDyn>;
 
 impl<'py, T: Element, D: Dimension> FromPyObject<'py> for PyReadonlyArray<'py, T, D> {