diff --git a/CMakeLists.txt b/CMakeLists.txt index 8783dba6e3..266e111723 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -134,6 +134,7 @@ set(PYBIND11_HEADERS include/pybind11/detail/dynamic_raw_ptr_cast_if_possible.h include/pybind11/detail/init.h include/pybind11/detail/internals.h + include/pybind11/detail/native_enum_data.h include/pybind11/detail/struct_smart_holder.h include/pybind11/detail/type_caster_base.h include/pybind11/detail/typeid.h @@ -160,6 +161,7 @@ set(PYBIND11_HEADERS include/pybind11/gil_safe_call_once.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 diff --git a/docs/classes.rst b/docs/classes.rst index 5406668f0b..f53fdb5c2e 100644 --- a/docs/classes.rst +++ b/docs/classes.rst @@ -459,8 +459,8 @@ you can use ``py::detail::overload_cast_impl`` with an additional set of parenth other using the ``.def(py::init<...>())`` syntax. The existing machinery for specifying keyword and default arguments also works. -Enumerations and internal types -=============================== +Enumerations +============ Let's now suppose that the example class contains internal types like enumerations, e.g.: @@ -494,69 +494,37 @@ The binding code for this example looks as follows: .def_readwrite("type", &Pet::type) .def_readwrite("attr", &Pet::attr); - py::enum_(pet, "Kind") + py::native_enum(pet, "Kind") .value("Dog", Pet::Kind::Dog) .value("Cat", Pet::Kind::Cat) - .export_values(); + .export_values() + .finalize(); py::class_(pet, "Attributes") .def(py::init<>()) .def_readwrite("age", &Pet::Attributes::age); -To ensure that the nested types ``Kind`` and ``Attributes`` are created within the scope of ``Pet``, the -``pet`` ``py::class_`` instance must be supplied to the :class:`enum_` and ``py::class_`` -constructor. The :func:`enum_::export_values` function exports the enum entries -into the parent scope, which should be skipped for newer C++11-style strongly -typed enums. - -.. code-block:: pycon - - >>> p = Pet("Lucy", Pet.Cat) - >>> p.type - Kind.Cat - >>> int(p.type) - 1L - -The entries defined by the enumeration type are exposed in the ``__members__`` property: - -.. code-block:: pycon - - >>> Pet.Kind.__members__ - {'Dog': Kind.Dog, 'Cat': Kind.Cat} - -The ``name`` property returns the name of the enum value as a unicode string. - -.. note:: - - It is also possible to use ``str(enum)``, however these accomplish different - goals. The following shows how these two approaches differ. - - .. code-block:: pycon - - >>> p = Pet("Lucy", Pet.Cat) - >>> pet_type = p.type - >>> pet_type - Pet.Cat - >>> str(pet_type) - 'Pet.Cat' - >>> pet_type.name - 'Cat' - -.. note:: - - When the special tag ``py::arithmetic()`` is specified to the ``enum_`` - constructor, pybind11 creates an enumeration that also supports rudimentary - arithmetic and bit-level operations like comparisons, and, or, xor, negation, - etc. - - .. code-block:: cpp - - py::enum_(pet, "Kind", py::arithmetic()) - ... - - By default, these are omitted to conserve space. - -.. warning:: - - Contrary to Python customs, enum values from the wrappers should not be compared using ``is``, but with ``==`` (see `#1177 `_ for background). +To ensure that the nested types ``Kind`` and ``Attributes`` are created +within the scope of ``Pet``, the ``pet`` ``py::class_`` instance must be +supplied to the ``py::native_enum`` and ``py::class_`` constructors. The +``.export_values()`` function is available for exporting the enum entries +into the parent scope, if desired. + +The ``.finalize()`` call above is needed because Python's native enums +cannot be built incrementally, but all name/value pairs need to be passed at +once. To achieve this, ``py::native_enum`` acts as a buffer to collect the +name/value pairs. The ``.finalize()`` call uses the accumulated name/value +pairs to build the arguments for constructing a native Python enum type. + +``py::native_enum`` was introduced with pybind11 release v3.0.0. It binds C++ +enum types to Python's native enum.Enum, making them PEP 435 compatible. This +is the recommended way to bind C++ enums. The older ``py::enum_`` is +not PEP 435 compatible +(see `issue #2332 `_) +but remains supported indefinitely for backward compatibility. +New bindings should prefer ``py::native_enum``. + +For details about the deprecated ``py::enum_``, please refer to +:file:`tests/test_enum.cpp` and +:file:`tests/test_enum.py`. diff --git a/include/pybind11/cast.h b/include/pybind11/cast.h index 47575084c8..caa1e9e851 100644 --- a/include/pybind11/cast.h +++ b/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" @@ -53,6 +54,104 @@ cast_op(make_caster &&caster) { return std::move(caster).operator result_t(); } +template +class type_caster_enum_type { +private: + using Underlying = typename std::underlying_type::type; + +public: + static constexpr auto name = const_name(); + + template + static handle cast(SrcType &&src, return_value_policy, handle parent) { + handle native_enum + = global_internals_native_enum_type_map_get_item(std::type_index(typeid(EnumType))); + if (native_enum) { + return native_enum(static_cast(src)).release(); + } + return type_caster_base::cast( + std::forward(src), + // Fixes https://github.com/pybind/pybind11/pull/3643#issuecomment-1022987818: + return_value_policy::copy, + parent); + } + + bool load(handle src, bool convert) { + handle native_enum + = global_internals_native_enum_type_map_get_item(std::type_index(typeid(EnumType))); + if (native_enum) { + if (!isinstance(src, native_enum)) { + return false; + } + type_caster underlying_caster; + if (!underlying_caster.load(src.attr("value"), convert)) { + pybind11_fail("native_enum internal consistency failure."); + } + value = static_cast(static_cast(underlying_caster)); + return true; + } + if (!pybind11_enum_) { + pybind11_enum_.reset(new type_caster_base()); + } + return pybind11_enum_->load(src, convert); + } + + template + using cast_op_type = detail::cast_op_type; + + // 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> pybind11_enum_; + EnumType value; +}; + +template +struct type_caster_enum_type_enabled : std::true_type {}; + +template +struct type_uses_type_caster_enum_type { + static constexpr bool value + = std::is_enum::value && type_caster_enum_type_enabled::value; +}; + +template +class type_caster::value>> + : public type_caster_enum_type {}; + +template ::value, int> = 0> +bool isinstance_native_enum_impl(handle obj, const std::type_info &tp) { + handle native_enum = global_internals_native_enum_type_map_get_item(tp); + if (!native_enum) { + return false; + } + return isinstance(obj, native_enum); +} + +template ::value, int> = 0> +bool isinstance_native_enum_impl(handle, const std::type_info &) { + return false; +} + +template +bool isinstance_native_enum(handle obj, const std::type_info &tp) { + return isinstance_native_enum_impl>(obj, tp); +} + template class type_caster> { private: @@ -1468,8 +1567,17 @@ template T cast(const handle &handle) { using namespace detail; - static_assert(!cast_is_temporary_value_reference::value, + constexpr bool is_enum_cast = type_uses_type_caster_enum_type>::value; + static_assert(!cast_is_temporary_value_reference::value || is_enum_cast, "Unable to cast type to reference: value is local to type caster"); +#ifndef NDEBUG + if (is_enum_cast && cast_is_temporary_value_reference::value) { + if (detail::global_internals_native_enum_type_map_contains( + std::type_index(typeid(intrinsic_t)))) { + pybind11_fail("Unable to cast native enum type to reference"); + } + } +#endif return cast_op(load_type(handle)); } diff --git a/include/pybind11/detail/class.h b/include/pybind11/detail/class.h index 08e23afb59..98ff61f5d7 100644 --- a/include/pybind11/detail/class.h +++ b/include/pybind11/detail/class.h @@ -716,15 +716,7 @@ inline PyObject *make_new_python_type(const type_record &rec) { PyUnicode_FromFormat("%U.%U", rec.scope.attr("__qualname__").ptr(), name.ptr())); } - object module_; - if (rec.scope) { - if (hasattr(rec.scope, "__module__")) { - module_ = rec.scope.attr("__module__"); - } else if (hasattr(rec.scope, "__name__")) { - module_ = rec.scope.attr("__name__"); - } - } - + object module_ = get_module_name_if_available(rec.scope); const auto *full_name = c_str( #if !defined(PYPY_VERSION) module_ ? str(module_).cast() + "." + rec.name : diff --git a/include/pybind11/detail/internals.h b/include/pybind11/detail/internals.h index 841c8fe155..2fd1f6719c 100644 --- a/include/pybind11/detail/internals.h +++ b/include/pybind11/detail/internals.h @@ -37,11 +37,11 @@ /// 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 7 +# define PYBIND11_INTERNALS_VERSION 8 #endif -#if PYBIND11_INTERNALS_VERSION < 7 -# error "PYBIND11_INTERNALS_VERSION 7 is the minimum for all platforms for pybind11v3." +#if PYBIND11_INTERNALS_VERSION < 8 +# error "PYBIND11_INTERNALS_VERSION 8 is the minimum for all platforms for pybind11v3." #endif PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) @@ -194,6 +194,8 @@ struct internals { // We want unique addresses since we use pointer equality to compare function records std::string function_record_capsule_name = internals_function_record_capsule_name; + type_map native_enum_type_map; + internals() = default; internals(const internals &other) = delete; internals &operator=(const internals &other) = delete; diff --git a/include/pybind11/detail/native_enum_data.h b/include/pybind11/detail/native_enum_data.h new file mode 100644 index 0000000000..c04624757b --- /dev/null +++ b/include/pybind11/detail/native_enum_data.h @@ -0,0 +1,142 @@ +// Copyright (c) 2022-2025 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 + +#define PYBIND11_HAS_NATIVE_ENUM + +#include "../pytypes.h" +#include "common.h" +#include "internals.h" + +#include +#include +#include + +PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) +PYBIND11_NAMESPACE_BEGIN(detail) + +// This is a separate function only to enable easy unit testing. +inline std::string +native_enum_missing_finalize_error_message(const std::string &enum_name_encoded) { + return "pybind11::native_enum<...>(\"" + enum_name_encoded + "\", ...): MISSING .finalize()"; +} + +class native_enum_data { +public: + native_enum_data(const object &parent_scope, + const char *enum_name, + const std::type_index &enum_type_index, + bool use_int_enum) + : enum_name_encoded{enum_name}, enum_type_index{enum_type_index}, enum_name{enum_name}, + parent_scope(parent_scope), export_values_flag{false}, use_int_enum{use_int_enum}, + finalize_needed{false} {} + + void finalize(); + + native_enum_data(const native_enum_data &) = delete; + native_enum_data &operator=(const native_enum_data &) = delete; + +#if !defined(NDEBUG) + // This dtor cannot easily be unit tested because it terminates the process. + ~native_enum_data() { + if (finalize_needed) { + pybind11_fail(native_enum_missing_finalize_error_message(enum_name_encoded)); + } + } +#endif + +protected: + void disarm_finalize_check(const char *error_context) { + if (!finalize_needed) { + pybind11_fail("pybind11::native_enum<...>(\"" + enum_name_encoded + + "\"): " + error_context); + } + finalize_needed = false; + } + + void arm_finalize_check() { + assert(!finalize_needed); + finalize_needed = true; + } + + std::string enum_name_encoded; + std::type_index enum_type_index; + +private: + str enum_name; + object parent_scope; + +protected: + list members; + list docs; + bool export_values_flag : 1; + +private: + bool use_int_enum : 1; + bool finalize_needed : 1; +}; + +inline void global_internals_native_enum_type_map_set_item(const std::type_index &enum_type_index, + PyObject *py_enum) { + with_internals( + [&](internals &internals) { internals.native_enum_type_map[enum_type_index] = py_enum; }); +} + +inline handle +global_internals_native_enum_type_map_get_item(const std::type_index &enum_type_index) { + return with_internals([&](internals &internals) { + auto found = internals.native_enum_type_map.find(enum_type_index); + if (found != internals.native_enum_type_map.end()) { + return handle(found->second); + } + return handle(); + }); +} + +inline bool +global_internals_native_enum_type_map_contains(const std::type_index &enum_type_index) { + return with_internals([&](internals &internals) { + return internals.native_enum_type_map.count(enum_type_index) != 0; + }); +} + +inline void native_enum_data::finalize() { + disarm_finalize_check("DOUBLE finalize"); + if (hasattr(parent_scope, enum_name)) { + pybind11_fail("pybind11::native_enum<...>(\"" + enum_name_encoded + + "\"): an object with that name is already defined"); + } + auto enum_module = reinterpret_steal(PyImport_ImportModule("enum")); + if (!enum_module) { + raise_from(PyExc_SystemError, + "`import enum` FAILED at " __FILE__ ":" PYBIND11_TOSTRING(__LINE__)); + throw error_already_set(); + } + auto py_enum_type = enum_module.attr(use_int_enum ? "IntEnum" : "Enum"); + auto py_enum = py_enum_type(enum_name, members); + object module_name = get_module_name_if_available(parent_scope); + if (module_name) { + py_enum.attr("__module__") = module_name; + } + parent_scope.attr(enum_name) = py_enum; + if (export_values_flag) { + for (auto member : members) { + auto member_name = member[int_(0)]; + if (hasattr(parent_scope, member_name)) { + pybind11_fail("pybind11::native_enum<...>(\"" + enum_name_encoded + "\").value(\"" + + member_name.cast() + + "\"): an object with that name is already defined"); + } + parent_scope.attr(member_name) = py_enum[member_name]; + } + } + for (auto doc : docs) { + py_enum[doc[int_(0)]].attr("__doc__") = doc[int_(1)]; + } + global_internals_native_enum_type_map_set_item(enum_type_index, py_enum.release().ptr()); +} + +PYBIND11_NAMESPACE_END(detail) +PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE) diff --git a/include/pybind11/native_enum.h b/include/pybind11/native_enum.h new file mode 100644 index 0000000000..6ea4aa51f1 --- /dev/null +++ b/include/pybind11/native_enum.h @@ -0,0 +1,66 @@ +// Copyright (c) 2022-2025 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 "detail/common.h" +#include "detail/native_enum_data.h" +#include "detail/type_caster_base.h" +#include "cast.h" + +#include +#include +#include + +PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) + +enum class native_enum_kind { Enum, IntEnum }; + +/// Conversions between Python's native (stdlib) enum types and C++ enums. +template +class native_enum : public detail::native_enum_data { +public: + using Underlying = typename std::underlying_type::type; + + explicit native_enum(const object &parent_scope, const char *name, native_enum_kind kind) + : detail::native_enum_data(parent_scope, + name, + std::type_index(typeid(Type)), + kind == native_enum_kind::IntEnum) { + if (detail::get_local_type_info(typeid(Type)) != nullptr + || detail::get_global_type_info(typeid(Type)) != nullptr) { + pybind11_fail( + "pybind11::native_enum<...>(\"" + enum_name_encoded + + "\") is already registered as a `pybind11::enum_` or `pybind11::class_`!"); + } + if (detail::global_internals_native_enum_type_map_contains(enum_type_index)) { + pybind11_fail("pybind11::native_enum<...>(\"" + enum_name_encoded + + "\") is already registered!"); + } + arm_finalize_check(); + } + + /// Export enumeration entries into the parent scope + native_enum &export_values() { + export_values_flag = true; + return *this; + } + + /// Add an enumeration entry + native_enum &value(char const *name, Type value, const char *doc = nullptr) { + // Disarm for the case that the native_enum_data dtor runs during exception unwinding. + disarm_finalize_check("value after finalize"); + members.append(make_tuple(name, static_cast(value))); + if (doc) { + docs.append(make_tuple(name, doc)); + } + arm_finalize_check(); // There was no exception. + return *this; + } + + native_enum(const native_enum &) = delete; + native_enum &operator=(const native_enum &) = delete; +}; + +PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE) diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h index 4dee2c55fa..19096e84b2 100644 --- a/include/pybind11/pybind11.h +++ b/include/pybind11/pybind11.h @@ -13,6 +13,7 @@ #include "detail/dynamic_raw_ptr_cast_if_possible.h" #include "detail/exception_translation.h" #include "detail/init.h" +#include "detail/native_enum_data.h" #include "detail/using_smart_holder.h" #include "attr.h" #include "gil.h" @@ -2668,6 +2669,14 @@ class enum_ : public class_ { template enum_(const handle &scope, const char *name, const Extra &...extra) : class_(scope, name, extra...), m_base(*this, scope) { + { + if (detail::global_internals_native_enum_type_map_contains( + std::type_index(typeid(Type)))) { + pybind11_fail("pybind11::enum_ \"" + std::string(name) + + "\" is already registered as a pybind11::native_enum!"); + } + } + constexpr bool is_arithmetic = detail::any_of...>::value; constexpr bool is_convertible = std::is_convertible::value; m_base.init(is_arithmetic, is_convertible); diff --git a/include/pybind11/pytypes.h b/include/pybind11/pytypes.h index 92e0a81f44..b38526e8f6 100644 --- a/include/pybind11/pytypes.h +++ b/include/pybind11/pytypes.h @@ -48,6 +48,9 @@ PYBIND11_NAMESPACE_BEGIN(detail) class args_proxy; bool isinstance_generic(handle obj, const std::type_info &tp); +template +bool isinstance_native_enum(handle obj, const std::type_info &tp); + // Accessor forward declarations template class accessor; @@ -859,7 +862,8 @@ bool isinstance(handle obj) { template ::value, int> = 0> bool isinstance(handle obj) { - return detail::isinstance_generic(obj, typeid(T)); + return detail::isinstance_native_enum(obj, typeid(T)) + || detail::isinstance_generic(obj, typeid(T)); } template <> @@ -2651,5 +2655,18 @@ PYBIND11_MATH_OPERATOR_BINARY_INPLACE(operator>>=, PyNumber_InPlaceRshift) #undef PYBIND11_MATH_OPERATOR_BINARY #undef PYBIND11_MATH_OPERATOR_BINARY_INPLACE +// Meant to return a Python str, but this is not checked. +inline object get_module_name_if_available(handle scope) { + if (scope) { + if (hasattr(scope, "__module__")) { + return scope.attr("__module__"); + } + if (hasattr(scope, "__name__")) { + return scope.attr("__name__"); + } + } + return object(); +} + PYBIND11_NAMESPACE_END(detail) PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE) diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index e2fab9c13d..1b65729dfd 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -154,6 +154,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 diff --git a/tests/extra_python_package/test_files.py b/tests/extra_python_package/test_files.py index 5d7299c2ac..2fa47c614a 100644 --- a/tests/extra_python_package/test_files.py +++ b/tests/extra_python_package/test_files.py @@ -38,6 +38,7 @@ "include/pybind11/gil.h", "include/pybind11/gil_safe_call_once.h", "include/pybind11/iostream.h", + "include/pybind11/native_enum.h", "include/pybind11/numpy.h", "include/pybind11/operators.h", "include/pybind11/options.h", @@ -66,6 +67,7 @@ "include/pybind11/detail/dynamic_raw_ptr_cast_if_possible.h", "include/pybind11/detail/init.h", "include/pybind11/detail/internals.h", + "include/pybind11/detail/native_enum_data.h", "include/pybind11/detail/struct_smart_holder.h", "include/pybind11/detail/type_caster_base.h", "include/pybind11/detail/typeid.h", diff --git a/tests/test_enum.cpp b/tests/test_enum.cpp index 2597b275ef..4ec0af7245 100644 --- a/tests/test_enum.cpp +++ b/tests/test_enum.cpp @@ -130,4 +130,20 @@ TEST_SUBMODULE(enums, m) { py::enum_(m, "ScopedBoolEnum") .value("FALSE", ScopedBoolEnum::FALSE) .value("TRUE", ScopedBoolEnum::TRUE); + +#if defined(__MINGW32__) + m.attr("obj_cast_UnscopedEnum_ptr") = "MinGW: dangling pointer to an unnamed temporary may be " + "used [-Werror=dangling-pointer=]"; +#else + m.def("obj_cast_UnscopedEnum_ptr", [](const py::object &obj) { + // https://github.com/OpenImageIO/oiio/blob/30ea4ebdfab11aec291befbaff446f2a7d24835b/src/python/py_oiio.h#L300 + if (py::isinstance(obj)) { + if (*obj.cast() == UnscopedEnum::ETwo) { + return 2; + } + return 1; + } + return 0; + }); +#endif } diff --git a/tests/test_enum.py b/tests/test_enum.py index 044ef1803e..697e28843f 100644 --- a/tests/test_enum.py +++ b/tests/test_enum.py @@ -331,3 +331,12 @@ def test_generated_dunder_methods_pos_only(): ) is not None ) + + +@pytest.mark.skipif( + isinstance(m.obj_cast_UnscopedEnum_ptr, str), reason=m.obj_cast_UnscopedEnum_ptr +) +def test_obj_cast_unscoped_enum_ptr(): + assert m.obj_cast_UnscopedEnum_ptr(m.UnscopedEnum.ETwo) == 2 + assert m.obj_cast_UnscopedEnum_ptr(m.UnscopedEnum.EOne) == 1 + assert m.obj_cast_UnscopedEnum_ptr(None) == 0 diff --git a/tests/test_native_enum.cpp b/tests/test_native_enum.cpp new file mode 100644 index 0000000000..801d874496 --- /dev/null +++ b/tests/test_native_enum.cpp @@ -0,0 +1,221 @@ +#include + +#include "pybind11_tests.h" + +#include + +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 +}; + +enum class export_values { exv0, exv1 }; + +enum class member_doc { mem0, mem1, mem2 }; + +struct class_with_enum { + enum class in_class { one, two }; +}; + +// https://github.com/protocolbuffers/protobuf/blob/d70b5c5156858132decfdbae0a1103e6a5cb1345/src/google/protobuf/generated_enum_util.h#L52-L53 +template +struct is_proto_enum : std::false_type {}; + +enum some_proto_enum : int { Zero, One }; + +template <> +struct is_proto_enum : std::true_type {}; + +} // namespace test_native_enum + +PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) +PYBIND11_NAMESPACE_BEGIN(detail) + +template +struct type_caster_enum_type_enabled< + ProtoEnumType, + detail::enable_if_t::value>> : std::false_type { +}; + +// https://github.com/pybind/pybind11_protobuf/blob/a50899c2eb604fc5f25deeb8901eff6231b8b3c0/pybind11_protobuf/enum_type_caster.h#L101-L105 +template +struct type_caster::value>> { + static handle + cast(const ProtoEnumType & /*src*/, return_value_policy /*policy*/, handle /*parent*/) { + return py::none(); + } + + bool load(handle /*src*/, bool /*convert*/) { + value = static_cast(0); + return true; + } + + PYBIND11_TYPE_CASTER(ProtoEnumType, const_name()); +}; + +PYBIND11_NAMESPACE_END(detail) +PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE) + +TEST_SUBMODULE(native_enum, m) { + using namespace test_native_enum; + + py::native_enum(m, "smallenum", py::native_enum_kind::IntEnum) + .value("a", smallenum::a) + .value("b", smallenum::b) + .value("c", smallenum::c) + .finalize(); + + py::native_enum(m, "color", py::native_enum_kind::IntEnum) + .value("red", color::red) + .value("yellow", color::yellow) + .value("green", color::green) + .value("blue", color::blue) + .finalize(); + + py::native_enum(m, "altitude", py::native_enum_kind::Enum) + .value("high", altitude::high) + .value("low", altitude::low) + .finalize(); + + py::native_enum(m, "export_values", py::native_enum_kind::IntEnum) + .value("exv0", export_values::exv0) + .value("exv1", export_values::exv1) + .export_values() + .finalize(); + + py::native_enum(m, "member_doc", py::native_enum_kind::IntEnum) + .value("mem0", member_doc::mem0, "docA") + .value("mem1", member_doc::mem1) + .value("mem2", member_doc::mem2, "docC") + .finalize(); + + py::class_ py_class_with_enum(m, "class_with_enum"); + py::native_enum( + py_class_with_enum, "in_class", py::native_enum_kind::IntEnum) + .value("one", class_with_enum::in_class::one) + .value("two", class_with_enum::in_class::two) + .finalize(); + + m.def("isinstance_color", [](const py::object &obj) { return py::isinstance(obj); }); + + m.def("pass_color", [](color e) { return static_cast(e); }); + m.def("return_color", [](int i) { return static_cast(i); }); + + m.def("pass_some_proto_enum", [](some_proto_enum) { return py::none(); }); + m.def("return_some_proto_enum", []() { return some_proto_enum::Zero; }); + +#if defined(__MINGW32__) + m.attr("obj_cast_color_ptr") = "MinGW: dangling pointer to an unnamed temporary may be used " + "[-Werror=dangling-pointer=]"; +#elif defined(NDEBUG) + m.attr("obj_cast_color_ptr") = "NDEBUG disables cast safety check"; +#else + m.def("obj_cast_color_ptr", [](const py::object &obj) { obj.cast(); }); +#endif + + m.def("py_cast_color_handle", [](py::handle obj) { + // Exercises `if (is_enum_cast && cast_is_temporary_value_reference::value)` + // in `T cast(const handle &handle)` + auto e = py::cast(obj); + return static_cast(e); + }); + + m.def("native_enum_data_missing_finalize_error_message", + [](const std::string &enum_name_encoded) { + return py::detail::native_enum_missing_finalize_error_message(enum_name_encoded); + }); + + m.def("native_enum_ctor_malformed_utf8", [](const char *malformed_utf8) { + enum fake { x }; + py::native_enum{py::none(), malformed_utf8, py::native_enum_kind::IntEnum}; + }); + + m.def("native_enum_double_finalize", [](py::module_ &m) { + enum fake { x }; + py::native_enum ne( + m, "fake_native_enum_double_finalize", py::native_enum_kind::IntEnum); + ne.finalize(); + ne.finalize(); + }); + + m.def("native_enum_value_after_finalize", [](py::module_ &m) { + enum fake { x }; + py::native_enum ne( + m, "fake_native_enum_value_after_finalize", py::native_enum_kind::IntEnum); + ne.finalize(); + ne.value("x", fake::x); + }); + + m.def("native_enum_value_malformed_utf8", [](const char *malformed_utf8) { + enum fake { x }; + py::native_enum(py::none(), "fake", py::native_enum_kind::IntEnum) + .value(malformed_utf8, fake::x); + }); + + m.def("double_registration_native_enum", [](py::module_ &m) { + enum fake { x }; + py::native_enum( + m, "fake_double_registration_native_enum", py::native_enum_kind::IntEnum) + .value("x", fake::x) + .finalize(); + py::native_enum( + m, "fake_double_registration_native_enum", py::native_enum_kind::Enum); + }); + + m.def("native_enum_name_clash", [](py::module_ &m) { + enum fake { x }; + py::native_enum(m, "fake_native_enum_name_clash", py::native_enum_kind::IntEnum) + .value("x", fake::x) + .finalize(); + }); + + m.def("native_enum_value_name_clash", [](py::module_ &m) { + enum fake { x }; + py::native_enum( + m, "fake_native_enum_value_name_clash", py::native_enum_kind::IntEnum) + .value("fake_native_enum_value_name_clash_x", fake::x) + .export_values() + .finalize(); + }); + + m.def("double_registration_enum_before_native_enum", [](py::module_ &m) { + enum fake { x }; + py::enum_(m, "fake_enum_first").value("x", fake::x); + py::native_enum(m, "fake_enum_first", py::native_enum_kind::IntEnum) + .value("x", fake::x) + .finalize(); + }); + + m.def("double_registration_native_enum_before_enum", [](py::module_ &m) { + enum fake { x }; + py::native_enum(m, "fake_native_enum_first", py::native_enum_kind::IntEnum) + .value("x", fake::x) + .finalize(); + py::enum_(m, "name_must_be_different_to_reach_desired_code_path"); + }); + +#if defined(PYBIND11_NEGATE_THIS_CONDITION_FOR_LOCAL_TESTING) && !defined(NDEBUG) + m.def("native_enum_missing_finalize_failure", []() { + enum fake { x }; + py::native_enum( + py::none(), "fake_native_enum_missing_finalize_failure", py::native_enum_kind::IntEnum) + .value("x", fake::x) + // .finalize() missing + ; + }); +#else + m.attr("native_enum_missing_finalize_failure") = "For local testing only: terminates process"; +#endif +} diff --git a/tests/test_native_enum.py b/tests/test_native_enum.py new file mode 100644 index 0000000000..1ad51a6fcb --- /dev/null +++ b/tests/test_native_enum.py @@ -0,0 +1,237 @@ +from __future__ import annotations + +import enum +import pickle + +import pytest + +import env +from pybind11_tests import native_enum as m + +SMALLENUM_MEMBERS = ( + ("a", 0), + ("b", 1), + ("c", 2), +) + +COLOR_MEMBERS = ( + ("red", 0), + ("yellow", 1), + ("green", 20), + ("blue", 21), +) + +ALTITUDE_MEMBERS = ( + ("high", "h"), + ("low", "l"), +) + +CLASS_WITH_ENUM_IN_CLASS_MEMBERS = ( + ("one", 0), + ("two", 1), +) + +EXPORT_VALUES_MEMBERS = ( + ("exv0", 0), + ("exv1", 1), +) + +MEMBER_DOC_MEMBERS = ( + ("mem0", 0), + ("mem1", 1), + ("mem2", 2), +) + +ENUM_TYPES_AND_MEMBERS = ( + (m.smallenum, SMALLENUM_MEMBERS), + (m.color, COLOR_MEMBERS), + (m.altitude, ALTITUDE_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), +) + +ENUM_TYPES = [_[0] for _ in ENUM_TYPES_AND_MEMBERS] + + +@pytest.mark.parametrize("enum_type", ENUM_TYPES) +def test_enum_type(enum_type): + assert isinstance(enum_type, enum.EnumMeta) + assert enum_type.__module__ == m.__name__ + + +@pytest.mark.parametrize(("enum_type", "members"), ENUM_TYPES_AND_MEMBERS) +def test_enum_members(enum_type, members): + for name, value in members: + assert enum_type[name].value == value + + +@pytest.mark.parametrize(("enum_type", "members"), ENUM_TYPES_AND_MEMBERS) +def test_pickle_roundtrip(enum_type, members): + for name, _ in members: + orig = enum_type[name] + if enum_type is m.class_with_enum.in_class: + # This is a general pickle limitation. + with pytest.raises(pickle.PicklingError): + pickle.dumps(orig) + else: + # This only works if __module__ is correct. + serialized = pickle.dumps(orig) + restored = pickle.loads(serialized) + assert restored == orig + + +def test_export_values(): + assert m.exv0 is m.export_values.exv0 + assert m.exv1 is m.export_values.exv1 + + +def test_member_doc(): + pure_native = enum.IntEnum("pure_native", (("mem", 0),)) + assert m.member_doc.mem0.__doc__ == "docA" + assert m.member_doc.mem1.__doc__ == pure_native.mem.__doc__ + assert m.member_doc.mem2.__doc__ == "docC" + + +def test_pybind11_isinstance_color(): + for name, _ in COLOR_MEMBERS: + assert m.isinstance_color(m.color[name]) + assert not m.isinstance_color(m.color) + for name, _ in SMALLENUM_MEMBERS: + assert not m.isinstance_color(m.smallenum[name]) + assert not m.isinstance_color(m.smallenum) + assert not m.isinstance_color(None) + + +def test_pass_color_success(): + for name, value in COLOR_MEMBERS: + assert m.pass_color(m.color[name]) == value + + +def test_pass_color_fail(): + with pytest.raises(TypeError) as excinfo: + m.pass_color(None) + assert "test_native_enum::color" in str(excinfo.value) + + +def test_return_color_success(): + for name, value in COLOR_MEMBERS: + 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_type_caster_enum_type_enabled_false(): + # This is really only a "does it compile" test. + assert m.pass_some_proto_enum(None) is None + assert m.return_some_proto_enum() is None + + +@pytest.mark.skipif(isinstance(m.obj_cast_color_ptr, str), reason=m.obj_cast_color_ptr) +def test_obj_cast_color_ptr(): + with pytest.raises(RuntimeError) as excinfo: + m.obj_cast_color_ptr(m.color.red) + assert str(excinfo.value) == "Unable to cast native enum type to reference" + + +def test_py_cast_color_handle(): + for name, value in COLOR_MEMBERS: + assert m.py_cast_color_handle(m.color[name]) == value + + +def test_native_enum_data_missing_finalize_error_message(): + msg = m.native_enum_data_missing_finalize_error_message("Fake") + assert msg == 'pybind11::native_enum<...>("Fake", ...): MISSING .finalize()' + + +@pytest.mark.parametrize( + "func", [m.native_enum_ctor_malformed_utf8, m.native_enum_value_malformed_utf8] +) +def test_native_enum_malformed_utf8(func): + if env.GRAALPY and func is m.native_enum_ctor_malformed_utf8: + pytest.skip("GraalPy does not raise UnicodeDecodeError") + malformed_utf8 = b"\x80" + with pytest.raises(UnicodeDecodeError): + func(malformed_utf8) + + +def test_native_enum_double_finalize(): + with pytest.raises(RuntimeError) as excinfo: + m.native_enum_double_finalize(m) + assert ( + str(excinfo.value) + == 'pybind11::native_enum<...>("fake_native_enum_double_finalize"): DOUBLE finalize' + ) + + +def test_native_enum_value_after_finalize(): + with pytest.raises(RuntimeError) as excinfo: + m.native_enum_value_after_finalize(m) + assert ( + str(excinfo.value) + == 'pybind11::native_enum<...>("fake_native_enum_value_after_finalize"): value after finalize' + ) + + +def test_double_registration_native_enum(): + with pytest.raises(RuntimeError) as excinfo: + m.double_registration_native_enum(m) + assert ( + str(excinfo.value) + == 'pybind11::native_enum<...>("fake_double_registration_native_enum") is already registered!' + ) + + +def test_native_enum_name_clash(): + m.fake_native_enum_name_clash = None + with pytest.raises(RuntimeError) as excinfo: + m.native_enum_name_clash(m) + assert ( + str(excinfo.value) + == 'pybind11::native_enum<...>("fake_native_enum_name_clash"):' + " an object with that name is already defined" + ) + + +def test_native_enum_value_name_clash(): + m.fake_native_enum_value_name_clash_x = None + with pytest.raises(RuntimeError) as excinfo: + m.native_enum_value_name_clash(m) + assert ( + str(excinfo.value) + == 'pybind11::native_enum<...>("fake_native_enum_value_name_clash")' + '.value("fake_native_enum_value_name_clash_x"):' + " an object with that name is already defined" + ) + + +def test_double_registration_enum_before_native_enum(): + with pytest.raises(RuntimeError) as excinfo: + m.double_registration_enum_before_native_enum(m) + assert ( + str(excinfo.value) + == 'pybind11::native_enum<...>("fake_enum_first") is already registered' + " as a `pybind11::enum_` or `pybind11::class_`!" + ) + + +def test_double_registration_native_enum_before_enum(): + with pytest.raises(RuntimeError) as excinfo: + m.double_registration_native_enum_before_enum(m) + assert ( + str(excinfo.value) + == 'pybind11::enum_ "name_must_be_different_to_reach_desired_code_path"' + " is already registered as a pybind11::native_enum!" + ) + + +def test_native_enum_missing_finalize_failure(): + if not isinstance(m.native_enum_missing_finalize_failure, str): + m.native_enum_missing_finalize_failure() + pytest.fail("Process termination expected.")