Skip to content

Commit 350b435

Browse files
committed
[skip ci] Explain type_caster_enum_type_enabled, copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled, move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled in Upgrade guide.
1 parent c06cad0 commit 350b435

File tree

2 files changed

+58
-3
lines changed

2 files changed

+58
-3
lines changed

docs/classes.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -580,7 +580,7 @@ As of Python 3.13, the compatible `types in the stdlib enum module
580580
template <typename FancyEnum>
581581
struct type_caster_enum_type_enabled<
582582
FancyEnum,
583-
std::enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};
583+
enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};
584584
}
585585
#endif
586586

docs/upgrade.rst

Lines changed: 57 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,64 @@ Potential stumbling blocks when migrating to v3.0
9191

9292
The following issues are very unlikely to arise, and easy to work around:
9393

94-
* TODO holder caster traits specializations may be needed
94+
* In rare cases, a C++ enum may be bound to Python via a
95+
:ref:`custom type caster <custom_type_caster>`. In such cases, a
96+
template specialization like this may be required:
97+
98+
.. code-block:: cpp
99+
100+
#if defined(PYBIND11_HAS_NATIVE_ENUM)
101+
namespace pybind11::detail {
102+
template <typename FancyEnum>
103+
struct type_caster_enum_type_enabled<
104+
FancyEnum,
105+
enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};
106+
}
107+
#endif
108+
109+
This specialization is needed only if the custom type caster is templated.
110+
111+
The ``PYBIND11_HAS_NATIVE_ENUM`` guard is needed only
112+
if backward compatibility with pybind11v2 is required.
113+
114+
* Similarly, template specializations like the following may be required
115+
if there are custom
116+
117+
* ``pybind11::detail::copyable_holder_caster`` or
118+
119+
* ``pybind11::detail::move_only_holder_caster``
120+
121+
implementations that are used for ``std::shared_ptr`` or ``std::unique_ptr``
122+
conversions:
123+
124+
.. code-block:: cpp
125+
126+
#if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT)
127+
namespace pybind11::detail {
128+
template <typename ExampleType>
129+
struct copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled<
130+
ExampleType,
131+
enable_if_t<is_example_type<ExampleType>::value>> : std::false_type {};
132+
}
133+
#endif
134+
135+
.. code-block:: cpp
136+
137+
#if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT)
138+
namespace pybind11::detail {
139+
template <typename ExampleType>
140+
struct move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled<
141+
ExampleType,
142+
enable_if_t<is_example_type<ExampleType>::value>> : std::false_type {};
143+
}
144+
#endif
145+
146+
The ``PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT`` guard is needed only
147+
if backward compatibility with pybind11v2 is required.
148+
149+
(Note that ``copyable_holder_caster`` and ``move_only_holder_caster`` are not
150+
documented, although they existed since 2017.)
95151

96-
* TODO enum caster traits specializations may be needed
97152

98153
.. _upgrade-guide-2.12:
99154

0 commit comments

Comments
 (0)