README.md

PyAwaitable

Call asynchronous code from an extension module

• Docs
• Source
• PyPI

What is it?

PyAwaitable is the only library to support defining and calling asynchronous Python functions from pure C code.

It was originally designed to be directly part of CPython; you can read the scrapped PEP about it. But, since this library only uses the public ABI, it's better fit outside of CPython, as a library.

Installation

Add it to your project's build process:

# pyproject.toml example with setuptools
[build-system]
requires = ["setuptools", "pyawaitable"]
build-backend = "setuptools.build_meta"

Include it in your extension:

from setuptools import setup, Extension
import pyawaitable

if __name__ == "__main__":
    setup(
        ...,
        ext_modules=[Extension(..., include_dirs=[pyawaitable.include()])]
    )

Example

/*
 Equivalent to the following Python function:

 async def async_function(coro: collections.abc.Awaitable) -> None:
    await coro

 */
static PyObject *
async_function(PyObject *self, PyObject *coro)
{
    // Create our transport between the C world and the asynchronous world.
    PyObject *awaitable = PyAwaitable_New();
    if (awaitable == NULL) {
        return NULL;
    }

    // Mark our Python coroutine, *coro*, for being executed by the event loop.
    if (PyAwaitable_AddAwait(awaitable, coro, NULL, NULL) < 0) {
        Py_DECREF(awaitable);
        return NULL;
    }

    // Return our transport, allowing *coro* to be eventually executed.
    return awaitable;
}

Copyright

pyawaitable is distributed under the terms of the MIT license.