The Correct and Concise Way to Use PyO3 Bindings (Similar to pybind11)

Getting Started with PyO3 Bindings

Now that we’ve covered the basics, let’s get started with creating PyO3 bindings for your Rust library!

Step 1: Install PyO3

The first step is to install PyO3 using Cargo, the Rust package manager. Add the following line to your `Cargo.toml` file:

[dependencies]
pyo3 = "0.14.1"

Then, run the following command to install PyO3:

cargo build

Step 2: Create a Python Module

Create a new file called `my_module.rs` in your project directory. This file will contain the code for your Python module:

use pyo3::prelude::*;

#[pyclass]
struct MyClass {
    #[pyo3(get)]
    num: i32,
}

#[pymethods]
impl MyClass {
    #[new]
    fn new() -> Self {
        MyClass { num: 0 }
    }

    fn increment(&mut self) {
        self.num += 1;
    }

    fn get_num(&self) -> i32 {
        self.num
    }
}

In this example, we’ve defined a `MyClass` struct with a single field `num` and three methods: `new`, `increment`, and `get_num`. The `#[pyclass]` attribute indicates that `MyClass` should be exposed as a Python class, while the `#[pymethods]` attribute specifies the methods that should be available in Python.

Step 3: Create a Python Binding

Next, create a new file called `my_binding.rs` in the same directory. This file will contain the code for your Python binding:

use pyo3::{Python, types::PyDict};

use my_module::MyClass;

#[pyfn]
fn my_function(py: Python<'_>, obj: &PyDict) -> PyResult<()> {
    let instance = MyClass::new();
    let py_obj = py.init_obj("my_module", "MyClass", instance);
    obj.set_item("my_class", py_obj);
    Ok(())
}

In this example, we’ve defined a `my_function` function that creates an instance of `MyClass` and adds it to a Python dictionary. The `#[pyfn]` attribute indicates that this function should be exposed as a Python function.

Step 4: Build and Run Your Binding

Finally, build your project using Cargo and run your Python binding:

cargo build
python -c "import my_module; print(my_module.my_class().get_num())"

This should output `0`, indicating that your Python binding is working correctly!

Advanced Topics

Now that we’ve covered the basics, let’s explore some advanced topics in PyO3 bindings.

Error Handling

Error handling is an essential aspect of any Python binding. PyO3 provides several ways to handle errors, including:

• PyResult**: The `PyResult` type represents a result that may contain an error. You can use the `?` operator to propagate errors up the call stack.
• PyErr**: The `PyErr` type represents a Python error. You can use the `PyErr` type to raise errors in your Python binding.

use pyo3::err;

#[pyfn]
fn my_function(py: Python<'_>) -> PyResult<()> {
    if let Err(e) = my_rust_function() {
        Err(py_err!(py, e))
    } else {
        Ok(())
    }
}

use std::sync::Mutex;

struct MyClass {
    num: Mutex<i32>,
}

impl MyClass {
    fn new() -> Self {
        MyClass { num: Mutex::new(0) }
    }

    fn increment(&self) {
        *self.num.lock().unwrap() += 1;
    }

    fn get_num(&self) -> i32 {
        *self.num.lock().unwrap()
    }
}

use pyo3::prelude::*;
use std::sync::Arc;

struct MyClass {
    cache: Arc<Mutex<HashMap<i32, i32>>>,
}

impl MyClass {
    fn new() -> Self {
        MyClass { cache: Arc::new(Mutex::new(HashMap::new())) }
    }

    fn get_num(&self, key: i32) -> i32 {
        if let Some(value) = self.cache.lock().unwrap().get(&key) {
            *value
        } else {
            let value = my_rust_function(key);
            self.cache.lock().unwrap().insert(key, value);
            value
        }
    }
}