pyo3-stub-gen

PyO3的Python stub文件 (*.pyi) 生成器，用于具有 PyO3 和 maturin 项目的项目。

crate名称	crates.io	docs.rs	文档（主要部分）
pyo3-stub-gen
pyo3-stub-gen-derive

设计

我们的目标是创建一个从Rust代码生成的stub文件 *.pyi，然而，由于Rust和Python类型系统之间的差异以及proc-macro的限制，自动完整翻译是不可能的。我们采取半自动方法

• 提供一个默认的翻译器，它将适用于 大多数 情况，但不是 所有 情况
• 还提供了一种手动指定翻译的方法。

如果默认翻译器不起作用，用户可以手动指定翻译，这些手动翻译可以与默认翻译器生成的结果集成。因此，用户可以尽可能多地使用默认翻译器，仅针对边缘情况指定翻译。

pyo3-stub-gen crate提供了手动指定翻译的方法，而 pyo3-stub-gen-derive crate提供了基于 pyo3-stub-gen 机制的默认翻译器作为proc-macro。

用法

如果您正在寻找一个工作示例，请参阅 示例目录。

以下是基于 pyo3-stub-gen crate 的基本使用说明，该 crate 基于 examples/pure 示例。

使用 proc-macro 注释 Rust 代码

此 crate 提供了一个过程宏 #[gen_stub_pyfunction] 以及其他宏来生成 Python stub 文件。它与 PyO3 的 #[pyfunction] 宏一起使用。让我们考虑一个简单的 PyO3 项目

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

要为该项目生成 stub 文件，请按照以下方式修改

use pyo3::prelude::*;
use pyo3_stub_gen::{derive::gen_stub_pyfunction, define_stub_info_gatherer};

#[gen_stub_pyfunction]  // Proc-macro attribute to register a function to stub file generator.
#[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 a function to gather stub information.
define_stub_info_gatherer!(stub_info);

生成 stub 文件

然后，在 src/bin/stub_gen.rs 中创建一个可执行目标，以生成 stub 文件

use pyo3_stub_gen::Result;

fn main() -> Result<()> {
    // `stub_info` is a function defined by `define_stub_info_gatherer!` macro.
    let stub = pure::stub_info()?;
    stub.generate()?;
    Ok(())
}

并在 [lib] 部分的 Cargo.toml 中添加 rlib（除了 cdylib）

[lib]
crate-type = ["cdylib", "rlib"]

当执行时，此目标生成一个 stub 文件 pure.pyi

cargo run --bin stub_gen

stub 文件会自动被 maturin 找到，并包含在 wheel 包中。有关更多详细信息，请参阅 maturin 文档。

贡献

待定。

许可证

© 2024 Jij Inc。

本项目受以下其中之一许可

• Apache 许可证 2.0 版，(LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 https://opensource.org/licenses/MIT)

任选其一。

链接

• pybind11-stubgen
  • 基于 pybind11 的 C++ 项目的 stub 文件生成器。