PyO3完全入门：Rust编写Python扩展模块的终极指南，5分钟打造你的第一个高性能扩展

PyO3完全入门Rust编写Python扩展模块的终极指南5分钟打造你的第一个高性能扩展【免费下载链接】pyo3Rust bindings for the Python interpreter项目地址: https://gitcode.com/gh_mirrors/py/pyo3PyO3 是 Python 官方 CPython 的 Rust bindingsRust 绑定库它让你用 Rust 编写 Python 扩展模块把 Python 中最耗时的计算逻辑加速数倍乃至数百倍。作为 Python 生态中最成熟的 Rust 扩展方案PyO3 被 polars、pydantic-core、orjson、tiktoken 等明星项目采用。无论你是想给 Python 项目提速还是初探 Rust这篇指南都能在 5 分钟内带你写出第一个可运行的高性能扩展。一、PyO3 是什么为什么选择它想象一下你的 Python 数据处理脚本 90% 的时间卡在一个纯 Python 的循环上。C 扩展写起来痛苦、容易内存泄漏而 PyO3 提供了更优雅的答案——用 Rust 的安全性和性能配合 Python 的简洁体验。PyO3 的核心能力可以用三个概念概括概念对应宏作用Python 模块#[pymodule]生成可被import的原生模块Python 函数#[pyfunction]把 Rust 函数暴露给 Python 调用Python 类#[pyclass]#[pymethods]用 Rust 结构体定义带方法的 Python 类它支持双向互操作Rust 写扩展给 Python 用也能在 Rust 二进制中嵌入 Python 解释器执行 Python 代码。二、环境准备3 步装好 PyO3 扩展开发工具链PyO3 要求Rust 1.83和Python 3.9同时支持 PyPy 7.3、GraalPy 25.0。构建工具官方推荐 maturin配置最少、开箱即用。# 1. 创建项目目录并建立 Python 虚拟环境 mkdir string_sum cd string_sum python -m venv .env source .env/bin/activate # 2. 安装构建工具 maturin pip install maturin # 3. 初始化一个 pyo3 绑定的项目 maturin init --bindings pyo3完成后目录里会出现两个关键文件Cargo.tomlRust 项目的配置文件声明pyo3依赖src/lib.rs扩展模块的 Rust 源码 详细的环境搭建说明可参考仓库自带指南guide/src/getting-started.md三、5 分钟上手写出第一个 Rust 高性能扩展maturin init生成的src/lib.rs就是最精简的入门模板只有一段核心代码#[pyo3::pymodule] mod string_sum { use pyo3::prelude::*; /// Formats the sum of two numbers as string. #[pyfunction] fn sum_as_string(a: usize, b: usize) - PyResultString { Ok((a b).to_string()) } }接下来一条命令完成编译和安装maturin develop然后在 Python 中直接调用 import string_sum string_sum.sum_as_string(5, 20) 25就这么简单——你已经拥有了第一个由 Rust 驱动的高性能 Python 扩展模块。以后修改 Rust 代码只需重跑maturin develop即可重新编译测性能时记得加--release开启优化maturin develop --release。四、三大核心宏模块、函数与类PyO3 用 Rust 过程宏自动处理所有与 CPython 的胶水代码。下面快速认识三件套1.#[pymodule]—— 生成 Python 模块模块名必须与共享库文件名一致否则 Python 会报ImportError。Rust 的文档注释会自动变成 Python 的 docstring。详见guide/src/module.md2.#[pyfunction]—— 暴露 Rust 函数Rust 类型会自动映射到 Python 类型usize → int、String → str、str → str、VecT → list……类型转换表完整收录于 guide/src/conversions/tables.md。3.#[pyclass]#[pymethods]—— 定义 Python 类Rust 结构体加上这两个宏就拥有了__init__、__getitem__等完整的 Python 对象协议能力。仓库中的getitem示例演示了如何优雅地同时支持整数索引和切片访问examples/getitem/src/lib.rs#[pyclass] struct ExampleContainer { max_length: i32 } #[pymethods] impl ExampleContainer { #[new] fn new() - Self { ExampleContainer { max_length: 100 } } fn __getitem__(self, key: Bound_, PyAny) - PyResulti32 { /* ... */ } }五、释放 Rust 的威力多线程并行加速为什么非要用 Rust因为 Python 有 GIL全局解释器锁限制并行而 PyO3 的 Rust 代码可以完全绕开 GIL。官方示例word-count展示了这个经典场景统计大文本中的单词出现次数用rayon库实现并行搜索性能远超单线程版本/// Searches for the word, parallelized by rayon #[pyfunction] fn search(contents: str, needle: str) - usize { contents.par_lines() .map(|line| count_line(line, needle)) .sum() }Python 侧调用方式与纯 Python 函数毫无区别from word_count import search search(big_text, rust) # 多核并行速度起飞示例完整源码examples/word-count/src/lib.rs。更多并行用法可阅读并行章节指南guide/src/parallelism.md六、仓库导航去哪找你要的资料PyO3 仓库自带了完整的用户指南mdbook 格式和测试项目建议按需查阅 官方指南目录总览guide/src/SUMMARY.md 入门与安装guide/src/getting-started.md⚙️ 模块/函数/类教程guide/src/rust-from-python.md、guide/src/class.md 类型转换对照表guide/src/conversions/tables.md️ 架构设计文档进阶阅读Architecture.md 可直接运行的示例集合examples/README.md 常见类型转换实现src/conversions/mod.rs如果遇到问题FAQ 章节几乎覆盖了所有常见坑guide/src/faq.md七、进阶之路这些能力等你解锁入门之后PyO3 还有大量性能利器值得探索abi3特性编译一个兼容多版本 Python 的 wheel发布到 PyPI 一次搞定async 支持通过experimental-async特性让 Rust 函数支持 Python 的async/await嵌入 Python反过来在 Rust 程序里运行 Python 代码把它当脚本语言用免 GIL 支持官方已支持 Python 3.13 的 free-threading 模式guide/src/free-threading.md性能调优官方性能章节总结了大量实测优化技巧guide/src/performance.md八、总结步骤命令/动作耗时1. 安装工具链Rust 1.83 / Python 3.9 /pip install maturin~2 分钟2. 初始化项目maturin init --bindings pyo310 秒3. 编写扩展修改src/lib.rs中的#[pyfunction]2 分钟4. 编译安装maturin develop首次约 1 分钟5. Python 调用import your_module0 秒PyO3 让Python 的体验 Rust 的性能成为现实宏替你写完全部 C API 样板代码类型系统保证内存安全maturin让打包发布像pip install一样顺滑。从string_sum起步到 rayon 并行加速你的高性能 Python 扩展之路已经开启——现在就去创建你的第一个 PyO3 项目吧【免费下载链接】pyo3Rust bindings for the Python interpreter项目地址: https://gitcode.com/gh_mirrors/py/pyo3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考