Supporting Cyclic Garbage Collection

Supporting Cyclic Garbage Collection¶
Python’s support for detecting and collecting garbage which involves circular references requires support from object types which are “containers” for other objects which may also be containers. Types which do not store references to other objects, or which only store references to atomic types (such as numbers or strings), do not need to provide any explicit support for garbage collection.
To create a container type, the tp_flags
field of the type object must
include the Py_TPFLAGS_HAVE_GC
and provide an implementation of the
tp_traverse
handler. If instances of the type are mutable, a
tp_clear
implementation must also be provided.
Py_TPFLAGS_HAVE_GC
Objects with a type with this flag set must conform with the rules documented here. For convenience these objects will be referred to as container objects.
Constructors for container types must conform to two rules:
The memory for the object must be allocated using
PyObject_GC_New
orPyObject_GC_NewVar
.Once all the fields which may contain references to other containers are initialized, it must call
PyObject_GC_Track()
.
Similarly, the deallocator for the object must conform to a similar pair of rules:
Before fields which refer to other containers are invalidated,
PyObject_GC_UnTrack()
must be called.The object’s memory must be deallocated using
PyObject_GC_Del()
.Warning
If a type adds the Py_TPFLAGS_HAVE_GC, then it must implement at least a
tp_traverse
handler or explicitly use one from its subclass or subclasses.When calling
PyType_Ready()
or some of the APIs that indirectly call it likePyType_FromSpecWithBases()
orPyType_FromSpec()
the interpreter will automatically populate thetp_flags
,tp_traverse
andtp_clear
fields if the type inherits from a class that implements the garbage collector protocol and the child class does not include thePy_TPFLAGS_HAVE_GC
flag.
-
PyObject_GC_New(TYPE, typeobj)¶
Analogous to
PyObject_New
but for container objects with thePy_TPFLAGS_HAVE_GC
flag set.Do not call this directly to allocate memory for an object; call the type’s
tp_alloc
slot instead.When populating a type’s
tp_alloc
slot,PyType_GenericAlloc()
is preferred over a custom function that simply calls this macro.Memory allocated by this macro must be freed with
PyObject_GC_Del()
(usually called via the object’stp_free
slot).
-
PyObject_GC_NewVar(TYPE, typeobj, size)¶
Analogous to
PyObject_NewVar
but for container objects with thePy_TPFLAGS_HAVE_GC
flag set.Do not call this directly to allocate memory for an object; call the type’s
tp_alloc
slot instead.When populating a type’s
tp_alloc
slot,PyType_GenericAlloc()
is preferred over a custom function that simply calls this macro.Memory allocated by this macro must be freed with
PyObject_GC_Del()
(usually called via the object’stp_free
slot).
-
PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)¶
- This is Unstable API. It may change without warning in minor releases.
Analogous to
PyObject_GC_New
but allocates extra_size bytes at the end of the object (at offsettp_basicsize
). The allocated memory is initialized to zeros, except for thePython object header
.The extra data will be deallocated with the object, but otherwise it is not managed by Python.
Memory allocated by this function must be freed with
PyObject_GC_Del()
(usually called via the object’stp_free
slot).Warning
The function is marked as unstable because the final mechanism for reserving extra data after an instance is not yet decided. For allocating a variable number of fields, prefer using
PyVarObject
andtp_itemsize
instead.Added in version 3.12.
-
PyObject_GC_Resize(TYPE, op, newsize)¶
Resize an object allocated by
PyObject_NewVar
. Returns the resized object of typeTYPE*
(refers to any C type) orNULL
on failure.op must be of type PyVarObject* and must not be tracked by the collector yet. newsize must be of type
Py_ssize_t
.
-
void PyObject_GC_Track(PyObject *op)¶
- Part of the Stable ABI.
Adds the object op to the set of container objects tracked by the collector. The collector can run at unexpected times so objects must be valid while being tracked. This should be called once all the fields followed by the
tp_traverse
handler become valid, usually near the end of the constructor.
-
int PyObject_IS_GC(PyObject *obj)¶
Returns non-zero if the object implements the garbage collector protocol, otherwise returns 0.
The object cannot be tracked by the garbage collector if this function returns 0.
-
int PyObject_GC_IsTracked(PyObject *op)¶
- Part of the Stable ABI since version 3.9.
Returns 1 if the object type of op implements the GC protocol and op is being currently tracked by the garbage collector and 0 otherwise.
This is analogous to the Python function
gc.is_tracked()
.Added in version 3.9.
-
int PyObject_GC_IsFinalized(PyObject *op)¶
- Part of the Stable ABI since version 3.9.
Returns 1 if the object type of op implements the GC protocol and op has been already finalized by the garbage collector and 0 otherwise.
This is analogous to the Python function
gc.is_finalized()
.Added in version 3.9.
-
void PyObject_GC_Del(void *op)¶
- Part of the Stable ABI.
Releases memory allocated to an object using
PyObject_GC_New
orPyObject_GC_NewVar
.Do not call this directly to free an object’s memory; call the type’s
tp_free
slot instead.Do not use this for memory allocated by
PyObject_New
,PyObject_NewVar
, or related allocation functions; usePyObject_Free()
instead.See also
PyObject_Free()
is the non-GC equivalent of this function.
-
void PyObject_GC_UnTrack(void *op)¶
- Part of the Stable ABI.
Remove the object op from the set of container objects tracked by the collector. Note that
PyObject_GC_Track()
can be called again on this object to add it back to the set of tracked objects. The deallocator (tp_dealloc
handler) should call this for the object before any of the fields used by thetp_traverse
handler become invalid.
Changed in version 3.8: The _PyObject_GC_TRACK()
and _PyObject_GC_UNTRACK()
macros
have been removed from the public C API.
The tp_traverse
handler accepts a function parameter of this type:
-
typedef int (*visitproc)(PyObject *object, void *arg)¶
- Part of the Stable ABI.
Type of the visitor function passed to the
tp_traverse
handler. The function should be called with an object to traverse as object and the third parameter to thetp_traverse
handler as arg. The Python core uses several visitor functions to implement cyclic garbage detection; it’s not expected that users will need to write their own visitor functions.
The tp_traverse
handler must have the following type:
-
typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)¶
- Part of the Stable ABI.
Traversal function for a container object. Implementations must call the visit function for each object directly contained by self, with the parameters to visit being the contained object and the arg value passed to the handler. The visit function must not be called with a
NULL
object argument. If visit returns a non-zero value that value should be returned immediately.The traversal function must not have any side effects. Implementations may not modify the reference counts of any Python objects nor create or destroy any Python objects.
To simplify writing tp_traverse
handlers, a Py_VISIT()
macro is
provided. In order to use this macro, the tp_traverse
implementation
must name its arguments exactly visit and arg:
-
Py_VISIT(o)¶
If the PyObject* o is not
NULL
, call the visit callback, with arguments o and arg. If visit returns a non-zero value, then return it. Using this macro,tp_traverse
handlers look like:static int my_traverse(Noddy *self, visitproc visit, void *arg) { Py_VISIT(self->foo); Py_VISIT(self->bar); return 0; }
The tp_clear
handler must be of the inquiry
type, or NULL
if the object is immutable.
-
typedef int (*inquiry)(PyObject *self)¶
- Part of the Stable ABI.
Drop references that may have created reference cycles. Immutable objects do not have to define this method since they can never directly create reference cycles. Note that the object must still be valid after calling this method (don’t just call
Py_DECREF()
on a reference). The collector will call this method if it detects that this object is involved in a reference cycle.
Controlling the Garbage Collector State¶
The C-API provides the following functions for controlling garbage collection runs.
-
Py_ssize_t PyGC_Collect(void)¶
- Part of the Stable ABI.
Perform a full garbage collection, if the garbage collector is enabled. (Note that
gc.collect()
runs it unconditionally.)Returns the number of collected + unreachable objects which cannot be collected. If the garbage collector is disabled or already collecting, returns
0
immediately. Errors during garbage collection are passed tosys.unraisablehook
. This function does not raise exceptions.
-
int PyGC_Enable(void)¶
- Part of the Stable ABI since version 3.10.
Enable the garbage collector: similar to
gc.enable()
. Returns the previous state, 0 for disabled and 1 for enabled.Added in version 3.10.
-
int PyGC_Disable(void)¶
- Part of the Stable ABI since version 3.10.
Disable the garbage collector: similar to
gc.disable()
. Returns the previous state, 0 for disabled and 1 for enabled.Added in version 3.10.
-
int PyGC_IsEnabled(void)¶
- Part of the Stable ABI since version 3.10.
Query the state of the garbage collector: similar to
gc.isenabled()
. Returns the current state, 0 for disabled and 1 for enabled.Added in version 3.10.
Querying Garbage Collector State¶
The C-API provides the following interface for querying information about the garbage collector.
-
void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)¶
- This is Unstable API. It may change without warning in minor releases.
Run supplied callback on all live GC-capable objects. arg is passed through to all invocations of callback.
Warning
If new objects are (de)allocated by the callback it is undefined if they will be visited.
Garbage collection is disabled during operation. Explicitly running a collection in the callback may lead to undefined behaviour e.g. visiting the same objects multiple times or not at all.
Added in version 3.12.
-
typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)¶
Type of the visitor function to be passed to
PyUnstable_GC_VisitObjects()
. arg is the same as the arg passed toPyUnstable_GC_VisitObjects
. Return1
to continue iteration, return0
to stop iteration. Other return values are reserved for now so behavior on returning anything else is undefined.Added in version 3.12.


— Asynchronous socket handler

asyncore
— Asynchronous socket handler¶
Deprecated since version 3.6, removed in version 3.12.
This module is no longer part of the Python standard library. It was removed in Python 3.12 after being deprecated in Python 3.6. The removal was decided in PEP 594.
Applications should use the asyncio
module instead.
The last version of Python that provided the asyncore
module was
Python 3.11.


asynchat
— Asynchronous socket command/response handler¶
Deprecated since version 3.6, removed in version 3.12.
This module is no longer part of the Python standard library. It was removed in Python 3.12 after being deprecated in Python 3.6. The removal was decided in PEP 594.
Applications should use the asyncio
module instead.
The last version of Python that provided the asynchat
module was
Python 3.11.


— Read and write AIFF and AIFC files

aifc
— Read and write AIFF and AIFC files¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
The last version of Python that provided the aifc
module was
Python 3.12.


Module Objects

Module Objects¶
-
PyTypeObject PyModule_Type¶
- Part of the Stable ABI.
This instance of
PyTypeObject
represents the Python module type. This is exposed to Python programs astypes.ModuleType
.
-
int PyModule_Check(PyObject *p)¶
Return true if p is a module object, or a subtype of a module object. This function always succeeds.
-
int PyModule_CheckExact(PyObject *p)¶
Return true if p is a module object, but not a subtype of
PyModule_Type
. This function always succeeds.
-
PyObject *PyModule_NewObject(PyObject *name)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Return a new module object with
module.__name__
set to name. The module’s__name__
,__doc__
,__package__
and__loader__
attributes are filled in (all but__name__
are set toNone
). The caller is responsible for setting a__file__
attribute.Return
NULL
with an exception set on error.Added in version 3.3.
Changed in version 3.4:
__package__
and__loader__
are now set toNone
.
-
PyObject *PyModule_New(const char *name)¶
- Return value: New reference. Part of the Stable ABI.
Similar to
PyModule_NewObject()
, but the name is a UTF-8 encoded string instead of a Unicode object.
-
PyObject *PyModule_GetDict(PyObject *module)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Return the dictionary object that implements module’s namespace; this object is the same as the
__dict__
attribute of the module object. If module is not a module object (or a subtype of a module object),SystemError
is raised andNULL
is returned.It is recommended extensions use other
PyModule_*
andPyObject_*
functions rather than directly manipulate a module’s__dict__
.The returned reference is borrowed from the module; it is valid until the module is destroyed.
-
PyObject *PyModule_GetNameObject(PyObject *module)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Return module’s
__name__
value. If the module does not provide one, or if it is not a string,SystemError
is raised andNULL
is returned.Added in version 3.3.
-
const char *PyModule_GetName(PyObject *module)¶
- Part of the Stable ABI.
Similar to
PyModule_GetNameObject()
but return the name encoded to'utf-8'
.The returned buffer is only valid until the module is renamed or destroyed. Note that Python code may rename a module by setting its
__name__
attribute.
-
void *PyModule_GetState(PyObject *module)¶
- Part of the Stable ABI.
Return the “state” of the module, that is, a pointer to the block of memory allocated at module creation time, or
NULL
. SeePyModuleDef.m_size
.
-
PyModuleDef *PyModule_GetDef(PyObject *module)¶
- Part of the Stable ABI.
Return a pointer to the
PyModuleDef
struct from which the module was created, orNULL
if the module wasn’t created from a definition.On error, return
NULL
with an exception set. UsePyErr_Occurred()
to tell this case apart from a missingPyModuleDef
.
-
PyObject *PyModule_GetFilenameObject(PyObject *module)¶
- Return value: New reference. Part of the Stable ABI.
Return the name of the file from which module was loaded using module’s
__file__
attribute. If this is not defined, or if it is not a string, raiseSystemError
and returnNULL
; otherwise return a reference to a Unicode object.Added in version 3.2.
-
const char *PyModule_GetFilename(PyObject *module)¶
- Part of the Stable ABI.
Similar to
PyModule_GetFilenameObject()
but return the filename encoded to ‘utf-8’.The returned buffer is only valid until the module’s
__file__
attribute is reassigned or the module is destroyed.Deprecated since version 3.2:
PyModule_GetFilename()
raisesUnicodeEncodeError
on unencodable filenames, usePyModule_GetFilenameObject()
instead.
Module definitions¶
The functions in the previous section work on any module object, including modules imported from Python code.
Modules defined using the C API typically use a module definition,
PyModuleDef
– a statically allocated, constant “description” of
how a module should be created.
The definition is usually used to define an extension’s “main” module object (see Defining extension modules for details). It is also used to create extension modules dynamically.
Unlike PyModule_New()
, the definition allows management of
module state – a piece of memory that is allocated and cleared together
with the module object.
Unlike the module’s Python attributes, Python code cannot replace or delete
data stored in module state.
-
type PyModuleDef¶
- Part of the Stable ABI (including all members).
The module definition struct, which holds all information needed to create a module object. This structure must be statically allocated (or be otherwise guaranteed to be valid while any modules created from it exist). Usually, there is only one variable of this type for each extension module.
-
PyModuleDef_Base m_base¶
Always initialize this member to
PyModuleDef_HEAD_INIT
.
-
const char *m_name¶
Name for the new module.
-
const char *m_doc¶
Docstring for the module; usually a docstring variable created with
PyDoc_STRVAR
is used.
-
Py_ssize_t m_size¶
Module state may be kept in a per-module memory area that can be retrieved with
PyModule_GetState()
, rather than in static globals. This makes modules safe for use in multiple sub-interpreters.This memory area is allocated based on m_size on module creation, and freed when the module object is deallocated, after the
m_free
function has been called, if present.Setting it to a non-negative value means that the module can be re-initialized and specifies the additional amount of memory it requires for its state.
Setting
m_size
to-1
means that the module does not support sub-interpreters, because it has global state. Negativem_size
is only allowed when using legacy single-phase initialization or when creating modules dynamically.See PEP 3121 for more details.
-
PyMethodDef *m_methods¶
A pointer to a table of module-level functions, described by
PyMethodDef
values. Can beNULL
if no functions are present.
-
PyModuleDef_Slot *m_slots¶
An array of slot definitions for multi-phase initialization, terminated by a
{0, NULL}
entry. When using legacy single-phase initialization, m_slots must beNULL
.
-
traverseproc m_traverse¶
A traversal function to call during GC traversal of the module object, or
NULL
if not needed.This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (
Py_mod_exec
function). More precisely, this function is not called ifm_size
is greater than 0 and the module state (as returned byPyModule_GetState()
) isNULL
.Changed in version 3.9: No longer called before the module state is allocated.
-
inquiry m_clear¶
A clear function to call during GC clearing of the module object, or
NULL
if not needed.This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (
Py_mod_exec
function). More precisely, this function is not called ifm_size
is greater than 0 and the module state (as returned byPyModule_GetState()
) isNULL
.Like
PyTypeObject.tp_clear
, this function is not always called before a module is deallocated. For example, when reference counting is enough to determine that an object is no longer used, the cyclic garbage collector is not involved andm_free
is called directly.Changed in version 3.9: No longer called before the module state is allocated.
-
freefunc m_free¶
A function to call during deallocation of the module object, or
NULL
if not needed.This function is not called if the module state was requested but is not allocated yet. This is the case immediately after the module is created and before the module is executed (
Py_mod_exec
function). More precisely, this function is not called ifm_size
is greater than 0 and the module state (as returned byPyModule_GetState()
) isNULL
.Changed in version 3.9: No longer called before the module state is allocated.
-
PyModuleDef_Base m_base¶
Module slots¶
-
type PyModuleDef_Slot¶
- Part of the Stable ABI (including all members) since version 3.5.
-
int slot¶
A slot ID, chosen from the available values explained below.
-
void *value¶
Value of the slot, whose meaning depends on the slot ID.
Added in version 3.5.
-
int slot¶
The available slot types are:
-
Py_mod_create¶
- Part of the Stable ABI since version 3.5.
Specifies a function that is called to create the module object itself. The value pointer of this slot must point to a function of the signature:
-
PyObject *create_module(PyObject *spec, PyModuleDef *def)¶
The function receives a
ModuleSpec
instance, as defined in PEP 451, and the module definition. It should return a new module object, or set an error and returnNULL
.This function should be kept minimal. In particular, it should not call arbitrary Python code, as trying to import the same module again may result in an infinite loop.
Multiple
Py_mod_create
slots may not be specified in one module definition.If
Py_mod_create
is not specified, the import machinery will create a normal module object usingPyModule_New()
. The name is taken from spec, not the definition, to allow extension modules to dynamically adjust to their place in the module hierarchy and be imported under different names through symlinks, all while sharing a single module definition.There is no requirement for the returned object to be an instance of
PyModule_Type
. Any type can be used, as long as it supports setting and getting import-related attributes. However, onlyPyModule_Type
instances may be returned if thePyModuleDef
has non-NULL
m_traverse
,m_clear
,m_free
; non-zerom_size
; or slots other thanPy_mod_create
.Added in version 3.5.
-
PyObject *create_module(PyObject *spec, PyModuleDef *def)¶
-
Py_mod_exec¶
- Part of the Stable ABI since version 3.5.
Specifies a function that is called to execute the module. This is equivalent to executing the code of a Python module: typically, this function adds classes and constants to the module. The signature of the function is:
If multiple
Py_mod_exec
slots are specified, they are processed in the order they appear in the m_slots array.Added in version 3.5.
-
Py_mod_multiple_interpreters¶
- Part of the Stable ABI since version 3.12.
Specifies one of the following values:
-
Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶
The module does not support being imported in subinterpreters.
-
Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶
The module supports being imported in subinterpreters, but only when they share the main interpreter’s GIL. (See Isolating Extension Modules.)
-
Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶
The module supports being imported in subinterpreters, even when they have their own GIL. (See Isolating Extension Modules.)
This slot determines whether or not importing this module in a subinterpreter will fail.
Multiple
Py_mod_multiple_interpreters
slots may not be specified in one module definition.If
Py_mod_multiple_interpreters
is not specified, the import machinery defaults toPy_MOD_MULTIPLE_INTERPRETERS_SUPPORTED
.Added in version 3.12.
-
Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶
-
Py_mod_gil¶
- Part of the Stable ABI since version 3.13.
Specifies one of the following values:
-
Py_MOD_GIL_USED¶
The module depends on the presence of the global interpreter lock (GIL), and may access global state without synchronization.
-
Py_MOD_GIL_NOT_USED¶
The module is safe to run without an active GIL.
This slot is ignored by Python builds not configured with
--disable-gil
. Otherwise, it determines whether or not importing this module will cause the GIL to be automatically enabled. See Free-threaded CPython for more detail.Multiple
Py_mod_gil
slots may not be specified in one module definition.If
Py_mod_gil
is not specified, the import machinery defaults toPy_MOD_GIL_USED
.Added in version 3.13.
-
Py_MOD_GIL_USED¶
Creating extension modules dynamically¶
The following functions may be used to create a module outside of an extension’s initialization function. They are also used in single-phase initialization.
-
PyObject *PyModule_Create(PyModuleDef *def)¶
- Return value: New reference.
Create a new module object, given the definition in def. This is a macro that calls
PyModule_Create2()
with module_api_version set toPYTHON_API_VERSION
, or toPYTHON_ABI_VERSION
if using the limited API.
-
PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶
- Return value: New reference. Part of the Stable ABI.
Create a new module object, given the definition in def, assuming the API version module_api_version. If that version does not match the version of the running interpreter, a
RuntimeWarning
is emitted.Return
NULL
with an exception set on error.This function does not support slots. The
m_slots
member of def must beNULL
.Note
Most uses of this function should be using
PyModule_Create()
instead; only use this if you are sure you need it.
-
PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶
- Return value: New reference.
This macro calls
PyModule_FromDefAndSpec2()
with module_api_version set toPYTHON_API_VERSION
, or toPYTHON_ABI_VERSION
if using the limited API.Added in version 3.5.
-
PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Create a new module object, given the definition in def and the ModuleSpec spec, assuming the API version module_api_version. If that version does not match the version of the running interpreter, a
RuntimeWarning
is emitted.Return
NULL
with an exception set on error.Note that this does not process execution slots (
Py_mod_exec
). BothPyModule_FromDefAndSpec
andPyModule_ExecDef
must be called to fully initialize a module.Note
Most uses of this function should be using
PyModule_FromDefAndSpec()
instead; only use this if you are sure you need it.Added in version 3.5.
-
int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶
- Part of the Stable ABI since version 3.7.
Process any execution slots (
Py_mod_exec
) given in def.Added in version 3.5.
-
PYTHON_API_VERSION¶
The C API version. Defined for backwards compatibility.
Currently, this constant is not updated in new Python versions, and is not useful for versioning. This may change in the future.
-
PYTHON_ABI_VERSION¶
Defined as
3
for backwards compatibility.Currently, this constant is not updated in new Python versions, and is not useful for versioning. This may change in the future.
Support functions¶
The following functions are provided to help initialize a module
state.
They are intended for a module’s execution slots (Py_mod_exec
),
the initialization function for legacy single-phase initialization,
or code that creates modules dynamically.
-
int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)¶
- Part of the Stable ABI since version 3.10.
Add an object to module as name. This is a convenience function which can be used from the module’s initialization function.
On success, return
0
. On error, raise an exception and return-1
.Example usage:
static int add_spam(PyObject *module, int value) { PyObject *obj = PyLong_FromLong(value); if (obj == NULL) { return -1; } int res = PyModule_AddObjectRef(module, "spam", obj); Py_DECREF(obj); return res; }
To be convenient, the function accepts
NULL
value with an exception set. In this case, return-1
and just leave the raised exception unchanged.The example can also be written without checking explicitly if obj is
NULL
:static int add_spam(PyObject *module, int value) { PyObject *obj = PyLong_FromLong(value); int res = PyModule_AddObjectRef(module, "spam", obj); Py_XDECREF(obj); return res; }
Note that
Py_XDECREF()
should be used instead ofPy_DECREF()
in this case, since obj can beNULL
.The number of different name strings passed to this function should be kept small, usually by only using statically allocated strings as name. For names that aren’t known at compile time, prefer calling
PyUnicode_FromString()
andPyObject_SetAttr()
directly. For more details, seePyUnicode_InternFromString()
, which may be used internally to create a key object.Added in version 3.10.
-
int PyModule_Add(PyObject *module, const char *name, PyObject *value)¶
- Part of the Stable ABI since version 3.13.
Similar to
PyModule_AddObjectRef()
, but “steals” a reference to value. It can be called with a result of function that returns a new reference without bothering to check its result or even saving it to a variable.Example usage:
if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) { goto error; }
Added in version 3.13.
-
int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)¶
- Part of the Stable ABI.
Similar to
PyModule_AddObjectRef()
, but steals a reference to value on success (if it returns0
).The new
PyModule_Add()
orPyModule_AddObjectRef()
functions are recommended, since it is easy to introduce reference leaks by misusing thePyModule_AddObject()
function.Note
Unlike other functions that steal references,
PyModule_AddObject()
only releases the reference to value on success.This means that its return value must be checked, and calling code must
Py_XDECREF()
value manually on error.Example usage:
PyObject *obj = PyBytes_FromString(value); if (PyModule_AddObject(module, "spam", obj) < 0) { // If 'obj' is not NULL and PyModule_AddObject() failed, // 'obj' strong reference must be deleted with Py_XDECREF(). // If 'obj' is NULL, Py_XDECREF() does nothing. Py_XDECREF(obj); goto error; } // PyModule_AddObject() stole a reference to obj: // Py_XDECREF(obj) is not needed here.
Deprecated since version 3.13:
PyModule_AddObject()
is soft deprecated.
-
int PyModule_AddIntConstant(PyObject *module, const char *name, long value)¶
- Part of the Stable ABI.
Add an integer constant to module as name. This convenience function can be used from the module’s initialization function. Return
-1
with an exception set on error,0
on success.This is a convenience function that calls
PyLong_FromLong()
andPyModule_AddObjectRef()
; see their documentation for details.
-
int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)¶
- Part of the Stable ABI.
Add a string constant to module as name. This convenience function can be used from the module’s initialization function. The string value must be
NULL
-terminated. Return-1
with an exception set on error,0
on success.This is a convenience function that calls
PyUnicode_InternFromString()
andPyModule_AddObjectRef()
; see their documentation for details.
-
PyModule_AddIntMacro(module, macro)¶
Add an int constant to module. The name and the value are taken from macro. For example
PyModule_AddIntMacro(module, AF_INET)
adds the int constant AF_INET with the value of AF_INET to module. Return-1
with an exception set on error,0
on success.
-
PyModule_AddStringMacro(module, macro)¶
Add a string constant to module.
-
int PyModule_AddType(PyObject *module, PyTypeObject *type)¶
- Part of the Stable ABI since version 3.10.
Add a type object to module. The type object is finalized by calling internally
PyType_Ready()
. The name of the type object is taken from the last component oftp_name
after dot. Return-1
with an exception set on error,0
on success.Added in version 3.9.
-
int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶
- Part of the Stable ABI since version 3.7.
Add the functions from the
NULL
terminated functions array to module. Refer to thePyMethodDef
documentation for details on individual entries (due to the lack of a shared module namespace, module level “functions” implemented in C typically receive the module as their first parameter, making them similar to instance methods on Python classes).This function is called automatically when creating a module from
PyModuleDef
(such as when using Multi-phase initialization,PyModule_Create
, orPyModule_FromDefAndSpec
). Some module authors may prefer defining functions in multiplePyMethodDef
arrays; in that case they should call this function directly.The functions array must be statically allocated (or otherwise guaranteed to outlive the module object).
Added in version 3.5.
-
int PyModule_SetDocString(PyObject *module, const char *docstring)¶
- Part of the Stable ABI since version 3.7.
Set the docstring for module to docstring. This function is called automatically when creating a module from
PyModuleDef
(such as when using Multi-phase initialization,PyModule_Create
, orPyModule_FromDefAndSpec
).Return
0
on success. Return-1
with an exception set on error.Added in version 3.5.
-
int PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶
- This is Unstable API. It may change without warning in minor releases.
Indicate that module does or does not support running without the global interpreter lock (GIL), using one of the values from
Py_mod_gil
. It must be called during module’s initialization function when using Legacy single-phase initialization. If this function is not called during module initialization, the import machinery assumes the module does not support running without the GIL. This function is only available in Python builds configured with--disable-gil
. Return-1
with an exception set on error,0
on success.Added in version 3.13.
Module lookup (single-phase initialization)¶
The legacy single-phase initialization initialization scheme creates singleton modules that can be looked up in the context of the current interpreter. This allows the module object to be retrieved later with only a reference to the module definition.
These functions will not work on modules created using multi-phase initialization, since multiple such modules can be created from a single definition.
-
PyObject *PyState_FindModule(PyModuleDef *def)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Returns the module object that was created from def for the current interpreter. This method requires that the module object has been attached to the interpreter state with
PyState_AddModule()
beforehand. In case the corresponding module object is not found or has not been attached to the interpreter state yet, it returnsNULL
.
-
int PyState_AddModule(PyObject *module, PyModuleDef *def)¶
- Part of the Stable ABI since version 3.3.
Attaches the module object passed to the function to the interpreter state. This allows the module object to be accessible via
PyState_FindModule()
.Only effective on modules created using single-phase initialization.
Python calls
PyState_AddModule
automatically after importing a module that uses single-phase initialization, so it is unnecessary (but harmless) to call it from module initialization code. An explicit call is needed only if the module’s own init code subsequently callsPyState_FindModule
. The function is mainly intended for implementing alternative import mechanisms (either by calling it directly, or by referring to its implementation for details of the required state updates).If a module was attached previously using the same def, it is replaced by the new module.
The caller must have an attached thread state.
Return
-1
with an exception set on error,0
on success.Added in version 3.3.
-
int PyState_RemoveModule(PyModuleDef *def)¶
- Part of the Stable ABI since version 3.3.
Removes the module object created from def from the interpreter state. Return
-1
with an exception set on error,0
on success.The caller must have an attached thread state.
Added in version 3.3.


Reflection

Reflection¶
-
PyObject *PyEval_GetBuiltins(void)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Deprecated since version 3.13: Use
PyEval_GetFrameBuiltins()
instead.Return a dictionary of the builtins in the current execution frame, or the interpreter of the thread state if no frame is currently executing.
-
PyObject *PyEval_GetLocals(void)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Deprecated since version 3.13: Use either
PyEval_GetFrameLocals()
to obtain the same behaviour as callinglocals()
in Python code, or else callPyFrame_GetLocals()
on the result ofPyEval_GetFrame()
to access thef_locals
attribute of the currently executing frame.Return a mapping providing access to the local variables in the current execution frame, or
NULL
if no frame is currently executing.Refer to
locals()
for details of the mapping returned at different scopes.As this function returns a borrowed reference, the dictionary returned for optimized scopes is cached on the frame object and will remain alive as long as the frame object does. Unlike
PyEval_GetFrameLocals()
andlocals()
, subsequent calls to this function in the same frame will update the contents of the cached dictionary to reflect changes in the state of the local variables rather than returning a new snapshot.Changed in version 3.13: As part of PEP 667,
PyFrame_GetLocals()
,locals()
, andFrameType.f_locals
no longer make use of the shared cache dictionary. Refer to the What’s New entry for additional details.
-
PyObject *PyEval_GetGlobals(void)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Deprecated since version 3.13: Use
PyEval_GetFrameGlobals()
instead.Return a dictionary of the global variables in the current execution frame, or
NULL
if no frame is currently executing.
-
PyFrameObject *PyEval_GetFrame(void)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Return the attached thread state’s frame, which is
NULL
if no frame is currently executing.See also
PyThreadState_GetFrame()
.
-
PyObject *PyEval_GetFrameBuiltins(void)¶
- Return value: New reference. Part of the Stable ABI since version 3.13.
Return a dictionary of the builtins in the current execution frame, or the interpreter of the thread state if no frame is currently executing.
Added in version 3.13.
-
PyObject *PyEval_GetFrameLocals(void)¶
- Return value: New reference. Part of the Stable ABI since version 3.13.
Return a dictionary of the local variables in the current execution frame, or
NULL
if no frame is currently executing. Equivalent to callinglocals()
in Python code.To access
f_locals
on the current frame without making an independent snapshot in optimized scopes, callPyFrame_GetLocals()
on the result ofPyEval_GetFrame()
.Added in version 3.13.
-
PyObject *PyEval_GetFrameGlobals(void)¶
- Return value: New reference. Part of the Stable ABI since version 3.13.
Return a dictionary of the global variables in the current execution frame, or
NULL
if no frame is currently executing. Equivalent to callingglobals()
in Python code.Added in version 3.13.
-
const char *PyEval_GetFuncName(PyObject *func)¶
- Part of the Stable ABI.
Return the name of func if it is a function, class or instance object, else the name of funcs type.
-
const char *PyEval_GetFuncDesc(PyObject *func)¶
- Part of the Stable ABI.
Return a description string, depending on the type of func. Return values include “()” for functions and methods, “ constructor”, “ instance”, and “ object”. Concatenated with the result of
PyEval_GetFuncName()
, the result will be a description of func.


Frame Objects

Frame Objects¶
-
type PyFrameObject¶
- Part of the Limited API (as an opaque struct).
The C structure of the objects used to describe frame objects.
There are no public members in this structure.
Changed in version 3.11: The members of this structure were removed from the public C API. Refer to the What’s New entry for details.
The PyEval_GetFrame()
and PyThreadState_GetFrame()
functions
can be used to get a frame object.
See also Reflection.
-
PyTypeObject PyFrame_Type¶
The type of frame objects. It is the same object as
types.FrameType
in the Python layer.Changed in version 3.11: Previously, this type was only available after including
<frameobject.h>
.
-
PyFrameObject *PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals, PyObject *locals)¶
Create a new frame object. This function returns a strong reference to the new frame object on success, and returns
NULL
with an exception set on failure.
-
int PyFrame_Check(PyObject *obj)¶
Return non-zero if obj is a frame object.
Changed in version 3.11: Previously, this function was only available after including
<frameobject.h>
.
-
PyFrameObject *PyFrame_GetBack(PyFrameObject *frame)¶
- Return value: New reference.
Get the frame next outer frame.
Return a strong reference, or
NULL
if frame has no outer frame.Added in version 3.9.
-
PyObject *PyFrame_GetBuiltins(PyFrameObject *frame)¶
- Return value: New reference.
Get the frame’s
f_builtins
attribute.Return a strong reference. The result cannot be
NULL
.Added in version 3.11.
-
PyCodeObject *PyFrame_GetCode(PyFrameObject *frame)¶
- Return value: New reference. Part of the Stable ABI since version 3.10.
Get the frame code.
Return a strong reference.
The result (frame code) cannot be
NULL
.Added in version 3.9.
-
PyObject *PyFrame_GetGenerator(PyFrameObject *frame)¶
- Return value: New reference.
Get the generator, coroutine, or async generator that owns this frame, or
NULL
if this frame is not owned by a generator. Does not raise an exception, even if the return value isNULL
.Return a strong reference, or
NULL
.Added in version 3.11.
-
PyObject *PyFrame_GetGlobals(PyFrameObject *frame)¶
- Return value: New reference.
Get the frame’s
f_globals
attribute.Return a strong reference. The result cannot be
NULL
.Added in version 3.11.
-
int PyFrame_GetLasti(PyFrameObject *frame)¶
Get the frame’s
f_lasti
attribute.Returns -1 if
frame.f_lasti
isNone
.Added in version 3.11.
-
PyObject *PyFrame_GetVar(PyFrameObject *frame, PyObject *name)¶
- Return value: New reference.
Get the variable name of frame.
Return a strong reference to the variable value on success.
Raise
NameError
and returnNULL
if the variable does not exist.Raise an exception and return
NULL
on error.
name type must be a
str
.Added in version 3.12.
-
PyObject *PyFrame_GetVarString(PyFrameObject *frame, const char *name)¶
- Return value: New reference.
Similar to
PyFrame_GetVar()
, but the variable name is a C string encoded in UTF-8.Added in version 3.12.
-
PyObject *PyFrame_GetLocals(PyFrameObject *frame)¶
- Return value: New reference.
Get the frame’s
f_locals
attribute. If the frame refers to an optimized scope, this returns a write-through proxy object that allows modifying the locals. In all other cases (classes, modules,exec()
,eval()
) it returns the mapping representing the frame locals directly (as described forlocals()
).Return a strong reference.
Added in version 3.11.
Changed in version 3.13: As part of PEP 667, return an instance of
PyFrameLocalsProxy_Type
.
-
int PyFrame_GetLineNumber(PyFrameObject *frame)¶
- Part of the Stable ABI since version 3.10.
Return the line number that frame is currently executing.
Frame Locals Proxies¶
Added in version 3.13.
The f_locals
attribute on a frame object
is an instance of a “frame-locals proxy”. The proxy object exposes a
write-through view of the underlying locals dictionary for the frame. This
ensures that the variables exposed by f_locals
are always up to date with
the live local variables in the frame itself.
See PEP 667 for more information.
-
PyTypeObject PyFrameLocalsProxy_Type¶
The type of frame
locals()
proxy objects.
Legacy Local Variable APIs¶
These APIs are soft deprecated. As of Python 3.13, they do nothing. They exist solely for backwards compatibility.
-
void PyFrame_LocalsToFast(PyFrameObject *f, int clear)¶
This function is soft deprecated and does nothing.
Prior to Python 3.13, this function would copy the
f_locals
attribute of f to the internal “fast” array of local variables, allowing changes in frame objects to be visible to the interpreter. If clear was true, this function would process variables that were unset in the locals dictionary.Changed in version 3.13: This function now does nothing.
-
void PyFrame_FastToLocals(PyFrameObject *f)¶
This function is soft deprecated and does nothing.
Prior to Python 3.13, this function would copy the internal “fast” array of local variables (which is used by the interpreter) to the
f_locals
attribute of f, allowing changes in local variables to be visible to frame objects.Changed in version 3.13: This function now does nothing.
-
int PyFrame_FastToLocalsWithError(PyFrameObject *f)¶
This function is soft deprecated and does nothing.
Prior to Python 3.13, this function was similar to
PyFrame_FastToLocals()
, but would return0
on success, and-1
with an exception set on failure.Changed in version 3.13: This function now does nothing.
See also
Internal Frames¶
Unless using PEP 523, you will not need this.
-
struct _PyInterpreterFrame¶
The interpreter’s internal frame representation.
Added in version 3.11.
-
PyObject *PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);¶
- This is Unstable API. It may change without warning in minor releases.
Return a strong reference to the code object for the frame.
Added in version 3.12.
-
int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);¶
- This is Unstable API. It may change without warning in minor releases.
Return the byte offset into the last executed instruction.
Added in version 3.12.
-
int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);¶
- This is Unstable API. It may change without warning in minor releases.
Return the currently executing line number, or -1 if there is no line number.
Added in version 3.12.


Operating System Utilities

Operating System Utilities¶
-
PyObject *PyOS_FSPath(PyObject *path)¶
- Return value: New reference. Part of the Stable ABI since version 3.6.
Return the file system representation for path. If the object is a
str
orbytes
object, then a new strong reference is returned. If the object implements theos.PathLike
interface, then__fspath__()
is returned as long as it is astr
orbytes
object. OtherwiseTypeError
is raised andNULL
is returned.Added in version 3.6.
-
int Py_FdIsInteractive(FILE *fp, const char *filename)¶
Return true (nonzero) if the standard I/O file fp with name filename is deemed interactive. This is the case for files for which
isatty(fileno(fp))
is true. If thePyConfig.interactive
is non-zero, this function also returns true if the filename pointer isNULL
or if the name is equal to one of the strings'<stdin>'
or'???'
.This function must not be called before Python is initialized.
-
void PyOS_BeforeFork()¶
- Part of the Stable ABI on platforms with fork() since version 3.7.
Function to prepare some internal state before a process fork. This should be called before calling
fork()
or any similar function that clones the current process. Only available on systems wherefork()
is defined.Warning
The C
fork()
call should only be made from the “main” thread (of the “main” interpreter). The same is true forPyOS_BeforeFork()
.Added in version 3.7.
-
void PyOS_AfterFork_Parent()¶
- Part of the Stable ABI on platforms with fork() since version 3.7.
Function to update some internal state after a process fork. This should be called from the parent process after calling
fork()
or any similar function that clones the current process, regardless of whether process cloning was successful. Only available on systems wherefork()
is defined.Warning
The C
fork()
call should only be made from the “main” thread (of the “main” interpreter). The same is true forPyOS_AfterFork_Parent()
.Added in version 3.7.
-
void PyOS_AfterFork_Child()¶
- Part of the Stable ABI on platforms with fork() since version 3.7.
Function to update internal interpreter state after a process fork. This must be called from the child process after calling
fork()
, or any similar function that clones the current process, if there is any chance the process will call back into the Python interpreter. Only available on systems wherefork()
is defined.Warning
The C
fork()
call should only be made from the “main” thread (of the “main” interpreter). The same is true forPyOS_AfterFork_Child()
.Added in version 3.7.
See also
os.register_at_fork()
allows registering custom Python functions to be called byPyOS_BeforeFork()
,PyOS_AfterFork_Parent()
andPyOS_AfterFork_Child()
.
-
void PyOS_AfterFork()¶
- Part of the Stable ABI on platforms with fork().
Function to update some internal state after a process fork; this should be called in the new process if the Python interpreter will continue to be used. If a new executable is loaded into the new process, this function does not need to be called.
Deprecated since version 3.7: This function is superseded by
PyOS_AfterFork_Child()
.
-
int PyOS_CheckStack()¶
- Part of the Stable ABI on platforms with USE_STACKCHECK since version 3.7.
Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when
USE_STACKCHECK
is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler).USE_STACKCHECK
will be defined automatically; you should never change the definition in your own code.
-
typedef void (*PyOS_sighandler_t)(int)¶
- Part of the Stable ABI.
-
PyOS_sighandler_t PyOS_getsig(int i)¶
- Part of the Stable ABI.
Return the current signal handler for signal i. This is a thin wrapper around either
sigaction()
orsignal()
. Do not call those functions directly!
-
PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)¶
- Part of the Stable ABI.
Set the signal handler for signal i to be h; return the old signal handler. This is a thin wrapper around either
sigaction()
orsignal()
. Do not call those functions directly!
-
int PyOS_InterruptOccurred(void)¶
- Part of the Stable ABI.
Check if a
SIGINT
signal has been received.Returns
1
if aSIGINT
has occurred and clears the signal flag, or0
otherwise.In most cases, you should prefer
PyErr_CheckSignals()
over this function.PyErr_CheckSignals()
invokes the appropriate signal handlers for all pending signals, allowing Python code to handle the signal properly. This function only detectsSIGINT
and does not invoke any Python signal handlers.This function is async-signal-safe and this function cannot fail. The caller must hold an attached thread state.
-
wchar_t *Py_DecodeLocale(const char *arg, size_t *size)¶
- Part of the Stable ABI since version 3.7.
Warning
This function should not be called directly: use the
PyConfig
API with thePyConfig_SetBytesString()
function which ensures that Python is preinitialized.This function must not be called before Python is preinitialized and so that the LC_CTYPE locale is properly configured: see the
Py_PreInitialize()
function.Decode a byte string from the filesystem encoding and error handler. If the error handler is surrogateescape error handler, undecodable bytes are decoded as characters in range U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate character, the bytes are escaped using the surrogateescape error handler instead of decoding them.
Return a pointer to a newly allocated wide character string, use
PyMem_RawFree()
to free the memory. If size is notNULL
, write the number of wide characters excluding the null character into*size
Return
NULL
on decoding error or memory allocation error. If size is notNULL
,*size
is set to(size_t)-1
on memory error or set to(size_t)-2
on decoding error.The filesystem encoding and error handler are selected by
PyConfig_Read()
: seefilesystem_encoding
andfilesystem_errors
members ofPyConfig
.Decoding errors should never happen, unless there is a bug in the C library.
Use the
Py_EncodeLocale()
function to encode the character string back to a byte string.See also
The
PyUnicode_DecodeFSDefaultAndSize()
andPyUnicode_DecodeLocaleAndSize()
functions.Added in version 3.5.
Changed in version 3.7: The function now uses the UTF-8 encoding in the Python UTF-8 Mode.
Changed in version 3.8: The function now uses the UTF-8 encoding on Windows if
PyPreConfig.legacy_windows_fs_encoding
is zero;
-
char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)¶
- Part of the Stable ABI since version 3.7.
Encode a wide character string to the filesystem encoding and error handler. If the error handler is surrogateescape error handler, surrogate characters in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.
Return a pointer to a newly allocated byte string, use
PyMem_Free()
to free the memory. ReturnNULL
on encoding error or memory allocation error.If error_pos is not
NULL
,*error_pos
is set to(size_t)-1
on success, or set to the index of the invalid character on encoding error.The filesystem encoding and error handler are selected by
PyConfig_Read()
: seefilesystem_encoding
andfilesystem_errors
members ofPyConfig
.Use the
Py_DecodeLocale()
function to decode the bytes string back to a wide character string.Warning
This function must not be called before Python is preinitialized and so that the LC_CTYPE locale is properly configured: see the
Py_PreInitialize()
function.See also
The
PyUnicode_EncodeFSDefault()
andPyUnicode_EncodeLocale()
functions.Added in version 3.5.
Changed in version 3.7: The function now uses the UTF-8 encoding in the Python UTF-8 Mode.
Changed in version 3.8: The function now uses the UTF-8 encoding on Windows if
PyPreConfig.legacy_windows_fs_encoding
is zero.
-
FILE *Py_fopen(PyObject *path, const char *mode)¶
Similar to
fopen()
, but path is a Python object and an exception is set on error.path must be a
str
object, abytes
object, or a path-like object.On success, return the new file pointer. On error, set an exception and return
NULL
.The file must be closed by
Py_fclose()
rather than calling directlyfclose()
.The file descriptor is created non-inheritable (PEP 446).
The caller must have an attached thread state.
Added in version 3.14.
-
int Py_fclose(FILE *file)¶
Close a file that was opened by
Py_fopen()
.On success, return
0
. On error, returnEOF
anderrno
is set to indicate the error. In either case, any further access (including another call toPy_fclose()
) to the stream results in undefined behavior.Added in version 3.14.
System Functions¶
These are utility functions that make functionality from the sys
module
accessible to C code. They all work with the current interpreter thread’s
sys
module’s dict, which is contained in the internal thread state structure.
-
PyObject *PySys_GetObject(const char *name)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Return the object name from the
sys
module orNULL
if it does not exist, without setting an exception.
-
int PySys_SetObject(const char *name, PyObject *v)¶
- Part of the Stable ABI.
Set name in the
sys
module to v unless v isNULL
, in which case name is deleted from the sys module. Returns0
on success,-1
on error.
-
void PySys_ResetWarnOptions()¶
- Part of the Stable ABI.
Reset
sys.warnoptions
to an empty list. This function may be called prior toPy_Initialize()
.Deprecated since version 3.13, will be removed in version 3.15: Clear
sys.warnoptions
andwarnings.filters
instead.
-
void PySys_WriteStdout(const char *format, ...)¶
- Part of the Stable ABI.
Write the output string described by format to
sys.stdout
. No exceptions are raised, even if truncation occurs (see below).format should limit the total size of the formatted output string to 1000 bytes or less – after 1000 bytes, the output string is truncated. In particular, this means that no unrestricted “%s” formats should occur; these should be limited using “%.<N>s” where <N> is a decimal number calculated so that <N> plus the maximum size of other formatted text does not exceed 1000 bytes. Also watch out for “%f”, which can print hundreds of digits for very large numbers.
If a problem occurs, or
sys.stdout
is unset, the formatted message is written to the real (C level) stdout.
-
void PySys_WriteStderr(const char *format, ...)¶
- Part of the Stable ABI.
As
PySys_WriteStdout()
, but write tosys.stderr
or stderr instead.
-
void PySys_FormatStdout(const char *format, ...)¶
- Part of the Stable ABI.
Function similar to PySys_WriteStdout() but format the message using
PyUnicode_FromFormatV()
and don’t truncate the message to an arbitrary length.Added in version 3.2.
-
void PySys_FormatStderr(const char *format, ...)¶
- Part of the Stable ABI.
As
PySys_FormatStdout()
, but write tosys.stderr
or stderr instead.Added in version 3.2.
-
PyObject *PySys_GetXOptions()¶
- Return value: Borrowed reference. Part of the Stable ABI since version 3.7.
Return the current dictionary of
-X
options, similarly tosys._xoptions
. On error,NULL
is returned and an exception is set.Added in version 3.2.
-
int PySys_Audit(const char *event, const char *format, ...)¶
- Part of the Stable ABI since version 3.13.
Raise an auditing event with any active hooks. Return zero for success and non-zero with an exception set on failure.
The event string argument must not be NULL.
If any hooks have been added, format and other arguments will be used to construct a tuple to pass. Apart from
N
, the same format characters as used inPy_BuildValue()
are available. If the built value is not a tuple, it will be added into a single-element tuple.The
N
format option must not be used. It consumes a reference, but since there is no way to know whether arguments to this function will be consumed, using it may cause reference leaks.Note that
#
format characters should always be treated asPy_ssize_t
, regardless of whetherPY_SSIZE_T_CLEAN
was defined.sys.audit()
performs the same function from Python code.See also
PySys_AuditTuple()
.Added in version 3.8.
Changed in version 3.8.2: Require
Py_ssize_t
for#
format characters. Previously, an unavoidable deprecation warning was raised.
-
int PySys_AuditTuple(const char *event, PyObject *args)¶
- Part of the Stable ABI since version 3.13.
Similar to
PySys_Audit()
, but pass arguments as a Python object. args must be atuple
. To pass no arguments, args can be NULL.Added in version 3.13.
-
int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)¶
Append the callable hook to the list of active auditing hooks. Return zero on success and non-zero on failure. If the runtime has been initialized, also set an error on failure. Hooks added through this API are called for all interpreters created by the runtime.
The userData pointer is passed into the hook function. Since hook functions may be called from different runtimes, this pointer should not refer directly to Python state.
This function is safe to call before
Py_Initialize()
. When called after runtime initialization, existing audit hooks are notified and may silently abort the operation by raising an error subclassed fromException
(other errors will not be silenced).The hook function is always called with an attached thread state by the Python interpreter that raised the event.
See PEP 578 for a detailed description of auditing. Functions in the runtime and standard library that raise events are listed in the audit events table. Details are in each function’s documentation.
If the interpreter is initialized, this function raises an auditing event
sys.addaudithook
with no arguments. If any existing hooks raise an exception derived fromException
, the new hook will not be added and the exception is cleared. As a result, callers cannot assume that their hook has been added unless they control all existing hooks.-
typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)¶
The type of the hook function. event is the C string event argument passed to
PySys_Audit()
orPySys_AuditTuple()
. args is guaranteed to be aPyTupleObject
. userData is the argument passed to PySys_AddAuditHook().
Added in version 3.8.
-
typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)¶
Process Control¶
-
void Py_FatalError(const char *message)¶
- Part of the Stable ABI.
Print a fatal error message and kill the process. No cleanup is performed. This function should only be invoked when a condition is detected that would make it dangerous to continue using the Python interpreter; e.g., when the object administration appears to be corrupted. On Unix, the standard C library function
abort()
is called which will attempt to produce acore
file.The
Py_FatalError()
function is replaced with a macro which logs automatically the name of the current function, unless thePy_LIMITED_API
macro is defined.Changed in version 3.9: Log the function name automatically.
-
void Py_Exit(int status)¶
- Part of the Stable ABI.
Exit the current process. This calls
Py_FinalizeEx()
and then calls the standard C library functionexit(status)
. IfPy_FinalizeEx()
indicates an error, the exit status is set to 120.Changed in version 3.6: Errors from finalization no longer ignored.
-
int Py_AtExit(void (*func)())¶
- Part of the Stable ABI.
Register a cleanup function to be called by
Py_FinalizeEx()
. The cleanup function will be called with no arguments and should return no value. At most 32 cleanup functions can be registered. When the registration is successful,Py_AtExit()
returns0
; on failure, it returns-1
. The cleanup function registered last is called first. Each cleanup function will be called at most once. Since Python’s internal finalization will have completed before the cleanup function, no Python APIs should be called by func.See also
PyUnstable_AtExit()
for passing avoid *data
argument.


Importing Modules

Importing Modules¶
-
PyObject *PyImport_ImportModule(const char *name)¶
- Return value: New reference. Part of the Stable ABI.
This is a wrapper around
PyImport_Import()
which takes a const char* as an argument instead of a PyObject*.
-
PyObject *PyImport_ImportModuleNoBlock(const char *name)¶
- Return value: New reference. Part of the Stable ABI.
This function is a deprecated alias of
PyImport_ImportModule()
.Changed in version 3.3: This function used to fail immediately when the import lock was held by another thread. In Python 3.3 though, the locking scheme switched to per-module locks for most purposes, so this function’s special behaviour isn’t needed anymore.
Deprecated since version 3.13, will be removed in version 3.15: Use
PyImport_ImportModule()
instead.
-
PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)¶
- Return value: New reference.
Import a module. This is best described by referring to the built-in Python function
__import__()
.The return value is a new reference to the imported module or top-level package, or
NULL
with an exception set on failure. Like for__import__()
, the return value when a submodule of a package was requested is normally the top-level package, unless a non-empty fromlist was given.Failing imports remove incomplete module objects, like with
PyImport_ImportModule()
.
-
PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Import a module. This is best described by referring to the built-in Python function
__import__()
, as the standard__import__()
function calls this function directly.The return value is a new reference to the imported module or top-level package, or
NULL
with an exception set on failure. Like for__import__()
, the return value when a submodule of a package was requested is normally the top-level package, unless a non-empty fromlist was given.Added in version 3.3.
-
PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶
- Return value: New reference. Part of the Stable ABI.
Similar to
PyImport_ImportModuleLevelObject()
, but the name is a UTF-8 encoded string instead of a Unicode object.Changed in version 3.3: Negative values for level are no longer accepted.
-
PyObject *PyImport_Import(PyObject *name)¶
- Return value: New reference. Part of the Stable ABI.
This is a higher-level interface that calls the current “import hook function” (with an explicit level of 0, meaning absolute import). It invokes the
__import__()
function from the__builtins__
of the current globals. This means that the import is done using whatever import hooks are installed in the current environment.This function always uses absolute imports.
-
PyObject *PyImport_ReloadModule(PyObject *m)¶
- Return value: New reference. Part of the Stable ABI.
Reload a module. Return a new reference to the reloaded module, or
NULL
with an exception set on failure (the module still exists in this case).
-
PyObject *PyImport_AddModuleRef(const char *name)¶
- Return value: New reference. Part of the Stable ABI since version 3.13.
Return the module object corresponding to a module name.
The name argument may be of the form
package.module
. First check the modules dictionary if there’s one there, and if not, create a new one and insert it in the modules dictionary.Return a strong reference to the module on success. Return
NULL
with an exception set on failure.The module name name is decoded from UTF-8.
This function does not load or import the module; if the module wasn’t already loaded, you will get an empty module object. Use
PyImport_ImportModule()
or one of its variants to import a module. Package structures implied by a dotted name for name are not created if not already present.Added in version 3.13.
-
PyObject *PyImport_AddModuleObject(PyObject *name)¶
- Return value: Borrowed reference. Part of the Stable ABI since version 3.7.
Similar to
PyImport_AddModuleRef()
, but return a borrowed reference and name is a Pythonstr
object.Added in version 3.3.
-
PyObject *PyImport_AddModule(const char *name)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Similar to
PyImport_AddModuleRef()
, but return a borrowed reference.
-
PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)¶
- Return value: New reference. Part of the Stable ABI.
Given a module name (possibly of the form
package.module
) and a code object read from a Python bytecode file or obtained from the built-in functioncompile()
, load the module. Return a new reference to the module object, orNULL
with an exception set if an error occurred. name is removed fromsys.modules
in error cases, even if name was already insys.modules
on entry toPyImport_ExecCodeModule()
. Leaving incompletely initialized modules insys.modules
is dangerous, as imports of such modules have no way to know that the module object is an unknown (and probably damaged with respect to the module author’s intents) state.The module’s
__spec__
and__loader__
will be set, if not set already, with the appropriate values. The spec’s loader will be set to the module’s__loader__
(if set) and to an instance ofSourceFileLoader
otherwise.The module’s
__file__
attribute will be set to the code object’sco_filename
. If applicable,__cached__
will also be set.This function will reload the module if it was already imported. See
PyImport_ReloadModule()
for the intended way to reload a module.If name points to a dotted name of the form
package.module
, any package structures not already created will still not be created.See also
PyImport_ExecCodeModuleEx()
andPyImport_ExecCodeModuleWithPathnames()
.Changed in version 3.12: The setting of
__cached__
and__loader__
is deprecated. SeeModuleSpec
for alternatives.
-
PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)¶
- Return value: New reference. Part of the Stable ABI.
Like
PyImport_ExecCodeModule()
, but the__file__
attribute of the module object is set to pathname if it is non-NULL
.See also
PyImport_ExecCodeModuleWithPathnames()
.
-
PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)¶
- Return value: New reference. Part of the Stable ABI since version 3.7.
Like
PyImport_ExecCodeModuleEx()
, but the__cached__
attribute of the module object is set to cpathname if it is non-NULL
. Of the three functions, this is the preferred one to use.Added in version 3.3.
Changed in version 3.12: Setting
__cached__
is deprecated. SeeModuleSpec
for alternatives.
-
PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)¶
- Return value: New reference. Part of the Stable ABI.
Like
PyImport_ExecCodeModuleObject()
, but name, pathname and cpathname are UTF-8 encoded strings. Attempts are also made to figure out what the value for pathname should be from cpathname if the former is set toNULL
.Added in version 3.2.
Changed in version 3.3: Uses
imp.source_from_cache()
in calculating the source path if only the bytecode path is provided.Changed in version 3.12: No longer uses the removed
imp
module.
-
long PyImport_GetMagicNumber()¶
- Part of the Stable ABI.
Return the magic number for Python bytecode files (a.k.a.
.pyc
file). The magic number should be present in the first four bytes of the bytecode file, in little-endian byte order. Returns-1
on error.Changed in version 3.3: Return value of
-1
upon failure.
-
const char *PyImport_GetMagicTag()¶
- Part of the Stable ABI.
Return the magic tag string for PEP 3147 format Python bytecode file names. Keep in mind that the value at
sys.implementation.cache_tag
is authoritative and should be used instead of this function.Added in version 3.2.
-
PyObject *PyImport_GetModuleDict()¶
- Return value: Borrowed reference. Part of the Stable ABI.
Return the dictionary used for the module administration (a.k.a.
sys.modules
). Note that this is a per-interpreter variable.
-
PyObject *PyImport_GetModule(PyObject *name)¶
- Return value: New reference. Part of the Stable ABI since version 3.8.
Return the already imported module with the given name. If the module has not been imported yet then returns
NULL
but does not set an error. ReturnsNULL
and sets an error if the lookup failed.Added in version 3.7.
-
PyObject *PyImport_GetImporter(PyObject *path)¶
- Return value: New reference. Part of the Stable ABI.
Return a finder object for a
sys.path
/pkg.__path__
item path, possibly by fetching it from thesys.path_importer_cache
dict. If it wasn’t yet cached, traversesys.path_hooks
until a hook is found that can handle the path item. ReturnNone
if no hook could; this tells our caller that the path based finder could not find a finder for this path item. Cache the result insys.path_importer_cache
. Return a new reference to the finder object.
-
int PyImport_ImportFrozenModuleObject(PyObject *name)¶
- Part of the Stable ABI since version 3.7.
Load a frozen module named name. Return
1
for success,0
if the module is not found, and-1
with an exception set if the initialization failed. To access the imported module on a successful load, usePyImport_ImportModule()
. (Note the misnomer — this function would reload the module if it was already imported.)Added in version 3.3.
Changed in version 3.4: The
__file__
attribute is no longer set on the module.
-
int PyImport_ImportFrozenModule(const char *name)¶
- Part of the Stable ABI.
Similar to
PyImport_ImportFrozenModuleObject()
, but the name is a UTF-8 encoded string instead of a Unicode object.
-
struct _frozen¶
This is the structure type definition for frozen module descriptors, as generated by the freeze utility (see
Tools/freeze/
in the Python source distribution). Its definition, found inInclude/import.h
, is:struct _frozen { const char *name; const unsigned char *code; int size; bool is_package; };
Changed in version 3.11: The new
is_package
field indicates whether the module is a package or not. This replaces setting thesize
field to a negative value.
-
const struct _frozen *PyImport_FrozenModules¶
This pointer is initialized to point to an array of
_frozen
records, terminated by one whose members are allNULL
or zero. When a frozen module is imported, it is searched in this table. Third-party code could play tricks with this to provide a dynamically created collection of frozen modules.
-
int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))¶
- Part of the Stable ABI.
Add a single module to the existing table of built-in modules. This is a convenience wrapper around
PyImport_ExtendInittab()
, returning-1
if the table could not be extended. The new module can be imported by the name name, and uses the function initfunc as the initialization function called on the first attempted import. This should be called beforePy_Initialize()
.
-
struct _inittab¶
Structure describing a single entry in the list of built-in modules. Programs which embed Python may use an array of these structures in conjunction with
PyImport_ExtendInittab()
to provide additional built-in modules. The structure consists of two members:-
const char *name¶
The module name, as an ASCII encoded string.
-
const char *name¶
-
int PyImport_ExtendInittab(struct _inittab *newtab)¶
Add a collection of modules to the table of built-in modules. The newtab array must end with a sentinel entry which contains
NULL
for thename
field; failure to provide the sentinel value can result in a memory fault. Returns0
on success or-1
if insufficient memory could be allocated to extend the internal table. In the event of failure, no modules are added to the internal table. This must be called beforePy_Initialize()
.If Python is initialized multiple times,
PyImport_AppendInittab()
orPyImport_ExtendInittab()
must be called before each Python initialization.
-
struct _inittab *PyImport_Inittab¶
The table of built-in modules used by Python initialization. Do not use this directly; use
PyImport_AppendInittab()
andPyImport_ExtendInittab()
instead.
-
PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)¶
- Return value: New reference.
Import the module mod_name and get its attribute attr_name.
Names must be Python
str
objects.Helper function combining
PyImport_Import()
andPyObject_GetAttr()
. For example, it can raiseImportError
if the module is not found, andAttributeError
if the attribute doesn’t exist.Added in version 3.14.
-
PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)¶
- Return value: New reference.
Similar to
PyImport_ImportModuleAttr()
, but names are UTF-8 encoded strings instead of Pythonstr
objects.Added in version 3.14.


— Encode and decode XDR data

xdrlib
— Encode and decode XDR data¶
Deprecated since version 3.11, removed in version 3.13.
This module is no longer part of the Python standard library. It was removed in Python 3.13 after being deprecated in Python 3.11. The removal was decided in PEP 594.
The last version of Python that provided the xdrlib
module was
Python 3.12.


Iterator Protocol

Iterator Protocol¶
There are two functions specifically for working with iterators.
-
int PyIter_Check(PyObject *o)¶
- Part of the Stable ABI since version 3.8.
Return non-zero if the object o can be safely passed to
PyIter_NextItem()
and0
otherwise. This function always succeeds.
-
int PyAIter_Check(PyObject *o)¶
- Part of the Stable ABI since version 3.10.
Return non-zero if the object o provides the
AsyncIterator
protocol, and0
otherwise. This function always succeeds.Added in version 3.10.
-
int PyIter_NextItem(PyObject *iter, PyObject **item)¶
- Part of the Stable ABI since version 3.14.
Return
1
and set item to a strong reference of the next value of the iterator iter on success. Return0
and set item toNULL
if there are no remaining values. Return-1
, set item toNULL
and set an exception on error.Added in version 3.14.
-
PyObject *PyIter_Next(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
This is an older version of
PyIter_NextItem()
, which is retained for backwards compatibility. PreferPyIter_NextItem()
.Return the next value from the iterator o. The object must be an iterator according to
PyIter_Check()
(it is up to the caller to check this). If there are no remaining values, returnsNULL
with no exception set. If an error occurs while retrieving the item, returnsNULL
and passes along the exception.
-
type PySendResult¶
The enum value used to represent different results of
PyIter_Send()
.Added in version 3.10.
-
PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)¶
- Part of the Stable ABI since version 3.10.
Sends the arg value into the iterator iter. Returns:
PYGEN_RETURN
if iterator returns. Return value is returned via presult.PYGEN_NEXT
if iterator yields. Yielded value is returned via presult.PYGEN_ERROR
if iterator has raised and exception. presult is set toNULL
.
Added in version 3.10.


Weak Reference Objects

Weak Reference Objects¶
Python supports weak references as first-class objects. There are two specific object types which directly implement weak references. The first is a simple reference object, and the second acts as a proxy for the original object as much as it can.
-
int PyWeakref_Check(PyObject *ob)¶
Return non-zero if ob is either a reference or proxy object. This function always succeeds.
-
int PyWeakref_CheckRef(PyObject *ob)¶
Return non-zero if ob is a reference object or a subclass of the reference type. This function always succeeds.
-
int PyWeakref_CheckRefExact(PyObject *ob)¶
Return non-zero if ob is a reference object, but not a subclass of the reference type. This function always succeeds.
-
int PyWeakref_CheckProxy(PyObject *ob)¶
Return non-zero if ob is a proxy object. This function always succeeds.
-
PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)¶
- Return value: New reference. Part of the Stable ABI.
Return a weak reference object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be
None
orNULL
. If ob is not a weakly referenceable object, or if callback is not callable,None
, orNULL
, this will returnNULL
and raiseTypeError
.See also
PyType_SUPPORTS_WEAKREFS()
for checking if ob is weakly referenceable.
-
PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)¶
- Return value: New reference. Part of the Stable ABI.
Return a weak reference proxy object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing proxy object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be
None
orNULL
. If ob is not a weakly referenceable object, or if callback is not callable,None
, orNULL
, this will returnNULL
and raiseTypeError
.See also
PyType_SUPPORTS_WEAKREFS()
for checking if ob is weakly referenceable.
-
int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)¶
- Part of the Stable ABI since version 3.13.
Get a strong reference to the referenced object from a weak reference, ref, into *pobj.
On success, set *pobj to a new strong reference to the referenced object and return 1.
If the reference is dead, set *pobj to
NULL
and return 0.On error, raise an exception and return -1.
Added in version 3.13.
-
PyObject *PyWeakref_GetObject(PyObject *ref)¶
- Return value: Borrowed reference. Part of the Stable ABI.
Return a borrowed reference to the referenced object from a weak reference, ref. If the referent is no longer live, returns
Py_None
.Note
This function returns a borrowed reference to the referenced object. This means that you should always call
Py_INCREF()
on the object except when it cannot be destroyed before the last usage of the borrowed reference.Deprecated since version 3.13, will be removed in version 3.15: Use
PyWeakref_GetRef()
instead.
-
PyObject *PyWeakref_GET_OBJECT(PyObject *ref)¶
- Return value: Borrowed reference.
Similar to
PyWeakref_GetObject()
, but does no error checking.Deprecated since version 3.13, will be removed in version 3.15: Use
PyWeakref_GetRef()
instead.
-
int PyWeakref_IsDead(PyObject *ref)¶
Test if the weak reference ref is dead. Returns 1 if the reference is dead, 0 if it is alive, and -1 with an error set if ref is not a weak reference object.
Added in version 3.14.
-
void PyObject_ClearWeakRefs(PyObject *object)¶
- Part of the Stable ABI.
This function is called by the
tp_dealloc
handler to clear weak references.This iterates through the weak references for object and calls callbacks for those references which have one. It returns when all callbacks have been attempted.
-
void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object)¶
- This is Unstable API. It may change without warning in minor releases.
Clears the weakrefs for object without calling the callbacks.
This function is called by the
tp_dealloc
handler for types with finalizers (i.e.,__del__()
). The handler for those objects first callsPyObject_ClearWeakRefs()
to clear weakrefs and call their callbacks, then the finalizer, and finally this function to clear any weakrefs that may have been created by the finalizer.In most circumstances, it’s more appropriate to use
PyObject_ClearWeakRefs()
to clear weakrefs instead of this function.Added in version 3.13.


PyHash API

PyHash API¶
See also the PyTypeObject.tp_hash
member and Hashing of numeric types.
-
type Py_hash_t¶
Hash value type: signed integer.
Added in version 3.2.
-
type Py_uhash_t¶
Hash value type: unsigned integer.
Added in version 3.2.
-
Py_HASH_ALGORITHM¶
A numerical value indicating the algorithm for hashing of
str
,bytes
, andmemoryview
.The algorithm name is exposed by
sys.hash_info.algorithm
.Added in version 3.4.
-
Py_HASH_FNV¶
-
Py_HASH_SIPHASH24¶
-
Py_HASH_SIPHASH13¶
Numerical values to compare to
Py_HASH_ALGORITHM
to determine which algorithm is used for hashing. The hash algorithm can be configured via the configure--with-hash-algorithm
option.Added in version 3.4: Add
Py_HASH_FNV
andPy_HASH_SIPHASH24
.Added in version 3.11: Add
Py_HASH_SIPHASH13
.
-
Py_HASH_CUTOFF¶
Buffers of length in range
[1, Py_HASH_CUTOFF)
are hashed using DJBX33A instead of the algorithm described byPy_HASH_ALGORITHM
.A
Py_HASH_CUTOFF
of 0 disables the optimization.Py_HASH_CUTOFF
must be non-negative and less or equal than 7.
32-bit platforms should use a cutoff smaller than 64-bit platforms because it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms and 5 on 32-bit platforms should provide a decent safety margin.
This corresponds to the
sys.hash_info.cutoff
constant.Added in version 3.4.
-
PyHASH_MODULUS¶
The Mersenne prime
P = 2**n -1
, used for numeric hash scheme.This corresponds to the
sys.hash_info.modulus
constant.Added in version 3.13.
-
PyHASH_BITS¶
The exponent
n
ofP
inPyHASH_MODULUS
.Added in version 3.13.
-
PyHASH_MULTIPLIER¶
Prime multiplier used in string and various other hashes.
Added in version 3.13.
-
PyHASH_INF¶
The hash value returned for a positive infinity.
This corresponds to the
sys.hash_info.inf
constant.Added in version 3.13.
-
PyHASH_IMAG¶
The multiplier used for the imaginary part of a complex number.
This corresponds to the
sys.hash_info.imag
constant.Added in version 3.13.
-
type PyHash_FuncDef¶
Hash function definition used by
PyHash_GetFuncDef()
.-
Py_hash_t (*const hash)(const void*, Py_ssize_t)¶
Hash function.
-
const char *name¶
Hash function name (UTF-8 encoded string).
This corresponds to the
sys.hash_info.algorithm
constant.
-
const int hash_bits¶
Internal size of the hash value in bits.
This corresponds to the
sys.hash_info.hash_bits
constant.
-
const int seed_bits¶
Size of seed input in bits.
This corresponds to the
sys.hash_info.seed_bits
constant.
Added in version 3.4.
-
Py_hash_t (*const hash)(const void*, Py_ssize_t)¶
-
PyHash_FuncDef *PyHash_GetFuncDef(void)¶
Get the hash function definition.
See also
PEP 456 “Secure and interchangeable hash algorithm”.
Added in version 3.4.
-
Py_hash_t Py_HashPointer(const void *ptr)¶
Hash a pointer value: process the pointer value as an integer (cast it to
uintptr_t
internally). The pointer is not dereferenced.The function cannot fail: it cannot return
-1
.Added in version 3.13.
-
Py_hash_t Py_HashBuffer(const void *ptr, Py_ssize_t len)¶
Compute and return the hash value of a buffer of len bytes starting at address ptr. The hash is guaranteed to match that of
bytes
,memoryview
, and other built-in objects that implement the buffer protocol.Use this function to implement hashing for immutable objects whose
tp_richcompare
function compares to another object’s buffer.len must be greater than or equal to
0
.This function always succeeds.
Added in version 3.14.
-
Py_hash_t PyObject_GenericHash(PyObject *obj)¶
Generic hashing function that is meant to be put into a type object’s
tp_hash
slot. Its result only depends on the object’s identity.CPython implementation detail: In CPython, it is equivalent to
Py_HashPointer()
.Added in version 3.13.


C API Stability

C API Stability¶
Unless documented otherwise, Python’s C API is covered by the Backwards Compatibility Policy, PEP 387. Most changes to it are source-compatible (typically by only adding new API). Changing existing API or removing API is only done after a deprecation period or to fix serious issues.
CPython’s Application Binary Interface (ABI) is forward- and backwards-compatible across a minor release (if these are compiled the same way; see Platform Considerations below). So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa, but will need to be compiled separately for 3.9.x and 3.11.x.
There are two tiers of C API with different stability expectations:
Unstable API, may change in minor versions without a deprecation period. It is marked by the
PyUnstable
prefix in names.Limited API, is compatible across several minor releases. When
Py_LIMITED_API
is defined, only this subset is exposed fromPython.h
.
These are discussed in more detail below.
Names prefixed by an underscore, such as _Py_InternalState
,
are private API that can change without notice even in patch releases.
If you need to use this API, consider reaching out to
CPython developers
to discuss adding public API for your use case.
Unstable C API¶
Any API named with the PyUnstable
prefix exposes CPython implementation
details, and may change in every minor release (e.g. from 3.9 to 3.10) without
any deprecation warnings.
However, it will not change in a bugfix release (e.g. from 3.10.0 to 3.10.1).
It is generally intended for specialized, low-level tools like debuggers.
Projects that use this API are expected to follow CPython development and spend extra effort adjusting to changes.
Stable Application Binary Interface¶
For simplicity, this document talks about extensions, but the Limited API and Stable ABI work the same way for all uses of the API – for example, embedding Python.
Limited C API¶
Python 3.2 introduced the Limited API, a subset of Python’s C API. Extensions that only use the Limited API can be compiled once and be loaded on multiple versions of Python. Contents of the Limited API are listed below.
-
Py_LIMITED_API¶
Define this macro before including
Python.h
to opt in to only use the Limited API, and to select the Limited API version.Define
Py_LIMITED_API
to the value ofPY_VERSION_HEX
corresponding to the lowest Python version your extension supports. The extension will be ABI-compatible with all Python 3 releases from the specified one onward, and can use Limited API introduced up to that version.Rather than using the
PY_VERSION_HEX
macro directly, hardcode a minimum minor version (e.g.0x030A0000
for Python 3.10) for stability when compiling with future Python versions.You can also define
Py_LIMITED_API
to3
. This works the same as0x03020000
(Python 3.2, the version that introduced Limited API).
Stable ABI¶
To enable this, Python provides a Stable ABI: a set of symbols that will remain ABI-compatible across Python 3.x versions.
Note
The Stable ABI prevents ABI issues, like linker errors due to missing symbols or data corruption due to changes in structure layouts or function signatures. However, other changes in Python can change the behavior of extensions. See Python’s Backwards Compatibility Policy (PEP 387) for details.
The Stable ABI contains symbols exposed in the Limited API, but also other ones – for example, functions necessary to support older versions of the Limited API.
On Windows, extensions that use the Stable ABI should be linked against
python3.dll
rather than a version-specific library such as
python39.dll
.
On some platforms, Python will look for and load shared library files named
with the abi3
tag (e.g. mymodule.abi3.so
).
It does not check if such extensions conform to a Stable ABI.
The user (or their packaging tools) need to ensure that, for example,
extensions built with the 3.10+ Limited API are not installed for lower
versions of Python.
All functions in the Stable ABI are present as functions in Python’s shared library, not solely as macros. This makes them usable from languages that don’t use the C preprocessor.
Limited API Scope and Performance¶
The goal for the Limited API is to allow everything that is possible with the full C API, but possibly with a performance penalty.
For example, while PyList_GetItem()
is available, its “unsafe” macro
variant PyList_GET_ITEM()
is not.
The macro can be faster because it can rely on version-specific implementation
details of the list object.
Without Py_LIMITED_API
defined, some C API functions are inlined or
replaced by macros.
Defining Py_LIMITED_API
disables this inlining, allowing stability as
Python’s data structures are improved, but possibly reducing performance.
By leaving out the Py_LIMITED_API
definition, it is possible to compile
a Limited API extension with a version-specific ABI. This can improve
performance for that Python version, but will limit compatibility.
Compiling with Py_LIMITED_API
will then yield an extension that can be
distributed where a version-specific one is not available – for example,
for prereleases of an upcoming Python version.
Limited API Caveats¶
Note that compiling with Py_LIMITED_API
is not a complete guarantee that
code conforms to the Limited API or the Stable ABI. Py_LIMITED_API
only covers definitions, but an API also
includes other issues, such as expected semantics.
One issue that Py_LIMITED_API
does not guard against is calling a function
with arguments that are invalid in a lower Python version.
For example, consider a function that starts accepting NULL
for an
argument. In Python 3.9, NULL
now selects a default behavior, but in
Python 3.8, the argument will be used directly, causing a NULL
dereference
and crash. A similar argument works for fields of structs.
Another issue is that some struct fields are currently not hidden when
Py_LIMITED_API
is defined, even though they’re part of the Limited API.
For these reasons, we recommend testing an extension with all minor Python versions it supports, and preferably to build with the lowest such version.
We also recommend reviewing documentation of all used API to check
if it is explicitly part of the Limited API. Even with Py_LIMITED_API
defined, a few private declarations are exposed for technical reasons (or
even unintentionally, as bugs).
Also note that the Limited API is not necessarily stable: compiling with
Py_LIMITED_API
with Python 3.8 means that the extension will
run with Python 3.12, but it will not necessarily compile with Python 3.12.
In particular, parts of the Limited API may be deprecated and removed,
provided that the Stable ABI stays stable.
Platform Considerations¶
ABI stability depends not only on Python, but also on the compiler used, lower-level libraries and compiler options. For the purposes of the Stable ABI, these details define a “platform”. They usually depend on the OS type and processor architecture
It is the responsibility of each particular distributor of Python
to ensure that all Python versions on a particular platform are built
in a way that does not break the Stable ABI.
This is the case with Windows and macOS releases from python.org
and many
third-party distributors.
Contents of Limited API¶
Currently, the Limited API includes the following items:
PyErr_Display()
PyModuleDef_Base
PyModuleDef_Type
PyUnicode_AsDecodedObject()
PyUnicode_AsDecodedUnicode()
PyUnicode_AsEncodedObject()
PyUnicode_AsEncodedUnicode()
PyVarObject.ob_base
PyWeakReference
Py_FileSystemDefaultEncodeErrors
Py_FileSystemDefaultEncoding
Py_HasFileSystemDefaultEncoding
Py_UTF8Mode
Py_intptr_t
Py_uintptr_t
ssizessizeargfunc
ssizessizeobjargproc
symtable