Undocumented 3.14 C API

[encukou]

The following public C API is new in 3.14 (beta 3 & 4, relative to 3.13.0), and as of this writing it looks either:

• undocumented,
• documented incorrectly, or
• public by mistake.

previously: 3.13

---

• Py_INCREF_MORTAL: Include/refcount.h:251 (Use tagged pointers on the stack in the default build. #127705 (comment))
• MAX_SCRIPT_PATH_SIZE: Include/cpython/pystate.h:31 (PEP 768, gh-131591: Add Py_ prefix to MAX_SCRIPT_PATH_SIZE; remove unprefixed struct tag #135924)
  • Py_MAX_SCRIPT_PATH_SIZE
• PyFunction_GET_BUILTINS: Include/cpython/funcobject.h:100 (added in gh-132775: Add _PyCode_GetVarCounts() #133128; assigned to @ZeroIntensity) (gh-135755: Move PyFunction_GET_BUILTINS to the private API #135938)
• struct _remote_debugger_support: Include/cpython/pystate.h:32 (PEP 768, gh-131591: Add Py_ prefix to MAX_SCRIPT_PATH_SIZE; remove unprefixed struct tag #135924)

"PYOS" (#135928):

• PYOS_LOG2_STACK_MARGIN: Include/pythonrun.h
• PYOS_STACK_MARGIN_BYTES: Include/pythonrun.h
• PYOS_STACK_MARGIN_SHIFT: Include/pythonrun.h

"SPECIAL" (#135922):

• SPECIAL_MAX: Include/ceval.h
• SPECIAL___AENTER__: Include/ceval.h
• SPECIAL___AEXIT__: Include/ceval.h
• SPECIAL___ENTER__: Include/ceval.h
• SPECIAL___EXIT__: Include/ceval.h

Header guards (traditionally named Py_*_H, but a leading underscore would be better for new ones) (#135921):

• Py_AUDIT_H: Include/audit.h
• Py_CPYTHON_AUDIT_H: Include/audit.h
• Py_REFCOUNT_H: Include/refcount.h

New configure constants.
(IMO, if we don't want users to touch these, they should use the _Py prefix.
If we do want users to use them, they need docs.)

• Py_FFI_SUPPORT_C_COMPLEX (gh-125206: Make _Py_FFI_SUPPORT_C_COMPLEX private #135932)
• Py_NORMALIZE_CENTURY (gh-120713: Make _Py_NORMALIZE_CENTURY private #135933)
• Py_REMOTE_DEBUG (gh-131591: Document Py_REMOTE_DEBUG #135929)
• HACL_CAN_COMPILE_SIMD128 (gh-135755: rename undocumented HACL_CAN_COMPILE_SIMD{128,256} macros #135847)
• HACL_CAN_COMPILE_SIMD256 (gh-135755: rename undocumented HACL_CAN_COMPILE_SIMD{128,256} macros #135847)

New HAVE configure constants -- a lost cause:

• HAVE_BACKTRACE
• HAVE_DECL_UT_NAMESIZE
• HAVE_DLADDR
• HAVE_DLADDR1
• HAVE_EXECINFO_H
• HAVE_GETLOGIN_R
• HAVE_LINK_H
• HAVE_LINUX_NETFILTER_IPV4_H
• HAVE_LINUX_SCHED_H
• HAVE_PTHREAD_GETATTR_NP
• HAVE_PTHREAD_GETNAME_NP
• HAVE_PTHREAD_SETNAME_NP
• HAVE_SYS_PIDFD_H3
• HAVE_TTYNAME_R
• HAVE_USABLE_WCHAR_T
• HAVE_UT_NAMESIZE

New CO_ flags (documented in inspect; Sphinx sees none of these as C macros): (#135980)

• CO_HAS_DOCSTRING: Include/cpython/code.h:115
• CO_METHOD: Include/cpython/code.h:115

Linked PRs

• gh-135755: Docs: C API: Document missing PyFunction_GET* macros #135762
• gh-135755: rename undocumented HACL_CAN_COMPILE_SIMD{128,256} macros #135847
• gh-95245: Document Py_TPFLAGS_PREHEADER #135861
• [3.14] gh-135755: Docs: C API: Document missing PyFunction_GET* macros (GH-135762) #135916
• [3.13] gh-135755: Docs: C API: Document missing PyFunction_GET* macros (GH-135762) #135917
• gh-135755: Use private names (_Py*) for header file guards new in 3.14 #135921
• gh-135755: Move SPECIAL_ constants to a private header #135922
• [3.14] gh-135755: Move SPECIAL_ constants to a private header (GH-135922) #135926
• gh-135755: Document the new PyFunction_GET_BUILTINS macro #135934
• gh-135755: Move PyFunction_GET_BUILTINS to the private API #135938
• [3.14] gh-135755: Use private names (_Py*) for header file guards new in 3.14 (GH-135921) #135976
• gh-135755: Document __future__.* and CO_* as proper Sphinx objects #135980
• [3.14] gh-135755: rename undocumented HACL_CAN_COMPILE_SIMD{128,256} macros (GH-135847) #136045
• [3.14] gh-135755: Document __future__.* and CO_* as proper Sphinx objects (GH-135980) #136370
• [3.13] gh-135755: Document __future__.* and CO_* as proper Sphinx objects (GH-135980) #136371
• gh-135755: Make Py_MAX_SCRIPT_PATH_SIZE private #138350
• [3.14] gh-135755: Make Py_MAX_SCRIPT_PATH_SIZE private (GH-138350) #138356
• gh-135755: Make Py_TAIL_CALL_INTERP macro private #138981
• [3.14] gh-135755: Make Py_TAIL_CALL_INTERP macro private (#138981) #139120

• Check links above! I prefer attaching doc fixes & renames to issues that added the API.

[ZeroIntensity]

For PyFunction_GET_BUILTINS, I don't think we document any existing PyFunction_GET_* functions. I'm happy to take on documenting all those if you haven't started with it.

[picnixz]

I'll take care of adding the PY_* to HACL ones, though the HACL ones are actually because of mismatches. I actually don't remember why we have those mismatches in the first place...

[encukou]

Thank you, go ahead!
I'd prefer if the people involved in adding them are also involved in the documentation -- it's no always easy to guess the intent :)

[sergey-miryanov]

Should Py_TPFLAGS_PREHEADER (Include/object.h) also be documented?

[encukou]

@sergey-miryanov: Yes, though it was added in 3.12; you might want to reopen #95245 where it was added.