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_API
PyBytesObjectNeither
PyPy
nor Py_LIMITED_API
PyCFunctionObject
Py_3_9
and non-Py_LIMITED_API
PyCodeObjectNon-
PyPy
and Py_3_8
and non-Py_3_11
Structure representing a
datetime.date
Structure representing a
datetime.datetime
.Structure representing a
datetime.timedelta
.Structure representing a
datetime.time
.PyFloatObjectNon-
Py_LIMITED_API
PyFrameObjectNeither
PyPy
nor Py_3_11
PyFunctionObjectNon-
PyPy
and Py_3_10
PyFutureFeaturesNon-
PyPy
PyGenObjectNon-
PyPy
PyHash_FuncDefNeither
Py_LIMITED_API
nor PyPy
PyImportErrorObjectNon-
PyPy
PyListObjectNon-
PyPy
PyMemAllocatorExNon-
PyPy
PyOSErrorObjectNon-
PyPy
PyObjectArenaAllocatorNeither
Py_LIMITED_API
nor PyPy
PySetObjectNeither
Py_LIMITED_API
nor PyPy
PySliceObjectNon-
Py_LIMITED_API
PySyntaxErrorObjectNon-
PyPy
PySystemExitObjectNon-
PyPy
PyTryBlockNeither
PyPy
nor Py_3_11
PyUnicodeErrorObjectNon-
PyPy
PyWeakReferenceNon-
PyPy
_PyDateTime_BaseDateTimeNon-
PyPy
Structure representing a
datetime.datetime
without a tzinfo
member._PyDateTime_BaseTimeNon-
PyPy
Structure representing a
datetime.time
without a tzinfo
member._PyErr_StackItemNon-
PyPy
_PyWeakReferenceNon-
PyPy
_frozenNon-
PyPy
_inittabNon-
PyPy
setentryNeither
Py_LIMITED_API
nor PyPy
Enums
Constants
METH_FASTCALL
Py_3_10
or non-Py_LIMITED_API
METH_METHOD
Py_3_9
and non-Py_LIMITED_API
Maximum number of dimensions
Set if the type allows subclassing
Objects support garbage collection (see objimp.h)
Py_TPFLAGS_HAVE_VECTORCALL
Py_3_8
and non-Py_LIMITED_API
Set 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
Py_TPFLAGS_IMMUTABLETYPE
Py_3_10
Py_TPFLAGS_MAPPING
Py_3_10
and non-Py_LIMITED_API
Set if the type is ‘ready’ – fully initialized
Set while the type is being ‘readied’, to prevent recursive ready calls
Py_TPFLAGS_SEQUENCE
Py_3_10
and non-Py_LIMITED_API
Py_fstring_input
Py_3_9
Py_func_type_input
Py_3_8
Statics
built-in ‘object’
PyDictRevIterItem_Type
Py_3_8
PyDictRevIterKey_Type
Py_3_8
PyDictRevIterValue_Type
Py_3_8
PyExc_EncodingWarning
Py_3_10
PyFunction_TypeNot (
PyPy
and non-Py_3_8
)PyImport_FrozenModulesNon-
PyPy
PyImport_InittabNon-
PyPy
built-in ‘super’
built-in ‘type’
_PyManagedBuffer_TypeNon-
Py_LIMITED_API
Functions
PyAnySet_CheckExact⚠Non-
PyPy
PyCFunction_Call⚠Deprecated
PyCFunction_Check⚠
Py_3_9
PyCFunction_CheckExact⚠
Py_3_9
PyCFunction_New⚠
Py_3_9
PyCFunction_NewEx⚠
Py_3_9
PyCode_Check⚠Non-
PyPy
PyCode_GetNumFree⚠Non-
PyPy
and Py_3_10
and non-Py_3_11
PyCode_NewWithPosOnlyArgs⚠
Py_3_8
PyCodec_Unregister⚠
Py_3_10
and non-PyPy
Returns 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-
PyPy
Retrieve the fold component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 1]
PyDateTime_DATE_GET_HOUR⚠Non-
PyPy
Retrieve the hour component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 23]
PyDateTime_DATE_GET_MICROSECOND⚠Non-
PyPy
Retrieve the microsecond component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 999999]
PyDateTime_DATE_GET_MINUTE⚠Non-
PyPy
Retrieve the minute component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 59]
PyDateTime_DATE_GET_SECOND⚠Non-
PyPy
Retrieve the second component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 59]
PyDateTime_DATE_GET_TZINFO⚠Non-
PyPy
Retrieve 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-
PyPy
Retrieve the days component of a
PyDateTime_Delta
.PyDateTime_DELTA_GET_MICROSECONDS⚠Non-
PyPy
Retrieve the seconds component of a
PyDateTime_Delta
.PyDateTime_DELTA_GET_SECONDS⚠Non-
PyPy
Retrieve the seconds component of a
PyDateTime_Delta
.PyDateTime_FromTimestamp⚠Non-
PyPy
PyDateTime_GET_DAY⚠Non-
PyPy
Retrieve the day component of a
PyDateTime_Date
or PyDateTime_DateTime
.
Returns a signed integer in the interval [1, 31]
.PyDateTime_GET_MONTH⚠Non-
PyPy
Retrieve the month component of a
PyDateTime_Date
or PyDateTime_DateTime
.
Returns a signed integer in the range [1, 12]
.PyDateTime_GET_YEAR⚠Non-
PyPy
Retrieve 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-
PyPy
Retrieve the fold component of a
PyDateTime_Time
.
Returns a signed integer in the interval [0, 1]
PyDateTime_TIME_GET_HOUR⚠Non-
PyPy
Retrieve the hour component of a
PyDateTime_Time
.
Returns a signed integer in the interval [0, 23]
PyDateTime_TIME_GET_MICROSECOND⚠Non-
PyPy
Retrieve the microsecond component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 999999]
PyDateTime_TIME_GET_MINUTE⚠Non-
PyPy
Retrieve the minute component of a
PyDateTime_Time
.
Returns a signed integer in the interval [0, 59]
PyDateTime_TIME_GET_SECOND⚠Non-
PyPy
Retrieve the second component of a
PyDateTime_DateTime
.
Returns a signed integer in the interval [0, 59]
PyDateTime_TIME_GET_TZINFO⚠Non-
PyPy
Retrieve 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-
PyPy
Check if
op
is a PyDateTimeAPI.DetaType
or subtype.Check if
op
’s type is exactly PyDateTimeAPI.DeltaType
.PyErr_SetInterruptEx⚠
Py_3_10
PyEval_CallFunction⚠Deprecated
PyEval_CallMethod⚠Deprecated
PyEval_CallObject⚠Deprecated
PyEval_CallObjectWithKeywords⚠Deprecated
PyExceptionInstance_Class⚠Non-
PyPy
PyFloat_AS_DOUBLE⚠Non-
Py_LIMITED_API
PyFrame_BlockPop⚠Neither
PyPy
nor Py_3_11
PyFrame_GetCode⚠
Py_3_10
, or Py_3_9
and non-Py_LIMITED_API
PyFrozenSet_Check⚠Non-
PyPy
PyFrozenSet_CheckExact⚠Non-
PyPy
PyFunction_Check⚠Not (
PyPy
and non-Py_3_8
)PyGC_Disable⚠
Py_3_10
PyGC_Enable⚠
Py_3_10
PyGC_IsEnabled⚠
Py_3_10
PyGILState_GetThisThreadState⚠Non-
PyPy
PyHash_GetFuncDef⚠Neither
Py_LIMITED_API
nor PyPy
PyImport_ExtendInittab⚠Non-
PyPy
PyIndex_Check⚠Neither
Py_LIMITED_API
nor PyPy
PyInterpreterState_Clear⚠Non-
PyPy
PyInterpreterState_Delete⚠Non-
PyPy
PyInterpreterState_Get⚠
Py_3_9
and non-PyPy
PyInterpreterState_GetDict⚠
Py_3_8
and non-PyPy
PyInterpreterState_GetID⚠Non-
PyPy
PyInterpreterState_Main⚠Non-
PyPy
PyInterpreterState_New⚠Non-
PyPy
PyInterpreterState_ThreadHead⚠Non-
PyPy
PyIter_Check⚠
Py_3_8
or PyPy
PyIter_Send⚠Non-
PyPy
and Py_3_10
PyList_GET_ITEM⚠Non-
PyPy
Macro, trading safety for speed
PyList_GET_SIZE⚠Non-
PyPy
PyList_SET_ITEM⚠Non-
PyPy
Macro, only to be used to fill in brand new lists
PyMapping_Length⚠Non-
PyPy
PyMem_GetAllocator⚠Non-
PyPy
PyMem_SetAllocator⚠Non-
PyPy
PyMem_SetupDebugHooks⚠Non-
PyPy
PyModule_AddObjectRef⚠
Py_3_10
PyModule_AddType⚠
Py_3_10
, or Py_3_9
and non-Py_LIMITED_API
PyModule_Create2⚠Non-
py_sys_config="Py_TRACE_REFS"
PyModule_FromDefAndSpec2⚠Non-
py_sys_config="Py_TRACE_REFS"
PyModule_GetFilenameObject⚠Non-
PyPy
PyModule_GetNameObject⚠Non-
PyPy
PyOS_AfterFork⚠Deprecated
PyObject_CallMethodNoArgs⚠
Py_3_9
and non-PyPy
PyObject_CallMethodOneArg⚠
Py_3_9
and non-PyPy
PyObject_CallNoArgs⚠Non-
PyPy
and (Py_3_10
, or non-Py_LIMITED_API
and Py_3_9
)PyObject_CallOneArg⚠
Py_3_8
and non-PyPy
PyObject_CheckBuffer⚠
Py_3_9
and non-PyPy
and non-Py_3_11
PyObject_DelAttrString⚠Non-
PyPy
PyObject_GET_WEAKREFS_LISTPTR⚠Non-
Py_LIMITED_API
PyObject_GenericGetDict⚠Not (
Py_LIMITED_API
and non-Py_3_10
)PyObject_GetArenaAllocator⚠Neither
Py_LIMITED_API
nor PyPy
PyObject_IS_GC⚠Non-
Py_LIMITED_API
Test if an object has a GC head
PyObject_SetArenaAllocator⚠Neither
Py_LIMITED_API
nor PyPy
PyObject_Vectorcall⚠
Py_3_8
and non-PyPy
PyObject_VectorcallDict⚠
Py_3_8
PyObject_VectorcallMethod⚠
Py_3_9
and non-PyPy
PyRun_AnyFile⚠Non-
PyPy
PyRun_AnyFileEx⚠Non-
PyPy
PyRun_AnyFileFlags⚠Non-
PyPy
PyRun_FileEx⚠Non-
PyPy
PyRun_FileExFlags⚠Non-
PyPy
PyRun_FileFlags⚠Non-
PyPy
PyRun_InteractiveLoop⚠Non-
PyPy
PyRun_InteractiveOne⚠Non-
PyPy
PyRun_SimpleFile⚠Non-
PyPy
PyRun_SimpleFileEx⚠Non-
PyPy
PySequence_Length⚠Non-
PyPy
PySet_Check⚠Non-
PyPy
PySet_CheckExact⚠
Py_3_10
PySet_GET_SIZE⚠Non-
PyPy
and non-Py_LIMITED_API
PyState_AddModule⚠Non-
PyPy
PyState_FindModule⚠Non-
PyPy
PyState_RemoveModule⚠Non-
PyPy
PyStructSequence_GET_ITEM⚠Neither
Py_LIMITED_API
nor PyPy
PyStructSequence_GetItem⚠Non-
PyPy
PyStructSequence_InitType⚠Non-
Py_LIMITED_API
PyStructSequence_InitType2⚠Non-
Py_LIMITED_API
PyStructSequence_NewType⚠Non-
PyPy
PyStructSequence_SET_ITEM⚠Neither
Py_LIMITED_API
nor PyPy
PyStructSequence_SetItem⚠Non-
PyPy
Check if
op
is a PyDateTimeAPI.TZInfoType
or subtype.Check if
op
’s type is exactly PyDateTimeAPI.TZInfoType
.PyThreadState_Next⚠Non-
PyPy
PyThreadState_SetAsyncExc⚠Non-
PyPy
Check if
op
is a PyDateTimeAPI.TimeType
or subtype.Check if
op
’s type is exactly PyDateTimeAPI.TimeType
.PyTraceBack_Check⚠Non-
PyPy
PyTuple_GET_ITEM⚠Non-
PyPy
PyTuple_GET_SIZE⚠Non-
PyPy
Macro, trading safety for speed
PyTuple_SET_ITEM⚠Non-
PyPy
Macro, only to be used to fill in brand new tuples
PyType_FromModuleAndSpec⚠
Py_3_10
, or Py_3_9
and non-Py_LIMITED_API
PyType_GetModule⚠
Py_3_10
, or Py_3_9
and non-Py_LIMITED_API
PyType_GetModuleState⚠
Py_3_10
, or Py_3_9
and non-Py_LIMITED_API
PyType_HasFeature⚠Non-
Py_LIMITED_API
Test if a type has a GC head
PyType_SUPPORTS_WEAKREFS⚠Non-
Py_LIMITED_API
Test if a type supports weak references
PyUnicodeDecodeError_Create⚠Non-
PyPy
PyUnicode_1BYTE_DATA⚠Little-endian
PyUnicode_2BYTE_DATA⚠Little-endian
PyUnicode_4BYTE_DATA⚠Little-endian
PyUnicode_AsUTF8AndSize⚠
Py_3_10
or non-Py_LIMITED_API
PyUnicode_Check⚠Non-
PyPy
PyUnicode_CheckExact⚠Non-
PyPy
PyUnicode_CopyCharacters⚠Non-
PyPy
PyUnicode_DATA⚠Little-endian
PyUnicode_Fill⚠Non-
PyPy
PyUnicode_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
PyVectorcall_Call⚠
Py_3_8
PyVectorcall_Function⚠
Py_3_8
and non-PyPy
PyVectorcall_NARGS⚠
Py_3_8
PyWeakref_CheckProxy⚠Non-
PyPy
PyWeakref_CheckRef⚠Non-
PyPy
PyWeakref_CheckRefExact⚠Non-
PyPy
Py_CompileStringExFlags⚠Non-
PyPy
Py_CompileStringFlags⚠Non-
PyPy
Py_CompileStringObject⚠Non-
Py_LIMITED_API
Py_EnterRecursiveCall⚠
Py_3_9
Py_LeaveRecursiveCall⚠
Py_3_9
Py_NewRef⚠
Py_3_10
Py_XNewRef⚠
Py_3_10
_PyErr_ChainExceptions⚠Non-
PyPy
_PyImport_FindExtensionObject⚠Non-
Py_3_11
Get the frame evaluation function.
Set the frame evaluation function.
_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 PyPy
Type Definitions
PyCMethod
Py_3_9
and non-Py_LIMITED_API
PyFrameStateNeither
PyPy
nor Py_3_11
PyStructSequenceNon-
Py_LIMITED_API
Py_UNICODENon-
Py_LIMITED_API
_PyCFunctionFast
Py_3_10
or non-Py_LIMITED_API
_PyCFunctionFastWithKeywordsNon-
Py_LIMITED_API
_PyFrameEvalFunction
Py_3_9
sendfunc
Py_3_10
vectorcallfunc
Py_3_8
Unions
Function types used to implement Python callables.