Add native_enum: expose Rust enums as Python enum.Enum subclasses

[wakita181009]

Summary

Closes #2887. Adds #[py_native_enum] / #[derive(NativeEnum)] — an opt-in way to expose a fieldless Rust enum as a real Python enum.Enum subclass, without touching
the existing #[pyclass] enum path.

Discussed in #5991 (RFC + benchmarks).

How it works

The macro uses Python's functional enum API at runtime to construct the class:

equivalent to what the macro generates at first use:

Color = enum.Enum("Color", [("Red", auto()), ("Green", auto()), ("Blue", auto())])

Two layers of caching keep things both correct and fast, both backed by PyOnceLock:

1. Base class cache — enum.Enum, enum.IntEnum, etc. are imported once per interpreter and reused across all enums that share the same base (base_cache.rs).
2. Generated class cache — the Python class for each Rust enum type is stored in a per-type static PyOnceLock<Py>, constructed only once per interpreter
   session (generated by the derive macro).

Caching the generated class is essential for correctness, not just performance: without it, each to_py_member call would produce a new class object, and
isinstance(x, Color) would return False for values converted in a previous call.

This makes repeated conversions as cheap as a reference clone (~59 ns, on par with #[pyclass] enum at ~58 ns — see #5991 for the full benchmark table).

Usage

use pyo3::py_native_enum;

#[py_native_enum]                         // defaults to enum.Enum                                                                                                   
enum Color { Red, Green, Blue }
                                                                                                                                                                       
#[py_native_enum(base = "IntEnum")]                                                                                                                                  
enum Status { Active = 1, Inactive = 2 }                                                                                                                             
                                                                                                                                                                   
#[py_native_enum(base = "Flag")]                          
enum Permission {
   Read  = 1,                                                                                                                                                       
   Write = 2,                                                                                                                                                       
   Exec  = 4,                                                                                                                                                       
}

IntoPyObject and FromPyObject are auto-derived, so the enum works directly in #[pyfunction] signatures.

Supported bases

Enum (default) · IntEnum · StrEnum (Python 3.11+) · Flag · IntFlag

Supported attributes

• Enum-level: base, rename, module, crate
• Variant-level: rename, value

Design decisions

• StrEnum with implicit values uses the variant name as-is rather than enum.auto(), because Python's StrEnum.generate_next_value lowercases the name, which would
  silently break the Rust ↔ Python name mapping.
  • py_enum_class is uncached by default in the trait. A static PyOnceLock cannot live in a trait default method (it would be shared across all implementing types).
    The derive macro generates a per-type static to provide caching. Manual implementers must supply their own — this is documented with an example.
• No unsafe code — all Python C API interaction goes through PyO3's safe wrappers.
  • No unwrap/panic/expect in library code — all fallible operations use Result + ?.

Known limitations / out of scope for this PR

• #[pymethods] blocks are not supported. Adding methods to the generated Python class is a separate design question (Tpt's comment in RFC: Opt-in `native_enum` mode — expose `#[pyclass]` enums as real `enum.Enum` subclasses #5991
  (RFC: Opt-in `native_enum` mode — expose `#[pyclass]` enums as real `enum.Enum` subclasses #5991)).
  • Only unit (fieldless) variants are supported — complex/ADT enums remain #[pyclass].
• StrEnum requires Python 3.11+; the macro emits a compile error (#[cfg(not(Py_3_11))]) and base_cache.rs returns PyImportError at runtime on older interpreters.
• Users must add #[derive(Copy, Clone)] themselves — the macro does not auto-derive these traits. This is intentional to avoid surprising trait implementations, but
  means #[pyfunction] fn f(c: Color) -> Color requires an explicit derive.
• No guide chapter yet — can be added as a follow-up.

[codspeed-hq]

Merging this PR will improve performance by 12.89%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 104 untouched benchmarks
🆕 6 new benchmarks
⏩ 1 skipped benchmark¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
🆕	native_enum_from_py_member	N/A	9.1 µs	N/A
🆕	native_enum_int_enum_class	N/A	423.9 ns	N/A
🆕	native_enum_int_enum_from_py_member	N/A	10.4 µs	N/A
🆕	native_enum_int_enum_to_py_member	N/A	2.5 µs	N/A
🆕	native_enum_py_enum_class	N/A	394.7 ns	N/A
🆕	native_enum_to_py_member	N/A	2.4 µs	N/A
⚡	bench_pyclass_create	4.6 µs	4.1 µs	+12.89%

---

_{Comparing wakita181009:native-enum (c0f95ea) with main (f57bda7)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩