pyo3-async-runtimes

You can use uvloop as the event loop in a PyO3 native extension. Since uvloop is a non-standard loop, you cannot use the #[pyo3_async_runtimes::<runtime>::main] proc macro for initialization. Instead, install uvloop in Python before calling your async functions.

Steps:

1. Define your async functions using pyo3_async_runtimes::tokio::future_into_py (or the async-std equivalent).
2. In Python, call uvloop.install().
3. Run your async code using asyncio.run().

// lib.rs
use pyo3::{prelude::*, wrap_pyfunction};

#[pyfunction]
fn rust_sleep(py: Python) -> PyResult<Bound<PyAny>> {
    pyo3_async_runtimes::tokio::future_into_py(py, async {
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
        Ok(())
    })
}

#[pymodule]
fn my_async_module(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;
    Ok(())
}

import asyncio
import uvloop
import my_async_module

uvloop.install()

async def main():
    await my_async_module.rust_sleep()

asyncio.run(main())

To use uvloop in a standalone Rust application (not just a native extension), you must manually initialize Python and install the uvloop policy before starting the pyo3-async-runtimes loop. You cannot use the #[pyo3_async_runtimes::<runtime>::main] macro because the macro executes before you can install uvloop via Python.

//! main.rs

use pyo3::{prelude::*, types::PyType};

fn main() -> PyResult<()> {
    Python::initialize();

    Python::attach(|py| {
        let uvloop = py.import("uvloop")?;
        uvloop.call_method0("install")?;

        // store a reference for the assertion
        let uvloop: Py<PyAny> = uvloop.into();

        pyo3_async_runtimes::async_std::run(py, async move {
            // verify that we are on a uvloop.Loop
            Python::attach(|py| -> PyResult<()> {
                assert!(uvloop
                    .bind(py)
                    .getattr("Loop")?
                    .cast::<PyType>()
                    .unwrap()
                    .is_instance(&pyo3_async_runtimes::async_std::get_current_loop(py)?)
                    ?);
                Ok(())
            })?;

            async_std::task::sleep(std::time::Duration::from_secs(1)).await;

            Ok(())
        })
    })
}

Because Python must control the main thread, you cannot use standard runtime macros like #[tokio::main] or #[async_std::main] in a PyO3 application. Instead, use the pyo3-async-runtimes versions of these macros. These macros ensure the main thread blocks on pyo3_async_runtimes::<runtime>::run_until_complete while allowing Python to manage the main thread.

To use async-std, use the #[pyo3_async_runtimes::async_std::main] attribute on your async fn main().

use pyo3::prelude::*;

#[pyo3_async_runtimes::async_std::main]
async fn main() -> PyResult<()> {
    // PyO3 is initialized - Ready to go

    let fut = Python::attach(|py| -> PyResult<_> {
        let asyncio = py.import("asyncio")?;

        // convert asyncio.sleep into a Rust Future
        pyo3_async_runtimes::async_std::into_future(
            asyncio.call_method1("sleep", (1,))?
        )
    })?;

    fut.await?;

    Ok(())
}

When performing manual conversions, you can use TaskLocals to explicitly carry the Python event loop and contextvars context into Rust. This is necessary for libraries that need to work with any event loop provided by the host application.

Key methods:

• TaskLocals::with_running_loop(py): Constructs locals using the current running loop via asyncio.get_running_loop().
• TaskLocals::copy_context(py): Captures the current Python contextvars context.
• TaskLocals::event_loop(py): Returns a reference to the stored event loop.
• TaskLocals::context(py): Returns a reference to the stored context.

use pyo3::{wrap_pyfunction, prelude::*};

// #[cfg(feature = "tokio-runtime")]
#[pyfunction]
fn sleep(py: Python) -> PyResult<Bound<PyAny>> {
    // Construct the task locals structure with the current running loop and context
    let locals = pyo3_async_runtimes::TaskLocals::with_running_loop(py)?.copy_context(py)?;

    // Convert the async move { } block to a Python awaitable
    pyo3_async_runtimes::tokio::future_into_py_with_locals(py, locals.clone(), async move {
        let py_sleep = Python::attach(|py| {
            // Use the captured locals to ensure the inner Python call uses the correct loop/context
            pyo3_async_runtimes::into_future_with_locals(
                &locals,
                py.import("asyncio")?.call_method1("sleep", (1,))?
            )
        })?;

        py_sleep.await?;

        Ok(())
    })
}