test: add integration tests and UI tests for native_enum

- tests/test_native_enum.rs: Rust integration tests covering the full
  enum protocol (isinstance, name/value, len/iter/contains, lookup by
  name and value), class and member identity, IntoPyObject/FromPyObject
  roundtrips, all five base classes (Enum/IntEnum/Flag/IntFlag/StrEnum),
  rename at class and variant level, module attribute, qualname via
  direct build_native_enum call, and VariantValue::Str

- pytests/src/native_enums.rs + pytests/tests/test_native_enums.py:
  Python-side tests for the same surface area, exposing Color/Status/
  Permission/Bits/Size to Python and verifying enum protocol from pytest

- tests/ui/invalid_native_enum_base.rs: UI test for unknown base name
- tests/ui/native_enum_generic.rs: UI test for generic/lifetime params
  (also adds the validation logic in pyo3-macros-backend)

Author: wakita181009

newsfragments/6020.added.md

@@ -0,0 +1 @@
+Added `#[py_native_enum]` / `#[derive(NativeEnum)]` to expose fieldless Rust enums as Python `enum.Enum` subclasses, supporting `Enum`, `IntEnum`, `StrEnum`, `Flag`, and `IntFlag` bases.

pyo3-benches/benches/bench_native_enum.rs

@@ -25,13 +25,13 @@ enum Status {
 // Measures the PyOnceLock cache-hit path: get + clone_ref + into_bound.
 fn bench_py_enum_class(b: &mut Bencher<'_>) {
     Python::attach(|py| {
-        b.iter(|| Color::py_enum_class(py).unwrap());
+        b.iter(|| black_box(Color::py_enum_class(py).unwrap()));
     });
 }
 
 fn bench_int_enum_class(b: &mut Bencher<'_>) {
     Python::attach(|py| {
-        b.iter(|| Status::py_enum_class(py).unwrap());
+        b.iter(|| black_box(Status::py_enum_class(py).unwrap()));
     });
 }
 

pyo3-macros-backend/src/native_enum.rs

@@ -252,6 +252,8 @@ fn impl_native_enum(
                 if let Some((_, expr)) = &variant.discriminant {
                     let int_val: i64 = extract_discriminant_i64(expr)?;
                     quote! { #pyo3::native_enum::VariantValue::Int(#int_val) }
+                } else if base_str == "StrEnum" {
+                    quote! { #pyo3::native_enum::VariantValue::Str(#py_member_name) }
                 } else {
                     quote! { #pyo3::native_enum::VariantValue::Auto }
                 }
@@ -398,6 +400,13 @@ pub fn build_derive_native_enum(input: &mut DeriveInput) -> syn::Result<TokenStr
             ))
         }
     };
+    if let Some(lt) = input.generics.lifetimes().next() {
+        bail_spanned!(lt.span() => "#[derive(NativeEnum)] cannot have lifetime parameters");
+    }
+    ensure_spanned!(
+        input.generics.params.is_empty(),
+        input.generics.span() => "#[derive(NativeEnum)] cannot have generic parameters"
+    );
     let args = PyNativeEnumArgs::take_from_attrs(&mut input.attrs)?;
     impl_native_enum(&input.ident, &args, &mut data_enum.variants)
 }
@@ -407,6 +416,13 @@ pub fn native_enum_impl(
     item: &mut syn::ItemEnum,
     args: PyNativeEnumArgs,
 ) -> syn::Result<TokenStream> {
+    if let Some(lt) = item.generics.lifetimes().next() {
+        bail_spanned!(lt.span() => "#[native_enum] cannot have lifetime parameters");
+    }
+    ensure_spanned!(
+        item.generics.params.is_empty(),
+        item.generics.span() => "#[native_enum] cannot have generic parameters"
+    );
     impl_native_enum(&item.ident, &args, &mut item.variants)
 }
 

pytests/src/lib.rs

@@ -11,6 +11,7 @@ mod dict_iter;
 mod enums;
 mod exception;
 mod misc;
+mod native_enums;
 mod objstore;
 mod othermod;
 mod path;
@@ -35,9 +36,9 @@ mod pyo3_pytests {
     #[pymodule_export]
     use {
         awaitable::awaitable, comparisons::comparisons, consts::consts, dict_iter::dict_iter,
-        enums::enums, exception::exception, misc::misc, objstore::objstore, othermod::othermod,
-        path::path, pyclasses::pyclasses, pyfunctions::pyfunctions, sequence::sequence,
-        subclassing::subclassing,
+        enums::enums, exception::exception, misc::misc, native_enums::native_enums,
+        objstore::objstore, othermod::othermod, path::path, pyclasses::pyclasses,
+        pyfunctions::pyfunctions, sequence::sequence, subclassing::subclassing,
     };
 
     // Inserting to sys.modules allows importing submodules nicely from Python
@@ -52,6 +53,7 @@ mod pyo3_pytests {
         sys_modules.set_item("pyo3_pytests.datetime", m.getattr("datetime")?)?;
         sys_modules.set_item("pyo3_pytests.dict_iter", m.getattr("dict_iter")?)?;
         sys_modules.set_item("pyo3_pytests.enums", m.getattr("enums")?)?;
+        sys_modules.set_item("pyo3_pytests.native_enums", m.getattr("native_enums")?)?;
         sys_modules.set_item("pyo3_pytests.misc", m.getattr("misc")?)?;
         sys_modules.set_item("pyo3_pytests.objstore", m.getattr("objstore")?)?;
         sys_modules.set_item("pyo3_pytests.othermod", m.getattr("othermod")?)?;

pytests/src/native_enums.rs

@@ -0,0 +1,79 @@
+use pyo3::native_enum::NativeEnum;
+use pyo3::prelude::*;
+use pyo3::py_native_enum;
+
+#[py_native_enum]
+pub enum Color {
+    Red,
+    Green,
+    Blue,
+}
+
+#[py_native_enum(base = "IntEnum")]
+pub enum Status {
+    Active = 1,
+    Inactive = 2,
+    Pending = 3,
+}
+
+#[py_native_enum(base = "Flag")]
+pub enum Permission {
+    Read = 1,
+    Write = 2,
+    Exec = 4,
+}
+
+#[py_native_enum(base = "IntFlag")]
+pub enum Bits {
+    A = 1,
+    B = 2,
+    C = 4,
+}
+
+#[cfg(Py_3_11)]
+#[py_native_enum(base = "StrEnum")]
+pub enum Size {
+    Small,
+    Medium,
+    Large,
+}
+
+#[pyfunction]
+fn identity_bits(b: Bits) -> Bits {
+    b
+}
+
+#[pyfunction]
+fn identity_color(c: Color) -> Color {
+    c
+}
+
+#[pyfunction]
+fn identity_status(s: Status) -> Status {
+    s
+}
+
+#[pyfunction]
+fn identity_permission(p: Permission) -> Permission {
+    p
+}
+
+#[pymodule]
+pub mod native_enums {
+    use super::*;
+
+    #[pymodule_init]
+    fn init(m: &Bound<'_, PyModule>) -> PyResult<()> {
+        let py = m.py();
+        m.add("Color", Color::py_enum_class(py)?)?;
+        m.add("Status", Status::py_enum_class(py)?)?;
+        m.add("Permission", Permission::py_enum_class(py)?)?;
+        m.add("Bits", Bits::py_enum_class(py)?)?;
+        #[cfg(Py_3_11)]
+        m.add("Size", Size::py_enum_class(py)?)?;
+        Ok(())
+    }
+
+    #[pymodule_export]
+    use super::{identity_bits, identity_color, identity_permission, identity_status};
+}

pytests/tests/test_native_enums.py

@@ -0,0 +1,167 @@
+import enum
+import sys
+
+import pytest
+from pyo3_pytests import native_enums
+
+
+def test_color_is_enum_subclass():
+    assert issubclass(native_enums.Color, enum.Enum)
+
+
+def test_color_member_isinstance():
+    assert isinstance(native_enums.Color.Red, enum.Enum)
+    assert isinstance(native_enums.Color.Green, enum.Enum)
+    assert isinstance(native_enums.Color.Blue, enum.Enum)
+
+
+def test_color_member_isinstance_of_class():
+    assert isinstance(native_enums.Color.Red, native_enums.Color)
+
+
+def test_color_name_attribute():
+    assert native_enums.Color.Red.name == "Red"
+    assert native_enums.Color.Green.name == "Green"
+    assert native_enums.Color.Blue.name == "Blue"
+
+
+def test_color_len():
+    assert len(native_enums.Color) == 3
+
+
+def test_color_iter():
+    members = list(native_enums.Color)
+    assert members == [native_enums.Color.Red, native_enums.Color.Green, native_enums.Color.Blue]
+
+
+def test_color_contains():
+    assert native_enums.Color.Red in native_enums.Color
+    assert native_enums.Color.Blue in native_enums.Color
+
+
+def test_color_members_mapping():
+    assert "Red" in native_enums.Color._member_names_
+    assert "Green" in native_enums.Color._member_names_
+    assert "Blue" in native_enums.Color._member_names_
+
+
+def test_color_lookup_by_name():
+    assert native_enums.Color["Red"] is native_enums.Color.Red
+    assert native_enums.Color["Blue"] is native_enums.Color.Blue
+
+
+def test_color_lookup_by_value():
+    assert native_enums.Color(native_enums.Color.Red.value) is native_enums.Color.Red
+    assert native_enums.Color(native_enums.Color.Blue.value) is native_enums.Color.Blue
+
+
+def test_color_member_identity():
+    a = native_enums.Color.Green
+    b = native_enums.Color.Green
+    assert a is b
+
+
+def test_color_class_identity():
+    cls1 = type(native_enums.Color.Red)
+    cls2 = native_enums.Color
+    assert cls1 is cls2
+
+
+def test_identity_color_roundtrip():
+    result = native_enums.identity_color(native_enums.Color.Red)
+    assert result is native_enums.Color.Red
+
+
+@pytest.mark.parametrize("variant", list(native_enums.Color))
+def test_identity_color_all_variants(variant):
+    assert native_enums.identity_color(variant) is variant
+
+
+def test_status_is_int_enum_subclass():
+    assert issubclass(native_enums.Status, enum.IntEnum)
+    assert issubclass(native_enums.Status, int)
+
+
+def test_status_values():
+    assert native_enums.Status.Active == 1
+    assert native_enums.Status.Inactive == 2
+    assert native_enums.Status.Pending == 3
+
+
+def test_status_isinstance_int():
+    assert isinstance(native_enums.Status.Active, int)
+
+
+def test_status_lookup_by_value():
+    assert native_enums.Status(1) is native_enums.Status.Active
+    assert native_enums.Status(2) is native_enums.Status.Inactive
+    assert native_enums.Status(3) is native_enums.Status.Pending
+
+
+def test_identity_status_roundtrip():
+    result = native_enums.identity_status(native_enums.Status.Active)
+    assert result is native_enums.Status.Active
+
+
+def test_bits_is_int_flag_subclass():
+    assert issubclass(native_enums.Bits, enum.IntFlag)
+    assert issubclass(native_enums.Bits, int)
+
+
+def test_bits_bitwise_or():
+    ab = native_enums.Bits.A | native_enums.Bits.B
+    assert native_enums.Bits.A in ab
+    assert native_enums.Bits.B in ab
+    assert native_enums.Bits.C not in ab
+
+
+def test_bits_isinstance_int():
+    assert isinstance(native_enums.Bits.A, int)
+    assert native_enums.Bits.A == 1
+    assert native_enums.Bits.B == 2
+    assert native_enums.Bits.C == 4
+
+
+def test_identity_bits_roundtrip():
+    result = native_enums.identity_bits(native_enums.Bits.A)
+    assert result is native_enums.Bits.A
+
+
+def test_permission_is_flag_subclass():
+    assert issubclass(native_enums.Permission, enum.Flag)
+
+
+def test_permission_bitwise_or():
+    rw = native_enums.Permission.Read | native_enums.Permission.Write
+    assert native_enums.Permission.Read in rw
+    assert native_enums.Permission.Write in rw
+    assert native_enums.Permission.Exec not in rw
+
+
+def test_permission_bitwise_and():
+    rw = native_enums.Permission.Read | native_enums.Permission.Write
+    assert rw & native_enums.Permission.Read == native_enums.Permission.Read
+
+
+def test_identity_permission_roundtrip():
+    result = native_enums.identity_permission(native_enums.Permission.Read)
+    assert result is native_enums.Permission.Read
+
+
+@pytest.mark.skipif(sys.version_info < (3, 11), reason="StrEnum requires Python 3.11+")
+def test_size_is_str_enum_subclass():
+    assert issubclass(native_enums.Size, enum.StrEnum)
+    assert issubclass(native_enums.Size, str)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 11), reason="StrEnum requires Python 3.11+")
+def test_size_members_are_strings():
+    assert isinstance(native_enums.Size.Small, str)
+    assert native_enums.Size.Small == "Small"
+    assert native_enums.Size.Medium == "Medium"
+    assert native_enums.Size.Large == "Large"
+
+
+@pytest.mark.skipif(sys.version_info < (3, 11), reason="StrEnum requires Python 3.11+")
+def test_size_lookup_by_value():
+    assert native_enums.Size("Small") is native_enums.Size.Small

tests/test_compile_error.rs

@@ -96,4 +96,6 @@ fn test_compile_errors() {
     t.pass("tests/ui/pyclass_probe.rs");
     t.compile_fail("tests/ui/invalid_pyfunction_warn.rs");
     t.compile_fail("tests/ui/invalid_pymethods_warn.rs");
+    t.compile_fail("tests/ui/invalid_native_enum_base.rs");
+    t.compile_fail("tests/ui/native_enum_generic.rs");
 }