Description

encukou

opened on Jun 20, 2025

Issue body actions

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
next: 3.15

---

• 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.

Activity

1. encukou

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   topic-C-API

   on Jun 20, 2025
2. github-project-automation

   added this to docs issueson Jun 20, 2025
3. github-project-automation

   moved this to Todo in docs issueson Jun 20, 2025
4. AA-Turner

   added

   3.14bugs and security fixesbugs and security fixes

   on Jun 20, 2025
5. ZeroIntensity commented on Jun 20, 2025

   

   ZeroIntensity

   on Jun 20, 2025

   Member

   More actions

   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.

   Reacted by Petr Viktorin
6. picnixz commented on Jun 20, 2025

   

   picnixz

   on Jun 20, 2025

   Member

   More actions

   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...
7. picnixz

   added

   extension-modulesC modules in the Modules dirC modules in the Modules dir

   and removed

   extension-modulesC modules in the Modules dirC modules in the Modules dir

   on Jun 20, 2025
8. encukou commented on Jun 23, 2025

   

   encukou

   on Jun 23, 2025

   MemberAuthor

   More actions

   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 :)
9. sergey-miryanov commented on Jun 23, 2025

   

   sergey-miryanov

   on Jun 23, 2025

   Contributor

   More actions

   Should Py_TPFLAGS_PREHEADER (Include/object.h) also be documented?
10. encukou commented on Jun 23, 2025

    

    encukou

    on Jun 23, 2025

    MemberAuthor

    More actions

    @sergey-miryanov: Yes, though it was added in 3.12; you might want to reopen #95245 where it was added.
11. sergey-miryanov commented on Jun 23, 2025

    

    sergey-miryanov

    on Jun 23, 2025

    Contributor

    More actions

    @encukou I can't reopen #95245 because I haven't rights :) So I added and linked PR to this issue.
12. AA-Turner commented on Jun 24, 2025

    

    AA-Turner

    on Jun 24, 2025

    Member

    More actions

    Now done

    Reacted by Sergey Miryanov
13. encukou

    added a commit that references this issue on Jun 25, 2025

    gh-135755: Docs: C API: Document missing `PyFunction_GET*` macros (GH…

    ca87a47
14. 56 remaining items

15. Fidget-Spinner commented on Sep 1, 2025

    

    Fidget-Spinner

    on Sep 1, 2025

    Member

    More actions

    Should Py_TAIL_CALL_INTERP be made private as well?
16. vstinner commented on Sep 1, 2025

    

    vstinner

    on Sep 1, 2025

    Member

    More actions

    Should Py_TAIL_CALL_INTERP be made private as well?

    Unless there is a clear usage for it in 3rd party code, I would also suggest to make it private.
17. Fidget-Spinner commented on Sep 1, 2025

    

    Fidget-Spinner

    on Sep 1, 2025

    Member

    More actions

    Should Py_TAIL_CALL_INTERP be made private as well?

    Unless there is a clear usage for it in 3rd party code, I would also suggest to make it private.

    Ok I think this should be made private then. Unfortunately, I'm not sure how to do it. Do I just add an underscore in front?
18. vstinner commented on Sep 1, 2025

    

    vstinner

    on Sep 1, 2025

    Member

    More actions

    Ok I think this should be made private then. Unfortunately, I'm not sure how to do it. Do I just add an underscore in front?

    Yes, just add an underscore prefix.
19. pablogsal

    added a commit that references this issue on Sep 1, 2025

    gh-135755: Make Py_MAX_SCRIPT_PATH_SIZE private (#138350)

    aec006b
20. miss-islington

    added a commit that references this issue on Sep 1, 2025

    pythongh-135755: Make Py_MAX_SCRIPT_PATH_SIZE private (pythonGH-138350)

    c2706e4
21. lkollar

    added a commit that references this issue on Sep 9, 2025

    pythongh-135755: Make Py_MAX_SCRIPT_PATH_SIZE private (python#138350)

    29fff01
22. hugovk

    added a commit that references this issue on Sep 16, 2025

    [3.14] gh-135755: Make Py_MAX_SCRIPT_PATH_SIZE private (GH-138350) (#…

    c0d490d
23. encukou

    closed this as completedon Sep 16, 2025
24. Fidget-Spinner commented on Sep 16, 2025

    

    Fidget-Spinner

    on Sep 16, 2025

    Member

    More actions

    @vstinner or @encukou I have not made the symbol private yet. If you want someone to sprint on it this week, I'm happy to review the PR, but this isn't on top of my priority list so I'm not gonna get to it anytime soon.
25. vstinner

    added a commit that references this issue on Sep 16, 2025

    pythongh-135755: Make Py_TAIL_CALL_INTERP macro private

    7270f12
26. vstinner commented on Sep 16, 2025

    

    vstinner

    on Sep 16, 2025

    Member

    More actions

    @Fidget-Spinner: I wrote #138981 to rename Py_TAIL_CALL_INTERP to _Py_TAIL_CALL_INTERP.
27. vstinner

    added 2 commits that reference this issue on Sep 18, 2025

    gh-135755: Make Py_TAIL_CALL_INTERP macro private (#138981)

    6504f20

    pythongh-135755: Make Py_TAIL_CALL_INTERP macro private (python#138981)

    fda779d
28. encukou commented on May 11, 2026

    

    encukou

    on May 11, 2026

    MemberAuthor

    More actions

    For the record, for 3.15 the same scan only found API that shouldn't be documented: #149685
    Thanks @ZeroIntensity for adding the CI check in #142102!

    Reacted by Peter Bierma

Issue actions