PyO3 Asyncio

这是对 pyo3-asyncio 的分支，以提供与 PyO3 0.21 的兼容性。这可能是未来永久分支的基础，具体取决于原始 pyo3-asyncio 维护者的状态。

Rust 绑定 Python 的 Asyncio 库。此存储库促进 Rust Futures 和 Python 协程之间的交互，并管理它们对应的事件循环的生命周期。

• PyO3 项目：主页 | GitHub

• PyO3 Asyncio API 文档：稳定版 | 主分支

• Async/Await 指南：稳定版 | 主分支

• 贡献说明：GitHub

PyO3 Asyncio 是 PyO3 生态系统中的 全新 部分。请随时为此存储库打开任何有关功能请求或错误修复的问题。

如果您是新手，阅读以下入门指南是最佳起点！对于 v0.13 和 v0.14 用户，我强烈建议阅读 迁移部分，以了解 v0.14 和 v0.15 中发生了哪些变化。

使用方法

与 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指南中的在Python中使用Rust部分以获取设置说明）。之后，您应该能够运行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对象。关键因素在于，调用异步函数就像调用一个普通函数一样，唯一的区别是我们必须对它返回的对象做些特别的事情。

通常在Python中，这特别的事情就是await关键字，但为了在Rust中等待这个coroutine，我们首先需要将其转换为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(())
}

如果您想了解更多关于协程（coroutines）和通用可等待对象（awaitables）的信息，请查看Python 3 asyncio 文档以获取更多信息。

在 Python 中等待 Rust 未来

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

/// 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，使其变为可等待的。这告诉 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]，因为在异步函数中进行长时间阻塞调用不是一个好主意。

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(())
}

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(())
        })
    })
}