WIP: Conversions between Python's native (stdlib) enum and C++ enums.

include/pybind11/detail/internals.h

@@ -34,7 +34,7 @@
 /// further ABI-incompatible changes may be made before the ABI is officially
 /// changed to the new version.
 #ifndef PYBIND11_INTERNALS_VERSION
-#    define PYBIND11_INTERNALS_VERSION 4
+#    define PYBIND11_INTERNALS_VERSION 5
 #endif
 
 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
@@ -209,6 +209,9 @@ struct internals {
         PYBIND11_TLS_FREE(tstate);
     }
 #endif
+#if PYBIND11_INTERNALS_VERSION > 4
+    type_map<PyObject *> native_enum_types;
+#endif
 };
 
 /// Additional type information which does not fit into the PyTypeObject.

include/pybind11/native_enum.h

@@ -0,0 +1,67 @@
+// Copyright (c) 2022 The pybind Community.
+// All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+#pragma once
+
+#include "pybind11.h"
+
+#include <type_traits>
+
+PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
+
+/// Conversions between Python's native (stdlib) enum types and C++ enums.
+template <typename Type>
+class native_enum {
+public:
+    using Underlying = typename std::underlying_type<Type>::type;
+    // Scalar is the integer representation of underlying type
+    using Scalar = detail::conditional_t<detail::any_of<detail::is_std_char_type<Underlying>,
+                                                        std::is_same<Underlying, bool>>::value,
+                                         detail::equivalent_integer_t<Underlying>,
+                                         Underlying>;
+
+    template <typename... Extra>
+    native_enum(const handle &scope, const char *name, const Extra &.../*extra*/)
+        : m_scope(reinterpret_borrow<object>(scope)), m_name(name) {
+        constexpr bool is_arithmetic = detail::any_of<std::is_same<arithmetic, Extra>...>::value;
+        constexpr bool is_convertible = std::is_convertible<Type, Underlying>::value;
+        if (is_arithmetic || is_convertible) {
+            // IGNORED.
+        }
+    }
+
+    /// Export enumeration entries into the parent scope
+    native_enum &export_values() { return *this; }
+
+    /// Add an enumeration entry
+    native_enum &value(char const *name, Type value, const char *doc = nullptr) {
+        if (doc) {
+            // IGNORED.
+        }
+        m_members.append(make_tuple(name, static_cast<Scalar>(value)));
+        return *this;
+    }
+
+    native_enum(const native_enum &) = delete;
+    native_enum &operator=(const native_enum &) = delete;
+
+    ~native_enum() {
+        // Any exception here will terminate the process.
+        auto enum_module = module_::import("enum");
+        auto int_enum = enum_module.attr("IntEnum");
+        auto int_enum_color = int_enum(m_name, m_members);
+        int_enum_color.attr("__module__") = m_scope;
+        m_scope.attr(m_name) = int_enum_color;
+        // Intentionally leak Python reference.
+        detail::get_internals().native_enum_types[std::type_index(typeid(Type))]
+            = int_enum_color.release().ptr();
+    }
+
+private:
+    object m_scope;
+    str m_name;
+    list m_members;
+};
+
+PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)

tests/CMakeLists.txt

@@ -142,6 +142,7 @@ set(PYBIND11_TEST_FILES
     test_methods_and_attributes
     test_modules
     test_multiple_inheritance
+    test_native_enum
     test_numpy_array
     test_numpy_dtypes
     test_numpy_vectorize

tests/extra_python_package/test_files.py

@@ -36,6 +36,7 @@
     "include/pybind11/functional.h",
     "include/pybind11/gil.h",
     "include/pybind11/iostream.h",
+    "include/pybind11/native_enum.h",
     "include/pybind11/numpy.h",
     "include/pybind11/operators.h",
     "include/pybind11/options.h",

tests/test_native_enum.cpp

@@ -0,0 +1,86 @@
+#include <pybind11/native_enum.h>
+
+#include "pybind11_tests.h"
+
+namespace test_native_enum {
+
+// https://en.cppreference.com/w/cpp/language/enum
+
+// enum that takes 16 bits
+enum smallenum : std::int16_t { a, b, c };
+
+// color may be red (value 0), yellow (value 1), green (value 20), or blue (value 21)
+enum color { red, yellow, green = 20, blue };
+
+// altitude may be altitude::high or altitude::low
+enum class altitude : char {
+    high = 'h',
+    low = 'l', // trailing comma only allowed after CWG518
+};
+
+// the constant d is 0, the constant e is 1, the constant f is 3
+enum { d, e, f = e + 2 };
+
+int pass_color(color e) { return static_cast<int>(e); }
+color return_color(int i) { return static_cast<color>(i); }
+
+py::handle wrap_color(py::module_ m) {
+    auto enum_module = py::module_::import("enum");
+    auto int_enum = enum_module.attr("IntEnum");
+    using u_t = std::underlying_type<color>::type;
+    auto members = py::make_tuple(py::make_tuple("red", static_cast<u_t>(color::red)),
+                                  py::make_tuple("yellow", static_cast<u_t>(color::yellow)),
+                                  py::make_tuple("green", static_cast<u_t>(color::green)),
+                                  py::make_tuple("blue", static_cast<u_t>(color::blue)));
+    auto int_enum_color = int_enum("color", members);
+    int_enum_color.attr("__module__") = m;
+    m.attr("color") = int_enum_color;
+    return int_enum_color.release(); // Intentionally leak Python reference.
+}
+
+} // namespace test_native_enum
+
+PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
+PYBIND11_NAMESPACE_BEGIN(detail)
+
+using namespace test_native_enum;
+
+template <>
+struct type_caster<color> {
+    static handle native_type;
+
+    static handle cast(const color &src, return_value_policy /* policy */, handle /* parent */) {
+        auto u_v = static_cast<std::underlying_type<color>::type>(src);
+        return native_type(u_v).release();
+    }
+
+    bool load(handle src, bool /* convert */) {
+        if (!isinstance(src, native_type)) {
+            return false;
+        }
+        value = static_cast<color>(py::cast<std::underlying_type<color>::type>(src.attr("value")));
+        return true;
+    }
+
+    PYBIND11_TYPE_CASTER(color, const_name("<enum 'color'>"));
+};
+
+handle type_caster<color>::native_type = nullptr;
+
+PYBIND11_NAMESPACE_END(detail)
+PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
+
+TEST_SUBMODULE(native_enum, m) {
+    using namespace test_native_enum;
+
+    py::detail::type_caster<color>::native_type = wrap_color(m);
+
+    m.def("pass_color", pass_color);
+    m.def("return_color", return_color);
+
+    py::native_enum<color>(m, "WIPcolor")
+        .value("red", color::red)
+        .value("yellow", color::yellow)
+        .value("green", color::green)
+        .value("blue", color::blue);
+}

tests/test_native_enum.py

@@ -0,0 +1,51 @@
+import enum
+
+import pytest
+
+from pybind11_tests import native_enum as m
+
+COLOR_MEMBERS = (
+    ("red", 0),
+    ("yellow", 1),
+    ("green", 20),
+    ("blue", 21),
+)
+
+
+def test_enum_color_type():
+    assert isinstance(m.color, enum.EnumMeta)
+
+
+@pytest.mark.parametrize("name,value", COLOR_MEMBERS)
+def test_enum_color_members(name, value):
+    assert m.color[name] == value
+
+
+@pytest.mark.parametrize("name,value", COLOR_MEMBERS)
+def test_pass_color_success(name, value):
+    assert m.pass_color(m.color[name]) == value
+
+
+def test_pass_color_fail():
+    with pytest.raises(TypeError) as excinfo:
+        m.pass_color(None)
+    assert "<enum 'color'>" in str(excinfo.value)
+
+
+@pytest.mark.parametrize("name,value", COLOR_MEMBERS)
+def test_return_color_success(name, value):
+    assert m.return_color(value) == m.color[name]
+
+
+def test_return_color_fail():
+    with pytest.raises(ValueError) as excinfo_direct:
+        m.color(2)
+    with pytest.raises(ValueError) as excinfo_cast:
+        m.return_color(2)
+    assert str(excinfo_cast.value) == str(excinfo_direct.value)
+
+
+def test_wip_color():
+    assert isinstance(m.WIPcolor, enum.EnumMeta)
+    for name, value in COLOR_MEMBERS:
+        assert m.WIPcolor[name] == value