delete my modification in doc

fengluo · fengluo · commit cdfbc6215e82 · 2024-10-19T11:31:23.000+08:00
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst
@@ -30,57 +30,6 @@ and its sub-types).
 
     The number of dimensions in the array.
 
-.. c:function:: void *PyArray_DATA(PyArrayObject *arr)
-
-    The pointer to the first element of the array.
-
-.. c:function:: char *PyArray_BYTES(PyArrayObject *arr)
-
-    These two macros are similar and obtain the pointer to the
-    data-buffer for the array. The first macro can (and should be)
-    assigned to a particular pointer where the second is for generic
-    processing. If you have not guaranteed a contiguous and/or aligned
-    array then be sure you understand how to access the data in the
-    array to avoid memory and/or alignment problems.
-
-.. c:function:: npy_intp *PyArray_DIMS(PyArrayObject *arr)
-
-    Returns a pointer to the dimensions/shape of the array. The
-    number of elements matches the number of dimensions
-    of the array. Can return ``NULL`` for 0-dimensional arrays.
-
-.. c:function:: npy_intp *PyArray_STRIDES(PyArrayObject* arr)
-
-    Returns a pointer to the strides of the array. The
-    number of elements matches the number of dimensions
-    of the array.
-
-.. c:function:: npy_intp PyArray_DIM(PyArrayObject* arr, int n)
-
-    Return the shape in the *n* :math:`^{\textrm{th}}` dimension.
-
-.. c:function:: npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)
-
-    Return the stride in the *n* :math:`^{\textrm{th}}` dimension.
-
-.. c:function:: PyObject *PyArray_BASE(PyArrayObject* arr)
-
-    This returns the base object of the array. In most cases, this
-    means the object which owns the memory the array is pointing at.
-
-    If you are constructing an array using the C API, and specifying
-    your own memory, you should use the function :c:func:`PyArray_SetBaseObject`
-    to set the base to an object which owns the memory.
-
-    If the :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag is set, it has a different
-    meaning, namely base is the array into which the current array will
-    be copied upon copy resolution. This overloading of the base property
-    for two functions is likely to change in a future version of NumPy.
-
-.. c:function:: PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)
-
-    Returns a borrowed reference to the dtype property of the array.
-
 .. c:function:: int PyArray_FLAGS(PyArrayObject* arr)
 
     Returns an integer representing the :ref:`array-flags<array-flags>`.
@@ -89,32 +38,6 @@ and its sub-types).
 
     Return the (builtin) typenumber for the elements of this array.
 
-.. c:function:: PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)
-
-    A synonym for PyArray_DESCR, named to be consistent with the
-    'dtype' usage within Python.
-
-.. c:function:: npy_intp *PyArray_SHAPE(PyArrayObject *arr)
-
-    A synonym for :c:func:`PyArray_DIMS`, named to be consistent with the
-    `shape <numpy.ndarray.shape>` usage within Python.
-
-.. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
-
-    Enables the specified array flags. This function does no validation,
-    and assumes that you know what you're doing.
-
-.. c:function:: void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)
-
-    Clears the specified array flags. This function does no validation,
-    and assumes that you know what you're doing.
-
-.. c:function:: int PyArray_HANDLER(PyArrayObject *arr)
-
-    .. versionadded:: 1.22
-
-    Returns the memory handler associated with the given array.
-
 .. c:function:: int PyArray_Pack(  \
         const PyArray_Descr *descr, void *item, const PyObject *value)
 
@@ -141,6 +64,52 @@ and its sub-types).
         handling arbitrary Python objects.  Setitem is for example not able
         to handle arbitrary casts between different dtypes.
 
+.. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
+
+    Enables the specified array flags. This function does no validation,
+    and assumes that you know what you're doing.
+
+.. c:function:: void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)
+
+    Clears the specified array flags. This function does no validation,
+    and assumes that you know what you're doing.
+
+.. c:function:: void *PyArray_DATA(PyArrayObject *arr)
+
+.. c:function:: char *PyArray_BYTES(PyArrayObject *arr)
+
+    These two macros are similar and obtain the pointer to the
+    data-buffer for the array. The first macro can (and should be)
+    assigned to a particular pointer where the second is for generic
+    processing. If you have not guaranteed a contiguous and/or aligned
+    array then be sure you understand how to access the data in the
+    array to avoid memory and/or alignment problems.
+
+.. c:function:: npy_intp *PyArray_DIMS(PyArrayObject *arr)
+
+    Returns a pointer to the dimensions/shape of the array. The
+    number of elements matches the number of dimensions
+    of the array. Can return ``NULL`` for 0-dimensional arrays.
+
+.. c:function:: npy_intp *PyArray_SHAPE(PyArrayObject *arr)
+
+    A synonym for :c:func:`PyArray_DIMS`, named to be consistent with the
+    `shape <numpy.ndarray.shape>` usage within Python.
+
+.. c:function:: npy_intp *PyArray_STRIDES(PyArrayObject* arr)
+
+    Returns a pointer to the strides of the array. The
+    number of elements matches the number of dimensions
+    of the array.
+
+.. c:function:: npy_intp PyArray_DIM(PyArrayObject* arr, int n)
+
+    Return the shape in the *n* :math:`^{\textrm{th}}` dimension.
+
+.. c:function:: npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)
+
+    Return the stride in the *n* :math:`^{\textrm{th}}` dimension.
+
 .. c:function:: npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)
 
     Return the itemsize for the elements of this array.
@@ -162,6 +131,29 @@ and its sub-types).
 
     Returns the total number of bytes consumed by the array.
 
+.. c:function:: PyObject *PyArray_BASE(PyArrayObject* arr)
+
+    This returns the base object of the array. In most cases, this
+    means the object which owns the memory the array is pointing at.
+
+    If you are constructing an array using the C API, and specifying
+    your own memory, you should use the function :c:func:`PyArray_SetBaseObject`
+    to set the base to an object which owns the memory.
+
+    If the :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag is set, it has a different
+    meaning, namely base is the array into which the current array will
+    be copied upon copy resolution. This overloading of the base property
+    for two functions is likely to change in a future version of NumPy.
+
+.. c:function:: PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)
+
+    Returns a borrowed reference to the dtype property of the array.
+
+.. c:function:: PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)
+
+    A synonym for PyArray_DESCR, named to be consistent with the
+    'dtype' usage within Python.
+
 .. c:function:: PyObject *PyArray_GETITEM(PyArrayObject* arr, void* itemptr)
 
     Get a Python object of a builtin type from the ndarray, *arr*,
diff --git a/doc/source/reference/c-api/dtype.rst b/doc/source/reference/c-api/dtype.rst
@@ -421,11 +421,6 @@ to the front of the integer name.
 
     The C ``size_t``/``Py_size_t``.
 
-.. c:type:: npy_hash_t
-
-   The C ``Py_hash_t`` (a signed integer type used for hashing).
-   This type is utilized in NumPy to represent hash values for objects.
-
 
 (Complex) Floating point
 ~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst
@@ -71,17 +71,19 @@ PyArray_Type and PyArrayObject
    member of this structure contains a pointer to the :c:data:`PyArray_Type`
    typeobject.
 
-.. c:type:: PyArrayObject_fields
-
-   The :c:type:`PyArrayObject_fields` C-structure contains all of the
-   required information for an array. All instances of an ndarray (and
-   its subclasses) will have this structure. For future compatibility,
-   these structure members should normally be accessed using the provided
-   functions and macros. Direct access to the members of :c:type:`PyArrayObject_fields`
-   should be avoided. Instead, users should interact with :c:type:`PyArrayObject`,
-   which provides a stable interface for accessing array data and metadata.
-   This struct may be moved to a private header in a future release,
-   further emphasizing the importance of using the defined macros for access.
+.. c:type:: PyArrayObject
+            NPY_AO
+
+   The :c:type:`PyArrayObject` C-structure contains all of the required
+   information for an array. All instances of an ndarray (and its
+   subclasses) will have this structure.  For future compatibility,
+   these structure members should normally be accessed using the
+   provided macros. If you need a shorter name, then you can make use
+   of :c:type:`NPY_AO` (deprecated) which is defined to be equivalent to
+   :c:type:`PyArrayObject`. Direct access to the struct fields are
+   deprecated. Use the ``PyArray_*(arr)`` form instead.
+   As of NumPy 1.20, the size of this struct is not considered part of
+   the NumPy ABI (see note at the end of the member list).
 
    .. code-block:: c
 
@@ -95,17 +97,17 @@ PyArray_Type and PyArrayObject
           PyArray_Descr *descr;
           int flags;
           PyObject *weakreflist;
-          void *_buffer_info;
-          PyObject *mem_handler;
+          /* version dependent private members */
       } PyArrayObject;
 
    :c:macro:`PyObject_HEAD`
        This is needed by all Python objects. It consists of (at least)
        a reference count member ( ``ob_refcnt`` ) and a pointer to the
        typeobject ( ``ob_type`` ). (Other elements may also be present
-       if Python was compiled with special options see Include/object.h
-       in the Python source tree for more information). The ``ob_type``
-       member points to a Python type object.
+       if Python was compiled with special options see
+       Include/object.h in the Python source tree for more
+       information). The ob_type member points to a Python type
+       object.
 
    .. c:member:: char *data
 
@@ -120,7 +122,7 @@ PyArray_Type and PyArrayObject
        array. Such arrays have undefined dimensions and strides and
        cannot be accessed. Macro :c:data:`PyArray_NDIM` defined in
        ``ndarraytypes.h`` points to this data member.
-       :c:macro:`NPY_MAXDIMS` is defined as a compile time constant limiting the
+       ``NPY_MAXDIMS`` is defined as a compile time constant limiting the
        number of dimensions.  This number is 64 since NumPy 2 and was 32
        before. However, we may wish to remove this limitations in the future
        so that it is best to explicitly check dimensionality for code
@@ -179,43 +181,6 @@ PyArray_Type and PyArrayObject
        This member allows array objects to have weak references (using the
        weakref module).
 
-   .. c:member:: void *_buffer_info
-
-   .. versionadded:: 1.20
-
-   Private buffer information, tagged for warning purposes. Direct
-   access is discouraged to ensure API stability.
-
-   .. c:member:: PyObject *mem_handler
-
-   .. versionadded:: 1.22
-
-   A pointer to a ``PyObject`` that serves as a :c:data:`PyDataMem_Handler`.
-   This allows custom memory management policies for each array object,
-   enabling the use of user-defined memory allocation and deallocation routines
-   instead of the standard `malloc`, `calloc`, `realloc`, and `free` functions.
-
-   Accessed through the macro :c:data:`PyArray_HANDLER`.
-
-   .. note::
-
-      For setting or retrieving the current memory management policy,
-      see the `PyDataMem_SetHandler` and `PyDataMem_GetHandler` functions.
-
-.. c:type:: PyArrayObject
-
-   .. deprecated:: 1.7
-      Use ``NPY_AO`` for a shorter name.
-
-   Represents a NumPy array object in the C API.
-
-   To hide the implementation details, only the Python struct HEAD is exposed.
-   Direct access to the struct fields is deprecated;
-   instead, use the ``PyArray_*(*arr)`` functions (such as :c:func:`PyArray_NDIM`).
-
-   As of NumPy 1.20, the size of this struct is not considered part of the NumPy ABI
-   (see the note below).
-
    .. note::
 
       Further members are considered private and version dependent. If the size
@@ -322,7 +287,7 @@ PyArrayDescr_Type and PyArray_Descr
           npy_uint64 flags;
           npy_intp elsize;
           npy_intp alignment;
-          PyObject *metadata;
+          NpyAuxData *c_metadata;
           npy_hash_t hash;
           void *reserved_null[2];  // unused field, must be NULLed.
       } PyArray_Descr;
@@ -412,6 +377,7 @@ PyArrayDescr_Type and PyArray_Descr
        Metadata specific to the C implementation
        of the particular dtype. Added for NumPy 1.7.0.
 
+   .. c:type:: npy_hash_t
    .. c:member:: npy_hash_t *hash
 
        Used for caching hash values.
@@ -515,7 +481,7 @@ PyArray_ArrFuncs
     .. code-block:: c
 
        typedef struct {
-           PyArray_VectorUnaryFunc *cast[NPY_NTYPES_ABI_COMPATIBLE];
+           PyArray_VectorUnaryFunc *cast[NPY_NTYPES_LEGACY];
            PyArray_GetItemFunc *getitem;
            PyArray_SetItemFunc *setitem;
            PyArray_CopySwapNFunc *copyswapn;
@@ -562,10 +528,8 @@ PyArray_ArrFuncs
             void *from, void *to, npy_intp n, void *fromarr, void *toarr)
 
         An array of function pointers to cast from the current type to
-        most of the other builtin types. The types
-        :c:type:`NPY_DATETIME`, :c:type:`NPY_TIMEDELTA`, and :c:type:`NPY_HALF`
-        go into the castdict even though they are built-in. Each function
-        casts a contiguous, aligned, and notswapped buffer pointed at by
+        all of the other builtin types. Each function casts a
+        contiguous, aligned, and notswapped buffer pointed at by
         *from* to a contiguous, aligned, and notswapped buffer pointed
         at by *to* The number of items to cast is given by *n*, and
         the arguments *fromarr* and *toarr* are interpreted as
@@ -1009,11 +973,11 @@ PyUFunc_Type and PyUFuncObject
           int nargs;
           int identity;
           PyUFuncGenericFunction *functions;
-          void *const *data;
+          void **data;
           int ntypes;
           int reserved1;
           const char *name;
-          const char *types;
+          char *types;
           const char *doc;
           void *ptr;
           PyObject *obj;
