PyO3中常规引用与Bound的区别及选型建议

你实现的三个increment函数对应PyO3中处理pyclass实例的三种不同引用方式，核心差异体现在对Python对象的控制权、操作能力和语法简洁性上，具体分析如下：

1. &mut Number：便捷的直接可变引用 #

• 这是PyO3提供的语法糖，会自动将传入的Python对象转换为内部Rust结构体的可变引用。
• 底层自动完成安全检查：确保当前无其他Python线程持有该对象引用，同时获取对Rust结构体的可变借用。
• 写法最简洁，无需额外调用borrow_mut()，直接操作结构体字段即可。
• 局限性：仅能操作pyclass内部的Rust字段，无法直接调用该对象的Python方法或访问Python层面属性（若需此类操作，需手动通过PyRefMut转换）。

2. Bound<'_, Number>：持有Python对象所有权的包装 #

• Bound是PyO3 0.18版本后引入的类型，代表绑定到Python解释器生命周期的Python对象。
• 函数会获取该Python对象的Rust层面所有权，执行结束后自动将所有权归还Python解释器。
• 需要通过borrow_mut()获取内部Rust结构体的可变引用，这一步会执行运行时检查，确保无冲突的可变借用。
• 优势：可以直接操作Python对象本身，比如调用其Python方法、访问Python属性，或与其他需要Python对象的API交互。
• 适用场景：当函数需要持有对象所有权（如存储到结构体、传递给需要所有权的API）时使用。

3. &Bound<'_, Number>：Python对象的不可变引用 #

• 这是对Bound对象的不可变借用，函数仅临时使用对象，不获取所有权。
• 同样需要通过borrow_mut()获取内部结构体的可变引用，运行时安全检查规则与Bound版本一致。
• 优势：语义更清晰，明确表明函数只是临时使用对象，无需转移所有权。
• 与Bound的区别：无法调用需要所有权的Python API，但对于修改内部Rust字段的场景，功能完全一致。

推荐方案 #

• 优先选择&mut Number：如果你的函数仅需修改pyclass内部的Rust字段，不需要与Python层面的对象交互，这种方式语法最简洁，性能也最优（减少了Bound包装的额外开销）。
• 选择Bound<'_, Number>或&Bound<'_, Number>：当函数需要操作Python对象本身（如调用Python方法、与其他Python API交互）时：
  • 若需要持有对象所有权，使用Bound<'_, Number>；
  • 若仅需临时借用对象，使用&Bound<'_, Number>，语义更准确。

你的代码示例 #

Rust代码

#[pyclass]
struct Number {
  #[pyo3(get, set)]
  value: i32,
}

#[pymethods]
impl Number {
    #[new]
    fn new(value: i32) -> Self {
        Number { value }
    }

    fn __repr__(&self) -> PyResult<String> {
        Ok(format!("Number({})", self.value))
    }
}

#[pyfunction]
fn increment_1(n: &mut Number) {
    n.value += 1;
}

#[pyfunction]
fn increment_2(n: Bound<'_, Number>) {
    n.borrow_mut().value += 1;
}

#[pyfunction]
fn increment_3(n: &Bound<'_, Number>) {
    n.borrow_mut().value += 1;
}

#[pymodule]
fn mod(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<Number>()?;
    m.add_function(wrap_pyfunction!(increment_1, m)?)?;
    m.add_function(wrap_pyfunction!(increment_2, m)?)?;
    m.add_function(wrap_pyfunction!(increment_3, m)?)?;
    Ok(())
}

Python测试代码

from mod import Number, increment_1, increment_2, increment_3

n = Number(1)
print(n) # Number(1)

increment_1(n)
print(n) # Number(2)

increment_2(n)
print(n) # Number(3)

increment_3(n)
print(n) # Number(4)

内容的提问来源于stack exchange，提问作者Eran Cohen