本文介绍如何在不构建或安装到 python 环境的前提下，直接在 rust 单元测试中调用并验证 pyo3 暴露的 python 接口，涵盖 python 解释器嵌入、模块导入、函数调用及类型转换等关键步骤。
本文介绍如何在不构建或安装到 python 环境的前提下，直接在 rust 单元测试中调用并验证 pyo3 暴露的 python 接口，涵盖 python 解释器嵌入、模块导入、函数调用及类型转换等关键步骤。
在使用 PyO3 将 Rust 函数暴露为 Python 模块时，除了对底层 Rust 逻辑的单元测试和 Python 端的端到端集成测试外，还有一类关键验证：确保 PyO3 的绑定层正确处理 Python 类型、异常和调用约定。这类测试不应依赖外部 Python 环境，而应完全在 Rust 测试框架（cargo test）内完成——PyO3 支持通过嵌入 Python 解释器实现这一目标。
核心思路是：在测试中初始化一个轻量级 Python 运行时，将当前 crate 编译为可被 Python 动态导入的模块（即“内置模块”），然后像在真实 Python 中一样 import 并调用函数。这要求模块名与 #[pymodule] 宏注册的名称严格一致，并在测试前显式注册该模块到 Python 初始化表。
以下是一个完整、可复用的测试模板（适配 PyO3 v0.21+）：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
#[cfg(test)]
mod tests {
use pyo3::prelude::*;
use pyo3::exceptions::PyTypeError;
// 注意：此处的 `py_fizzbuzzo3` 必须与 lib.rs 中 #[pymodule] 宏注册的模块名完全匹配
// 例如：#[pymodule] fn py_fizzbuzzo3(_py: Python, m: &PyModule) -> PyResult<()> { ... }
use super::*;
#[test]
fn test_fizzbuzz() {
// 步骤 1：向 Python 初始化表注册当前模块（必须在 prepare_freethreaded_python 之前！）
pyo3::append_to_inittab!(py_fizzbuzzo3);
// 步骤 2：初始化多线程安全的 Python 解释器（仅限测试环境）
pyo3::prepare_freethreaded_python();
// 步骤 3：获取 GIL 并执行 Python 代码
Python::with_gil(|py| {
// 导入模块（模块名即 crate 名，如 Cargo.toml 中的 `package.name` 或 `lib.name`）
let module = py.import_bound("fizzbuzzo3")
.expect("Failed to import fizzbuzzo3 module");
// 获取目标函数对象
let fizzbuzz = module.getattr("fizzbuzz")
.expect("Failed to get 'fizzbuzz' function");
// 调用函数：call1 接受单参数元组；call0 无参；call 接受 (args, kwargs)
let result = fizzbuzz.call1((1i32,))
.expect("Failed to call fizzbuzz(1)");
// 提取返回值（需与 Python 函数返回类型匹配）
let result_str: String = result.extract()
.expect("Failed to extract result as String");
assert_eq!(result_str, "1");
});
}
#[test]
fn test_error_handling() {
pyo3::append_to_inittab!(py_fizzbuzzo3);
pyo3::prepare_freethreaded_python();
Python::with_gil(|py| {
let module = py.import_bound("fizzbuzzo3").unwrap();
let fizzbuzz = module.getattr("fizzbuzz").unwrap();
// 测试非法输入触发 Python 异常（如传入 None 或字符串）
let result = fizzbuzz.call1((py.None(),));
assert!(result.is_err());
// 可进一步检查异常类型
let err = result.unwrap_err();
assert!(err.is_instance_of::<PyTypeError>(py));
});
}
}? 关键注意事项：
立即学习“Python免费学习笔记（深入）”；
- ✅ pyo3::append_to_inittab! 的宏参数（如 py_fizzbuzzo3）必须与 #[pymodule] 函数名完全一致，且该函数需位于当前作用域（通常为 lib.rs 根模块）；
- ✅ pyo3::prepare_freethreaded_python() 是必需的，它初始化 CPython 解释器并启用多线程支持（即使单线程测试也需调用）；
- ✅ 模块导入名（如 "fizzbuzzo3"）默认为 crate 名（Cargo.toml 中 package.name），若 lib.name 显式指定则以 lib.name 为准；
- ⚠️ 此方法仅适用于 crate 类型为 cdylib 或 lib（且启用了 extension-module feature），确保生成兼容 Python 的动态库；
- ⚠️ 测试中嵌入的 Python 解释器与系统 Python 独立，不加载 site-packages，因此所有依赖必须通过 pyo3::types 或标准库模拟；
- ? 建议将重复初始化逻辑提取为 setup_py_test() 辅助函数，提升可维护性。
通过这种方式，你能在 Rust 开发流程中快速迭代 PyO3 绑定层：修改 #[pyfunction] 签名、添加类型检查、处理 Option
