Crate pyo3_asyncio

Rust Bindings to the Python Asyncio Event Loop

Motivation

This crate aims to provide a convenient interface to manage the interop between Python and Rust’s async/await models. It supports conversions between Rust and Python futures and manages the event loops for both languages. Python’s threading model and GIL can make this interop a bit trickier than one might expect, so there are a few caveats that users should be aware of.

Why Two Event Loops

Currently, we don’t have a way to run Rust futures directly on Python’s event loop. Likewise, Python’s coroutines cannot be directly spawned on a Rust event loop. The two coroutine models require some additional assistance from their event loops, so in all likelihood they will need a new unique event loop that addresses the needs of both languages if the coroutines are to be run on the same loop.

It’s not immediately clear that this would provide worthwhile performance wins either, so in the interest of keeping things simple, this crate creates and manages the Python event loop and handles the communication between separate Rust event loops.

Python’s Event Loop

Python is very picky about the threads used by the asyncio executor. In particular, it needs to have control over the main thread in order to handle signals like CTRL-C correctly. This means that Cargo’s default test harness will no longer work since it doesn’t provide a method of overriding the main function to add our event loop initialization and finalization.

Rust’s Event Loop

Currently only the async-std and Tokio runtimes are supported by this crate.

In the future, more runtimes may be supported for Rust.

Features

Items marked with attributes are only available when the attributes Cargo feature is enabled:

[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["attributes"]

Items marked with async-std-runtime are only available when the async-std-runtime Cargo feature is enabled:

[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["async-std-runtime"]

Items marked with tokio-runtime are only available when the tokio-runtime Cargo feature is enabled:

[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["tokio-runtime"]

Items marked with testing are only available when the testing Cargo feature is enabled:

[dependencies.pyo3-asyncio]
version = "0.13.0"
features = ["testing"]

Re-exports

pub use inventory;

Modules

async_std	async-std-runtime PyO3 Asyncio functions specific to the async-std runtime
generic	Generic implementations of PyO3 Asyncio utilities that can be used for any Rust runtime
testing	testing Utilities for writing PyO3 Asyncio tests
tokio	tokio-runtime PyO3 Asyncio functions specific to the tokio runtime

Functions

get_event_loop	Get a reference to the Python Event Loop from Rust
into_future	Convert a Python awaitable into a Rust Future
run_forever	Run the event loop forever
try_close	Shutdown the event loops and perform any necessary cleanup
try_init	Attempt to initialize the Python and Rust event loops
with_runtime	Wraps the provided function with the initialization and finalization for PyO3 Asyncio