pythongh-141004: soft-deprecate Py_INFINITY macro (python#141033)

skirpichev · vstinner · web-flow · commit e2026731f568 · 2025-11-12T13:44:49.000+01:00
Co-authored-by: Victor Stinner &lt;vstinner@python.org&gt;
diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst
@@ -105,7 +105,7 @@ The following functions provide locale-independent string to number conversions.
 
    If ``s`` represents a value that is too large to store in a float
    (for example, ``"1e500"`` is such a string on many platforms) then
-   if ``overflow_exception`` is ``NULL`` return ``Py_INFINITY`` (with
+   if ``overflow_exception`` is ``NULL`` return :c:macro:`!INFINITY` (with
    an appropriate sign) and don't set any exception.  Otherwise,
    ``overflow_exception`` must point to a Python exception object;
    raise that exception and return ``-1.0``.  In both cases, set
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
@@ -83,8 +83,11 @@ Floating-Point Objects
    This macro expands a to constant expression of type :c:expr:`double`, that
    represents the positive infinity.
 
-   On most platforms, this is equivalent to the :c:macro:`!INFINITY` macro from
-   the C11 standard ``<math.h>`` header.
+   It is equivalent to the :c:macro:`!INFINITY` macro from the C11 standard
+   ``<math.h>`` header.
+
+   .. deprecated:: 3.15
+      The macro is soft deprecated.
 
 
 .. c:macro:: Py_NAN
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -3045,7 +3045,7 @@ Deprecated C APIs
 -----------------
 
 * The :c:macro:`!Py_HUGE_VAL` macro is now :term:`soft deprecated`.
-  Use :c:macro:`!Py_INFINITY` instead.
+  Use :c:macro:`!INFINITY` instead.
   (Contributed by Sergey B Kirpichev in :gh:`120026`.)
 
 * The :c:macro:`!Py_IS_NAN`, :c:macro:`!Py_IS_INFINITY`,
diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
@@ -1095,6 +1095,10 @@ Deprecated C APIs
   since 3.15 and will be removed in 3.17.
   (Contributed by Nikita Sobolev in :gh:`136355`.)
 
+* :c:macro:`!Py_INFINITY` macro is :term:`soft deprecated`,
+  use the C11 standard ``<math.h>`` :c:macro:`!INFINITY` instead.
+  (Contributed by Sergey B Kirpichev in :gh:`141004`.)
+
 * :c:macro:`!Py_MATH_El` and :c:macro:`!Py_MATH_PIl` are deprecated
   since 3.15 and will be removed in 3.20.
   (Contributed by Sergey B Kirpichev in :gh:`141004`.)
diff --git a/Include/floatobject.h b/Include/floatobject.h
@@ -18,14 +18,14 @@ PyAPI_DATA(PyTypeObject) PyFloat_Type;
 
 #define Py_RETURN_NAN return PyFloat_FromDouble(Py_NAN)
 
-#define Py_RETURN_INF(sign)                          \
-    do {                                             \
-        if (copysign(1., sign) == 1.) {              \
-            return PyFloat_FromDouble(Py_INFINITY);  \
-        }                                            \
-        else {                                       \
-            return PyFloat_FromDouble(-Py_INFINITY); \
-        }                                            \
+#define Py_RETURN_INF(sign)                       \
+    do {                                          \
+        if (copysign(1., sign) == 1.) {           \
+            return PyFloat_FromDouble(INFINITY);  \
+        }                                         \
+        else {                                    \
+            return PyFloat_FromDouble(-INFINITY); \
+        }                                         \
     } while(0)
 
 PyAPI_FUNC(double) PyFloat_GetMax(void);
diff --git a/Include/internal/pycore_pymath.h b/Include/internal/pycore_pymath.h
@@ -33,7 +33,7 @@ extern "C" {
 static inline void _Py_ADJUST_ERANGE1(double x)
 {
     if (errno == 0) {
-        if (x == Py_INFINITY || x == -Py_INFINITY) {
+        if (x == INFINITY || x == -INFINITY) {
             errno = ERANGE;
         }
     }
@@ -44,8 +44,8 @@ static inline void _Py_ADJUST_ERANGE1(double x)
 
 static inline void _Py_ADJUST_ERANGE2(double x, double y)
 {
-    if (x == Py_INFINITY || x == -Py_INFINITY ||
-        y == Py_INFINITY || y == -Py_INFINITY)
+    if (x == INFINITY || x == -INFINITY ||
+        y == INFINITY || y == -INFINITY)
     {
         if (errno == 0) {
             errno = ERANGE;
diff --git a/Include/pymath.h b/Include/pymath.h
@@ -45,13 +45,14 @@
 #define Py_IS_FINITE(X) isfinite(X)
 
 // Py_INFINITY: Value that evaluates to a positive double infinity.
+// Soft deprecated since Python 3.15, use INFINITY instead.
 #ifndef Py_INFINITY
 #  define Py_INFINITY ((double)INFINITY)
 #endif
 
 /* Py_HUGE_VAL should always be the same as Py_INFINITY.  But historically
  * this was not reliable and Python did not require IEEE floats and C99
- * conformity.  The macro was soft deprecated in Python 3.14, use Py_INFINITY instead.
+ * conformity.  The macro was soft deprecated in Python 3.14, use INFINITY instead.
  */
 #ifndef Py_HUGE_VAL
 #  define Py_HUGE_VAL HUGE_VAL
diff --git a/Misc/NEWS.d/next/C_API/2025-11-05-04-38-16.gh-issue-141004.rJL43P.rst b/Misc/NEWS.d/next/C_API/2025-11-05-04-38-16.gh-issue-141004.rJL43P.rst
@@ -0,0 +1 @@
+The :c:macro:`!Py_INFINITY` macro is :term:`soft deprecated`.
diff --git a/Modules/cmathmodule.c b/Modules/cmathmodule.c
@@ -150,7 +150,7 @@ special_type(double d)
 #define P14 0.25*Py_MATH_PI
 #define P12 0.5*Py_MATH_PI
 #define P34 0.75*Py_MATH_PI
-#define INF Py_INFINITY
+#define INF INFINITY
 #define N Py_NAN
 #define U -9.5426319407711027e33 /* unlikely value, used as placeholder */
 
@@ -1186,11 +1186,11 @@ cmath_exec(PyObject *mod)
     if (PyModule_Add(mod, "tau", PyFloat_FromDouble(Py_MATH_TAU)) < 0) {
         return -1;
     }
-    if (PyModule_Add(mod, "inf", PyFloat_FromDouble(Py_INFINITY)) < 0) {
+    if (PyModule_Add(mod, "inf", PyFloat_FromDouble(INFINITY)) < 0) {
         return -1;
     }
 
-    Py_complex infj = {0.0, Py_INFINITY};
+    Py_complex infj = {0.0, INFINITY};
     if (PyModule_Add(mod, "infj", PyComplex_FromCComplex(infj)) < 0) {
         return -1;
     }
diff --git a/Modules/mathmodule.c b/Modules/mathmodule.c
@@ -395,7 +395,7 @@ m_tgamma(double x)
     if (x == 0.0) {
         errno = EDOM;
         /* tgamma(+-0.0) = +-inf, divide-by-zero */
-        return copysign(Py_INFINITY, x);
+        return copysign(INFINITY, x);
     }
 
     /* integer arguments */
@@ -426,7 +426,7 @@ m_tgamma(double x)
         }
         else {
             errno = ERANGE;
-            return Py_INFINITY;
+            return INFINITY;
         }
     }
 
@@ -490,14 +490,14 @@ m_lgamma(double x)
         if (isnan(x))
             return x;  /* lgamma(nan) = nan */
         else
-            return Py_INFINITY; /* lgamma(+-inf) = +inf */
+            return INFINITY; /* lgamma(+-inf) = +inf */
     }
 
     /* integer arguments */
     if (x == floor(x) && x <= 2.0) {
         if (x <= 0.0) {
             errno = EDOM;  /* lgamma(n) = inf, divide-by-zero for */
-            return Py_INFINITY; /* integers n <= 0 */
+            return INFINITY; /* integers n <= 0 */
         }
         else {
             return 0.0; /* lgamma(1) = lgamma(2) = 0.0 */
@@ -633,7 +633,7 @@ m_log(double x)
             return log(x);
         errno = EDOM;
         if (x == 0.0)
-            return -Py_INFINITY; /* log(0) = -inf */
+            return -INFINITY; /* log(0) = -inf */
         else
             return Py_NAN; /* log(-ve) = nan */
     }
@@ -676,7 +676,7 @@ m_log2(double x)
     }
     else if (x == 0.0) {
         errno = EDOM;
-        return -Py_INFINITY; /* log2(0) = -inf, divide-by-zero */
+        return -INFINITY; /* log2(0) = -inf, divide-by-zero */
     }
     else {
         errno = EDOM;
@@ -692,7 +692,7 @@ m_log10(double x)
             return log10(x);
         errno = EDOM;
         if (x == 0.0)
-            return -Py_INFINITY; /* log10(0) = -inf */
+            return -INFINITY; /* log10(0) = -inf */
         else
             return Py_NAN; /* log10(-ve) = nan */
     }
@@ -1500,7 +1500,7 @@ math_ldexp_impl(PyObject *module, double x, PyObject *i)
         errno = 0;
     } else if (exp > INT_MAX) {
         /* overflow */
-        r = copysign(Py_INFINITY, x);
+        r = copysign(INFINITY, x);
         errno = ERANGE;
     } else if (exp < INT_MIN) {
         /* underflow to +-0 */
@@ -2983,7 +2983,7 @@ math_ulp_impl(PyObject *module, double x)
     if (isinf(x)) {
         return x;
     }
-    double inf = Py_INFINITY;
+    double inf = INFINITY;
     double x2 = nextafter(x, inf);
     if (isinf(x2)) {
         /* special case: x is the largest positive representable float */
@@ -3007,7 +3007,7 @@ math_exec(PyObject *module)
     if (PyModule_Add(module, "tau", PyFloat_FromDouble(Py_MATH_TAU)) < 0) {
         return -1;
     }
-    if (PyModule_Add(module, "inf", PyFloat_FromDouble(Py_INFINITY)) < 0) {
+    if (PyModule_Add(module, "inf", PyFloat_FromDouble(INFINITY)) < 0) {
         return -1;
     }
     if (PyModule_Add(module, "nan", PyFloat_FromDouble(fabs(Py_NAN))) < 0) {
diff --git a/Objects/complexobject.c b/Objects/complexobject.c
@@ -139,8 +139,8 @@ _Py_c_prod(Py_complex z, Py_complex w)
             recalc = 1;
         }
         if (recalc) {
-            r.real = Py_INFINITY*(a*c - b*d);
-            r.imag = Py_INFINITY*(a*d + b*c);
+            r.real = INFINITY*(a*c - b*d);
+            r.imag = INFINITY*(a*d + b*c);
         }
     }
 
@@ -229,8 +229,8 @@ _Py_c_quot(Py_complex a, Py_complex b)
         {
             const double x = copysign(isinf(a.real) ? 1.0 : 0.0, a.real);
             const double y = copysign(isinf(a.imag) ? 1.0 : 0.0, a.imag);
-            r.real = Py_INFINITY * (x*b.real + y*b.imag);
-            r.imag = Py_INFINITY * (y*b.real - x*b.imag);
+            r.real = INFINITY * (x*b.real + y*b.imag);
+            r.imag = INFINITY * (y*b.real - x*b.imag);
         }
         else if ((isinf(abs_breal) || isinf(abs_bimag))
                  && isfinite(a.real) && isfinite(a.imag))
diff --git a/Objects/floatobject.c b/Objects/floatobject.c
@@ -2415,7 +2415,7 @@ PyFloat_Unpack2(const char *data, int le)
     if (e == 0x1f) {
         if (f == 0) {
             /* Infinity */
-            return sign ? -Py_INFINITY : Py_INFINITY;
+            return sign ? -INFINITY : INFINITY;
         }
         else {
             /* NaN */
diff --git a/Python/pystrtod.c b/Python/pystrtod.c
@@ -43,7 +43,7 @@ _Py_parse_inf_or_nan(const char *p, char **endptr)
         s += 3;
         if (case_insensitive_match(s, "inity"))
             s += 5;
-        retval = negate ? -Py_INFINITY : Py_INFINITY;
+        retval = negate ? -INFINITY : INFINITY;
     }
     else if (case_insensitive_match(s, "nan")) {
         s += 3;
@@ -286,7 +286,7 @@ _PyOS_ascii_strtod(const char *nptr, char **endptr)
    string, -1.0 is returned and again ValueError is raised.
 
    On overflow (e.g., when trying to convert '1e500' on an IEEE 754 machine),
-   if overflow_exception is NULL then +-Py_INFINITY is returned, and no Python
+   if overflow_exception is NULL then +-INFINITY is returned, and no Python
    exception is raised.  Otherwise, overflow_exception should point to
    a Python exception, this exception will be raised, -1.0 will be returned,
    and *endptr will point just past the end of the converted value.

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@ extern "C" {`
`33`	`33`	`static inline void _Py_ADJUST_ERANGE1(double x)`
`34`	`34`	`{`
`35`	`35`	`if (errno == 0) {`
`36`		`- if (x == Py_INFINITY \|\| x == -Py_INFINITY) {`
	`36`	`+ if (x == INFINITY \|\| x == -INFINITY) {`
`37`	`37`	`errno = ERANGE;`
`38`	`38`	`}`
`39`	`39`	`}`
`@@ -44,8 +44,8 @@ static inline void _Py_ADJUST_ERANGE1(double x)`
`44`	`44`
`45`	`45`	`static inline void _Py_ADJUST_ERANGE2(double x, double y)`
`46`	`46`	`{`
`47`		`- if (x == Py_INFINITY \|\| x == -Py_INFINITY \|\|`
`48`		`- y == Py_INFINITY \|\| y == -Py_INFINITY)`
	`47`	`+ if (x == INFINITY \|\| x == -INFINITY \|\|`
	`48`	`+ y == INFINITY \|\| y == -INFINITY)`
`49`	`49`	`{`
`50`	`50`	`if (errno == 0) {`
`51`	`51`	`errno = ERANGE;`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+The :c:macro:`!Py_INFINITY` macro is :term:`soft deprecated`.