What is the reference to a bound enum in PyO3?

In PyO3, a "bound enum" refers to a Rust enum that has been exposed to Python using the PyO3 library. When you bind a Rust enum to Python, you're essentially creating a Python class that mirrors the structure and values of the Rust enum. The reference to a bound enum in PyO3 is how you interact with this Python class from within your Python code.

Here's a breakdown of what this means:

1. Rust Enum Definition:

- You start with a Rust enum, which is a type that can have a fixed set of possible values. For example:

#[derive(Debug, Clone, Copy)]
enum Status {
  Pending,
  Running,
  Completed,
  Failed,
}

2. Binding with PyO3:

- Using PyO3, you expose this Rust enum to Python. This typically involves using the #[pyclass] and #[pymethods] attributes or similar mechanisms. The exact syntax might vary depending on the PyO3 version and how you're structuring your code.

3. Python Representation:

- Once bound, the Rust enum becomes a Python class. Each variant of the enum becomes a member of this class. For example, if your Rust enum is named Status, you can access its variants in Python as Status.Pending, Status.Running, etc.

4. Reference in Python:

- The "reference" to a bound enum in Python is simply how you use this Python class and its members. You can use it in your Python code just like any other Python class or constant. For example:

import my_rust_module

def process_status(status):
  if status == my_rust_module.Status.Pending:
    print("Task is pending")
  elif status == my_rust_module.Status.Running:
    print("Task is running")
  elif status == my_rust_module.Status.Completed:
    print("Task is completed")
  elif status == my_rust_module.Status.Failed:
    print("Task has failed")

current_status = my_rust_module.Status.Running
process_status(current_status)

5. Key Points:

- The bound enum in Python is a class, not just a set of constants. This allows you to potentially add methods to the enum in Rust and expose them to Python.

- The values of the enum are typically represented as members of the Python class, allowing for type-safe usage in Python.

- When you pass a bound enum value from Python to Rust, PyO3 handles the conversion back to the corresponding Rust enum variant.

In summary, the reference to a bound enum in PyO3 is how you use the Python class that represents your Rust enum. It allows you to work with Rust enums in a type-safe and idiomatic way within your Python code.

Learn more about this