PyO3 Asyncio

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

• PyO3 项目：首页 | GitHub

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

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

• 贡献指南：GitHub

PyO3 Asyncio 是 PyO3 生态系统中的新成员。请随时为此crate提交任何功能请求或错误修复问题。

如果您是新手，最好的入门方式是阅读下面的入门指南！对于 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 = { 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指南中的使用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对象。关键因素是调用异步函数的方式与调用常规函数一样，唯一的区别是我们必须对返回的对象进行特殊处理。

在Python中，有一些特殊的关键词，比如await，但在Rust中等待这个协程，我们首先需要将其转换为Rust版本的协程：一个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(())
}

如果您想了解更多关于协程和awaitables的信息，请查看Python 3 asyncio文档。

在Python中等待Rust Future

这里有一个与之前相同的异步函数，它使用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::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(())
        })
    })
}