gh-141004: Document Py_RETURN_NAN and Py_RETURN_INF

[ZeroIntensity]

• Issue: Document the entire C API #141004

---

📚 Documentation preview 📚: https://cpython-previews--141029.org.readthedocs.build/en/141029/c-api/float.html#c.Py_RETURN_NAN

[encukou]

Macro docs should generally include the expansion (perhaps simplified).
Docs for function-like macros should include arguments.

[ZeroIntensity]

Unfortunately, that's a little tricky here, because the definition involves Py_NAN and Py_INFINITY, which aren't documented either (and probably things we should make private).

Take a look at something like Py_RETURN_NONE for precedent. I think this is clear and fine for users.

[encukou]

Take a look at something like Py_RETURN_NONE for precedent. I think this is clear and fine for users.

I disagree there. I think it's clear as mud to someone who'd see it for the first time.
For Py_RETURN_NONE you can search for examples easily, but not so much for these.

Unfortunately, that's a little tricky here, because the definition involves Py_NAN and Py_INFINITY, which aren't documented either (and probably things we should make private).

The expansion can be approximate -- it should illustrate the concept for to C programmers, and be a hint for the non-C ones (who generally can't use headers and need to reimplement macros).
So you can say, for example, that “on platforms where Python's math.nan uses the C99 NAN macro, it's equivalent to: return PyFloat_FromDouble(NAN)”.

But I'd also be fine with Py_NAN & Py_INFINITY being fully public, documented as primitive values of Python's math.nan and math.inf, and (equivalently) cross-platform versions of C99's NAN and INFINITY.
(Not great for stable ABI – platforms without IEEE floats might need a more elaborate nan representation than a C float. But it's a case for practicality beating purity.)

[skirpichev]

Macro docs should generally include the expansion (perhaps simplified).

I agree, we shouldn't use pure-Python world equivalents.

Unfortunately, that's a little tricky here, because the definition involves Py_NAN and Py_INFINITY, which aren't documented either (and probably things we should make private).

See issue thread on fate of such macros. I hope we could reference to INFINITY/NAN from the C standard.

[ZeroIntensity]

Ok, I've updated it to include the macro expansion using C99's NAN and INFINITY. I'll adjust if we decide to make Py_NAN and Py_INFINITY public.

[skirpichev]

Note that neither macro is used in the CPython codebase. Do we need them at all?

Both return PyFloat_FromDouble(+/-INFINITY) or return PyFloat_FromDouble(NAN) are readable enough.

[ZeroIntensity]

Note that neither macro is used in the CPython codebase. Do we need them at all?

Is it used in any third parties? (We should document the macro nonetheless, but perhaps we could deprecate it.)

[skirpichev]

Is it used in any third parties?

It seems so, I see few matches in the Github search. Though, nothing that can't be replaced by something like return PyFloat_FromDouble(INFINITY*sign);, ditto for Py_RETURN_NAN. I think at least soft deprecation does make sense.

[ZeroIntensity]

If there's actual usage, I don't see why we need to deprecate these at all. They don't pose a maintenance issue.

[ZeroIntensity]

Ok, I'm going to merge this. @encukou, if you'd like to deprecate these, let's do that in a separate PR for 3.15 only. I personally don't see any need to deprecate them.

[miss-islington-app]

Thanks @ZeroIntensity for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-141074 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-141075 is a backport of this pull request to the 3.13 branch.