PyCFunction_New is not documented

[encukou]

PyCFunction_New, PyCFunction_NewEx and PyCMethod_New, which can be used to turn PyMethodDef into a Python callable, are currently not documented, though they're useful, stable, and used in the wild.

Linked PRs

• gh-102468: Document PyCFunction_New* and PyCMethod_New #112557
• [3.12] gh-102468: Document PyCFunction_New* and PyCMethod_New (GH-112557) #114119
• [3.11] gh-102468: Document PyCFunction_New* and PyCMethod_New (GH-112557) #114120

[TannerFirl]

Should PyThread_start_new_thread be documented as well?

vscode ➜ /workspaces/cpython (main) $ git grep -n PyThread_start_new_thread
Doc/data/stable_abi.dat:644:function,PyThread_start_new_thread,3.2,,
Doc/whatsnew/3.7.rst:1709:The type of results of :c:func:`PyThread_start_new_thread` and
Include/pythread.h:19:PyAPI_FUNC(unsigned long) PyThread_start_new_thread(void (*)(void *), void *);

[TannerFirl]

And these in cpython/Include/methodobject.h?

PyAPI_FUNC(PyCFunction) PyCFunction_GetFunction(PyObject *);
PyAPI_FUNC(PyObject *) PyCFunction_GetSelf(PyObject *);
PyAPI_FUNC(int) PyCFunction_GetFlags(PyObject *);

[encukou]

Well, anything in https://docs.python.org/3/c-api/stable.html#contents-of-limited-api that's not a link should be either documented or deprecated. Or both, but documenting some of them might not be the best use of time.

PyCFunction_GetFlags should be deprecated, IMO.
AFAIK, it's nearly impossible to use PyCFunction_GetFunction correctly without PyCFunction_GetFlags -- unless you somehow know what the function pointer type is, but then it'd be better if it was exposed directly in C.
I don't know enough about PyThread_start_new_thread.

Anyway, I definitely wouldn't document them in the same pull request.

[ramvikrams]

@encukou Acutally in which file should those be documented

[encukou]

Probably Doc/c-api/structures.rst, in the Implementing functions and methods section along with PyMethodDef.

[ramvikrams]

Probably Doc/c-api/structures.rst, in the Implementing functions and methods section along with PyMethodDef.

Thanks I'll do it