Introduce py::native_enum_kind (mandatory argument without a default).

[rwgk]

Description

The core change here is to introduce

    enum class native_enum_kind { Enum, IntEnum };

and to change the native_enum constructor to require passing one of those two values, e.g.:

    py::native_enum<smallenum>("smallenum", py::native_enum_kind::IntEnum)

This completely replaces the automatic mechanism for the determination of use_int_enum (a member of pybind11::detail::native_enum_data).

All other changes are of the boilerplate kind (updating one error message and the native_enum unit tests).

The rationale for this change is:

• For manually written code: Simply put it in the hands of the author what native enum type is used. This also makes the bindings more self-documenting.

• For automatically generated code (PyCLIF): Leave the choice of native enum type up to the code generator (PyCLIF-C-API has the corresponding logic already).

Google-internal global test ID: OCL:626240839:BASE:626375750:1713541129757:e746a257

---

---

---

For completeness: This is what happens if a user chooses IntEnum for a C++ enum with a char underlying type:

( cd /usr/local/google/home/rwgk/forked/pybind11/tests && PYTHONPATH=/usr/local/google/home/rwgk/forked/build_gcc/lib /usr/bin/python3 -m pytest test_native_enum.py )

Traceback (most recent call last):
  File "/usr/lib/python3.11/enum.py", line 714, in __call__
    return cls._create_(
           ^^^^^^^^^^^^^
  File "/usr/lib/python3.11/enum.py", line 891, in _create_
    return metacls.__new__(metacls, class_name, bases, classdict, boundary=boundary)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.11/enum.py", line 566, in __new__
    raise exc
  File "/usr/lib/python3.11/enum.py", line 259, in __set_name__
    enum_member = enum_class._new_member_(enum_class, *args)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ValueError: invalid literal for int() with base 10: 'h'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/google/home/rwgk/forked/pybind11/tests/conftest.py", line 20, in <module>
    import pybind11_tests
ImportError: initialization failed
ImportError while loading conftest '/usr/local/google/home/rwgk/forked/pybind11/tests/conftest.py'.
conftest.py:20: in <module>
    import pybind11_tests
E   ImportError: initialization failed

ERROR: completed_process.returncode=4

---

---

---

Note regarding commit history: this PR was originally based on #30117.

Suggested changelog entry:

[metzen]

This might give an impression that the IntEnum kind is preferred, which isn't really true, right? Should this just use a placeholder ellipsis , or full suggestion of both versions? (e.g., "Use m += native_enum<...>("Name", Enum) or m += native_enum<...>("Name", IntEnum) to fix)

[rwgk]

Changed (f3b8a03) to .... — I wasn't sure about this myself before. Considering that the += part is the critical part of the error message, I believe using ... is best (will distract people the least from the critical part).