在Rust的pyO3中检查Python自定义类的实例类型

在使用Rust的pyO3库与Python交互时，若需判断一个`PyAny`对象是否为Python自定义类的实例，应避免直接使用`PyTypeInfo`和`is_type_of`检查实例。正确的做法是先通过`py.import`和`getattr`获取到Python自定义类的类型对象，然后调用`PyAny`对象的`is_instance()`方法进行判断。为提高效率，建议缓存获取到的Python类型对象。

在Rust中利用pyO3库与Python生态系统集成时，经常需要处理Python对象。一个常见的场景是，当Rust函数接收一个泛型的PyAny对象时，需要判断它是否属于某个特定的Python自定义类实例。本文将详细介绍如何在pyO3中正确地实现这一类型检查。

理解PyTypeInfo与实例类型检查的局限性

开发者在尝试检查Python自定义类实例类型时，可能会自然地想到使用PyTypeInfo trait。PyTypeInfo主要用于将Rust类型映射到Python类型，并提供获取Python类型对象的方法。例如，以下代码尝试为Python中定义的FinalRule类创建一个Rust表示：

struct PyFinalRule(PyAny);

unsafe impl PyTypeInfo for PyFinalRule {
    const NAME: &'static str = "FinalRule";
    const MODULE: Option<&'static str> = Option::Some("LiSE.util");
    type AsRefTarget = PyAny;

    fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject {
        let modu = py.import("LiSE.util").unwrap();
        let final_rule = modu.getattr("FinalRule").unwrap();
        final_rule.get_type_ptr()
    }
}
unsafe impl PyNativeType for PyFinalRule {}

随后，开发者可能会尝试使用PyFinalRule::is_type_of(obj)来检查一个PyAny对象obj是否为FinalRule的实例。然而，这种方法通常会失败，因为is_type_of方法实际上是检查一个PyAny对象是否是该PyTypeInfo所代表的类型对象本身，而不是该类型的实例。换句话说，PyFinalRule::is_type_of会返回true如果传入的是FinalRule类对象本身，但对FinalRule的实例则返回false。这与我们期望的实例类型检查行为不符。

立即学习“Python免费学习笔记（深入）”；

正确的解决方案：使用PyAny::is_instance()

pyO3提供了一个更直接且正确的机制来检查一个PyAny对象是否是特定Python类的实例，即PyAny::is_instance()方法。这个方法接收一个&PyAny类型的参数，该参数应为目标Python类的类型对象。

1. 获取Python自定义类的类型对象

首先，我们需要在Rust代码中获取到Python自定义类的类型对象。这可以通过py.import()导入包含该类的模块，然后使用getattr()获取类本身来完成。

use pyo3::{PyResult, Python, types::PyAny};

fn get_final_rule_type<'py>(py: Python<'py>) -> PyResult<&'py PyAny> {
    let module = py.import("LiSE.util")?; // 导入包含FinalRule的模块
    let final_rule_type = module.getattr("FinalRule")?; // 获取FinalRule类对象
    Ok(final_rule_type)
}

2. 执行实例类型检查

一旦获取到Python自定义类的类型对象，就可以将其作为参数传递给PyAny对象的is_instance()方法进行类型检查。

Giiso写作机器人

Giiso写作机器人，让写作更简单

下载

fn is_instance_of_final_rule(py: Python<'_>, object: &PyAny) -> PyResult<bool> {
    let final_rule_type = get_final_rule_type(py)?; // 获取FinalRule类型对象
    object.is_instance(final_rule_type) // 检查object是否为final_rule_type的实例
}

将上述逻辑整合，完整的示例代码如下：

use pyo3::{PyResult, Python, types::PyAny};

/// 检查一个PyAny对象是否为Python中定义的LiSE.util.FinalRule类的实例。
///
/// # 参数
/// - `py`: Python GIL令牌。
/// - `object`: 待检查的PyAny对象。
///
/// # 返回
/// 如果`object`是`FinalRule`的实例，则返回`Ok(true)`；否则返回`Ok(false)`。
/// 如果在导入模块或获取类时发生Python错误，则返回`Err(PyErr)`。
pub fn check_final_rule_instance(py: Python<'_>, object: &PyAny) -> PyResult<bool> {
    // 导入包含FinalRule类的Python模块
    let module = py.import("LiSE.util")?;
    // 从模块中获取FinalRule类对象
    let final_rule_class = module.getattr("FinalRule")?;
    // 使用PyAny::is_instance方法检查object是否为final_rule_class的实例
    object.is_instance(final_rule_class)
}

// 假设在Python中有一个LiSE/util.py文件，内容如下：
// class FinalRule:
//     pass
//
// class AnotherClass:
//     pass

// 示例用法（在Rust测试或实际应用中）：
#[cfg(test)]
mod tests {
    use super::*;
    use pyo3::{prelude::*, types::{PyDict, PyList}};

    #[test]
    fn test_final_rule_instance_check() -> PyResult<()> {
        pyo3::prepare_python(); // 初始化Python解释器

        Python::with_gil(|py| {
            // 模拟Python环境，创建LiSE.util模块和FinalRule类
            let sys = py.import("sys")?;
            let modules: &PyDict = sys.getattr("modules")?.downcast()?;
            let li_se_util = PyModule::new(py, "LiSE.util")?;
            li_se_util.add_class::<PyFinalRuleStub>()?; // 添加一个模拟的FinalRule类
            modules.set_item("LiSE.util", li_se_util)?;

            // 获取FinalRule类对象
            let final_rule_class = py.import("LiSE.util")?.getattr("FinalRule")?;

            // 创建FinalRule的实例
            let final_rule_instance = final_rule_class.call0()?;
            // 创建另一个类的实例
            let another_instance = py.eval("object()", None, None)?;
            // 创建一个Python列表
            let py_list = PyList::empty(py);

            // 检查实例
            assert!(check_final_rule_instance(py, final_rule_instance)?.is_ok());
            assert!(check_final_rule_instance(py, another_instance)?.is_err()); // 预期失败，因为不是FinalRule
            assert!(check_final_rule_instance(py, py_list)?.is_err()); // 预期失败，因为不是FinalRule

            Ok(())
        })
    }

    // 用于测试的模拟FinalRule类
    #[pyclass(name = "FinalRule", module = "LiSE.util")]
    struct PyFinalRuleStub {}

    #[pymethods]
    impl PyFinalRuleStub {
        #[new]
        fn new() -> Self {
            PyFinalRuleStub {}
        }
    }
}

最佳实践与注意事项

1. 缓存Python类型对象： 在实际应用中，如果需要频繁地检查某个Python类的实例类型，每次都通过py.import()和getattr()来获取类型对象会带来不必要的性能开销。建议在Rust模块或结构体中缓存这些Python类型对象。例如，可以将其存储在一个static变量（使用once_cell等库进行懒初始化）或在初始化时获取并存储。

   use pyo3::{PyResult, Python, types::PyAny, Py, GILOnceCell};
   
   // 使用once_cell缓存FinalRule类型对象
   static FINAL_RULE_TYPE: GILOnceCell<Py<PyAny>> = GILOnceCell::new();
   
   pub fn check_final_rule_instance_cached(py: Python<'_>, object: &PyAny) -> PyResult<bool> {
       let final_rule_type_ref = FINAL_RULE_TYPE.get_or_try_init(py, || {
           let module = py.import("LiSE.util")?;
           let final_rule_class = module.getattr("FinalRule")?;
           Ok(final_rule_class.into()) // 将&PyAny转换为Py<PyAny>以便缓存
       })?;
   
       object.is_instance(final_rule_type_ref.as_ref(py))
   }

2. 错误处理： py.import()、getattr()和is_instance()都返回PyResult，这意味着它们可能会因为Python运行时错误而失败（例如，模块不存在、属性不存在）。在实际代码中，务必对这些错误进行适当的处理，而不是简单地使用unwrap()。

3. PyTypeInfo的适用场景： PyTypeInfo并非完全无用。它适用于以下情况：

   • 定义一个Rust结构体来代表一个已知的Python类型（如PyList, PyDict），并希望利用其提供的类型安全方法。
   • 当你需要直接与Python类型对象本身进行交互，而不是检查实例时。
   • 在实现自定义FromPyObject或ToPyObject trait时，可能需要获取类型信息。

总结

在Rust的pyO3中，检查一个PyAny对象是否为Python自定义类的实例，应通过以下步骤实现：

1. 使用py.import()和module.getattr()获取到目标Python自定义类的类型对象。
2. 调用待检查PyAny对象的is_instance()方法，并传入上一步获取的类型对象。
3. 为了优化性能，建议缓存获取到的Python类型对象，避免重复的Python运行时查找。

遵循这些指导原则，可以确保在pyO3项目中进行准确且高效的Python自定义类实例类型检查。