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.

1 files changed, 22 insertions, 0 deletions

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