gh-135755: Docs: C API: Document missing PyFunction_GET* macros

[ZeroIntensity]

I'm documenting all of these before getting to PyFunction_GET_BUILTINS, because this needs to be backported to 3.13. I'll document PyFunction_GET_BUILTINS in a follow-up that goes only to 3.14.

I've included versionadded directives for a few APIs that were added in 3.0 (PEP-3102 and PEP-3107), but I don't know if those are particularly useful these days. AFAIK, it's a controversial topic.

• Issue: Undocumented 3.14 C API #135755

---

📚 Documentation preview 📚: https://cpython-previews--135762.org.readthedocs.build/en/135762/c-api/function.html#function-objects

[picnixz]

I'd appreciate if we have the "Return value: borrowed reference" for those functions (i.e., update refcounts.dat to add those entries).

[picnixz]

Looks good now:

[encukou]

Hm, that's a lot of repetition.
It might be easier for the reader -- and still semantically correct -- to put them all in a single block like this:

.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op)
                PyObject *PyFunction_GET_GLOBALS(PyObject *op)
                PyObject *PyFunction_GET_MODULE(PyObject *op)
                PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
                PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
                PyObject *PyFunction_GET_CLOSURE(PyObject *op)
                PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)

   These macros are equivalent to the respective ``PyFunction_GetCode*``
   functions documented above, except they do no type checking.
   That is, if *op* is not of type :c:data:`PyFunction_Type`, the behavior
   is undefined.

We don't use versionadded:: for differences from 2.x; I don't think we should start now.
(What's controversial is whether we should remove versionadded:: 3.1 and such.)

[ZeroIntensity]

Do we lose the reference count effect when we do that?

[encukou]

Visually, it's at the end of the block. Together with the “equivalent to the respective functions” bit, I think it's enough.

[ZeroIntensity]

Ok, I've updated it. Let me know what you think of the wording I chose.

[encukou]

Thank you!

[miss-islington-app]

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

[bedevere-app]

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

[bedevere-app]

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