Rust扩展的Setuptools插件

setuptools-rust是setuptools的一个插件，用于构建使用PyO3或rust-cpython实现的Rust Python扩展。

像编译和分发用C语言编写的Python扩展一样轻松地编译和分发用Rust编写的Python扩展。

快速入门

以下是一个非常基础的教程，展示如何在pyproject.toml中使用setuptools-rust。它假设你已经有了一些想要分发的Python和Rust文件。你可以在github仓库的examples/hello-world目录中看到这些文件的示例。PyO3文档中有关于如何用Rust编写Python模块的详细信息。

hello-world
├── python
│   └── hello_world
│       └── __init__.py
└── rust
    └── lib.rs

一旦实现文件就位，我们需要添加一个pyproject.toml文件，告诉任何想要使用你的项目的人如何构建它。在这个文件中，我们使用表的数组（TOML术语，相当于Python的字典列表）来指定[[tool.setuptools-rust.ext-modules]]，以定义用Rust编写的不同扩展模块：

# pyproject.toml
[build-system]
requires = ["setuptools", "setuptools-rust"]
build-backend = "setuptools.build_meta"

[project]
name = "hello-world"
version = "1.0"

[tool.setuptools.packages]
# 纯Python包/模块
find = { where = ["python"] }

[[tool.setuptools-rust.ext-modules]]
# 要嵌套到Python包中的私有Rust扩展模块
target = "hello_world._lib"  # 名称的最后一部分（如"_lib"）必须与Cargo.toml中的lib.name匹配，
                             # 但你可以添加前缀以将其嵌套到Python包中。
path = "Cargo.toml"      # 默认值，可以省略
binding = "PyO3"         # 默认值，可以省略

每个扩展模块应直接映射到Cargo清单文件中相应的[lib]表：

# Cargo.toml
[package]
name = "hello-world"
version = "0.1.0"
edition = "2021"

[dependencies]
pyo3 = "0.22.0"

[lib]
name = "_lib"  # 要嵌套到Python包中的私有模块，
               # 需要与带有`[#pymodule]`属性的函数名匹配
path = "rust/lib.rs"
crate-type = ["cdylib"]  # Python导入共享库所需

# 有关更多键及其定义，请参阅https://doc.rust-lang.org/cargo/reference/manifest.html
# 另请参阅PyO3文档中关于编写Cargo.toml文件的内容：https://pyo3.rs

你还需要告诉Setuptools，从源代码分发构建项目时需要Rust文件。这可以通过MANIFEST.in（见下面的示例）或通过像setuptools-scm这样的插件来完成。

# MANIFEST.in
包含 Cargo.toml
递归包含 rust 目录下所有 *.rs 文件

准备好这些文件后，你可以在虚拟环境中安装项目，以测试并确保一切正常工作：

# cd hello-world
python3 -m venv .venv
source .venv/bin/activate  # Linux 或 macOS
.venv\Scripts\activate     # Windows
python -m pip install -e .
python
>>> import hello_world
# ... 尝试运行新扩展模块中的一些内容 ...
# ... 最好用 pytest 编写一些测试 ...

后续步骤和最终说明

当你准备分发项目时，请查看文档中关于构建轮子的说明。
还支持交叉编译，可以使用 crossenv、cross 或 cargo-zigbuild 之一。例子请参见 ci.yml 中的 test-crossenv、test-cross 和 test-zigbuild GitHub Actions 任务。
如果你想分发用 Rust 编写的二进制可执行文件（而不是可以被 Python 运行时导入的库），你也可以使用 [[tool.setuptools-rust.bins]]（而不是 [[tool.setuptools-rust.ext-modules]]）。但请注意，同时分发库和可执行文件（或多个可执行文件）可能会显著增加包索引分发的 wheel 文件大小，从而增加构建、下载和安装时间。另一种方法是使用调用 Rust 实现（通过 PyO3 绑定暴露）的 Python 入口点。更多见解请参考 hello-world 示例。
完整的配置选项参考，请查看API 参考。你可以在 [[tool.setuptools-rust.ext-modules]] 中使用 RustExtension 类定义的任何参数，在 [[tool.setuptools-rust.bins]] 中使用 RustBin 类定义的任何参数；只需记住在 pyproject.toml 文件中将下划线字符 _ 替换为破折号 -。
Cargo.toml 每个文件只允许一个 [lib] 表。如果你需要多个扩展模块，你需要编写多个 Cargo.toml 文件。或者，你可以创建一个单一的私有 Rust 顶级模块，暴露多个子模块（使用 PyO3 的子模块），这也可能减少构建产物的大小。你始终可以保持扩展模块私有，并用纯 Python 包装它们，以精细控制公共 API。
如果想在同一个 macOS wheel 中同时包含 [[tool.setuptools-rust.bins]] 和 [[tool.setuptools-rust.ext-modules]]，你可能需要手动添加一个额外的 build.rs 文件，有关此解决方法的更多信息，请参见 PyO3/setuptools-rust#351。
更多示例，请参见：
- hello-world：本教程中使用的代码的更完整版本，在单个发行版中混合了 [[tool.setuptools-rust.ext-modules]]和[[tool.setuptools-rust.bins]]。
- html-py-ever：一个更高级的示例，使用Rust crate作为依赖项。
- rust_with_cffi：同时使用Rust和CFFI。
- namespace_package：将用Rust编写的模块集成到PEP 420命名空间包中。
- hello-world-script：仅使用Rust创建二进制可执行文件，而不是库模块。