Fix: Enum Internals Filter (#303)

Fix #302

- [x] reproducer/test
- [x] fix
- [x] update stubs, ensure they include no `_sunder_` members

Author: ax3l

pybind11_stubgen/__init__.py

@@ -21,6 +21,7 @@
 from pybind11_stubgen.parser.mixins.filter import (
     FilterClassMembers,
     FilterInvalidIdentifiers,
+    FilterPybind11NativeEnumMembers,
     FilterPybind11ViewClasses,
     FilterPybindInternals,
     FilterTypingModuleAttributes,
@@ -284,6 +285,7 @@ class Parser(
         FixValueReprRandomAddress,
         FixRedundantBuiltinsAnnotation,
         FilterPybindInternals,
+        FilterPybind11NativeEnumMembers,
         FilterPybind11ViewClasses,
         FixRedundantMethodsFromBuiltinObject,
         RemoveSelfAnnotation,

pybind11_stubgen/parser/mixins/filter.py

@@ -148,3 +148,35 @@ def handle_module_member(
             return None
 
         return result
+
+
+class FilterPybind11NativeEnumMembers(IParser):
+    @staticmethod
+    def _is_sunder(name: str) -> bool:
+        """Match CPython Enum's reserved ``_sunder_`` names.
+
+        Keep this in sync with CPython's ``enum._is_sunder``:
+        https://github.com/python/cpython/blob/3.14/Lib/enum.py#L57-L66
+
+        These names are rejected by ``EnumDict.__setitem__`` unless explicitly
+        allowlisted by ``enum`` itself:
+        https://github.com/python/cpython/blob/3.14/Lib/enum.py#L342-L367
+        """
+        return (
+            len(name) > 2
+            and name[0] == name[-1] == "_"
+            and name[1] != "_"
+            and name[-2] != "_"
+        )
+
+    def handle_class_member(
+        self, path: QualifiedName, class_: type, obj: Any
+    ) -> Docstring | Alias | Class | list[Method] | Field | Property | None:
+        name = str(path[-1])
+        # py::native_enum exposes Enum internals via __dict__, but emitting them
+        # into a stub that later gets executed as Python can fail at import time.
+        if hasattr(class_, "__pybind11_native_enum__") and (
+            name == "__pybind11_native_enum__" or self._is_sunder(name)
+        ):
+            return None
+        return super().handle_class_member(path, class_, obj)

tests/py-demo/bindings/src/modules/enum.cpp

@@ -2,6 +2,19 @@
 
 #include <demo/sublibA/ConsoleColors.h>
 
+#if PYBIND11_VERSION_AT_LEAST(3,0)
+#    include <pybind11/native_enum.h>
+#endif
+
+#if PYBIND11_VERSION_AT_LEAST(3,0)
+namespace {
+enum class NativeColor : int {
+    Red = 1,
+    Blue = 2,
+};
+} // namespace
+#endif
+
 void bind_enum_module(py::module&&m) {
 
     py::enum_<demo::sublibA::ConsoleForegroundColor>(m, "ConsoleForegroundColor")
@@ -16,4 +29,11 @@ void bind_enum_module(py::module&&m) {
         "accept_defaulted_enum",
         [](const demo::sublibA::ConsoleForegroundColor &color) {},
         py::arg("color") = demo::sublibA::ConsoleForegroundColor::None_);
+
+#if PYBIND11_VERSION_AT_LEAST(3,0)
+    py::native_enum<NativeColor>(m, "NativeColor", "enum.IntEnum")
+        .value("Red", NativeColor::Red)
+        .value("Blue", NativeColor::Blue)
+        .finalize();
+#endif
 }

tests/stubs/python-3.10

@@ -0,0 +1 @@
+../python-3.11/pybind11-v2.11

tests/stubs/python-3.10/pybind11-v2.11

@@ -0,0 +1 @@
+../python-3.11/pybind11-v2.12

tests/stubs/python-3.10/pybind11-v2.12

@@ -0,0 +1 @@
+../python-3.11/pybind11-v2.13

tests/stubs/python-3.10/pybind11-v2.13

@@ -0,0 +1 @@
+../../python-3.11/pybind11-v3.0/numpy-array-use-type-var

tests/stubs/python-3.10/pybind11-v3.0/numpy-array-use-type-var

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from demo._bindings import (
+    aliases,
+    classes,
+    eigen,
+    enum,
+    flawed_bindings,
+    functions,
+    hidden_builtins,
+    issues,
+    methods,
+    numpy,
+    properties,
+    stl,
+    stl_bind,
+    typing,
+    values,
+)
+
+from . import _bindings, core, pure_python
+
+__all__: list[str] = [
+    "aliases",
+    "classes",
+    "core",
+    "eigen",
+    "enum",
+    "flawed_bindings",
+    "functions",
+    "hidden_builtins",
+    "issues",
+    "methods",
+    "numpy",
+    "properties",
+    "pure_python",
+    "stl",
+    "stl_bind",
+    "typing",
+    "values",
+    "version",
+]
+version: str = "0.0.0"

tests/stubs/python-3.10/pybind11-v3.0/numpy-array-wrap-with-annotated/demo/__init__.pyi

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from . import (
+    aliases,
+    classes,
+    eigen,
+    enum,
+    flawed_bindings,
+    functions,
+    hidden_builtins,
+    issues,
+    methods,
+    numpy,
+    properties,
+    stl,
+    stl_bind,
+    typing,
+    values,
+)
+
+__all__: list[str] = [
+    "aliases",
+    "classes",
+    "eigen",
+    "enum",
+    "flawed_bindings",
+    "functions",
+    "hidden_builtins",
+    "issues",
+    "methods",
+    "numpy",
+    "properties",
+    "stl",
+    "stl_bind",
+    "typing",
+    "values",
+]