Advertise Enum, IntEnum, Flag, IntFlags are compatible stdlib enum types in the documentation (as suggested by gh-timohl, #5555 (review)); add test for enum.Flag to ensure that is actually true.

Author: rwgk

docs/classes.rst

@@ -563,6 +563,10 @@ in these ways:
 
     underlying = red.value
 
+As of Python 3.13, the compatible `types in the stdlib enum module
+<https://docs.python.org/3/library/enum.html#module-contents>`_ are:
+``Enum``, ``IntEnum``, ``Flag``, ``IntFlag``.
+
 .. note::
 
     In rare cases, a C++ enum may be bound to Python via a

tests/test_native_enum.cpp

@@ -20,7 +20,8 @@ enum class altitude : char {
     low = 'l', // trailing comma only allowed after CWG518
 };
 
-enum class combinable { trait1 = 0x1, trait2 = 0x2, trait3 = 0x4 };
+enum class flags_uchar : unsigned char { bit0 = 0x1u, bit1 = 0x2u, bit2 = 0x4u };
+enum class flags_uint : unsigned int { bit0 = 0x1u, bit1 = 0x2u, bit2 = 0x4u };
 
 enum class export_values { exv0, exv1 };
 
@@ -91,10 +92,16 @@ TEST_SUBMODULE(native_enum, m) {
         .value("low", altitude::low)
         .finalize();
 
-    py::native_enum<combinable>(m, "combinable", "enum.IntFlag")
-        .value("trait1", combinable::trait1)
-        .value("trait2", combinable::trait2)
-        .value("trait3", combinable::trait3)
+    py::native_enum<flags_uchar>(m, "flags_uchar", "enum.Flag")
+        .value("bit0", flags_uchar::bit0)
+        .value("bit1", flags_uchar::bit1)
+        .value("bit2", flags_uchar::bit2)
+        .finalize();
+
+    py::native_enum<flags_uint>(m, "flags_uint", "enum.IntFlag")
+        .value("bit0", flags_uint::bit0)
+        .value("bit1", flags_uint::bit1)
+        .value("bit2", flags_uint::bit2)
         .finalize();
 
     py::native_enum<export_values>(m, "export_values", "enum.IntEnum")

tests/test_native_enum.py

@@ -26,10 +26,16 @@
     ("low", "l"),
 )
 
-COMBINABLE_MEMBERS = (
-    ("trait1", 0x1),
-    ("trait2", 0x2),
-    ("trait3", 0x4),
+FLAGS_UCHAR_MEMBERS = (
+    ("bit0", 0x1),
+    ("bit1", 0x2),
+    ("bit2", 0x4),
+)
+
+FLAGS_UINT_MEMBERS = (
+    ("bit0", 0x1),
+    ("bit1", 0x2),
+    ("bit2", 0x4),
 )
 
 CLASS_WITH_ENUM_IN_CLASS_MEMBERS = (
@@ -52,7 +58,8 @@
     (m.smallenum, SMALLENUM_MEMBERS),
     (m.color, COLOR_MEMBERS),
     (m.altitude, ALTITUDE_MEMBERS),
-    (m.combinable, COMBINABLE_MEMBERS),
+    (m.flags_uchar, FLAGS_UCHAR_MEMBERS),
+    (m.flags_uint, FLAGS_UINT_MEMBERS),
     (m.export_values, EXPORT_VALUES_MEMBERS),
     (m.member_doc, MEMBER_DOC_MEMBERS),
     (m.class_with_enum.in_class, CLASS_WITH_ENUM_IN_CLASS_MEMBERS),
@@ -88,11 +95,12 @@ def test_pickle_roundtrip(enum_type, members):
             assert restored == orig
 
 
-def test_enum_intflag():
-    traits13 = m.combinable.trait1 | m.combinable.trait3
-    assert m.combinable.trait1 in traits13
-    assert m.combinable.trait2 not in traits13
-    assert m.combinable.trait3 in traits13
+@pytest.mark.parametrize("enum_type", [m.flags_uchar, m.flags_uint])
+def test_enum_flag(enum_type):
+    bits02 = enum_type.bit0 | enum_type.bit2
+    assert enum_type.bit0 in bits02
+    assert enum_type.bit1 not in bits02
+    assert enum_type.bit2 in bits02
 
 
 def test_export_values():