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 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 (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 (gh-141004: Document PyBUF_WRITEABLE #141255)

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 (gh-141004: Document PyErr_ProgramTextObject and PyErr_ProgramText #141250)
• PyExceptionInstance_Check
• PyExceptionInstance_Class

pyhash.h

(covered in #141205 and #141233)

• Py_HASH_ALGORITHM
• Py_HASH_CUTOFF
• Py_HASH_EXTERNAL (addressed in Deprecate Py_HASH_EXTERNAL as it cannot be used for --with-hash-algorithm #141226)
• 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 (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_Check (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_GetFlags (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_GetFunction (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_GetSelf (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_Type (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)

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

(covered by #141254)

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

pymacro.h

• PyDoc_VAR (gh-141004: Document the PyDoc_VAR macro #141263)
• Py_ARRAY_LENGTH
• Py_BUILD_ASSERT_EXPR (gh-141004: Document Py_BUILD_ASSERT* macros #141266)
• Py_BUILD_ASSERT (gh-141004: Document Py_BUILD_ASSERT* macros #141266)

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

(covered in #141259)

• 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 (gh-141004: Document pyctype.h macros #141272)
• Py_ISALPHA (gh-141004: Document pyctype.h macros #141272)
• Py_ISDIGIT (gh-141004: Document pyctype.h macros #141272)
• Py_ISLOWER (gh-141004: Document pyctype.h macros #141272)
• Py_ISSPACE (gh-141004: Document pyctype.h macros #141272)
• Py_ISUPPER (gh-141004: Document pyctype.h macros #141272)
• Py_ISXDIGIT (gh-141004: Document pyctype.h macros #141272)
• Py_TOLOWER (gh-141004: Document pyctype.h macros #141272)
• Py_TOUPPER (gh-141004: Document pyctype.h macros #141272)

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 (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_GET_FLAGS (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_GET_FUNCTION (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCFunction_GET_SELF (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCMethod_CheckExact (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCMethod_Check (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253)
• PyCMethod_Type (gh-141004: Document missing PyCFunction* and PyCMethod* APIs #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
• 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 (gh-141004: Document PyErr_ProgramTextObject and PyErr_ProgramText #141250)
• 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
• gh-141004: fix versionadded typo for Py_HASH_SIPHASH13 #141223
• [3.13] gh-141004: Document Py_HASH_* macros (GH-141205) #141224
• [3.14] gh-141004: Document Py_HASH_* macros (GH-141205) #141225
• gh-141004: correctly document Py_HASH_* and PyHASH_* as hash_info attributes #141233
• [3.14] gh-141004: correctly document Py_HASH_* and PyHASH_* as hash_info attributes (GH-141233) #141234
• [3.13] gh-141004: correctly document Py_HASH_* and PyHASH_* as hash_info attributes (GH-141233) #141235
• gh-141004: Document PyErr_ProgramTextObject and PyErr_ProgramText #141250
• gh-141004: Document missing PyCFunction* and PyCMethod* APIs #141253
• gh-141004: document curses C API #141254
• gh-141004: Document PyBUF_WRITEABLE #141255
• [3.14] gh-141004: Document PyErr_ProgramTextObject and PyErr_ProgramText (GH-141250) #141256
• [3.13] gh-141004: Document PyErr_ProgramTextObject and PyErr_ProgramText (GH-141250) #141257
• gh-141004: document pyexpat C API #141259
• [3.13] gh-141004: Document PyBUF_WRITEABLE (GH-141255) #141260
• [3.14] gh-141004: Document PyBUF_WRITEABLE (GH-141255) #141261
• gh-141004: Document the PyDoc_VAR macro #141263
• [3.14] gh-141004: Document the PyDoc_VAR macro (GH-141263) #141264
• [3.13] gh-141004: Document the PyDoc_VAR macro (GH-141263) #141265
• gh-141004: Document Py_BUILD_ASSERT* macros #141266
• [3.14] gh-141004: Document Py_BUILD_ASSERT* macros (GH-141266) #141269
• [3.13] gh-141004: Document Py_BUILD_ASSERT* macros (GH-141266) #141270
• gh-141004: Document pyctype.h macros #141272
• gh-141004: Document Py_func_type_input #141273

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