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§
- marshalNon-
Py_LIMITED_API
- structmemberDeprecated
Structs§
- PyByteArrayObjectNeither
PyPy
norGraalPy
norPy_LIMITED_API
- PyBytesObjectNeither
PyPy
norGraalPy
norPy_LIMITED_API
- PyCFunctionObject
Py_3_9
and non-Py_LIMITED_API
and non-GraalPy
- PyCMethodObjectNon-
GraalPy
- PyCodeObjectNeither
PyPy
norGraalPy
andPy_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
. - PyDictObjectNon-
GraalPy
- PyFrameObjectNeither
PyPy
norGraalPy
norPy_3_11
- PyFunctionObjectNeither
PyPy
norGraalPy
andPy_3_10
- PyFutureFeaturesNeither
PyPy
norGraalPy
- PyGenObjectNeither
PyPy
norGraalPy
- Represents the PyGetSetDef structure.
- PyHash_FuncDefNeither
Py_LIMITED_API
norPyPy
norGraalPy
- PyImportErrorObjectNeither
PyPy
norGraalPy
- PyListObjectNeither
PyPy
norGraalPy
- PyMemAllocatorExNeither
PyPy
norGraalPy
- Represents the PyMemberDef structure.
- Represents the PyMethodDef structure.
- PyOSErrorObjectNeither
PyPy
norGraalPy
- PyObjectArenaAllocatorNeither
PyPy
norGraalPy
- PySetObjectNeither
Py_LIMITED_API
norPyPy
norGraalPy
- PySliceObjectNon-
Py_LIMITED_API
- PySyntaxErrorObjectNeither
PyPy
norGraalPy
- PySystemExitObjectNeither
PyPy
norGraalPy
- PyTryBlockNeither
PyPy
norGraalPy
norPy_3_11
- PyUnicodeErrorObjectNeither
PyPy
norGraalPy
- PyWeakReferenceNeither
PyPy
norGraalPy
- _PyDateTime_BaseDateTimeNeither
PyPy
norGraalPy
Structure representing adatetime.datetime
without atzinfo
member. - _PyDateTime_BaseTimeNeither
PyPy
norGraalPy
Structure representing adatetime.time
without atzinfo
member. - _PyErr_StackItemNon-
PyPy
- _PyWeakReferenceNeither
PyPy
norGraalPy
- _frozenNon-
PyPy
- _inittabNon-
PyPy
- setentryNeither
Py_LIMITED_API
norPyPy
norGraalPy
Enums§
- PySendResult
Py_3_10
Constants§
- METH_FASTCALL
Py_3_10
or non-Py_LIMITED_API
- METH_METHOD
Py_3_9
and non-Py_LIMITED_API
- PY_BIG_ENDIANLittle-endian
- PY_LITTLE_ENDIANLittle-endian
- Maximum number of dimensions
- Py_AUDIT_READ
Py_3_10
- Set if the type allows subclassing
- Objects support garbage collection (see objimp.h)
- Py_TPFLAGS_HAVE_VECTORCALL
Py_3_12
, orPy_3_8
and non-Py_LIMITED_API
Set if the type implements the vectorcall protocol (PEP 590) - 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
- _Py_T_NONEDeprecated
- _Py_T_OBJECTDeprecated
- _Py_WRITE_RESTRICTEDDeprecated
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’
- Py_BytesWarningFlagDeprecated
- Py_DebugFlagDeprecated
- Py_DontWriteBytecodeFlagDeprecated
- Py_FileSystemDefaultEncodeErrorsDeprecated
- Py_FileSystemDefaultEncodingDeprecated
- Py_FrozenFlagDeprecated
- Py_HasFileSystemDefaultEncodingDeprecated
- Py_IgnoreEnvironmentFlagDeprecated
- Py_InspectFlagDeprecated
- Py_InteractiveFlagDeprecated
- Py_IsolatedFlagDeprecated
- Py_NoSiteFlagDeprecated
- Py_NoUserSiteDirectoryDeprecated
- Py_OptimizeFlagDeprecated
- Py_QuietFlagDeprecated
- Py_UnbufferedStdioFlagDeprecated
- Py_UseClassExceptionsFlagDeprecated
- Py_VerboseFlagDeprecated
- _PyManagedBuffer_TypeNon-
Py_LIMITED_API
Functions§
- PyAnySet_CheckExact⚠Non-
PyPy
- PyCFunction_Call⚠Deprecated
- PyCFunction_Check⚠
Py_3_9
- PyCFunction_CheckExact⚠
Py_3_9
- PyCFunction_GET_CLASS⚠Non-
GraalPy
- PyCFunction_GET_FLAGS⚠Non-
GraalPy
- PyCFunction_GET_FUNCTION⚠Non-
GraalPy
- PyCFunction_GET_SELF⚠Non-
GraalPy
- PyCFunction_New⚠
Py_3_9
- PyCFunction_NewEx⚠
Py_3_9
- PyCode_Addr2Line⚠Non-
GraalPy
- PyCode_Check⚠Neither
PyPy
norGraalPy
- PyCode_GetNumFree⚠Neither
PyPy
norGraalPy
andPy_3_10
and non-Py_3_11
- PyCode_New⚠Non-
GraalPy
- PyCode_NewEmpty⚠Non-
GraalPy
- PyCode_NewWithPosOnlyArgs⚠Non-
GraalPy
andPy_3_8
- PyCodec_Unregister⚠
Py_3_10
and non-PyPy
- Returns a pointer to a
PyDateTime_CAPI
instance - Check if
op
is aPyDateTimeAPI.DateTimeType
or subtype. - Check if
op
’s type is exactlyPyDateTimeAPI.DateTimeType
. - PyDateTime_DATE_GET_FOLD⚠Neither
PyPy
norGraalPy
Retrieve the fold component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 1]
- PyDateTime_DATE_GET_HOUR⚠Neither
PyPy
norGraalPy
Retrieve the hour component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 23]
- PyDateTime_DATE_GET_MICROSECOND⚠Neither
PyPy
norGraalPy
Retrieve the microsecond component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 999999]
- PyDateTime_DATE_GET_MINUTE⚠Neither
PyPy
norGraalPy
Retrieve the minute component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 59]
- PyDateTime_DATE_GET_SECOND⚠Neither
PyPy
norGraalPy
Retrieve the second component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 59]
- PyDateTime_DATE_GET_TZINFO⚠Neither
PyPy
norGraalPy
Retrieve the tzinfo component of aPyDateTime_DateTime
. Returns a pointer to aPyObject
that should be either NULL or an instance of adatetime.tzinfo
subclass. - PyDateTime_DELTA_GET_DAYS⚠Neither
PyPy
norGraalPy
Retrieve the days component of aPyDateTime_Delta
. - PyDateTime_DELTA_GET_MICROSECONDS⚠Neither
PyPy
norGraalPy
Retrieve the seconds component of aPyDateTime_Delta
. - PyDateTime_DELTA_GET_SECONDS⚠Neither
PyPy
norGraalPy
Retrieve the seconds component of aPyDateTime_Delta
. - PyDateTime_FromTimestamp⚠Non-
PyPy
- PyDateTime_GET_DAY⚠Neither
PyPy
norGraalPy
Retrieve the day component of aPyDateTime_Date
orPyDateTime_DateTime
. Returns a signed integer in the interval[1, 31]
. - PyDateTime_GET_MONTH⚠Neither
PyPy
norGraalPy
Retrieve the month component of aPyDateTime_Date
orPyDateTime_DateTime
. Returns a signed integer in the range[1, 12]
. - PyDateTime_GET_YEAR⚠Neither
PyPy
norGraalPy
Retrieve the year component of aPyDateTime_Date
orPyDateTime_DateTime
. Returns a signed integer greater than 0. - Populates the
PyDateTimeAPI
object - PyDateTime_TIME_GET_FOLD⚠Neither
PyPy
norGraalPy
Retrieve the fold component of aPyDateTime_Time
. Returns a signed integer in the interval[0, 1]
- PyDateTime_TIME_GET_HOUR⚠Neither
PyPy
norGraalPy
Retrieve the hour component of aPyDateTime_Time
. Returns a signed integer in the interval[0, 23]
- PyDateTime_TIME_GET_MICROSECOND⚠Neither
PyPy
norGraalPy
Retrieve the microsecond component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 999999]
- PyDateTime_TIME_GET_MINUTE⚠Neither
PyPy
norGraalPy
Retrieve the minute component of aPyDateTime_Time
. Returns a signed integer in the interval[0, 59]
- PyDateTime_TIME_GET_SECOND⚠Neither
PyPy
norGraalPy
Retrieve the second component of aPyDateTime_DateTime
. Returns a signed integer in the interval[0, 59]
- PyDateTime_TIME_GET_TZINFO⚠Neither
PyPy
norGraalPy
Retrieve the tzinfo component of aPyDateTime_Time
. Returns a pointer to aPyObject
that should be either NULL or an instance of adatetime.tzinfo
subclass. - Type Check macros
- Check if
op
’s type is exactlyPyDateTimeAPI.DateType
. - PyDate_FromTimestamp⚠Non-
PyPy
- Check if
op
is aPyDateTimeAPI.DetaType
or subtype. - Check if
op
’s type is exactlyPyDateTimeAPI.DeltaType
. - PyErr_SetInterruptEx⚠
Py_3_10
- PyEval_CallFunction⚠Deprecated
- PyEval_CallMethod⚠Deprecated
- PyEval_CallObject⚠Deprecated
- PyEval_CallObjectWithKeywords⚠Deprecated
- PyExceptionInstance_Class⚠Non-
PyPy
- PyFrame_BlockPop⚠Neither
PyPy
norGraalPy
norPy_3_11
- PyFrame_GetCode⚠Non-
GraalPy
and (Py_3_10
, orPy_3_9
and non-Py_LIMITED_API
) - PyFrame_New⚠Non-
GraalPy
- PyFrozenSet_Check⚠Non-
PyPy
- PyFrozenSet_CheckExact⚠Neither
PyPy
norGraalPy
- 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
norPyPy
norGraalPy
- PyImport_ExtendInittab⚠Non-
PyPy
- PyIndex_Check⚠Neither
Py_LIMITED_API
norPyPy
- 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
orPyPy
- PyIter_Send⚠Non-
PyPy
andPy_3_10
- PyList_GET_ITEM⚠Neither
PyPy
norGraalPy
Macro, trading safety for speed - PyList_GET_SIZE⚠Non-
PyPy
- PyList_SET_ITEM⚠Neither
PyPy
norGraalPy
Macro, only to be used to fill in brand new lists - PyMapping_Length⚠Non-
PyPy
- PyMem_GetAllocator⚠Neither
PyPy
norGraalPy
- PyMem_SetAllocator⚠Neither
PyPy
norGraalPy
- PyMem_SetupDebugHooks⚠Neither
PyPy
norGraalPy
- PyMemoryView_FromBuffer⚠
Py_3_11
or non-Py_LIMITED_API
- PyModule_AddObjectRef⚠
Py_3_10
- PyModule_AddType⚠
Py_3_10
, orPy_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 neitherPyPy
norGraalPy
- PyObject_CallMethodOneArg⚠
Py_3_9
and neitherPyPy
norGraalPy
- PyObject_CallNoArgs⚠Non-
PyPy
and non-GraalPy
and (Py_3_10
, or non-Py_LIMITED_API
andPy_3_9
) - PyObject_CallOneArg⚠
Py_3_8
and neitherPyPy
norGraalPy
- PyObject_CheckBuffer⚠
Py_3_9
and neitherPyPy
norGraalPy
and non-Py_3_11
- PyObject_DelAttrString⚠Non-
PyPy
- PyObject_GC_IsFinalized⚠
Py_3_9
and non-PyPy
, orPy_3_10
- PyObject_GC_IsTracked⚠
Py_3_9
and non-PyPy
, orPy_3_10
- PyObject_GC_Track⚠Non-
PyPy
- PyObject_GC_UnTrack⚠Non-
PyPy
- PyObject_GenericGetDict⚠Not (
Py_LIMITED_API
and non-Py_3_10
) - PyObject_GetArenaAllocator⚠Neither
PyPy
norGraalPy
- PyObject_IS_GC⚠
Py_3_9
- PyObject_SetArenaAllocator⚠Neither
PyPy
norGraalPy
- PyObject_Vectorcall⚠
Py_3_8
and neitherPyPy
norGraalPy
- PyObject_VectorcallDict⚠
Py_3_8
- PyObject_VectorcallMethod⚠
Py_3_9
and neitherPyPy
norGraalPy
- PyRun_AnyFile⚠Neither
PyPy
norGraalPy
- PyRun_AnyFileEx⚠Neither
PyPy
norGraalPy
- PyRun_AnyFileFlags⚠Neither
PyPy
norGraalPy
- PyRun_FileEx⚠Neither
PyPy
norGraalPy
- PyRun_FileExFlags⚠Neither
PyPy
norGraalPy
- PyRun_FileFlags⚠Neither
PyPy
norGraalPy
- PyRun_InteractiveLoop⚠Neither
PyPy
norGraalPy
- PyRun_InteractiveOne⚠Neither
PyPy
norGraalPy
- PyRun_SimpleFile⚠Neither
PyPy
norGraalPy
- PyRun_SimpleFileEx⚠Neither
PyPy
norGraalPy
- PySequence_Length⚠Non-
PyPy
- PySet_Check⚠Non-
PyPy
- PySet_CheckExact⚠
Py_3_10
- PySet_GET_SIZE⚠Neither
PyPy
norGraalPy
and non-Py_LIMITED_API
- PyState_AddModule⚠Non-
PyPy
orPy_3_9
- PyState_FindModule⚠Non-
PyPy
orPy_3_9
- PyState_RemoveModule⚠Non-
PyPy
orPy_3_9
- PyStructSequence_GET_ITEM⚠Neither
Py_LIMITED_API
norPyPy
norGraalPy
- 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
norPyPy
norGraalPy
- PyStructSequence_SetItem⚠Non-
PyPy
- Check if
op
is aPyDateTimeAPI.TZInfoType
or subtype. - Check if
op
’s type is exactlyPyDateTimeAPI.TZInfoType
. - PyThreadState_Next⚠Non-
PyPy
- PyThreadState_SetAsyncExc⚠Non-
PyPy
- Check if
op
is aPyDateTimeAPI.TimeType
or subtype. - Check if
op
’s type is exactlyPyDateTimeAPI.TimeType
. - PyTraceBack_Check⚠Non-
PyPy
- PyTuple_GET_ITEM⚠Neither
PyPy
norGraalPy
- PyTuple_GET_SIZE⚠Non-
PyPy
Macro, trading safety for speed - PyTuple_SET_ITEM⚠Neither
PyPy
norGraalPy
Macro, only to be used to fill in brand new tuples - PyType_FromModuleAndSpec⚠
Py_3_10
, orPy_3_9
and non-Py_LIMITED_API
- PyType_GetModule⚠
Py_3_10
, orPy_3_9
and non-Py_LIMITED_API
- PyType_GetModuleState⚠
Py_3_10
, orPy_3_9
and non-Py_LIMITED_API
- PyType_HasFeature⚠Non-
Py_LIMITED_API
- PyUnicodeDecodeError_Create⚠Non-
PyPy
- PyUnicode_1BYTE_DATA⚠Non-
GraalPy
- PyUnicode_2BYTE_DATA⚠Non-
GraalPy
- PyUnicode_4BYTE_DATA⚠Non-
GraalPy
- PyUnicode_AsUTF8AndSize⚠
Py_3_10
or non-Py_LIMITED_API
- PyUnicode_Check⚠Non-
PyPy
- PyUnicode_CheckExact⚠Non-
PyPy
- PyUnicode_CopyCharacters⚠Non-
PyPy
- PyUnicode_DATA⚠Non-
GraalPy
- PyUnicode_Fill⚠Non-
PyPy
- PyUnicode_GET_LENGTH⚠Non-
GraalPy
- PyUnicode_IS_ASCII⚠Non-
GraalPy
- PyUnicode_IS_COMPACT⚠Non-
GraalPy
- PyUnicode_IS_COMPACT_ASCII⚠Non-
GraalPy
- PyUnicode_IS_READY⚠Neither
GraalPy
norPy_3_12
- PyUnicode_KIND⚠Non-
GraalPy
- PyUnicode_READY⚠Neither
Py_3_12
norGraalPy
- PyVectorcall_Call⚠
Py_3_8
- PyVectorcall_Function⚠
Py_3_8
and neitherPyPy
norGraalPy
- PyVectorcall_NARGS⚠
Py_3_8
- PyWeakref_CheckProxy⚠Non-
PyPy
- PyWeakref_CheckRef⚠Non-
PyPy
- PyWeakref_CheckRefExact⚠Non-
PyPy
- Py_CompileString⚠Non-
GraalPy
- Py_CompileStringExFlags⚠Neither
PyPy
norGraalPy
- Py_CompileStringFlags⚠Neither
PyPy
norGraalPy
- Py_CompileStringObject⚠Non-
Py_LIMITED_API
- Py_EnterRecursiveCall⚠
Py_3_9
- Py_GETENV⚠Non-
Py_3_11
- Py_LeaveRecursiveCall⚠
Py_3_9
- Py_NewRef⚠
Py_3_10
and non-Py_LIMITED_API
- Py_REFCNT⚠Non-
Py_3_12
- Py_XNewRef⚠
Py_3_10
and non-Py_LIMITED_API
- _PyDict_Contains_KnownHash⚠
Py_3_10
- _PyErr_ChainExceptions⚠Neither
PyPy
norGraalPy
- _PyEval_EvalFrameDefault⚠Non-
Py_3_11
- _PyImport_FindExtensionObject⚠Non-
Py_3_11
- Get the frame evaluation function.
- Set the frame evaluation function.
- _PyObject_CallFunction_SizeT⚠Non-
Py_3_13
- _PyObject_CallMethod_SizeT⚠Non-
Py_3_13
- _PyObject_CallNoArg⚠
Py_3_8
and neitherPyPy
norGraalPy
- _PyObject_FastCall⚠
Py_3_8
and neitherPyPy
norGraalPy
- _PyObject_FastCallTstate⚠
Py_3_8
and neitherPyPy
norGraalPy
- _PyObject_GetDictPtr⚠Non-
PyPy
- _PyObject_MakeTpCall⚠
Py_3_8
and neitherPyPy
norGraalPy
- _PyObject_NextNotImplemented⚠Non-
PyPy
- _PyObject_VectorcallTstate⚠
Py_3_8
and neitherPyPy
norGraalPy
- _PySequence_IterSearch⚠Neither
PyPy
norGraalPy
- _PySet_NextEntry⚠Non-
Py_LIMITED_API
- _PyStack_AsDict⚠
Py_3_8
and neitherPyPy
norGraalPy
- _PyUnicode_COMPACT_DATA⚠Non-
GraalPy
- _PyUnicode_CheckConsistency⚠Neither
PyPy
norGraalPy
- _PyUnicode_NONCOMPACT_DATA⚠Non-
GraalPy
- _Py_CheckFunctionResult⚠
Py_3_8
and neitherPyPy
norGraalPy
- _Py_DecRef⚠
Py_3_10
- _Py_HashBytes⚠Neither
Py_LIMITED_API
norPyPy
norGraalPy
- _Py_IncRef⚠
Py_3_10
Type Aliases§
- PyCMethod
Py_3_9
and non-Py_LIMITED_API
- PyFrameStateNeither
PyPy
norGraalPy
norPy_3_11
- PyObjectObRefcntNon-
Py_3_12
- 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
and non-Py_3_11
- sendfunc
Py_3_10
- vectorcallfunc
Py_3_8
Unions§
- Function types used to implement Python callables.