使用说明

与 PyO3 一样，PyO3 Asyncio 支持以下软件版本

• Python 3.7 及以上版本（CPython 和 PyPy）
• Rust 1.48 及以上版本

PyO3 Asyncio 入门指南

如果您正在使用一个利用异步函数的 Python 库，或者希望为异步 Rust 库提供 Python 绑定，那么 pyo3-asyncio 可能正是您所需要的工具。它提供了在 Python 和 Rust 之间异步函数的转换，并支持流行的 Rust 运行时，如 tokio 和 async-std。此外，所有异步 Python 代码都在默认的 asyncio 事件循环上运行，因此 pyo3-asyncio 应该与现有的 Python 库很好地协同工作。

在接下来的章节中，我们将对 pyo3-asyncio 进行概述，解释如何使用 PyO3 调用异步 Python 函数，如何从 Python 调用异步 Rust 函数，以及如何配置代码库来管理这两个运行时。

快速入门

以下是一些立即开始使用的示例！这些示例中概念的更详细解释可以在接下来的章节中找到。

Rust 应用程序

在这里，我们初始化运行时，导入 Python 的 asyncio 库，并使用 Python 的默认 EventLoop 和 async-std 运行给定的 future，直到完成。在 future 中，我们将 asyncio 睡眠转换为 Rust future 并等待它。

# Cargo.toml dependencies
[dependencies]
pyo3 = { version = "0.20" }
pyo3-asyncio-0-21 = { version = "0.20", features = ["attributes", "async-std-runtime"] }
async-std = "1.9"

//! main.rs

use pyo3::prelude::*;

#[pyo3_asyncio_0_21::async_std::main]
async fn main() -> PyResult<()> {
    let fut = Python::with_gil(|py| {
        let asyncio = py.import_bound("asyncio")?;
        // convert asyncio.sleep into a Rust Future
        pyo3_asyncio_0_21::async_std::into_future(asyncio.call_method1("sleep", (1.into_py(py),))?)
    })?;

    fut.await?;

    Ok(())
}

同样的应用程序可以写成使用 tokio，通过使用 #[pyo3_asyncio_0_21::tokio::main] 属性。

# Cargo.toml dependencies
[dependencies]
pyo3 = { version = "0.20" }
pyo3-asyncio-0-21 = { version = "0.20", features = ["attributes", "tokio-runtime"] }
tokio = "1.9"

//! main.rs

use pyo3::prelude::*;

#[pyo3_asyncio_0_21::tokio::main]
async fn main() -> PyResult<()> {
    let fut = Python::with_gil(|py| {
        let asyncio = py.import_bound("asyncio")?;
        // convert asyncio.sleep into a Rust Future
        pyo3_asyncio_0_21::tokio::into_future(asyncio.call_method1("sleep", (1.into_py(py),))?)
    })?;

    fut.await?;

    Ok(())
}

有关此库的更多使用细节，请参阅 API 文档 和下面的简介。

PyO3 本地 Rust 模块

PyO3 Asyncio 还可以用来编写具有异步函数的本地模块。

将 [lib] 部分添加到 Cargo.toml，使您的库成为一个 Python 可以导入的 cdylib。

[lib]
name = "my_async_module"
crate-type = ["cdylib"]

使用启用了 extension-module 功能的 pyo3 使您的项目依赖，并选择您的 pyo3-asyncio 运行时

对于 async-std

[dependencies]
pyo3 = { version = "0.20", features = ["extension-module"] }
pyo3-asyncio-0-21 = { version = "0.20", features = ["async-std-runtime"] }
async-std = "1.9"

对于 tokio

[dependencies]
pyo3 = { version = "0.20", features = ["extension-module"] }
pyo3-asyncio-0-21 = { version = "0.20", features = ["tokio-runtime"] }
tokio = "1.9"

导出一个使用 async-std 的异步函数

//! lib.rs

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

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

#[pymodule]
fn my_async_module(py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;

    Ok(())
}

如果您想使用 tokio，则您的模块应如下所示

//! lib.rs

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

#[pyfunction]
fn rust_sleep(py: Python) -> PyResult<Bound<PyAny>> {
    pyo3_asyncio_0_21::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: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;
    Ok(())
}

您可以使用 maturin（有关设置说明，请参阅 PyO3 指南中的 使用 Rust 的 Python 部分）构建您的模块。之后，您应该能够运行 Python REPL 来尝试它。

maturin develop && python3
🔗 Found pyo3 bindings
🐍 Found CPython 3.8 at python3
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
Python 3.8.5 (default, Jan 27 2021, 15:41:15)
[GCC 9.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>>
>>> from my_async_module import rust_sleep
>>>
>>> async def main():
>>>     await rust_sleep()
>>>
>>> # should sleep for 1s
>>> asyncio.run(main())
>>>

在 Rust 中等待异步 Python 函数

让我们看看一个简单的异步 Python 函数

# Sleep for 1 second
async def py_sleep():
    await asyncio.sleep(1)

Python 中的异步函数只是返回一个 coroutine 对象的函数。对于我们来说，我们实际上并不需要了解太多关于这些 coroutine 对象。关键因素是调用一个 async 函数的方式与调用一个普通函数的方式相同，唯一的区别是我们必须对它返回的对象做些特殊处理。

通常在 Python 中，这种特殊处理是 await 关键字，但为了在 Rust 中等待这个协程，我们首先需要将其转换为 Rust 的 coroutine 版本：一个 Future。这就是 pyo3-asyncio 发挥作用的地方。`pyo3_asyncio_0_21::into_future` 为我们执行这个转换。

use pyo3::prelude::*;

#[pyo3_asyncio_0_21::tokio::main]
async fn main() -> PyResult<()> {
    let future = Python::with_gil(|py| -> PyResult<_> {
        // import the module containing the py_sleep function
        let example = py.import_bound("example")?;

        // calling the py_sleep method like a normal function
        // returns a coroutine
        let coroutine = example.call_method0("py_sleep")?;

        // convert the coroutine into a Rust future using the
        // tokio runtime
        pyo3_asyncio_0_21::tokio::into_future(coroutine)
    })?;

    // await the future
    future.await?;

    Ok(())
}

如果您想了解更多有关通用 协程 和 awaitables 的信息，请查看 Python 3 asyncio 文档 以获取更多信息。

在 Python 中等待 Rust 未来

这里我们有与之前相同的异步函数，使用 async-std 运行时在 Rust 中编写

/// Sleep for 1 second
async fn rust_sleep() {
    async_std::task::sleep(std::time::Duration::from_secs(1)).await;
}

类似于 Python，Rust 的异步函数也返回一个称为 Future 的特殊对象

let future = rust_sleep();

我们可以将这个 Future 对象转换为 Python，使其成为 awaitable。这告诉 Python 您可以使用 await 关键字与它一起使用。为了做到这一点，我们将调用 pyo3_asyncio_0_21::async_std::future_into_py

use pyo3::prelude::*;

async fn rust_sleep() {
    async_std::task::sleep(std::time::Duration::from_secs(1)).await;
}

#[pyfunction]
fn call_rust_sleep(py: Python) -> PyResult<Bound<PyAny>> {
    pyo3_asyncio_0_21::async_std::future_into_py(py, async move {
        rust_sleep().await;
        Ok(())
    })
}

在 Python 中，我们可以像调用任何其他异步函数一样调用这个 pyo3 函数

from example import call_rust_sleep

async def rust_sleep():
    await call_rust_sleep()

管理事件循环

Python 的事件循环需要一些特殊处理，特别是关于主线程。Python 的某些 asyncio 功能，如适当的信号处理，需要控制主线程，而这通常与 Rust 不兼容。

幸运的是，Rust 的事件循环非常灵活，且 不需要 控制主线程，因此在我们 pyo3-asyncio 中，我们决定最佳方式来处理 Rust/Python 互操作是仅仅将主线程让给 Python，并在后台运行 Rust 的事件循环。遗憾的是，由于大多数事件循环实现 偏好 控制主线程，这仍然可能使某些事情变得尴尬。

PyO3 Asyncio 初始化

由于 Python 需要控制主线程，我们无法使用 Rust 运行时提供的方便的 proc macros 来处理 main 函数或 #[test] 函数。相反，PyO3 的初始化必须从 main 函数中完成，并且主线程必须阻塞在 pyo3_asyncio_0_21::run_forever 或 pyo3_asyncio_0_21::async_std::run_until_complete 上。

由于我们必须在这些函数上阻塞，所以我们不能使用 #[async_std::main] 或 #[tokio::main]，因为在一个异步函数中进行长阻塞调用不是一个好主意。

内部，这些 #[main] proc macros 被扩展为类似这样的内容

fn main() {
    // your async main fn
    async fn _main_impl() { /* ... */ }
    Runtime::new().block_on(_main_impl());
}

在由 block_on 驱动的 Future 中进行长时间的阻塞调用会阻止该线程执行其他操作，并可能对某些运行时造成麻烦（实际上，这也会导致单线程运行时死锁！）。许多运行时都提供某种 spawn_blocking 机制来避免这个问题，但同样，我们在这里无法使用它，因为我们需要在 主 线程上进行阻塞。

因此，pyo3-asyncio 提供了自己的 proc macros 来提供这种初始化。这些宏旨在模仿 async-std 和 tokio 的初始化，同时满足 Python 运行时的需求。

以下是一个使用 async-std 运行时的 PyO3 初始化的完整示例

use pyo3::prelude::*;

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

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

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

    fut.await?;

    Ok(())
}

关于 asyncio.run 的说明

在 Python 3.7+ 中，使用 asyncio 运行顶层协程的推荐方法是使用 asyncio.run。在 v0.13 中，由于初始化问题，我们不建议使用此函数，但在 v0.14 中，使用此函数是完全可以的...但有条件。

import asyncio

from my_async_module import rust_sleep

asyncio.run(rust_sleep())

Traceback (most recent call last):
  File "example.py", line 5, in <module>
    asyncio.run(rust_sleep())
RuntimeError: no running event loop

import asyncio

from my_async_module import rust_sleep

# Calling main will just construct the coroutine that later calls rust_sleep.
# - This ensures that rust_sleep will be called when the event loop is running,
#   not before.
async def main():
    await rust_sleep()

# Run the main() coroutine at the top-level instead
asyncio.run(main())

# Cargo.toml

[lib]
name = "my_async_module"
crate-type = ["cdylib"]

[dependencies]
pyo3 = { version = "0.20", features = ["extension-module"] }
pyo3-asyncio-0-21 = { version = "0.20", features = ["tokio-runtime"] }
async-std = "1.9"
tokio = "1.9"

//! lib.rs

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

#[pyfunction]
fn rust_sleep(py: Python) -> PyResult<Bound<PyAny>> {
    pyo3_asyncio_0_21::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: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(rust_sleep, m)?)?;

    Ok(())
}

$ maturin develop && python3
🔗 Found pyo3 bindings
🐍 Found CPython 3.8 at python3
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
Python 3.8.8 (default, Apr 13 2021, 19:58:26)
[GCC 7.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>> import uvloop
>>>
>>> import my_async_module
>>>
>>> uvloop.install()
>>>
>>> async def main():
...     await my_async_module.rust_sleep()
...
>>> asyncio.run(main())
>>>

[dependencies]
async-std = "1.9"
pyo3 = "0.20"
pyo3-asyncio-0-21 = { version = "0.20", features = ["async-std-runtime"] }

//! main.rs

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

fn main() -> PyResult<()> {
    pyo3::prepare_freethreaded_python();

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

        // store a reference for the assertion
        let uvloop = PyObject::from(uvloop);

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

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

            Ok(())
        })
    })
}