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

.github/workflows/python312.yml

@@ -0,0 +1,131 @@
+name: Python312
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+concurrency:
+  group: python312-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  PYTEST_TIMEOUT: 300
+
+jobs:
+  standard:
+    name: "🐍 3.12 latest • ubuntu-latest • x64"
+    runs-on: ubuntu-latest
+    # if: "contains(github.event.pull_request.labels.*.name, 'python dev')"
+
+    steps:
+    - name: Show env
+      run: env
+
+    - uses: actions/checkout@v3
+
+    - name: Setup Python 3.12
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.12-dev"
+
+    - name: Setup Boost
+      run: sudo apt-get install libboost-dev
+
+    - name: Update CMake
+      uses: jwlawson/[email protected]
+
+    - name: Run pip installs
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --prefer-binary -r tests/requirements.txt
+        python -m pip install --prefer-binary numpy
+    #   python -m pip install --prefer-binary scipy
+
+    - name: Show platform info
+      run: python -m platform
+
+    - name: Show CMake version
+      run: cmake --version
+
+    # FIRST BUILD
+    - name: Configure C++11
+      run: >
+        cmake -S . -B build11
+        -DCMAKE_VERBOSE_MAKEFILE=ON
+        -DPYBIND11_WERROR=ON
+        -DDOWNLOAD_CATCH=ON
+        -DDOWNLOAD_EIGEN=ON
+        -DCMAKE_CXX_STANDARD=11
+        -DCMAKE_BUILD_TYPE=Debug
+
+    - name: Build C++11
+      run: cmake --build build11 -j 2
+
+    - name: Python tests C++11
+      run: cmake --build build11 --target pytest -j 2
+
+    - name: C++ tests C++11
+      run: cmake --build build11 --target cpptest -j 2
+
+    - name: Interface test C++11
+      run: cmake --build build11 --target test_cmake_build
+
+    - name: Clean directory
+      run: git clean -fdx
+
+    # SECOND BUILD
+    - name: Configure C++17
+      run: >
+        cmake -S . -B build17
+        -DCMAKE_VERBOSE_MAKEFILE=ON
+        -DPYBIND11_WERROR=ON
+        -DDOWNLOAD_CATCH=ON
+        -DDOWNLOAD_EIGEN=ON
+        -DCMAKE_CXX_STANDARD=17
+        -DCMAKE_BUILD_TYPE=Debug
+
+    - name: Build C++17
+      run: cmake --build build17 -j 2
+
+    - name: Python tests C++17
+      run: cmake --build build17 --target pytest
+
+    - name: C++ tests C++17
+      run: cmake --build build17 --target cpptest
+
+    - name: Interface test C++17
+      run: cmake --build build17 --target test_cmake_build
+
+    - name: Clean directory
+      run: git clean -fdx
+
+    # THIRD BUILD
+    - name: Configure C++17 max DPYBIND11_INTERNALS_VERSION
+      run: >
+        cmake -S . -B build17max
+        -DCMAKE_VERBOSE_MAKEFILE=ON
+        -DPYBIND11_WERROR=ON
+        -DDOWNLOAD_CATCH=ON
+        -DDOWNLOAD_EIGEN=ON
+        -DCMAKE_CXX_STANDARD=17
+        -DCMAKE_BUILD_TYPE=Debug
+        -DPYBIND11_INTERNALS_VERSION=10000000
+
+    - name: Build C++17 max DPYBIND11_INTERNALS_VERSION
+      run: cmake --build build17max -j 2
+
+    - name: Python tests C++17 max DPYBIND11_INTERNALS_VERSION
+      run: cmake --build build17max --target pytest
+
+    - name: C++ tests C++17 max DPYBIND11_INTERNALS_VERSION
+      run: cmake --build build17max --target cpptest
+
+    - name: Interface test C++17 max DPYBIND11_INTERNALS_VERSION
+      run: cmake --build build17max --target test_cmake_build
+
+    # Ensure the setup_helpers module can build packages using setuptools
+    - name: Setuptools helpers test
+      run: pytest tests/extra_setuptools
+
+    - name: Clean directory
+      run: git clean -fdx

CMakeLists.txt

@@ -111,12 +111,16 @@ cmake_dependent_option(PYBIND11_FINDPYTHON "Force new FindPython" OFF
 
 # NB: when adding a header don't forget to also add it to setup.py
 set(PYBIND11_HEADERS
+    include/pybind11/detail/abi_platform_id.h
     include/pybind11/detail/class.h
     include/pybind11/detail/common.h
+    include/pybind11/detail/cross_extension_shared_state.h
     include/pybind11/detail/descr.h
     include/pybind11/detail/init.h
     include/pybind11/detail/internals.h
+    include/pybind11/detail/native_enum_data.h
     include/pybind11/detail/type_caster_base.h
+    include/pybind11/detail/type_map.h
     include/pybind11/detail/typeid.h
     include/pybind11/attr.h
     include/pybind11/buffer_info.h
@@ -133,6 +137,7 @@ set(PYBIND11_HEADERS
     include/pybind11/gil.h
     include/pybind11/iostream.h
     include/pybind11/functional.h
+    include/pybind11/native_enum.h
     include/pybind11/numpy.h
     include/pybind11/operators.h
     include/pybind11/pybind11.h

include/pybind11/cast.h

@@ -12,6 +12,7 @@
 
 #include "detail/common.h"
 #include "detail/descr.h"
+#include "detail/native_enum_data.h"
 #include "detail/type_caster_base.h"
 #include "detail/typeid.h"
 #include "pytypes.h"
@@ -48,6 +49,101 @@ cast_op(make_caster<T> &&caster) {
         template cast_op_type<typename std::add_rvalue_reference<T>::type>();
 }
 
+template <typename EnumType>
+class type_caster_enum_type {
+private:
+    using Underlying = typename std::underlying_type<EnumType>::type;
+
+public:
+    static constexpr auto name = const_name<EnumType>();
+
+    template <typename SrcType>
+    static handle cast(SrcType &&src, return_value_policy, handle parent) {
+        auto const &natives = cross_extension_shared_states::native_enum_type_map::get();
+        auto found = natives.find(std::type_index(typeid(EnumType)));
+        if (found != natives.end()) {
+            return handle(found->second)(static_cast<Underlying>(src)).release();
+        }
+        return type_caster_base<EnumType>::cast(
+            std::forward<SrcType>(src),
+            // Fixes https://github.com/pybind/pybind11/pull/3643#issuecomment-1022987818:
+            return_value_policy::copy,
+            parent);
+    }
+
+    bool load(handle src, bool convert) {
+        auto const &natives = cross_extension_shared_states::native_enum_type_map::get();
+        auto found = natives.find(std::type_index(typeid(EnumType)));
+        if (found != natives.end()) {
+            if (!isinstance(src, found->second)) {
+                return false;
+            }
+            type_caster<Underlying> underlying_caster;
+            if (!underlying_caster.load(src.attr("value"), convert)) {
+                pybind11_fail("native_enum internal consistency failure.");
+            }
+            value = static_cast<EnumType>(static_cast<Underlying>(underlying_caster));
+            return true;
+        }
+        if (!pybind11_enum_) {
+            pybind11_enum_.reset(new type_caster_base<EnumType>());
+        }
+        return pybind11_enum_->load(src, convert);
+    }
+
+    template <typename T>
+    using cast_op_type = detail::cast_op_type<T>;
+
+    // NOLINTNEXTLINE(google-explicit-constructor)
+    operator EnumType *() {
+        if (!pybind11_enum_) {
+            return &value;
+        }
+        return pybind11_enum_->operator EnumType *();
+    }
+
+    // NOLINTNEXTLINE(google-explicit-constructor)
+    operator EnumType &() {
+        if (!pybind11_enum_) {
+            return value;
+        }
+        return pybind11_enum_->operator EnumType &();
+    }
+
+private:
+    std::unique_ptr<type_caster_base<EnumType>> pybind11_enum_;
+    EnumType value;
+};
+
+template <typename EnumType, typename SFINAE = void>
+struct type_caster_enum_type_enabled : std::true_type {};
+
+template <typename EnumType>
+class type_caster<EnumType,
+                  detail::enable_if_t<std::is_enum<EnumType>::value
+                                      && type_caster_enum_type_enabled<EnumType>::value>>
+    : public type_caster_enum_type<EnumType> {};
+
+template <typename T, detail::enable_if_t<std::is_enum<T>::value, int> = 0>
+bool isinstance_native_enum_impl(handle obj, const std::type_info &tp) {
+    auto const &natives = cross_extension_shared_states::native_enum_type_map::get();
+    auto found = natives.find(tp);
+    if (found == natives.end()) {
+        return false;
+    }
+    return isinstance(obj, found->second);
+}
+
+template <typename T, detail::enable_if_t<!std::is_enum<T>::value, int> = 0>
+bool isinstance_native_enum_impl(handle, const std::type_info &) {
+    return false;
+}
+
+template <typename T>
+bool isinstance_native_enum(handle obj, const std::type_info &tp) {
+    return isinstance_native_enum_impl<intrinsic_t<T>>(obj, tp);
+}
+
 template <typename type>
 class type_caster<std::reference_wrapper<type>> {
 private:
@@ -1037,8 +1133,19 @@ PYBIND11_NAMESPACE_END(detail)
 template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0>
 T cast(const handle &handle) {
     using namespace detail;
-    static_assert(!cast_is_temporary_value_reference<T>::value,
+    constexpr bool is_enum_cast
+        = std::is_base_of<type_caster_enum_type<intrinsic_t<T>>, make_caster<T>>::value;
+    static_assert(!cast_is_temporary_value_reference<T>::value || is_enum_cast,
                   "Unable to cast type to reference: value is local to type caster");
+#ifndef NDEBUG
+    if (is_enum_cast) {
+        if (cross_extension_shared_states::native_enum_type_map::get().count(
+                std::type_index(typeid(intrinsic_t<T>)))
+            != 0) {
+            pybind11_fail("Unable to cast native enum type to reference");
+        }
+    }
+#endif
     return cast_op<T>(load_type<T>(handle));
 }
 

include/pybind11/detail/abi_platform_id.h

@@ -0,0 +1,93 @@
+// 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 "common.h"
+
+/// On MSVC, debug and release builds are not ABI-compatible!
+#if defined(_MSC_VER) && defined(_DEBUG)
+#    define PYBIND11_BUILD_TYPE "_debug"
+#else
+#    define PYBIND11_BUILD_TYPE ""
+#endif
+
+/// Let's assume that different compilers are ABI-incompatible.
+/// A user can manually set this string if they know their
+/// compiler is compatible.
+#ifndef PYBIND11_COMPILER_TYPE
+#    if defined(_MSC_VER)
+#        define PYBIND11_COMPILER_TYPE "_msvc"
+#    elif defined(__INTEL_COMPILER)
+#        define PYBIND11_COMPILER_TYPE "_icc"
+#    elif defined(__clang__)
+#        define PYBIND11_COMPILER_TYPE "_clang"
+#    elif defined(__PGI)
+#        define PYBIND11_COMPILER_TYPE "_pgi"
+#    elif defined(__MINGW32__)
+#        define PYBIND11_COMPILER_TYPE "_mingw"
+#    elif defined(__CYGWIN__)
+#        define PYBIND11_COMPILER_TYPE "_gcc_cygwin"
+#    elif defined(__GNUC__)
+#        define PYBIND11_COMPILER_TYPE "_gcc"
+#    else
+#        define PYBIND11_COMPILER_TYPE "_unknown"
+#    endif
+#endif
+
+/// Also standard libs
+#ifndef PYBIND11_STDLIB
+#    if defined(_LIBCPP_VERSION)
+#        define PYBIND11_STDLIB "_libcpp"
+#    elif defined(__GLIBCXX__) || defined(__GLIBCPP__)
+#        define PYBIND11_STDLIB "_libstdcpp"
+#    else
+#        define PYBIND11_STDLIB ""
+#    endif
+#endif
+
+/// On Linux/OSX, changes in __GXX_ABI_VERSION__ indicate ABI incompatibility.
+#ifndef PYBIND11_BUILD_ABI
+#    if defined(__GXX_ABI_VERSION)
+#        define PYBIND11_BUILD_ABI "_cxxabi" PYBIND11_TOSTRING(__GXX_ABI_VERSION)
+#    else
+#        define PYBIND11_BUILD_ABI ""
+#    endif
+#endif
+
+#ifndef PYBIND11_INTERNALS_KIND
+#    if defined(WITH_THREAD)
+#        define PYBIND11_INTERNALS_KIND ""
+#    else
+#        define PYBIND11_INTERNALS_KIND "_without_thread"
+#    endif
+#endif
+
+/* NOTE - ATTENTION - WARNING - EXTREME CAUTION
+   Changing this will break compatibility with `PYBIND11_INTERNALS_VERSION 4`
+   See pybind11/detail/type_map.h for more information.
+ */
+#define PYBIND11_PLATFORM_ABI_ID_V4                                                               \
+    PYBIND11_INTERNALS_KIND PYBIND11_COMPILER_TYPE PYBIND11_STDLIB PYBIND11_BUILD_ABI             \
+        PYBIND11_BUILD_TYPE
+
+/// LEGACY "ABI-breaking" APPROACH, ORIGINAL COMMENT
+/// ------------------------------------------------
+/// Tracks the `internals` and `type_info` ABI version independent of the main library version.
+///
+/// Some portions of the code use an ABI that is conditional depending on this
+/// version number.  That allows ABI-breaking changes to be "pre-implemented".
+/// Once the default version number is incremented, the conditional logic that
+/// no longer applies can be removed.  Additionally, users that need not
+/// maintain ABI compatibility can increase the version number in order to take
+/// advantage of any functionality/efficiency improvements that depend on the
+/// newer ABI.
+///
+/// WARNING: If you choose to manually increase the ABI version, note that
+/// pybind11 may not be tested as thoroughly with a non-default ABI version, and
+/// 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
+#endif