diff options
Diffstat (limited to 'doc/source/reference/c-api')
| -rw-r--r-- | doc/source/reference/c-api/array.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/c-api/types-and-structures.rst | 27 |
2 files changed, 30 insertions, 5 deletions
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst index e9717d59a..3aa541b79 100644 --- a/doc/source/reference/c-api/array.rst +++ b/doc/source/reference/c-api/array.rst @@ -2960,9 +2960,9 @@ to. already a buffer object pointing to another object). If you need to hold on to the memory be sure to INCREF the base member. The chunk of memory is pointed to by *buf* ->ptr member and has length - *buf* ->len. The flags member of *buf* is :c:data:`NPY_BEHAVED_RO` with - the :c:data:`NPY_ARRAY_WRITEABLE` flag set if *obj* has a writeable buffer - interface. + *buf* ->len. The flags member of *buf* is :c:data:`NPY_ARRAY_ALIGNED` + with the :c:data:`NPY_ARRAY_WRITEABLE` flag set if *obj* has + a writeable buffer interface. .. c:function:: int PyArray_AxisConverter(PyObject* obj, int* axis) @@ -3136,7 +3136,7 @@ the C-API is needed then some additional steps must be taken. be defined in another compilation unit. * Whenever :c:macro:`PY_ARRAY_UNIQUE_SYMBOL` is #defined, it also changes the name of the variable holding the C-API, which - defaults to :c:data:`PyArray_API`, to whatever the macro is + defaults to ``PyArray_API``, to whatever the macro is #defined to. Checking the API Version diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst index 87d4be6f3..763f985a6 100644 --- a/doc/source/reference/c-api/types-and-structures.rst +++ b/doc/source/reference/c-api/types-and-structures.rst @@ -79,6 +79,8 @@ PyArray_Type and PyArrayObject 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 @@ -92,6 +94,7 @@ PyArray_Type and PyArrayObject PyArray_Descr *descr; int flags; PyObject *weakreflist; + /* version dependend private members */ } PyArrayObject; .. c:macro:: PyObject_HEAD @@ -173,6 +176,27 @@ PyArray_Type and PyArrayObject This member allows array objects to have weak references (using the weakref module). + .. note:: + + Further members are considered private and version dependend. If the size + of the struct is important for your code, special care must be taken. + A possible use-case when this is relevant is subclassing in C. + If your code relies on ``sizeof(PyArrayObject)`` to be constant, + you must add the following check at import time: + + .. code-block:: c + + if (sizeof(PyArrayObject) < PyArray_Type.tp_basicsize) { + PyErr_SetString(PyExc_ImportError, + "Binary incompatibility with NumPy, must recompile/update X."); + return NULL; + } + + To ensure that your code does not have to be compiled for a specific + NumPy version, you may add a constant, leaving room for changes in NumPy. + A solution guaranteed to be compatible with any future NumPy version + requires the use of a runtime calculate offset and allocation size. + PyArrayDescr_Type and PyArray_Descr ----------------------------------- @@ -412,7 +436,8 @@ PyArrayDescr_Type and PyArray_Descr Metadata specific to the C implementation of the particular dtype. Added for NumPy 1.7.0. - .. c:member:: Npy_hash_t *hash + .. c:type:: npy_hash_t + .. c:member:: npy_hash_t *hash Currently unused. Reserved for future use in caching hash values. |