API: Expose PyArray_Pack

AnsonTran · Mar 7, 2024 · ad3524c · ad3524c
1 parent 80a21e7
commit ad3524c
Show file tree

Hide file tree

Showing 6 changed files with 33 additions and 7 deletions.
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst
@@ -38,13 +38,32 @@ and its sub-types).
 
     Return the (builtin) typenumber for the elements of this array.
 
+.. c:function:: int PyArray_Pack(  \
+        const PyArray_Descr *descr, void *item, const PyObject *value)
+
+    .. versionadded:: 2.0
+
+    Sets the memory location ``item`` of dtype ``descr`` to ``value``.
+
+    The function is equivalent to setting a single array element with a Python
+    assignment.  Returns 0 on success and -1 with an error set on failure.
+
+    .. note::
+        If the ``descr`` has the :c:data:`NPY_NEEDS_INIT` flag set, the
+        data must be valid or the memory zeroed.
+
 .. c:function:: int PyArray_SETITEM( \
         PyArrayObject* arr, void* itemptr, PyObject* obj)
 
     Convert obj and place it in the ndarray, *arr*, at the place
     pointed to by itemptr. Return -1 if an error occurs or 0 on
     success.
 
+    .. note::
+        In general, prefer the use of :c:function:`PyArray_Pack` when
+        handling arbitrary Python objects.  Setitem is for example not able
+        to handle arbitrary casts between different dtypes.
+
 .. c:function:: void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)
 
     .. versionadded:: 1.7

diff --git a/doc/source/release/2.0.0-notes.rst b/doc/source/release/2.0.0-notes.rst
@@ -347,6 +347,12 @@ C API changes
 
   (`gh-25789 <https://github.com/numpy/numpy/pull/25789>`__)
 
+* NumPy now defines :c:function:`PyArray_Pack` to set an individual memory
+  address.  Unlike ``PyArray_SETITEM`` this function is equivalent to setting
+  an individual array item and does not require a NumPy array input.
+
+  (`gh-25954 <https://github.com/numpy/numpy/pull/25954>`__)
+
 * The ``->f`` slot has been removed from ``PyArray_Descr``.
   If you use this slot, replace accessing it with
   ``PyDataType_GetArrFuncs`` (see its documentation and the

diff --git a/numpy/_core/code_generators/cversions.txt b/numpy/_core/code_generators/cversions.txt
@@ -73,4 +73,4 @@
 0x00000011 = ca1aebdad799358149567d9d93cbca09
 
 # Version 18 (NumPy 2.0.0)
-0x00000012 = af4bcb877c1ce2e351681fe18bb8195d
+0x00000012 = 2b8f1f4da822491ff030b2b37dff07e3
diff --git a/numpy/_core/code_generators/numpy_api.py b/numpy/_core/code_generators/numpy_api.py
@@ -103,7 +103,7 @@ def get_annotations():
 
 multiarray_funcs_api = {
     '__unused_indices__': (
-        [1, 4, 40, 41, 65, 66, 67, 68, 81, 82, 83,
+        [1, 4, 40, 41, 66, 67, 68, 81, 82, 83,
          103, 115, 117, 122, 163, 164, 171, 173, 197,
          201, 202, 208, 219, 220, 221, 222, 223, 278,
          291, 293, 294, 295, 301]
@@ -135,7 +135,7 @@ def get_annotations():
     'PyArray_ScalarAsCtype':                (62,),
     'PyArray_CastScalarToCtype':            (63,),
     'PyArray_CastScalarDirect':             (64,),
-    # Unused slot 65, was `PyArray_ScalarFromObject`
+    'PyArray_Pack':                         (65, MinVersion("2.0")),
     # Unused slot 66, was `PyArray_GetCastFunc`
     # Unused slot 67, was `PyArray_FromDims`
     # Unused slot 68, was `PyArray_FromDimsAndDataAndDescr`
@@ -399,10 +399,10 @@ def get_annotations():
     'PyArrayInitDTypeMeta_FromSpec':                 (362, MinVersion("2.0")),
     'PyArray_CommonDType':                           (363, MinVersion("2.0")),
     'PyArray_PromoteDTypeSequence':                  (364, MinVersion("2.0")),
-    # End 2.0 API
     # The actual public API for this is the inline function
     # `PyDataType_GetArrFuncs` checks for the NumPy runtime version.
     '_PyDataType_GetArrFuncs':                       (365,),
+    # End 2.0 API
 }
 
 ufunc_types_api = {

diff --git a/numpy/_core/src/multiarray/array_coercion.c b/numpy/_core/src/multiarray/array_coercion.c
@@ -431,7 +431,8 @@ npy_cast_raw_scalar_item(
 }
 
 
-/**
+/*NUMPY_API
+ **
  * Assign a single element in an array from a python value.
  *
  * The dtypes SETITEM should only be trusted to generally do the right
@@ -471,7 +472,7 @@ npy_cast_raw_scalar_item(
  * @return 0 on success -1 on failure.
  */
 NPY_NO_EXPORT int
-PyArray_Pack(PyArray_Descr *descr, char *item, PyObject *value)
+PyArray_Pack(PyArray_Descr *descr, void *item, PyObject *value)
 {
     PyArrayObject_fields arr_fields = {
             .flags = NPY_ARRAY_WRITEABLE,  /* assume array is not behaved. */

diff --git a/numpy/_core/src/multiarray/array_coercion.h b/numpy/_core/src/multiarray/array_coercion.h
@@ -28,7 +28,7 @@ npy_cast_raw_scalar_item(
         PyArray_Descr *to_descr, char *to_item);
 
 NPY_NO_EXPORT int
-PyArray_Pack(PyArray_Descr *descr, char *item, PyObject *value);
+PyArray_Pack(PyArray_Descr *descr, void *item, PyObject *value);
 
 NPY_NO_EXPORT PyArray_Descr *
 PyArray_AdaptDescriptorToArray(