How does a Pyo3 function take a reference to an enum?

In Pyo3, a Rust function can take a reference to an enum by using the appropriate type annotation and ensuring that the enum is properly exposed to Python. Here's a breakdown of how it works:

1. Defining the Rust Enum:

- First, you need to define your enum in Rust. For example:

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MyEnum {
  VariantA,
  VariantB,
  VariantC,
}

2. Exposing the Enum to Pyo3:

- You need to use the pyo3::prelude:: and pyo3::pyclass macros to make the enum accessible from Python:

use pyo3::prelude::;

#[pyclass]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MyEnum {
  #[pyo3(name = "A")]
  VariantA,
  #[pyo3(name = "B")]
  VariantB,
  #[pyo3(name = "C")]
  VariantC,
}

- The #[pyo3(name = "...")] attributes allow you to specify the names that will be used in Python.

3. Creating a Function that Takes a Reference:

- Now, you can create a function that takes a reference to the enum using &MyEnum:

#[pyfunction]
fn process_enum(enum_ref: &MyEnum) -> String {
  match enum_ref {
    MyEnum::VariantA => "Variant A".to_string(),
    MyEnum::VariantB => "Variant B".to_string(),
    MyEnum::VariantC => "Variant C".to_string(),
  }
}

4. Exposing the Function in a Pyo3 Module:

- Finally, you need to expose the function and the enum in a Pyo3 module:

#[pymodule]
fn my_module(_py: Python, m: &PyModule) -> PyResult<()> {
  m.add_class::()?;
  m.add_function(wrap_pyfunction!(process_enum, m)?)?;
  Ok(())
}

5. Using it in Python:

- In Python, you can now import the module and use the enum and the function:

import my_module

print(my_module.process_enum(my_module.MyEnum.A)) # Output: Variant A
print(my_module.process_enum(my_module.MyEnum.B)) # Output: Variant B
print(my_module.process_enum(my_module.MyEnum.C)) # Output: Variant C

Key Points:

- The &MyEnum in the function signature indicates that the function takes a reference to the enum, not ownership. This is efficient as it avoids unnecessary copying.

- The #[pyclass] macro is essential for making the enum accessible from Python.

- The #[pyo3(name = "...")] attributes allow you to customize the names of the enum variants in Python.

By following these steps, you can effectively pass references to enums from Python to Rust using Pyo3.

Learn more about this