Reference

General

pyawaitable.include()

Return the include path of pyawaitable.h.

PYAWAITABLE_INCLUDE

Result of pyawaitable.include(), stored as an environment variable through a .pth file (only available when Python isn’t run through -S).

int PyAwaitable_Init(void)

Initialize PyAwaitable. This should typically be done in the Py_mod_exec slot of a module.

This can safely be called multiple times.

Return 0 on success, and -1 with an exception set on failure.

PyObject *PyAwaitable_New(void)

Create a new empty PyAwaitable object.

This returns a new strong reference to a PyAwaitable object on success, and returns NULL with an exception set on failure.

int PyAwaitable_SetResult(PyObject *awaitable, PyObject *result)

Set result to the result of the PyAwaitable object. The result will be returned to the await expression on this PyAwaitable object.

result will not be stolen; this function will create its own reference to result internally.

Return 0 with the return value set on success, and -1 with an exception set on failure.

Coroutines

typedef int (*PyAwaitable_Callback)(PyObject *awaitable, PyObject *result)

The type of a result callback, as submitted in PyAwaitable_AddAwait().

This takes two PyObject * references: an instance of a PyAwaitable object, and the return value of the awaited coroutine.

There are three possible return values:

  1. 0: OK.

  2. -1: Error, fall to the error callback registered alongside this one, if it exists. There must be an exception set.

  3. -2: Error, but skip the error callback if provided. There must be an exception set.

typedef int (*PyAwaitable_Error)(PyObject *awaitable, PyObject *result)

The type of an error callback.

typedef int (*PyAwaitable_Defer)(PyObject *awaitable)

The type of a “defer” callback.

int PyAwaitable_AddAwait(PyObject *awaitable, PyObject *coroutine, PyAwaitable_Callback result_callback, PyAwaitable_Error error_callback)

Mark an awaitable object, coroutine, for execution by the event loop when the PyAwaitable object is awaited.

result_callback is a return value callback. It will be called with the result of coroutine when it has finished execution. This may be NULL, in which case the return value is simply discarded.

error_callback is an error callback. It is called if coroutine raises an exception during execution, or when result_callback returns -1. This may be NULL, which will cause any exceptions to be propagated to the caller (the one who awaited the PyAwaitable object).

This function will return 0 on success, and -1 with an exception set on failure.

int PyAwaitable_AddExpr(PyObject *awaitable, PyObject *expr, PyAwaitable_Callback result_callback, PyAwaitable_Error error_callback)

Similar to PyAwaitable_AddAwait(), but designed for convenience.

If expr is NULL, this function returns -1 without an exception set. If expr is non-NULL, this function calls PyAwaitable_AddAwait() with all the provided arguments, and then steals a reference to expr.

This behavior allows you to use other C API functions directly with this one. For example, if you had an async def function coro, it could be added to the PyAwaitable object with PyAwaitable_AddExpr(awaitable, PyObject_CallNoArgs(coro), NULL, NULL).

Added in version 2.1.

Value Storage

int PyAwaitable_SaveValues(PyObject *awaitable, Py_ssize_t nargs, ...)

Store nargs amount of object values in the PyAwaitable object.

The number of arguments passed to ... must match nargs. The objects passed will be stored in the PyAwaitable object internally to be unpacked by PyAwaitable_UnpackValues() later.

Return 0 with the values stored on success, and -1 with an exception set on failure.

int PyAwaitable_UnpackValues(PyObject *awaitable, ...)

Unpack object values stored in the PyAwaitable object.

This function expects PyObject ** pointers passed to the .... These will then be set to borrowed reference. The number of arguments passed to the ... must match the sum of all nargs to prior PyAwaitable_SaveValues() calls. For example, if one call stored two values, and then another call stored three values, this function would expect five pointers to be passed.

Pointers passed to the ... may be NULL, in which case the object at that position is skipped.

Return 0 will all references set on success, and -1 with an exception set on failure.

int PyAwaitable_SetValue(PyObject *awaitable, Py_ssize_t index, PyObject *value)

Replace a single object value at the position index with value. The old reference to the object stored at the position index is released, so value must not be NULL.

If index is below zero or out of bounds for the number of stored object values, this function will fail. As such, this function cannot be used to append new object values – use PyAwaitable_SaveValues() for that.

Return 0 with the object replaced on success, and -1 with an exception set on failure.

PyObject *PyAwaitable_GetValue(PyObject *awaitable, Py_ssize_t index)

Unpack a single object value at the position index.

If index is below zero or out of bounds for the number of stored object values, this function will sanely fail.

This is a low-level routine meant for complete-ness; always prefer using PyAwaitable_UnpackValues() over this function.

Return a borrowed reference to the value on success, and NULL with an exception set on failure.

int PyAwaitable_SaveArbValues(PyObject *awaitable, Py_ssize_t nargs, ...)

Similar to PyAwaitable_SaveValues(), but saves arbitrary values (void * pointers) instead of PyObject * references.

Arbitrary values are separate from object values, so the number of Python objects stored through PyAwaitable_SaveValues() has no effect on this function.

Return 0 with all pointers stored on success, and -1 with an exception set on failure.

int PyAwaitable_UnpackArbValues(PyObject *awaitable, ...)

Similar to PyAwaitable_UnpackValues(), but unpacks arbitrary values (void * pointers) instead of PyObject * references.

Arbitrary values are separate from object values, so the number of Python objects stored through PyAwaitable_SaveValues() has no effect on this function.

This function expects void ** pointers passed to the .... The number of arguments passed to the ... must match the sum of all nargs to prior PyAwaitable_SaveArbValues() calls. For example, if one call stored two values, and then another call stored three values, this function would expect five pointers to be passed.

Return 0 with all pointers set on success, and -1 with an exception set on failure.

int PyAwaitable_SetArbValue(PyObject *awaitable, Py_ssize_t index, void *value)

Similar to PyAwaitable_SetValue(), but replaces a single arbitrary value instead.

If index is below zero or out of bounds for the number of stored object values, this function will fail. As such, this function cannot be used to append new object values – use PyAwaitable_SaveArbValues() for that.

Return 0 with the object replaced on success, and -1 with an exception set on failure.

void *PyAwaitable_GetArbValue(PyObject *awaitable, Py_ssize_t index)

Similar to PyAwaitable_GetValue(), but unpacks a single arbitrary value at the position index.

If index is below zero or out of bounds for the number of stored object values, this function will sanely fail.

This is a low-level routine meant for complete-ness; always prefer using PyAwaitable_UnpackArbValues() over this function.

Return the void * pointer stored at index on success, and NULL with an exception set on failure. If NULL is a valid value for the arbitrary value, use PyErr_Occurred() to differentiate.