7 When including the additional header file :file:`pybind11/stl.h`, conversions
8 between ``std::vector<>``/``std::list<>``/``std::array<>``,
9 ``std::set<>``/``std::unordered_set<>``, and
10 ``std::map<>``/``std::unordered_map<>`` and the Python ``list``, ``set`` and
11 ``dict`` data structures are automatically enabled. The types ``std::pair<>``
12 and ``std::tuple<>`` are already supported out of the box with just the core
13 :file:`pybind11/pybind11.h` header.
15 The major downside of these implicit conversions is that containers must be
16 converted (i.e. copied) on every Python->C++ and C++->Python transition, which
17 can have implications on the program semantics and performance. Please read the
18 next sections for more details and alternative approaches that avoid this.
22 Arbitrary nesting of any of these types is possible.
26 The file :file:`tests/test_stl.cpp` contains a complete
27 example that demonstrates how to pass STL data types in more detail.
29 .. _cpp17_container_casters:
31 C++17 library containers
32 ========================
34 The :file:`pybind11/stl.h` header also includes support for ``std::optional<>``
35 and ``std::variant<>``. These require a C++17 compiler and standard library.
36 In C++14 mode, ``std::experimental::optional<>`` is supported if available.
38 Various versions of these containers also exist for C++11 (e.g. in Boost).
39 pybind11 provides an easy way to specialize the ``type_caster`` for such
44 // `boost::optional` as an example -- can be any `std::optional`-like container
45 namespace pybind11 { namespace detail {
47 struct type_caster<boost::optional<T>> : optional_caster<boost::optional<T>> {};
50 The above should be placed in a header file and included in all translation units
51 where automatic conversion is needed. Similarly, a specialization can be provided
52 for custom variant types:
56 // `boost::variant` as an example -- can be any `std::variant`-like container
57 namespace pybind11 { namespace detail {
58 template <typename... Ts>
59 struct type_caster<boost::variant<Ts...>> : variant_caster<boost::variant<Ts...>> {};
61 // Specifies the function used to visit the variant -- `apply_visitor` instead of `visit`
63 struct visit_helper<boost::variant> {
64 template <typename... Args>
65 static auto call(Args &&...args) -> decltype(boost::apply_visitor(args...)) {
66 return boost::apply_visitor(args...);
69 }} // namespace pybind11::detail
71 The ``visit_helper`` specialization is not required if your ``name::variant`` provides
72 a ``name::visit()`` function. For any other function name, the specialization must be
73 included to tell pybind11 how to visit the variant.
77 pybind11 only supports the modern implementation of ``boost::variant``
78 which makes use of variadic templates. This requires Boost 1.56 or newer.
79 Additionally, on Windows, MSVC 2017 is required because ``boost::variant``
80 falls back to the old non-variadic implementation on MSVC 2015.
87 pybind11 heavily relies on a template matching mechanism to convert parameters
88 and return values that are constructed from STL data types such as vectors,
89 linked lists, hash tables, etc. This even works in a recursive manner, for
90 instance to deal with lists of hash maps of pairs of elementary and custom
93 However, a fundamental limitation of this approach is that internal conversions
94 between Python and C++ types involve a copy operation that prevents
95 pass-by-reference semantics. What does this mean?
97 Suppose we bind the following function
101 void append_1(std::vector<int> &v) {
105 and call it from Python, the following happens:
107 .. code-block:: pycon
114 As you can see, when passing STL data structures by reference, modifications
115 are not propagated back the Python side. A similar situation arises when
116 exposing STL data structures using the ``def_readwrite`` or ``def_readonly``
121 /* ... definition ... */
124 std::vector<int> contents;
127 /* ... binding code ... */
129 py::class_<MyClass>(m, "MyClass")
131 .def_readwrite("contents", &MyClass::contents);
133 In this case, properties can be read and written in their entirety. However, an
134 ``append`` operation involving such a list type has no effect:
136 .. code-block:: pycon
139 >>> m.contents = [5, 6]
140 >>> print(m.contents)
142 >>> m.contents.append(7)
143 >>> print(m.contents)
146 Finally, the involved copy operations can be costly when dealing with very
147 large lists. To deal with all of the above situations, pybind11 provides a
148 macro named ``PYBIND11_MAKE_OPAQUE(T)`` that disables the template-based
149 conversion machinery of types, thus rendering them *opaque*. The contents of
150 opaque objects are never inspected or extracted, hence they *can* be passed by
151 reference. For instance, to turn ``std::vector<int>`` into an opaque type, add
156 PYBIND11_MAKE_OPAQUE(std::vector<int>);
158 before any binding code (e.g. invocations to ``class_::def()``, etc.). This
159 macro must be specified at the top level (and outside of any namespaces), since
160 it instantiates a partial template overload. If your binding code consists of
161 multiple compilation units, it must be present in every file (typically via a
162 common header) preceding any usage of ``std::vector<int>``. Opaque types must
163 also have a corresponding ``class_`` declaration to associate them with a name
164 in Python, and to define a set of available operations, e.g.:
168 py::class_<std::vector<int>>(m, "IntVector")
170 .def("clear", &std::vector<int>::clear)
171 .def("pop_back", &std::vector<int>::pop_back)
172 .def("__len__", [](const std::vector<int> &v) { return v.size(); })
173 .def("__iter__", [](std::vector<int> &v) {
174 return py::make_iterator(v.begin(), v.end());
175 }, py::keep_alive<0, 1>()) /* Keep vector alive while iterator is used */
178 Please take a look at the :ref:`macro_notes` before using the
179 ``PYBIND11_MAKE_OPAQUE`` macro.
183 The file :file:`tests/test_opaque_types.cpp` contains a complete
184 example that demonstrates how to create and expose opaque types using
185 pybind11 in more detail.
189 Binding STL containers
190 ======================
192 The ability to expose STL containers as native Python objects is a fairly
193 common request, hence pybind11 also provides an optional header file named
194 :file:`pybind11/stl_bind.h` that does exactly this. The mapped containers try
195 to match the behavior of their native Python counterparts as much as possible.
197 The following example showcases usage of :file:`pybind11/stl_bind.h`:
202 #include <pybind11/stl_bind.h>
204 PYBIND11_MAKE_OPAQUE(std::vector<int>);
205 PYBIND11_MAKE_OPAQUE(std::map<std::string, double>);
209 // later in binding code:
210 py::bind_vector<std::vector<int>>(m, "VectorInt");
211 py::bind_map<std::map<std::string, double>>(m, "MapStringDouble");
213 When binding STL containers pybind11 considers the types of the container's
214 elements to decide whether the container should be confined to the local module
215 (via the :ref:`module_local` feature). If the container element types are
216 anything other than already-bound custom types bound without
217 ``py::module_local()`` the container binding will have ``py::module_local()``
218 applied. This includes converting types such as numeric types, strings, Eigen
219 types; and types that have not yet been bound at the time of the stl container
220 binding. This module-local binding is designed to avoid potential conflicts
221 between module bindings (for example, from two separate modules each attempting
222 to bind ``std::vector<int>`` as a python type).
224 It is possible to override this behavior to force a definition to be either
225 module-local or global. To do so, you can pass the attributes
226 ``py::module_local()`` (to make the binding module-local) or
227 ``py::module_local(false)`` (to make the binding global) into the
228 ``py::bind_vector`` or ``py::bind_map`` arguments:
232 py::bind_vector<std::vector<int>>(m, "VectorInt", py::module_local(false));
234 Note, however, that such a global binding would make it impossible to load this
235 module at the same time as any other pybind module that also attempts to bind
236 the same container type (``std::vector<int>`` in the above example).
238 See :ref:`module_local` for more details on module-local bindings.
242 The file :file:`tests/test_stl_binders.cpp` shows how to use the
243 convenience STL container wrappers.