From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 5 Nov 2025 22:05:47 +0000 (+0100)
Subject: [3.14] gh-141004: Document `Py_RETURN_NAN` and `Py_RETURN_INF` (GH-141029) (GH-141074)
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=090c0f140398fa923ac893936a95246d82d53e66;p=thirdparty%2FPython%2Fcpython.git

[3.14] gh-141004: Document `Py_RETURN_NAN` and `Py_RETURN_INF` (GH-141029) (GH-141074)

gh-141004: Document `Py_RETURN_NAN` and `Py_RETURN_INF` (GH-141029)
(cherry picked from commit 5b02c6e920aaef4b202fc19186f742d008460fd3)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
---

diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index 489676caa3a1..1085c32a5370 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -78,6 +78,23 @@ Floating-Point Objects
    Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`.
 
 
+.. c:macro:: Py_RETURN_NAN
+
+   Return :data:`math.nan` from a function.
+
+   On most platforms, this is equivalent to ``return PyFloat_FromDouble(NAN)``.
+
+
+.. c:macro:: Py_RETURN_INF(sign)
+
+   Return :data:`math.inf` or :data:`-math.inf <math.inf>` from a function,
+   depending on the sign of *sign*.
+
+   On most platforms, this is equivalent to the following::
+
+      return PyFloat_FromDouble(copysign(INFINITY, sign));
+
+
 Pack and Unpack functions
 -------------------------