Skip to content

Commit 30a6ea5

Browse files
author
fengluo
committed
Fix some out-of-data struct in c-api types-and-structures
1 parent 4e7f657 commit 30a6ea5

File tree

3 files changed

+144
-95
lines changed

3 files changed

+144
-95
lines changed

‎doc/source/reference/c-api/array.rst

Lines changed: 77 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,57 @@ and its sub-types).
3030
3131
The number of dimensions in the array.
3232
33+
.. c:function:: void *PyArray_DATA(PyArrayObject *arr)
34+
35+
The pointer to the first element of the array.
36+
37+
.. c:function:: char *PyArray_BYTES(PyArrayObject *arr)
38+
39+
These two macros are similar and obtain the pointer to the
40+
data-buffer for the array. The first macro can (and should be)
41+
assigned to a particular pointer where the second is for generic
42+
processing. If you have not guaranteed a contiguous and/or aligned
43+
array then be sure you understand how to access the data in the
44+
array to avoid memory and/or alignment problems.
45+
46+
.. c:function:: npy_intp *PyArray_DIMS(PyArrayObject *arr)
47+
48+
Returns a pointer to the dimensions/shape of the array. The
49+
number of elements matches the number of dimensions
50+
of the array. Can return ``NULL`` for 0-dimensional arrays.
51+
52+
.. c:function:: npy_intp *PyArray_STRIDES(PyArrayObject* arr)
53+
54+
Returns a pointer to the strides of the array. The
55+
number of elements matches the number of dimensions
56+
of the array.
57+
58+
.. c:function:: npy_intp PyArray_DIM(PyArrayObject* arr, int n)
59+
60+
Return the shape in the *n* :math:`^{\textrm{th}}` dimension.
61+
62+
.. c:function:: npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)
63+
64+
Return the stride in the *n* :math:`^{\textrm{th}}` dimension.
65+
66+
.. c:function:: PyObject *PyArray_BASE(PyArrayObject* arr)
67+
68+
This returns the base object of the array. In most cases, this
69+
means the object which owns the memory the array is pointing at.
70+
71+
If you are constructing an array using the C API, and specifying
72+
your own memory, you should use the function :c:func:`PyArray_SetBaseObject`
73+
to set the base to an object which owns the memory.
74+
75+
If the :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag is set, it has a different
76+
meaning, namely base is the array into which the current array will
77+
be copied upon copy resolution. This overloading of the base property
78+
for two functions is likely to change in a future version of NumPy.
79+
80+
.. c:function:: PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)
81+
82+
Returns a borrowed reference to the dtype property of the array.
83+
3384
.. c:function:: int PyArray_FLAGS(PyArrayObject* arr)
3485
3586
Returns an integer representing the :ref:`array-flags<array-flags>`.
@@ -38,6 +89,32 @@ and its sub-types).
3889
3990
Return the (builtin) typenumber for the elements of this array.
4091
92+
.. c:function:: PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)
93+
94+
A synonym for PyArray_DESCR, named to be consistent with the
95+
'dtype' usage within Python.
96+
97+
.. c:function:: npy_intp *PyArray_SHAPE(PyArrayObject *arr)
98+
99+
A synonym for :c:func:`PyArray_DIMS`, named to be consistent with the
100+
`shape <numpy.ndarray.shape>` usage within Python.
101+
102+
.. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
103+
104+
Enables the specified array flags. This function does no validation,
105+
and assumes that you know what you're doing.
106+
107+
.. c:function:: void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)
108+
109+
Clears the specified array flags. This function does no validation,
110+
and assumes that you know what you're doing.
111+
112+
.. c:function:: int PyArray_HANDLER(PyArrayObject *arr)
113+
114+
.. versionadded:: 1.22
115+
116+
Returns the memory handler associated with the given array.
117+
41118
.. c:function:: int PyArray_Pack( \
42119
const PyArray_Descr *descr, void *item, const PyObject *value)
43120
@@ -64,52 +141,6 @@ and its sub-types).
64141
handling arbitrary Python objects. Setitem is for example not able
65142
to handle arbitrary casts between different dtypes.
66143
67-
.. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
68-
69-
Enables the specified array flags. This function does no validation,
70-
and assumes that you know what you're doing.
71-
72-
.. c:function:: void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)
73-
74-
Clears the specified array flags. This function does no validation,
75-
and assumes that you know what you're doing.
76-
77-
.. c:function:: void *PyArray_DATA(PyArrayObject *arr)
78-
79-
.. c:function:: char *PyArray_BYTES(PyArrayObject *arr)
80-
81-
These two macros are similar and obtain the pointer to the
82-
data-buffer for the array. The first macro can (and should be)
83-
assigned to a particular pointer where the second is for generic
84-
processing. If you have not guaranteed a contiguous and/or aligned
85-
array then be sure you understand how to access the data in the
86-
array to avoid memory and/or alignment problems.
87-
88-
.. c:function:: npy_intp *PyArray_DIMS(PyArrayObject *arr)
89-
90-
Returns a pointer to the dimensions/shape of the array. The
91-
number of elements matches the number of dimensions
92-
of the array. Can return ``NULL`` for 0-dimensional arrays.
93-
94-
.. c:function:: npy_intp *PyArray_SHAPE(PyArrayObject *arr)
95-
96-
A synonym for :c:func:`PyArray_DIMS`, named to be consistent with the
97-
`shape <numpy.ndarray.shape>` usage within Python.
98-
99-
.. c:function:: npy_intp *PyArray_STRIDES(PyArrayObject* arr)
100-
101-
Returns a pointer to the strides of the array. The
102-
number of elements matches the number of dimensions
103-
of the array.
104-
105-
.. c:function:: npy_intp PyArray_DIM(PyArrayObject* arr, int n)
106-
107-
Return the shape in the *n* :math:`^{\textrm{th}}` dimension.
108-
109-
.. c:function:: npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)
110-
111-
Return the stride in the *n* :math:`^{\textrm{th}}` dimension.
112-
113144
.. c:function:: npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)
114145
115146
Return the itemsize for the elements of this array.
@@ -131,29 +162,6 @@ and its sub-types).
131162
132163
Returns the total number of bytes consumed by the array.
133164
134-
.. c:function:: PyObject *PyArray_BASE(PyArrayObject* arr)
135-
136-
This returns the base object of the array. In most cases, this
137-
means the object which owns the memory the array is pointing at.
138-
139-
If you are constructing an array using the C API, and specifying
140-
your own memory, you should use the function :c:func:`PyArray_SetBaseObject`
141-
to set the base to an object which owns the memory.
142-
143-
If the :c:data:`NPY_ARRAY_WRITEBACKIFCOPY` flag is set, it has a different
144-
meaning, namely base is the array into which the current array will
145-
be copied upon copy resolution. This overloading of the base property
146-
for two functions is likely to change in a future version of NumPy.
147-
148-
.. c:function:: PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)
149-
150-
Returns a borrowed reference to the dtype property of the array.
151-
152-
.. c:function:: PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)
153-
154-
A synonym for PyArray_DESCR, named to be consistent with the
155-
'dtype' usage within Python.
156-
157165
.. c:function:: PyObject *PyArray_GETITEM(PyArrayObject* arr, void* itemptr)
158166
159167
Get a Python object of a builtin type from the ndarray, *arr*,

‎doc/source/reference/c-api/dtype.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -421,6 +421,11 @@ to the front of the integer name.
421421
422422
The C ``size_t``/``Py_size_t``.
423423

424+
.. c:type:: npy_hash_t
425+
426+
The C ``Py_hash_t`` (a signed integer type used for hashing).
427+
This type is utilized in NumPy to represent hash values for objects.
428+
424429

425430
(Complex) Floating point
426431
~~~~~~~~~~~~~~~~~~~~~~~~

‎doc/source/reference/c-api/types-and-structures.rst

Lines changed: 62 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -71,19 +71,17 @@ PyArray_Type and PyArrayObject
7171
member of this structure contains a pointer to the :c:data:`PyArray_Type`
7272
typeobject.
7373

74-
.. c:type:: PyArrayObject
75-
NPY_AO
76-
77-
The :c:type:`PyArrayObject` C-structure contains all of the required
78-
information for an array. All instances of an ndarray (and its
79-
subclasses) will have this structure. For future compatibility,
80-
these structure members should normally be accessed using the
81-
provided macros. If you need a shorter name, then you can make use
82-
of :c:type:`NPY_AO` (deprecated) which is defined to be equivalent to
83-
:c:type:`PyArrayObject`. Direct access to the struct fields are
84-
deprecated. Use the ``PyArray_*(arr)`` form instead.
85-
As of NumPy 1.20, the size of this struct is not considered part of
86-
the NumPy ABI (see note at the end of the member list).
74+
.. c:type:: PyArrayObject_fields
75+
76+
The :c:type:`PyArrayObject_fields` C-structure contains all of the
77+
required information for an array. All instances of an ndarray (and
78+
its subclasses) will have this structure. For future compatibility,
79+
these structure members should normally be accessed using the provided
80+
functions and macros. Direct access to the members of :c:type:`PyArrayObject_fields`
81+
should be avoided. Instead, users should interact with :c:type:`PyArrayObject`,
82+
which provides a stable interface for accessing array data and metadata.
83+
This struct may be moved to a private header in a future release,
84+
further emphasizing the importance of using the defined macros for access.
8785

8886
.. code-block:: c
8987
@@ -97,17 +95,17 @@ PyArray_Type and PyArrayObject
9795
PyArray_Descr *descr;
9896
int flags;
9997
PyObject *weakreflist;
100-
/* version dependent private members */
98+
void *_buffer_info;
99+
PyObject *mem_handler;
101100
} PyArrayObject;
102101
103102
:c:macro:`PyObject_HEAD`
104103
This is needed by all Python objects. It consists of (at least)
105104
a reference count member ( ``ob_refcnt`` ) and a pointer to the
106105
typeobject ( ``ob_type`` ). (Other elements may also be present
107-
if Python was compiled with special options see
108-
Include/object.h in the Python source tree for more
109-
information). The ob_type member points to a Python type
110-
object.
106+
if Python was compiled with special options see Include/object.h
107+
in the Python source tree for more information). The ``ob_type``
108+
member points to a Python type object.
111109

112110
.. c:member:: char *data
113111
@@ -122,7 +120,7 @@ PyArray_Type and PyArrayObject
122120
array. Such arrays have undefined dimensions and strides and
123121
cannot be accessed. Macro :c:data:`PyArray_NDIM` defined in
124122
``ndarraytypes.h`` points to this data member.
125-
``NPY_MAXDIMS`` is defined as a compile time constant limiting the
123+
:c:macro:`NPY_MAXDIMS` is defined as a compile time constant limiting the
126124
number of dimensions. This number is 64 since NumPy 2 and was 32
127125
before. However, we may wish to remove this limitations in the future
128126
so that it is best to explicitly check dimensionality for code
@@ -181,6 +179,43 @@ PyArray_Type and PyArrayObject
181179
This member allows array objects to have weak references (using the
182180
weakref module).
183181

182+
.. c:member:: void *_buffer_info
183+
184+
.. versionadded:: 1.20
185+
186+
Private buffer information, tagged for warning purposes. Direct
187+
access is discouraged to ensure API stability.
188+
189+
.. c:member:: PyObject *mem_handler
190+
191+
.. versionadded:: 1.22
192+
193+
A pointer to a ``PyObject`` that serves as a :c:data:`PyDataMem_Handler`.
194+
This allows custom memory management policies for each array object,
195+
enabling the use of user-defined memory allocation and deallocation routines
196+
instead of the standard `malloc`, `calloc`, `realloc`, and `free` functions.
197+
198+
Accessed through the macro :c:data:`PyArray_HANDLER`.
199+
200+
.. note::
201+
202+
For setting or retrieving the current memory management policy,
203+
see the `PyDataMem_SetHandler` and `PyDataMem_GetHandler` functions.
204+
205+
.. c:type:: PyArrayObject
206+
207+
.. deprecated:: 1.7
208+
Use :c:type:`NPY_AO` for a shorter name.
209+
210+
Represents a NumPy array object in the C API.
211+
212+
To hide the implementation details, only the Python struct HEAD is exposed.
213+
Direct access to the struct fields is deprecated;
214+
instead, use the ``PyArray_*(*arr)`` functions (such as :c:func:`PyArray_NDIM`).
215+
216+
As of NumPy 1.20, the size of this struct is not considered part of the NumPy ABI
217+
(see the note below).
218+
184219
.. note::
185220

186221
Further members are considered private and version dependent. If the size
@@ -287,7 +322,7 @@ PyArrayDescr_Type and PyArray_Descr
287322
npy_uint64 flags;
288323
npy_intp elsize;
289324
npy_intp alignment;
290-
NpyAuxData *c_metadata;
325+
PyObject *metadata;
291326
npy_hash_t hash;
292327
void *reserved_null[2]; // unused field, must be NULLed.
293328
} PyArray_Descr;
@@ -377,7 +412,6 @@ PyArrayDescr_Type and PyArray_Descr
377412
Metadata specific to the C implementation
378413
of the particular dtype. Added for NumPy 1.7.0.
379414

380-
.. c:type:: npy_hash_t
381415
.. c:member:: npy_hash_t *hash
382416
383417
Used for caching hash values.
@@ -481,7 +515,7 @@ PyArray_ArrFuncs
481515
.. code-block:: c
482516
483517
typedef struct {
484-
PyArray_VectorUnaryFunc *cast[NPY_NTYPES_LEGACY];
518+
PyArray_VectorUnaryFunc *cast[NPY_NTYPES_ABI_COMPATIBLE];
485519
PyArray_GetItemFunc *getitem;
486520
PyArray_SetItemFunc *setitem;
487521
PyArray_CopySwapNFunc *copyswapn;
@@ -528,8 +562,10 @@ PyArray_ArrFuncs
528562
void *from, void *to, npy_intp n, void *fromarr, void *toarr)
529563
530564
An array of function pointers to cast from the current type to
531-
all of the other builtin types. Each function casts a
532-
contiguous, aligned, and notswapped buffer pointed at by
565+
most of the other builtin types. The types
566+
:c:type:`NPY_DATETIME`, :c:type:`NPY_TIMEDELTA`, and :c:type:`HALF`
567+
go into the castdict even though they are built-in. Each function
568+
casts a contiguous, aligned, and notswapped buffer pointed at by
533569
*from* to a contiguous, aligned, and notswapped buffer pointed
534570
at by *to* The number of items to cast is given by *n*, and
535571
the arguments *fromarr* and *toarr* are interpreted as
@@ -973,11 +1009,11 @@ PyUFunc_Type and PyUFuncObject
9731009
int nargs;
9741010
int identity;
9751011
PyUFuncGenericFunction *functions;
976-
void **data;
1012+
void *const *data;
9771013
int ntypes;
9781014
int reserved1;
9791015
const char *name;
980-
char *types;
1016+
const char *types;
9811017
const char *doc;
9821018
void *ptr;
9831019
PyObject *obj;

0 commit comments

Comments
 (0)