summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/release/upcoming_changes/16938.c_api.rst19
-rw-r--r--doc/source/reference/c-api/types-and-structures.rst24
2 files changed, 43 insertions, 0 deletions
diff --git a/doc/release/upcoming_changes/16938.c_api.rst b/doc/release/upcoming_changes/16938.c_api.rst
new file mode 100644
index 000000000..aff72c8e5
--- /dev/null
+++ b/doc/release/upcoming_changes/16938.c_api.rst
@@ -0,0 +1,19 @@
+Size of ``np.ndarray`` and ``np.void_`` changed
+-----------------------------------------------
+The size of the ``PyArrayObject`` and ``PyVoidScalarObject``
+structures have changed. The following header definition has been
+removed::
+
+ #define NPY_SIZEOF_PYARRAYOBJECT (sizeof(PyArrayObject_fields))
+
+since the size must not be considered a compile time constant: it will
+change for different runtime versions of NumPy.
+
+The most likely relevant use are potential subclasses written in C which
+will have to be recompiled and should be updated. Please see the
+documentation for :c:type:`PyArrayObject` for more details and contact
+the NumPy developers if you are affected by this change.
+
+NumPy will attempt to give a graceful error but a program expecting a
+fixed structure size may have undefined behaviour and likely crash.
+
diff --git a/doc/source/reference/c-api/types-and-structures.rst b/doc/source/reference/c-api/types-and-structures.rst
index 6a9c4a9cf..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
-----------------------------------