python_packaging/src/external/pybind/include/pybind11/cast.h

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