Expand description
Raw FFI declarations for Python’s C API.
This module provides low level bindings to the Python interpreter. It is meant for advanced users only - regular PyO3 users shouldn’t need to interact with this module at all.
The contents of this module are not documented here, as it would entail basically copying the documentation from CPython. Consult the Python/C API Reference Manual for up-to-date documentation.
Safety
The functions in this module lack individual safety documentation, but generally the following apply:
- Pointer arguments have to point to a valid Python object of the correct type, although null pointers are sometimes valid input.
- The vast majority can only be used safely while the GIL is held.
- Some functions have additional safety requirements, consult the Python/C API Reference Manual for more information.
Modules
Structs
PyByteArrayObjectNeither
PyPy nor Py_LIMITED_APIPyBytesObjectNeither
PyPy nor Py_LIMITED_APIPyCodeObjectNon-
PyPy and Py_3_8 and non-Py_3_11Structure representing a
datetime.dateStructure representing a
datetime.datetime.Structure representing a
datetime.timedelta.Structure representing a
datetime.time.PyDictObjectNon-
PyPyPyFloatObjectNon-
Py_LIMITED_APIPyFrameObjectNeither
PyPy nor Py_3_11PyFunctionObjectNon-
PyPy and non-Py_3_10PyFutureFeaturesNon-
PyPyPyGenObjectNon-
PyPyPyHash_FuncDefNeither
Py_LIMITED_API nor PyPyPyImportErrorObjectNon-
PyPyPyListObjectNon-
PyPyPyMemAllocatorExNon-
PyPyPyOSErrorObjectNon-
PyPyPyObjectArenaAllocatorNeither
Py_LIMITED_API nor PyPyPySetObjectNeither
Py_LIMITED_API nor PyPyPySliceObjectNon-
Py_LIMITED_APIPySyntaxErrorObjectNon-
PyPyPySystemExitObjectNon-
PyPyPyTryBlockNeither
PyPy nor Py_3_11PyUnicodeErrorObjectNon-
PyPyPyWeakReferenceNon-
PyPy_PyDateTime_BaseDateTimeNon-
PyPyStructure representing a
datetime.datetime without a tzinfo member._PyDateTime_BaseTimeNon-
PyPyStructure representing a
datetime.time without a tzinfo member._PyErr_StackItemNon-
PyPy_PyWeakReferenceNon-
PyPy_frozenNon-
PyPy_inittabNon-
PyPysetentryNeither
Py_LIMITED_API nor PyPyEnums
Constants
METH_FASTCALL
Py_3_10 or non-Py_LIMITED_APIMaximum number of dimensions
PyUnicode_WCHAR_KINDNon-
Py_3_12Set if the type allows subclassing
Objects support garbage collection (see objimp.h)
Py_TPFLAGS_HAVE_VECTORCALL
Py_3_8 and non-Py_LIMITED_APISet if the type implements the vectorcall protocol (PEP 590)
This flag does nothing in Python 3.10+
Set if the type object is dynamically allocated
Set if the type is ‘ready’ – fully initialized
Set while the type is being ‘readied’, to prevent recursive ready calls
Py_func_type_input
Py_3_8Statics
built-in ‘object’
PyDictRevIterItem_Type
Py_3_8PyDictRevIterKey_Type
Py_3_8PyDictRevIterValue_Type
Py_3_8PyFunction_TypeNon-
PyPyPyImport_FrozenModulesNon-
PyPyPyImport_InittabNon-
PyPybuilt-in ‘super’
built-in ‘type’
_PyManagedBuffer_TypeNon-
Py_LIMITED_APIFunctions
PyAST_CompileEx⚠Neither
PyPy nor Py_3_10PyAST_CompileObject⚠Neither
PyPy nor Py_3_10PyAnySet_CheckExact⚠Non-
PyPyPyCFunction_Check⚠Non-
Py_3_9PyCFunction_ClearFreeList⚠Non-
Py_3_9PyCode_Check⚠Non-
PyPyPyCode_NewWithPosOnlyArgs⚠
Py_3_8Returns a pointer to a
PyDateTime_CAPI instanceCheck if
op is a PyDateTimeAPI.DateTimeType or subtype.Check if
op’s type is exactly PyDateTimeAPI.DateTimeType.PyDateTime_DATE_GET_FOLD⚠Non-
PyPyRetrieve the fold component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 1]PyDateTime_DATE_GET_HOUR⚠Non-
PyPyRetrieve the hour component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 23]PyDateTime_DATE_GET_MICROSECOND⚠Non-
PyPyRetrieve the microsecond component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 999999]PyDateTime_DATE_GET_MINUTE⚠Non-
PyPyRetrieve the minute component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 59]PyDateTime_DATE_GET_SECOND⚠Non-
PyPyRetrieve the second component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 59]PyDateTime_DATE_GET_TZINFO⚠Non-
PyPyRetrieve the tzinfo component of a
PyDateTime_DateTime.
Returns a pointer to a PyObject that should be either NULL or an instance
of a datetime.tzinfo subclass.PyDateTime_DELTA_GET_DAYS⚠Non-
PyPyRetrieve the days component of a
PyDateTime_Delta.PyDateTime_DELTA_GET_MICROSECONDS⚠Non-
PyPyRetrieve the seconds component of a
PyDateTime_Delta.PyDateTime_DELTA_GET_SECONDS⚠Non-
PyPyRetrieve the seconds component of a
PyDateTime_Delta.PyDateTime_FromTimestamp⚠Non-
PyPyPyDateTime_GET_DAY⚠Non-
PyPyRetrieve the day component of a
PyDateTime_Date or PyDateTime_DateTime.
Returns a signed integer in the interval [1, 31].PyDateTime_GET_MONTH⚠Non-
PyPyRetrieve the month component of a
PyDateTime_Date or PyDateTime_DateTime.
Returns a signed integer in the range [1, 12].PyDateTime_GET_YEAR⚠Non-
PyPyRetrieve the year component of a
PyDateTime_Date or PyDateTime_DateTime.
Returns a signed integer greater than 0.Populates the
PyDateTimeAPI objectPyDateTime_TIME_GET_FOLD⚠Non-
PyPyRetrieve the fold component of a
PyDateTime_Time.
Returns a signed integer in the interval [0, 1]PyDateTime_TIME_GET_HOUR⚠Non-
PyPyRetrieve the hour component of a
PyDateTime_Time.
Returns a signed integer in the interval [0, 23]PyDateTime_TIME_GET_MICROSECOND⚠Non-
PyPyRetrieve the microsecond component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 999999]PyDateTime_TIME_GET_MINUTE⚠Non-
PyPyRetrieve the minute component of a
PyDateTime_Time.
Returns a signed integer in the interval [0, 59]PyDateTime_TIME_GET_SECOND⚠Non-
PyPyRetrieve the second component of a
PyDateTime_DateTime.
Returns a signed integer in the interval [0, 59]PyDateTime_TIME_GET_TZINFO⚠Non-
PyPyRetrieve the tzinfo component of a
PyDateTime_Time.
Returns a pointer to a PyObject that should be either NULL or an instance
of a datetime.tzinfo subclass.Type Check macros
Check if
op’s type is exactly PyDateTimeAPI.DateType.PyDate_FromTimestamp⚠Non-
PyPyCheck if
op is a PyDateTimeAPI.DetaType or subtype.Check if
op’s type is exactly PyDateTimeAPI.DeltaType.PyExceptionInstance_Class⚠Non-
PyPyPyFloat_AS_DOUBLE⚠Non-
Py_LIMITED_APIPyFrame_BlockPop⚠Neither
PyPy nor Py_3_11PyFrame_ClearFreeList⚠Non-
Py_3_9PyFrozenSet_Check⚠Non-
PyPyPyFrozenSet_CheckExact⚠Non-
PyPyPyFunction_Check⚠Non-
PyPyPyFuture_FromAST⚠Neither
PyPy nor Py_3_10PyFuture_FromASTObject⚠Neither
PyPy nor Py_3_10PyGILState_GetThisThreadState⚠Non-
PyPyPyHash_GetFuncDef⚠Neither
Py_LIMITED_API nor PyPyPyImport_ExtendInittab⚠Non-
PyPyPyIndex_Check⚠Neither
Py_LIMITED_API nor PyPyPyInterpreterState_Clear⚠Non-
PyPyPyInterpreterState_Delete⚠Non-
PyPyPyInterpreterState_GetDict⚠
Py_3_8 and non-PyPyPyInterpreterState_GetID⚠Non-
PyPyPyInterpreterState_Main⚠Non-
PyPyPyInterpreterState_New⚠Non-
PyPyPyInterpreterState_ThreadHead⚠Non-
PyPyPyIter_Check⚠Neither
Py_LIMITED_API nor PyPyPyList_GET_ITEM⚠Non-
PyPyMacro, trading safety for speed
PyList_GET_SIZE⚠Non-
PyPyPyList_SET_ITEM⚠Non-
PyPyMacro, only to be used to fill in brand new lists
PyMapping_Length⚠Non-
PyPyPyMem_GetAllocator⚠Non-
PyPyPyMem_SetAllocator⚠Non-
PyPyPyMem_SetupDebugHooks⚠Non-
PyPyPyModule_Create2⚠Non-
py_sys_config="Py_TRACE_REFS"PyModule_FromDefAndSpec2⚠Non-
py_sys_config="Py_TRACE_REFS"PyModule_GetFilenameObject⚠Non-
PyPyPyModule_GetNameObject⚠Non-
PyPyPyNode_Compile⚠Neither
PyPy nor Py_3_10PyOS_AfterFork⚠Deprecated
PyObject_CallOneArg⚠
Py_3_8 and non-PyPyPyObject_CheckBuffer⚠Neither
Py_3_9 nor PyPyPyObject_DelAttrString⚠Non-
PyPyPyObject_GET_WEAKREFS_LISTPTR⚠Non-
Py_LIMITED_APIPyObject_GenericGetDict⚠Not (
Py_LIMITED_API and non-Py_3_10)PyObject_GetArenaAllocator⚠Neither
Py_LIMITED_API nor PyPyPyObject_IS_GC⚠Non-
Py_LIMITED_APITest if an object has a GC head
PyObject_SetArenaAllocator⚠Neither
Py_LIMITED_API nor PyPyPyObject_Vectorcall⚠
Py_3_8 and non-PyPyPyObject_VectorcallDict⚠
Py_3_8PyParser_ASTFromFile⚠Neither
PyPy nor Py_3_10PyParser_ASTFromFileObject⚠Neither
PyPy nor Py_3_10PyParser_ASTFromString⚠Neither
PyPy nor Py_3_10PyParser_ASTFromStringObject⚠Neither
PyPy nor Py_3_10PyParser_SimpleParseFile⚠Neither
PyPy nor Py_LIMITED_API nor Py_3_10PyParser_SimpleParseFileFlags⚠Neither
PyPy nor Py_3_10PyParser_SimpleParseString⚠Neither
PyPy nor Py_LIMITED_API nor Py_3_10PyParser_SimpleParseStringFlags⚠Neither
PyPy nor Py_3_10PyParser_SimpleParseStringFlagsFilename⚠Neither
PyPy nor Py_3_10PyRun_AnyFile⚠Non-
PyPyPyRun_AnyFileEx⚠Non-
PyPyPyRun_AnyFileFlags⚠Non-
PyPyPyRun_FileEx⚠Non-
PyPyPyRun_FileExFlags⚠Non-
PyPyPyRun_FileFlags⚠Non-
PyPyPyRun_InteractiveLoop⚠Non-
PyPyPyRun_InteractiveOne⚠Non-
PyPyPyRun_SimpleFile⚠Non-
PyPyPyRun_SimpleFileEx⚠Non-
PyPyPySequence_Length⚠Non-
PyPyPySet_Check⚠Non-
PyPyPySet_GET_SIZE⚠Non-
PyPy and non-Py_LIMITED_APIPyState_AddModule⚠Non-
PyPyPyState_FindModule⚠Non-
PyPyPyState_RemoveModule⚠Non-
PyPyPyStructSequence_GET_ITEM⚠Neither
Py_LIMITED_API nor PyPyPyStructSequence_GetItem⚠Non-
PyPyPyStructSequence_InitType⚠Non-
Py_LIMITED_APIPyStructSequence_InitType2⚠Non-
Py_LIMITED_APIPyStructSequence_NewType⚠Non-
PyPyPyStructSequence_SET_ITEM⚠Neither
Py_LIMITED_API nor PyPyPyStructSequence_SetItem⚠Non-
PyPyCheck if
op is a PyDateTimeAPI.TZInfoType or subtype.Check if
op’s type is exactly PyDateTimeAPI.TZInfoType.PyThreadState_Next⚠Non-
PyPyPyThreadState_SetAsyncExc⚠Non-
PyPyCheck if
op is a PyDateTimeAPI.TimeType or subtype.Check if
op’s type is exactly PyDateTimeAPI.TimeType.PyTraceBack_Check⚠Non-
PyPyPyTuple_ClearFreeList⚠Non-
Py_3_9PyTuple_GET_ITEM⚠Non-
PyPyPyTuple_GET_SIZE⚠Non-
PyPyMacro, trading safety for speed
PyTuple_SET_ITEM⚠Non-
PyPyMacro, only to be used to fill in brand new tuples
PyType_HasFeature⚠Non-
Py_LIMITED_APITest if a type has a GC head
PyType_SUPPORTS_WEAKREFS⚠Non-
Py_LIMITED_APITest if a type supports weak references
PyUnicodeDecodeError_Create⚠Non-
PyPyPyUnicode_1BYTE_DATA⚠Little-endian
PyUnicode_2BYTE_DATA⚠Little-endian
PyUnicode_4BYTE_DATA⚠Little-endian
PyUnicode_AsUTF8AndSize⚠
Py_3_10 or non-Py_LIMITED_APIPyUnicode_Check⚠Non-
PyPyPyUnicode_CheckExact⚠Non-
PyPyPyUnicode_CopyCharacters⚠Non-
PyPyPyUnicode_DATA⚠Little-endian
PyUnicode_Fill⚠Non-
PyPyPyUnicode_GET_LENGTH⚠Little-endian
PyUnicode_IS_ASCII⚠Little-endian
PyUnicode_IS_COMPACT⚠Little-endian
PyUnicode_IS_COMPACT_ASCII⚠Little-endian
PyUnicode_IS_READY⚠Little-endian
PyUnicode_KIND⚠Little-endian
PyUnicode_READY⚠Non-
Py_3_12 and little-endianPyVectorcall_Call⚠
Py_3_8PyVectorcall_Function⚠
Py_3_8 and non-PyPyPyVectorcall_NARGS⚠
Py_3_8 and non-PyPyPyWeakref_CheckProxy⚠Non-
PyPyPyWeakref_CheckRef⚠Non-
PyPyPyWeakref_CheckRefExact⚠Non-
PyPyPy_CompileStringExFlags⚠Non-
PyPyPy_CompileStringFlags⚠Non-
PyPyPy_CompileStringObject⚠Non-
Py_LIMITED_APIPy_SymtableString⚠Neither
PyPy nor Py_3_10Py_SymtableStringObject⚠Neither
PyPy nor Py_LIMITED_API nor Py_3_10_PyDict_Contains⚠Non-
Py_3_10_PyImport_FindBuiltin⚠Non-
Py_3_9_PyImport_FindExtensionObject⚠Non-
Py_3_11_PyObject_CallNoArg⚠
Py_3_8 and non-PyPy_PyObject_FastCall⚠
Py_3_8 and non-PyPy_PyObject_FastCallTstate⚠
Py_3_8 and non-PyPy_PyObject_GC_Calloc⚠Non-
Py_LIMITED_API_PyObject_GC_Malloc⚠Non-
Py_LIMITED_API_PyObject_GetDictPtr⚠Non-
PyPy_PyObject_MakeTpCall⚠
Py_3_8 and non-PyPy_PyObject_NextNotImplemented⚠Non-
PyPy_PyObject_VectorcallTstate⚠
Py_3_8 and non-PyPy_PySequence_IterSearch⚠Non-
PyPy_PySet_NextEntry⚠Non-
Py_LIMITED_API_PyStack_AsDict⚠
Py_3_8 and non-PyPy_PyUnicode_COMPACT_DATA⚠Little-endian
_PyUnicode_CheckConsistency⚠Non-
PyPy_PyUnicode_NONCOMPACT_DATA⚠Little-endian
_Py_CheckFunctionResult⚠
Py_3_8 and non-PyPy_Py_GetAllocatedBlocks⚠Non-
Py_LIMITED_API_Py_HashBytes⚠Neither
Py_LIMITED_API nor PyPyType Definitions
PyFrameStateNeither
PyPy nor Py_3_11PyStructSequenceNon-
Py_LIMITED_APIPy_UNICODENon-
Py_LIMITED_API_PyCFunctionFast
Py_3_10 or non-Py_LIMITED_API_PyCFunctionFastWithKeywordsNon-
Py_LIMITED_APIvectorcallfunc
Py_3_8Unions
Function types used to implement Python callables.