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

   1 /*
   2     pybind11/pybind11.h: Main header file of the C++11 python
   3     binding generator library
   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 #if defined(__INTEL_COMPILER)
  14 #  pragma warning push
  15 #  pragma warning disable 68    // integer conversion resulted in a change of sign
  16 #  pragma warning disable 186   // pointless comparison of unsigned integer with zero
  17 #  pragma warning disable 878   // incompatible exception specifications
  18 #  pragma warning disable 1334  // the "template" keyword used for syntactic disambiguation may only be used within a template
  19 #  pragma warning disable 1682  // implicit conversion of a 64-bit integral type to a smaller integral type (potential portability problem)
  20 #  pragma warning disable 1786  // function "strdup" was declared deprecated
  21 #  pragma warning disable 1875  // offsetof applied to non-POD (Plain Old Data) types is nonstandard
  22 #  pragma warning disable 2196  // warning #2196: routine is both "inline" and "noinline"
  23 #elif defined(_MSC_VER)
  24 #  pragma warning(push)
  25 #  pragma warning(disable: 4100) // warning C4100: Unreferenced formal parameter
  26 #  pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
  27 #  pragma warning(disable: 4512) // warning C4512: Assignment operator was implicitly defined as deleted
  28 #  pragma warning(disable: 4800) // warning C4800: 'int': forcing value to bool 'true' or 'false' (performance warning)
  29 #  pragma warning(disable: 4996) // warning C4996: The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name
  30 #  pragma warning(disable: 4702) // warning C4702: unreachable code
  31 #  pragma warning(disable: 4522) // warning C4522: multiple assignment operators specified
  32 #elif defined(__GNUG__) && !defined(__clang__)
  33 #  pragma GCC diagnostic push
  34 #  pragma GCC diagnostic ignored "-Wunused-but-set-parameter"
  35 #  pragma GCC diagnostic ignored "-Wunused-but-set-variable"
  36 #  pragma GCC diagnostic ignored "-Wmissing-field-initializers"
  37 #  pragma GCC diagnostic ignored "-Wstrict-aliasing"
  38 #  pragma GCC diagnostic ignored "-Wattributes"
  39 #  if __GNUC__ >= 7
  40 #    pragma GCC diagnostic ignored "-Wnoexcept-type"
  41 #  endif
  42 #endif
  43
  44 #include "attr.h"
  45 #include "options.h"
  46 #include "detail/class.h"
  47 #include "detail/init.h"
  48
  49 #if defined(__GNUG__) && !defined(__clang__)
  50 #  include <cxxabi.h>
  51 #endif
  52
  53 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
  54
  55 /// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object
  56 class cpp_function : public function {
  57 public:
  58     cpp_function() { }
  59     cpp_function(std::nullptr_t) { }
  60
  61     /// Construct a cpp_function from a vanilla function pointer
  62     template <typename Return, typename... Args, typename... Extra>
  63     cpp_function(Return (*f)(Args...), const Extra&... extra) {
  64         initialize(f, f, extra...);
  65     }
  66
  67     /// Construct a cpp_function from a lambda function (possibly with internal state)
  68     template <typename Func, typename... Extra,
  69               typename = detail::enable_if_t<detail::is_lambda<Func>::value>>
  70     cpp_function(Func &&f, const Extra&... extra) {
  71         initialize(std::forward<Func>(f),
  72                    (detail::function_signature_t<Func> *) nullptr, extra...);
  73     }
  74
  75     /// Construct a cpp_function from a class method (non-const)
  76     template <typename Return, typename Class, typename... Arg, typename... Extra>
  77     cpp_function(Return (Class::*f)(Arg...), const Extra&... extra) {
  78         initialize([f](Class *c, Arg... args) -> Return { return (c->*f)(args...); },
  79                    (Return (*) (Class *, Arg...)) nullptr, extra...);
  80     }
  81
  82     /// Construct a cpp_function from a class method (const)
  83     template <typename Return, typename Class, typename... Arg, typename... Extra>
  84     cpp_function(Return (Class::*f)(Arg...) const, const Extra&... extra) {
  85         initialize([f](const Class *c, Arg... args) -> Return { return (c->*f)(args...); },
  86                    (Return (*)(const Class *, Arg ...)) nullptr, extra...);
  87     }
  88
  89     /// Return the function name
  90     object name() const { return attr("__name__"); }
  91
  92 protected:
  93     /// Space optimization: don't inline this frequently instantiated fragment
  94     PYBIND11_NOINLINE detail::function_record *make_function_record() {
  95         return new detail::function_record();
  96     }
  97
  98     /// Special internal constructor for functors, lambda functions, etc.
  99     template <typename Func, typename Return, typename... Args, typename... Extra>
 100     void initialize(Func &&f, Return (*)(Args...), const Extra&... extra) {
 101         using namespace detail;
 102         struct capture { remove_reference_t<Func> f; };
 103
 104         /* Store the function including any extra state it might have (e.g. a lambda capture object) */
 105         auto rec = make_function_record();
 106
 107         /* Store the capture object directly in the function record if there is enough space */
 108         if (sizeof(capture) <= sizeof(rec->data)) {
 109             /* Without these pragmas, GCC warns that there might not be
 110                enough space to use the placement new operator. However, the
 111                'if' statement above ensures that this is the case. */
 112 #if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
 113 #  pragma GCC diagnostic push
 114 #  pragma GCC diagnostic ignored "-Wplacement-new"
 115 #endif
 116             new ((capture *) &rec->data) capture { std::forward<Func>(f) };
 117 #if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
 118 #  pragma GCC diagnostic pop
 119 #endif
 120             if (!std::is_trivially_destructible<Func>::value)
 121                 rec->free_data = [](function_record *r) { ((capture *) &r->data)->~capture(); };
 122         } else {
 123             rec->data[0] = new capture { std::forward<Func>(f) };
 124             rec->free_data = [](function_record *r) { delete ((capture *) r->data[0]); };
 125         }
 126
 127         /* Type casters for the function arguments and return value */
 128         using cast_in = argument_loader<Args...>;
 129         using cast_out = make_caster<
 130             conditional_t<std::is_void<Return>::value, void_type, Return>
 131         >;
 132
 133         static_assert(expected_num_args<Extra...>(sizeof...(Args), cast_in::has_args, cast_in::has_kwargs),
 134                       "The number of argument annotations does not match the number of function arguments");
 135
 136         /* Dispatch code which converts function arguments and performs the actual function call */
 137         rec->impl = [](function_call &call) -> handle {
 138             cast_in args_converter;
 139
 140             /* Try to cast the function arguments into the C++ domain */
 141             if (!args_converter.load_args(call))
 142                 return PYBIND11_TRY_NEXT_OVERLOAD;
 143
 144             /* Invoke call policy pre-call hook */
 145             process_attributes<Extra...>::precall(call);
 146
 147             /* Get a pointer to the capture object */
 148             auto data = (sizeof(capture) <= sizeof(call.func.data)
 149                          ? &call.func.data : call.func.data[0]);
 150             capture *cap = const_cast<capture *>(reinterpret_cast<const capture *>(data));
 151
 152             /* Override policy for rvalues -- usually to enforce rvp::move on an rvalue */
 153             return_value_policy policy = return_value_policy_override<Return>::policy(call.func.policy);
 154
 155             /* Function scope guard -- defaults to the compile-to-nothing `void_type` */
 156             using Guard = extract_guard_t<Extra...>;
 157
 158             /* Perform the function call */
 159             handle result = cast_out::cast(
 160                 std::move(args_converter).template call<Return, Guard>(cap->f), policy, call.parent);
 161
 162             /* Invoke call policy post-call hook */
 163             process_attributes<Extra...>::postcall(call, result);
 164
 165             return result;
 166         };
 167
 168         /* Process any user-provided function attributes */
 169         process_attributes<Extra...>::init(extra..., rec);
 170
 171         /* Generate a readable signature describing the function's arguments and return value types */
 172         static constexpr auto signature = _("(") + cast_in::arg_names + _(") -> ") + cast_out::name;
 173         PYBIND11_DESCR_CONSTEXPR auto types = decltype(signature)::types();
 174
 175         /* Register the function with Python from generic (non-templated) code */
 176         initialize_generic(rec, signature.text, types.data(), sizeof...(Args));
 177
 178         if (cast_in::has_args) rec->has_args = true;
 179         if (cast_in::has_kwargs) rec->has_kwargs = true;
 180
 181         /* Stash some additional information used by an important optimization in 'functional.h' */
 182         using FunctionType = Return (*)(Args...);
 183         constexpr bool is_function_ptr =
 184             std::is_convertible<Func, FunctionType>::value &&
 185             sizeof(capture) == sizeof(void *);
 186         if (is_function_ptr) {
 187             rec->is_stateless = true;
 188             rec->data[1] = const_cast<void *>(reinterpret_cast<const void *>(&typeid(FunctionType)));
 189         }
 190     }
 191
 192     /// Register a function call with Python (generic non-templated code goes here)
 193     void initialize_generic(detail::function_record *rec, const char *text,
 194                             const std::type_info *const *types, size_t args) {
 195
 196         /* Create copies of all referenced C-style strings */
 197         rec->name = strdup(rec->name ? rec->name : "");
 198         if (rec->doc) rec->doc = strdup(rec->doc);
 199         for (auto &a: rec->args) {
 200             if (a.name)
 201                 a.name = strdup(a.name);
 202             if (a.descr)
 203                 a.descr = strdup(a.descr);
 204             else if (a.value)
 205                 a.descr = strdup(a.value.attr("__repr__")().cast<std::string>().c_str());
 206         }
 207
 208         rec->is_constructor = !strcmp(rec->name, "__init__") || !strcmp(rec->name, "__setstate__");
 209
 210 #if !defined(NDEBUG) && !defined(PYBIND11_DISABLE_NEW_STYLE_INIT_WARNING)
 211         if (rec->is_constructor && !rec->is_new_style_constructor) {
 212             const auto class_name = std::string(((PyTypeObject *) rec->scope.ptr())->tp_name);
 213             const auto func_name = std::string(rec->name);
 214             PyErr_WarnEx(
 215                 PyExc_FutureWarning,
 216                 ("pybind11-bound class '" + class_name + "' is using an old-style "
 217                  "placement-new '" + func_name + "' which has been deprecated. See "
 218                  "the upgrade guide in pybind11's docs. This message is only visible "
 219                  "when compiled in debug mode.").c_str(), 0
 220             );
 221         }
 222 #endif
 223
 224         /* Generate a proper function signature */
 225         std::string signature;
 226         size_t type_index = 0, arg_index = 0;
 227         for (auto *pc = text; *pc != '\0'; ++pc) {
 228             const auto c = *pc;
 229
 230             if (c == '{') {
 231                 // Write arg name for everything except *args and **kwargs.
 232                 if (*(pc + 1) == '*')
 233                     continue;
 234
 235                 if (arg_index < rec->args.size() && rec->args[arg_index].name) {
 236                     signature += rec->args[arg_index].name;
 237                 } else if (arg_index == 0 && rec->is_method) {
 238                     signature += "self";
 239                 } else {
 240                     signature += "arg" + std::to_string(arg_index - (rec->is_method ? 1 : 0));
 241                 }
 242                 signature += ": ";
 243             } else if (c == '}') {
 244                 // Write default value if available.
 245                 if (arg_index < rec->args.size() && rec->args[arg_index].descr) {
 246                     signature += " = ";
 247                     signature += rec->args[arg_index].descr;
 248                 }
 249                 arg_index++;
 250             } else if (c == '%') {
 251                 const std::type_info *t = types[type_index++];
 252                 if (!t)
 253                     pybind11_fail("Internal error while parsing type signature (1)");
 254                 if (auto tinfo = detail::get_type_info(*t)) {
 255                     handle th((PyObject *) tinfo->type);
 256                     signature +=
 257                         th.attr("__module__").cast<std::string>() + "." +
 258                         th.attr("__qualname__").cast<std::string>(); // Python 3.3+, but we backport it to earlier versions
 259                 } else if (rec->is_new_style_constructor && arg_index == 0) {
 260                     // A new-style `__init__` takes `self` as `value_and_holder`.
 261                     // Rewrite it to the proper class type.
 262                     signature +=
 263                         rec->scope.attr("__module__").cast<std::string>() + "." +
 264                         rec->scope.attr("__qualname__").cast<std::string>();
 265                 } else {
 266                     std::string tname(t->name());
 267                     detail::clean_type_id(tname);
 268                     signature += tname;
 269                 }
 270             } else {
 271                 signature += c;
 272             }
 273         }
 274         if (arg_index != args || types[type_index] != nullptr)
 275             pybind11_fail("Internal error while parsing type signature (2)");
 276
 277 #if PY_MAJOR_VERSION < 3
 278         if (strcmp(rec->name, "__next__") == 0) {
 279             std::free(rec->name);
 280             rec->name = strdup("next");
 281         } else if (strcmp(rec->name, "__bool__") == 0) {
 282             std::free(rec->name);
 283             rec->name = strdup("__nonzero__");
 284         }
 285 #endif
 286         rec->signature = strdup(signature.c_str());
 287         rec->args.shrink_to_fit();
 288         rec->nargs = (std::uint16_t) args;
 289
 290         if (rec->sibling && PYBIND11_INSTANCE_METHOD_CHECK(rec->sibling.ptr()))
 291             rec->sibling = PYBIND11_INSTANCE_METHOD_GET_FUNCTION(rec->sibling.ptr());
 292
 293         detail::function_record *chain = nullptr, *chain_start = rec;
 294         if (rec->sibling) {
 295             if (PyCFunction_Check(rec->sibling.ptr())) {
 296                 auto rec_capsule = reinterpret_borrow<capsule>(PyCFunction_GET_SELF(rec->sibling.ptr()));
 297                 chain = (detail::function_record *) rec_capsule;
 298                 /* Never append a method to an overload chain of a parent class;
 299                    instead, hide the parent's overloads in this case */
 300                 if (!chain->scope.is(rec->scope))
 301                     chain = nullptr;
 302             }
 303             // Don't trigger for things like the default __init__, which are wrapper_descriptors that we are intentionally replacing
 304             else if (!rec->sibling.is_none() && rec->name[0] != '_')
 305                 pybind11_fail("Cannot overload existing non-function object \"" + std::string(rec->name) +
 306                         "\" with a function of the same name");
 307         }
 308
 309         if (!chain) {
 310             /* No existing overload was found, create a new function object */
 311             rec->def = new PyMethodDef();
 312             std::memset(rec->def, 0, sizeof(PyMethodDef));
 313             rec->def->ml_name = rec->name;
 314             rec->def->ml_meth = reinterpret_cast<PyCFunction>(reinterpret_cast<void (*) (void)>(*dispatcher));
 315             rec->def->ml_flags = METH_VARARGS | METH_KEYWORDS;
 316
 317             capsule rec_capsule(rec, [](void *ptr) {
 318                 destruct((detail::function_record *) ptr);
 319             });
 320
 321             object scope_module;
 322             if (rec->scope) {
 323                 if (hasattr(rec->scope, "__module__")) {
 324                     scope_module = rec->scope.attr("__module__");
 325                 } else if (hasattr(rec->scope, "__name__")) {
 326                     scope_module = rec->scope.attr("__name__");
 327                 }
 328             }
 329
 330             m_ptr = PyCFunction_NewEx(rec->def, rec_capsule.ptr(), scope_module.ptr());
 331             if (!m_ptr)
 332                 pybind11_fail("cpp_function::cpp_function(): Could not allocate function object");
 333         } else {
 334             /* Append at the end of the overload chain */
 335             m_ptr = rec->sibling.ptr();
 336             inc_ref();
 337             chain_start = chain;
 338             if (chain->is_method != rec->is_method)
 339                 pybind11_fail("overloading a method with both static and instance methods is not supported; "
 340                     #if defined(NDEBUG)
 341                         "compile in debug mode for more details"
 342                     #else
 343                         "error while attempting to bind " + std::string(rec->is_method ? "instance" : "static") + " method " +
 344                         std::string(pybind11::str(rec->scope.attr("__name__"))) + "." + std::string(rec->name) + signature
 345                     #endif
 346                 );
 347             while (chain->next)
 348                 chain = chain->next;
 349             chain->next = rec;
 350         }
 351
 352         std::string signatures;
 353         int index = 0;
 354         /* Create a nice pydoc rec including all signatures and
 355            docstrings of the functions in the overload chain */
 356         if (chain && options::show_function_signatures()) {
 357             // First a generic signature
 358             signatures += rec->name;
 359             signatures += "(*args, **kwargs)\n";
 360             signatures += "Overloaded function.\n\n";
 361         }
 362         // Then specific overload signatures
 363         bool first_user_def = true;
 364         for (auto it = chain_start; it != nullptr; it = it->next) {
 365             if (options::show_function_signatures()) {
 366                 if (index > 0) signatures += "\n";
 367                 if (chain)
 368                     signatures += std::to_string(++index) + ". ";
 369                 signatures += rec->name;
 370                 signatures += it->signature;
 371                 signatures += "\n";
 372             }
 373             if (it->doc && strlen(it->doc) > 0 && options::show_user_defined_docstrings()) {
 374                 // If we're appending another docstring, and aren't printing function signatures, we
 375                 // need to append a newline first:
 376                 if (!options::show_function_signatures()) {
 377                     if (first_user_def) first_user_def = false;
 378                     else signatures += "\n";
 379                 }
 380                 if (options::show_function_signatures()) signatures += "\n";
 381                 signatures += it->doc;
 382                 if (options::show_function_signatures()) signatures += "\n";
 383             }
 384         }
 385
 386         /* Install docstring */
 387         PyCFunctionObject *func = (PyCFunctionObject *) m_ptr;
 388         if (func->m_ml->ml_doc)
 389             std::free(const_cast<char *>(func->m_ml->ml_doc));
 390         func->m_ml->ml_doc = strdup(signatures.c_str());
 391
 392         if (rec->is_method) {
 393             m_ptr = PYBIND11_INSTANCE_METHOD_NEW(m_ptr, rec->scope.ptr());
 394             if (!m_ptr)
 395                 pybind11_fail("cpp_function::cpp_function(): Could not allocate instance method object");
 396             Py_DECREF(func);
 397         }
 398     }
 399
 400     /// When a cpp_function is GCed, release any memory allocated by pybind11
 401     static void destruct(detail::function_record *rec) {
 402         while (rec) {
 403             detail::function_record *next = rec->next;
 404             if (rec->free_data)
 405                 rec->free_data(rec);
 406             std::free((char *) rec->name);
 407             std::free((char *) rec->doc);
 408             std::free((char *) rec->signature);
 409             for (auto &arg: rec->args) {
 410                 std::free(const_cast<char *>(arg.name));
 411                 std::free(const_cast<char *>(arg.descr));
 412                 arg.value.dec_ref();
 413             }
 414             if (rec->def) {
 415                 std::free(const_cast<char *>(rec->def->ml_doc));
 416                 delete rec->def;
 417             }
 418             delete rec;
 419             rec = next;
 420         }
 421     }
 422
 423     /// Main dispatch logic for calls to functions bound using pybind11
 424     static PyObject *dispatcher(PyObject *self, PyObject *args_in, PyObject *kwargs_in) {
 425         using namespace detail;
 426
 427         /* Iterator over the list of potentially admissible overloads */
 428         const function_record *overloads = (function_record *) PyCapsule_GetPointer(self, nullptr),
 429                               *it = overloads;
 430
 431         /* Need to know how many arguments + keyword arguments there are to pick the right overload */
 432         const size_t n_args_in = (size_t) PyTuple_GET_SIZE(args_in);
 433
 434         handle parent = n_args_in > 0 ? PyTuple_GET_ITEM(args_in, 0) : nullptr,
 435                result = PYBIND11_TRY_NEXT_OVERLOAD;
 436
 437         auto self_value_and_holder = value_and_holder();
 438         if (overloads->is_constructor) {
 439             const auto tinfo = get_type_info((PyTypeObject *) overloads->scope.ptr());
 440             const auto pi = reinterpret_cast<instance *>(parent.ptr());
 441             self_value_and_holder = pi->get_value_and_holder(tinfo, false);
 442
 443             if (!self_value_and_holder.type || !self_value_and_holder.inst) {
 444                 PyErr_SetString(PyExc_TypeError, "__init__(self, ...) called with invalid `self` argument");
 445                 return nullptr;
 446             }
 447
 448             // If this value is already registered it must mean __init__ is invoked multiple times;
 449             // we really can't support that in C++, so just ignore the second __init__.
 450             if (self_value_and_holder.instance_registered())
 451                 return none().release().ptr();
 452         }
 453
 454         try {
 455             // We do this in two passes: in the first pass, we load arguments with `convert=false`;
 456             // in the second, we allow conversion (except for arguments with an explicit
 457             // py::arg().noconvert()).  This lets us prefer calls without conversion, with
 458             // conversion as a fallback.
 459             std::vector<function_call> second_pass;
 460
 461             // However, if there are no overloads, we can just skip the no-convert pass entirely
 462             const bool overloaded = it != nullptr && it->next != nullptr;
 463
 464             for (; it != nullptr; it = it->next) {
 465
 466                 /* For each overload:
 467                    1. Copy all positional arguments we were given, also checking to make sure that
 468                       named positional arguments weren't *also* specified via kwarg.
 469                    2. If we weren't given enough, try to make up the omitted ones by checking
 470                       whether they were provided by a kwarg matching the `py::arg("name")` name.  If
 471                       so, use it (and remove it from kwargs; if not, see if the function binding
 472                       provided a default that we can use.
 473                    3. Ensure that either all keyword arguments were "consumed", or that the function
 474                       takes a kwargs argument to accept unconsumed kwargs.
 475                    4. Any positional arguments still left get put into a tuple (for args), and any
 476                       leftover kwargs get put into a dict.
 477                    5. Pack everything into a vector; if we have py::args or py::kwargs, they are an
 478                       extra tuple or dict at the end of the positional arguments.
 479                    6. Call the function call dispatcher (function_record::impl)
 480
 481                    If one of these fail, move on to the next overload and keep trying until we get a
 482                    result other than PYBIND11_TRY_NEXT_OVERLOAD.
 483                  */
 484
 485                 const function_record &func = *it;
 486                 size_t pos_args = func.nargs;    // Number of positional arguments that we need
 487                 if (func.has_args) --pos_args;   // (but don't count py::args
 488                 if (func.has_kwargs) --pos_args; //  or py::kwargs)
 489
 490                 if (!func.has_args && n_args_in > pos_args)
 491                     continue; // Too many arguments for this overload
 492
 493                 if (n_args_in < pos_args && func.args.size() < pos_args)
 494                     continue; // Not enough arguments given, and not enough defaults to fill in the blanks
 495
 496                 function_call call(func, parent);
 497
 498                 size_t args_to_copy = (std::min)(pos_args, n_args_in); // Protect std::min with parentheses
 499                 size_t args_copied = 0;
 500
 501                 // 0. Inject new-style `self` argument
 502                 if (func.is_new_style_constructor) {
 503                     // The `value` may have been preallocated by an old-style `__init__`
 504                     // if it was a preceding candidate for overload resolution.
 505                     if (self_value_and_holder)
 506                         self_value_and_holder.type->dealloc(self_value_and_holder);
 507
 508                     call.init_self = PyTuple_GET_ITEM(args_in, 0);
 509                     call.args.push_back(reinterpret_cast<PyObject *>(&self_value_and_holder));
 510                     call.args_convert.push_back(false);
 511                     ++args_copied;
 512                 }
 513
 514                 // 1. Copy any position arguments given.
 515                 bool bad_arg = false;
 516                 for (; args_copied < args_to_copy; ++args_copied) {
 517                     const argument_record *arg_rec = args_copied < func.args.size() ? &func.args[args_copied] : nullptr;
 518                     if (kwargs_in && arg_rec && arg_rec->name && PyDict_GetItemString(kwargs_in, arg_rec->name)) {
 519                         bad_arg = true;
 520                         break;
 521                     }
 522
 523                     handle arg(PyTuple_GET_ITEM(args_in, args_copied));
 524                     if (arg_rec && !arg_rec->none && arg.is_none()) {
 525                         bad_arg = true;
 526                         break;
 527                     }
 528                     call.args.push_back(arg);
 529                     call.args_convert.push_back(arg_rec ? arg_rec->convert : true);
 530                 }
 531                 if (bad_arg)
 532                     continue; // Maybe it was meant for another overload (Issue #688)
 533
 534                 // We'll need to copy this if we steal some kwargs for defaults
 535                 dict kwargs = reinterpret_borrow<dict>(kwargs_in);
 536
 537                 // 2. Check kwargs and, failing that, defaults that may help complete the list
 538                 if (args_copied < pos_args) {
 539                     bool copied_kwargs = false;
 540
 541                     for (; args_copied < pos_args; ++args_copied) {
 542                         const auto &arg = func.args[args_copied];
 543
 544                         handle value;
 545                         if (kwargs_in && arg.name)
 546                             value = PyDict_GetItemString(kwargs.ptr(), arg.name);
 547
 548                         if (value) {
 549                             // Consume a kwargs value
 550                             if (!copied_kwargs) {
 551                                 kwargs = reinterpret_steal<dict>(PyDict_Copy(kwargs.ptr()));
 552                                 copied_kwargs = true;
 553                             }
 554                             PyDict_DelItemString(kwargs.ptr(), arg.name);
 555                         } else if (arg.value) {
 556                             value = arg.value;
 557                         }
 558
 559                         if (value) {
 560                             call.args.push_back(value);
 561                             call.args_convert.push_back(arg.convert);
 562                         }
 563                         else
 564                             break;
 565                     }
 566
 567                     if (args_copied < pos_args)
 568                         continue; // Not enough arguments, defaults, or kwargs to fill the positional arguments
 569                 }
 570
 571                 // 3. Check everything was consumed (unless we have a kwargs arg)
 572                 if (kwargs && kwargs.size() > 0 && !func.has_kwargs)
 573                     continue; // Unconsumed kwargs, but no py::kwargs argument to accept them
 574
 575                 // 4a. If we have a py::args argument, create a new tuple with leftovers
 576                 if (func.has_args) {
 577                     tuple extra_args;
 578                     if (args_to_copy == 0) {
 579                         // We didn't copy out any position arguments from the args_in tuple, so we
 580                         // can reuse it directly without copying:
 581                         extra_args = reinterpret_borrow<tuple>(args_in);
 582                     } else if (args_copied >= n_args_in) {
 583                         extra_args = tuple(0);
 584                     } else {
 585                         size_t args_size = n_args_in - args_copied;
 586                         extra_args = tuple(args_size);
 587                         for (size_t i = 0; i < args_size; ++i) {
 588                             extra_args[i] = PyTuple_GET_ITEM(args_in, args_copied + i);
 589                         }
 590                     }
 591                     call.args.push_back(extra_args);
 592                     call.args_convert.push_back(false);
 593                     call.args_ref = std::move(extra_args);
 594                 }
 595
 596                 // 4b. If we have a py::kwargs, pass on any remaining kwargs
 597                 if (func.has_kwargs) {
 598                     if (!kwargs.ptr())
 599                         kwargs = dict(); // If we didn't get one, send an empty one
 600                     call.args.push_back(kwargs);
 601                     call.args_convert.push_back(false);
 602                     call.kwargs_ref = std::move(kwargs);
 603                 }
 604
 605                 // 5. Put everything in a vector.  Not technically step 5, we've been building it
 606                 // in `call.args` all along.
 607                 #if !defined(NDEBUG)
 608                 if (call.args.size() != func.nargs || call.args_convert.size() != func.nargs)
 609                     pybind11_fail("Internal error: function call dispatcher inserted wrong number of arguments!");
 610                 #endif
 611
 612                 std::vector<bool> second_pass_convert;
 613                 if (overloaded) {
 614                     // We're in the first no-convert pass, so swap out the conversion flags for a
 615                     // set of all-false flags.  If the call fails, we'll swap the flags back in for
 616                     // the conversion-allowed call below.
 617                     second_pass_convert.resize(func.nargs, false);
 618                     call.args_convert.swap(second_pass_convert);
 619                 }
 620
 621                 // 6. Call the function.
 622                 try {
 623                     loader_life_support guard{};
 624                     result = func.impl(call);
 625                 } catch (reference_cast_error &) {
 626                     result = PYBIND11_TRY_NEXT_OVERLOAD;
 627                 }
 628
 629                 if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD)
 630                     break;
 631
 632                 if (overloaded) {
 633                     // The (overloaded) call failed; if the call has at least one argument that
 634                     // permits conversion (i.e. it hasn't been explicitly specified `.noconvert()`)
 635                     // then add this call to the list of second pass overloads to try.
 636                     for (size_t i = func.is_method ? 1 : 0; i < pos_args; i++) {
 637                         if (second_pass_convert[i]) {
 638                             // Found one: swap the converting flags back in and store the call for
 639                             // the second pass.
 640                             call.args_convert.swap(second_pass_convert);
 641                             second_pass.push_back(std::move(call));
 642                             break;
 643                         }
 644                     }
 645                 }
 646             }
 647
 648             if (overloaded && !second_pass.empty() && result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) {
 649                 // The no-conversion pass finished without success, try again with conversion allowed
 650                 for (auto &call : second_pass) {
 651                     try {
 652                         loader_life_support guard{};
 653                         result = call.func.impl(call);
 654                     } catch (reference_cast_error &) {
 655                         result = PYBIND11_TRY_NEXT_OVERLOAD;
 656                     }
 657
 658                     if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD) {
 659                         // The error reporting logic below expects 'it' to be valid, as it would be
 660                         // if we'd encountered this failure in the first-pass loop.
 661                         if (!result)
 662                             it = &call.func;
 663                         break;
 664                     }
 665                 }
 666             }
 667         } catch (error_already_set &e) {
 668             e.restore();
 669             return nullptr;
 670 #if defined(__GNUG__) && !defined(__clang__)
 671         } catch ( abi::__forced_unwind& ) {
 672             throw;
 673 #endif
 674         } catch (...) {
 675             /* When an exception is caught, give each registered exception
 676                translator a chance to translate it to a Python exception
 677                in reverse order of registration.
 678
 679                A translator may choose to do one of the following:
 680
 681                 - catch the exception and call PyErr_SetString or PyErr_SetObject
 682                   to set a standard (or custom) Python exception, or
 683                 - do nothing and let the exception fall through to the next translator, or
 684                 - delegate translation to the next translator by throwing a new type of exception. */
 685
 686             auto last_exception = std::current_exception();
 687             auto &registered_exception_translators = get_internals().registered_exception_translators;
 688             for (auto& translator : registered_exception_translators) {
 689                 try {
 690                     translator(last_exception);
 691                 } catch (...) {
 692                     last_exception = std::current_exception();
 693                     continue;
 694                 }
 695                 return nullptr;
 696             }
 697             PyErr_SetString(PyExc_SystemError, "Exception escaped from default exception translator!");
 698             return nullptr;
 699         }
 700
 701         auto append_note_if_missing_header_is_suspected = [](std::string &msg) {
 702             if (msg.find("std::") != std::string::npos) {
 703                 msg += "\n\n"
 704                        "Did you forget to `#include <pybind11/stl.h>`? Or <pybind11/complex.h>,\n"
 705                        "<pybind11/functional.h>, <pybind11/chrono.h>, etc. Some automatic\n"
 706                        "conversions are optional and require extra headers to be included\n"
 707                        "when compiling your pybind11 module.";
 708             }
 709         };
 710
 711         if (result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) {
 712             if (overloads->is_operator)
 713                 return handle(Py_NotImplemented).inc_ref().ptr();
 714
 715             std::string msg = std::string(overloads->name) + "(): incompatible " +
 716                 std::string(overloads->is_constructor ? "constructor" : "function") +
 717                 " arguments. The following argument types are supported:\n";
 718
 719             int ctr = 0;
 720             for (const function_record *it2 = overloads; it2 != nullptr; it2 = it2->next) {
 721                 msg += "    "+ std::to_string(++ctr) + ". ";
 722
 723                 bool wrote_sig = false;
 724                 if (overloads->is_constructor) {
 725                     // For a constructor, rewrite `(self: Object, arg0, ...) -> NoneType` as `Object(arg0, ...)`
 726                     std::string sig = it2->signature;
 727                     size_t start = sig.find('(') + 7; // skip "(self: "
 728                     if (start < sig.size()) {
 729                         // End at the , for the next argument
 730                         size_t end = sig.find(", "), next = end + 2;
 731                         size_t ret = sig.rfind(" -> ");
 732                         // Or the ), if there is no comma:
 733                         if (end >= sig.size()) next = end = sig.find(')');
 734                         if (start < end && next < sig.size()) {
 735                             msg.append(sig, start, end - start);
 736                             msg += '(';
 737                             msg.append(sig, next, ret - next);
 738                             wrote_sig = true;
 739                         }
 740                     }
 741                 }
 742                 if (!wrote_sig) msg += it2->signature;
 743
 744                 msg += "\n";
 745             }
 746             msg += "\nInvoked with: ";
 747             auto args_ = reinterpret_borrow<tuple>(args_in);
 748             bool some_args = false;
 749             for (size_t ti = overloads->is_constructor ? 1 : 0; ti < args_.size(); ++ti) {
 750                 if (!some_args) some_args = true;
 751                 else msg += ", ";
 752                 msg += pybind11::repr(args_[ti]);
 753             }
 754             if (kwargs_in) {
 755                 auto kwargs = reinterpret_borrow<dict>(kwargs_in);
 756                 if (kwargs.size() > 0) {
 757                     if (some_args) msg += "; ";
 758                     msg += "kwargs: ";
 759                     bool first = true;
 760                     for (auto kwarg : kwargs) {
 761                         if (first) first = false;
 762                         else msg += ", ";
 763                         msg += pybind11::str("{}={!r}").format(kwarg.first, kwarg.second);
 764                     }
 765                 }
 766             }
 767
 768             append_note_if_missing_header_is_suspected(msg);
 769             PyErr_SetString(PyExc_TypeError, msg.c_str());
 770             return nullptr;
 771         } else if (!result) {
 772             std::string msg = "Unable to convert function return value to a "
 773                               "Python type! The signature was\n\t";
 774             msg += it->signature;
 775             append_note_if_missing_header_is_suspected(msg);
 776             PyErr_SetString(PyExc_TypeError, msg.c_str());
 777             return nullptr;
 778         } else {
 779             if (overloads->is_constructor && !self_value_and_holder.holder_constructed()) {
 780                 auto *pi = reinterpret_cast<instance *>(parent.ptr());
 781                 self_value_and_holder.type->init_instance(pi, nullptr);
 782             }
 783             return result.ptr();
 784         }
 785     }
 786 };
 787
 788 /// Wrapper for Python extension modules
 789 class module : public object {
 790 public:
 791     PYBIND11_OBJECT_DEFAULT(module, object, PyModule_Check)
 792
 793     /// Create a new top-level Python module with the given name and docstring
 794     explicit module(const char *name, const char *doc = nullptr) {
 795         if (!options::show_user_defined_docstrings()) doc = nullptr;
 796 #if PY_MAJOR_VERSION >= 3
 797         PyModuleDef *def = new PyModuleDef();
 798         std::memset(def, 0, sizeof(PyModuleDef));
 799         def->m_name = name;
 800         def->m_doc = doc;
 801         def->m_size = -1;
 802         Py_INCREF(def);
 803         m_ptr = PyModule_Create(def);
 804 #else
 805         m_ptr = Py_InitModule3(name, nullptr, doc);
 806 #endif
 807         if (m_ptr == nullptr)
 808             pybind11_fail("Internal error in module::module()");
 809         inc_ref();
 810     }
 811
 812     /** \rst
 813         Create Python binding for a new function within the module scope. ``Func``
 814         can be a plain C++ function, a function pointer, or a lambda function. For
 815         details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
 816     \endrst */
 817     template <typename Func, typename... Extra>
 818     module &def(const char *name_, Func &&f, const Extra& ... extra) {
 819         cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
 820                           sibling(getattr(*this, name_, none())), extra...);
 821         // NB: allow overwriting here because cpp_function sets up a chain with the intention of
 822         // overwriting (and has already checked internally that it isn't overwriting non-functions).
 823         add_object(name_, func, true /* overwrite */);
 824         return *this;
 825     }
 826
 827     /** \rst
 828         Create and return a new Python submodule with the given name and docstring.
 829         This also works recursively, i.e.
 830
 831         .. code-block:: cpp
 832
 833             py::module m("example", "pybind11 example plugin");
 834             py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
 835             py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
 836     \endrst */
 837     module def_submodule(const char *name, const char *doc = nullptr) {
 838         std::string full_name = std::string(PyModule_GetName(m_ptr))
 839             + std::string(".") + std::string(name);
 840         auto result = reinterpret_borrow<module>(PyImport_AddModule(full_name.c_str()));
 841         if (doc && options::show_user_defined_docstrings())
 842             result.attr("__doc__") = pybind11::str(doc);
 843         attr(name) = result;
 844         return result;
 845     }
 846
 847     /// Import and return a module or throws `error_already_set`.
 848     static module import(const char *name) {
 849         PyObject *obj = PyImport_ImportModule(name);
 850         if (!obj)
 851             throw error_already_set();
 852         return reinterpret_steal<module>(obj);
 853     }
 854
 855     /// Reload the module or throws `error_already_set`.
 856     void reload() {
 857         PyObject *obj = PyImport_ReloadModule(ptr());
 858         if (!obj)
 859             throw error_already_set();
 860         *this = reinterpret_steal<module>(obj);
 861     }
 862
 863     // Adds an object to the module using the given name.  Throws if an object with the given name
 864     // already exists.
 865     //
 866     // overwrite should almost always be false: attempting to overwrite objects that pybind11 has
 867     // established will, in most cases, break things.
 868     PYBIND11_NOINLINE void add_object(const char *name, handle obj, bool overwrite = false) {
 869         if (!overwrite && hasattr(*this, name))
 870             pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" +
 871                     std::string(name) + "\"");
 872
 873         PyModule_AddObject(ptr(), name, obj.inc_ref().ptr() /* steals a reference */);
 874     }
 875 };
 876
 877 /// \ingroup python_builtins
 878 /// Return a dictionary representing the global variables in the current execution frame,
 879 /// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded).
 880 inline dict globals() {
 881     PyObject *p = PyEval_GetGlobals();
 882     return reinterpret_borrow<dict>(p ? p : module::import("__main__").attr("__dict__").ptr());
 883 }
 884
 885 NAMESPACE_BEGIN(detail)
 886 /// Generic support for creating new Python heap types
 887 class generic_type : public object {
 888     template <typename...> friend class class_;
 889 public:
 890     PYBIND11_OBJECT_DEFAULT(generic_type, object, PyType_Check)
 891 protected:
 892     void initialize(const type_record &rec) {
 893         if (rec.scope && hasattr(rec.scope, rec.name))
 894             pybind11_fail("generic_type: cannot initialize type \"" + std::string(rec.name) +
 895                           "\": an object with that name is already defined");
 896
 897         if (rec.module_local ? get_local_type_info(*rec.type) : get_global_type_info(*rec.type))
 898             pybind11_fail("generic_type: type \"" + std::string(rec.name) +
 899                           "\" is already registered!");
 900
 901         m_ptr = make_new_python_type(rec);
 902
 903         /* Register supplemental type information in C++ dict */
 904         auto *tinfo = new detail::type_info();
 905         tinfo->type = (PyTypeObject *) m_ptr;
 906         tinfo->cpptype = rec.type;
 907         tinfo->type_size = rec.type_size;
 908         tinfo->type_align = rec.type_align;
 909         tinfo->operator_new = rec.operator_new;
 910         tinfo->holder_size_in_ptrs = size_in_ptrs(rec.holder_size);
 911         tinfo->init_instance = rec.init_instance;
 912         tinfo->dealloc = rec.dealloc;
 913         tinfo->simple_type = true;
 914         tinfo->simple_ancestors = true;
 915         tinfo->default_holder = rec.default_holder;
 916         tinfo->module_local = rec.module_local;
 917
 918         auto &internals = get_internals();
 919         auto tindex = std::type_index(*rec.type);
 920         tinfo->direct_conversions = &internals.direct_conversions[tindex];
 921         if (rec.module_local)
 922             registered_local_types_cpp()[tindex] = tinfo;
 923         else
 924             internals.registered_types_cpp[tindex] = tinfo;
 925         internals.registered_types_py[(PyTypeObject *) m_ptr] = { tinfo };
 926
 927         if (rec.bases.size() > 1 || rec.multiple_inheritance) {
 928             mark_parents_nonsimple(tinfo->type);
 929             tinfo->simple_ancestors = false;
 930         }
 931         else if (rec.bases.size() == 1) {
 932             auto parent_tinfo = get_type_info((PyTypeObject *) rec.bases[0].ptr());
 933             tinfo->simple_ancestors = parent_tinfo->simple_ancestors;
 934         }
 935
 936         if (rec.module_local) {
 937             // Stash the local typeinfo and loader so that external modules can access it.
 938             tinfo->module_local_load = &type_caster_generic::local_load;
 939             setattr(m_ptr, PYBIND11_MODULE_LOCAL_ID, capsule(tinfo));
 940         }
 941     }
 942
 943     /// Helper function which tags all parents of a type using mult. inheritance
 944     void mark_parents_nonsimple(PyTypeObject *value) {
 945         auto t = reinterpret_borrow<tuple>(value->tp_bases);
 946         for (handle h : t) {
 947             auto tinfo2 = get_type_info((PyTypeObject *) h.ptr());
 948             if (tinfo2)
 949                 tinfo2->simple_type = false;
 950             mark_parents_nonsimple((PyTypeObject *) h.ptr());
 951         }
 952     }
 953
 954     void install_buffer_funcs(
 955             buffer_info *(*get_buffer)(PyObject *, void *),
 956             void *get_buffer_data) {
 957         PyHeapTypeObject *type = (PyHeapTypeObject*) m_ptr;
 958         auto tinfo = detail::get_type_info(&type->ht_type);
 959
 960         if (!type->ht_type.tp_as_buffer)
 961             pybind11_fail(
 962                 "To be able to register buffer protocol support for the type '" +
 963                 std::string(tinfo->type->tp_name) +
 964                 "' the associated class<>(..) invocation must "
 965                 "include the pybind11::buffer_protocol() annotation!");
 966
 967         tinfo->get_buffer = get_buffer;
 968         tinfo->get_buffer_data = get_buffer_data;
 969     }
 970
 971     // rec_func must be set for either fget or fset.
 972     void def_property_static_impl(const char *name,
 973                                   handle fget, handle fset,
 974                                   detail::function_record *rec_func) {
 975         const auto is_static = rec_func && !(rec_func->is_method && rec_func->scope);
 976         const auto has_doc = rec_func && rec_func->doc && pybind11::options::show_user_defined_docstrings();
 977         auto property = handle((PyObject *) (is_static ? get_internals().static_property_type
 978                                                        : &PyProperty_Type));
 979         attr(name) = property(fget.ptr() ? fget : none(),
 980                               fset.ptr() ? fset : none(),
 981                               /*deleter*/none(),
 982                               pybind11::str(has_doc ? rec_func->doc : ""));
 983     }
 984 };
 985
 986 /// Set the pointer to operator new if it exists. The cast is needed because it can be overloaded.
 987 template <typename T, typename = void_t<decltype(static_cast<void *(*)(size_t)>(T::operator new))>>
 988 void set_operator_new(type_record *r) { r->operator_new = &T::operator new; }
 989
 990 template <typename> void set_operator_new(...) { }
 991
 992 template <typename T, typename SFINAE = void> struct has_operator_delete : std::false_type { };
 993 template <typename T> struct has_operator_delete<T, void_t<decltype(static_cast<void (*)(void *)>(T::operator delete))>>
 994     : std::true_type { };
 995 template <typename T, typename SFINAE = void> struct has_operator_delete_size : std::false_type { };
 996 template <typename T> struct has_operator_delete_size<T, void_t<decltype(static_cast<void (*)(void *, size_t)>(T::operator delete))>>
 997     : std::true_type { };
 998 /// Call class-specific delete if it exists or global otherwise. Can also be an overload set.
 999 template <typename T, enable_if_t<has_operator_delete<T>::value, int> = 0>
1000 void call_operator_delete(T *p, size_t, size_t) { T::operator delete(p); }
1001 template <typename T, enable_if_t<!has_operator_delete<T>::value && has_operator_delete_size<T>::value, int> = 0>
1002 void call_operator_delete(T *p, size_t s, size_t) { T::operator delete(p, s); }
1003
1004 inline void call_operator_delete(void *p, size_t s, size_t a) {
1005     (void)s; (void)a;
1006 #if defined(PYBIND11_CPP17)
1007     if (a > __STDCPP_DEFAULT_NEW_ALIGNMENT__)
1008         ::operator delete(p, s, std::align_val_t(a));
1009     else
1010         ::operator delete(p, s);
1011 #else
1012     ::operator delete(p);
1013 #endif
1014 }
1015
1016 NAMESPACE_END(detail)
1017
1018 /// Given a pointer to a member function, cast it to its `Derived` version.
1019 /// Forward everything else unchanged.
1020 template <typename /*Derived*/, typename F>
1021 auto method_adaptor(F &&f) -> decltype(std::forward<F>(f)) { return std::forward<F>(f); }
1022
1023 template <typename Derived, typename Return, typename Class, typename... Args>
1024 auto method_adaptor(Return (Class::*pmf)(Args...)) -> Return (Derived::*)(Args...) {
1025     static_assert(detail::is_accessible_base_of<Class, Derived>::value,
1026         "Cannot bind an inaccessible base class method; use a lambda definition instead");
1027     return pmf;
1028 }
1029
1030 template <typename Derived, typename Return, typename Class, typename... Args>
1031 auto method_adaptor(Return (Class::*pmf)(Args...) const) -> Return (Derived::*)(Args...) const {
1032     static_assert(detail::is_accessible_base_of<Class, Derived>::value,
1033         "Cannot bind an inaccessible base class method; use a lambda definition instead");
1034     return pmf;
1035 }
1036
1037 template <typename type_, typename... options>
1038 class class_ : public detail::generic_type {
1039     template <typename T> using is_holder = detail::is_holder_type<type_, T>;
1040     template <typename T> using is_subtype = detail::is_strict_base_of<type_, T>;
1041     template <typename T> using is_base = detail::is_strict_base_of<T, type_>;
1042     // struct instead of using here to help MSVC:
1043     template <typename T> struct is_valid_class_option :
1044         detail::any_of<is_holder<T>, is_subtype<T>, is_base<T>> {};
1045
1046 public:
1047     using type = type_;
1048     using type_alias = detail::exactly_one_t<is_subtype, void, options...>;
1049     constexpr static bool has_alias = !std::is_void<type_alias>::value;
1050     using holder_type = detail::exactly_one_t<is_holder, std::unique_ptr<type>, options...>;
1051
1052     static_assert(detail::all_of<is_valid_class_option<options>...>::value,
1053             "Unknown/invalid class_ template parameters provided");
1054
1055     static_assert(!has_alias || std::is_polymorphic<type>::value,
1056             "Cannot use an alias class with a non-polymorphic type");
1057
1058     PYBIND11_OBJECT(class_, generic_type, PyType_Check)
1059
1060     template <typename... Extra>
1061     class_(handle scope, const char *name, const Extra &... extra) {
1062         using namespace detail;
1063
1064         // MI can only be specified via class_ template options, not constructor parameters
1065         static_assert(
1066             none_of<is_pyobject<Extra>...>::value || // no base class arguments, or:
1067             (   constexpr_sum(is_pyobject<Extra>::value...) == 1 && // Exactly one base
1068                 constexpr_sum(is_base<options>::value...)   == 0 && // no template option bases
1069                 none_of<std::is_same<multiple_inheritance, Extra>...>::value), // no multiple_inheritance attr
1070             "Error: multiple inheritance bases must be specified via class_ template options");
1071
1072         type_record record;
1073         record.scope = scope;
1074         record.name = name;
1075         record.type = &typeid(type);
1076         record.type_size = sizeof(conditional_t<has_alias, type_alias, type>);
1077         record.type_align = alignof(conditional_t<has_alias, type_alias, type>&);
1078         record.holder_size = sizeof(holder_type);
1079         record.init_instance = init_instance;
1080         record.dealloc = dealloc;
1081         record.default_holder = detail::is_instantiation<std::unique_ptr, holder_type>::value;
1082
1083         set_operator_new<type>(&record);
1084
1085         /* Register base classes specified via template arguments to class_, if any */
1086         PYBIND11_EXPAND_SIDE_EFFECTS(add_base<options>(record));
1087
1088         /* Process optional arguments, if any */
1089         process_attributes<Extra...>::init(extra..., &record);
1090
1091         generic_type::initialize(record);
1092
1093         if (has_alias) {
1094             auto &instances = record.module_local ? registered_local_types_cpp() : get_internals().registered_types_cpp;
1095             instances[std::type_index(typeid(type_alias))] = instances[std::type_index(typeid(type))];
1096         }
1097     }
1098
1099     template <typename Base, detail::enable_if_t<is_base<Base>::value, int> = 0>
1100     static void add_base(detail::type_record &rec) {
1101         rec.add_base(typeid(Base), [](void *src) -> void * {
1102             return static_cast<Base *>(reinterpret_cast<type *>(src));
1103         });
1104     }
1105
1106     template <typename Base, detail::enable_if_t<!is_base<Base>::value, int> = 0>
1107     static void add_base(detail::type_record &) { }
1108
1109     template <typename Func, typename... Extra>
1110     class_ &def(const char *name_, Func&& f, const Extra&... extra) {
1111         cpp_function cf(method_adaptor<type>(std::forward<Func>(f)), name(name_), is_method(*this),
1112                         sibling(getattr(*this, name_, none())), extra...);
1113         attr(cf.name()) = cf;
1114         return *this;
1115     }
1116
1117     template <typename Func, typename... Extra> class_ &
1118     def_static(const char *name_, Func &&f, const Extra&... extra) {
1119         static_assert(!std::is_member_function_pointer<Func>::value,
1120                 "def_static(...) called with a non-static member function pointer");
1121         cpp_function cf(std::forward<Func>(f), name(name_), scope(*this),
1122                         sibling(getattr(*this, name_, none())), extra...);
1123         attr(cf.name()) = staticmethod(cf);
1124         return *this;
1125     }
1126
1127     template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
1128     class_ &def(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
1129         op.execute(*this, extra...);
1130         return *this;
1131     }
1132
1133     template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
1134     class_ & def_cast(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
1135         op.execute_cast(*this, extra...);
1136         return *this;
1137     }
1138
1139     template <typename... Args, typename... Extra>
1140     class_ &def(const detail::initimpl::constructor<Args...> &init, const Extra&... extra) {
1141         init.execute(*this, extra...);
1142         return *this;
1143     }
1144
1145     template <typename... Args, typename... Extra>
1146     class_ &def(const detail::initimpl::alias_constructor<Args...> &init, const Extra&... extra) {
1147         init.execute(*this, extra...);
1148         return *this;
1149     }
1150
1151     template <typename... Args, typename... Extra>
1152     class_ &def(detail::initimpl::factory<Args...> &&init, const Extra&... extra) {
1153         std::move(init).execute(*this, extra...);
1154         return *this;
1155     }
1156
1157     template <typename... Args, typename... Extra>
1158     class_ &def(detail::initimpl::pickle_factory<Args...> &&pf, const Extra &...extra) {
1159         std::move(pf).execute(*this, extra...);
1160         return *this;
1161     }
1162
1163     template <typename Func> class_& def_buffer(Func &&func) {
1164         struct capture { Func func; };
1165         capture *ptr = new capture { std::forward<Func>(func) };
1166         install_buffer_funcs([](PyObject *obj, void *ptr) -> buffer_info* {
1167             detail::make_caster<type> caster;
1168             if (!caster.load(obj, false))
1169                 return nullptr;
1170             return new buffer_info(((capture *) ptr)->func(caster));
1171         }, ptr);
1172         return *this;
1173     }
1174
1175     template <typename Return, typename Class, typename... Args>
1176     class_ &def_buffer(Return (Class::*func)(Args...)) {
1177         return def_buffer([func] (type &obj) { return (obj.*func)(); });
1178     }
1179
1180     template <typename Return, typename Class, typename... Args>
1181     class_ &def_buffer(Return (Class::*func)(Args...) const) {
1182         return def_buffer([func] (const type &obj) { return (obj.*func)(); });
1183     }
1184
1185     template <typename C, typename D, typename... Extra>
1186     class_ &def_readwrite(const char *name, D C::*pm, const Extra&... extra) {
1187         static_assert(std::is_same<C, type>::value || std::is_base_of<C, type>::value, "def_readwrite() requires a class member (or base class member)");
1188         cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this)),
1189                      fset([pm](type &c, const D &value) { c.*pm = value; }, is_method(*this));
1190         def_property(name, fget, fset, return_value_policy::reference_internal, extra...);
1191         return *this;
1192     }
1193
1194     template <typename C, typename D, typename... Extra>
1195     class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra) {
1196         static_assert(std::is_same<C, type>::value || std::is_base_of<C, type>::value, "def_readonly() requires a class member (or base class member)");
1197         cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this));
1198         def_property_readonly(name, fget, return_value_policy::reference_internal, extra...);
1199         return *this;
1200     }
1201
1202     template <typename D, typename... Extra>
1203     class_ &def_readwrite_static(const char *name, D *pm, const Extra& ...extra) {
1204         cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this)),
1205                      fset([pm](object, const D &value) { *pm = value; }, scope(*this));
1206         def_property_static(name, fget, fset, return_value_policy::reference, extra...);
1207         return *this;
1208     }
1209
1210     template <typename D, typename... Extra>
1211     class_ &def_readonly_static(const char *name, const D *pm, const Extra& ...extra) {
1212         cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this));
1213         def_property_readonly_static(name, fget, return_value_policy::reference, extra...);
1214         return *this;
1215     }
1216
1217     /// Uses return_value_policy::reference_internal by default
1218     template <typename Getter, typename... Extra>
1219     class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra) {
1220         return def_property_readonly(name, cpp_function(method_adaptor<type>(fget)),
1221                                      return_value_policy::reference_internal, extra...);
1222     }
1223
1224     /// Uses cpp_function's return_value_policy by default
1225     template <typename... Extra>
1226     class_ &def_property_readonly(const char *name, const cpp_function &fget, const Extra& ...extra) {
1227         return def_property(name, fget, nullptr, extra...);
1228     }
1229
1230     /// Uses return_value_policy::reference by default
1231     template <typename Getter, typename... Extra>
1232     class_ &def_property_readonly_static(const char *name, const Getter &fget, const Extra& ...extra) {
1233         return def_property_readonly_static(name, cpp_function(fget), return_value_policy::reference, extra...);
1234     }
1235
1236     /// Uses cpp_function's return_value_policy by default
1237     template <typename... Extra>
1238     class_ &def_property_readonly_static(const char *name, const cpp_function &fget, const Extra& ...extra) {
1239         return def_property_static(name, fget, nullptr, extra...);
1240     }
1241
1242     /// Uses return_value_policy::reference_internal by default
1243     template <typename Getter, typename Setter, typename... Extra>
1244     class_ &def_property(const char *name, const Getter &fget, const Setter &fset, const Extra& ...extra) {
1245         return def_property(name, fget, cpp_function(method_adaptor<type>(fset)), extra...);
1246     }
1247     template <typename Getter, typename... Extra>
1248     class_ &def_property(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
1249         return def_property(name, cpp_function(method_adaptor<type>(fget)), fset,
1250                             return_value_policy::reference_internal, extra...);
1251     }
1252
1253     /// Uses cpp_function's return_value_policy by default
1254     template <typename... Extra>
1255     class_ &def_property(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1256         return def_property_static(name, fget, fset, is_method(*this), extra...);
1257     }
1258
1259     /// Uses return_value_policy::reference by default
1260     template <typename Getter, typename... Extra>
1261     class_ &def_property_static(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
1262         return def_property_static(name, cpp_function(fget), fset, return_value_policy::reference, extra...);
1263     }
1264
1265     /// Uses cpp_function's return_value_policy by default
1266     template <typename... Extra>
1267     class_ &def_property_static(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1268         static_assert( 0 == detail::constexpr_sum(std::is_base_of<arg, Extra>::value...),
1269                       "Argument annotations are not allowed for properties");
1270         auto rec_fget = get_function_record(fget), rec_fset = get_function_record(fset);
1271         auto *rec_active = rec_fget;
1272         if (rec_fget) {
1273            char *doc_prev = rec_fget->doc; /* 'extra' field may include a property-specific documentation string */
1274            detail::process_attributes<Extra...>::init(extra..., rec_fget);
1275            if (rec_fget->doc && rec_fget->doc != doc_prev) {
1276               free(doc_prev);
1277               rec_fget->doc = strdup(rec_fget->doc);
1278            }
1279         }
1280         if (rec_fset) {
1281             char *doc_prev = rec_fset->doc;
1282             detail::process_attributes<Extra...>::init(extra..., rec_fset);
1283             if (rec_fset->doc && rec_fset->doc != doc_prev) {
1284                 free(doc_prev);
1285                 rec_fset->doc = strdup(rec_fset->doc);
1286             }
1287             if (! rec_active) rec_active = rec_fset;
1288         }
1289         def_property_static_impl(name, fget, fset, rec_active);
1290         return *this;
1291     }
1292
1293 private:
1294     /// Initialize holder object, variant 1: object derives from enable_shared_from_this
1295     template <typename T>
1296     static void init_holder(detail::instance *inst, detail::value_and_holder &v_h,
1297             const holder_type * /* unused */, const std::enable_shared_from_this<T> * /* dummy */) {
1298         try {
1299             auto sh = std::dynamic_pointer_cast<typename holder_type::element_type>(
1300                     v_h.value_ptr<type>()->shared_from_this());
1301             if (sh) {
1302                 new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(sh));
1303                 v_h.set_holder_constructed();
1304             }
1305         } catch (const std::bad_weak_ptr &) {}
1306
1307         if (!v_h.holder_constructed() && inst->owned) {
1308             new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>());
1309             v_h.set_holder_constructed();
1310         }
1311     }
1312
1313     static void init_holder_from_existing(const detail::value_and_holder &v_h,
1314             const holder_type *holder_ptr, std::true_type /*is_copy_constructible*/) {
1315         new (std::addressof(v_h.holder<holder_type>())) holder_type(*reinterpret_cast<const holder_type *>(holder_ptr));
1316     }
1317
1318     static void init_holder_from_existing(const detail::value_and_holder &v_h,
1319             const holder_type *holder_ptr, std::false_type /*is_copy_constructible*/) {
1320         new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(*const_cast<holder_type *>(holder_ptr)));
1321     }
1322
1323     /// Initialize holder object, variant 2: try to construct from existing holder object, if possible
1324     static void init_holder(detail::instance *inst, detail::value_and_holder &v_h,
1325             const holder_type *holder_ptr, const void * /* dummy -- not enable_shared_from_this<T>) */) {
1326         if (holder_ptr) {
1327             init_holder_from_existing(v_h, holder_ptr, std::is_copy_constructible<holder_type>());
1328             v_h.set_holder_constructed();
1329         } else if (inst->owned || detail::always_construct_holder<holder_type>::value) {
1330             new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>());
1331             v_h.set_holder_constructed();
1332         }
1333     }
1334
1335     /// Performs instance initialization including constructing a holder and registering the known
1336     /// instance.  Should be called as soon as the `type` value_ptr is set for an instance.  Takes an
1337     /// optional pointer to an existing holder to use; if not specified and the instance is
1338     /// `.owned`, a new holder will be constructed to manage the value pointer.
1339     static void init_instance(detail::instance *inst, const void *holder_ptr) {
1340         auto v_h = inst->get_value_and_holder(detail::get_type_info(typeid(type)));
1341         if (!v_h.instance_registered()) {
1342             register_instance(inst, v_h.value_ptr(), v_h.type);
1343             v_h.set_instance_registered();
1344         }
1345         init_holder(inst, v_h, (const holder_type *) holder_ptr, v_h.value_ptr<type>());
1346     }
1347
1348     /// Deallocates an instance; via holder, if constructed; otherwise via operator delete.
1349     static void dealloc(detail::value_and_holder &v_h) {
1350         if (v_h.holder_constructed()) {
1351             v_h.holder<holder_type>().~holder_type();
1352             v_h.set_holder_constructed(false);
1353         }
1354         else {
1355             detail::call_operator_delete(v_h.value_ptr<type>(),
1356                 v_h.type->type_size,
1357                 v_h.type->type_align
1358             );
1359         }
1360         v_h.value_ptr() = nullptr;
1361     }
1362
1363     static detail::function_record *get_function_record(handle h) {
1364         h = detail::get_function(h);
1365         return h ? (detail::function_record *) reinterpret_borrow<capsule>(PyCFunction_GET_SELF(h.ptr()))
1366                  : nullptr;
1367     }
1368 };
1369
1370 /// Binds an existing constructor taking arguments Args...
1371 template <typename... Args> detail::initimpl::constructor<Args...> init() { return {}; }
1372 /// Like `init<Args...>()`, but the instance is always constructed through the alias class (even
1373 /// when not inheriting on the Python side).
1374 template <typename... Args> detail::initimpl::alias_constructor<Args...> init_alias() { return {}; }
1375
1376 /// Binds a factory function as a constructor
1377 template <typename Func, typename Ret = detail::initimpl::factory<Func>>
1378 Ret init(Func &&f) { return {std::forward<Func>(f)}; }
1379
1380 /// Dual-argument factory function: the first function is called when no alias is needed, the second
1381 /// when an alias is needed (i.e. due to python-side inheritance).  Arguments must be identical.
1382 template <typename CFunc, typename AFunc, typename Ret = detail::initimpl::factory<CFunc, AFunc>>
1383 Ret init(CFunc &&c, AFunc &&a) {
1384     return {std::forward<CFunc>(c), std::forward<AFunc>(a)};
1385 }
1386
1387 /// Binds pickling functions `__getstate__` and `__setstate__` and ensures that the type
1388 /// returned by `__getstate__` is the same as the argument accepted by `__setstate__`.
1389 template <typename GetState, typename SetState>
1390 detail::initimpl::pickle_factory<GetState, SetState> pickle(GetState &&g, SetState &&s) {
1391     return {std::forward<GetState>(g), std::forward<SetState>(s)};
1392 }
1393
1394 NAMESPACE_BEGIN(detail)
1395 struct enum_base {
1396     enum_base(handle base, handle parent) : m_base(base), m_parent(parent) { }
1397
1398     PYBIND11_NOINLINE void init(bool is_arithmetic, bool is_convertible) {
1399         m_base.attr("__entries") = dict();
1400         auto property = handle((PyObject *) &PyProperty_Type);
1401         auto static_property = handle((PyObject *) get_internals().static_property_type);
1402
1403         m_base.attr("__repr__") = cpp_function(
1404             [](handle arg) -> str {
1405                 handle type = arg.get_type();
1406                 object type_name = type.attr("__name__");
1407                 dict entries = type.attr("__entries");
1408                 for (const auto &kv : entries) {
1409                     object other = kv.second[int_(0)];
1410                     if (other.equal(arg))
1411                         return pybind11::str("{}.{}").format(type_name, kv.first);
1412                 }
1413                 return pybind11::str("{}.???").format(type_name);
1414             }, is_method(m_base)
1415         );
1416
1417         m_base.attr("name") = property(cpp_function(
1418             [](handle arg) -> str {
1419                 dict entries = arg.get_type().attr("__entries");
1420                 for (const auto &kv : entries) {
1421                     if (handle(kv.second[int_(0)]).equal(arg))
1422                         return pybind11::str(kv.first);
1423                 }
1424                 return "???";
1425             }, is_method(m_base)
1426         ));
1427
1428         m_base.attr("__doc__") = static_property(cpp_function(
1429             [](handle arg) -> std::string {
1430                 std::string docstring;
1431                 dict entries = arg.attr("__entries");
1432                 if (((PyTypeObject *) arg.ptr())->tp_doc)
1433                     docstring += std::string(((PyTypeObject *) arg.ptr())->tp_doc) + "\n\n";
1434                 docstring += "Members:";
1435                 for (const auto &kv : entries) {
1436                     auto key = std::string(pybind11::str(kv.first));
1437                     auto comment = kv.second[int_(1)];
1438                     docstring += "\n\n  " + key;
1439                     if (!comment.is_none())
1440                         docstring += " : " + (std::string) pybind11::str(comment);
1441                 }
1442                 return docstring;
1443             }
1444         ), none(), none(), "");
1445
1446         m_base.attr("__members__") = static_property(cpp_function(
1447             [](handle arg) -> dict {
1448                 dict entries = arg.attr("__entries"), m;
1449                 for (const auto &kv : entries)
1450                     m[kv.first] = kv.second[int_(0)];
1451                 return m;
1452             }), none(), none(), ""
1453         );
1454
1455         #define PYBIND11_ENUM_OP_STRICT(op, expr, strict_behavior)                     \
1456             m_base.attr(op) = cpp_function(                                            \
1457                 [](object a, object b) {                                               \
1458                     if (!a.get_type().is(b.get_type()))                                \
1459                         strict_behavior;                                               \
1460                     return expr;                                                       \
1461                 },                                                                     \
1462                 is_method(m_base))
1463
1464         #define PYBIND11_ENUM_OP_CONV(op, expr)                                        \
1465             m_base.attr(op) = cpp_function(                                            \
1466                 [](object a_, object b_) {                                             \
1467                     int_ a(a_), b(b_);                                                 \
1468                     return expr;                                                       \
1469                 },                                                                     \
1470                 is_method(m_base))
1471
1472         #define PYBIND11_ENUM_OP_CONV_LHS(op, expr)                                    \
1473             m_base.attr(op) = cpp_function(                                            \
1474                 [](object a_, object b) {                                              \
1475                     int_ a(a_);                                                        \
1476                     return expr;                                                       \
1477                 },                                                                     \
1478                 is_method(m_base))
1479
1480         if (is_convertible) {
1481             PYBIND11_ENUM_OP_CONV_LHS("__eq__", !b.is_none() &&  a.equal(b));
1482             PYBIND11_ENUM_OP_CONV_LHS("__ne__",  b.is_none() || !a.equal(b));
1483
1484             if (is_arithmetic) {
1485                 PYBIND11_ENUM_OP_CONV("__lt__",   a <  b);
1486                 PYBIND11_ENUM_OP_CONV("__gt__",   a >  b);
1487                 PYBIND11_ENUM_OP_CONV("__le__",   a <= b);
1488                 PYBIND11_ENUM_OP_CONV("__ge__",   a >= b);
1489                 PYBIND11_ENUM_OP_CONV("__and__",  a &  b);
1490                 PYBIND11_ENUM_OP_CONV("__rand__", a &  b);
1491                 PYBIND11_ENUM_OP_CONV("__or__",   a |  b);
1492                 PYBIND11_ENUM_OP_CONV("__ror__",  a |  b);
1493                 PYBIND11_ENUM_OP_CONV("__xor__",  a ^  b);
1494                 PYBIND11_ENUM_OP_CONV("__rxor__", a ^  b);
1495                 m_base.attr("__invert__") = cpp_function(
1496                     [](object arg) { return ~(int_(arg)); }, is_method(m_base));
1497             }
1498         } else {
1499             PYBIND11_ENUM_OP_STRICT("__eq__",  int_(a).equal(int_(b)), return false);
1500             PYBIND11_ENUM_OP_STRICT("__ne__", !int_(a).equal(int_(b)), return true);
1501
1502             if (is_arithmetic) {
1503                 #define PYBIND11_THROW throw type_error("Expected an enumeration of matching type!");
1504                 PYBIND11_ENUM_OP_STRICT("__lt__", int_(a) <  int_(b), PYBIND11_THROW);
1505                 PYBIND11_ENUM_OP_STRICT("__gt__", int_(a) >  int_(b), PYBIND11_THROW);
1506                 PYBIND11_ENUM_OP_STRICT("__le__", int_(a) <= int_(b), PYBIND11_THROW);
1507                 PYBIND11_ENUM_OP_STRICT("__ge__", int_(a) >= int_(b), PYBIND11_THROW);
1508                 #undef PYBIND11_THROW
1509             }
1510         }
1511
1512         #undef PYBIND11_ENUM_OP_CONV_LHS
1513         #undef PYBIND11_ENUM_OP_CONV
1514         #undef PYBIND11_ENUM_OP_STRICT
1515
1516         object getstate = cpp_function(
1517             [](object arg) { return int_(arg); }, is_method(m_base));
1518
1519         m_base.attr("__getstate__") = getstate;
1520         m_base.attr("__hash__") = getstate;
1521     }
1522
1523     PYBIND11_NOINLINE void value(char const* name_, object value, const char *doc = nullptr) {
1524         dict entries = m_base.attr("__entries");
1525         str name(name_);
1526         if (entries.contains(name)) {
1527             std::string type_name = (std::string) str(m_base.attr("__name__"));
1528             throw value_error(type_name + ": element \"" + std::string(name_) + "\" already exists!");
1529         }
1530
1531         entries[name] = std::make_pair(value, doc);
1532         m_base.attr(name) = value;
1533     }
1534
1535     PYBIND11_NOINLINE void export_values() {
1536         dict entries = m_base.attr("__entries");
1537         for (const auto &kv : entries)
1538             m_parent.attr(kv.first) = kv.second[int_(0)];
1539     }
1540
1541     handle m_base;
1542     handle m_parent;
1543 };
1544
1545 NAMESPACE_END(detail)
1546
1547 /// Binds C++ enumerations and enumeration classes to Python
1548 template <typename Type> class enum_ : public class_<Type> {
1549 public:
1550     using Base = class_<Type>;
1551     using Base::def;
1552     using Base::attr;
1553     using Base::def_property_readonly;
1554     using Base::def_property_readonly_static;
1555     using Scalar = typename std::underlying_type<Type>::type;
1556
1557     template <typename... Extra>
1558     enum_(const handle &scope, const char *name, const Extra&... extra)
1559       : class_<Type>(scope, name, extra...), m_base(*this, scope) {
1560         constexpr bool is_arithmetic = detail::any_of<std::is_same<arithmetic, Extra>...>::value;
1561         constexpr bool is_convertible = std::is_convertible<Type, Scalar>::value;
1562         m_base.init(is_arithmetic, is_convertible);
1563
1564         def(init([](Scalar i) { return static_cast<Type>(i); }));
1565         def("__int__", [](Type value) { return (Scalar) value; });
1566         #if PY_MAJOR_VERSION < 3
1567             def("__long__", [](Type value) { return (Scalar) value; });
1568         #endif
1569         #if PY_MAJOR_VERSION > 3 || (PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION >= 8)
1570             def("__index__", [](Type value) { return (Scalar) value; });
1571         #endif
1572
1573         cpp_function setstate(
1574             [](Type &value, Scalar arg) { value = static_cast<Type>(arg); },
1575             is_method(*this));
1576         attr("__setstate__") = setstate;
1577     }
1578
1579     /// Export enumeration entries into the parent scope
1580     enum_& export_values() {
1581         m_base.export_values();
1582         return *this;
1583     }
1584
1585     /// Add an enumeration entry
1586     enum_& value(char const* name, Type value, const char *doc = nullptr) {
1587         m_base.value(name, pybind11::cast(value, return_value_policy::copy), doc);
1588         return *this;
1589     }
1590
1591 private:
1592     detail::enum_base m_base;
1593 };
1594
1595 NAMESPACE_BEGIN(detail)
1596
1597
1598 inline void keep_alive_impl(handle nurse, handle patient) {
1599     if (!nurse || !patient)
1600         pybind11_fail("Could not activate keep_alive!");
1601
1602     if (patient.is_none() || nurse.is_none())
1603         return; /* Nothing to keep alive or nothing to be kept alive by */
1604
1605     auto tinfo = all_type_info(Py_TYPE(nurse.ptr()));
1606     if (!tinfo.empty()) {
1607         /* It's a pybind-registered type, so we can store the patient in the
1608          * internal list. */
1609         add_patient(nurse.ptr(), patient.ptr());
1610     }
1611     else {
1612         /* Fall back to clever approach based on weak references taken from
1613          * Boost.Python. This is not used for pybind-registered types because
1614          * the objects can be destroyed out-of-order in a GC pass. */
1615         cpp_function disable_lifesupport(
1616             [patient](handle weakref) { patient.dec_ref(); weakref.dec_ref(); });
1617
1618         weakref wr(nurse, disable_lifesupport);
1619
1620         patient.inc_ref(); /* reference patient and leak the weak reference */
1621         (void) wr.release();
1622     }
1623 }
1624
1625 PYBIND11_NOINLINE inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret) {
1626     auto get_arg = [&](size_t n) {
1627         if (n == 0)
1628             return ret;
1629         else if (n == 1 && call.init_self)
1630             return call.init_self;
1631         else if (n <= call.args.size())
1632             return call.args[n - 1];
1633         return handle();
1634     };
1635
1636     keep_alive_impl(get_arg(Nurse), get_arg(Patient));
1637 }
1638
1639 inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type) {
1640     auto res = get_internals().registered_types_py
1641 #ifdef __cpp_lib_unordered_map_try_emplace
1642         .try_emplace(type);
1643 #else
1644         .emplace(type, std::vector<detail::type_info *>());
1645 #endif
1646     if (res.second) {
1647         // New cache entry created; set up a weak reference to automatically remove it if the type
1648         // gets destroyed:
1649         weakref((PyObject *) type, cpp_function([type](handle wr) {
1650             get_internals().registered_types_py.erase(type);
1651             wr.dec_ref();
1652         })).release();
1653     }
1654
1655     return res;
1656 }
1657
1658 template <typename Iterator, typename Sentinel, bool KeyIterator, return_value_policy Policy>
1659 struct iterator_state {
1660     Iterator it;
1661     Sentinel end;
1662     bool first_or_done;
1663 };
1664
1665 NAMESPACE_END(detail)
1666
1667 /// Makes a python iterator from a first and past-the-end C++ InputIterator.
1668 template <return_value_policy Policy = return_value_policy::reference_internal,
1669           typename Iterator,
1670           typename Sentinel,
1671           typename ValueType = decltype(*std::declval<Iterator>()),
1672           typename... Extra>
1673 iterator make_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1674     typedef detail::iterator_state<Iterator, Sentinel, false, Policy> state;
1675
1676     if (!detail::get_type_info(typeid(state), false)) {
1677         class_<state>(handle(), "iterator", pybind11::module_local())
1678             .def("__iter__", [](state &s) -> state& { return s; })
1679             .def("__next__", [](state &s) -> ValueType {
1680                 if (!s.first_or_done)
1681                     ++s.it;
1682                 else
1683                     s.first_or_done = false;
1684                 if (s.it == s.end) {
1685                     s.first_or_done = true;
1686                     throw stop_iteration();
1687                 }
1688                 return *s.it;
1689             }, std::forward<Extra>(extra)..., Policy);
1690     }
1691
1692     return cast(state{first, last, true});
1693 }
1694
1695 /// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a
1696 /// first and past-the-end InputIterator.
1697 template <return_value_policy Policy = return_value_policy::reference_internal,
1698           typename Iterator,
1699           typename Sentinel,
1700           typename KeyType = decltype((*std::declval<Iterator>()).first),
1701           typename... Extra>
1702 iterator make_key_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1703     typedef detail::iterator_state<Iterator, Sentinel, true, Policy> state;
1704
1705     if (!detail::get_type_info(typeid(state), false)) {
1706         class_<state>(handle(), "iterator", pybind11::module_local())
1707             .def("__iter__", [](state &s) -> state& { return s; })
1708             .def("__next__", [](state &s) -> KeyType {
1709                 if (!s.first_or_done)
1710                     ++s.it;
1711                 else
1712                     s.first_or_done = false;
1713                 if (s.it == s.end) {
1714                     s.first_or_done = true;
1715                     throw stop_iteration();
1716                 }
1717                 return (*s.it).first;
1718             }, std::forward<Extra>(extra)..., Policy);
1719     }
1720
1721     return cast(state{first, last, true});
1722 }
1723
1724 /// Makes an iterator over values of an stl container or other container supporting
1725 /// `std::begin()`/`std::end()`
1726 template <return_value_policy Policy = return_value_policy::reference_internal,
1727           typename Type, typename... Extra> iterator make_iterator(Type &value, Extra&&... extra) {
1728     return make_iterator<Policy>(std::begin(value), std::end(value), extra...);
1729 }
1730
1731 /// Makes an iterator over the keys (`.first`) of a stl map-like container supporting
1732 /// `std::begin()`/`std::end()`
1733 template <return_value_policy Policy = return_value_policy::reference_internal,
1734           typename Type, typename... Extra> iterator make_key_iterator(Type &value, Extra&&... extra) {
1735     return make_key_iterator<Policy>(std::begin(value), std::end(value), extra...);
1736 }
1737
1738 template <typename InputType, typename OutputType> void implicitly_convertible() {
1739     struct set_flag {
1740         bool &flag;
1741         set_flag(bool &flag) : flag(flag) { flag = true; }
1742         ~set_flag() { flag = false; }
1743     };
1744     auto implicit_caster = [](PyObject *obj, PyTypeObject *type) -> PyObject * {
1745         static bool currently_used = false;
1746         if (currently_used) // implicit conversions are non-reentrant
1747             return nullptr;
1748         set_flag flag_helper(currently_used);
1749         if (!detail::make_caster<InputType>().load(obj, false))
1750             return nullptr;
1751         tuple args(1);
1752         args[0] = obj;
1753         PyObject *result = PyObject_Call((PyObject *) type, args.ptr(), nullptr);
1754         if (result == nullptr)
1755             PyErr_Clear();
1756         return result;
1757     };
1758
1759     if (auto tinfo = detail::get_type_info(typeid(OutputType)))
1760         tinfo->implicit_conversions.push_back(implicit_caster);
1761     else
1762         pybind11_fail("implicitly_convertible: Unable to find type " + type_id<OutputType>());
1763 }
1764
1765 template <typename ExceptionTranslator>
1766 void register_exception_translator(ExceptionTranslator&& translator) {
1767     detail::get_internals().registered_exception_translators.push_front(
1768         std::forward<ExceptionTranslator>(translator));
1769 }
1770
1771 /**
1772  * Wrapper to generate a new Python exception type.
1773  *
1774  * This should only be used with PyErr_SetString for now.
1775  * It is not (yet) possible to use as a py::base.
1776  * Template type argument is reserved for future use.
1777  */
1778 template <typename type>
1779 class exception : public object {
1780 public:
1781     exception() = default;
1782     exception(handle scope, const char *name, PyObject *base = PyExc_Exception) {
1783         std::string full_name = scope.attr("__name__").cast<std::string>() +
1784                                 std::string(".") + name;
1785         m_ptr = PyErr_NewException(const_cast<char *>(full_name.c_str()), base, NULL);
1786         if (hasattr(scope, name))
1787             pybind11_fail("Error during initialization: multiple incompatible "
1788                           "definitions with name \"" + std::string(name) + "\"");
1789         scope.attr(name) = *this;
1790     }
1791
1792     // Sets the current python exception to this exception object with the given message
1793     void operator()(const char *message) {
1794         PyErr_SetString(m_ptr, message);
1795     }
1796 };
1797
1798 NAMESPACE_BEGIN(detail)
1799 // Returns a reference to a function-local static exception object used in the simple
1800 // register_exception approach below.  (It would be simpler to have the static local variable
1801 // directly in register_exception, but that makes clang <3.5 segfault - Issue #1349).
1802 template <typename CppException>
1803 exception<CppException> &get_exception_object() { static exception<CppException> ex; return ex; }
1804 NAMESPACE_END(detail)
1805
1806 /**
1807  * Registers a Python exception in `m` of the given `name` and installs an exception translator to
1808  * translate the C++ exception to the created Python exception using the exceptions what() method.
1809  * This is intended for simple exception translations; for more complex translation, register the
1810  * exception object and translator directly.
1811  */
1812 template <typename CppException>
1813 exception<CppException> &register_exception(handle scope,
1814                                             const char *name,
1815                                             PyObject *base = PyExc_Exception) {
1816     auto &ex = detail::get_exception_object<CppException>();
1817     if (!ex) ex = exception<CppException>(scope, name, base);
1818
1819     register_exception_translator([](std::exception_ptr p) {
1820         if (!p) return;
1821         try {
1822             std::rethrow_exception(p);
1823         } catch (const CppException &e) {
1824             detail::get_exception_object<CppException>()(e.what());
1825         }
1826     });
1827     return ex;
1828 }
1829
1830 NAMESPACE_BEGIN(detail)
1831 PYBIND11_NOINLINE inline void print(tuple args, dict kwargs) {
1832     auto strings = tuple(args.size());
1833     for (size_t i = 0; i < args.size(); ++i) {
1834         strings[i] = str(args[i]);
1835     }
1836     auto sep = kwargs.contains("sep") ? kwargs["sep"] : cast(" ");
1837     auto line = sep.attr("join")(strings);
1838
1839     object file;
1840     if (kwargs.contains("file")) {
1841         file = kwargs["file"].cast<object>();
1842     } else {
1843         try {
1844             file = module::import("sys").attr("stdout");
1845         } catch (const error_already_set &) {
1846             /* If print() is called from code that is executed as
1847                part of garbage collection during interpreter shutdown,
1848                importing 'sys' can fail. Give up rather than crashing the
1849                interpreter in this case. */
1850             return;
1851         }
1852     }
1853
1854     auto write = file.attr("write");
1855     write(line);
1856     write(kwargs.contains("end") ? kwargs["end"] : cast("\n"));
1857
1858     if (kwargs.contains("flush") && kwargs["flush"].cast<bool>())
1859         file.attr("flush")();
1860 }
1861 NAMESPACE_END(detail)
1862
1863 template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
1864 void print(Args &&...args) {
1865     auto c = detail::collect_arguments<policy>(std::forward<Args>(args)...);
1866     detail::print(c.args(), c.kwargs());
1867 }
1868
1869 #if defined(WITH_THREAD) && !defined(PYPY_VERSION)
1870
1871 /* The functions below essentially reproduce the PyGILState_* API using a RAII
1872  * pattern, but there are a few important differences:
1873  *
1874  * 1. When acquiring the GIL from an non-main thread during the finalization
1875  *    phase, the GILState API blindly terminates the calling thread, which
1876  *    is often not what is wanted. This API does not do this.
1877  *
1878  * 2. The gil_scoped_release function can optionally cut the relationship
1879  *    of a PyThreadState and its associated thread, which allows moving it to
1880  *    another thread (this is a fairly rare/advanced use case).
1881  *
1882  * 3. The reference count of an acquired thread state can be controlled. This
1883  *    can be handy to prevent cases where callbacks issued from an external
1884  *    thread would otherwise constantly construct and destroy thread state data
1885  *    structures.
1886  *
1887  * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an
1888  * example which uses features 2 and 3 to migrate the Python thread of
1889  * execution to another thread (to run the event loop on the original thread,
1890  * in this case).
1891  */
1892
1893 class gil_scoped_acquire {
1894 public:
1895     PYBIND11_NOINLINE gil_scoped_acquire() {
1896         auto const &internals = detail::get_internals();
1897         tstate = (PyThreadState *) PYBIND11_TLS_GET_VALUE(internals.tstate);
1898
1899         if (!tstate) {
1900             /* Check if the GIL was acquired using the PyGILState_* API instead (e.g. if
1901                calling from a Python thread). Since we use a different key, this ensures
1902                we don't create a new thread state and deadlock in PyEval_AcquireThread
1903                below. Note we don't save this state with internals.tstate, since we don't
1904                create it we would fail to clear it (its reference count should be > 0). */
1905             tstate = PyGILState_GetThisThreadState();
1906         }
1907
1908         if (!tstate) {
1909             tstate = PyThreadState_New(internals.istate);
1910             #if !defined(NDEBUG)
1911                 if (!tstate)
1912                     pybind11_fail("scoped_acquire: could not create thread state!");
1913             #endif
1914             tstate->gilstate_counter = 0;
1915             PYBIND11_TLS_REPLACE_VALUE(internals.tstate, tstate);
1916         } else {
1917             release = detail::get_thread_state_unchecked() != tstate;
1918         }
1919
1920         if (release) {
1921             /* Work around an annoying assertion in PyThreadState_Swap */
1922             #if defined(Py_DEBUG)
1923                 PyInterpreterState *interp = tstate->interp;
1924                 tstate->interp = nullptr;
1925             #endif
1926             PyEval_AcquireThread(tstate);
1927             #if defined(Py_DEBUG)
1928                 tstate->interp = interp;
1929             #endif
1930         }
1931
1932         inc_ref();
1933     }
1934
1935     void inc_ref() {
1936         ++tstate->gilstate_counter;
1937     }
1938
1939     PYBIND11_NOINLINE void dec_ref() {
1940         --tstate->gilstate_counter;
1941         #if !defined(NDEBUG)
1942             if (detail::get_thread_state_unchecked() != tstate)
1943                 pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!");
1944             if (tstate->gilstate_counter < 0)
1945                 pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!");
1946         #endif
1947         if (tstate->gilstate_counter == 0) {
1948             #if !defined(NDEBUG)
1949                 if (!release)
1950                     pybind11_fail("scoped_acquire::dec_ref(): internal error!");
1951             #endif
1952             PyThreadState_Clear(tstate);
1953             PyThreadState_DeleteCurrent();
1954             PYBIND11_TLS_DELETE_VALUE(detail::get_internals().tstate);
1955             release = false;
1956         }
1957     }
1958
1959     PYBIND11_NOINLINE ~gil_scoped_acquire() {
1960         dec_ref();
1961         if (release)
1962            PyEval_SaveThread();
1963     }
1964 private:
1965     PyThreadState *tstate = nullptr;
1966     bool release = true;
1967 };
1968
1969 class gil_scoped_release {
1970 public:
1971     explicit gil_scoped_release(bool disassoc = false) : disassoc(disassoc) {
1972         // `get_internals()` must be called here unconditionally in order to initialize
1973         // `internals.tstate` for subsequent `gil_scoped_acquire` calls. Otherwise, an
1974         // initialization race could occur as multiple threads try `gil_scoped_acquire`.
1975         const auto &internals = detail::get_internals();
1976         tstate = PyEval_SaveThread();
1977         if (disassoc) {
1978             auto key = internals.tstate;
1979             PYBIND11_TLS_DELETE_VALUE(key);
1980         }
1981     }
1982     ~gil_scoped_release() {
1983         if (!tstate)
1984             return;
1985         PyEval_RestoreThread(tstate);
1986         if (disassoc) {
1987             auto key = detail::get_internals().tstate;
1988             PYBIND11_TLS_REPLACE_VALUE(key, tstate);
1989         }
1990     }
1991 private:
1992     PyThreadState *tstate;
1993     bool disassoc;
1994 };
1995 #elif defined(PYPY_VERSION)
1996 class gil_scoped_acquire {
1997     PyGILState_STATE state;
1998 public:
1999     gil_scoped_acquire() { state = PyGILState_Ensure(); }
2000     ~gil_scoped_acquire() { PyGILState_Release(state); }
2001 };
2002
2003 class gil_scoped_release {
2004     PyThreadState *state;
2005 public:
2006     gil_scoped_release() { state = PyEval_SaveThread(); }
2007     ~gil_scoped_release() { PyEval_RestoreThread(state); }
2008 };
2009 #else
2010 class gil_scoped_acquire { };
2011 class gil_scoped_release { };
2012 #endif
2013
2014 error_already_set::~error_already_set() {
2015     if (m_type) {
2016         gil_scoped_acquire gil;
2017         error_scope scope;
2018         m_type.release().dec_ref();
2019         m_value.release().dec_ref();
2020         m_trace.release().dec_ref();
2021     }
2022 }
2023
2024 inline function get_type_overload(const void *this_ptr, const detail::type_info *this_type, const char *name)  {
2025     handle self = detail::get_object_handle(this_ptr, this_type);
2026     if (!self)
2027         return function();
2028     handle type = self.get_type();
2029     auto key = std::make_pair(type.ptr(), name);
2030
2031     /* Cache functions that aren't overloaded in Python to avoid
2032        many costly Python dictionary lookups below */
2033     auto &cache = detail::get_internals().inactive_overload_cache;
2034     if (cache.find(key) != cache.end())
2035         return function();
2036
2037     function overload = getattr(self, name, function());
2038     if (overload.is_cpp_function()) {
2039         cache.insert(key);
2040         return function();
2041     }
2042
2043     /* Don't call dispatch code if invoked from overridden function.
2044        Unfortunately this doesn't work on PyPy. */
2045 #if !defined(PYPY_VERSION)
2046     PyFrameObject *frame = PyThreadState_Get()->frame;
2047     if (frame && (std::string) str(frame->f_code->co_name) == name &&
2048         frame->f_code->co_argcount > 0) {
2049         PyFrame_FastToLocals(frame);
2050         PyObject *self_caller = PyDict_GetItem(
2051             frame->f_locals, PyTuple_GET_ITEM(frame->f_code->co_varnames, 0));
2052         if (self_caller == self.ptr())
2053             return function();
2054     }
2055 #else
2056     /* PyPy currently doesn't provide a detailed cpyext emulation of
2057        frame objects, so we have to emulate this using Python. This
2058        is going to be slow..*/
2059     dict d; d["self"] = self; d["name"] = pybind11::str(name);
2060     PyObject *result = PyRun_String(
2061         "import inspect\n"
2062         "frame = inspect.currentframe()\n"
2063         "if frame is not None:\n"
2064         "    frame = frame.f_back\n"
2065         "    if frame is not None and str(frame.f_code.co_name) == name and "
2066         "frame.f_code.co_argcount > 0:\n"
2067         "        self_caller = frame.f_locals[frame.f_code.co_varnames[0]]\n"
2068         "        if self_caller == self:\n"
2069         "            self = None\n",
2070         Py_file_input, d.ptr(), d.ptr());
2071     if (result == nullptr)
2072         throw error_already_set();
2073     if (d["self"].is_none())
2074         return function();
2075     Py_DECREF(result);
2076 #endif
2077
2078     return overload;
2079 }
2080
2081 /** \rst
2082   Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
2083
2084   :this_ptr: The pointer to the object the overload should be retrieved for. This should be the first
2085                    non-trampoline class encountered in the inheritance chain.
2086   :name: The name of the overloaded Python method to retrieve.
2087   :return: The Python method by this name from the object or an empty function wrapper.
2088  \endrst */
2089 template <class T> function get_overload(const T *this_ptr, const char *name) {
2090     auto tinfo = detail::get_type_info(typeid(T));
2091     return tinfo ? get_type_overload(this_ptr, tinfo, name) : function();
2092 }
2093
2094 #define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) { \
2095         pybind11::gil_scoped_acquire gil; \
2096         pybind11::function overload = pybind11::get_overload(static_cast<const cname *>(this), name); \
2097         if (overload) { \
2098             auto o = overload(__VA_ARGS__); \
2099             if (pybind11::detail::cast_is_temporary_value_reference<ret_type>::value) { \
2100                 static pybind11::detail::overload_caster_t<ret_type> caster; \
2101                 return pybind11::detail::cast_ref<ret_type>(std::move(o), caster); \
2102             } \
2103             else return pybind11::detail::cast_safe<ret_type>(std::move(o)); \
2104         } \
2105     }
2106
2107 /** \rst
2108     Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named 'fn'
2109     from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2110     the appropriate type. See :ref:`overriding_virtuals` for more information. This macro should be used when the method
2111     name in C is not the same as the method name in Python. For example with `__str__`.
2112
2113     .. code-block:: cpp
2114
2115       std::string toString() override {
2116         PYBIND11_OVERLOAD_NAME(
2117             std::string, // Return type (ret_type)
2118             Animal,      // Parent class (cname)
2119             toString,    // Name of function in C++ (name)
2120             "__str__",   // Name of method in Python (fn)
2121         );
2122       }
2123 \endrst */
2124 #define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \
2125     PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2126     return cname::fn(__VA_ARGS__)
2127
2128 /** \rst
2129     Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD_NAME`, except that it
2130     throws if no overload can be found.
2131 \endrst */
2132 #define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \
2133     PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2134     pybind11::pybind11_fail("Tried to call pure virtual function \"" PYBIND11_STRINGIFY(cname) "::" name "\"");
2135
2136 /** \rst
2137     Macro to populate the virtual method in the trampoline class. This macro tries to look up the method
2138     from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2139     the appropriate type. This macro should be used if the method name in C and in Python are identical.
2140     See :ref:`overriding_virtuals` for more information.
2141
2142     .. code-block:: cpp
2143
2144       class PyAnimal : public Animal {
2145       public:
2146           // Inherit the constructors
2147           using Animal::Animal;
2148
2149           // Trampoline (need one for each virtual function)
2150           std::string go(int n_times) override {
2151               PYBIND11_OVERLOAD_PURE(
2152                   std::string, // Return type (ret_type)
2153                   Animal,      // Parent class (cname)
2154                   go,          // Name of function in C++ (must match Python name) (fn)
2155                   n_times      // Argument(s) (...)
2156               );
2157           }
2158       };
2159 \endrst */
2160 #define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \
2161     PYBIND11_OVERLOAD_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2162
2163 /** \rst
2164     Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD`, except that it throws
2165     if no overload can be found.
2166 \endrst */
2167 #define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \
2168     PYBIND11_OVERLOAD_PURE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2169
2170 NAMESPACE_END(PYBIND11_NAMESPACE)
2171
2172 #if defined(_MSC_VER) && !defined(__INTEL_COMPILER)
2173 #  pragma warning(pop)
2174 #elif defined(__GNUG__) && !defined(__clang__)
2175 #  pragma GCC diagnostic pop
2176 #endif