PyO3 开源项目安装与使用手册

卓桔洋

于 2024-10-10 07:38:42 发布

阅读量1k

点赞数 15

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00961/article/details/142804444

PyO3 开源项目安装与使用手册

pyo3 Rust bindings for the Python interpreter 项目地址: https://gitcode.com/gh_mirrors/py/pyo3

PyO3 是一个强大的 Rust 绑定库，它允许开发者创建原生的 Python 扩展模块，并从 Rust 程序中运行和交互 Python 代码。本手册将引导您了解 PyO3 的基本架构，以及如何通过其关键的文件和配置来上手此项目。

1. 项目目录结构及介绍

PyO3 的仓库遵循标准的 Rust 项目布局，但包含了一些特定于 Python 绑定的特有部分。以下是核心目录结构概述：

src: 包含了主要的库代码，如 Rust 的核心逻辑实现。
- lib.rs: 核心库入口，定义了与 Python 交互的主要功能，包括 [pymodule] 定义的 Python 模块。
examples: 提供多个示例程序，演示如何使用 PyO3 创建 Python 可调用的 Rust 函数。
tests: 单元测试和集成测试，用于验证 PyO3 的正确性。
benches: 性能基准测试代码，评估不同场景下的性能表现。
pyo3-macros: 支持自定义的宏，简化绑定代码的编写。
pyo3-ffi: 处理与 Python 解释器的底层 Foreign Function Interface（FFI）交互。
Cargo.toml: 项目的核心配置文件，定义依赖关系、版本信息、构建指令等。
README.md: 项目简介，快速入门指南。
LICENSE-APACHE, LICENSE-MIT: 许可证文件，表明项目采用双许可证模式。

2. 项目的启动文件介绍

对于 PyO3 项目而言，没有单一的“启动文件”概念，而是依赖于 Rust 的 main.rs 或通过 Cargo.toml 配置的库入口([lib])指定的文件作为起点。但在用户应用层面上，如果您想要创建一个能够立即运行的示例应用，通常会从 main.rs 入手，在这个文件里初始化和运行 Rust 程序，并且可能通过 PyO3 来调用 Python 相关的逻辑。

示例：在 Rust 中启动 Python 代码

假设您想从 Rust 应用中执行 Python 脚本，您的 main.rs 可能像这样：

use pyo3::prelude::*;

fn main() {
    Python::with_gil(|py| {
        let result = py.run("print('Hello from Python!')", None, None);
        if let Err(err) = result {
            println!("Error executing Python code: {}", err);
        }
    });
}

3. 项目的配置文件介绍

Cargo.toml 是管理 PyO3 项目配置的关键。它不仅定义了项目的基本信息，如包名、版本、作者，还配置了 Rust 编译设置、依赖关系和特殊编译特征。

以下是一个基础的 Cargo.toml 示例，展示如何为 PyO3 项目设定依赖：

[package]
name = "your_project_name"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]
name = "your_library_name"

[dependencies]
pyo3 = { version = "0.22.3", features = ["extension-module", "auto-initialize"] }

[features]
default = []

这里：