Ensuring True NumPy ndarrays in C++: When to Use PyArray_CheckExact()

Purpose

• It returns an integer value:
  • 1 (True): If op is a bona fide NumPy ndarray.
  • 0 (False): If op is not a NumPy ndarray or is a subclass of it.
• PyArray_CheckExact() is a function in the NumPy C-API that determines if a given Python object (op) is an exact NumPy ndarray (n-dimensional array).

Importance

• PyArray_CheckExact() helps you verify if an object is a genuine NumPy ndarray, allowing you to interact with it appropriately using the NumPy C-API functions.
• When working with C or C++ extensions for Python, you might encounter objects that resemble NumPy arrays but aren't necessarily true ndarrays.

Usage

1. • To use PyArray_CheckExact(), you need to include the numpy/arraytypes.h header file in your C or C++ code:

   #include <numpy/arraytypes.h>
   

2. Call the Function
   

   • Pass the Python object you want to check as an argument to PyArray_CheckExact():

   PyObject *my_object;  // Your Python object (potentially an array)
   
   if (PyArray_CheckExact(my_object)) {
       // Handle the object as a true NumPy ndarray
       // (use other NumPy C-API functions for manipulation)
   } else {
       // Handle the object as something else
   }
   

Key Points

• For typical Python projects using the NumPy API, import NumPy using PyArray_ImportNumPyAPI() or import_array() for full functionality. However, if you only need type definitions for basic use cases, including numpy/arraytypes.h is sufficient.
• If you only need to confirm that an object has the NumPy array interface (not necessarily a strict ndarray), use PyArray_HasArrayInterface() instead.
• PyArray_CheckExact() is more stringent than PyArray_Check(), which also checks for subclasses of PyArray_Type.

---

#include <Python.h>
#include <numpy/arraytypes.h>

// Function to check if a Python object is a true NumPy ndarray
bool is_exact_ndarray(PyObject* obj) {
  if (PyArray_CheckExact(obj)) {
    return true;
  } else {
    return false;
  }
}

// Example usage in a Python extension function
static PyObject* my_extension_function(PyObject* self, PyObject* args) {
  PyObject* input_array;

  if (!PyArg_ParseTuple(args, "O", &input_array)) {
    PyErr_SetString(PyExc_ValueError, "Expected a single argument");
    return NULL;
  }

  if (is_exact_ndarray(input_array)) {
    // Now you can safely use NumPy C-API functions on input_array
    // (e.g., get dimensions, data type, element access, etc.)
    PyArray_Descr* descr = PyArray_DescrFromObject(input_array);
    int ndim = PyArray_NDIM(input_array);

    printf("Input array is a true NumPy ndarray with %d dimensions and data type: %s\n", ndim, PyArray_Descr_Converter(descr));
  } else {
    PyErr_SetString(PyExc_TypeError, "Input is not a true NumPy ndarray");
    return NULL;
  }

  Py_RETURN_NONE;
}

// Module definition
static PyMethodDef my_extension_methods[] = {
  {"is_exact_ndarray", my_extension_function, METH_VARARGS, "Checks if the input is a true NumPy ndarray"},
  {NULL, NULL, 0, NULL} /* Sentinel */
};

static struct PyModuleDef my_extension_module = {
  PyModuleDef_HEAD_INIT,
  "my_extension", /* Module name */
  "Example extension using NumPy C-API",
  -1,
  my_extension_methods
};

PyMODINIT_FUNC PyInit_my_extension(void) {
  return PyModuleDef_Init(&my_extension_module);
}

1. • Python.h for general Python C API functions.
   • numpy/arraytypes.h for PyArray_CheckExact().

2. is_exact_ndarray Function
   

   • Takes a Python object (obj).
   • Uses PyArray_CheckExact() to verify if it's a true ndarray.
   • Returns true if it is, false otherwise.

3. my_extension_function
   

   • A sample extension function that takes a single argument.
   • Parses the argument using PyArg_ParseTuple.
   • Calls is_exact_ndarray to check the input.
   • If it's a true ndarray, retrieves the descriptor (PyArray_DescrFromObject) and number of dimensions (PyArray_NDIM).
   • Prints information about the array.
   • Handles errors using PyErr_SetString.

4. Module Definition
   

   • Defines the extension module named "my_extension" with a docstring and a list of methods (my_extension_methods).
   • The sentinel ({NULL, NULL, 0, NULL}) marks the end of the method list.

5. Initialization Function (PyMODINIT_FUNC)
   

   • Initializes the module using PyModuleDef_Init.

Compilation and Usage

1. Compile this code into a shared library (e.g., .so on Linux, .pyd on Windows) using a C++ compiler that supports Python extensions.

2. Import the module in your Python code:

   import my_extension
   
   # Example usage
   arr = np.array([1, 2, 3])
   result = my_extension.is_exact_ndarray(arr)
   print(result)  # Output: True
   

---

1. • Purpose: Similar to PyArray_CheckExact(), it checks if a Python object is a NumPy array (including subclasses of PyArray_Type).
   • Difference: PyArray_Check() is less strict. It returns True even if the object is a subclass of ndarray, whereas PyArray_CheckExact() only returns True for strict ndarray instances.
   • Use Case: If you want to handle both standard ndarrays and potential subclasses that implement the NumPy array interface, use PyArray_Check().

2. PyArray_HasArrayInterface()
   

   • Purpose: Determines if a Python object exposes the NumPy array interface, regardless of whether it's a true ndarray.
   • Use Case: This is useful when you need to interact with objects that might be array-like but not necessarily NumPy ndarrays. It allows you to use some generic array operations on these objects if they provide the NumPy array interface.

Choosing the Right Alternative

• If you're open to handling subclasses or objects with the NumPy array interface, consider PyArray_Check() or PyArray_HasArrayInterface().
• If you absolutely need to work with genuine NumPy ndarrays and avoid subclasses, use PyArray_CheckExact().

Function	Description	Use Case
PyArray_CheckExact()	Checks for a true NumPy ndarray (no subclasses)	Ensure strict ndarray type for precise NumPy C-API interactions
PyArray_Check()	Checks for a NumPy array (including subclasses)	Handle both ndarrays and potential subclasses with the NumPy array interface
PyArray_HasArrayInterface()	Checks if an object exposes the NumPy array interface	Interact with array-like objects that might not be true NumPy ndarrays

Remember

• The C-API checks become more relevant when writing C or C++ extensions that interact directly with NumPy data structures.
• For typical Python projects using the NumPy API at a higher level, importing NumPy with PyArray_ImportNumPyAPI() or import_array() provides the necessary functionality without needing these low-level checks.