From: Sergey B Kirpichev <skirpichev@gmail.com>
Date: Tue, 18 Nov 2025 09:17:37 +0000 (+0300)
Subject: gh-141004: Document Py_HUGE_VAL/IS_FINITE/IS_INFINITE/IS_NAN (#141544)
X-Git-Tag: v3.15.0a2~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=630cd37bfae0fc4021d9e9461b94d36e7ce6b95c;p=thirdparty%2FPython%2Fcpython.git

gh-141004: Document Py_HUGE_VAL/IS_FINITE/IS_INFINITE/IS_NAN (#141544)

Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---

diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index 79de5daaa90d..b0d440580b98 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -87,7 +87,7 @@ Floating-Point Objects
    ``<math.h>`` header.
 
    .. deprecated:: 3.15
-      The macro is soft deprecated.
+      The macro is :term:`soft deprecated`.
 
 
 .. c:macro:: Py_NAN
@@ -99,6 +99,14 @@ Floating-Point Objects
    the C11 standard ``<math.h>`` header.
 
 
+.. c:macro:: Py_HUGE_VAL
+
+   Equivalent to :c:macro:`!INFINITY`.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.
+
+
 .. c:macro:: Py_MATH_E
 
    The definition (accurate for a :c:expr:`double` type) of the :data:`math.e` constant.
@@ -147,6 +155,34 @@ Floating-Point Objects
       return PyFloat_FromDouble(copysign(INFINITY, sign));
 
 
+.. c:macro:: Py_IS_FINITE(X)
+
+   Return ``1`` if the given floating-point number *X* is finite,
+   that is, it is normal, subnormal or zero, but not infinite or NaN.
+   Return ``0`` otherwise.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.  Use :c:macro:`!isfinite` instead.
+
+
+.. c:macro:: Py_IS_INFINITY(X)
+
+   Return ``1`` if the given floating-point number *X* is positive or negative
+   infinity.  Return ``0`` otherwise.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.  Use :c:macro:`!isinf` instead.
+
+
+.. c:macro:: Py_IS_NAN(X)
+
+   Return ``1`` if the given floating-point number *X* is a not-a-number (NaN)
+   value.  Return ``0`` otherwise.
+
+   .. deprecated:: 3.14
+      The macro is :term:`soft deprecated`.  Use :c:macro:`!isnan` instead.
+
+
 Pack and Unpack functions
 -------------------------