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§
- C API Compatibility Shims
- marshal
Non- Py_LIMITED_API - structmember
Deprecated
Macros§
- This is a helper macro to create a
&'static CStr.
Structs§
- PyByte
Array Object Neither PyPynorGraalPynorPy_LIMITED_API - PyBytes
Object Neither PyPynorGraalPynorPy_LIMITED_API - PyCFunction
Object Py_3_9and non-Py_LIMITED_APIand non-GraalPy - PyCMethod
Object Non- GraalPy - PyCode
Object Neither PyPynorGraalPyandPy_3_8and non-Py_3_11 - Structure representing a
datetime.date - Structure representing a
datetime.datetime. - Structure representing a
datetime.timedelta. - Structure representing a
datetime.time. - PyDict
Object Non- GraalPy - PyFrame
Object Neither PyPynorGraalPynorPy_3_11 - PyFunction
Object Neither PyPynorGraalPyandPy_3_10 - PyFuture
Features Neither PyPynorGraalPynorPy_3_13 - PyGen
Object Neither PyPynorGraalPy - Represents the PyGetSetDef structure.
- PyHash_
Func Def Neither Py_LIMITED_APInorPyPynorGraalPy - PyImport
Error Object Neither PyPynorGraalPy - PyList
Object Neither PyPynorGraalPy - PyMem
Allocator Ex Neither PyPynorGraalPy - Represents the PyMemberDef structure.
- Represents the PyMethodDef structure.
- PyOS
Error Object Neither PyPynorGraalPy - PyObject
Arena Allocator Neither PyPynorGraalPy - PySet
Object Neither Py_LIMITED_APInorPyPynorGraalPy - PySlice
Object Non- Py_LIMITED_API - PySyntax
Error Object Neither PyPynorGraalPy - PySystem
Exit Object Neither PyPynorGraalPy - PyTry
Block Neither PyPynorGraalPynorPy_3_11 - PyUnicode
Error Object Neither PyPynorGraalPy - PyWeak
Reference Neither PyPynorGraalPy - _PyDate
Time_ Base Date Time Neither PyPynorGraalPyStructure representing adatetime.datetimewithout atzinfomember. - _PyDate
Time_ Base Time Neither PyPynorGraalPyStructure representing adatetime.timewithout atzinfomember. - _PyErr_
Stack Item Non- PyPy - _PyWeak
Reference Neither PyPynorGraalPy - _frozen
Non- PyPy - _inittab
Non- PyPy - setentry
Neither Py_LIMITED_APInorPyPynorGraalPy
Enums§
- PySend
Result Py_3_10
Constants§
- METH_
FASTCALL Py_3_10or non-Py_LIMITED_API - METH_
METHOD Py_3_9and non-Py_LIMITED_API - PY_
BIG_ ENDIAN Little-endian - PY_
LITTLE_ ENDIAN Little-endian - Maximum number of dimensions
- PyUnicode_
WCHAR_ KIND Deprecated Non- Py_3_12 - 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_8and non-Py_LIMITED_APISet 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_10and 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_10and non-Py_LIMITED_API - Py_
fstring_ input Py_3_9 - Py_
func_ type_ input Py_3_8 - _Py_
T_ NONE Deprecated - _Py_
T_ OBJECT Deprecated - _Py_
WRITE_ RESTRICTED Deprecated
Statics§
- built-in ‘object’
- PyDict
RevIter Item_ Type Py_3_8 - PyDict
RevIter Key_ Type Py_3_8 - PyDict
RevIter Value_ Type Py_3_8 - PyExc_
Encoding Warning Py_3_10 - PyFunction_
Type Not ( PyPyand non-Py_3_8) - PyImport_
Frozen Modules Non- PyPy - PyImport_
Inittab Non- PyPy - built-in ‘super’
- built-in ‘type’
- Py_
Bytes Warning Flag Deprecated - Py_
Debug Flag Deprecated - Py_
Dont Write Bytecode Flag Deprecated - Py_
File System Default Encode Errors Deprecated - Py_
File System Default Encoding Deprecated - Py_
Frozen Flag Deprecated - Py_
HasFile System Default Encoding Deprecated - Py_
Ignore Environment Flag Deprecated - Py_
Inspect Flag Deprecated - Py_
Interactive Flag Deprecated - Py_
Isolated Flag Deprecated - Py_
NoSite Flag Deprecated - Py_
NoUser Site Directory Deprecated - Py_
Optimize Flag Deprecated - Py_
Quiet Flag Deprecated - Py_
Unbuffered Stdio Flag Deprecated - Py_
UseClass Exceptions Flag Deprecated - Py_
Verbose Flag Deprecated - _PyManaged
Buffer_ Type Non- Py_LIMITED_API
Functions§
- PyAny
Set_ ⚠Check Exact Non- PyPy - PyCFunction_
Call ⚠Deprecated Non- Py_3_13 - PyCFunction_
Check ⚠Py_3_9 - PyCFunction_
Check ⚠Exact 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_
Addr2 ⚠Line Non- GraalPy - PyCode_
Check ⚠Neither PyPynorGraalPy - PyCode_
GetNum ⚠Free Neither PyPynorGraalPyandPy_3_10and non-Py_3_11 - PyCode_
New ⚠Non- GraalPy - PyCode_
NewEmpty ⚠Non- GraalPy - PyCode_
NewWith ⚠PosOnly Args Non- GraalPyandPy_3_8 - PyCodec_
Unregister ⚠Py_3_10and non-PyPy - Returns a pointer to a
PyDateTime_CAPIinstance - Check if
opis aPyDateTimeAPI.DateTimeTypeor subtype. - Check if
op’s type is exactlyPyDateTimeAPI.DateTimeType. - PyDate
Time_ ⚠DATE_ GET_ FOLD Neither PyPynorGraalPyRetrieve the fold component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 1] - PyDate
Time_ ⚠DATE_ GET_ HOUR Neither PyPynorGraalPyRetrieve the hour component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 23] - PyDate
Time_ ⚠DATE_ GET_ MICROSECOND Neither PyPynorGraalPyRetrieve the microsecond component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 999999] - PyDate
Time_ ⚠DATE_ GET_ MINUTE Neither PyPynorGraalPyRetrieve the minute component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 59] - PyDate
Time_ ⚠DATE_ GET_ SECOND Neither PyPynorGraalPyRetrieve the second component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 59] - PyDate
Time_ ⚠DATE_ GET_ TZINFO Neither PyPynorGraalPyRetrieve the tzinfo component of aPyDateTime_DateTime. Returns a pointer to aPyObjectthat should be either NULL or an instance of adatetime.tzinfosubclass. - PyDate
Time_ ⚠DELTA_ GET_ DAYS Neither PyPynorGraalPyRetrieve the days component of aPyDateTime_Delta. - PyDate
Time_ ⚠DELTA_ GET_ MICROSECONDS Neither PyPynorGraalPyRetrieve the seconds component of aPyDateTime_Delta. - PyDate
Time_ ⚠DELTA_ GET_ SECONDS Neither PyPynorGraalPyRetrieve the seconds component of aPyDateTime_Delta. - PyDate
Time_ ⚠From Timestamp Non- PyPy - PyDate
Time_ ⚠GET_ DAY Neither PyPynorGraalPyRetrieve the day component of aPyDateTime_DateorPyDateTime_DateTime. Returns a signed integer in the interval[1, 31]. - PyDate
Time_ ⚠GET_ MONTH Neither PyPynorGraalPyRetrieve the month component of aPyDateTime_DateorPyDateTime_DateTime. Returns a signed integer in the range[1, 12]. - PyDate
Time_ ⚠GET_ YEAR Neither PyPynorGraalPyRetrieve the year component of aPyDateTime_DateorPyDateTime_DateTime. Returns a signed integer greater than 0. - Populates the
PyDateTimeAPIobject - PyDate
Time_ ⚠TIME_ GET_ FOLD Neither PyPynorGraalPyRetrieve the fold component of aPyDateTime_Time. Returns a signed integer in the interval[0, 1] - PyDate
Time_ ⚠TIME_ GET_ HOUR Neither PyPynorGraalPyRetrieve the hour component of aPyDateTime_Time. Returns a signed integer in the interval[0, 23] - PyDate
Time_ ⚠TIME_ GET_ MICROSECOND Neither PyPynorGraalPyRetrieve the microsecond component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 999999] - PyDate
Time_ ⚠TIME_ GET_ MINUTE Neither PyPynorGraalPyRetrieve the minute component of aPyDateTime_Time. Returns a signed integer in the interval[0, 59] - PyDate
Time_ ⚠TIME_ GET_ SECOND Neither PyPynorGraalPyRetrieve the second component of aPyDateTime_DateTime. Returns a signed integer in the interval[0, 59] - PyDate
Time_ ⚠TIME_ GET_ TZINFO Neither PyPynorGraalPyRetrieve the tzinfo component of aPyDateTime_Time. Returns a pointer to aPyObjectthat should be either NULL or an instance of adatetime.tzinfosubclass. - Type Check macros
- Check if
op’s type is exactlyPyDateTimeAPI.DateType. - PyDate_
From ⚠Timestamp Non- PyPy - Check if
opis aPyDateTimeAPI.DetaTypeor subtype. - Check if
op’s type is exactlyPyDateTimeAPI.DeltaType. - PyErr_
SetInterrupt ⚠Ex Py_3_10 - PyEval_
Call ⚠Function Deprecated Non- Py_3_13 - PyEval_
Call ⚠Method Deprecated Non- Py_3_13 - PyEval_
Call ⚠Object Deprecated Non- Py_3_13 - PyEval_
Call ⚠Object With Keywords Deprecated Non- Py_3_13 - PyEval_
Init ⚠Threads Deprecated - PyEval_
Threads ⚠Initialized Deprecated Non- Py_3_13 - PyException
Instance_ ⚠Class Non- PyPy - PyFrame_
Block ⚠Pop Neither PyPynorGraalPynorPy_3_11 - PyFrame_
GetCode ⚠Non- GraalPyand (Py_3_10, orPy_3_9and non-Py_LIMITED_API) - PyFrame_
New ⚠Non- GraalPy - PyFrozen
Set_ ⚠Check Non- PyPy - PyFrozen
Set_ ⚠Check Exact Neither PyPynorGraalPy - PyFunction_
Check ⚠Not ( PyPyand non-Py_3_8) - PyGC_
Disable ⚠Py_3_10 - PyGC_
Enable ⚠Py_3_10 - PyGC_
IsEnabled ⚠Py_3_10 - PyGIL
State_ ⚠GetThis Thread State Non- PyPy - PyHash_
GetFunc ⚠Def Neither Py_LIMITED_APInorPyPynorGraalPy - PyHeap
Type_ ⚠GET_ MEMBERS Non- Py_3_11 - PyImport_
Extend ⚠Inittab Non- PyPy - PyIndex_
Check ⚠Neither Py_LIMITED_APInorPyPy - PyInterpreter
State_ ⚠Clear Non- PyPy - PyInterpreter
State_ ⚠Delete Non- PyPy - PyInterpreter
State_ ⚠Get Py_3_9and non-PyPy - PyInterpreter
State_ ⚠GetDict Py_3_8and non-PyPy - PyInterpreter
State_ ⚠GetID Non- PyPy - PyInterpreter
State_ ⚠Main Non- PyPy - PyInterpreter
State_ ⚠New Non- PyPy - PyInterpreter
State_ ⚠Thread Head Non- PyPy - PyIter_
Check ⚠Py_3_8orPyPy - PyIter_
Send ⚠Non- PyPyandPy_3_10 - PyList_
GET_ ⚠ITEM Neither PyPynorGraalPyMacro, trading safety for speed - PyList_
GET_ ⚠SIZE Non- PyPy - PyList_
SET_ ⚠ITEM Neither PyPynorGraalPyMacro, only to be used to fill in brand new lists - PyMapping_
Length ⚠Non- PyPy - PyMem_
GetAllocator ⚠Neither PyPynorGraalPy - PyMem_
SetAllocator ⚠Neither PyPynorGraalPy - PyMem_
Setup ⚠Debug Hooks Neither PyPynorGraalPy - PyMemory
View_ ⚠From Buffer Py_3_11or non-Py_LIMITED_API - PyModule_
AddObject ⚠Ref Py_3_10 - PyModule_
AddType ⚠Py_3_10, orPy_3_9and non-Py_LIMITED_API - PyModule_
Create2 ⚠Non- py_sys_config="Py_TRACE_REFS" - PyModule_
From ⚠DefAnd Spec2 Non- py_sys_config="Py_TRACE_REFS" - PyModule_
GetFilename ⚠Deprecated Not (Windows and PyPy) - PyModule_
GetFilename ⚠Object Non- PyPy - PyModule_
GetName ⚠Object Non- PyPy - PyOS_
After ⚠Fork Deprecated - PyObject_
Call ⚠Method NoArgs Py_3_9and neitherPyPynorGraalPy - PyObject_
Call ⚠Method OneArg Py_3_9and neitherPyPynorGraalPy - PyObject_
Call ⚠NoArgs Non- PyPyand non-GraalPyand (Py_3_10, or non-Py_LIMITED_APIandPy_3_9) - PyObject_
Call ⚠OneArg Py_3_8and neitherPyPynorGraalPy - PyObject_
Check ⚠Buffer Py_3_9and neitherPyPynorGraalPyand non-Py_3_11 - PyObject_
DelAttr ⚠Non- Py_3_13and non-PyPy - PyObject_
DelAttr ⚠String Non- Py_3_13and non-PyPy - PyObject_
GC_ ⚠IsFinalized Py_3_9and non-PyPy, orPy_3_10 - PyObject_
GC_ ⚠IsTracked Py_3_9and non-PyPy, orPy_3_10 - PyObject_
GC_ ⚠Track Non- PyPy - PyObject_
GC_ ⚠UnTrack Non- PyPy - PyObject_
Generic ⚠GetDict Not ( Py_LIMITED_APIand non-Py_3_10) - PyObject_
GetArena ⚠Allocator Neither PyPynorGraalPy - PyObject_
IS_ ⚠GC Py_3_9 - PyObject_
SetArena ⚠Allocator Neither PyPynorGraalPy - PyObject_
Vectorcall ⚠Py_3_8and neitherPyPynorGraalPy - PyObject_
Vectorcall ⚠Dict Py_3_8 - PyObject_
Vectorcall ⚠Method Py_3_9and neitherPyPynorGraalPy - PyRun_
AnyFile ⚠Neither PyPynorGraalPy - PyRun_
AnyFile ⚠Ex Neither PyPynorGraalPy - PyRun_
AnyFile ⚠Flags Neither PyPynorGraalPy - PyRun_
File ⚠Ex Neither PyPynorGraalPy - PyRun_
File ⚠ExFlags Neither PyPynorGraalPy - PyRun_
File ⚠Flags Neither PyPynorGraalPy - PyRun_
Interactive ⚠Loop Neither PyPynorGraalPy - PyRun_
Interactive ⚠One Neither PyPynorGraalPy - PyRun_
Simple ⚠File Neither PyPynorGraalPy - PyRun_
Simple ⚠File Ex Neither PyPynorGraalPy - PySequence_
Length ⚠Non- PyPy - PySet_
Check ⚠Non- PyPy - PySet_
Check ⚠Exact Py_3_10 - PySet_
GET_ ⚠SIZE Neither PyPynorGraalPyand non-Py_LIMITED_API - PyStruct
Sequence_ ⚠GET_ ITEM Neither Py_LIMITED_APInorPyPynorGraalPy - PyStruct
Sequence_ ⚠GetItem Non- PyPy - PyStruct
Sequence_ ⚠Init Type Non- Py_LIMITED_API - PyStruct
Sequence_ ⚠Init Type2 Non- Py_LIMITED_API - PyStruct
Sequence_ ⚠NewType Non- PyPy - PyStruct
Sequence_ ⚠SET_ ITEM Neither Py_LIMITED_APInorPyPynorGraalPy - PyStruct
Sequence_ ⚠SetItem Non- PyPy - Check if
opis aPyDateTimeAPI.TZInfoTypeor subtype. - Check if
op’s type is exactlyPyDateTimeAPI.TZInfoType. - PyThread
State_ ⚠Next Non- PyPy - PyThread
State_ ⚠SetAsync Exc Non- PyPy - Check if
opis aPyDateTimeAPI.TimeTypeor subtype. - Check if
op’s type is exactlyPyDateTimeAPI.TimeType. - PyTrace
Back_ ⚠Check Non- PyPy - PyTuple_
GET_ ⚠ITEM Neither PyPynorGraalPy - PyTuple_
GET_ ⚠SIZE Non- PyPyMacro, trading safety for speed - PyTuple_
SET_ ⚠ITEM Neither PyPynorGraalPyMacro, only to be used to fill in brand new tuples - PyType_
From ⚠Module AndSpec Py_3_10, orPy_3_9and non-Py_LIMITED_API - PyType_
GetModule ⚠Py_3_10, orPy_3_9and non-Py_LIMITED_API - PyType_
GetModule ⚠State Py_3_10, orPy_3_9and non-Py_LIMITED_API - PyUnicode
Decode ⚠Error_ Create Non- PyPy - PyUnicode_
1BYTE_ ⚠DATA Neither GraalPynorPyPy - PyUnicode_
2BYTE_ ⚠DATA Neither GraalPynorPyPy - PyUnicode_
4BYTE_ ⚠DATA Neither GraalPynorPyPy - PyUnicode_
AsUT ⚠F8And Size Py_3_10or non-Py_LIMITED_API - PyUnicode_
AsUnicode ⚠Deprecated Non- Py_3_12 - PyUnicode_
AsUnicode ⚠AndSize Deprecated Non- Py_3_12 - PyUnicode_
Check ⚠Non- PyPy - PyUnicode_
Check ⚠Exact Non- PyPy - PyUnicode_
Copy ⚠Characters Non- PyPy - PyUnicode_
DATA ⚠Neither GraalPynorPyPy - PyUnicode_
Fill ⚠Non- PyPy - PyUnicode_
From ⚠Unicode Deprecated Non- Py_3_12 - PyUnicode_
GET_ ⚠LENGTH Non- GraalPy - PyUnicode_
GetSize ⚠Deprecated Non- Py_3_12 - PyUnicode_
IS_ ⚠ASCII Non- GraalPy - PyUnicode_
IS_ ⚠COMPACT Non- GraalPy - PyUnicode_
IS_ ⚠COMPACT_ ASCII Non- GraalPy - PyUnicode_
IS_ ⚠READY Neither GraalPynorPy_3_12 - PyUnicode_
Intern ⚠Immortal Deprecated Non- Py_3_12 - PyUnicode_
KIND ⚠Non- GraalPy - PyUnicode_
READY ⚠Neither Py_3_12norGraalPy - PyVectorcall_
Call ⚠Py_3_8 - PyVectorcall_
Function ⚠Py_3_8and neitherPyPynorGraalPy - PyVectorcall_
NARGS ⚠Py_3_8 - PyWeakref_
Check ⚠Proxy Non- PyPy - PyWeakref_
Check ⚠Ref Non- PyPy - PyWeakref_
Check ⚠RefExact Non- PyPy - Py_
Compile ⚠String Neither PyPynorGraalPy - Py_
Compile ⚠String ExFlags Neither PyPynorGraalPy - Py_
Compile ⚠String Flags Neither PyPynorGraalPy - Py_
Compile ⚠String Object Non- Py_LIMITED_API - Py_
Enter ⚠Recursive Call Py_3_9 - Py_
GETENV ⚠Non- Py_3_11 - Py_Is⚠
Not ( PyPyandPy_3_10) - Py_
Leave ⚠Recursive Call Py_3_9 - Py_
NewRef ⚠Py_3_10and (non-Py_LIMITED_APIorPyPy) - Py_
SetPath ⚠Non- Py_3_13 - Py_
XNew ⚠Ref Py_3_10and (non-Py_LIMITED_APIorPyPy) - _PyDict_
Contains_ ⚠Known Hash Py_3_10 - _PyEval_
Eval ⚠Frame Default Non- Py_3_11 - _PyImport_
Find ⚠Extension Object Non- Py_3_11 - Get the frame evaluation function.
- Set the frame evaluation function.
- _PyObject_
Call ⚠Function_ SizeT Non- Py_3_13 - _PyObject_
Call ⚠Method_ SizeT Non- Py_3_13 - _PyObject_
Call ⚠NoArg Py_3_8and neitherPyPynorGraalPy - _PyObject_
Fast ⚠Call Py_3_8and neitherPyPynorGraalPy - _PyObject_
Fast ⚠Call Tstate Py_3_8and neitherPyPynorGraalPy - _PyObject_
Make ⚠TpCall Py_3_8and neitherPyPynorGraalPy - _PyObject_
Vectorcall ⚠Tstate Py_3_8and neitherPyPynorGraalPy - _PySequence_
Iter ⚠Search Neither PyPynorGraalPy - _PySet_
Next ⚠Entry Non- Py_LIMITED_API - _PyStack_
AsDict ⚠Py_3_8and neitherPyPynorGraalPy - _PyUnicode_
COMPACT_ ⚠DATA Non- GraalPy - _PyUnicode_
Check ⚠Consistency Neither PyPynorGraalPy - _PyUnicode_
NONCOMPACT_ ⚠DATA Neither GraalPynorPyPy - _Py_
Check ⚠Function Result Py_3_8and neitherPyPynorGraalPy - _Py_
Hash ⚠Bytes Neither Py_LIMITED_APInorPyPynorGraalPy
Type Aliases§
- PyCFunction
Fast Py_3_10or non-Py_LIMITED_API - PyCFunction
Fast With Keywords Py_3_10or non-Py_LIMITED_API - PyCMethod
Py_3_9and non-Py_LIMITED_API - PyFrame
State Neither PyPynorGraalPynorPy_3_11 - PyObject
ObRefcnt Non- Py_3_12and non-Py_GIL_DISABLED - PyStruct
Sequence Non- Py_LIMITED_API - Py_
UNICODE Non- Py_LIMITED_API - _PyC
Function Fast Deprecated Py_3_10or non-Py_LIMITED_API - _PyC
Function Fast With Keywords Deprecated Py_3_10or non-Py_LIMITED_API - _PyFrame
Eval Function Py_3_9and non-Py_3_11 - sendfunc
Py_3_10 - vectorcallfunc
Py_3_8
Unions§
- Function types used to implement Python callables.