Adding pybind11 v2.2.4 to repo
[tidl/tidl-api.git] / tidl_api / pybind11 / include / pybind11 / cast.h
1 /*
2     pybind11/cast.h: Partial template specializations to cast between
3     C++ and Python types
5     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
7     All rights reserved. Use of this source code is governed by a
8     BSD-style license that can be found in the LICENSE file.
9 */
11 #pragma once
13 #include "pytypes.h"
14 #include "detail/typeid.h"
15 #include "detail/descr.h"
16 #include "detail/internals.h"
17 #include <array>
18 #include <limits>
19 #include <tuple>
21 #if defined(PYBIND11_CPP17)
22 #  if defined(__has_include)
23 #    if __has_include(<string_view>)
24 #      define PYBIND11_HAS_STRING_VIEW
25 #    endif
26 #  elif defined(_MSC_VER)
27 #    define PYBIND11_HAS_STRING_VIEW
28 #  endif
29 #endif
30 #ifdef PYBIND11_HAS_STRING_VIEW
31 #include <string_view>
32 #endif
34 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
35 NAMESPACE_BEGIN(detail)
37 /// A life support system for temporary objects created by `type_caster::load()`.
38 /// Adding a patient will keep it alive up until the enclosing function returns.
39 class loader_life_support {
40 public:
41     /// A new patient frame is created when a function is entered
42     loader_life_support() {
43         get_internals().loader_patient_stack.push_back(nullptr);
44     }
46     /// ... and destroyed after it returns
47     ~loader_life_support() {
48         auto &stack = get_internals().loader_patient_stack;
49         if (stack.empty())
50             pybind11_fail("loader_life_support: internal error");
52         auto ptr = stack.back();
53         stack.pop_back();
54         Py_CLEAR(ptr);
56         // A heuristic to reduce the stack's capacity (e.g. after long recursive calls)
57         if (stack.capacity() > 16 && stack.size() != 0 && stack.capacity() / stack.size() > 2)
58             stack.shrink_to_fit();
59     }
61     /// This can only be used inside a pybind11-bound function, either by `argument_loader`
62     /// at argument preparation time or by `py::cast()` at execution time.
63     PYBIND11_NOINLINE static void add_patient(handle h) {
64         auto &stack = get_internals().loader_patient_stack;
65         if (stack.empty())
66             throw cast_error("When called outside a bound function, py::cast() cannot "
67                              "do Python -> C++ conversions which require the creation "
68                              "of temporary values");
70         auto &list_ptr = stack.back();
71         if (list_ptr == nullptr) {
72             list_ptr = PyList_New(1);
73             if (!list_ptr)
74                 pybind11_fail("loader_life_support: error allocating list");
75             PyList_SET_ITEM(list_ptr, 0, h.inc_ref().ptr());
76         } else {
77             auto result = PyList_Append(list_ptr, h.ptr());
78             if (result == -1)
79                 pybind11_fail("loader_life_support: error adding patient");
80         }
81     }
82 };
84 // Gets the cache entry for the given type, creating it if necessary.  The return value is the pair
85 // returned by emplace, i.e. an iterator for the entry and a bool set to `true` if the entry was
86 // just created.
87 inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type);
89 // Populates a just-created cache entry.
90 PYBIND11_NOINLINE inline void all_type_info_populate(PyTypeObject *t, std::vector<type_info *> &bases) {
91     std::vector<PyTypeObject *> check;
92     for (handle parent : reinterpret_borrow<tuple>(t->tp_bases))
93         check.push_back((PyTypeObject *) parent.ptr());
95     auto const &type_dict = get_internals().registered_types_py;
96     for (size_t i = 0; i < check.size(); i++) {
97         auto type = check[i];
98         // Ignore Python2 old-style class super type:
99         if (!PyType_Check((PyObject *) type)) continue;
101         // Check `type` in the current set of registered python types:
102         auto it = type_dict.find(type);
103         if (it != type_dict.end()) {
104             // We found a cache entry for it, so it's either pybind-registered or has pre-computed
105             // pybind bases, but we have to make sure we haven't already seen the type(s) before: we
106             // want to follow Python/virtual C++ rules that there should only be one instance of a
107             // common base.
108             for (auto *tinfo : it->second) {
109                 // NB: Could use a second set here, rather than doing a linear search, but since
110                 // having a large number of immediate pybind11-registered types seems fairly
111                 // unlikely, that probably isn't worthwhile.
112                 bool found = false;
113                 for (auto *known : bases) {
114                     if (known == tinfo) { found = true; break; }
115                 }
116                 if (!found) bases.push_back(tinfo);
117             }
118         }
119         else if (type->tp_bases) {
120             // It's some python type, so keep follow its bases classes to look for one or more
121             // registered types
122             if (i + 1 == check.size()) {
123                 // When we're at the end, we can pop off the current element to avoid growing
124                 // `check` when adding just one base (which is typical--i.e. when there is no
125                 // multiple inheritance)
126                 check.pop_back();
127                 i--;
128             }
129             for (handle parent : reinterpret_borrow<tuple>(type->tp_bases))
130                 check.push_back((PyTypeObject *) parent.ptr());
131         }
132     }
135 /**
136  * Extracts vector of type_info pointers of pybind-registered roots of the given Python type.  Will
137  * be just 1 pybind type for the Python type of a pybind-registered class, or for any Python-side
138  * derived class that uses single inheritance.  Will contain as many types as required for a Python
139  * class that uses multiple inheritance to inherit (directly or indirectly) from multiple
140  * pybind-registered classes.  Will be empty if neither the type nor any base classes are
141  * pybind-registered.
142  *
143  * The value is cached for the lifetime of the Python type.
144  */
145 inline const std::vector<detail::type_info *> &all_type_info(PyTypeObject *type) {
146     auto ins = all_type_info_get_cache(type);
147     if (ins.second)
148         // New cache entry: populate it
149         all_type_info_populate(type, ins.first->second);
151     return ins.first->second;
154 /**
155  * Gets a single pybind11 type info for a python type.  Returns nullptr if neither the type nor any
156  * ancestors are pybind11-registered.  Throws an exception if there are multiple bases--use
157  * `all_type_info` instead if you want to support multiple bases.
158  */
159 PYBIND11_NOINLINE inline detail::type_info* get_type_info(PyTypeObject *type) {
160     auto &bases = all_type_info(type);
161     if (bases.size() == 0)
162         return nullptr;
163     if (bases.size() > 1)
164         pybind11_fail("pybind11::detail::get_type_info: type has multiple pybind11-registered bases");
165     return bases.front();
168 inline detail::type_info *get_local_type_info(const std::type_index &tp) {
169     auto &locals = registered_local_types_cpp();
170     auto it = locals.find(tp);
171     if (it != locals.end())
172         return it->second;
173     return nullptr;
176 inline detail::type_info *get_global_type_info(const std::type_index &tp) {
177     auto &types = get_internals().registered_types_cpp;
178     auto it = types.find(tp);
179     if (it != types.end())
180         return it->second;
181     return nullptr;
184 /// Return the type info for a given C++ type; on lookup failure can either throw or return nullptr.
185 PYBIND11_NOINLINE inline detail::type_info *get_type_info(const std::type_index &tp,
186                                                           bool throw_if_missing = false) {
187     if (auto ltype = get_local_type_info(tp))
188         return ltype;
189     if (auto gtype = get_global_type_info(tp))
190         return gtype;
192     if (throw_if_missing) {
193         std::string tname = tp.name();
194         detail::clean_type_id(tname);
195         pybind11_fail("pybind11::detail::get_type_info: unable to find type info for \"" + tname + "\"");
196     }
197     return nullptr;
200 PYBIND11_NOINLINE inline handle get_type_handle(const std::type_info &tp, bool throw_if_missing) {
201     detail::type_info *type_info = get_type_info(tp, throw_if_missing);
202     return handle(type_info ? ((PyObject *) type_info->type) : nullptr);
205 struct value_and_holder {
206     instance *inst;
207     size_t index;
208     const detail::type_info *type;
209     void **vh;
211     // Main constructor for a found value/holder:
212     value_and_holder(instance *i, const detail::type_info *type, size_t vpos, size_t index) :
213         inst{i}, index{index}, type{type},
214         vh{inst->simple_layout ? inst->simple_value_holder : &inst->nonsimple.values_and_holders[vpos]}
215     {}
217     // Default constructor (used to signal a value-and-holder not found by get_value_and_holder())
218     value_and_holder() : inst{nullptr} {}
220     // Used for past-the-end iterator
221     value_and_holder(size_t index) : index{index} {}
223     template <typename V = void> V *&value_ptr() const {
224         return reinterpret_cast<V *&>(vh[0]);
225     }
226     // True if this `value_and_holder` has a non-null value pointer
227     explicit operator bool() const { return value_ptr(); }
229     template <typename H> H &holder() const {
230         return reinterpret_cast<H &>(vh[1]);
231     }
232     bool holder_constructed() const {
233         return inst->simple_layout
234             ? inst->simple_holder_constructed
235             : inst->nonsimple.status[index] & instance::status_holder_constructed;
236     }
237     void set_holder_constructed(bool v = true) {
238         if (inst->simple_layout)
239             inst->simple_holder_constructed = v;
240         else if (v)
241             inst->nonsimple.status[index] |= instance::status_holder_constructed;
242         else
243             inst->nonsimple.status[index] &= (uint8_t) ~instance::status_holder_constructed;
244     }
245     bool instance_registered() const {
246         return inst->simple_layout
247             ? inst->simple_instance_registered
248             : inst->nonsimple.status[index] & instance::status_instance_registered;
249     }
250     void set_instance_registered(bool v = true) {
251         if (inst->simple_layout)
252             inst->simple_instance_registered = v;
253         else if (v)
254             inst->nonsimple.status[index] |= instance::status_instance_registered;
255         else
256             inst->nonsimple.status[index] &= (uint8_t) ~instance::status_instance_registered;
257     }
258 };
260 // Container for accessing and iterating over an instance's values/holders
261 struct values_and_holders {
262 private:
263     instance *inst;
264     using type_vec = std::vector<detail::type_info *>;
265     const type_vec &tinfo;
267 public:
268     values_and_holders(instance *inst) : inst{inst}, tinfo(all_type_info(Py_TYPE(inst))) {}
270     struct iterator {
271     private:
272         instance *inst;
273         const type_vec *types;
274         value_and_holder curr;
275         friend struct values_and_holders;
276         iterator(instance *inst, const type_vec *tinfo)
277             : inst{inst}, types{tinfo},
278             curr(inst /* instance */,
279                  types->empty() ? nullptr : (*types)[0] /* type info */,
280                  0, /* vpos: (non-simple types only): the first vptr comes first */
281                  0 /* index */)
282         {}
283         // Past-the-end iterator:
284         iterator(size_t end) : curr(end) {}
285     public:
286         bool operator==(const iterator &other) { return curr.index == other.curr.index; }
287         bool operator!=(const iterator &other) { return curr.index != other.curr.index; }
288         iterator &operator++() {
289             if (!inst->simple_layout)
290                 curr.vh += 1 + (*types)[curr.index]->holder_size_in_ptrs;
291             ++curr.index;
292             curr.type = curr.index < types->size() ? (*types)[curr.index] : nullptr;
293             return *this;
294         }
295         value_and_holder &operator*() { return curr; }
296         value_and_holder *operator->() { return &curr; }
297     };
299     iterator begin() { return iterator(inst, &tinfo); }
300     iterator end() { return iterator(tinfo.size()); }
302     iterator find(const type_info *find_type) {
303         auto it = begin(), endit = end();
304         while (it != endit && it->type != find_type) ++it;
305         return it;
306     }
308     size_t size() { return tinfo.size(); }
309 };
311 /**
312  * Extracts C++ value and holder pointer references from an instance (which may contain multiple
313  * values/holders for python-side multiple inheritance) that match the given type.  Throws an error
314  * if the given type (or ValueType, if omitted) is not a pybind11 base of the given instance.  If
315  * `find_type` is omitted (or explicitly specified as nullptr) the first value/holder are returned,
316  * regardless of type (and the resulting .type will be nullptr).
317  *
318  * The returned object should be short-lived: in particular, it must not outlive the called-upon
319  * instance.
320  */
321 PYBIND11_NOINLINE inline value_and_holder instance::get_value_and_holder(const type_info *find_type /*= nullptr default in common.h*/, bool throw_if_missing /*= true in common.h*/) {
322     // Optimize common case:
323     if (!find_type || Py_TYPE(this) == find_type->type)
324         return value_and_holder(this, find_type, 0, 0);
326     detail::values_and_holders vhs(this);
327     auto it = vhs.find(find_type);
328     if (it != vhs.end())
329         return *it;
331     if (!throw_if_missing)
332         return value_and_holder();
334 #if defined(NDEBUG)
335     pybind11_fail("pybind11::detail::instance::get_value_and_holder: "
336             "type is not a pybind11 base of the given instance "
337             "(compile in debug mode for type details)");
338 #else
339     pybind11_fail("pybind11::detail::instance::get_value_and_holder: `" +
340             std::string(find_type->type->tp_name) + "' is not a pybind11 base of the given `" +
341             std::string(Py_TYPE(this)->tp_name) + "' instance");
342 #endif
345 PYBIND11_NOINLINE inline void instance::allocate_layout() {
346     auto &tinfo = all_type_info(Py_TYPE(this));
348     const size_t n_types = tinfo.size();
350     if (n_types == 0)
351         pybind11_fail("instance allocation failed: new instance has no pybind11-registered base types");
353     simple_layout =
354         n_types == 1 && tinfo.front()->holder_size_in_ptrs <= instance_simple_holder_in_ptrs();
356     // Simple path: no python-side multiple inheritance, and a small-enough holder
357     if (simple_layout) {
358         simple_value_holder[0] = nullptr;
359         simple_holder_constructed = false;
360         simple_instance_registered = false;
361     }
362     else { // multiple base types or a too-large holder
363         // Allocate space to hold: [v1*][h1][v2*][h2]...[bb...] where [vN*] is a value pointer,
364         // [hN] is the (uninitialized) holder instance for value N, and [bb...] is a set of bool
365         // values that tracks whether each associated holder has been initialized.  Each [block] is
366         // padded, if necessary, to an integer multiple of sizeof(void *).
367         size_t space = 0;
368         for (auto t : tinfo) {
369             space += 1; // value pointer
370             space += t->holder_size_in_ptrs; // holder instance
371         }
372         size_t flags_at = space;
373         space += size_in_ptrs(n_types); // status bytes (holder_constructed and instance_registered)
375         // Allocate space for flags, values, and holders, and initialize it to 0 (flags and values,
376         // in particular, need to be 0).  Use Python's memory allocation functions: in Python 3.6
377         // they default to using pymalloc, which is designed to be efficient for small allocations
378         // like the one we're doing here; in earlier versions (and for larger allocations) they are
379         // just wrappers around malloc.
380 #if PY_VERSION_HEX >= 0x03050000
381         nonsimple.values_and_holders = (void **) PyMem_Calloc(space, sizeof(void *));
382         if (!nonsimple.values_and_holders) throw std::bad_alloc();
383 #else
384         nonsimple.values_and_holders = (void **) PyMem_New(void *, space);
385         if (!nonsimple.values_and_holders) throw std::bad_alloc();
386         std::memset(nonsimple.values_and_holders, 0, space * sizeof(void *));
387 #endif
388         nonsimple.status = reinterpret_cast<uint8_t *>(&nonsimple.values_and_holders[flags_at]);
389     }
390     owned = true;
393 PYBIND11_NOINLINE inline void instance::deallocate_layout() {
394     if (!simple_layout)
395         PyMem_Free(nonsimple.values_and_holders);
398 PYBIND11_NOINLINE inline bool isinstance_generic(handle obj, const std::type_info &tp) {
399     handle type = detail::get_type_handle(tp, false);
400     if (!type)
401         return false;
402     return isinstance(obj, type);
405 PYBIND11_NOINLINE inline std::string error_string() {
406     if (!PyErr_Occurred()) {
407         PyErr_SetString(PyExc_RuntimeError, "Unknown internal error occurred");
408         return "Unknown internal error occurred";
409     }
411     error_scope scope; // Preserve error state
413     std::string errorString;
414     if (scope.type) {
415         errorString += handle(scope.type).attr("__name__").cast<std::string>();
416         errorString += ": ";
417     }
418     if (scope.value)
419         errorString += (std::string) str(scope.value);
421     PyErr_NormalizeException(&scope.type, &scope.value, &scope.trace);
423 #if PY_MAJOR_VERSION >= 3
424     if (scope.trace != nullptr)
425         PyException_SetTraceback(scope.value, scope.trace);
426 #endif
428 #if !defined(PYPY_VERSION)
429     if (scope.trace) {
430         PyTracebackObject *trace = (PyTracebackObject *) scope.trace;
432         /* Get the deepest trace possible */
433         while (trace->tb_next)
434             trace = trace->tb_next;
436         PyFrameObject *frame = trace->tb_frame;
437         errorString += "\n\nAt:\n";
438         while (frame) {
439             int lineno = PyFrame_GetLineNumber(frame);
440             errorString +=
441                 "  " + handle(frame->f_code->co_filename).cast<std::string>() +
442                 "(" + std::to_string(lineno) + "): " +
443                 handle(frame->f_code->co_name).cast<std::string>() + "\n";
444             frame = frame->f_back;
445         }
446     }
447 #endif
449     return errorString;
452 PYBIND11_NOINLINE inline handle get_object_handle(const void *ptr, const detail::type_info *type ) {
453     auto &instances = get_internals().registered_instances;
454     auto range = instances.equal_range(ptr);
455     for (auto it = range.first; it != range.second; ++it) {
456         for (auto vh : values_and_holders(it->second)) {
457             if (vh.type == type)
458                 return handle((PyObject *) it->second);
459         }
460     }
461     return handle();
464 inline PyThreadState *get_thread_state_unchecked() {
465 #if defined(PYPY_VERSION)
466     return PyThreadState_GET();
467 #elif PY_VERSION_HEX < 0x03000000
468     return _PyThreadState_Current;
469 #elif PY_VERSION_HEX < 0x03050000
470     return (PyThreadState*) _Py_atomic_load_relaxed(&_PyThreadState_Current);
471 #elif PY_VERSION_HEX < 0x03050200
472     return (PyThreadState*) _PyThreadState_Current.value;
473 #else
474     return _PyThreadState_UncheckedGet();
475 #endif
478 // Forward declarations
479 inline void keep_alive_impl(handle nurse, handle patient);
480 inline PyObject *make_new_instance(PyTypeObject *type);
482 class type_caster_generic {
483 public:
484     PYBIND11_NOINLINE type_caster_generic(const std::type_info &type_info)
485         : typeinfo(get_type_info(type_info)), cpptype(&type_info) { }
487     type_caster_generic(const type_info *typeinfo)
488         : typeinfo(typeinfo), cpptype(typeinfo ? typeinfo->cpptype : nullptr) { }
490     bool load(handle src, bool convert) {
491         return load_impl<type_caster_generic>(src, convert);
492     }
494     PYBIND11_NOINLINE static handle cast(const void *_src, return_value_policy policy, handle parent,
495                                          const detail::type_info *tinfo,
496                                          void *(*copy_constructor)(const void *),
497                                          void *(*move_constructor)(const void *),
498                                          const void *existing_holder = nullptr) {
499         if (!tinfo) // no type info: error will be set already
500             return handle();
502         void *src = const_cast<void *>(_src);
503         if (src == nullptr)
504             return none().release();
506         auto it_instances = get_internals().registered_instances.equal_range(src);
507         for (auto it_i = it_instances.first; it_i != it_instances.second; ++it_i) {
508             for (auto instance_type : detail::all_type_info(Py_TYPE(it_i->second))) {
509                 if (instance_type && same_type(*instance_type->cpptype, *tinfo->cpptype))
510                     return handle((PyObject *) it_i->second).inc_ref();
511             }
512         }
514         auto inst = reinterpret_steal<object>(make_new_instance(tinfo->type));
515         auto wrapper = reinterpret_cast<instance *>(inst.ptr());
516         wrapper->owned = false;
517         void *&valueptr = values_and_holders(wrapper).begin()->value_ptr();
519         switch (policy) {
520             case return_value_policy::automatic:
521             case return_value_policy::take_ownership:
522                 valueptr = src;
523                 wrapper->owned = true;
524                 break;
526             case return_value_policy::automatic_reference:
527             case return_value_policy::reference:
528                 valueptr = src;
529                 wrapper->owned = false;
530                 break;
532             case return_value_policy::copy:
533                 if (copy_constructor)
534                     valueptr = copy_constructor(src);
535                 else
536                     throw cast_error("return_value_policy = copy, but the "
537                                      "object is non-copyable!");
538                 wrapper->owned = true;
539                 break;
541             case return_value_policy::move:
542                 if (move_constructor)
543                     valueptr = move_constructor(src);
544                 else if (copy_constructor)
545                     valueptr = copy_constructor(src);
546                 else
547                     throw cast_error("return_value_policy = move, but the "
548                                      "object is neither movable nor copyable!");
549                 wrapper->owned = true;
550                 break;
552             case return_value_policy::reference_internal:
553                 valueptr = src;
554                 wrapper->owned = false;
555                 keep_alive_impl(inst, parent);
556                 break;
558             default:
559                 throw cast_error("unhandled return_value_policy: should not happen!");
560         }
562         tinfo->init_instance(wrapper, existing_holder);
564         return inst.release();
565     }
567     // Base methods for generic caster; there are overridden in copyable_holder_caster
568     void load_value(value_and_holder &&v_h) {
569         auto *&vptr = v_h.value_ptr();
570         // Lazy allocation for unallocated values:
571         if (vptr == nullptr) {
572             auto *type = v_h.type ? v_h.type : typeinfo;
573             vptr = type->operator_new(type->type_size);
574         }
575         value = vptr;
576     }
577     bool try_implicit_casts(handle src, bool convert) {
578         for (auto &cast : typeinfo->implicit_casts) {
579             type_caster_generic sub_caster(*cast.first);
580             if (sub_caster.load(src, convert)) {
581                 value = cast.second(sub_caster.value);
582                 return true;
583             }
584         }
585         return false;
586     }
587     bool try_direct_conversions(handle src) {
588         for (auto &converter : *typeinfo->direct_conversions) {
589             if (converter(src.ptr(), value))
590                 return true;
591         }
592         return false;
593     }
594     void check_holder_compat() {}
596     PYBIND11_NOINLINE static void *local_load(PyObject *src, const type_info *ti) {
597         auto caster = type_caster_generic(ti);
598         if (caster.load(src, false))
599             return caster.value;
600         return nullptr;
601     }
603     /// Try to load with foreign typeinfo, if available. Used when there is no
604     /// native typeinfo, or when the native one wasn't able to produce a value.
605     PYBIND11_NOINLINE bool try_load_foreign_module_local(handle src) {
606         constexpr auto *local_key = PYBIND11_MODULE_LOCAL_ID;
607         const auto pytype = src.get_type();
608         if (!hasattr(pytype, local_key))
609             return false;
611         type_info *foreign_typeinfo = reinterpret_borrow<capsule>(getattr(pytype, local_key));
612         // Only consider this foreign loader if actually foreign and is a loader of the correct cpp type
613         if (foreign_typeinfo->module_local_load == &local_load
614             || (cpptype && !same_type(*cpptype, *foreign_typeinfo->cpptype)))
615             return false;
617         if (auto result = foreign_typeinfo->module_local_load(src.ptr(), foreign_typeinfo)) {
618             value = result;
619             return true;
620         }
621         return false;
622     }
624     // Implementation of `load`; this takes the type of `this` so that it can dispatch the relevant
625     // bits of code between here and copyable_holder_caster where the two classes need different
626     // logic (without having to resort to virtual inheritance).
627     template <typename ThisT>
628     PYBIND11_NOINLINE bool load_impl(handle src, bool convert) {
629         if (!src) return false;
630         if (!typeinfo) return try_load_foreign_module_local(src);
631         if (src.is_none()) {
632             // Defer accepting None to other overloads (if we aren't in convert mode):
633             if (!convert) return false;
634             value = nullptr;
635             return true;
636         }
638         auto &this_ = static_cast<ThisT &>(*this);
639         this_.check_holder_compat();
641         PyTypeObject *srctype = Py_TYPE(src.ptr());
643         // Case 1: If src is an exact type match for the target type then we can reinterpret_cast
644         // the instance's value pointer to the target type:
645         if (srctype == typeinfo->type) {
646             this_.load_value(reinterpret_cast<instance *>(src.ptr())->get_value_and_holder());
647             return true;
648         }
649         // Case 2: We have a derived class
650         else if (PyType_IsSubtype(srctype, typeinfo->type)) {
651             auto &bases = all_type_info(srctype);
652             bool no_cpp_mi = typeinfo->simple_type;
654             // Case 2a: the python type is a Python-inherited derived class that inherits from just
655             // one simple (no MI) pybind11 class, or is an exact match, so the C++ instance is of
656             // the right type and we can use reinterpret_cast.
657             // (This is essentially the same as case 2b, but because not using multiple inheritance
658             // is extremely common, we handle it specially to avoid the loop iterator and type
659             // pointer lookup overhead)
660             if (bases.size() == 1 && (no_cpp_mi || bases.front()->type == typeinfo->type)) {
661                 this_.load_value(reinterpret_cast<instance *>(src.ptr())->get_value_and_holder());
662                 return true;
663             }
664             // Case 2b: the python type inherits from multiple C++ bases.  Check the bases to see if
665             // we can find an exact match (or, for a simple C++ type, an inherited match); if so, we
666             // can safely reinterpret_cast to the relevant pointer.
667             else if (bases.size() > 1) {
668                 for (auto base : bases) {
669                     if (no_cpp_mi ? PyType_IsSubtype(base->type, typeinfo->type) : base->type == typeinfo->type) {
670                         this_.load_value(reinterpret_cast<instance *>(src.ptr())->get_value_and_holder(base));
671                         return true;
672                     }
673                 }
674             }
676             // Case 2c: C++ multiple inheritance is involved and we couldn't find an exact type match
677             // in the registered bases, above, so try implicit casting (needed for proper C++ casting
678             // when MI is involved).
679             if (this_.try_implicit_casts(src, convert))
680                 return true;
681         }
683         // Perform an implicit conversion
684         if (convert) {
685             for (auto &converter : typeinfo->implicit_conversions) {
686                 auto temp = reinterpret_steal<object>(converter(src.ptr(), typeinfo->type));
687                 if (load_impl<ThisT>(temp, false)) {
688                     loader_life_support::add_patient(temp);
689                     return true;
690                 }
691             }
692             if (this_.try_direct_conversions(src))
693                 return true;
694         }
696         // Failed to match local typeinfo. Try again with global.
697         if (typeinfo->module_local) {
698             if (auto gtype = get_global_type_info(*typeinfo->cpptype)) {
699                 typeinfo = gtype;
700                 return load(src, false);
701             }
702         }
704         // Global typeinfo has precedence over foreign module_local
705         return try_load_foreign_module_local(src);
706     }
709     // Called to do type lookup and wrap the pointer and type in a pair when a dynamic_cast
710     // isn't needed or can't be used.  If the type is unknown, sets the error and returns a pair
711     // with .second = nullptr.  (p.first = nullptr is not an error: it becomes None).
712     PYBIND11_NOINLINE static std::pair<const void *, const type_info *> src_and_type(
713             const void *src, const std::type_info &cast_type, const std::type_info *rtti_type = nullptr) {
714         if (auto *tpi = get_type_info(cast_type))
715             return {src, const_cast<const type_info *>(tpi)};
717         // Not found, set error:
718         std::string tname = rtti_type ? rtti_type->name() : cast_type.name();
719         detail::clean_type_id(tname);
720         std::string msg = "Unregistered type : " + tname;
721         PyErr_SetString(PyExc_TypeError, msg.c_str());
722         return {nullptr, nullptr};
723     }
725     const type_info *typeinfo = nullptr;
726     const std::type_info *cpptype = nullptr;
727     void *value = nullptr;
728 };
730 /**
731  * Determine suitable casting operator for pointer-or-lvalue-casting type casters.  The type caster
732  * needs to provide `operator T*()` and `operator T&()` operators.
733  *
734  * If the type supports moving the value away via an `operator T&&() &&` method, it should use
735  * `movable_cast_op_type` instead.
736  */
737 template <typename T>
738 using cast_op_type =
739     conditional_t<std::is_pointer<remove_reference_t<T>>::value,
740         typename std::add_pointer<intrinsic_t<T>>::type,
741         typename std::add_lvalue_reference<intrinsic_t<T>>::type>;
743 /**
744  * Determine suitable casting operator for a type caster with a movable value.  Such a type caster
745  * needs to provide `operator T*()`, `operator T&()`, and `operator T&&() &&`.  The latter will be
746  * called in appropriate contexts where the value can be moved rather than copied.
747  *
748  * These operator are automatically provided when using the PYBIND11_TYPE_CASTER macro.
749  */
750 template <typename T>
751 using movable_cast_op_type =
752     conditional_t<std::is_pointer<typename std::remove_reference<T>::type>::value,
753         typename std::add_pointer<intrinsic_t<T>>::type,
754     conditional_t<std::is_rvalue_reference<T>::value,
755         typename std::add_rvalue_reference<intrinsic_t<T>>::type,
756         typename std::add_lvalue_reference<intrinsic_t<T>>::type>>;
758 // std::is_copy_constructible isn't quite enough: it lets std::vector<T> (and similar) through when
759 // T is non-copyable, but code containing such a copy constructor fails to actually compile.
760 template <typename T, typename SFINAE = void> struct is_copy_constructible : std::is_copy_constructible<T> {};
762 // Specialization for types that appear to be copy constructible but also look like stl containers
763 // (we specifically check for: has `value_type` and `reference` with `reference = value_type&`): if
764 // so, copy constructability depends on whether the value_type is copy constructible.
765 template <typename Container> struct is_copy_constructible<Container, enable_if_t<all_of<
766         std::is_copy_constructible<Container>,
767         std::is_same<typename Container::value_type &, typename Container::reference>
768     >::value>> : is_copy_constructible<typename Container::value_type> {};
770 #if !defined(PYBIND11_CPP17)
771 // Likewise for std::pair before C++17 (which mandates that the copy constructor not exist when the
772 // two types aren't themselves copy constructible).
773 template <typename T1, typename T2> struct is_copy_constructible<std::pair<T1, T2>>
774     : all_of<is_copy_constructible<T1>, is_copy_constructible<T2>> {};
775 #endif
777 /// Generic type caster for objects stored on the heap
778 template <typename type> class type_caster_base : public type_caster_generic {
779     using itype = intrinsic_t<type>;
780 public:
781     static PYBIND11_DESCR name() { return type_descr(_<type>()); }
783     type_caster_base() : type_caster_base(typeid(type)) { }
784     explicit type_caster_base(const std::type_info &info) : type_caster_generic(info) { }
786     static handle cast(const itype &src, return_value_policy policy, handle parent) {
787         if (policy == return_value_policy::automatic || policy == return_value_policy::automatic_reference)
788             policy = return_value_policy::copy;
789         return cast(&src, policy, parent);
790     }
792     static handle cast(itype &&src, return_value_policy, handle parent) {
793         return cast(&src, return_value_policy::move, parent);
794     }
796     // Returns a (pointer, type_info) pair taking care of necessary RTTI type lookup for a
797     // polymorphic type.  If the instance isn't derived, returns the non-RTTI base version.
798     template <typename T = itype, enable_if_t<std::is_polymorphic<T>::value, int> = 0>
799     static std::pair<const void *, const type_info *> src_and_type(const itype *src) {
800         const void *vsrc = src;
801         auto &cast_type = typeid(itype);
802         const std::type_info *instance_type = nullptr;
803         if (vsrc) {
804             instance_type = &typeid(*src);
805             if (!same_type(cast_type, *instance_type)) {
806                 // This is a base pointer to a derived type; if it is a pybind11-registered type, we
807                 // can get the correct derived pointer (which may be != base pointer) by a
808                 // dynamic_cast to most derived type:
809                 if (auto *tpi = get_type_info(*instance_type))
810                     return {dynamic_cast<const void *>(src), const_cast<const type_info *>(tpi)};
811             }
812         }
813         // Otherwise we have either a nullptr, an `itype` pointer, or an unknown derived pointer, so
814         // don't do a cast
815         return type_caster_generic::src_and_type(vsrc, cast_type, instance_type);
816     }
818     // Non-polymorphic type, so no dynamic casting; just call the generic version directly
819     template <typename T = itype, enable_if_t<!std::is_polymorphic<T>::value, int> = 0>
820     static std::pair<const void *, const type_info *> src_and_type(const itype *src) {
821         return type_caster_generic::src_and_type(src, typeid(itype));
822     }
824     static handle cast(const itype *src, return_value_policy policy, handle parent) {
825         auto st = src_and_type(src);
826         return type_caster_generic::cast(
827             st.first, policy, parent, st.second,
828             make_copy_constructor(src), make_move_constructor(src));
829     }
831     static handle cast_holder(const itype *src, const void *holder) {
832         auto st = src_and_type(src);
833         return type_caster_generic::cast(
834             st.first, return_value_policy::take_ownership, {}, st.second,
835             nullptr, nullptr, holder);
836     }
838     template <typename T> using cast_op_type = cast_op_type<T>;
840     operator itype*() { return (type *) value; }
841     operator itype&() { if (!value) throw reference_cast_error(); return *((itype *) value); }
843 protected:
844     using Constructor = void *(*)(const void *);
846     /* Only enabled when the types are {copy,move}-constructible *and* when the type
847        does not have a private operator new implementation. */
848     template <typename T, typename = enable_if_t<is_copy_constructible<T>::value>>
849     static auto make_copy_constructor(const T *x) -> decltype(new T(*x), Constructor{}) {
850         return [](const void *arg) -> void * {
851             return new T(*reinterpret_cast<const T *>(arg));
852         };
853     }
855     template <typename T, typename = enable_if_t<std::is_move_constructible<T>::value>>
856     static auto make_move_constructor(const T *x) -> decltype(new T(std::move(*const_cast<T *>(x))), Constructor{}) {
857         return [](const void *arg) -> void * {
858             return new T(std::move(*const_cast<T *>(reinterpret_cast<const T *>(arg))));
859         };
860     }
862     static Constructor make_copy_constructor(...) { return nullptr; }
863     static Constructor make_move_constructor(...) { return nullptr; }
864 };
866 template <typename type, typename SFINAE = void> class type_caster : public type_caster_base<type> { };
867 template <typename type> using make_caster = type_caster<intrinsic_t<type>>;
869 // Shortcut for calling a caster's `cast_op_type` cast operator for casting a type_caster to a T
870 template <typename T> typename make_caster<T>::template cast_op_type<T> cast_op(make_caster<T> &caster) {
871     return caster.operator typename make_caster<T>::template cast_op_type<T>();
873 template <typename T> typename make_caster<T>::template cast_op_type<typename std::add_rvalue_reference<T>::type>
874 cast_op(make_caster<T> &&caster) {
875     return std::move(caster).operator
876         typename make_caster<T>::template cast_op_type<typename std::add_rvalue_reference<T>::type>();
879 template <typename type> class type_caster<std::reference_wrapper<type>> {
880 private:
881     using caster_t = make_caster<type>;
882     caster_t subcaster;
883     using subcaster_cast_op_type = typename caster_t::template cast_op_type<type>;
884     static_assert(std::is_same<typename std::remove_const<type>::type &, subcaster_cast_op_type>::value,
885             "std::reference_wrapper<T> caster requires T to have a caster with an `T &` operator");
886 public:
887     bool load(handle src, bool convert) { return subcaster.load(src, convert); }
888     static PYBIND11_DESCR name() { return caster_t::name(); }
889     static handle cast(const std::reference_wrapper<type> &src, return_value_policy policy, handle parent) {
890         // It is definitely wrong to take ownership of this pointer, so mask that rvp
891         if (policy == return_value_policy::take_ownership || policy == return_value_policy::automatic)
892             policy = return_value_policy::automatic_reference;
893         return caster_t::cast(&src.get(), policy, parent);
894     }
895     template <typename T> using cast_op_type = std::reference_wrapper<type>;
896     operator std::reference_wrapper<type>() { return subcaster.operator subcaster_cast_op_type&(); }
897 };
899 #define PYBIND11_TYPE_CASTER(type, py_name) \
900     protected: \
901         type value; \
902     public: \
903         static PYBIND11_DESCR name() { return type_descr(py_name); } \
904         template <typename T_, enable_if_t<std::is_same<type, remove_cv_t<T_>>::value, int> = 0> \
905         static handle cast(T_ *src, return_value_policy policy, handle parent) { \
906             if (!src) return none().release(); \
907             if (policy == return_value_policy::take_ownership) { \
908                 auto h = cast(std::move(*src), policy, parent); delete src; return h; \
909             } else { \
910                 return cast(*src, policy, parent); \
911             } \
912         } \
913         operator type*() { return &value; } \
914         operator type&() { return value; } \
915         operator type&&() && { return std::move(value); } \
916         template <typename T_> using cast_op_type = pybind11::detail::movable_cast_op_type<T_>
919 template <typename CharT> using is_std_char_type = any_of<
920     std::is_same<CharT, char>, /* std::string */
921     std::is_same<CharT, char16_t>, /* std::u16string */
922     std::is_same<CharT, char32_t>, /* std::u32string */
923     std::is_same<CharT, wchar_t> /* std::wstring */
924 >;
926 template <typename T>
927 struct type_caster<T, enable_if_t<std::is_arithmetic<T>::value && !is_std_char_type<T>::value>> {
928     using _py_type_0 = conditional_t<sizeof(T) <= sizeof(long), long, long long>;
929     using _py_type_1 = conditional_t<std::is_signed<T>::value, _py_type_0, typename std::make_unsigned<_py_type_0>::type>;
930     using py_type = conditional_t<std::is_floating_point<T>::value, double, _py_type_1>;
931 public:
933     bool load(handle src, bool convert) {
934         py_type py_value;
936         if (!src)
937             return false;
939         if (std::is_floating_point<T>::value) {
940             if (convert || PyFloat_Check(src.ptr()))
941                 py_value = (py_type) PyFloat_AsDouble(src.ptr());
942             else
943                 return false;
944         } else if (PyFloat_Check(src.ptr())) {
945             return false;
946         } else if (std::is_unsigned<py_type>::value) {
947             py_value = as_unsigned<py_type>(src.ptr());
948         } else { // signed integer:
949             py_value = sizeof(T) <= sizeof(long)
950                 ? (py_type) PyLong_AsLong(src.ptr())
951                 : (py_type) PYBIND11_LONG_AS_LONGLONG(src.ptr());
952         }
954         bool py_err = py_value == (py_type) -1 && PyErr_Occurred();
955         if (py_err || (std::is_integral<T>::value && sizeof(py_type) != sizeof(T) &&
956                        (py_value < (py_type) std::numeric_limits<T>::min() ||
957                         py_value > (py_type) std::numeric_limits<T>::max()))) {
958             bool type_error = py_err && PyErr_ExceptionMatches(
959 #if PY_VERSION_HEX < 0x03000000 && !defined(PYPY_VERSION)
960                 PyExc_SystemError
961 #else
962                 PyExc_TypeError
963 #endif
964             );
965             PyErr_Clear();
966             if (type_error && convert && PyNumber_Check(src.ptr())) {
967                 auto tmp = reinterpret_steal<object>(std::is_floating_point<T>::value
968                                                      ? PyNumber_Float(src.ptr())
969                                                      : PyNumber_Long(src.ptr()));
970                 PyErr_Clear();
971                 return load(tmp, false);
972             }
973             return false;
974         }
976         value = (T) py_value;
977         return true;
978     }
980     static handle cast(T src, return_value_policy /* policy */, handle /* parent */) {
981         if (std::is_floating_point<T>::value) {
982             return PyFloat_FromDouble((double) src);
983         } else if (sizeof(T) <= sizeof(long)) {
984             if (std::is_signed<T>::value)
985                 return PyLong_FromLong((long) src);
986             else
987                 return PyLong_FromUnsignedLong((unsigned long) src);
988         } else {
989             if (std::is_signed<T>::value)
990                 return PyLong_FromLongLong((long long) src);
991             else
992                 return PyLong_FromUnsignedLongLong((unsigned long long) src);
993         }
994     }
996     PYBIND11_TYPE_CASTER(T, _<std::is_integral<T>::value>("int", "float"));
997 };
999 template<typename T> struct void_caster {
1000 public:
1001     bool load(handle src, bool) {
1002         if (src && src.is_none())
1003             return true;
1004         return false;
1005     }
1006     static handle cast(T, return_value_policy /* policy */, handle /* parent */) {
1007         return none().inc_ref();
1008     }
1009     PYBIND11_TYPE_CASTER(T, _("None"));
1010 };
1012 template <> class type_caster<void_type> : public void_caster<void_type> {};
1014 template <> class type_caster<void> : public type_caster<void_type> {
1015 public:
1016     using type_caster<void_type>::cast;
1018     bool load(handle h, bool) {
1019         if (!h) {
1020             return false;
1021         } else if (h.is_none()) {
1022             value = nullptr;
1023             return true;
1024         }
1026         /* Check if this is a capsule */
1027         if (isinstance<capsule>(h)) {
1028             value = reinterpret_borrow<capsule>(h);
1029             return true;
1030         }
1032         /* Check if this is a C++ type */
1033         auto &bases = all_type_info((PyTypeObject *) h.get_type().ptr());
1034         if (bases.size() == 1) { // Only allowing loading from a single-value type
1035             value = values_and_holders(reinterpret_cast<instance *>(h.ptr())).begin()->value_ptr();
1036             return true;
1037         }
1039         /* Fail */
1040         return false;
1041     }
1043     static handle cast(const void *ptr, return_value_policy /* policy */, handle /* parent */) {
1044         if (ptr)
1045             return capsule(ptr).release();
1046         else
1047             return none().inc_ref();
1048     }
1050     template <typename T> using cast_op_type = void*&;
1051     operator void *&() { return value; }
1052     static PYBIND11_DESCR name() { return type_descr(_("capsule")); }
1053 private:
1054     void *value = nullptr;
1055 };
1057 template <> class type_caster<std::nullptr_t> : public void_caster<std::nullptr_t> { };
1059 template <> class type_caster<bool> {
1060 public:
1061     bool load(handle src, bool convert) {
1062         if (!src) return false;
1063         else if (src.ptr() == Py_True) { value = true; return true; }
1064         else if (src.ptr() == Py_False) { value = false; return true; }
1065         else if (convert || !strcmp("numpy.bool_", Py_TYPE(src.ptr())->tp_name)) {
1066             // (allow non-implicit conversion for numpy booleans)
1068             Py_ssize_t res = -1;
1069             if (src.is_none()) {
1070                 res = 0;  // None is implicitly converted to False
1071             }
1072             #if defined(PYPY_VERSION)
1073             // On PyPy, check that "__bool__" (or "__nonzero__" on Python 2.7) attr exists
1074             else if (hasattr(src, PYBIND11_BOOL_ATTR)) {
1075                 res = PyObject_IsTrue(src.ptr());
1076             }
1077             #else
1078             // Alternate approach for CPython: this does the same as the above, but optimized
1079             // using the CPython API so as to avoid an unneeded attribute lookup.
1080             else if (auto tp_as_number = src.ptr()->ob_type->tp_as_number) {
1081                 if (PYBIND11_NB_BOOL(tp_as_number)) {
1082                     res = (*PYBIND11_NB_BOOL(tp_as_number))(src.ptr());
1083                 }
1084             }
1085             #endif
1086             if (res == 0 || res == 1) {
1087                 value = (bool) res;
1088                 return true;
1089             }
1090         }
1091         return false;
1092     }
1093     static handle cast(bool src, return_value_policy /* policy */, handle /* parent */) {
1094         return handle(src ? Py_True : Py_False).inc_ref();
1095     }
1096     PYBIND11_TYPE_CASTER(bool, _("bool"));
1097 };
1099 // Helper class for UTF-{8,16,32} C++ stl strings:
1100 template <typename StringType, bool IsView = false> struct string_caster {
1101     using CharT = typename StringType::value_type;
1103     // Simplify life by being able to assume standard char sizes (the standard only guarantees
1104     // minimums, but Python requires exact sizes)
1105     static_assert(!std::is_same<CharT, char>::value || sizeof(CharT) == 1, "Unsupported char size != 1");
1106     static_assert(!std::is_same<CharT, char16_t>::value || sizeof(CharT) == 2, "Unsupported char16_t size != 2");
1107     static_assert(!std::is_same<CharT, char32_t>::value || sizeof(CharT) == 4, "Unsupported char32_t size != 4");
1108     // wchar_t can be either 16 bits (Windows) or 32 (everywhere else)
1109     static_assert(!std::is_same<CharT, wchar_t>::value || sizeof(CharT) == 2 || sizeof(CharT) == 4,
1110             "Unsupported wchar_t size != 2/4");
1111     static constexpr size_t UTF_N = 8 * sizeof(CharT);
1113     bool load(handle src, bool) {
1114 #if PY_MAJOR_VERSION < 3
1115         object temp;
1116 #endif
1117         handle load_src = src;
1118         if (!src) {
1119             return false;
1120         } else if (!PyUnicode_Check(load_src.ptr())) {
1121 #if PY_MAJOR_VERSION >= 3
1122             return load_bytes(load_src);
1123 #else
1124             if (sizeof(CharT) == 1) {
1125                 return load_bytes(load_src);
1126             }
1128             // The below is a guaranteed failure in Python 3 when PyUnicode_Check returns false
1129             if (!PYBIND11_BYTES_CHECK(load_src.ptr()))
1130                 return false;
1132             temp = reinterpret_steal<object>(PyUnicode_FromObject(load_src.ptr()));
1133             if (!temp) { PyErr_Clear(); return false; }
1134             load_src = temp;
1135 #endif
1136         }
1138         object utfNbytes = reinterpret_steal<object>(PyUnicode_AsEncodedString(
1139             load_src.ptr(), UTF_N == 8 ? "utf-8" : UTF_N == 16 ? "utf-16" : "utf-32", nullptr));
1140         if (!utfNbytes) { PyErr_Clear(); return false; }
1142         const CharT *buffer = reinterpret_cast<const CharT *>(PYBIND11_BYTES_AS_STRING(utfNbytes.ptr()));
1143         size_t length = (size_t) PYBIND11_BYTES_SIZE(utfNbytes.ptr()) / sizeof(CharT);
1144         if (UTF_N > 8) { buffer++; length--; } // Skip BOM for UTF-16/32
1145         value = StringType(buffer, length);
1147         // If we're loading a string_view we need to keep the encoded Python object alive:
1148         if (IsView)
1149             loader_life_support::add_patient(utfNbytes);
1151         return true;
1152     }
1154     static handle cast(const StringType &src, return_value_policy /* policy */, handle /* parent */) {
1155         const char *buffer = reinterpret_cast<const char *>(src.data());
1156         ssize_t nbytes = ssize_t(src.size() * sizeof(CharT));
1157         handle s = decode_utfN(buffer, nbytes);
1158         if (!s) throw error_already_set();
1159         return s;
1160     }
1162     PYBIND11_TYPE_CASTER(StringType, _(PYBIND11_STRING_NAME));
1164 private:
1165     static handle decode_utfN(const char *buffer, ssize_t nbytes) {
1166 #if !defined(PYPY_VERSION)
1167         return
1168             UTF_N == 8  ? PyUnicode_DecodeUTF8(buffer, nbytes, nullptr) :
1169             UTF_N == 16 ? PyUnicode_DecodeUTF16(buffer, nbytes, nullptr, nullptr) :
1170                           PyUnicode_DecodeUTF32(buffer, nbytes, nullptr, nullptr);
1171 #else
1172         // PyPy seems to have multiple problems related to PyUnicode_UTF*: the UTF8 version
1173         // sometimes segfaults for unknown reasons, while the UTF16 and 32 versions require a
1174         // non-const char * arguments, which is also a nuisance, so bypass the whole thing by just
1175         // passing the encoding as a string value, which works properly:
1176         return PyUnicode_Decode(buffer, nbytes, UTF_N == 8 ? "utf-8" : UTF_N == 16 ? "utf-16" : "utf-32", nullptr);
1177 #endif
1178     }
1180     // When loading into a std::string or char*, accept a bytes object as-is (i.e.
1181     // without any encoding/decoding attempt).  For other C++ char sizes this is a no-op.
1182     // which supports loading a unicode from a str, doesn't take this path.
1183     template <typename C = CharT>
1184     bool load_bytes(enable_if_t<sizeof(C) == 1, handle> src) {
1185         if (PYBIND11_BYTES_CHECK(src.ptr())) {
1186             // We were passed a Python 3 raw bytes; accept it into a std::string or char*
1187             // without any encoding attempt.
1188             const char *bytes = PYBIND11_BYTES_AS_STRING(src.ptr());
1189             if (bytes) {
1190                 value = StringType(bytes, (size_t) PYBIND11_BYTES_SIZE(src.ptr()));
1191                 return true;
1192             }
1193         }
1195         return false;
1196     }
1198     template <typename C = CharT>
1199     bool load_bytes(enable_if_t<sizeof(C) != 1, handle>) { return false; }
1200 };
1202 template <typename CharT, class Traits, class Allocator>
1203 struct type_caster<std::basic_string<CharT, Traits, Allocator>, enable_if_t<is_std_char_type<CharT>::value>>
1204     : string_caster<std::basic_string<CharT, Traits, Allocator>> {};
1206 #ifdef PYBIND11_HAS_STRING_VIEW
1207 template <typename CharT, class Traits>
1208 struct type_caster<std::basic_string_view<CharT, Traits>, enable_if_t<is_std_char_type<CharT>::value>>
1209     : string_caster<std::basic_string_view<CharT, Traits>, true> {};
1210 #endif
1212 // Type caster for C-style strings.  We basically use a std::string type caster, but also add the
1213 // ability to use None as a nullptr char* (which the string caster doesn't allow).
1214 template <typename CharT> struct type_caster<CharT, enable_if_t<is_std_char_type<CharT>::value>> {
1215     using StringType = std::basic_string<CharT>;
1216     using StringCaster = type_caster<StringType>;
1217     StringCaster str_caster;
1218     bool none = false;
1219     CharT one_char = 0;
1220 public:
1221     bool load(handle src, bool convert) {
1222         if (!src) return false;
1223         if (src.is_none()) {
1224             // Defer accepting None to other overloads (if we aren't in convert mode):
1225             if (!convert) return false;
1226             none = true;
1227             return true;
1228         }
1229         return str_caster.load(src, convert);
1230     }
1232     static handle cast(const CharT *src, return_value_policy policy, handle parent) {
1233         if (src == nullptr) return pybind11::none().inc_ref();
1234         return StringCaster::cast(StringType(src), policy, parent);
1235     }
1237     static handle cast(CharT src, return_value_policy policy, handle parent) {
1238         if (std::is_same<char, CharT>::value) {
1239             handle s = PyUnicode_DecodeLatin1((const char *) &src, 1, nullptr);
1240             if (!s) throw error_already_set();
1241             return s;
1242         }
1243         return StringCaster::cast(StringType(1, src), policy, parent);
1244     }
1246     operator CharT*() { return none ? nullptr : const_cast<CharT *>(static_cast<StringType &>(str_caster).c_str()); }
1247     operator CharT&() {
1248         if (none)
1249             throw value_error("Cannot convert None to a character");
1251         auto &value = static_cast<StringType &>(str_caster);
1252         size_t str_len = value.size();
1253         if (str_len == 0)
1254             throw value_error("Cannot convert empty string to a character");
1256         // If we're in UTF-8 mode, we have two possible failures: one for a unicode character that
1257         // is too high, and one for multiple unicode characters (caught later), so we need to figure
1258         // out how long the first encoded character is in bytes to distinguish between these two
1259         // errors.  We also allow want to allow unicode characters U+0080 through U+00FF, as those
1260         // can fit into a single char value.
1261         if (StringCaster::UTF_N == 8 && str_len > 1 && str_len <= 4) {
1262             unsigned char v0 = static_cast<unsigned char>(value[0]);
1263             size_t char0_bytes = !(v0 & 0x80) ? 1 : // low bits only: 0-127
1264                 (v0 & 0xE0) == 0xC0 ? 2 : // 0b110xxxxx - start of 2-byte sequence
1265                 (v0 & 0xF0) == 0xE0 ? 3 : // 0b1110xxxx - start of 3-byte sequence
1266                 4; // 0b11110xxx - start of 4-byte sequence
1268             if (char0_bytes == str_len) {
1269                 // If we have a 128-255 value, we can decode it into a single char:
1270                 if (char0_bytes == 2 && (v0 & 0xFC) == 0xC0) { // 0x110000xx 0x10xxxxxx
1271                     one_char = static_cast<CharT>(((v0 & 3) << 6) + (static_cast<unsigned char>(value[1]) & 0x3F));
1272                     return one_char;
1273                 }
1274                 // Otherwise we have a single character, but it's > U+00FF
1275                 throw value_error("Character code point not in range(0x100)");
1276             }
1277         }
1279         // UTF-16 is much easier: we can only have a surrogate pair for values above U+FFFF, thus a
1280         // surrogate pair with total length 2 instantly indicates a range error (but not a "your
1281         // string was too long" error).
1282         else if (StringCaster::UTF_N == 16 && str_len == 2) {
1283             one_char = static_cast<CharT>(value[0]);
1284             if (one_char >= 0xD800 && one_char < 0xE000)
1285                 throw value_error("Character code point not in range(0x10000)");
1286         }
1288         if (str_len != 1)
1289             throw value_error("Expected a character, but multi-character string found");
1291         one_char = value[0];
1292         return one_char;
1293     }
1295     static PYBIND11_DESCR name() { return type_descr(_(PYBIND11_STRING_NAME)); }
1296     template <typename _T> using cast_op_type = pybind11::detail::cast_op_type<_T>;
1297 };
1299 // Base implementation for std::tuple and std::pair
1300 template <template<typename...> class Tuple, typename... Ts> class tuple_caster {
1301     using type = Tuple<Ts...>;
1302     static constexpr auto size = sizeof...(Ts);
1303     using indices = make_index_sequence<size>;
1304 public:
1306     bool load(handle src, bool convert) {
1307         if (!isinstance<sequence>(src))
1308             return false;
1309         const auto seq = reinterpret_borrow<sequence>(src);
1310         if (seq.size() != size)
1311             return false;
1312         return load_impl(seq, convert, indices{});
1313     }
1315     template <typename T>
1316     static handle cast(T &&src, return_value_policy policy, handle parent) {
1317         return cast_impl(std::forward<T>(src), policy, parent, indices{});
1318     }
1320     static PYBIND11_DESCR name() {
1321         return type_descr(_("Tuple[") + detail::concat(make_caster<Ts>::name()...) + _("]"));
1322     }
1324     template <typename T> using cast_op_type = type;
1326     operator type() & { return implicit_cast(indices{}); }
1327     operator type() && { return std::move(*this).implicit_cast(indices{}); }
1329 protected:
1330     template <size_t... Is>
1331     type implicit_cast(index_sequence<Is...>) & { return type(cast_op<Ts>(std::get<Is>(subcasters))...); }
1332     template <size_t... Is>
1333     type implicit_cast(index_sequence<Is...>) && { return type(cast_op<Ts>(std::move(std::get<Is>(subcasters)))...); }
1335     static constexpr bool load_impl(const sequence &, bool, index_sequence<>) { return true; }
1337     template <size_t... Is>
1338     bool load_impl(const sequence &seq, bool convert, index_sequence<Is...>) {
1339         for (bool r : {std::get<Is>(subcasters).load(seq[Is], convert)...})
1340             if (!r)
1341                 return false;
1342         return true;
1343     }
1345     /* Implementation: Convert a C++ tuple into a Python tuple */
1346     template <typename T, size_t... Is>
1347     static handle cast_impl(T &&src, return_value_policy policy, handle parent, index_sequence<Is...>) {
1348         std::array<object, size> entries{{
1349             reinterpret_steal<object>(make_caster<Ts>::cast(std::get<Is>(std::forward<T>(src)), policy, parent))...
1350         }};
1351         for (const auto &entry: entries)
1352             if (!entry)
1353                 return handle();
1354         tuple result(size);
1355         int counter = 0;
1356         for (auto & entry: entries)
1357             PyTuple_SET_ITEM(result.ptr(), counter++, entry.release().ptr());
1358         return result.release();
1359     }
1361     Tuple<make_caster<Ts>...> subcasters;
1362 };
1364 template <typename T1, typename T2> class type_caster<std::pair<T1, T2>>
1365     : public tuple_caster<std::pair, T1, T2> {};
1367 template <typename... Ts> class type_caster<std::tuple<Ts...>>
1368     : public tuple_caster<std::tuple, Ts...> {};
1370 /// Helper class which abstracts away certain actions. Users can provide specializations for
1371 /// custom holders, but it's only necessary if the type has a non-standard interface.
1372 template <typename T>
1373 struct holder_helper {
1374     static auto get(const T &p) -> decltype(p.get()) { return p.get(); }
1375 };
1377 /// Type caster for holder types like std::shared_ptr, etc.
1378 template <typename type, typename holder_type>
1379 struct copyable_holder_caster : public type_caster_base<type> {
1380 public:
1381     using base = type_caster_base<type>;
1382     static_assert(std::is_base_of<base, type_caster<type>>::value,
1383             "Holder classes are only supported for custom types");
1384     using base::base;
1385     using base::cast;
1386     using base::typeinfo;
1387     using base::value;
1389     bool load(handle src, bool convert) {
1390         return base::template load_impl<copyable_holder_caster<type, holder_type>>(src, convert);
1391     }
1393     explicit operator type*() { return this->value; }
1394     explicit operator type&() { return *(this->value); }
1395     explicit operator holder_type*() { return std::addressof(holder); }
1397     // Workaround for Intel compiler bug
1398     // see pybind11 issue 94
1399     #if defined(__ICC) || defined(__INTEL_COMPILER)
1400     operator holder_type&() { return holder; }
1401     #else
1402     explicit operator holder_type&() { return holder; }
1403     #endif
1405     static handle cast(const holder_type &src, return_value_policy, handle) {
1406         const auto *ptr = holder_helper<holder_type>::get(src);
1407         return type_caster_base<type>::cast_holder(ptr, &src);
1408     }
1410 protected:
1411     friend class type_caster_generic;
1412     void check_holder_compat() {
1413         if (typeinfo->default_holder)
1414             throw cast_error("Unable to load a custom holder type from a default-holder instance");
1415     }
1417     bool load_value(value_and_holder &&v_h) {
1418         if (v_h.holder_constructed()) {
1419             value = v_h.value_ptr();
1420             holder = v_h.template holder<holder_type>();
1421             return true;
1422         } else {
1423             throw cast_error("Unable to cast from non-held to held instance (T& to Holder<T>) "
1424 #if defined(NDEBUG)
1425                              "(compile in debug mode for type information)");
1426 #else
1427                              "of type '" + type_id<holder_type>() + "''");
1428 #endif
1429         }
1430     }
1432     template <typename T = holder_type, detail::enable_if_t<!std::is_constructible<T, const T &, type*>::value, int> = 0>
1433     bool try_implicit_casts(handle, bool) { return false; }
1435     template <typename T = holder_type, detail::enable_if_t<std::is_constructible<T, const T &, type*>::value, int> = 0>
1436     bool try_implicit_casts(handle src, bool convert) {
1437         for (auto &cast : typeinfo->implicit_casts) {
1438             copyable_holder_caster sub_caster(*cast.first);
1439             if (sub_caster.load(src, convert)) {
1440                 value = cast.second(sub_caster.value);
1441                 holder = holder_type(sub_caster.holder, (type *) value);
1442                 return true;
1443             }
1444         }
1445         return false;
1446     }
1448     static bool try_direct_conversions(handle) { return false; }
1451     holder_type holder;
1452 };
1454 /// Specialize for the common std::shared_ptr, so users don't need to
1455 template <typename T>
1456 class type_caster<std::shared_ptr<T>> : public copyable_holder_caster<T, std::shared_ptr<T>> { };
1458 template <typename type, typename holder_type>
1459 struct move_only_holder_caster {
1460     static_assert(std::is_base_of<type_caster_base<type>, type_caster<type>>::value,
1461             "Holder classes are only supported for custom types");
1463     static handle cast(holder_type &&src, return_value_policy, handle) {
1464         auto *ptr = holder_helper<holder_type>::get(src);
1465         return type_caster_base<type>::cast_holder(ptr, std::addressof(src));
1466     }
1467     static PYBIND11_DESCR name() { return type_caster_base<type>::name(); }
1468 };
1470 template <typename type, typename deleter>
1471 class type_caster<std::unique_ptr<type, deleter>>
1472     : public move_only_holder_caster<type, std::unique_ptr<type, deleter>> { };
1474 template <typename type, typename holder_type>
1475 using type_caster_holder = conditional_t<is_copy_constructible<holder_type>::value,
1476                                          copyable_holder_caster<type, holder_type>,
1477                                          move_only_holder_caster<type, holder_type>>;
1479 template <typename T, bool Value = false> struct always_construct_holder { static constexpr bool value = Value; };
1481 /// Create a specialization for custom holder types (silently ignores std::shared_ptr)
1482 #define PYBIND11_DECLARE_HOLDER_TYPE(type, holder_type, ...) \
1483     namespace pybind11 { namespace detail { \
1484     template <typename type> \
1485     struct always_construct_holder<holder_type> : always_construct_holder<void, ##__VA_ARGS__>  { }; \
1486     template <typename type> \
1487     class type_caster<holder_type, enable_if_t<!is_shared_ptr<holder_type>::value>> \
1488         : public type_caster_holder<type, holder_type> { }; \
1489     }}
1491 // PYBIND11_DECLARE_HOLDER_TYPE holder types:
1492 template <typename base, typename holder> struct is_holder_type :
1493     std::is_base_of<detail::type_caster_holder<base, holder>, detail::type_caster<holder>> {};
1494 // Specialization for always-supported unique_ptr holders:
1495 template <typename base, typename deleter> struct is_holder_type<base, std::unique_ptr<base, deleter>> :
1496     std::true_type {};
1498 template <typename T> struct handle_type_name { static PYBIND11_DESCR name() { return _<T>(); } };
1499 template <> struct handle_type_name<bytes> { static PYBIND11_DESCR name() { return _(PYBIND11_BYTES_NAME); } };
1500 template <> struct handle_type_name<args> { static PYBIND11_DESCR name() { return _("*args"); } };
1501 template <> struct handle_type_name<kwargs> { static PYBIND11_DESCR name() { return _("**kwargs"); } };
1503 template <typename type>
1504 struct pyobject_caster {
1505     template <typename T = type, enable_if_t<std::is_same<T, handle>::value, int> = 0>
1506     bool load(handle src, bool /* convert */) { value = src; return static_cast<bool>(value); }
1508     template <typename T = type, enable_if_t<std::is_base_of<object, T>::value, int> = 0>
1509     bool load(handle src, bool /* convert */) {
1510         if (!isinstance<type>(src))
1511             return false;
1512         value = reinterpret_borrow<type>(src);
1513         return true;
1514     }
1516     static handle cast(const handle &src, return_value_policy /* policy */, handle /* parent */) {
1517         return src.inc_ref();
1518     }
1519     PYBIND11_TYPE_CASTER(type, handle_type_name<type>::name());
1520 };
1522 template <typename T>
1523 class type_caster<T, enable_if_t<is_pyobject<T>::value>> : public pyobject_caster<T> { };
1525 // Our conditions for enabling moving are quite restrictive:
1526 // At compile time:
1527 // - T needs to be a non-const, non-pointer, non-reference type
1528 // - type_caster<T>::operator T&() must exist
1529 // - the type must be move constructible (obviously)
1530 // At run-time:
1531 // - if the type is non-copy-constructible, the object must be the sole owner of the type (i.e. it
1532 //   must have ref_count() == 1)h
1533 // If any of the above are not satisfied, we fall back to copying.
1534 template <typename T> using move_is_plain_type = satisfies_none_of<T,
1535     std::is_void, std::is_pointer, std::is_reference, std::is_const
1536 >;
1537 template <typename T, typename SFINAE = void> struct move_always : std::false_type {};
1538 template <typename T> struct move_always<T, enable_if_t<all_of<
1539     move_is_plain_type<T>,
1540     negation<is_copy_constructible<T>>,
1541     std::is_move_constructible<T>,
1542     std::is_same<decltype(std::declval<make_caster<T>>().operator T&()), T&>
1543 >::value>> : std::true_type {};
1544 template <typename T, typename SFINAE = void> struct move_if_unreferenced : std::false_type {};
1545 template <typename T> struct move_if_unreferenced<T, enable_if_t<all_of<
1546     move_is_plain_type<T>,
1547     negation<move_always<T>>,
1548     std::is_move_constructible<T>,
1549     std::is_same<decltype(std::declval<make_caster<T>>().operator T&()), T&>
1550 >::value>> : std::true_type {};
1551 template <typename T> using move_never = none_of<move_always<T>, move_if_unreferenced<T>>;
1553 // Detect whether returning a `type` from a cast on type's type_caster is going to result in a
1554 // reference or pointer to a local variable of the type_caster.  Basically, only
1555 // non-reference/pointer `type`s and reference/pointers from a type_caster_generic are safe;
1556 // everything else returns a reference/pointer to a local variable.
1557 template <typename type> using cast_is_temporary_value_reference = bool_constant<
1558     (std::is_reference<type>::value || std::is_pointer<type>::value) &&
1559     !std::is_base_of<type_caster_generic, make_caster<type>>::value
1560 >;
1562 // When a value returned from a C++ function is being cast back to Python, we almost always want to
1563 // force `policy = move`, regardless of the return value policy the function/method was declared
1564 // with.
1565 template <typename Return, typename SFINAE = void> struct return_value_policy_override {
1566     static return_value_policy policy(return_value_policy p) { return p; }
1567 };
1569 template <typename Return> struct return_value_policy_override<Return,
1570         detail::enable_if_t<std::is_base_of<type_caster_generic, make_caster<Return>>::value, void>> {
1571     static return_value_policy policy(return_value_policy p) {
1572         return !std::is_lvalue_reference<Return>::value && !std::is_pointer<Return>::value
1573             ? return_value_policy::move : p;
1574     }
1575 };
1577 // Basic python -> C++ casting; throws if casting fails
1578 template <typename T, typename SFINAE> type_caster<T, SFINAE> &load_type(type_caster<T, SFINAE> &conv, const handle &handle) {
1579     if (!conv.load(handle, true)) {
1580 #if defined(NDEBUG)
1581         throw cast_error("Unable to cast Python instance to C++ type (compile in debug mode for details)");
1582 #else
1583         throw cast_error("Unable to cast Python instance of type " +
1584             (std::string) str(handle.get_type()) + " to C++ type '" + type_id<T>() + "'");
1585 #endif
1586     }
1587     return conv;
1589 // Wrapper around the above that also constructs and returns a type_caster
1590 template <typename T> make_caster<T> load_type(const handle &handle) {
1591     make_caster<T> conv;
1592     load_type(conv, handle);
1593     return conv;
1596 NAMESPACE_END(detail)
1598 // pytype -> C++ type
1599 template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0>
1600 T cast(const handle &handle) {
1601     using namespace detail;
1602     static_assert(!cast_is_temporary_value_reference<T>::value,
1603             "Unable to cast type to reference: value is local to type caster");
1604     return cast_op<T>(load_type<T>(handle));
1607 // pytype -> pytype (calls converting constructor)
1608 template <typename T, detail::enable_if_t<detail::is_pyobject<T>::value, int> = 0>
1609 T cast(const handle &handle) { return T(reinterpret_borrow<object>(handle)); }
1611 // C++ type -> py::object
1612 template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0>
1613 object cast(const T &value, return_value_policy policy = return_value_policy::automatic_reference,
1614             handle parent = handle()) {
1615     if (policy == return_value_policy::automatic)
1616         policy = std::is_pointer<T>::value ? return_value_policy::take_ownership : return_value_policy::copy;
1617     else if (policy == return_value_policy::automatic_reference)
1618         policy = std::is_pointer<T>::value ? return_value_policy::reference : return_value_policy::copy;
1619     return reinterpret_steal<object>(detail::make_caster<T>::cast(value, policy, parent));
1622 template <typename T> T handle::cast() const { return pybind11::cast<T>(*this); }
1623 template <> inline void handle::cast() const { return; }
1625 template <typename T>
1626 detail::enable_if_t<!detail::move_never<T>::value, T> move(object &&obj) {
1627     if (obj.ref_count() > 1)
1628 #if defined(NDEBUG)
1629         throw cast_error("Unable to cast Python instance to C++ rvalue: instance has multiple references"
1630             " (compile in debug mode for details)");
1631 #else
1632         throw cast_error("Unable to move from Python " + (std::string) str(obj.get_type()) +
1633                 " instance to C++ " + type_id<T>() + " instance: instance has multiple references");
1634 #endif
1636     // Move into a temporary and return that, because the reference may be a local value of `conv`
1637     T ret = std::move(detail::load_type<T>(obj).operator T&());
1638     return ret;
1641 // Calling cast() on an rvalue calls pybind::cast with the object rvalue, which does:
1642 // - If we have to move (because T has no copy constructor), do it.  This will fail if the moved
1643 //   object has multiple references, but trying to copy will fail to compile.
1644 // - If both movable and copyable, check ref count: if 1, move; otherwise copy
1645 // - Otherwise (not movable), copy.
1646 template <typename T> detail::enable_if_t<detail::move_always<T>::value, T> cast(object &&object) {
1647     return move<T>(std::move(object));
1649 template <typename T> detail::enable_if_t<detail::move_if_unreferenced<T>::value, T> cast(object &&object) {
1650     if (object.ref_count() > 1)
1651         return cast<T>(object);
1652     else
1653         return move<T>(std::move(object));
1655 template <typename T> detail::enable_if_t<detail::move_never<T>::value, T> cast(object &&object) {
1656     return cast<T>(object);
1659 template <typename T> T object::cast() const & { return pybind11::cast<T>(*this); }
1660 template <typename T> T object::cast() && { return pybind11::cast<T>(std::move(*this)); }
1661 template <> inline void object::cast() const & { return; }
1662 template <> inline void object::cast() && { return; }
1664 NAMESPACE_BEGIN(detail)
1666 // Declared in pytypes.h:
1667 template <typename T, enable_if_t<!is_pyobject<T>::value, int>>
1668 object object_or_cast(T &&o) { return pybind11::cast(std::forward<T>(o)); }
1670 struct overload_unused {}; // Placeholder type for the unneeded (and dead code) static variable in the OVERLOAD_INT macro
1671 template <typename ret_type> using overload_caster_t = conditional_t<
1672     cast_is_temporary_value_reference<ret_type>::value, make_caster<ret_type>, overload_unused>;
1674 // Trampoline use: for reference/pointer types to value-converted values, we do a value cast, then
1675 // store the result in the given variable.  For other types, this is a no-op.
1676 template <typename T> enable_if_t<cast_is_temporary_value_reference<T>::value, T> cast_ref(object &&o, make_caster<T> &caster) {
1677     return cast_op<T>(load_type(caster, o));
1679 template <typename T> enable_if_t<!cast_is_temporary_value_reference<T>::value, T> cast_ref(object &&, overload_unused &) {
1680     pybind11_fail("Internal error: cast_ref fallback invoked"); }
1682 // Trampoline use: Having a pybind11::cast with an invalid reference type is going to static_assert, even
1683 // though if it's in dead code, so we provide a "trampoline" to pybind11::cast that only does anything in
1684 // cases where pybind11::cast is valid.
1685 template <typename T> enable_if_t<!cast_is_temporary_value_reference<T>::value, T> cast_safe(object &&o) {
1686     return pybind11::cast<T>(std::move(o)); }
1687 template <typename T> enable_if_t<cast_is_temporary_value_reference<T>::value, T> cast_safe(object &&) {
1688     pybind11_fail("Internal error: cast_safe fallback invoked"); }
1689 template <> inline void cast_safe<void>(object &&) {}
1691 NAMESPACE_END(detail)
1693 template <return_value_policy policy = return_value_policy::automatic_reference>
1694 tuple make_tuple() { return tuple(0); }
1696 template <return_value_policy policy = return_value_policy::automatic_reference,
1697           typename... Args> tuple make_tuple(Args&&... args_) {
1698     constexpr size_t size = sizeof...(Args);
1699     std::array<object, size> args {
1700         { reinterpret_steal<object>(detail::make_caster<Args>::cast(
1701             std::forward<Args>(args_), policy, nullptr))... }
1702     };
1703     for (size_t i = 0; i < args.size(); i++) {
1704         if (!args[i]) {
1705 #if defined(NDEBUG)
1706             throw cast_error("make_tuple(): unable to convert arguments to Python object (compile in debug mode for details)");
1707 #else
1708             std::array<std::string, size> argtypes { {type_id<Args>()...} };
1709             throw cast_error("make_tuple(): unable to convert argument of type '" +
1710                 argtypes[i] + "' to Python object");
1711 #endif
1712         }
1713     }
1714     tuple result(size);
1715     int counter = 0;
1716     for (auto &arg_value : args)
1717         PyTuple_SET_ITEM(result.ptr(), counter++, arg_value.release().ptr());
1718     return result;
1721 /// \ingroup annotations
1722 /// Annotation for arguments
1723 struct arg {
1724     /// Constructs an argument with the name of the argument; if null or omitted, this is a positional argument.
1725     constexpr explicit arg(const char *name = nullptr) : name(name), flag_noconvert(false), flag_none(true) { }
1726     /// Assign a value to this argument
1727     template <typename T> arg_v operator=(T &&value) const;
1728     /// Indicate that the type should not be converted in the type caster
1729     arg &noconvert(bool flag = true) { flag_noconvert = flag; return *this; }
1730     /// Indicates that the argument should/shouldn't allow None (e.g. for nullable pointer args)
1731     arg &none(bool flag = true) { flag_none = flag; return *this; }
1733     const char *name; ///< If non-null, this is a named kwargs argument
1734     bool flag_noconvert : 1; ///< If set, do not allow conversion (requires a supporting type caster!)
1735     bool flag_none : 1; ///< If set (the default), allow None to be passed to this argument
1736 };
1738 /// \ingroup annotations
1739 /// Annotation for arguments with values
1740 struct arg_v : arg {
1741 private:
1742     template <typename T>
1743     arg_v(arg &&base, T &&x, const char *descr = nullptr)
1744         : arg(base),
1745           value(reinterpret_steal<object>(
1746               detail::make_caster<T>::cast(x, return_value_policy::automatic, {})
1747           )),
1748           descr(descr)
1749 #if !defined(NDEBUG)
1750         , type(type_id<T>())
1751 #endif
1752     { }
1754 public:
1755     /// Direct construction with name, default, and description
1756     template <typename T>
1757     arg_v(const char *name, T &&x, const char *descr = nullptr)
1758         : arg_v(arg(name), std::forward<T>(x), descr) { }
1760     /// Called internally when invoking `py::arg("a") = value`
1761     template <typename T>
1762     arg_v(const arg &base, T &&x, const char *descr = nullptr)
1763         : arg_v(arg(base), std::forward<T>(x), descr) { }
1765     /// Same as `arg::noconvert()`, but returns *this as arg_v&, not arg&
1766     arg_v &noconvert(bool flag = true) { arg::noconvert(flag); return *this; }
1768     /// Same as `arg::nonone()`, but returns *this as arg_v&, not arg&
1769     arg_v &none(bool flag = true) { arg::none(flag); return *this; }
1771     /// The default value
1772     object value;
1773     /// The (optional) description of the default value
1774     const char *descr;
1775 #if !defined(NDEBUG)
1776     /// The C++ type name of the default value (only available when compiled in debug mode)
1777     std::string type;
1778 #endif
1779 };
1781 template <typename T>
1782 arg_v arg::operator=(T &&value) const { return {std::move(*this), std::forward<T>(value)}; }
1784 /// Alias for backward compatibility -- to be removed in version 2.0
1785 template <typename /*unused*/> using arg_t = arg_v;
1787 inline namespace literals {
1788 /** \rst
1789     String literal version of `arg`
1790  \endrst */
1791 constexpr arg operator"" _a(const char *name, size_t) { return arg(name); }
1794 NAMESPACE_BEGIN(detail)
1796 // forward declaration (definition in attr.h)
1797 struct function_record;
1799 /// Internal data associated with a single function call
1800 struct function_call {
1801     function_call(function_record &f, handle p); // Implementation in attr.h
1803     /// The function data:
1804     const function_record &func;
1806     /// Arguments passed to the function:
1807     std::vector<handle> args;
1809     /// The `convert` value the arguments should be loaded with
1810     std::vector<bool> args_convert;
1812     /// Extra references for the optional `py::args` and/or `py::kwargs` arguments (which, if
1813     /// present, are also in `args` but without a reference).
1814     object args_ref, kwargs_ref;
1816     /// The parent, if any
1817     handle parent;
1819     /// If this is a call to an initializer, this argument contains `self`
1820     handle init_self;
1821 };
1824 /// Helper class which loads arguments for C++ functions called from Python
1825 template <typename... Args>
1826 class argument_loader {
1827     using indices = make_index_sequence<sizeof...(Args)>;
1829     template <typename Arg> using argument_is_args   = std::is_same<intrinsic_t<Arg>, args>;
1830     template <typename Arg> using argument_is_kwargs = std::is_same<intrinsic_t<Arg>, kwargs>;
1831     // Get args/kwargs argument positions relative to the end of the argument list:
1832     static constexpr auto args_pos = constexpr_first<argument_is_args, Args...>() - (int) sizeof...(Args),
1833                         kwargs_pos = constexpr_first<argument_is_kwargs, Args...>() - (int) sizeof...(Args);
1835     static constexpr bool args_kwargs_are_last = kwargs_pos >= - 1 && args_pos >= kwargs_pos - 1;
1837     static_assert(args_kwargs_are_last, "py::args/py::kwargs are only permitted as the last argument(s) of a function");
1839 public:
1840     static constexpr bool has_kwargs = kwargs_pos < 0;
1841     static constexpr bool has_args = args_pos < 0;
1843     static PYBIND11_DESCR arg_names() { return detail::concat(make_caster<Args>::name()...); }
1845     bool load_args(function_call &call) {
1846         return load_impl_sequence(call, indices{});
1847     }
1849     template <typename Return, typename Guard, typename Func>
1850     enable_if_t<!std::is_void<Return>::value, Return> call(Func &&f) && {
1851         return std::move(*this).template call_impl<Return>(std::forward<Func>(f), indices{}, Guard{});
1852     }
1854     template <typename Return, typename Guard, typename Func>
1855     enable_if_t<std::is_void<Return>::value, void_type> call(Func &&f) && {
1856         std::move(*this).template call_impl<Return>(std::forward<Func>(f), indices{}, Guard{});
1857         return void_type();
1858     }
1860 private:
1862     static bool load_impl_sequence(function_call &, index_sequence<>) { return true; }
1864     template <size_t... Is>
1865     bool load_impl_sequence(function_call &call, index_sequence<Is...>) {
1866         for (bool r : {std::get<Is>(argcasters).load(call.args[Is], call.args_convert[Is])...})
1867             if (!r)
1868                 return false;
1869         return true;
1870     }
1872     template <typename Return, typename Func, size_t... Is, typename Guard>
1873     Return call_impl(Func &&f, index_sequence<Is...>, Guard &&) {
1874         return std::forward<Func>(f)(cast_op<Args>(std::move(std::get<Is>(argcasters)))...);
1875     }
1877     std::tuple<make_caster<Args>...> argcasters;
1878 };
1880 /// Helper class which collects only positional arguments for a Python function call.
1881 /// A fancier version below can collect any argument, but this one is optimal for simple calls.
1882 template <return_value_policy policy>
1883 class simple_collector {
1884 public:
1885     template <typename... Ts>
1886     explicit simple_collector(Ts &&...values)
1887         : m_args(pybind11::make_tuple<policy>(std::forward<Ts>(values)...)) { }
1889     const tuple &args() const & { return m_args; }
1890     dict kwargs() const { return {}; }
1892     tuple args() && { return std::move(m_args); }
1894     /// Call a Python function and pass the collected arguments
1895     object call(PyObject *ptr) const {
1896         PyObject *result = PyObject_CallObject(ptr, m_args.ptr());
1897         if (!result)
1898             throw error_already_set();
1899         return reinterpret_steal<object>(result);
1900     }
1902 private:
1903     tuple m_args;
1904 };
1906 /// Helper class which collects positional, keyword, * and ** arguments for a Python function call
1907 template <return_value_policy policy>
1908 class unpacking_collector {
1909 public:
1910     template <typename... Ts>
1911     explicit unpacking_collector(Ts &&...values) {
1912         // Tuples aren't (easily) resizable so a list is needed for collection,
1913         // but the actual function call strictly requires a tuple.
1914         auto args_list = list();
1915         int _[] = { 0, (process(args_list, std::forward<Ts>(values)), 0)... };
1916         ignore_unused(_);
1918         m_args = std::move(args_list);
1919     }
1921     const tuple &args() const & { return m_args; }
1922     const dict &kwargs() const & { return m_kwargs; }
1924     tuple args() && { return std::move(m_args); }
1925     dict kwargs() && { return std::move(m_kwargs); }
1927     /// Call a Python function and pass the collected arguments
1928     object call(PyObject *ptr) const {
1929         PyObject *result = PyObject_Call(ptr, m_args.ptr(), m_kwargs.ptr());
1930         if (!result)
1931             throw error_already_set();
1932         return reinterpret_steal<object>(result);
1933     }
1935 private:
1936     template <typename T>
1937     void process(list &args_list, T &&x) {
1938         auto o = reinterpret_steal<object>(detail::make_caster<T>::cast(std::forward<T>(x), policy, {}));
1939         if (!o) {
1940 #if defined(NDEBUG)
1941             argument_cast_error();
1942 #else
1943             argument_cast_error(std::to_string(args_list.size()), type_id<T>());
1944 #endif
1945         }
1946         args_list.append(o);
1947     }
1949     void process(list &args_list, detail::args_proxy ap) {
1950         for (const auto &a : ap)
1951             args_list.append(a);
1952     }
1954     void process(list &/*args_list*/, arg_v a) {
1955         if (!a.name)
1956 #if defined(NDEBUG)
1957             nameless_argument_error();
1958 #else
1959             nameless_argument_error(a.type);
1960 #endif
1962         if (m_kwargs.contains(a.name)) {
1963 #if defined(NDEBUG)
1964             multiple_values_error();
1965 #else
1966             multiple_values_error(a.name);
1967 #endif
1968         }
1969         if (!a.value) {
1970 #if defined(NDEBUG)
1971             argument_cast_error();
1972 #else
1973             argument_cast_error(a.name, a.type);
1974 #endif
1975         }
1976         m_kwargs[a.name] = a.value;
1977     }
1979     void process(list &/*args_list*/, detail::kwargs_proxy kp) {
1980         if (!kp)
1981             return;
1982         for (const auto &k : reinterpret_borrow<dict>(kp)) {
1983             if (m_kwargs.contains(k.first)) {
1984 #if defined(NDEBUG)
1985                 multiple_values_error();
1986 #else
1987                 multiple_values_error(str(k.first));
1988 #endif
1989             }
1990             m_kwargs[k.first] = k.second;
1991         }
1992     }
1994     [[noreturn]] static void nameless_argument_error() {
1995         throw type_error("Got kwargs without a name; only named arguments "
1996                          "may be passed via py::arg() to a python function call. "
1997                          "(compile in debug mode for details)");
1998     }
1999     [[noreturn]] static void nameless_argument_error(std::string type) {
2000         throw type_error("Got kwargs without a name of type '" + type + "'; only named "
2001                          "arguments may be passed via py::arg() to a python function call. ");
2002     }
2003     [[noreturn]] static void multiple_values_error() {
2004         throw type_error("Got multiple values for keyword argument "
2005                          "(compile in debug mode for details)");
2006     }
2008     [[noreturn]] static void multiple_values_error(std::string name) {
2009         throw type_error("Got multiple values for keyword argument '" + name + "'");
2010     }
2012     [[noreturn]] static void argument_cast_error() {
2013         throw cast_error("Unable to convert call argument to Python object "
2014                          "(compile in debug mode for details)");
2015     }
2017     [[noreturn]] static void argument_cast_error(std::string name, std::string type) {
2018         throw cast_error("Unable to convert call argument '" + name
2019                          + "' of type '" + type + "' to Python object");
2020     }
2022 private:
2023     tuple m_args;
2024     dict m_kwargs;
2025 };
2027 /// Collect only positional arguments for a Python function call
2028 template <return_value_policy policy, typename... Args,
2029           typename = enable_if_t<all_of<is_positional<Args>...>::value>>
2030 simple_collector<policy> collect_arguments(Args &&...args) {
2031     return simple_collector<policy>(std::forward<Args>(args)...);
2034 /// Collect all arguments, including keywords and unpacking (only instantiated when needed)
2035 template <return_value_policy policy, typename... Args,
2036           typename = enable_if_t<!all_of<is_positional<Args>...>::value>>
2037 unpacking_collector<policy> collect_arguments(Args &&...args) {
2038     // Following argument order rules for generalized unpacking according to PEP 448
2039     static_assert(
2040         constexpr_last<is_positional, Args...>() < constexpr_first<is_keyword_or_ds, Args...>()
2041         && constexpr_last<is_s_unpacking, Args...>() < constexpr_first<is_ds_unpacking, Args...>(),
2042         "Invalid function call: positional args must precede keywords and ** unpacking; "
2043         "* unpacking must precede ** unpacking"
2044     );
2045     return unpacking_collector<policy>(std::forward<Args>(args)...);
2048 template <typename Derived>
2049 template <return_value_policy policy, typename... Args>
2050 object object_api<Derived>::operator()(Args &&...args) const {
2051     return detail::collect_arguments<policy>(std::forward<Args>(args)...).call(derived().ptr());
2054 template <typename Derived>
2055 template <return_value_policy policy, typename... Args>
2056 object object_api<Derived>::call(Args &&...args) const {
2057     return operator()<policy>(std::forward<Args>(args)...);
2060 NAMESPACE_END(detail)
2062 #define PYBIND11_MAKE_OPAQUE(Type) \
2063     namespace pybind11 { namespace detail { \
2064         template<> class type_caster<Type> : public type_caster_base<Type> { }; \
2065     }}
2067 NAMESPACE_END(PYBIND11_NAMESPACE)