Skip to content

Document the entire C API #141004

Description

@ZeroIntensity

@encukou has done great work getting us to document newly added C API in recent versions (#135755, #118915), but unfortunately, we still have plenty of undocumented APIs. I'd like to begin working towards a future where the C API documentation is extensive, up-to-date, and most importantly, helpful to users.

Here's my plan:

  1. Document all remaining C APIs (macros, static inline functions, and exported symbols) that are prefixed with Py.
  2. Add a CI job that prevents new C APIs from being added to public headers without documentation.
  3. Improve our "Extending and Embedding" tutorial. I started on this a little while ago, but I think it would be better to get the full C API documented before we do that.

I'm going to work on this myself, but others are welcome to send PRs where necessary. I've applied the easy label to this for any newcomers who are interested in helping.

Below is a list of CPython's undocumented C API. I'm sure many of these aren't documented intentionally, so we should either deprecate them or keep a canonical list of "public but undocumented" somewhere.


bltinmodule.h

enumobject.h

bytearrayobject.h

bytesobject.h

codecs.h

compile.h

datetime.h

These are under #83785.

descrobject.h

dictobject.h

fileobject.h

listobject.h

memoryobject.h

objimpl.h

(All covered by #141146)

  • PyObject_DEL
  • PyObject_FREE
  • PyObject_INIT_VAR
  • PyObject_INIT
  • PyObject_MALLOC
  • PyObject_NEW_VAR
  • PyObject_NEW
  • PyObject_REALLOC

pybuffer.h

pycapsule.h

pydtrace.h

pyerrors.h

pyhash.h

(covered in #141205 and #141233)

pystrtod.h

rangeobject.h

setobject.h

traceback.h

tupleobject.h

exports.h

floatobject.h

longobject.h

methodobject.h

modsupport.h

moduleobject.h

py_curses.h

(covered by #141254)

  • PyCursesInitialisedColor
  • PyCursesInitialised
  • PyCursesSetupTermCalled
  • PyCursesWindow_Check
  • PyCursesWindow_Type
  • PyCurses_API_pointers
  • PyCurses_CAPSULE_NAME

pymacro.h

pymath.h

typeslots.h

(Covered in #138190)

unicodeobject.h

object.h

pyexpat.h

(covered in #141259)

  • PyExpat_CAPI_MAGIC
  • PyExpat_CAPSULE_NAME

pyport.h

weakrefobject.h

cpython/pyctype.h

cpython/compile.h

cpython/descrobject.h

cpython/fileobject.h

cpython/methodobject.h

cpython/odictobject.h

(All covered by #141136)

  • PyODictItems_Type
  • PyODictIter_Type
  • PyODictKeys_Type
  • PyODictValues_Type
  • PyODict_CheckExact
  • PyODict_Check
  • PyODict_Contains
  • PyODict_DelItem
  • PyODict_GetItemString
  • PyODict_GetItemWithError
  • PyODict_GetItem
  • PyODict_New
  • PyODict_SIZE
  • PyODict_SetItem
  • PyODict_Size
  • PyODict_Type

cpython/picklebufobject.h

cpython/setobject.h

cpython/dictobject.h

cpython/genobject.h

cpython/import.h

cpython/longintrepr.h

cpython/pyerrors.h

cpython/pyframe.h

cpython/funcobject.h

cpython/unicodeobject.h

pystrcmp.h

intrcheck.h

ceval.h

pythread.h

cpython/frameobject.h

cpython/objimpl.h

cpython/pythonrun.h

cpython/ceval.h

cpython/pylifecycle.h

  • Py_FrozenMain

cpython/warnings.h

cpython/code.h

cpython/object.h

pymem.h

pystrtod.h

(all in #143867)

  • Py_DTSF_ADD_DOT_0
  • Py_DTSF_ALT
  • Py_DTSF_NO_NEG_0
  • Py_DTSF_SIGN
  • Py_DTST_FINITE
  • Py_DTST_INFINITE
  • Py_DTST_NAN

structmember.h

  • PY_AUDIT_READ

object.h

Linked PRs

Activity

  1. self-assigned this
    on Nov 4, 2025
  2. added
    docsDocumentation in the Doc dir
    3.13only security fixes
    3.14bugs and security fixes
    3.15pre-release feature fixes, bugs and security fixes
    on Nov 4, 2025
  3. encukou commented on Nov 4, 2025

    @encukou
    Member

    Be careful here; we might want to (soft-)deprecate some of the currently undocumented API.
    Historically (before PEP 387), undocumented API was considered private.

  4. ZeroIntensity commented on Nov 4, 2025

    @ZeroIntensity
    MemberAuthor

    That's fine with me. Apart from your comment on #141006, are there any things you'd specifically like to soft-deprecate?

  5. ZeroIntensity commented on Nov 4, 2025

    @ZeroIntensity
    MemberAuthor

    See capi-workgroup/decisions#86 for the C API WG issue on soft-deprecation.

  6. StanFromIreland commented on Nov 4, 2025

    @StanFromIreland
    Member

    PyUnicode_IS_COMPACT was deprecated and scheduled for removal in 3.12, oddly PyUnicode_IS_COMPACT_ASCII was not included. I think we can exclude this from the list?

  7. ZeroIntensity commented on Nov 4, 2025

    @ZeroIntensity
    MemberAuthor

    We should actually remove it from the headers or document it as deprecated.

  8. 316 remaining items

  9. added a commit that references this issue on Nov 25, 2025
  10. added a commit that references this issue on Nov 27, 2025
  11. added 2 commits that reference this issue on Nov 27, 2025
  12. added a commit that references this issue on Dec 1, 2025
  13. Yashp002 commented on Jan 6, 2026

    @Yashp002
    Contributor

    I'd like to document the missing macros in descrobject.h (PyDescr_COMMON, PyDescr_NAME, etc.). Working on it.

  14. ZeroIntensity commented on Jan 6, 2026

    @ZeroIntensity
    MemberAuthor

    PyDescr_COMMON is flagged for deprecation. Let's wait until the WG has finished voting for that one.

  15. Yashp002 commented on Jan 6, 2026

    @Yashp002
    Contributor

    @ZeroIntensity oh right sorry, So i should stay away from everything in that list in the link uve attached and can go ahead with the others right?

  16. ZeroIntensity commented on Jan 6, 2026

    @ZeroIntensity
    MemberAuthor

    Yeah, avoid the ones I linked.

  17. Yashp002 commented on Jan 6, 2026

    @Yashp002
    Contributor

    I'll tackle Include/cpython/pyframe.h (PyUnstable_EXECUTABLE_KINDS etc.) then

  18. Yashp002 commented on Jan 6, 2026

    @Yashp002
    Contributor

    I'll take Include/cpython/ceval.h (Perf Trampoline functions) next.

  19. Yashp002 commented on Jan 6, 2026

    @Yashp002
    Contributor

    I'll handle PyUnicode_IS_COMPACT and PyUnicode_IS_COMPACT_ASCII next.

  20. Yashp002 commented on Jan 7, 2026

    @Yashp002
    Contributor

    @ZeroIntensity Since PyDescr_COMMON and PyWrapperFlagKeywords is flagged for soft deprecation, should i avoid the other two in the list with them too? or can i go ahead with documenting those, as in PyDescr_NAME and PyDescr_TYPE?

  21. Yashp002 commented on Jan 7, 2026

    @Yashp002
    Contributor

    I'll proceed with PyAPI_DATA

    Py_EXPORTED_SYMBOL

    Py_IMPORTED_SYMBOL

    Py_LOCAL_SYMBOL in the meantime.

  22. encukou commented on Feb 20, 2026

    @encukou
    Member

    I've proposed more soft-deprecations: capi-workgroup/decisions#99

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

3.13only security fixes3.14bugs and security fixes3.15pre-release feature fixes, bugs and security fixesdocsDocumentation in the Doc dirtopic-C-API

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions