PyO3 Asyncio

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

• PyO3 项目：首页 | GitHub

• PyO3 Asyncio API 文档：稳定版 | master

• 异步/Await 指南：稳定版 | 主要

• 贡献指南：github

PyO3 Asyncio 是 PyO3 生态系统的一个全新的部分。对于此包的功能请求或错误修复，请随时提出任何问题。

如果您是新手，阅读以下入门指南是开始的最佳方式！对于 v0.13.2 和 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 = { version = "0.20", features = ["attributes", "async-std-runtime"] }
async-std = "1.9"

//! main.rs

use pyo3::prelude::*;

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

    fut.await?;

    Ok(())
}

相同的程序可以写成使用tokio，使用#[pyo3_asyncio::tokio::main]属性。

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

//! main.rs

use pyo3::prelude::*;

#[pyo3_asyncio::tokio::main]
async fn main() -> PyResult<()> {
    let fut = Python::with_gil(|py| {
        let asyncio = py.import("asyncio")?;
        // convert asyncio.sleep into a Rust Future
        pyo3_asyncio::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 = { version = "0.20", features = ["async-std-runtime"] }
async-std = "1.9"

对于tokio

[dependencies]
pyo3 = { version = "0.20", features = ["extension-module"] }
pyo3-asyncio = { 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<&PyAny> {
    pyo3_asyncio::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<&PyAny> {
    pyo3_asyncio::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中等待这个协程，我们首先需要将其转换为Rust的coroutine版本：一个Future。这正是pyo3-asyncio发挥作用的地方。 pyo3_asyncio::into_future为我们执行这个转换

use pyo3::prelude::*;

#[pyo3_asyncio::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("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::tokio::into_future(coroutine)
    })?;

    // await the future
    future.await?;

    Ok(())
}

如果您想了解更多关于 协程 和 可等待对象 的信息，请查看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，使其成为 可等待。这告诉 Python 可以使用 await 关键字。为了做到这一点，我们将调用 pyo3_asyncio::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<&PyAny> {
    pyo3_asyncio::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 宏来处理 main 函数或 #[test] 函数。相反，PyO3 的初始化必须从 main 函数中进行，并且主线程必须在 pyo3_asyncio::run_forever 或 pyo3_asyncio::async_std::run_until_complete 上阻塞。

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

use pyo3::prelude::*;

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

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

        // convert asyncio.sleep into a Rust Future
        pyo3_asyncio::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 = { 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<&PyAny> {
    pyo3_asyncio::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 = { 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("uvloop")?;
        uvloop.call_method0("install")?;

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

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

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

            Ok(())
        })
    })
}