Document the entire C API

@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

• PyFilter_Type (#141006)
• PyMap_Type (#141006)
• PyZip_Type (#141006)

enumobject.h

• PyEnum_Type (#141006)
• PyReversed_Type (#141006)

bytearrayobject.h

• PyByteArrayIter_Type (#141010)

bytesobject.h

• PyBytes_DecodeEscape (#141407)
• PyBytes_Repr (#141407)
• PyBytesIter_Type (#141010)

codecs.h

• Py_hexdigits (https://github.com/python/cpython/pull/141059)

compile.h

• Py_func_type_input (#141273)

datetime.h

These are under #83785.

• PyDateTime_CAPSULE_NAME (#141543)

descrobject.h

• PyClassMethodDescr_Type (#141803)
• PyDictProxy_Type (#141803)
• PyGetSetDescr_Type (#141803)
• PyMemberDescr_Type (#141803)
• PyMethodDescr_Type (#141803)
• PyWrapperDescr_Type (#141803)

dictobject.h

• PyDictItems_Check (#141009)
• PyDictItems_Type (#141009)
• PyDictKeys_Check (#141009)
• PyDictKeys_Type (#141009)
• PyDictValues_Check (#141009)
• PyDictValues_Type (#141009)
• PyDictViewSet_Check (#141009)
• PyDictIterItem_Type (#141010)
• PyDictIterKey_Type (#141010)
• PyDictIterValue_Type (#141010)
• PyDictRevIterItem_Type (#141010)
• PyDictRevIterKey_Type (#141010)
• PyDictRevIterValue_Type (#141010)

fileobject.h

• Py_FileSystemDefaultEncodeErrors (Pending removal in 3.15)
• Py_FileSystemDefaultEncoding (Pending removal in 3.15)
• Py_HasFileSystemDefaultEncoding (Pending removal in 3.15)
• Py_UTF8Mode (Pending removal in 3.15)

listobject.h

• PyListIter_Type (#141010)
• PyListRevIter_Type (#141010)

memoryobject.h

• PyMemoryView_Type (#141034)

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

• PyBUF_WRITEABLE (#141255)

pycapsule.h

• PyCapsule_Type (#141079)

pydtrace.h

• PyDTrace_AUDIT_ENABLED (#141856)
• PyDTrace_AUDIT (#141856)
• PyDTrace_FUNCTION_ENTRY_ENABLED (#141856)
• PyDTrace_FUNCTION_ENTRY (#141856)
• PyDTrace_FUNCTION_RETURN_ENABLED (#141856)
• PyDTrace_FUNCTION_RETURN (#141856)
• PyDTrace_GC_DONE_ENABLED (#141856)
• PyDTrace_GC_DONE (#141856)
• PyDTrace_GC_START_ENABLED (#141856)
• PyDTrace_GC_START (#141856)
• PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED (#141856)
• PyDTrace_IMPORT_FIND_LOAD_DONE (#141856)
• PyDTrace_IMPORT_FIND_LOAD_START_ENABLED (#141856)
• PyDTrace_IMPORT_FIND_LOAD_START (#141856)
• PyDTrace_INSTANCE_DELETE_DONE_ENABLED (#141856)
• PyDTrace_INSTANCE_DELETE_DONE (#141856)
• PyDTrace_INSTANCE_DELETE_START_ENABLED (#141856)
• PyDTrace_INSTANCE_DELETE_START (#141856)
• PyDTrace_INSTANCE_NEW_DONE_ENABLED (#141856)
• PyDTrace_INSTANCE_NEW_DONE (#141856)
• PyDTrace_INSTANCE_NEW_START_ENABLED (#141856)
• PyDTrace_INSTANCE_NEW_START (#141856)
• PyDTrace_LINE_ENABLED (#141856)
• PyDTrace_LINE (#141856)

pyerrors.h

• PyErr_ProgramText (#141250)
• PyExceptionInstance_Check (#141301)
• PyExceptionInstance_Class (#141301)

pyhash.h

(covered in https://github.com/python/cpython/pull/141205 and https://github.com/python/cpython/pull/141233)

• Py_HASH_ALGORITHM
• Py_HASH_CUTOFF
• Py_HASH_EXTERNAL (addressed in #141226)
• Py_HASH_FNV
• Py_HASH_SIPHASH13
• Py_HASH_SIPHASH24

pystrtod.h

• Py_DTSF_NO_NEG_0 (#141310)

rangeobject.h

• PyLongRangeIter_Type (#141010)
• PyRangeIter_Type (#141010)
• PyRange_Check (#141006)
• PyRange_Type (#141006)

setobject.h

• PySetIter_Type (#141010)

traceback.h

• PyTraceBack_Check (#141192)
• PyTraceBack_Here (#141192)
• PyTraceBack_Print (#141192)
• PyTraceBack_Type (#141192)

tupleobject.h

• PyTupleIter_Type (#141010)

exports.h

• PyAPI_DATA (#143508)
• PyMODEXPORT_FUNC (PEP-793: #141197)
• Py_EXPORTED_SYMBOL (#143508)
• Py_IMPORTED_SYMBOL (#143508)
• Py_LOCAL_SYMBOL (#143508)
• PyAPI_FUNC (#143508)

floatobject.h

• Py_RETURN_INF (#141029)
• Py_RETURN_NAN (#141029)

longobject.h

• PyLong_AsPid (#141028)
• PyLong_FromPid (#141028)

methodobject.h

• PyCFunction_CheckExact (#141253)
• PyCFunction_Check (#141253)
• PyCFunction_GetFlags (#141253)
• PyCFunction_GetFunction (#141253)
• PyCFunction_GetSelf (#141253)
• PyCFunction_Type (#141253)

modsupport.h

• PyABIInfo_FREETHREADING_AGNOSTIC (to be done by PEP-803: #148013)

moduleobject.h

• PyModuleDef_Type (#145043)
• PyModule_FromSlotsAndSpec (PEP-793: #141197)
• PyModule_GetStateSize (PEP-793: #141197)
• PyModule_GetToken (PEP-793: #141197)
• Py_mod_doc (PEP-793: #141197)
• Py_mod_methods (PEP-793: #141197)
• Py_mod_name (PEP-793: #141197)
• Py_mod_state_clear (PEP-793: #141197)
• Py_mod_state_free (PEP-793: #141197)
• Py_mod_state_size (PEP-793: #141197)
• Py_mod_state_traverse (PEP-793: #141197)
• Py_mod_token (PEP-793: #141197)

py_curses.h

(covered by #141254)

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

pymacro.h

• PyDoc_VAR (#141263)
• Py_ARRAY_LENGTH (#141601)
• Py_BUILD_ASSERT_EXPR (https://github.com/python/cpython/pull/141266)
• Py_BUILD_ASSERT (https://github.com/python/cpython/pull/141266)

pymath.h

• Py_HUGE_VAL (#141544)
• Py_IS_FINITE (#141544)
• Py_IS_INFINITY (#141544)
• Py_IS_NAN (#141544)
• Py_MATH_E (#141373)
• Py_MATH_El (deprecated in https://github.com/python/cpython/pull/141035)
• Py_MATH_PI (#141373)
• Py_MATH_PIl (deprecated in https://github.com/python/cpython/pull/141035)
• Py_MATH_TAU (#141373)
• Py_NAN (https://github.com/python/cpython/commit/d69447445cbacf7537bf59c5c683a3b17060312d)

typeslots.h

(Covered in #138190)

unicodeobject.h

• Py_UNICODE_SIZE (Pending removal in 3.15)

object.h

• PySuper_Type (#141315)
• PyType_FastSubclass (#141313)
• PyType_GetModuleByToken (PEP-793: #141197)
• Py_INVALID_SIZE (#146178)
• Py_TPFLAGS_HAVE_VERSION_TAG (#145127)
• Py_TPFLAGS_INLINE_VALUES (#145127)
• Py_TPFLAGS_IS_ABSTRACT (#145127)

pyexpat.h

(covered in #141259)

• PyExpat_CAPI_MAGIC
• PyExpat_CAPSULE_NAME

pyport.h

• Py_ALIGNED (#144279)
• Py_ARITHMETIC_RIGHT_SHIFT (#144279)
• Py_CAN_START_THREADS (#144279)
• Py_FORCE_EXPANSION (#144279)
• Py_GCC_ATTRIBUTE (#144279)
• Py_LL (#144279)
• Py_LOCAL_INLINE (#141725)
• Py_LOCAL (#141725)
• Py_MEMCPY (Soft deprecated in 3.14: https://github.com/python/cpython/commit/26e5c6e8351adb1a77a88920ff33fc8ebee9a99e; documented in #141676)
• Py_SAFE_DOWNCAST (#144279)
• Py_ULL (#144279)
• Py_VA_COPY (#144279)
• PY_BIG_ENDIAN
• PY_SSIZE_T_MAX
• PY_SSIZE_T_MIN

weakrefobject.h

• PyWeakref_CheckRefExact (#141279)

cpython/pyctype.h

• Py_ISALNUM (#141272)
• Py_ISALPHA (#141272)
• Py_ISDIGIT (#141272)
• Py_ISLOWER (#141272)
• Py_ISSPACE (#141272)
• Py_ISUPPER (#141272)
• Py_ISXDIGIT (#141272)
• Py_TOLOWER (#141272)
• Py_TOUPPER (#141272)

cpython/compile.h

• PyCF_ALLOW_INCOMPLETE_INPUT (Discussion in #142372) (#153958)
• PyCF_COMPILE_MASK (#153958)
• PyCF_DONT_IMPLY_DEDENT (#153958)
• PyCF_IGNORE_COOKIE (#153958)
• PyCF_MASK_OBSOLETE (#153958)
• PyCF_MASK (#153958)
• PyCF_SOURCE_IS_UTF8 (#153958)
• PyCompile_OpcodeStackEffectWithJump (#141843)
• PyCompile_OpcodeStackEffect (#141843)

cpython/descrobject.h

• PyDescr_COMMON (#143896)
• PyDescr_NAME
• PyDescr_TYPE
• PyWrapperFlag_KEYWORDS (marked for deprecation)

cpython/fileobject.h

• PyFile_NewStdPrinter (#141634)
• PyFile_OpenCodeObject (#141413)
• PyFile_OpenCode (#141413)
• PyStdPrinter_Type (#141634)
• Py_UniversalNewlineFgets

cpython/methodobject.h

• PyCFunction_GET_CLASS (#141253)
• PyCFunction_GET_FLAGS (#141253)
• PyCFunction_GET_FUNCTION (#141253)
• PyCFunction_GET_SELF (#141253)
• PyCMethod_CheckExact (#141253)
• PyCMethod_Check (#141253)
• PyCMethod_Type (#141253)

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

• PyPickleBuffer_Check (#141630)
• PyPickleBuffer_FromObject (#141630)
• PyPickleBuffer_GetBuffer (#141630)
• PyPickleBuffer_Release (#141630)
• PyPickleBuffer_Type (#141630)

cpython/setobject.h

• PySet_MINSIZE (#141634)

cpython/dictobject.h

• PyDict_GET_SIZE (#141078)

cpython/genobject.h

• PyAsyncGenASend_CheckExact (#141634)
• PyAsyncGen_CheckExact (#141409)
• PyAsyncGen_New (#141409)
• PyAsyncGen_Type (#141409)
• PyGen_GetCode (#141409)

cpython/import.h

• PyImport_Inittab (#141844)

cpython/longintrepr.h

• PyLong_BASE (#141634)
• PyLong_MASK (#141634)
• PyLong_SHIFT (#141634)

cpython/pyerrors.h

• PyErr_ProgramTextObject (#141250)
• PyErr_RangedSyntaxLocationObject (#141521)
• PyException_HEAD (#143896)

cpython/pyframe.h

• PyUnstable_EXECUTABLE_KINDS (#143490)
• PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION (#143490)
• PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR (#143490)
• PyUnstable_EXECUTABLE_KIND_PY_FUNCTION (#143490)
• PyUnstable_EXECUTABLE_KIND_SKIP (#143490)

cpython/funcobject.h

• PyClassMethod_New (#141296)
• PyClassMethod_Type (#141296)
• PyFunction_SetKwDefaults (#141294)
• PyStaticMethod_New (#141296)
• PyStaticMethod_Type (#141296)

cpython/unicodeobject.h

• PyUnicode_IS_COMPACT_ASCII (#143494)
• PyUnicode_IS_COMPACT (#143494)
• Py_UNICODE_HIGH_SURROGATE (https://github.com/python/cpython/pull/141019)
• Py_UNICODE_LOW_SURROGATE (https://github.com/python/cpython/pull/141019)

pystrcmp.h

• PyOS_mystricmp (#141760)
• PyOS_mystrnicmp (#141760)

intrcheck.h

• PyOS_InterruptOccurred (#141526)

ceval.h

• Py_GetRecursionLimit (#141151)
• Py_MakePendingCalls (#141137)
• Py_SetRecursionLimit (#141151)

pythread.h

• PyThread_GetInfo (#141810)
• PyThread_acquire_lock_timed(#141810)
• PyThread_acquire_lock(#141810)
• PyThread_allocate_lock(#141810)
• PyThread_free_lock(#141810)
• PyThread_get_stacksize(#141810)
• PyThread_get_thread_ident(#141810)
• PyThread_get_thread_native_id(#141810)
• PyThread_init_thread(#141810)
• PyThread_release_lock(#141810)
• PyThread_set_stacksize(#141810)
• PyThread_start_new_thread(#141810)

cpython/frameobject.h

• PyFrame_FastToLocalsWithError (#141189)
• PyFrame_FastToLocals (#141189)
• PyFrame_LocalsToFast (#141189)
• PyFrame_New (#141189)

cpython/objimpl.h

• PyType_SUPPORTS_WEAKREFS (#141408)

cpython/pythonrun.h

• PyRun_InteractiveOneObject (#141405)

cpython/ceval.h

• PyUnstable_CopyPerfMapFile (#143492)
• PyUnstable_PerfTrampoline_CompileCode (#143492)
• PyUnstable_PerfTrampoline_SetPersistAfterFork (#143492)

cpython/pylifecycle.h

• Py_FrozenMain

cpython/warnings.h

• PyErr_WarnExplicitFormat (#141187)

cpython/code.h

• PyCode_Optimize (#141378)
• PyCode_GetFirstFree
• PyCode_New
• PyCode_NewWithPosOnlyArgs

cpython/object.h

• PyType_Unwatch (#141414)

pymem.h

• PyMem_DEL (#143783)
• PyMem_FREE (#143783)
• PyMem_MALLOC (#143783)
• PyMem_NEW (#143783)
• PyMem_REALLOC (#143783)
• PyMem_RESIZE (#143783)

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

• Py_TPFLAGS_HAVE_STACKLESS_EXTENSION (#145127)

Linked PRs

• gh-141006
• gh-141009
• gh-141010
• gh-141019
• gh-141026
• gh-141027
• gh-141028
• gh-141029
• gh-141033
• gh-141034
• gh-141035
• gh-141046
• gh-141047
• gh-141054
• gh-141055
• gh-141059
• gh-141074
• gh-141075
• gh-141078
• gh-141079
• gh-141082
• gh-141083
• gh-141134
• gh-141135
• gh-141136
• gh-141137
• gh-141138
• gh-141139
• gh-141142
• gh-141143
• gh-141145
• gh-141146
• gh-141151
• gh-141156
• gh-141157
• gh-141187
• gh-141189
• gh-141192
• gh-141198
• gh-141199
• gh-141202
• gh-141203
• gh-141205
• gh-141210
• gh-141211
• gh-141223
• gh-141224
• gh-141225
• gh-141233
• gh-141234
• gh-141235
• gh-141250
• gh-141253
• gh-141254
• gh-141255
• gh-141256
• gh-141257
• gh-141259
• gh-141260
• gh-141261
• gh-141263
• gh-141264
• gh-141265
• gh-141266
• gh-141269
• gh-141270
• gh-141272
• gh-141273
• gh-141279
• gh-141288
• gh-141289
• gh-141290
• gh-141292
• gh-141293
• gh-141294
• gh-141296
• gh-141298
• gh-141299
• gh-141301
• gh-141302
• gh-141303
• gh-141304
• gh-141305
• gh-141308
• gh-141309
• gh-141310
• gh-141313
• gh-141315
• gh-141318
• gh-141319
• gh-141329
• gh-141330
• gh-141339
• gh-141340
• gh-141368
• gh-141369
• gh-141378
• gh-141379
• gh-141380
• gh-141399
• gh-141400
• gh-141405
• gh-141407
• gh-141408
• gh-141409
• gh-141413
• gh-141414
• gh-141418
• gh-141419
• gh-141373
• gh-141425
• gh-141426
• gh-141440
• gh-141441
• gh-141470
• gh-141471
• gh-141472
• gh-141485
• gh-141486
• gh-141487
• gh-141512
• gh-141513
• gh-141514
• gh-141515
• gh-141522
• gh-141524
• gh-141525
• gh-141526
• gh-141543
• gh-141544
• gh-141549
• gh-141550
• gh-141598
• gh-141601
• gh-141630
• gh-141632
• gh-141633
• gh-141634
• gh-141637
• gh-141638
• gh-141677
• gh-141678
• gh-141685
• gh-141698
• gh-141700
• gh-141725
• gh-141760
• gh-141761
• gh-141762
• gh-141787
• gh-141788
• gh-141789
• gh-141790
• gh-141791
• gh-141792
• gh-141803
• gh-141810
• gh-141843
• gh-141844
• gh-141856
• gh-141895
• gh-141896
• gh-141915
• gh-141916
• gh-141917
• gh-141947
• gh-141948
• gh-141954
• gh-141955
• gh-142016
• gh-142102
• gh-142147
• gh-142148
• gh-142247
• gh-142248
• gh-143490
• gh-143492
• gh-143494
• gh-143508
• gh-143564
• gh-143568
• gh-143573
• gh-143583
• gh-143593
• gh-143594
• gh-143598
• gh-143783
• gh-143785
• gh-143786
• gh-143787
• gh-143793
• gh-143794
• gh-143828
• gh-143829
• gh-143837
• gh-143864
• gh-143865
• gh-143867
• gh-143896
• gh-144146
• gh-144147
• gh-144279
• gh-144471
• gh-144477
• gh-144478
• gh-144541
• gh-145043
• gh-145127
• gh-145146
• gh-145147
• gh-145316
• gh-145317
• gh-145958
• gh-145959
• gh-150849
• gh-153958
• gh-153984
• gh-153985
• gh-153986
• gh-153988
• gh-153991
• gh-153993
• gh-153994
• gh-153996
• gh-154464
• gh-154640