Runners

Runners¶
Source code: Lib/asyncio/runners.py
This section outlines high-level asyncio primitives to run asyncio code.
They are built on top of an event loop with the aim to simplify async code usage for common wide-spread scenarios.
Running an asyncio Program¶
- asyncio.run(coro, *, debug=None, loop_factory=None)¶
Execute coro in an asyncio event loop and return the result.
The argument can be any awaitable object.
This function runs the awaitable, taking care of managing the asyncio event loop, finalizing asynchronous generators, and closing the executor.
This function cannot be called when another asyncio event loop is running in the same thread.
If debug is
True
, the event loop will be run in debug mode.False
disables debug mode explicitly.None
is used to respect the global Debug Mode settings.If loop_factory is not
None
, it is used to create a new event loop; otherwiseasyncio.new_event_loop()
is used. The loop is closed at the end. This function should be used as a main entry point for asyncio programs, and should ideally only be called once. It is recommended to use loop_factory to configure the event loop instead of policies. Passingasyncio.EventLoop
allows running asyncio without the policy system.The executor is given a timeout duration of 5 minutes to shutdown. If the executor hasn’t finished within that duration, a warning is emitted and the executor is closed.
Example:
async def main(): await asyncio.sleep(1) print('hello') asyncio.run(main())
Added in version 3.7.
Changed in version 3.9: Updated to use
loop.shutdown_default_executor()
.Changed in version 3.10: debug is
None
by default to respect the global debug mode settings.Changed in version 3.12: Added loop_factory parameter.
Changed in version 3.14: coro can be any awaitable object.
Note
The
asyncio
policy system is deprecated and will be removed in Python 3.16; from there on, an explicit loop_factory is needed to configure the event loop.
Runner context manager¶
- class asyncio.Runner(*, debug=None, loop_factory=None)¶
A context manager that simplifies multiple async function calls in the same context.
Sometimes several top-level async functions should be called in the same event loop and
contextvars.Context
.If debug is
True
, the event loop will be run in debug mode.False
disables debug mode explicitly.None
is used to respect the global Debug Mode settings.loop_factory could be used for overriding the loop creation. It is the responsibility of the loop_factory to set the created loop as the current one. By default
asyncio.new_event_loop()
is used and set as current event loop withasyncio.set_event_loop()
if loop_factory isNone
.Basically,
asyncio.run()
example can be rewritten with the runner usage:async def main(): await asyncio.sleep(1) print('hello') with asyncio.Runner() as runner: runner.run(main())
Added in version 3.11.
- run(coro, *, context=None)¶
Execute coro in the embedded event loop.
The argument can be any awaitable object.
If the argument is a coroutine, it is wrapped in a Task.
An optional keyword-only context argument allows specifying a custom
contextvars.Context
for the code to run in. The runner’s default context is used if context isNone
.Returns the awaitable’s result or raises an exception.
This function cannot be called when another asyncio event loop is running in the same thread.
Changed in version 3.14: coro can be any awaitable object.
- close()¶
Close the runner.
Finalize asynchronous generators, shutdown default executor, close the event loop and release embedded
contextvars.Context
.
- get_loop()¶
Return the event loop associated with the runner instance.
Note
Runner
uses the lazy initialization strategy, its constructor doesn’t initialize underlying low-level structures.Embedded loop and context are created at the
with
body entering or the first call ofrun()
orget_loop()
.
Handling Keyboard Interruption¶
Added in version 3.11.
When signal.SIGINT
is raised by Ctrl-C, KeyboardInterrupt
exception is raised in the main thread by default. However this doesn’t work with
asyncio
because it can interrupt asyncio internals and can hang the program from
exiting.
To mitigate this issue, asyncio
handles signal.SIGINT
as follows:
asyncio.Runner.run()
installs a customsignal.SIGINT
handler before any user code is executed and removes it when exiting from the function.The
Runner
creates the main task for the passed coroutine for its execution.When
signal.SIGINT
is raised by Ctrl-C, the custom signal handler cancels the main task by callingasyncio.Task.cancel()
which raisesasyncio.CancelledError
inside the main task. This causes the Python stack to unwind,try/except
andtry/finally
blocks can be used for resource cleanup. After the main task is cancelled,asyncio.Runner.run()
raisesKeyboardInterrupt
.A user could write a tight loop which cannot be interrupted by
asyncio.Task.cancel()
, in which case the second following Ctrl-C immediately raises theKeyboardInterrupt
without cancelling the main task.


File Objects

File Objects¶
These APIs are a minimal emulation of the Python 2 C API for built-in file
objects, which used to rely on the buffered I/O (FILE*) support
from the C standard library. In Python 3, files and streams use the new
io
module, which defines several layers over the low-level unbuffered
I/O of the operating system. The functions described below are
convenience C wrappers over these new APIs, and meant mostly for internal
error reporting in the interpreter; third-party code is advised to access
the io
APIs instead.
-
PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)¶
- Return value: New reference. Part of the Stable ABI.
Create a Python file object from the file descriptor of an already opened file fd. The arguments name, encoding, errors and newline can be
NULL
to use the defaults; buffering can be -1 to use the default. name is ignored and kept for backward compatibility. ReturnNULL
on failure. For a more comprehensive description of the arguments, please refer to theio.open()
function documentation.Warning
Since Python streams have their own buffering layer, mixing them with OS-level file descriptors can produce various issues (such as unexpected ordering of data).
Changed in version 3.2: Ignore name attribute.
-
int PyObject_AsFileDescriptor(PyObject *p)¶
- Part of the Stable ABI.
Return the file descriptor associated with p as an int. If the object is an integer, its value is returned. If not, the object’s
fileno()
method is called if it exists; the method must return an integer, which is returned as the file descriptor value. Sets an exception and returns-1
on failure.
-
PyObject *PyFile_GetLine(PyObject *p, int n)¶
- Return value: New reference. Part of the Stable ABI.
Equivalent to
p.readline([n])
, this function reads one line from the object p. p may be a file object or any object with areadline()
method. If n is0
, exactly one line is read, regardless of the length of the line. If n is greater than0
, no more than n bytes will be read from the file; a partial line can be returned. In both cases, an empty string is returned if the end of the file is reached immediately. If n is less than0
, however, one line is read regardless of length, butEOFError
is raised if the end of the file is reached immediately.
-
int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)¶
Overrides the normal behavior of
io.open_code()
to pass its parameter through the provided handler.The handler is a function of type:
-
typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)¶
Equivalent of PyObject *(*)(PyObject *path, void *userData), where path is guaranteed to be
PyUnicodeObject
.
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.
As this hook is intentionally used during import, avoid importing new modules during its execution unless they are known to be frozen or available in
sys.modules
.Once a hook has been set, it cannot be removed or replaced, and later calls to
PyFile_SetOpenCodeHook()
will fail. On failure, the function returns -1 and sets an exception if the interpreter has been initialized.This function is safe to call before
Py_Initialize()
.Raises an auditing event
setopencodehook
with no arguments.Added in version 3.8.
-
typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)¶
-
PyObject *PyFile_OpenCodeObject(PyObject *path)¶
Open path with the mode
'rb'
. path must be a Pythonstr
object. The behavior of this function may be overridden byPyFile_SetOpenCodeHook()
to allow for some preprocessing of the text.This is analogous to
io.open_code()
in Python.On success, this function returns a strong reference to a Python file object. On failure, this function returns
NULL
with an exception set.Added in version 3.8.
-
PyObject *PyFile_OpenCode(const char *path)¶
Similar to
PyFile_OpenCodeObject()
, but path is a UTF-8 encoded const char*.Added in version 3.8.
-
int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)¶
- Part of the Stable ABI.
Write object obj to file object p. The only supported flag for flags is
Py_PRINT_RAW
; if given, thestr()
of the object is written instead of therepr()
. Return0
on success or-1
on failure; the appropriate exception will be set.
-
int PyFile_WriteString(const char *s, PyObject *p)¶
- Part of the Stable ABI.
Write string s to file object p. Return
0
on success or-1
on failure; the appropriate exception will be set.
Deprecated API¶
These are soft deprecated APIs that were included in Python’s C API
by mistake. They are documented solely for completeness; use other
PyFile*
APIs instead.
-
PyObject *PyFile_NewStdPrinter(int fd)¶
Use
PyFile_FromFd()
with defaults (fd, NULL, "w", -1, NULL, NULL, NULL, 0
) instead.
-
PyTypeObject PyStdPrinter_Type¶
Type of file-like objects used internally at Python startup when
io
is not yet available. Use Pythonopen()
orPyFile_FromFd()
to create file objects instead.


Code Objects

Code Objects¶
Code objects are a low-level detail of the CPython implementation. Each one represents a chunk of executable code that hasn’t yet been bound into a function.
-
type PyCodeObject¶
The C structure of the objects used to describe code objects. The fields of this type are subject to change at any time.
-
PyTypeObject PyCode_Type¶
This is an instance of
PyTypeObject
representing the Python code object.
-
int PyCode_Check(PyObject *co)¶
Return true if co is a code object. This function always succeeds.
-
Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)¶
Return the number of free (closure) variables in a code object.
-
int PyUnstable_Code_GetFirstFree(PyCodeObject *co)¶
- This is Unstable API. It may change without warning in minor releases.
Return the position of the first free (closure) variable in a code object.
Changed in version 3.13: Renamed from
PyCode_GetFirstFree
as part of Unstable C API. The old name is deprecated, but will remain available until the signature changes again.
-
PyCodeObject *PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)¶
- This is Unstable API. It may change without warning in minor releases.
Return a new code object. If you need a dummy code object to create a frame, use
PyCode_NewEmpty()
instead.Since the definition of the bytecode changes often, calling
PyUnstable_Code_New()
directly can bind you to a precise Python version.The many arguments of this function are inter-dependent in complex ways, meaning that subtle changes to values are likely to result in incorrect execution or VM crashes. Use this function only with extreme care.
Changed in version 3.11: Added
qualname
andexceptiontable
parameters.Changed in version 3.12: Renamed from
PyCode_New
as part of Unstable C API. The old name is deprecated, but will remain available until the signature changes again.
-
PyCodeObject *PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)¶
- This is Unstable API. It may change without warning in minor releases.
Similar to
PyUnstable_Code_New()
, but with an extra “posonlyargcount” for positional-only arguments. The same caveats that apply toPyUnstable_Code_New
also apply to this function.Added in version 3.8: as
PyCode_NewWithPosOnlyArgs
Changed in version 3.11: Added
qualname
andexceptiontable
parameters.Changed in version 3.12: Renamed to
PyUnstable_Code_NewWithPosOnlyArgs
. The old name is deprecated, but will remain available until the signature changes again.
-
PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)¶
- Return value: New reference.
Return a new empty code object with the specified filename, function name, and first line number. The resulting code object will raise an
Exception
if executed.
-
int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)¶
Return the line number of the instruction that occurs on or before
byte_offset
and ends after it. If you just need the line number of a frame, usePyFrame_GetLineNumber()
instead.For efficiently iterating over the line numbers in a code object, use the API described in PEP 626.
-
int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)¶
Sets the passed
int
pointers to the source code line and column numbers for the instruction atbyte_offset
. Sets the value to0
when information is not available for any particular element.Returns
1
if the function succeeds and 0 otherwise.Added in version 3.11.
-
PyObject *PyCode_GetCode(PyCodeObject *co)¶
Equivalent to the Python code
getattr(co, 'co_code')
. Returns a strong reference to aPyBytesObject
representing the bytecode in a code object. On error,NULL
is returned and an exception is raised.This
PyBytesObject
may be created on-demand by the interpreter and does not necessarily represent the bytecode actually executed by CPython. The primary use case for this function is debuggers and profilers.Added in version 3.11.
-
PyObject *PyCode_GetVarnames(PyCodeObject *co)¶
Equivalent to the Python code
getattr(co, 'co_varnames')
. Returns a new reference to aPyTupleObject
containing the names of the local variables. On error,NULL
is returned and an exception is raised.Added in version 3.11.
-
PyObject *PyCode_GetCellvars(PyCodeObject *co)¶
Equivalent to the Python code
getattr(co, 'co_cellvars')
. Returns a new reference to aPyTupleObject
containing the names of the local variables that are referenced by nested functions. On error,NULL
is returned and an exception is raised.Added in version 3.11.
-
PyObject *PyCode_GetFreevars(PyCodeObject *co)¶
Equivalent to the Python code
getattr(co, 'co_freevars')
. Returns a new reference to aPyTupleObject
containing the names of the free (closure) variables. On error,NULL
is returned and an exception is raised.Added in version 3.11.
-
int PyCode_AddWatcher(PyCode_WatchCallback callback)¶
Register callback as a code object watcher for the current interpreter. Return an ID which may be passed to
PyCode_ClearWatcher()
. In case of error (e.g. no more watcher IDs available), return-1
and set an exception.Added in version 3.12.
-
int PyCode_ClearWatcher(int watcher_id)¶
Clear watcher identified by watcher_id previously returned from
PyCode_AddWatcher()
for the current interpreter. Return0
on success, or-1
and set an exception on error (e.g. if the given watcher_id was never registered.)Added in version 3.12.
-
type PyCodeEvent¶
Enumeration of possible code object watcher events: -
PY_CODE_EVENT_CREATE
-PY_CODE_EVENT_DESTROY
Added in version 3.12.
-
typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)¶
Type of a code object watcher callback function.
If event is
PY_CODE_EVENT_CREATE
, then the callback is invoked after co has been fully initialized. Otherwise, the callback is invoked before the destruction of co takes place, so the prior state of co can be inspected.If event is
PY_CODE_EVENT_DESTROY
, taking a reference in the callback to the about-to-be-destroyed code object will resurrect it and prevent it from being freed at this time. When the resurrected object is destroyed later, any watcher callbacks active at that time will be called again.Users of this API should not rely on internal runtime implementation details. Such details may include, but are not limited to, the exact order and timing of creation and destruction of code objects. While changes in these details may result in differences observable by watchers (including whether a callback is invoked or not), it does not change the semantics of the Python code being executed.
If the callback sets an exception, it must return
-1
; this exception will be printed as an unraisable exception usingPyErr_WriteUnraisable()
. Otherwise it should return0
.There may already be a pending exception set on entry to the callback. In this case, the callback should return
0
with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.Added in version 3.12.
Code Object Flags¶
Code objects contain a bit-field of flags, which can be retrieved as the
co_flags
Python attribute (for example using
PyObject_GetAttrString()
), and set using a flags argument to
PyUnstable_Code_New()
and similar functions.
Flags whose names start with CO_FUTURE_
correspond to features normally
selectable by future statements. These flags can be used in
PyCompilerFlags.cf_flags
.
Note that many CO_FUTURE_
flags are mandatory in current versions of
Python, and setting them has no effect.
The following flags are available. For their meaning, see the linked documentation of their Python equivalents.
Flag |
Meaning |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
no effect ( |
|
no effect ( |
|
no effect ( |
|
no effect ( |
|
no effect ( |
|
no effect ( |
|
Extra information¶
To support low-level extensions to frame evaluation, such as external just-in-time compilers, it is possible to attach arbitrary extra data to code objects.
These functions are part of the unstable C API tier: this functionality is a CPython implementation detail, and the API may change without deprecation warnings.
-
Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)¶
- This is Unstable API. It may change without warning in minor releases.
Return a new opaque index value used to adding data to code objects.
You generally call this function once (per interpreter) and use the result with
PyCode_GetExtra
andPyCode_SetExtra
to manipulate data on individual code objects.If free is not
NULL
: when a code object is deallocated, free will be called on non-NULL
data stored under the new index. UsePy_DecRef()
when storingPyObject
.Added in version 3.6: as
_PyEval_RequestCodeExtraIndex
Changed in version 3.12: Renamed to
PyUnstable_Eval_RequestCodeExtraIndex
. The old private name is deprecated, but will be available until the API changes.
-
int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)¶
- This is Unstable API. It may change without warning in minor releases.
Set extra to the extra data stored under the given index. Return 0 on success. Set an exception and return -1 on failure.
If no data was set under the index, set extra to
NULL
and return 0 without setting an exception.Added in version 3.6: as
_PyCode_GetExtra
Changed in version 3.12: Renamed to
PyUnstable_Code_GetExtra
. The old private name is deprecated, but will be available until the API changes.
-
int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)¶
- This is Unstable API. It may change without warning in minor releases.
Set the extra data stored under the given index to extra. Return 0 on success. Set an exception and return -1 on failure.
Added in version 3.6: as
_PyCode_SetExtra
Changed in version 3.12: Renamed to
PyUnstable_Code_SetExtra
. The old private name is deprecated, but will be available until the API changes.


High-level API Index

High-level API Index¶
This page lists all high-level async/await enabled asyncio APIs.
Tasks¶
Utilities to run asyncio programs, create Tasks, and await on multiple things with timeouts.
Create event loop, run a coroutine, close the loop. |
|
A context manager that simplifies multiple async function calls. |
|
Task object. |
|
A context manager that holds a group of tasks. Provides a convenient and reliable way to wait for all tasks in the group to finish. |
|
Start an asyncio Task, then returns it. |
|
Return the current Task. |
|
Return all tasks that are not yet finished for an event loop. |
|
|
Sleep for a number of seconds. |
|
Schedule and wait for things concurrently. |
|
Run with a timeout. |
|
Shield from cancellation. |
|
Monitor for completion. |
Run with a timeout. Useful in cases when |
|
Asynchronously run a function in a separate OS thread. |
|
Schedule a coroutine from another OS thread. |
|
|
Monitor for completion with a |
Examples
Queues¶
Queues should be used to distribute work amongst multiple asyncio Tasks, implement connection pools, and pub/sub patterns.
A FIFO queue. |
|
A priority queue. |
|
A LIFO queue. |
Examples
Subprocesses¶
Utilities to spawn subprocesses and run shell commands.
|
Create a subprocess. |
Run a shell command. |
Examples
See also the subprocess APIs documentation.
Streams¶
High-level APIs to work with network IO.
|
Establish a TCP connection. |
|
Establish a Unix socket connection. |
|
Start a TCP server. |
|
Start a Unix socket server. |
High-level async/await object to receive network data. |
|
High-level async/await object to send network data. |
Examples
See also the streams APIs documentation.
Synchronization¶
Threading-like synchronization primitives that can be used in Tasks.
A mutex lock. |
|
An event object. |
|
A condition object. |
|
A semaphore. |
|
A bounded semaphore. |
|
A barrier object. |
Examples
See also the documentation of asyncio synchronization primitives.
Exceptions¶
Raised when a Task is cancelled. See also |
|
Raised when a Barrier is broken. See also |
Examples
Handling CancelledError to run code on cancellation request.
See also the full list of asyncio-specific exceptions.


Cell Objects

Cell Objects¶
“Cell” objects are used to implement variables referenced by multiple scopes. For each such variable, a cell object is created to store the value; the local variables of each stack frame that references the value contain a reference to the cells from outer scopes which also use that variable. When the value is accessed, the value contained in the cell is used instead of the cell object itself. This de-referencing of the cell object requires support from the generated byte-code; these are not automatically de-referenced when accessed. Cell objects are not likely to be useful elsewhere.
-
type PyCellObject¶
The C structure used for cell objects.
-
PyTypeObject PyCell_Type¶
The type object corresponding to cell objects.
-
int PyCell_Check(PyObject *ob)¶
Return true if ob is a cell object; ob must not be
NULL
. This function always succeeds.
-
PyObject *PyCell_New(PyObject *ob)¶
- Return value: New reference.
Create and return a new cell object containing the value ob. The parameter may be
NULL
.
-
PyObject *PyCell_Get(PyObject *cell)¶
- Return value: New reference.
Return the contents of the cell cell, which can be
NULL
. If cell is not a cell object, returnsNULL
with an exception set.
-
PyObject *PyCell_GET(PyObject *cell)¶
- Return value: Borrowed reference.
Return the contents of the cell cell, but without checking that cell is non-
NULL
and a cell object.


Instance Method Objects

Instance Method Objects¶
An instance method is a wrapper for a PyCFunction
and the new way
to bind a PyCFunction
to a class object. It replaces the former call
PyMethod_New(func, NULL, class)
.
-
PyTypeObject PyInstanceMethod_Type¶
This instance of
PyTypeObject
represents the Python instance method type. It is not exposed to Python programs.
-
int PyInstanceMethod_Check(PyObject *o)¶
Return true if o is an instance method object (has type
PyInstanceMethod_Type
). The parameter must not beNULL
. This function always succeeds.
-
PyObject *PyInstanceMethod_New(PyObject *func)¶
- Return value: New reference.
Return a new instance method object, with func being any callable object. func is the function that will be called when the instance method is called.
-
PyObject *PyInstanceMethod_Function(PyObject *im)¶
- Return value: Borrowed reference.
Return the function object associated with the instance method im.
-
PyObject *PyInstanceMethod_GET_FUNCTION(PyObject *im)¶
- Return value: Borrowed reference.
Macro version of
PyInstanceMethod_Function()
which avoids error checking.
Method Objects¶
Methods are bound function objects. Methods are always bound to an instance of a user-defined class. Unbound methods (methods bound to a class object) are no longer available.
-
PyTypeObject PyMethod_Type¶
This instance of
PyTypeObject
represents the Python method type. This is exposed to Python programs astypes.MethodType
.
-
int PyMethod_Check(PyObject *o)¶
Return true if o is a method object (has type
PyMethod_Type
). The parameter must not beNULL
. This function always succeeds.
-
PyObject *PyMethod_New(PyObject *func, PyObject *self)¶
- Return value: New reference.
Return a new method object, with func being any callable object and self the instance the method should be bound. func is the function that will be called when the method is called. self must not be
NULL
.
-
PyObject *PyMethod_Function(PyObject *meth)¶
- Return value: Borrowed reference.
Return the function object associated with the method meth.
-
PyObject *PyMethod_GET_FUNCTION(PyObject *meth)¶
- Return value: Borrowed reference.
Macro version of
PyMethod_Function()
which avoids error checking.
-
PyObject *PyMethod_Self(PyObject *meth)¶
- Return value: Borrowed reference.
Return the instance associated with the method meth.
-
PyObject *PyMethod_GET_SELF(PyObject *meth)¶
- Return value: Borrowed reference.
Macro version of
PyMethod_Self()
which avoids error checking.


Function Objects

Function Objects¶
There are a few functions specific to Python functions.
-
type PyFunctionObject¶
The C structure used for functions.
-
PyTypeObject PyFunction_Type¶
This is an instance of
PyTypeObject
and represents the Python function type. It is exposed to Python programmers astypes.FunctionType
.
-
int PyFunction_Check(PyObject *o)¶
Return true if o is a function object (has type
PyFunction_Type
). The parameter must not beNULL
. This function always succeeds.
-
PyObject *PyFunction_New(PyObject *code, PyObject *globals)¶
- Return value: New reference.
Return a new function object associated with the code object code. globals must be a dictionary with the global variables accessible to the function.
The function’s docstring and name are retrieved from the code object.
__module__
is retrieved from globals. The argument defaults, annotations and closure are set toNULL
.__qualname__
is set to the same value as the code object’sco_qualname
field.
-
PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)¶
- Return value: New reference.
As
PyFunction_New()
, but also allows setting the function object’s__qualname__
attribute. qualname should be a unicode object orNULL
; ifNULL
, the__qualname__
attribute is set to the same value as the code object’sco_qualname
field.Added in version 3.3.
-
PyObject *PyFunction_GetCode(PyObject *op)¶
- Return value: Borrowed reference.
Return the code object associated with the function object op.
-
PyObject *PyFunction_GetGlobals(PyObject *op)¶
- Return value: Borrowed reference.
Return the globals dictionary associated with the function object op.
-
PyObject *PyFunction_GetModule(PyObject *op)¶
- Return value: Borrowed reference.
Return a borrowed reference to the
__module__
attribute of the function object op. It can be NULL.This is normally a
string
containing the module name, but can be set to any other object by Python code.
-
PyObject *PyFunction_GetDefaults(PyObject *op)¶
- Return value: Borrowed reference.
Return the argument default values of the function object op. This can be a tuple of arguments or
NULL
.
-
int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)¶
Set the argument default values for the function object op. defaults must be
Py_None
or a tuple.Raises
SystemError
and returns-1
on failure.
-
void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)¶
Set the vectorcall field of a given function object func.
Warning: extensions using this API must preserve the behavior of the unaltered (default) vectorcall function!
Added in version 3.12.
-
PyObject *PyFunction_GetKwDefaults(PyObject *op)¶
- Return value: Borrowed reference.
Return the keyword-only argument default values of the function object op. This can be a dictionary of arguments or
NULL
.
-
int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)¶
Set the keyword-only argument default values of the function object op. defaults must be a dictionary of keyword-only arguments or
Py_None
.This function returns
0
on success, and returns-1
with an exception set on failure.
-
PyObject *PyFunction_GetClosure(PyObject *op)¶
- Return value: Borrowed reference.
Return the closure associated with the function object op. This can be
NULL
or a tuple of cell objects.
-
int PyFunction_SetClosure(PyObject *op, PyObject *closure)¶
Set the closure associated with the function object op. closure must be
Py_None
or a tuple of cell objects.Raises
SystemError
and returns-1
on failure.
-
PyObject *PyFunction_GetAnnotations(PyObject *op)¶
- Return value: Borrowed reference.
Return the annotations of the function object op. This can be a mutable dictionary or
NULL
.
-
int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)¶
Set the annotations for the function object op. annotations must be a dictionary or
Py_None
.Raises
SystemError
and returns-1
on failure.
-
PyObject *PyFunction_GET_CODE(PyObject *op)¶
-
PyObject *PyFunction_GET_GLOBALS(PyObject *op)¶
-
PyObject *PyFunction_GET_MODULE(PyObject *op)¶
-
PyObject *PyFunction_GET_DEFAULTS(PyObject *op)¶
-
PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)¶
-
PyObject *PyFunction_GET_CLOSURE(PyObject *op)¶
-
PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)¶
- Return value: Borrowed reference.
These functions are similar to their
PyFunction_Get*
counterparts, but do not do type checking. Passing anything other than an instance ofPyFunction_Type
is undefined behavior.
-
int PyFunction_AddWatcher(PyFunction_WatchCallback callback)¶
Register callback as a function watcher for the current interpreter. Return an ID which may be passed to
PyFunction_ClearWatcher()
. In case of error (e.g. no more watcher IDs available), return-1
and set an exception.Added in version 3.12.
-
int PyFunction_ClearWatcher(int watcher_id)¶
Clear watcher identified by watcher_id previously returned from
PyFunction_AddWatcher()
for the current interpreter. Return0
on success, or-1
and set an exception on error (e.g. if the given watcher_id was never registered.)Added in version 3.12.
-
type PyFunction_WatchEvent¶
Enumeration of possible function watcher events:
PyFunction_EVENT_CREATE
PyFunction_EVENT_DESTROY
PyFunction_EVENT_MODIFY_CODE
PyFunction_EVENT_MODIFY_DEFAULTS
PyFunction_EVENT_MODIFY_KWDEFAULTS
Added in version 3.12.
-
typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)¶
Type of a function watcher callback function.
If event is
PyFunction_EVENT_CREATE
orPyFunction_EVENT_DESTROY
then new_value will beNULL
. Otherwise, new_value will hold a borrowed reference to the new value that is about to be stored in func for the attribute that is being modified.The callback may inspect but must not modify func; doing so could have unpredictable effects, including infinite recursion.
If event is
PyFunction_EVENT_CREATE
, then the callback is invoked after func has been fully initialized. Otherwise, the callback is invoked before the modification to func takes place, so the prior state of func can be inspected. The runtime is permitted to optimize away the creation of function objects when possible. In such cases no event will be emitted. Although this creates the possibility of an observable difference of runtime behavior depending on optimization decisions, it does not change the semantics of the Python code being executed.If event is
PyFunction_EVENT_DESTROY
, Taking a reference in the callback to the about-to-be-destroyed function will resurrect it, preventing it from being freed at this time. When the resurrected object is destroyed later, any watcher callbacks active at that time will be called again.If the callback sets an exception, it must return
-1
; this exception will be printed as an unraisable exception usingPyErr_WriteUnraisable()
. Otherwise it should return0
.There may already be a pending exception set on entry to the callback. In this case, the callback should return
0
with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.Added in version 3.12.


Low-level API Index

Low-level API Index¶
This page lists all low-level asyncio APIs.
Obtaining the Event Loop¶
The preferred function to get the running event loop. |
|
Get an event loop instance (running or current via the current policy). |
|
Set the event loop as current via the current policy. |
|
Create a new event loop. |
Examples
Event Loop Methods¶
See also the main documentation section about the Event Loop Methods.
Lifecycle
Run a Future/Task/awaitable until complete. |
|
Run the event loop forever. |
|
Stop the event loop. |
|
Close the event loop. |
|
Return |
|
Return |
|
Close asynchronous generators. |
Debugging
Enable or disable the debug mode. |
|
Get the current debug mode. |
Scheduling Callbacks
Invoke a callback soon. |
|
A thread-safe variant of |
|
Invoke a callback after the given time. |
|
Invoke a callback at the given time. |
Thread/Interpreter/Process Pool
|
Run a CPU-bound or other blocking function in
a |
Set the default executor for |
Tasks and Futures
Create a |
|
Schedule coroutine as a |
|
Set a factory used by |
|
Get the factory |
DNS
|
Asynchronous version of |
|
Asynchronous version of |
Networking and IPC
|
Open a TCP connection. |
|
Create a TCP server. |
Open a Unix socket connection. |
|
Create a Unix socket server. |
|
Wrap a |
|
Open a datagram (UDP) connection. |
|
|
Send a file over a transport. |
|
Upgrade an existing connection to TLS. |
|
Wrap a read end of a pipe into a |
Wrap a write end of a pipe into a |
Sockets
|
Receive data from the |
|
Receive data from the |
|
Receive a datagram from the |
Receive a datagram from the |
|
|
Send data to the |
|
Send a datagram via the |
|
Connect the |
|
Accept a |
|
Send a file over the |
Start watching a file descriptor for read availability. |
|
Stop watching a file descriptor for read availability. |
|
Start watching a file descriptor for write availability. |
|
Stop watching a file descriptor for write availability. |
Unix Signals
Add a handler for a |
|
Remove a handler for a |
Subprocesses
Spawn a subprocess. |
|
Spawn a subprocess from a shell command. |
Error Handling
Call the exception handler. |
|
Set a new exception handler. |
|
Get the current exception handler. |
|
The default exception handler implementation. |
Examples
Using
loop.create_connection()
to implement an echo-client.Using
loop.create_connection()
to connect a socket.
Transports¶
All transports implement the following methods:
Close the transport. |
|
Return |
|
Request for information about the transport. |
|
Set a new protocol. |
|
Return the current protocol. |
Transports that can receive data (TCP and Unix connections,
pipes, etc). Returned from methods like
loop.create_connection()
, loop.create_unix_connection()
,
loop.connect_read_pipe()
, etc:
Read Transports
Return |
|
Pause receiving. |
|
Resume receiving. |
Transports that can Send data (TCP and Unix connections,
pipes, etc). Returned from methods like
loop.create_connection()
, loop.create_unix_connection()
,
loop.connect_write_pipe()
, etc:
Write Transports
Write data to the transport. |
|
Write buffers to the transport. |
|
Return |
|
Close and send EOF after flushing buffered data. |
|
Close the transport immediately. |
|
Return the current size of the output buffer. |
|
Return high and low water marks for write flow control. |
|
Set new high and low water marks for write flow control. |
Transports returned by loop.create_datagram_endpoint()
:
Datagram Transports
Send data to the remote peer. |
|
Close the transport immediately. |
Low-level transport abstraction over subprocesses.
Returned by loop.subprocess_exec()
and
loop.subprocess_shell()
:
Subprocess Transports
Return the subprocess process id. |
|
Return the transport for the requested communication pipe (stdin, stdout, or stderr). |
|
Return the subprocess return code. |
|
Kill the subprocess. |
|
Send a signal to the subprocess. |
|
Stop the subprocess. |
|
Kill the subprocess and close all pipes. |
Protocols¶
Protocol classes can implement the following callback methods:
|
Called when a connection is made. |
|
Called when the connection is lost or closed. |
|
Called when the transport’s buffer goes over the high water mark. |
|
Called when the transport’s buffer drains below the low water mark. |
Streaming Protocols (TCP, Unix Sockets, Pipes)
|
Called when some data is received. |
|
Called when an EOF is received. |
Buffered Streaming Protocols
|
Called to allocate a new receive buffer. |
|
Called when the buffer was updated with the received data. |
|
Called when an EOF is received. |
Datagram Protocols
|
Called when a datagram is received. |
|
Called when a previous send or receive operation raises an
|
Subprocess Protocols
|
Called when the child process writes data into its stdout or stderr pipe. |
|
Called when one of the pipes communicating with the child process is closed. |
|
Called when the child process has exited. It can be called before
|
Event Loop Policies¶
Policies is a low-level mechanism to alter the behavior of
functions like asyncio.get_event_loop()
. See also
the main policies section for more
details.
Accessing Policies
Return the current process-wide policy. |
|
Set a new process-wide policy. |
|
Base class for policy objects. |


Platform Support

Platform Support¶
The asyncio
module is designed to be portable,
but some platforms have subtle differences and limitations
due to the platforms’ underlying architecture and capabilities.
All Platforms¶
loop.add_reader()
andloop.add_writer()
cannot be used to monitor file I/O.
Windows¶
Source code: Lib/asyncio/proactor_events.py, Lib/asyncio/windows_events.py, Lib/asyncio/windows_utils.py
Changed in version 3.8: On Windows, ProactorEventLoop
is now the default event loop.
All event loops on Windows do not support the following methods:
loop.create_unix_connection()
andloop.create_unix_server()
are not supported. Thesocket.AF_UNIX
socket family is specific to Unix.loop.add_signal_handler()
andloop.remove_signal_handler()
are not supported.
SelectorEventLoop
has the following limitations:
SelectSelector
is used to wait on socket events: it supports sockets and is limited to 512 sockets.loop.add_reader()
andloop.add_writer()
only accept socket handles (e.g. pipe file descriptors are not supported).Pipes are not supported, so the
loop.connect_read_pipe()
andloop.connect_write_pipe()
methods are not implemented.Subprocesses are not supported, i.e.
loop.subprocess_exec()
andloop.subprocess_shell()
methods are not implemented.
ProactorEventLoop
has the following limitations:
The
loop.add_reader()
andloop.add_writer()
methods are not supported.
The resolution of the monotonic clock on Windows is usually around 15.6 milliseconds. The best resolution is 0.5 milliseconds. The resolution depends on the hardware (availability of HPET) and on the Windows configuration.
Subprocess Support on Windows¶
On Windows, the default event loop ProactorEventLoop
supports
subprocesses, whereas SelectorEventLoop
does not.
macOS¶
Modern macOS versions are fully supported.
macOS <= 10.8
On macOS 10.6, 10.7 and 10.8, the default event loop
uses selectors.KqueueSelector
, which does not support
character devices on these versions. The SelectorEventLoop
can be manually configured to use SelectSelector
or PollSelector
to support character devices on
these older versions of macOS. Example:
import asyncio
import selectors
selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)


Complex Number Objects

Complex Number Objects¶
Python’s complex number objects are implemented as two distinct types when viewed from the C API: one is the Python object exposed to Python programs, and the other is a C structure which represents the actual complex number value. The API provides functions for working with both.
Complex Numbers as C Structures¶
Note that the functions which accept these structures as parameters and return them as results do so by value rather than dereferencing them through pointers. This is consistent throughout the API.
-
type Py_complex¶
The C structure which corresponds to the value portion of a Python complex number object. Most of the functions for dealing with complex number objects use structures of this type as input or output values, as appropriate.
The structure is defined as:
typedef struct { double real; double imag; } Py_complex;
-
Py_complex _Py_c_sum(Py_complex left, Py_complex right)¶
Return the sum of two complex numbers, using the C
Py_complex
representation.
-
Py_complex _Py_c_diff(Py_complex left, Py_complex right)¶
Return the difference between two complex numbers, using the C
Py_complex
representation.
-
Py_complex _Py_c_neg(Py_complex num)¶
Return the negation of the complex number num, using the C
Py_complex
representation.
-
Py_complex _Py_c_prod(Py_complex left, Py_complex right)¶
Return the product of two complex numbers, using the C
Py_complex
representation.
-
Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)¶
Return the quotient of two complex numbers, using the C
Py_complex
representation.If divisor is null, this method returns zero and sets
errno
toEDOM
.
-
Py_complex _Py_c_pow(Py_complex num, Py_complex exp)¶
Return the exponentiation of num by exp, using the C
Py_complex
representation.If num is null and exp is not a positive real number, this method returns zero and sets
errno
toEDOM
.Set
errno
toERANGE
on overflows.
Complex Numbers as Python Objects¶
-
PyTypeObject PyComplex_Type¶
- Part of the Stable ABI.
This instance of
PyTypeObject
represents the Python complex number type. It is the same object ascomplex
in the Python layer.
-
int PyComplex_Check(PyObject *p)¶
Return true if its argument is a
PyComplexObject
or a subtype ofPyComplexObject
. This function always succeeds.
-
int PyComplex_CheckExact(PyObject *p)¶
Return true if its argument is a
PyComplexObject
, but not a subtype ofPyComplexObject
. This function always succeeds.
-
PyObject *PyComplex_FromCComplex(Py_complex v)¶
- Return value: New reference.
Create a new Python complex number object from a C
Py_complex
value. ReturnNULL
with an exception set on error.
-
PyObject *PyComplex_FromDoubles(double real, double imag)¶
- Return value: New reference. Part of the Stable ABI.
Return a new
PyComplexObject
object from real and imag. ReturnNULL
with an exception set on error.
-
double PyComplex_RealAsDouble(PyObject *op)¶
- Part of the Stable ABI.
Return the real part of op as a C double.
If op is not a Python complex number object but has a
__complex__()
method, this method will first be called to convert op to a Python complex number object. If__complex__()
is not defined then it falls back to callPyFloat_AsDouble()
and returns its result.Upon failure, this method returns
-1.0
with an exception set, so one should callPyErr_Occurred()
to check for errors.Changed in version 3.13: Use
__complex__()
if available.
-
double PyComplex_ImagAsDouble(PyObject *op)¶
- Part of the Stable ABI.
Return the imaginary part of op as a C double.
If op is not a Python complex number object but has a
__complex__()
method, this method will first be called to convert op to a Python complex number object. If__complex__()
is not defined then it falls back to callPyFloat_AsDouble()
and returns0.0
on success.Upon failure, this method returns
-1.0
with an exception set, so one should callPyErr_Occurred()
to check for errors.Changed in version 3.13: Use
__complex__()
if available.
-
Py_complex PyComplex_AsCComplex(PyObject *op)¶
Return the
Py_complex
value of the complex number op.If op is not a Python complex number object but has a
__complex__()
method, this method will first be called to convert op to a Python complex number object. If__complex__()
is not defined then it falls back to__float__()
. If__float__()
is not defined then it falls back to__index__()
.Upon failure, this method returns
Py_complex
withreal
set to-1.0
and with an exception set, so one should callPyErr_Occurred()
to check for errors.Changed in version 3.8: Use
__index__()
if available.


Floating-Point Objects

Floating-Point Objects¶
-
PyTypeObject PyFloat_Type¶
- Part of the Stable ABI.
This instance of
PyTypeObject
represents the Python floating-point type. This is the same object asfloat
in the Python layer.
-
int PyFloat_Check(PyObject *p)¶
Return true if its argument is a
PyFloatObject
or a subtype ofPyFloatObject
. This function always succeeds.
-
int PyFloat_CheckExact(PyObject *p)¶
Return true if its argument is a
PyFloatObject
, but not a subtype ofPyFloatObject
. This function always succeeds.
-
PyObject *PyFloat_FromString(PyObject *str)¶
- Return value: New reference. Part of the Stable ABI.
Create a
PyFloatObject
object based on the string value in str, orNULL
on failure.
-
PyObject *PyFloat_FromDouble(double v)¶
- Return value: New reference. Part of the Stable ABI.
Create a
PyFloatObject
object from v, orNULL
on failure.
-
double PyFloat_AsDouble(PyObject *pyfloat)¶
- Part of the Stable ABI.
Return a C double representation of the contents of pyfloat. If pyfloat is not a Python floating-point object but has a
__float__()
method, this method will first be called to convert pyfloat into a float. If__float__()
is not defined then it falls back to__index__()
. This method returns-1.0
upon failure, so one should callPyErr_Occurred()
to check for errors.Changed in version 3.8: Use
__index__()
if available.
-
double PyFloat_AS_DOUBLE(PyObject *pyfloat)¶
Return a C double representation of the contents of pyfloat, but without error checking.
-
PyObject *PyFloat_GetInfo(void)¶
- Return value: New reference. Part of the Stable ABI.
Return a structseq instance which contains information about the precision, minimum and maximum values of a float. It’s a thin wrapper around the header file
float.h
.
-
double PyFloat_GetMax()¶
- Part of the Stable ABI.
Return the maximum representable finite float DBL_MAX as C double.
-
double PyFloat_GetMin()¶
- Part of the Stable ABI.
Return the minimum normalized positive float DBL_MIN as C double.
-
Py_INFINITY¶
This macro expands to a constant expression of type double, that represents the positive infinity.
On most platforms, this is equivalent to the
INFINITY
macro from the C11 standard<math.h>
header.
-
Py_NAN¶
This macro expands to a constant expression of type double, that represents a quiet not-a-number (qNaN) value.
On most platforms, this is equivalent to the
NAN
macro from the C11 standard<math.h>
header.
-
Py_HUGE_VAL¶
Equivalent to
INFINITY
.Deprecated since version 3.14: The macro is soft deprecated.
-
Py_MATH_TAU¶
The definition (accurate for a double type) of the
math.tau
constant.Added in version 3.6.
-
Py_RETURN_NAN¶
Return
math.nan
from a function.On most platforms, this is equivalent to
return PyFloat_FromDouble(NAN)
.
-
Py_RETURN_INF(sign)¶
Return
math.inf
or-math.inf
from a function, depending on the sign of sign.On most platforms, this is equivalent to the following:
return PyFloat_FromDouble(copysign(INFINITY, sign));
-
Py_IS_FINITE(X)¶
Return
1
if the given floating-point number X is finite, that is, it is normal, subnormal or zero, but not infinite or NaN. Return0
otherwise.Deprecated since version 3.14: The macro is soft deprecated. Use
isfinite
instead.
-
Py_IS_INFINITY(X)¶
Return
1
if the given floating-point number X is positive or negative infinity. Return0
otherwise.Deprecated since version 3.14: The macro is soft deprecated. Use
isinf
instead.
-
Py_IS_NAN(X)¶
Return
1
if the given floating-point number X is a not-a-number (NaN) value. Return0
otherwise.Deprecated since version 3.14: The macro is soft deprecated. Use
isnan
instead.
Pack and Unpack functions¶
The pack and unpack functions provide an efficient platform-independent way to store floating-point values as byte strings. The Pack routines produce a bytes string from a C double, and the Unpack routines produce a C double from such a bytes string. The suffix (2, 4 or 8) specifies the number of bytes in the bytes string.
On platforms that appear to use IEEE 754 formats these functions work by copying bits. On other platforms, the 2-byte format is identical to the IEEE 754 binary16 half-precision format, the 4-byte format (32-bit) is identical to the IEEE 754 binary32 single precision format, and the 8-byte format to the IEEE 754 binary64 double precision format, although the packing of INFs and NaNs (if such things exist on the platform) isn’t handled correctly, and attempting to unpack a bytes string containing an IEEE INF or NaN will raise an exception.
Note that NaNs type may not be preserved on IEEE platforms (signaling NaN become quiet NaN), for example on x86 systems in 32-bit mode.
On non-IEEE platforms with more precision, or larger dynamic range, than IEEE 754 supports, not all values can be packed; on non-IEEE platforms with less precision, or smaller dynamic range, not all values can be unpacked. What happens in such cases is partly accidental (alas).
Added in version 3.11.
Pack functions¶
The pack routines write 2, 4 or 8 bytes, starting at p. le is an
int argument, non-zero if you want the bytes string in little-endian
format (exponent last, at p+1
, p+3
, or p+6
p+7
), zero if you
want big-endian format (exponent first, at p). The PY_BIG_ENDIAN
constant can be used to use the native endian: it is equal to 1
on big
endian processor, or 0
on little endian processor.
Return value: 0
if all is OK, -1
if error (and an exception is set,
most likely OverflowError
).
There are two problems on non-IEEE platforms:
What this does is undefined if x is a NaN or infinity.
-0.0
and+0.0
produce the same bytes string.
-
int PyFloat_Pack2(double x, char *p, int le)¶
Pack a C double as the IEEE 754 binary16 half-precision format.
-
int PyFloat_Pack4(double x, char *p, int le)¶
Pack a C double as the IEEE 754 binary32 single precision format.
-
int PyFloat_Pack8(double x, char *p, int le)¶
Pack a C double as the IEEE 754 binary64 double precision format.
Unpack functions¶
The unpack routines read 2, 4 or 8 bytes, starting at p. le is an
int argument, non-zero if the bytes string is in little-endian format
(exponent last, at p+1
, p+3
or p+6
and p+7
), zero if big-endian
(exponent first, at p). The PY_BIG_ENDIAN
constant can be used to
use the native endian: it is equal to 1
on big endian processor, or 0
on little endian processor.
Return value: The unpacked double. On error, this is -1.0
and
PyErr_Occurred()
is true (and an exception is set, most likely
OverflowError
).
Note that on a non-IEEE platform this will refuse to unpack a bytes string that represents a NaN or infinity.
-
double PyFloat_Unpack2(const char *p, int le)¶
Unpack the IEEE 754 binary16 half-precision format as a C double.
-
double PyFloat_Unpack4(const char *p, int le)¶
Unpack the IEEE 754 binary32 single precision format as a C double.
-
double PyFloat_Unpack8(const char *p, int le)¶
Unpack the IEEE 754 binary64 double precision format as a C double.


Byte Array Objects

Byte Array Objects¶
-
PyTypeObject PyByteArray_Type¶
- Part of the Stable ABI.
This instance of
PyTypeObject
represents the Python bytearray type; it is the same object asbytearray
in the Python layer.
Type check macros¶
Direct API functions¶
-
PyObject *PyByteArray_FromObject(PyObject *o)¶
- Return value: New reference. Part of the Stable ABI.
Return a new bytearray object from any object, o, that implements the buffer protocol.
On failure, return
NULL
with an exception set.
-
PyObject *PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)¶
- Return value: New reference. Part of the Stable ABI.
Create a new bytearray object from string and its length, len.
On failure, return
NULL
with an exception set.
-
PyObject *PyByteArray_Concat(PyObject *a, PyObject *b)¶
- Return value: New reference. Part of the Stable ABI.
Concat bytearrays a and b and return a new bytearray with the result.
On failure, return
NULL
with an exception set.
-
Py_ssize_t PyByteArray_Size(PyObject *bytearray)¶
- Part of the Stable ABI.
Return the size of bytearray after checking for a
NULL
pointer.
-
char *PyByteArray_AsString(PyObject *bytearray)¶
- Part of the Stable ABI.
Return the contents of bytearray as a char array after checking for a
NULL
pointer. The returned array always has an extra null byte appended.
-
int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)¶
- Part of the Stable ABI.
Resize the internal buffer of bytearray to len. Failure is a
-1
return with an exception set.Changed in version 3.14: A negative len will now result in an exception being set and -1 returned.
Macros¶
These macros trade safety for speed and they don’t check pointers.
-
char *PyByteArray_AS_STRING(PyObject *bytearray)¶
Similar to
PyByteArray_AsString()
, but without error checking.
-
Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)¶
Similar to
PyByteArray_Size()
, but without error checking.


String conversion and formatting

String conversion and formatting¶
Functions for number conversion and formatted string output.
-
int PyOS_snprintf(char *str, size_t size, const char *format, ...)¶
- Part of the Stable ABI.
Output not more than size bytes to str according to the format string format and the extra arguments. See the Unix man page snprintf(3).
-
int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)¶
- Part of the Stable ABI.
Output not more than size bytes to str according to the format string format and the variable argument list va. Unix man page vsnprintf(3).
PyOS_snprintf()
and PyOS_vsnprintf()
wrap the Standard C library
functions snprintf()
and vsnprintf()
. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.
The wrappers ensure that str[size-1]
is always '\0'
upon return. They
never write more than size bytes (including the trailing '\0'
) into str.
Both functions require that str != NULL
, size > 0
, format != NULL
and size < INT_MAX
. Note that this means there is no equivalent to the C99
n = snprintf(NULL, 0, ...)
which would determine the necessary buffer size.
The return value (rv) for these functions should be interpreted as follows:
When
0 <= rv < size
, the output conversion was successful and rv characters were written to str (excluding the trailing'\0'
byte atstr[rv]
).When
rv >= size
, the output conversion was truncated and a buffer withrv + 1
bytes would have been needed to succeed.str[size-1]
is'\0'
in this case.When
rv < 0
, the output conversion failed andstr[size-1]
is'\0'
in this case too, but the rest of str is undefined. The exact cause of the error depends on the underlying platform.
The following functions provide locale-independent string to number conversions.
-
unsigned long PyOS_strtoul(const char *str, char **ptr, int base)¶
- Part of the Stable ABI.
Convert the initial part of the string in
str
to an unsigned long value according to the givenbase
, which must be between2
and36
inclusive, or be the special value0
.Leading white space and case of characters are ignored. If
base
is zero it looks for a leading0b
,0o
or0x
to tell which base. If these are absent it defaults to10
. Base must be 0 or between 2 and 36 (inclusive). Ifptr
is non-NULL
it will contain a pointer to the end of the scan.If the converted value falls out of range of corresponding return type, range error occurs (
errno
is set toERANGE
) andULONG_MAX
is returned. If no conversion can be performed,0
is returned.See also the Unix man page strtoul(3).
Added in version 3.2.
-
long PyOS_strtol(const char *str, char **ptr, int base)¶
- Part of the Stable ABI.
Convert the initial part of the string in
str
to an long value according to the givenbase
, which must be between2
and36
inclusive, or be the special value0
.Same as
PyOS_strtoul()
, but return a long value instead andLONG_MAX
on overflows.See also the Unix man page strtol(3).
Added in version 3.2.
-
double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)¶
- Part of the Stable ABI.
Convert a string
s
to a double, raising a Python exception on failure. The set of accepted strings corresponds to the set of strings accepted by Python’sfloat()
constructor, except thats
must not have leading or trailing whitespace. The conversion is independent of the current locale.If
endptr
isNULL
, convert the whole string. RaiseValueError
and return-1.0
if the string is not a valid representation of a floating-point number.If endptr is not
NULL
, convert as much of the string as possible and set*endptr
to point to the first unconverted character. If no initial segment of the string is the valid representation of a floating-point number, set*endptr
to point to the beginning of the string, raise ValueError, and return-1.0
.If
s
represents a value that is too large to store in a float (for example,"1e500"
is such a string on many platforms) then ifoverflow_exception
isNULL
returnPy_INFINITY
(with an appropriate sign) and don’t set any exception. Otherwise,overflow_exception
must point to a Python exception object; raise that exception and return-1.0
. In both cases, set*endptr
to point to the first character after the converted value.If any other error occurs during the conversion (for example an out-of-memory error), set the appropriate Python exception and return
-1.0
.Added in version 3.1.
-
char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)¶
- Part of the Stable ABI.
Convert a double val to a string using supplied format_code, precision, and flags.
format_code must be one of
'e'
,'E'
,'f'
,'F'
,'g'
,'G'
or'r'
. For'r'
, the supplied precision must be 0 and is ignored. The'r'
format code specifies the standardrepr()
format.flags can be zero or more of the following values or-ed together:
-
Py_DTSF_SIGN¶
Always precede the returned string with a sign character, even if val is non-negative.
-
Py_DTSF_ADD_DOT_0¶
Ensure that the returned string will not look like an integer.
-
Py_DTSF_ALT¶
Apply “alternate” formatting rules. See the documentation for the
PyOS_snprintf()
'#'
specifier for details.
-
Py_DTSF_NO_NEG_0¶
Negative zero is converted to positive zero.
Added in version 3.11.
If ptype is non-
NULL
, then the value it points to will be set to one of the following constants depending on the type of val:*ptype
type of val
-
Py_DTST_FINITE¶
finite number
-
Py_DTST_INFINITE¶
infinite number
-
Py_DTST_NAN¶
not a number
The return value is a pointer to buffer with the converted string or
NULL
if the conversion failed. The caller is responsible for freeing the returned string by callingPyMem_Free()
.Added in version 3.1.
-
Py_DTSF_SIGN¶
-
int PyOS_mystricmp(const char *str1, const char *str2)¶
-
int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)¶
- Part of the Stable ABI.
Case insensitive comparison of strings. These functions work almost identically to
strcmp()
andstrncmp()
(respectively), except that they ignore the case of ASCII characters.Return
0
if the strings are equal, a negative value if str1 sorts lexicographically before str2, or a positive value if it sorts after.In the str1 or str2 arguments, a NUL byte marks the end of the string. For
PyOS_mystrnicmp()
, the size argument gives the maximum size of the string, as if NUL was present at the index given by size.These functions do not use the locale.
-
int PyOS_stricmp(const char *str1, const char *str2)¶
-
int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)¶
Case insensitive comparison of strings.
On Windows, these are aliases of
stricmp()
andstrnicmp()
, respectively.On other platforms, they are aliases of
PyOS_mystricmp()
andPyOS_mystrnicmp()
, respectively.
Character classification and conversion¶
The following macros provide locale-independent (unlike the C standard library
ctype.h
) character classification and conversion.
The argument must be a signed or unsigned char.
-
Py_ISALNUM(c)¶
Return true if the character c is an alphanumeric character.
-
Py_ISALPHA(c)¶
Return true if the character c is an alphabetic character (
a-z
andA-Z
).
-
Py_ISDIGIT(c)¶
Return true if the character c is a decimal digit (
0-9
).
-
Py_ISLOWER(c)¶
Return true if the character c is a lowercase ASCII letter (
a-z
).
-
Py_ISUPPER(c)¶
Return true if the character c is an uppercase ASCII letter (
A-Z
).
-
Py_ISSPACE(c)¶
Return true if the character c is a whitespace character (space, tab, carriage return, newline, vertical tab, or form feed).
-
Py_ISXDIGIT(c)¶
Return true if the character c is a hexadecimal digit (
0-9
,a-f
, andA-F
).
-
Py_TOLOWER(c)¶
Return the lowercase equivalent of the character c.
-
Py_TOUPPER(c)¶
Return the uppercase equivalent of the character c.


Data marshalling support

Data marshalling support¶
These routines allow C code to work with serialized objects using the same
data format as the marshal
module. There are functions to write data
into the serialization format, and additional functions that can be used to
read the data back. Files used to store marshalled data must be opened in
binary mode.
Numeric values are stored with the least significant byte first.
The module supports several versions of the data format; see
the Python module documentation
for details.
-
Py_MARSHAL_VERSION¶
The current format version. See
marshal.version
.
-
void PyMarshal_WriteLongToFile(long value, FILE *file, int version)¶
Marshal a long integer, value, to file. This will only write the least-significant 32 bits of value; regardless of the size of the native long type. version indicates the file format.
This function can fail, in which case it sets the error indicator. Use
PyErr_Occurred()
to check for that.
-
void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)¶
Marshal a Python object, value, to file. version indicates the file format.
This function can fail, in which case it sets the error indicator. Use
PyErr_Occurred()
to check for that.
-
PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)¶
- Return value: New reference.
Return a bytes object containing the marshalled representation of value. version indicates the file format.
The following functions allow marshalled values to be read back in.
-
long PyMarshal_ReadLongFromFile(FILE *file)¶
Return a C long from the data stream in a FILE* opened for reading. Only a 32-bit value can be read in using this function, regardless of the native size of long.
On error, sets the appropriate exception (
EOFError
) and returns-1
.
-
int PyMarshal_ReadShortFromFile(FILE *file)¶
Return a C short from the data stream in a FILE* opened for reading. Only a 16-bit value can be read in using this function, regardless of the native size of short.
On error, sets the appropriate exception (
EOFError
) and returns-1
.
-
PyObject *PyMarshal_ReadObjectFromFile(FILE *file)¶
- Return value: New reference.
Return a Python object from the data stream in a FILE* opened for reading.
On error, sets the appropriate exception (
EOFError
,ValueError
orTypeError
) and returnsNULL
.
-
PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)¶
- Return value: New reference.
Return a Python object from the data stream in a FILE* opened for reading. Unlike
PyMarshal_ReadObjectFromFile()
, this function assumes that no further objects will be read from the file, allowing it to aggressively load file data into memory so that the de-serialization can operate from data in memory rather than reading a byte at a time from the file. Only use this variant if you are certain that you won’t be reading anything else from the file.On error, sets the appropriate exception (
EOFError
,ValueError
orTypeError
) and returnsNULL
.
-
PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)¶
- Return value: New reference.
Return a Python object from the data stream in a byte buffer containing len bytes pointed to by data.
On error, sets the appropriate exception (
EOFError
,ValueError
orTypeError
) and returnsNULL
.


: Internationalized headers

email.header
: Internationalized headers¶
Source code: Lib/email/header.py
This module is part of the legacy (Compat32
) email API. In the current API
encoding and decoding of headers is handled transparently by the
dictionary-like API of the EmailMessage
class. In
addition to uses in legacy code, this module can be useful in applications that
need to completely control the character sets used when encoding headers.
The remaining text in this section is the original documentation of the module.
RFC 2822 is the base standard that describes the format of email messages. It derives from the older RFC 822 standard which came into widespread use at a time when most email was composed of ASCII characters only. RFC 2822 is a specification written assuming email contains only 7-bit ASCII characters.
Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now be used in
email messages. The base standard still requires email messages to be
transferred using only 7-bit ASCII characters, so a slew of RFCs have been
written describing how to encode email containing non-ASCII characters into
RFC 2822-compliant format. These RFCs include RFC 2045, RFC 2046,
RFC 2047, and RFC 2231. The email
package supports these standards
in its email.header
and email.charset
modules.
If you want to include non-ASCII characters in your email headers, say in the
Subject or To fields, you should use the
Header
class and assign the field in the Message
object to an instance of Header
instead of using a string for the header
value. Import the Header
class from the email.header
module.
For example:
>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'
Notice here how we wanted the Subject field to contain a non-ASCII
character? We did this by creating a Header
instance and passing in
the character set that the byte string was encoded in. When the subsequent
Message
instance was flattened, the Subject
field was properly RFC 2047 encoded. MIME-aware mail readers would show this
header using the embedded ISO-8859-1 character.
Here is the Header
class description:
- class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')¶
Create a MIME-compliant header that can contain strings in different character sets.
Optional s is the initial header value. If
None
(the default), the initial header value is not set. You can later append to the header withappend()
method calls. s may be an instance ofbytes
orstr
, but see theappend()
documentation for semantics.Optional charset serves two purposes: it has the same meaning as the charset argument to the
append()
method. It also sets the default character set for all subsequentappend()
calls that omit the charset argument. If charset is not provided in the constructor (the default), theus-ascii
character set is used both as s’s initial charset and as the default for subsequentappend()
calls.The maximum line length can be specified explicitly via maxlinelen. For splitting the first line to a shorter value (to account for the field header which isn’t included in s, e.g. Subject) pass in the name of the field in header_name. The default maxlinelen is 78, and the default value for header_name is
None
, meaning it is not taken into account for the first line of a long, split header.Optional continuation_ws must be RFC 2822-compliant folding whitespace, and is usually either a space or a hard tab character. This character will be prepended to continuation lines. continuation_ws defaults to a single space character.
Optional errors is passed straight through to the
append()
method.- append(s, charset=None, errors='strict')¶
Append the string s to the MIME header.
Optional charset, if given, should be a
Charset
instance (seeemail.charset
) or the name of a character set, which will be converted to aCharset
instance. A value ofNone
(the default) means that the charset given in the constructor is used.s may be an instance of
bytes
orstr
. If it is an instance ofbytes
, then charset is the encoding of that byte string, and aUnicodeError
will be raised if the string cannot be decoded with that character set.If s is an instance of
str
, then charset is a hint specifying the character set of the characters in the string.In either case, when producing an RFC 2822-compliant header using RFC 2047 rules, the string will be encoded using the output codec of the charset. If the string cannot be encoded using the output codec, a UnicodeError will be raised.
Optional errors is passed as the errors argument to the decode call if s is a byte string.
- encode(splitchars=';, \t', maxlinelen=None, linesep='\n')¶
Encode a message header into an RFC-compliant format, possibly wrapping long lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
Optional splitchars is a string containing characters which should be given extra weight by the splitting algorithm during normal header wrapping. This is in very rough support of RFC 2822's ‘higher level syntactic breaks’: split points preceded by a splitchar are preferred during line splitting, with the characters preferred in the order in which they appear in the string. Space and tab may be included in the string to indicate whether preference should be given to one over the other as a split point when other split chars do not appear in the line being split. Splitchars does not affect RFC 2047 encoded lines.
maxlinelen, if given, overrides the instance’s value for the maximum line length.
linesep specifies the characters used to separate the lines of the folded header. It defaults to the most useful value for Python application code (
\n
), but\r\n
can be specified in order to produce headers with RFC-compliant line separators.Changed in version 3.2: Added the linesep argument.
The
Header
class also provides a number of methods to support standard operators and built-in functions.- __str__()¶
Returns an approximation of the
Header
as a string, using an unlimited line length. All pieces are converted to unicode using the specified encoding and joined together appropriately. Any pieces with a charset of'unknown-8bit'
are decoded as ASCII using the'replace'
error handler.Changed in version 3.2: Added handling for the
'unknown-8bit'
charset.
The email.header
module also provides the following convenient functions.
- email.header.decode_header(header)¶
Decode a message header value without converting the character set. The header value is in header.
For historical reasons, this function may return either:
A list of pairs containing each of the decoded parts of the header,
(decoded_bytes, charset)
, where decoded_bytes is always an instance ofbytes
, and charset is either:A lower case string containing the name of the character set specified.
None
for non-encoded parts of the header.
A list of length 1 containing a pair
(string, None)
, where string is always an instance ofstr
.
An
email.errors.HeaderParseError
may be raised when certain decoding errors occur (e.g. a base64 decoding exception).Here are examples:
>>> from email.header import decode_header >>> decode_header('=?iso-8859-1?q?p=F6stal?=') [(b'p\xf6stal', 'iso-8859-1')] >>> decode_header('unencoded_string') [('unencoded_string', None)] >>> decode_header('bar =?utf-8?B?ZsOzbw==?=') [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]
Note
This function exists for backwards compatibility only. For new code, we recommend using
email.headerregistry.HeaderRegistry
.
- email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')¶
Create a
Header
instance from a sequence of pairs as returned bydecode_header()
.decode_header()
takes a header value string and returns a sequence of pairs of the format(decoded_string, charset)
where charset is the name of the character set.This function takes one of those sequence of pairs and returns a
Header
instance. Optional maxlinelen, header_name, and continuation_ws are as in theHeader
constructor.Note
This function exists for backwards compatibility only, and is not recommended for use in new code.