Document the entire C API

[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 API (macros, static inline functions, and exported symbols) that are prefixed with Py.
2. Add a CI job that prevents new C API 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 (gh-141004: Document missing built-in iterator types in the C API #141006)
• PyMap_Type (gh-141004: Document missing built-in iterator types in the C API #141006)
• PyZip_Type (gh-141004: Document missing built-in iterator types in the C API #141006)

enumobject.h

• PyEnum_Type (gh-141004: Document missing built-in iterator types in the C API #141006)
• PyReversed_Type (gh-141004: Document missing built-in iterator types in the C API #141006)

bytearrayobject.h

• PyByteArrayIter_Type (gh-141004: Document remaining iterator types #141010)

bytesobject.h

• PyBytes_DecodeEscape
• PyBytes_Repr
• PyBytesIter_Type (gh-141004: Document remaining iterator types #141010)

codecs.h

• Py_hexdigits (gh-141004: Document Py_hexdigits #141059)

compile.h

• Py_func_type_input

datetime.h

• PyDateTime_CAPSULE_NAME

descrobject.h

• PyClassMethodDescr_Type
• PyDictProxy_Type
• PyGetSetDescr_Type
• PyMemberDescr_Type
• PyMethodDescr_Type
• PyWrapperDescr_Type

dictobject.h

• PyDictItems_Check (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictItems_Type (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictKeys_Check (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictKeys_Type (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictValues_Check (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictValues_Type (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictViewSet_Check (gh-141004: Document C APIs for dictionary keys, values, and items #141009)
• PyDictIterItem_Type (gh-141004: Document remaining iterator types #141010)
• PyDictIterKey_Type (gh-141004: Document remaining iterator types #141010)
• PyDictIterValue_Type (gh-141004: Document remaining iterator types #141010)
• PyDictRevIterItem_Type (gh-141004: Document remaining iterator types #141010)
• PyDictRevIterKey_Type (gh-141004: Document remaining iterator types #141010)
• PyDictRevIterValue_Type (gh-141004: Document remaining iterator types #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 (gh-141004: Document remaining iterator types #141010)
• PyListRevIter_Type (gh-141004: Document remaining iterator types #141010)

memoryobject.h

• PyMemoryView_Type (gh-141004: Document 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

pycapsule.h

• PyCapsule_Type (gh-141004: Document PyCapsule_Type #141079)

pydtrace.h

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

pyerrors.h

• PyErr_ProgramText
• PyExceptionInstance_Check
• PyExceptionInstance_Class

pyhash.h

(will be addressed by @picnixz in #141205)

• Py_HASH_ALGORITHM
• Py_HASH_CUTOFF
• Py_HASH_EXTERNAL (needs to be addressed separately)
• Py_HASH_FNV
• Py_HASH_SIPHASH13
• Py_HASH_SIPHASH24

pystrtod.h

• Py_DTSF_NO_NEG_0

rangeobject.h

• PyLongRangeIter_Type (gh-141004: Document remaining iterator types #141010)
• PyRangeIter_Type (gh-141004: Document remaining iterator types #141010)
• PyRange_Check (gh-141004: Document missing built-in iterator types in the C API #141006)
• PyRange_Type (gh-141004: Document missing built-in iterator types in the C API #141006)

setobject.h

• PySetIter_Type (gh-141004: Document remaining iterator types #141010)

traceback.h

• PyTraceBack_Check (gh-141004: Document PyTraceBack* APIs #141192)
• PyTraceBack_Here (gh-141004: Document PyTraceBack* APIs #141192)
• PyTraceBack_Print (gh-141004: Document PyTraceBack* APIs #141192)
• PyTraceBack_Type (gh-141004: Document PyTraceBack* APIs #141192)

tupleobject.h

• PyTupleIter_Type (gh-141004: Document remaining iterator types #141010)

exports.h

• PyAPI_DATA
• PyMODEXPORT_FUNC
• Py_EXPORTED_SYMBOL
• Py_IMPORTED_SYMBOL
• Py_LOCAL_SYMBOL

floatobject.h

• Py_RETURN_INF (gh-141004: Document Py_RETURN_NAN and Py_RETURN_INF #141029)
• Py_RETURN_NAN (gh-141004: Document Py_RETURN_NAN and Py_RETURN_INF #141029)

longobject.h

• PyLong_AsPid (gh-141004: Document PyLong_FromPid and PyLong_AsPid #141028)
• PyLong_FromPid (gh-141004: Document PyLong_FromPid and PyLong_AsPid #141028)

methodobject.h

• PyCFunction_CheckExact
• PyCFunction_Check
• PyCFunction_GetFlags
• PyCFunction_GetFunction
• PyCFunction_GetSelf
• PyCFunction_Type

modsupport.h

• PyABIInfo_FREETHREADING_AGNOSTIC

moduleobject.h

• PyModuleDef_Type
• PyModule_FromSlotsAndSpec
• PyModule_GetStateSize
• PyModule_GetToken
• Py_mod_doc
• Py_mod_methods
• Py_mod_name
• Py_mod_state_clear
• Py_mod_state_free
• Py_mod_state_size
• Py_mod_state_traverse
• Py_mod_token

py_curses.h

(will be addressed by @picnixz)

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

pymacro.h

• PyDoc_VAR
• Py_ARRAY_LENGTH
• Py_BUILD_ASSERT_EXPR
• Py_BUILD_ASSERT

pymath.h

• Py_HUGE_VAL
• Py_IS_FINITE
• Py_IS_INFINITY
• Py_IS_NAN
• Py_MATH_E
• Py_MATH_El
• Py_MATH_PI
• Py_MATH_PIl
• Py_MATH_TAU
• Py_NAN

typeslots.h

(Covered in #138190)

unicodeobject.h

• Py_UNICODE_SIZE (Pending removal in 3.15)

object.h

• PySuper_Type
• PyType_FastSubclass
• PyType_GetModuleByToken
• Py_INVALID_SIZE
• Py_TPFLAGS_HAVE_VERSION_TAG
• Py_TPFLAGS_INLINE_VALUES
• Py_TPFLAGS_IS_ABSTRACT

pyexpat.h

(will be addressed by @picnixz)

• PyExpat_CAPI_MAGIC
• PyExpat_CAPSULE_NAME

pyport.h

• Py_ALIGNED
• Py_ARITHMETIC_RIGHT_SHIFT
• Py_CAN_START_THREADS
• Py_FORCE_EXPANSION
• Py_GCC_ATTRIBUTE
• Py_LL
• Py_LOCAL_INLINE
• Py_LOCAL
• Py_MEMCPY
• Py_SAFE_DOWNCAST
• Py_ULL
• Py_VA_COPY

weakrefobject.h

• PyWeakref_CheckRefExact

cpython/pyctype.h

• Py_ISALNUM
• Py_ISALPHA
• Py_ISDIGIT
• Py_ISLOWER
• Py_ISSPACE
• Py_ISUPPER
• Py_ISXDIGIT
• Py_TOLOWER
• Py_TOUPPER

cpython/compile.h

• PyCF_ALLOW_INCOMPLETE_INPUT
• PyCF_COMPILE_MASK
• PyCF_DONT_IMPLY_DEDENT
• PyCF_IGNORE_COOKIE
• PyCF_MASK_OBSOLETE
• PyCF_MASK
• PyCF_SOURCE_IS_UTF8
• PyCompile_OpcodeStackEffectWithJump
• PyCompile_OpcodeStackEffect

cpython/descrobject.h

• PyDescr_COMMON
• PyDescr_NAME
• PyDescr_TYPE
• PyWrapperFlag_KEYWORDS

cpython/fileobject.h

• PyFile_NewStdPrinter
• PyFile_OpenCodeObject
• PyFile_OpenCode
• PyStdPrinter_Type
• Py_UniversalNewlineFgets

cpython/methodobject.h

• PyCFunction_GET_CLASS
• PyCFunction_GET_FLAGS
• PyCFunction_GET_FUNCTION
• PyCFunction_GET_SELF
• PyCMethod_CheckExact
• PyCMethod_Check
• PyCMethod_Type

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
• PyPickleBuffer_FromObject
• PyPickleBuffer_GetBuffer
• PyPickleBuffer_Release
• PyPickleBuffer_Type

cpython/setobject.h

• PySet_MINSIZE

cpython/dictobject.h

• PyDict_GET_SIZE (gh-141004: Document PyDict_GET_SIZE #141078)

cpython/genobject.h

• PyAsyncGenASend_CheckExact
• PyAsyncGen_CheckExact
• PyAsyncGen_New
• PyAsyncGen_Type
• PyGen_GetCode

cpython/import.h

• PyImport_Inittab

cpython/longintrepr.h

• PyLong_BASE
• PyLong_MASK
• PyLong_SHIFT

cpython/pyerrors.h

• PyErr_ProgramTextObject
• PyErr_RangedSyntaxLocationObject
• PyException_HEAD

cpython/pyframe.h

• PyUnstable_EXECUTABLE_KINDS
• PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
• PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR
• PyUnstable_EXECUTABLE_KIND_PY_FUNCTION
• PyUnstable_EXECUTABLE_KIND_SKIP

cpython/funcobject.h

• PyClassMethod_New
• PyClassMethod_Type
• PyFunction_SetKwDefaults
• PyStaticMethod_New
• PyStaticMethod_Type

cpython/unicodeobject.h

• PyUnicode_IS_COMPACT_ASCII
• PyUnicode_IS_COMPACT
• Py_UNICODE_HIGH_SURROGATE (gh-141004: Document Py_UNICODE_{HIGH, LOW}_SURROGATE functions #141019)
• Py_UNICODE_LOW_SURROGATE (gh-141004: Document Py_UNICODE_{HIGH, LOW}_SURROGATE functions #141019)

pystrcmp.h

• PyOS_mystricmp
• PyOS_mystrnicmp

intrcheck.h

• PyOS_InterruptOccurred

ceval.h

• Py_GetRecursionLimit (gh-141004: Document Py_GetRecursionLimit and Py_SetRecursionLimit #141151)
• Py_MakePendingCalls (gh-141004: Document Py_MakePendingCalls #141137)
• Py_SetRecursionLimit (gh-141004: Document Py_GetRecursionLimit and Py_SetRecursionLimit #141151)

pythread.h

• PyThread_GetInfo
• PyThread_acquire_lock_timed
• PyThread_acquire_lock
• PyThread_allocate_lock
• PyThread_free_lock
• PyThread_get_stacksize
• PyThread_get_thread_ident
• PyThread_get_thread_native_id
• PyThread_init_thread
• PyThread_release_lock
• PyThread_set_stacksize
• PyThread_start_new_thread

cpython/frameobject.h

• PyFrame_FastToLocalsWithError (gh-141004: Document missing frame APIs #141189)
• PyFrame_FastToLocals (gh-141004: Document missing frame APIs #141189)
• PyFrame_LocalsToFast (gh-141004: Document missing frame APIs #141189)
• PyFrame_New (gh-141004: Document missing frame APIs #141189)

cpython/objimpl.h

• PyType_SUPPORTS_WEAKREFS

cpython/pythonrun.h

• PyRun_InteractiveOneObject

cpython/ceval.h

• PyUnstable_CopyPerfMapFile
• PyUnstable_PerfTrampoline_CompileCode
• PyUnstable_PerfTrampoline_SetPersistAfterFork

cpython/pylifecycle.h

• Py_FrozenMain

cpython/warnings.h

• PyErr_WarnExplicitFormat (gh-141004: Document PyErr_WarnExplicitFormat #141187)

cpython/code.h

• PyCode_Optimize

cpython/object.h

• PyType_Unwatch

Linked PRs

• gh-141004: Document missing built-in iterator types in the C API #141006
• gh-141004: Document C APIs for dictionary keys, values, and items #141009
• gh-141004: Document remaining iterator types #141010
• gh-141004: Document Py_UNICODE_{HIGH, LOW}_SURROGATE functions #141019
• [3.13] gh-141004: Document Py_UNICODE_{HIGH, LOW}_SURROGATE functions (GH-141019) #141026
• [3.14] gh-141004: Document Py_UNICODE_{HIGH, LOW}_SURROGATE functions (GH-141019) #141027
• gh-141004: Document PyLong_FromPid and PyLong_AsPid #141028
• gh-141004: Document Py_RETURN_NAN and Py_RETURN_INF #141029
• gh-141004: soft-deprecate Py_INFINITY macro #141033
• gh-141004: Document PyMemoryView_Type #141034
• gh-141004: deprecate Py_MATH_El and Py_MATH_PIl macros #141035
• [3.14] gh-141004: Document missing iterator types in the C API (GH-141010) #141046
• [3.13] gh-141004: Document missing iterator types in the C API (GH-141010) #141047
• [3.14] gh-141004: Document PyMemoryView_Type (GH-141034) #141054
• [3.13] gh-141004: Document PyMemoryView_Type (GH-141034) #141055
• gh-141004: Document Py_hexdigits #141059
• [3.14] gh-141004: Document Py_RETURN_NAN and Py_RETURN_INF (GH-141029) #141074
• [3.13] gh-141004: Document Py_RETURN_NAN and Py_RETURN_INF (GH-141029) #141075
• gh-141004: Document PyDict_GET_SIZE #141078
• gh-141004: Document PyCapsule_Type #141079
• [3.14] gh-141004: Document PyDict_GET_SIZE (GH-141078) #141082
• [3.13] gh-141004: Document PyDict_GET_SIZE (GH-141078) #141083
• [3.14] gh-141004: Document built-in iterator types in the C API (GH-141006) #141134
• [3.13] gh-141004: Document built-in iterator types in the C API (GH-141006) #141135
• gh-141004: Document PyODict* APIs #141136
• gh-141004: Document Py_MakePendingCalls #141137
• [3.14] gh-141004: Document Py_hexdigits (GH-141059) #141138
• [3.13] gh-141004: Document Py_hexdigits (GH-141059) #141139
• [3.14] gh-141004: Document PyLong_FromPid and PyLong_AsPid (GH-141028) #141142
• [3.13] gh-141004: Document PyLong_FromPid and PyLong_AsPid (GH-141028) #141143
• gh-141004: document Py_INFINITY macro #141145
• gh-141004: Document deprecated aliases for memory allocation #141146
• gh-141004: Document Py_GetRecursionLimit and Py_SetRecursionLimit #141151
• [3.14] gh-141004: Document Py_GetRecursionLimit and Py_SetRecursionLimit (GH-141151) #141156
• [3.13] gh-141004: Document Py_GetRecursionLimit and Py_SetRecursionLimit (GH-141151) #141157
• gh-141004: Document PyErr_WarnExplicitFormat #141187
• gh-141004: Document missing frame APIs #141189
• gh-141004: Document PyTraceBack* APIs #141192
• [3.13] gh-141004: Document PyCapsule_Type (GH-141079) #141198
• [3.14] gh-141004: Document PyCapsule_Type (GH-141079) #141199
• [3.14] gh-141004: Document PyErr_WarnExplicitFormat (GH-141187) #141202
• [3.13] gh-141004: Document PyErr_WarnExplicitFormat (GH-141187) #141203
• gh-141004: Document Py_HASH_* macros #141205
• [3.14] gh-141004: Document PyTraceBack* APIs (GH-141192) #141210
• [3.13] gh-141004: Document PyTraceBack* APIs (GH-141192) #141211

[encukou]

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