From b6de7bc0dcadac314fcb9ecb6c0d59f91aadb3ed Mon Sep 17 00:00:00 2001 From: Sebastian Berg Date: Thu, 23 Jun 2022 10:49:29 -0700 Subject: DOC: Document expectation for object array initialization This documents (and thus semi-establishes) that we try to make sure that any array that may be *read* is fully initialized with proper Python objects (not NULL). However, try to write in a way that clearly says that users are not allowed to rely on this. I somewhat suspect there are more code paths where we may to fail fully initializing object arrays... It does promise to regard such things as bugs, if we do not want that, I am happy to just tell users to expect NULLs. --- doc/source/reference/c-api/array.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'doc/source/reference/c-api') diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst index f69c2bcb1..8c0acd418 100644 --- a/doc/source/reference/c-api/array.rst +++ b/doc/source/reference/c-api/array.rst @@ -1323,6 +1323,28 @@ User-defined data types Special functions for NPY_OBJECT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. warning:: + + When working with arrays or buffers filled with objects NumPy tries to + ensure such buffers are filled with ``None`` before any data may be read. + However, code paths may existed where an array is only initialized to + ``NULL``. + NumPy itself accepts ``NULL`` as an alias for ``None``, but may ``assert`` + non-``NULL`` when compiled in debug mode. + + Users **must** expect a value of ``NULL`` when working with buffers created + by NumPy. Users **should** also ensure to pass fully initialized buffers + to NumPy, since NumPy may make this a strong requirement in the future. + + There is currently an intention to ensure that NumPy always initalizes + object arrays before it may be read. Any failure to do so will be + regarded as a bug. + In the future, users may be able to rely on non-NULL values when reading + from any array, although exceptions for writing to freshly created arrays + may remain (e.g. for output arrays in ufunc code). As of NumPy 1.23 + known code paths exists where proper filling is not done. + + .. c:function:: int PyArray_INCREF(PyArrayObject* op) Used for an array, *op*, that contains any Python objects. It -- cgit v1.2.1