Cleanup PyArray/PyUFunc API and use numpy.org URL

Author: kngwyu

src/array.rs

@@ -16,7 +16,7 @@ use crate::slice_box::SliceBox;
 use crate::types::{NpyDataType, TypeNum};
 
 /// A safe, static-typed interface for
-/// [NumPy ndarray](https://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html).
+/// [NumPy ndarray](https://numpy.org/doc/stable/reference/arrays.ndarray.html).
 ///
 /// # Memory location
 ///
@@ -226,7 +226,7 @@ impl<T, D> PyArray<T, D> {
 
     /// Returns the number of dimensions in the array.
     ///
-    /// Same as [numpy.ndarray.ndim](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.ndim.html)
+    /// Same as [numpy.ndarray.ndim](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.ndim.html)
     ///
     /// # Example
     /// ```
@@ -237,15 +237,15 @@ impl<T, D> PyArray<T, D> {
     /// assert_eq!(arr.ndim(), 3);
     /// # }
     /// ```
-    // C API: https://docs.scipy.org/doc/numpy/reference/c-api.array.html#c.PyArray_NDIM
+    // C API: https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_NDIM
     pub fn ndim(&self) -> usize {
         let ptr = self.as_array_ptr();
         unsafe { (*ptr).nd as usize }
     }
 
     /// Returns a slice which contains how many bytes you need to jump to the next row.
     ///
-    /// Same as [numpy.ndarray.strides](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.strides.html)
+    /// Same as [numpy.ndarray.strides](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.strides.html)
     /// # Example
     /// ```
     /// # fn main() {
@@ -255,7 +255,7 @@ impl<T, D> PyArray<T, D> {
     /// assert_eq!(arr.strides(), &[240, 48, 8]);
     /// # }
     /// ```
-    // C API: https://docs.scipy.org/doc/numpy/reference/c-api.array.html#c.PyArray_STRIDES
+    // C API: https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_STRIDES
     pub fn strides(&self) -> &[isize] {
         let n = self.ndim();
         let ptr = self.as_array_ptr();
@@ -267,7 +267,7 @@ impl<T, D> PyArray<T, D> {
 
     /// Returns a slice which contains dimmensions of the array.
     ///
-    /// Same as [numpy.ndarray.shape](https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.shape.html)
+    /// Same as [numpy.ndarray.shape](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.shape.html)
     /// # Example
     /// ```
     /// # fn main() {
@@ -277,7 +277,7 @@ impl<T, D> PyArray<T, D> {
     /// assert_eq!(arr.shape(), &[4, 5, 6]);
     /// # }
     /// ```
-    // C API: https://docs.scipy.org/doc/numpy/reference/c-api.array.html#c.PyArray_DIMS
+    // C API: https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_DIMS
     pub fn shape(&self) -> &[usize] {
         let n = self.ndim();
         let ptr = self.as_array_ptr();
@@ -415,7 +415,7 @@ impl<T: TypeNum, D: Dimension> PyArray<T, D> {
     /// If `is_fortran` is true, then
     /// a fortran order array is created, otherwise a C-order array is created.
     ///
-    /// See also [PyArray_Zeros](https://docs.scipy.org/doc/numpy/reference/c-api.array.html#c.PyArray_Zeros)
+    /// See also [PyArray_Zeros](https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_Zeros)
     ///
     /// # Example
     /// ```
@@ -1037,9 +1037,9 @@ impl<T: TypeNum, D> PyArray<T, D> {
 
 impl<T: TypeNum + AsPrimitive<f64>> PyArray<T, Ix1> {
     /// Return evenly spaced values within a given interval.
-    /// Same as [numpy.arange](https://docs.scipy.org/doc/numpy/reference/generated/numpy.arange.html).
+    /// Same as [numpy.arange](https://numpy.org/doc/stable/reference/generated/numpy.arange.html).
     ///
-    /// See also [PyArray_Arange](https://docs.scipy.org/doc/numpy/reference/c-api.array.html#c.PyArray_Arange).
+    /// See also [PyArray_Arange](https://numpy.org/doc/stable/reference/c-api/array.html#c.PyArray_Arange).
     ///
     /// # Example
     /// ```

src/lib.rs

@@ -1,5 +1,5 @@
-//! `rust-numpy` provides Rust interfaces for [NumPy C APIs](https://docs.scipy.org/doc/numpy/reference/c-api.html),
-//! especially for [ndarray](https://www.numpy.org/devdocs/reference/arrays.ndarray.html) class.
+//! `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.
 //!
 //! It uses [pyo3](https://github.com/PyO3/pyo3) for rust bindings to cpython, and uses
 //! [ndarray](https://github.com/bluss/ndarray) for rust side matrix library.

src/npyffi/array.rs

@@ -1,18 +1,17 @@
-//! Low-Level binding for [Array API](https://docs.scipy.org/doc/numpy/reference/c-api.array.html)
+//! Low-Level binding for [Array API](https://numpy.org/doc/stable/reference/c-api/array.html)
 use libc::FILE;
 use pyo3::ffi::{self, PyObject, PyTypeObject};
-use std::ops::Deref;
 use std::os::raw::*;
-use std::ptr;
 use std::sync::Once;
+use std::{cell::Cell, ptr};
 
 use crate::npyffi::*;
 
 pub(crate) const MOD_NAME: &str = "numpy.core.multiarray";
 const CAPSULE_NAME: &str = "_ARRAY_API";
 
 /// A global variable which stores a ['capsule'](https://docs.python.org/3/c-api/capsule.html)
-/// pointer to [Numpy Array API](https://docs.scipy.org/doc/numpy/reference/c-api.array.html).
+/// pointer to [Numpy Array API](https://numpy.org/doc/stable/reference/c-api/array.html).
 ///
 /// You can acceess raw c APIs via this variable and its Deref implementation.
 ///
@@ -31,35 +30,33 @@ const CAPSULE_NAME: &str = "_ARRAY_API";
 /// assert_eq!(array.as_slice().unwrap(), &[2, 3, 4])
 /// # }
 /// ```
-pub static PY_ARRAY_API: PyArrayAPI = PyArrayAPI {
-    __private_field: (),
-};
+pub static PY_ARRAY_API: PyArrayAPI = PyArrayAPI::new();
 
+/// See [PY_ARRAY_API] for more.
 pub struct PyArrayAPI {
-    __private_field: (),
+    once: Once,
+    api: Cell<*const *const c_void>,
 }
 
-impl Deref for PyArrayAPI {
-    type Target = PyArrayAPI_Inner;
-    fn deref(&self) -> &Self::Target {
-        static INIT_API: Once = Once::new();
-        static mut ARRAY_API_CACHE: PyArrayAPI_Inner = PyArrayAPI_Inner(ptr::null());
-        unsafe {
-            if ARRAY_API_CACHE.0.is_null() {
-                let api = get_numpy_api(MOD_NAME, CAPSULE_NAME);
-                INIT_API.call_once(move || {
-                    ARRAY_API_CACHE = PyArrayAPI_Inner(api);
-                });
-            }
-            &ARRAY_API_CACHE
+impl PyArrayAPI {
+    const fn new() -> Self {
+        Self {
+            once: Once::new(),
+            api: Cell::new(ptr::null_mut()),
+        }
+    }
+    fn get(&self, offset: isize) -> *const *const c_void {
+        if self.api.get().is_null() {
+            let api = get_numpy_api(MOD_NAME, CAPSULE_NAME);
+            self.once.call_once(|| self.api.set(api));
         }
+        unsafe { self.api.get().offset(offset) }
     }
 }
 
-#[allow(non_camel_case_types)]
-pub struct PyArrayAPI_Inner(*const *const c_void);
+unsafe impl Sync for PyArrayAPI {}
 
-impl PyArrayAPI_Inner {
+impl PyArrayAPI {
     impl_api![0; PyArray_GetNDArrayCVersion() -> c_uint];
     impl_api![40; PyArray_SetNumericOps(dict: *mut PyObject) -> c_int];
     impl_api![41; PyArray_GetNumericOps() -> *mut PyObject];
@@ -322,13 +319,15 @@ impl PyArrayAPI_Inner {
 /// Define PyTypeObject related to Array API
 macro_rules! impl_array_type {
     ($(($offset:expr, $tname:ident)),*) => {
+        /// All type objects that numpy has.
         #[allow(non_camel_case_types)]
         #[repr(i32)]
         pub enum ArrayType { $($tname),* }
-        impl PyArrayAPI_Inner {
+        impl PyArrayAPI {
+            /// Get the pointer of the type object that `self` refers.
             pub unsafe fn get_type_object(&self, ty: ArrayType) -> *mut PyTypeObject {
                 match ty {
-                    $( ArrayType::$tname => *(self.0.offset($offset)) as *mut PyTypeObject ),*
+                    $( ArrayType::$tname => *(self.get($offset)) as *mut PyTypeObject ),*
                 }
             }
         }
@@ -377,11 +376,13 @@ impl_array_type!(
     (39, PyVoidArrType_Type)
 );
 
+/// Checks that `op` is an instance of `PyArray` or not.
 #[allow(non_snake_case)]
 pub unsafe fn PyArray_Check(op: *mut PyObject) -> c_int {
     ffi::PyObject_TypeCheck(op, PY_ARRAY_API.get_type_object(ArrayType::PyArray_Type))
 }
 
+/// Checks that `op` is an exact instance of `PyArray` or not.
 #[allow(non_snake_case)]
 pub unsafe fn PyArray_CheckExact(op: *mut PyObject) -> c_int {
     (ffi::Py_TYPE(op) == PY_ARRAY_API.get_type_object(ArrayType::PyArray_Type)) as c_int

src/npyffi/mod.rs

@@ -1,6 +1,6 @@
 //! Low-Level bindings for NumPy C API.
 //!
-//! https://docs.scipy.org/doc/numpy/reference/c-api.html
+//! https://numpy.org/doc/stable/reference/c-api
 #![allow(non_camel_case_types)]
 
 use pyo3::ffi;
@@ -11,9 +11,6 @@ use std::ptr::null_mut;
 fn get_numpy_api(module: &str, capsule: &str) -> *const *const c_void {
     let module = CString::new(module).unwrap();
     let capsule = CString::new(capsule).unwrap();
-    unsafe fn get_capsule(capsule: *mut ffi::PyObject) -> *const *const c_void {
-        ffi::PyCapsule_GetPointer(capsule, null_mut()) as *const *const c_void
-    }
     unsafe {
         assert_ne!(
             ffi::Py_IsInitialized(),
@@ -23,9 +20,9 @@ Please make sure that you get gil, by `let gil = Python::acquire_gil();`"
         );
         let numpy = ffi::PyImport_ImportModule(module.as_ptr());
         assert!(!numpy.is_null(), "Failed to import numpy module");
-        let capsule = ffi::PyObject_GetAttrString(numpy as *mut ffi::PyObject, capsule.as_ptr());
+        let capsule = ffi::PyObject_GetAttrString(numpy as _, capsule.as_ptr());
         assert!(!capsule.is_null(), "Failed to import numpy module");
-        get_capsule(capsule)
+        ffi::PyCapsule_GetPointer(capsule, null_mut()) as _
     }
 }
 
@@ -34,8 +31,8 @@ macro_rules! impl_api {
     [ $offset:expr; $fname:ident ( $($arg:ident : $t:ty),* ) $( -> $ret:ty )* ] => {
         #[allow(non_snake_case)]
         pub unsafe fn $fname(&self, $($arg : $t), *) $( -> $ret )* {
-            let fptr = self.0.offset($offset)
-                               as *const extern fn ($($arg : $t), *) $( -> $ret )*;
+            let fptr = self.get($offset)
+                           as *const extern fn ($($arg : $t), *) $( -> $ret )*;
             (*fptr)($($arg), *)
         }
     }

src/npyffi/objects.rs

@@ -1,6 +1,6 @@
 //! Low-Lebel binding for NumPy C API C-objects
 //!
-//! https://docs.scipy.org/doc/numpy/reference/c-api.types-and-structures.html
+//! https://numpy.org/doc/stable/reference/c-api/types-and-structures.html
 #![allow(non_camel_case_types)]
 
 use libc::FILE;

src/npyffi/ufunc.rs

@@ -1,9 +1,7 @@
-//! Low-Level binding for [UFunc API](https://docs.scipy.org/doc/numpy/reference/c-api.ufunc.html)
+//! Low-Level binding for [UFunc API](https://numpy.org/doc/stable/reference/c-api/ufunc.html)
 
-use std::ops::Deref;
 use std::os::raw::*;
-use std::ptr;
-use std::sync::Once;
+use std::{cell::Cell, ptr, sync::Once};
 
 use pyo3::ffi::PyObject;
 
@@ -14,35 +12,34 @@ use super::types::*;
 const MOD_NAME: &str = "numpy.core.umath";
 const CAPSULE_NAME: &str = "_UFUNC_API";
 
-pub static PY_UFUNC_API: PyUFuncAPI = PyUFuncAPI {
-    __private_field: (),
-};
+/// A global variable which stores a ['capsule'](https://docs.python.org/3/c-api/capsule.html)
+/// pointer to [Numpy UFunc API](https://numpy.org/doc/stable/reference/c-api/array.html).
+pub static PY_UFUNC_API: PyUFuncAPI = PyUFuncAPI::new();
 
 pub struct PyUFuncAPI {
-    __private_field: (),
+    once: Once,
+    api: Cell<*const *const c_void>,
 }
 
-impl Deref for PyUFuncAPI {
-    type Target = PyUFuncAPI_Inner;
-    fn deref(&self) -> &Self::Target {
-        static INIT_API: Once = Once::new();
-        static mut UFUNC_API_CACHE: PyUFuncAPI_Inner = PyUFuncAPI_Inner(ptr::null());
-        unsafe {
-            if UFUNC_API_CACHE.0.is_null() {
-                let api = get_numpy_api(MOD_NAME, CAPSULE_NAME);
-                INIT_API.call_once(move || {
-                    UFUNC_API_CACHE = PyUFuncAPI_Inner(api);
-                });
-            }
-            &UFUNC_API_CACHE
+impl PyUFuncAPI {
+    const fn new() -> Self {
+        Self {
+            once: Once::new(),
+            api: Cell::new(ptr::null_mut()),
         }
     }
+    fn get(&self, offset: isize) -> *const *const c_void {
+        if self.api.get().is_null() {
+            let api = get_numpy_api(MOD_NAME, CAPSULE_NAME);
+            self.once.call_once(|| self.api.set(api));
+        }
+        unsafe { self.api.get().offset(offset) }
+    }
 }
 
-#[allow(non_camel_case_types)]
-pub struct PyUFuncAPI_Inner(*const *const c_void);
+unsafe impl Sync for PyUFuncAPI {}
 
-impl PyUFuncAPI_Inner {
+impl PyUFuncAPI {
     impl_api![1; PyUFunc_FromFuncAndData(func: *mut PyUFuncGenericFunction, data: *mut *mut c_void, types: *mut c_char, ntypes: c_int, nin: c_int, nout: c_int, identity: c_int, name: *const c_char, doc: *const c_char, unused: c_int) -> *mut PyObject];
     impl_api![2; PyUFunc_RegisterLoopForType(ufunc: *mut PyUFuncObject, usertype: c_int, function: PyUFuncGenericFunction, arg_types: *mut c_int, data: *mut c_void) -> c_int];
     impl_api![3; PyUFunc_GenericFunction(ufunc: *mut PyUFuncObject, args: *mut PyObject, kwds: *mut PyObject, op: *mut *mut PyArrayObject) -> c_int];