Merge pull request numpy#27182 from seberg/revert-I

REV: Revert undef I and document it

Author: charris

doc/source/numpy_2_0_migration_guide.rst

@@ -220,6 +220,19 @@ using the NumPy types. You can still write cython code using the ``c.real`` and
 ``c.imag`` attributes (using the native typedefs), but you can no longer use
 in-place operators ``c.imag += 1`` in Cython's c++ mode.
 
+Because NumPy 2 now includes ``complex.h`` code that uses a variable named
+``I`` may see an error such as
+
+.. code-block::C
+   error: expected ‘)’ before ‘__extension__’
+                    double I,
+
+to use the name ``I`` requires an ``#undef I`` now.
+
+.. note::
+  NumPy 2.0.1 briefly included the ``#undef I`` to help users not already
+  including ``complex.h``.
+
 
 Changes to namespaces
 =====================

doc/source/reference/c-api/types-and-structures.rst

@@ -1611,3 +1611,29 @@ for completeness and assistance in understanding the code.
    ``arrayobject.h`` header. This type is not exposed to Python and
    could be replaced with a C-structure. As a Python type it takes
    advantage of reference- counted memory management.
+
+
+NumPy C-API and C complex
+=========================
+When you use the NumPy C-API, you will have access to complex real declarations
+``npy_cdouble`` and ``npy_cfloat``, which are declared in terms of the C
+standard types from ``complex.h``. Unfortunately, ``complex.h`` contains
+`#define I ...`` (where the actual definition depends on the compiler), which
+means that any downstream user that does ``#include <numpy/arrayobject.h>``
+could get ``I`` defined, and using something like declaring ``double I;`` in
+their code will result in an obscure compiler error like
+
+.. code-block::C
+    error: expected ‘)’ before ‘__extension__’
+                    double I,
+
+This error can be avoided  by adding::
+
+    #undef I
+
+to your code.
+
+.. versionchanged:: 2.0
+    The inclusion of ``complex.h`` was new in NumPy 2, so that code defining
+    a different ``I`` may not have required the ``#undef I`` on older versions.
+    NumPy 2.0.1 briefly included the ``#under I``

numpy/_core/include/numpy/npy_common.h

@@ -379,11 +379,6 @@ typedef struct
 
 #include <complex.h>
 
-// Downstream libraries like sympy would like to use I
-// see https://github.com/numpy/numpy/issues/26787
-#ifdef I
-#undef I
-#endif
 
 #if defined(_MSC_VER) && !defined(__INTEL_COMPILER)
 typedef _Dcomplex npy_cdouble;