pyo3-stub-gen：Rust 与 Python 互操作的利器-CSDN博客

本文链接：https://blog.csdn.net/gitblog_01092/article/details/147853244

pyo3-stub-gen：Rust 与 Python 互操作的利器

pyo3-stub-gen Stub file (*.pyi) generator for PyO3 项目地址: https://gitcode.com/gh_mirrors/py/pyo3-stub-gen

项目介绍

pyo3-stub-gen 是一个针对 [PyO3] 和 [maturin] 项目的 Python 存根文件 (*.pyi) 生成工具。它旨在帮助开发者从 Rust 代码自动生成 Python 类型注解，以提高 Rust 与 Python 之间的互操作性。通过半自动化的方式，pyo3-stub-gen 提供了一个默认的转换器，并且在默认转换器无法满足需求时，允许开发者手动指定转换。

项目技术分析

pyo3-stub-gen 利用 Rust 的 proc-macro 机制，通过 [pyo3-stub-gen-derive] 提供了一个默认的转换器。这个转换器能够处理大多数情况，但在某些边缘情况下可能需要手动介入。开发者可以通过 #[gen_stub_pyfunction] 等宏注解 Rust 代码，从而生成相应的 Python 存根文件。

项目的设计理念是在保持 Rust 和 Python 之间类型系统的差异性的同时，尽可能自动化地生成存根文件。由于两种语言的类型系统存在差异，完全自动化的转换是不可能的。因此，pyo3-stub-gen 采取了半自动化的方法，允许开发者对默认转换器生成的结果进行手动调整和补充。

项目技术应用场景

pyo3-stub-gen 适用于以下场景：

Rust 与 Python 的混合项目：对于使用 maturin 构建系统的 Rust 和 Python 混合项目，pyo3-stub-gen 可以自动生成 Python 类型注解，提高开发效率和代码质量。
Rust 扩展模块：对于需要将 Rust 代码作为 Python 扩展模块使用的项目，pyo3-stub-gen 可以生成相应的类型注解，使得 Python 代码在调用 Rust 功能时拥有更好的类型支持。
自动化工具链：在自动化工具链中，pyo3-stub-gen 可以作为生成 Python 类型注解的一环，为整个工具链提供类型支持。

项目特点

pyo3-stub-gen 的主要特点如下：

半自动化转换：提供了默认的转换器，同时允许开发者手动指定转换，以处理边缘情况。
易于集成：通过 proc-macro 机制，可以轻松集成到现有的 Rust 代码中。
类型系统兼容性：尊重 Rust 和 Python 之间的类型系统差异，提供灵活的类型转换方案。
社区支持：与 [PyO3] 和 [maturin] 社区紧密合作，获得持续的技术支持和更新。

以下是 pyo3-stub-gen 的一个基本使用示例：

use pyo3::prelude::*;

#[pyfunction]
fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
    Ok((a + b).to_string())
}

#[pymodule]
fn your_module_name(m: &Bound<PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
    Ok(())
}

// 使用 pyo3-stub-gen 的宏
use pyo3_stub_gen::{derive::gen_stub_pyfunction, define_stub_info_gatherer};

#[gen_stub_pyfunction]
#[pyfunction]
fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
    Ok((a + b).to_string())
}

#[pymodule]
fn your_module_name(m: &Bound<PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;
    Ok(())
}

// 定义收集存根信息的函数
define_stub_info_gatherer!(stub_info);

通过上述代码，开发者可以生成一个 Python 存根文件，从而为 Python 代码提供类型注解。

总之，pyo3-stub-gen 是一个强大的工具，它为 Rust 和 Python 的互操作性提供了重要的支持。通过使用 pyo3-stub-gen，开发者可以更加高效地构建混合语言的项目，并享受类型安全带来的好处。

pyo3-stub-gen Stub file (*.pyi) generator for PyO3 项目地址: https://gitcode.com/gh_mirrors/py/pyo3-stub-gen