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(__cpp_aligned_new) && (!defined(_MSC_VER) || _MSC_VER >= 1912)
1007         if (a > __STDCPP_DEFAULT_NEW_ALIGNMENT__) {
1008             #ifdef __cpp_sized_deallocation
1009                 ::operator delete(p, s, std::align_val_t(a));
1010             #else
1011                 ::operator delete(p, std::align_val_t(a));
1012             #endif
1013             return;
1014         }
1015     #endif
1016     #ifdef __cpp_sized_deallocation
1017         ::operator delete(p, s);
1018     #else
1019         ::operator delete(p);
1020     #endif
1021 }
1022
1023 NAMESPACE_END(detail)
1024
1025 /// Given a pointer to a member function, cast it to its `Derived` version.
1026 /// Forward everything else unchanged.
1027 template <typename /*Derived*/, typename F>
1028 auto method_adaptor(F &&f) -> decltype(std::forward<F>(f)) { return std::forward<F>(f); }
1029
1030 template <typename Derived, typename Return, typename Class, typename... Args>
1031 auto method_adaptor(Return (Class::*pmf)(Args...)) -> Return (Derived::*)(Args...) {
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 Derived, typename Return, typename Class, typename... Args>
1038 auto method_adaptor(Return (Class::*pmf)(Args...) const) -> Return (Derived::*)(Args...) const {
1039     static_assert(detail::is_accessible_base_of<Class, Derived>::value,
1040         "Cannot bind an inaccessible base class method; use a lambda definition instead");
1041     return pmf;
1042 }
1043
1044 template <typename type_, typename... options>
1045 class class_ : public detail::generic_type {
1046     template <typename T> using is_holder = detail::is_holder_type<type_, T>;
1047     template <typename T> using is_subtype = detail::is_strict_base_of<type_, T>;
1048     template <typename T> using is_base = detail::is_strict_base_of<T, type_>;
1049     // struct instead of using here to help MSVC:
1050     template <typename T> struct is_valid_class_option :
1051         detail::any_of<is_holder<T>, is_subtype<T>, is_base<T>> {};
1052
1053 public:
1054     using type = type_;
1055     using type_alias = detail::exactly_one_t<is_subtype, void, options...>;
1056     constexpr static bool has_alias = !std::is_void<type_alias>::value;
1057     using holder_type = detail::exactly_one_t<is_holder, std::unique_ptr<type>, options...>;
1058
1059     static_assert(detail::all_of<is_valid_class_option<options>...>::value,
1060             "Unknown/invalid class_ template parameters provided");
1061
1062     static_assert(!has_alias || std::is_polymorphic<type>::value,
1063             "Cannot use an alias class with a non-polymorphic type");
1064
1065     PYBIND11_OBJECT(class_, generic_type, PyType_Check)
1066
1067     template <typename... Extra>
1068     class_(handle scope, const char *name, const Extra &... extra) {
1069         using namespace detail;
1070
1071         // MI can only be specified via class_ template options, not constructor parameters
1072         static_assert(
1073             none_of<is_pyobject<Extra>...>::value || // no base class arguments, or:
1074             (   constexpr_sum(is_pyobject<Extra>::value...) == 1 && // Exactly one base
1075                 constexpr_sum(is_base<options>::value...)   == 0 && // no template option bases
1076                 none_of<std::is_same<multiple_inheritance, Extra>...>::value), // no multiple_inheritance attr
1077             "Error: multiple inheritance bases must be specified via class_ template options");
1078
1079         type_record record;
1080         record.scope = scope;
1081         record.name = name;
1082         record.type = &typeid(type);
1083         record.type_size = sizeof(conditional_t<has_alias, type_alias, type>);
1084         record.type_align = alignof(conditional_t<has_alias, type_alias, type>&);
1085         record.holder_size = sizeof(holder_type);
1086         record.init_instance = init_instance;
1087         record.dealloc = dealloc;
1088         record.default_holder = detail::is_instantiation<std::unique_ptr, holder_type>::value;
1089
1090         set_operator_new<type>(&record);
1091
1092         /* Register base classes specified via template arguments to class_, if any */
1093         PYBIND11_EXPAND_SIDE_EFFECTS(add_base<options>(record));
1094
1095         /* Process optional arguments, if any */
1096         process_attributes<Extra...>::init(extra..., &record);
1097
1098         generic_type::initialize(record);
1099
1100         if (has_alias) {
1101             auto &instances = record.module_local ? registered_local_types_cpp() : get_internals().registered_types_cpp;
1102             instances[std::type_index(typeid(type_alias))] = instances[std::type_index(typeid(type))];
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 &rec) {
1108         rec.add_base(typeid(Base), [](void *src) -> void * {
1109             return static_cast<Base *>(reinterpret_cast<type *>(src));
1110         });
1111     }
1112
1113     template <typename Base, detail::enable_if_t<!is_base<Base>::value, int> = 0>
1114     static void add_base(detail::type_record &) { }
1115
1116     template <typename Func, typename... Extra>
1117     class_ &def(const char *name_, Func&& f, const Extra&... extra) {
1118         cpp_function cf(method_adaptor<type>(std::forward<Func>(f)), name(name_), is_method(*this),
1119                         sibling(getattr(*this, name_, none())), extra...);
1120         attr(cf.name()) = cf;
1121         return *this;
1122     }
1123
1124     template <typename Func, typename... Extra> class_ &
1125     def_static(const char *name_, Func &&f, const Extra&... extra) {
1126         static_assert(!std::is_member_function_pointer<Func>::value,
1127                 "def_static(...) called with a non-static member function pointer");
1128         cpp_function cf(std::forward<Func>(f), name(name_), scope(*this),
1129                         sibling(getattr(*this, name_, none())), extra...);
1130         attr(cf.name()) = staticmethod(cf);
1131         return *this;
1132     }
1133
1134     template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
1135     class_ &def(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
1136         op.execute(*this, extra...);
1137         return *this;
1138     }
1139
1140     template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
1141     class_ & def_cast(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
1142         op.execute_cast(*this, extra...);
1143         return *this;
1144     }
1145
1146     template <typename... Args, typename... Extra>
1147     class_ &def(const detail::initimpl::constructor<Args...> &init, const Extra&... extra) {
1148         init.execute(*this, extra...);
1149         return *this;
1150     }
1151
1152     template <typename... Args, typename... Extra>
1153     class_ &def(const detail::initimpl::alias_constructor<Args...> &init, const Extra&... extra) {
1154         init.execute(*this, extra...);
1155         return *this;
1156     }
1157
1158     template <typename... Args, typename... Extra>
1159     class_ &def(detail::initimpl::factory<Args...> &&init, const Extra&... extra) {
1160         std::move(init).execute(*this, extra...);
1161         return *this;
1162     }
1163
1164     template <typename... Args, typename... Extra>
1165     class_ &def(detail::initimpl::pickle_factory<Args...> &&pf, const Extra &...extra) {
1166         std::move(pf).execute(*this, extra...);
1167         return *this;
1168     }
1169
1170     template <typename Func> class_& def_buffer(Func &&func) {
1171         struct capture { Func func; };
1172         capture *ptr = new capture { std::forward<Func>(func) };
1173         install_buffer_funcs([](PyObject *obj, void *ptr) -> buffer_info* {
1174             detail::make_caster<type> caster;
1175             if (!caster.load(obj, false))
1176                 return nullptr;
1177             return new buffer_info(((capture *) ptr)->func(caster));
1178         }, ptr);
1179         return *this;
1180     }
1181
1182     template <typename Return, typename Class, typename... Args>
1183     class_ &def_buffer(Return (Class::*func)(Args...)) {
1184         return def_buffer([func] (type &obj) { return (obj.*func)(); });
1185     }
1186
1187     template <typename Return, typename Class, typename... Args>
1188     class_ &def_buffer(Return (Class::*func)(Args...) const) {
1189         return def_buffer([func] (const type &obj) { return (obj.*func)(); });
1190     }
1191
1192     template <typename C, typename D, typename... Extra>
1193     class_ &def_readwrite(const char *name, D C::*pm, const Extra&... extra) {
1194         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)");
1195         cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this)),
1196                      fset([pm](type &c, const D &value) { c.*pm = value; }, is_method(*this));
1197         def_property(name, fget, fset, return_value_policy::reference_internal, extra...);
1198         return *this;
1199     }
1200
1201     template <typename C, typename D, typename... Extra>
1202     class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra) {
1203         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)");
1204         cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this));
1205         def_property_readonly(name, fget, return_value_policy::reference_internal, extra...);
1206         return *this;
1207     }
1208
1209     template <typename D, typename... Extra>
1210     class_ &def_readwrite_static(const char *name, D *pm, const Extra& ...extra) {
1211         cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this)),
1212                      fset([pm](object, const D &value) { *pm = value; }, scope(*this));
1213         def_property_static(name, fget, fset, return_value_policy::reference, extra...);
1214         return *this;
1215     }
1216
1217     template <typename D, typename... Extra>
1218     class_ &def_readonly_static(const char *name, const D *pm, const Extra& ...extra) {
1219         cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this));
1220         def_property_readonly_static(name, fget, return_value_policy::reference, extra...);
1221         return *this;
1222     }
1223
1224     /// Uses return_value_policy::reference_internal by default
1225     template <typename Getter, typename... Extra>
1226     class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra) {
1227         return def_property_readonly(name, cpp_function(method_adaptor<type>(fget)),
1228                                      return_value_policy::reference_internal, extra...);
1229     }
1230
1231     /// Uses cpp_function's return_value_policy by default
1232     template <typename... Extra>
1233     class_ &def_property_readonly(const char *name, const cpp_function &fget, const Extra& ...extra) {
1234         return def_property(name, fget, nullptr, extra...);
1235     }
1236
1237     /// Uses return_value_policy::reference by default
1238     template <typename Getter, typename... Extra>
1239     class_ &def_property_readonly_static(const char *name, const Getter &fget, const Extra& ...extra) {
1240         return def_property_readonly_static(name, cpp_function(fget), return_value_policy::reference, extra...);
1241     }
1242
1243     /// Uses cpp_function's return_value_policy by default
1244     template <typename... Extra>
1245     class_ &def_property_readonly_static(const char *name, const cpp_function &fget, const Extra& ...extra) {
1246         return def_property_static(name, fget, nullptr, extra...);
1247     }
1248
1249     /// Uses return_value_policy::reference_internal by default
1250     template <typename Getter, typename Setter, typename... Extra>
1251     class_ &def_property(const char *name, const Getter &fget, const Setter &fset, const Extra& ...extra) {
1252         return def_property(name, fget, cpp_function(method_adaptor<type>(fset)), extra...);
1253     }
1254     template <typename Getter, typename... Extra>
1255     class_ &def_property(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
1256         return def_property(name, cpp_function(method_adaptor<type>(fget)), fset,
1257                             return_value_policy::reference_internal, extra...);
1258     }
1259
1260     /// Uses cpp_function's return_value_policy by default
1261     template <typename... Extra>
1262     class_ &def_property(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1263         return def_property_static(name, fget, fset, is_method(*this), extra...);
1264     }
1265
1266     /// Uses return_value_policy::reference by default
1267     template <typename Getter, typename... Extra>
1268     class_ &def_property_static(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
1269         return def_property_static(name, cpp_function(fget), fset, return_value_policy::reference, extra...);
1270     }
1271
1272     /// Uses cpp_function's return_value_policy by default
1273     template <typename... Extra>
1274     class_ &def_property_static(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1275         static_assert( 0 == detail::constexpr_sum(std::is_base_of<arg, Extra>::value...),
1276                       "Argument annotations are not allowed for properties");
1277         auto rec_fget = get_function_record(fget), rec_fset = get_function_record(fset);
1278         auto *rec_active = rec_fget;
1279         if (rec_fget) {
1280            char *doc_prev = rec_fget->doc; /* 'extra' field may include a property-specific documentation string */
1281            detail::process_attributes<Extra...>::init(extra..., rec_fget);
1282            if (rec_fget->doc && rec_fget->doc != doc_prev) {
1283               free(doc_prev);
1284               rec_fget->doc = strdup(rec_fget->doc);
1285            }
1286         }
1287         if (rec_fset) {
1288             char *doc_prev = rec_fset->doc;
1289             detail::process_attributes<Extra...>::init(extra..., rec_fset);
1290             if (rec_fset->doc && rec_fset->doc != doc_prev) {
1291                 free(doc_prev);
1292                 rec_fset->doc = strdup(rec_fset->doc);
1293             }
1294             if (! rec_active) rec_active = rec_fset;
1295         }
1296         def_property_static_impl(name, fget, fset, rec_active);
1297         return *this;
1298     }
1299
1300 private:
1301     /// Initialize holder object, variant 1: object derives from enable_shared_from_this
1302     template <typename T>
1303     static void init_holder(detail::instance *inst, detail::value_and_holder &v_h,
1304             const holder_type * /* unused */, const std::enable_shared_from_this<T> * /* dummy */) {
1305         try {
1306             auto sh = std::dynamic_pointer_cast<typename holder_type::element_type>(
1307                     v_h.value_ptr<type>()->shared_from_this());
1308             if (sh) {
1309                 new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(sh));
1310                 v_h.set_holder_constructed();
1311             }
1312         } catch (const std::bad_weak_ptr &) {}
1313
1314         if (!v_h.holder_constructed() && inst->owned) {
1315             new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>());
1316             v_h.set_holder_constructed();
1317         }
1318     }
1319
1320     static void init_holder_from_existing(const detail::value_and_holder &v_h,
1321             const holder_type *holder_ptr, std::true_type /*is_copy_constructible*/) {
1322         new (std::addressof(v_h.holder<holder_type>())) holder_type(*reinterpret_cast<const holder_type *>(holder_ptr));
1323     }
1324
1325     static void init_holder_from_existing(const detail::value_and_holder &v_h,
1326             const holder_type *holder_ptr, std::false_type /*is_copy_constructible*/) {
1327         new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(*const_cast<holder_type *>(holder_ptr)));
1328     }
1329
1330     /// Initialize holder object, variant 2: try to construct from existing holder object, if possible
1331     static void init_holder(detail::instance *inst, detail::value_and_holder &v_h,
1332             const holder_type *holder_ptr, const void * /* dummy -- not enable_shared_from_this<T>) */) {
1333         if (holder_ptr) {
1334             init_holder_from_existing(v_h, holder_ptr, std::is_copy_constructible<holder_type>());
1335             v_h.set_holder_constructed();
1336         } else if (inst->owned || detail::always_construct_holder<holder_type>::value) {
1337             new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>());
1338             v_h.set_holder_constructed();
1339         }
1340     }
1341
1342     /// Performs instance initialization including constructing a holder and registering the known
1343     /// instance.  Should be called as soon as the `type` value_ptr is set for an instance.  Takes an
1344     /// optional pointer to an existing holder to use; if not specified and the instance is
1345     /// `.owned`, a new holder will be constructed to manage the value pointer.
1346     static void init_instance(detail::instance *inst, const void *holder_ptr) {
1347         auto v_h = inst->get_value_and_holder(detail::get_type_info(typeid(type)));
1348         if (!v_h.instance_registered()) {
1349             register_instance(inst, v_h.value_ptr(), v_h.type);
1350             v_h.set_instance_registered();
1351         }
1352         init_holder(inst, v_h, (const holder_type *) holder_ptr, v_h.value_ptr<type>());
1353     }
1354
1355     /// Deallocates an instance; via holder, if constructed; otherwise via operator delete.
1356     static void dealloc(detail::value_and_holder &v_h) {
1357         if (v_h.holder_constructed()) {
1358             v_h.holder<holder_type>().~holder_type();
1359             v_h.set_holder_constructed(false);
1360         }
1361         else {
1362             detail::call_operator_delete(v_h.value_ptr<type>(),
1363                 v_h.type->type_size,
1364                 v_h.type->type_align
1365             );
1366         }
1367         v_h.value_ptr() = nullptr;
1368     }
1369
1370     static detail::function_record *get_function_record(handle h) {
1371         h = detail::get_function(h);
1372         return h ? (detail::function_record *) reinterpret_borrow<capsule>(PyCFunction_GET_SELF(h.ptr()))
1373                  : nullptr;
1374     }
1375 };
1376
1377 /// Binds an existing constructor taking arguments Args...
1378 template <typename... Args> detail::initimpl::constructor<Args...> init() { return {}; }
1379 /// Like `init<Args...>()`, but the instance is always constructed through the alias class (even
1380 /// when not inheriting on the Python side).
1381 template <typename... Args> detail::initimpl::alias_constructor<Args...> init_alias() { return {}; }
1382
1383 /// Binds a factory function as a constructor
1384 template <typename Func, typename Ret = detail::initimpl::factory<Func>>
1385 Ret init(Func &&f) { return {std::forward<Func>(f)}; }
1386
1387 /// Dual-argument factory function: the first function is called when no alias is needed, the second
1388 /// when an alias is needed (i.e. due to python-side inheritance).  Arguments must be identical.
1389 template <typename CFunc, typename AFunc, typename Ret = detail::initimpl::factory<CFunc, AFunc>>
1390 Ret init(CFunc &&c, AFunc &&a) {
1391     return {std::forward<CFunc>(c), std::forward<AFunc>(a)};
1392 }
1393
1394 /// Binds pickling functions `__getstate__` and `__setstate__` and ensures that the type
1395 /// returned by `__getstate__` is the same as the argument accepted by `__setstate__`.
1396 template <typename GetState, typename SetState>
1397 detail::initimpl::pickle_factory<GetState, SetState> pickle(GetState &&g, SetState &&s) {
1398     return {std::forward<GetState>(g), std::forward<SetState>(s)};
1399 }
1400
1401 NAMESPACE_BEGIN(detail)
1402 struct enum_base {
1403     enum_base(handle base, handle parent) : m_base(base), m_parent(parent) { }
1404
1405     PYBIND11_NOINLINE void init(bool is_arithmetic, bool is_convertible) {
1406         m_base.attr("__entries") = dict();
1407         auto property = handle((PyObject *) &PyProperty_Type);
1408         auto static_property = handle((PyObject *) get_internals().static_property_type);
1409
1410         m_base.attr("__repr__") = cpp_function(
1411             [](handle arg) -> str {
1412                 handle type = arg.get_type();
1413                 object type_name = type.attr("__name__");
1414                 dict entries = type.attr("__entries");
1415                 for (const auto &kv : entries) {
1416                     object other = kv.second[int_(0)];
1417                     if (other.equal(arg))
1418                         return pybind11::str("{}.{}").format(type_name, kv.first);
1419                 }
1420                 return pybind11::str("{}.???").format(type_name);
1421             }, is_method(m_base)
1422         );
1423
1424         m_base.attr("name") = property(cpp_function(
1425             [](handle arg) -> str {
1426                 dict entries = arg.get_type().attr("__entries");
1427                 for (const auto &kv : entries) {
1428                     if (handle(kv.second[int_(0)]).equal(arg))
1429                         return pybind11::str(kv.first);
1430                 }
1431                 return "???";
1432             }, is_method(m_base)
1433         ));
1434
1435         m_base.attr("__doc__") = static_property(cpp_function(
1436             [](handle arg) -> std::string {
1437                 std::string docstring;
1438                 dict entries = arg.attr("__entries");
1439                 if (((PyTypeObject *) arg.ptr())->tp_doc)
1440                     docstring += std::string(((PyTypeObject *) arg.ptr())->tp_doc) + "\n\n";
1441                 docstring += "Members:";
1442                 for (const auto &kv : entries) {
1443                     auto key = std::string(pybind11::str(kv.first));
1444                     auto comment = kv.second[int_(1)];
1445                     docstring += "\n\n  " + key;
1446                     if (!comment.is_none())
1447                         docstring += " : " + (std::string) pybind11::str(comment);
1448                 }
1449                 return docstring;
1450             }
1451         ), none(), none(), "");
1452
1453         m_base.attr("__members__") = static_property(cpp_function(
1454             [](handle arg) -> dict {
1455                 dict entries = arg.attr("__entries"), m;
1456                 for (const auto &kv : entries)
1457                     m[kv.first] = kv.second[int_(0)];
1458                 return m;
1459             }), none(), none(), ""
1460         );
1461
1462         #define PYBIND11_ENUM_OP_STRICT(op, expr, strict_behavior)                     \
1463             m_base.attr(op) = cpp_function(                                            \
1464                 [](object a, object b) {                                               \
1465                     if (!a.get_type().is(b.get_type()))                                \
1466                         strict_behavior;                                               \
1467                     return expr;                                                       \
1468                 },                                                                     \
1469                 is_method(m_base))
1470
1471         #define PYBIND11_ENUM_OP_CONV(op, expr)                                        \
1472             m_base.attr(op) = cpp_function(                                            \
1473                 [](object a_, object b_) {                                             \
1474                     int_ a(a_), b(b_);                                                 \
1475                     return expr;                                                       \
1476                 },                                                                     \
1477                 is_method(m_base))
1478
1479         #define PYBIND11_ENUM_OP_CONV_LHS(op, expr)                                    \
1480             m_base.attr(op) = cpp_function(                                            \
1481                 [](object a_, object b) {                                              \
1482                     int_ a(a_);                                                        \
1483                     return expr;                                                       \
1484                 },                                                                     \
1485                 is_method(m_base))
1486
1487         if (is_convertible) {
1488             PYBIND11_ENUM_OP_CONV_LHS("__eq__", !b.is_none() &&  a.equal(b));
1489             PYBIND11_ENUM_OP_CONV_LHS("__ne__",  b.is_none() || !a.equal(b));
1490
1491             if (is_arithmetic) {
1492                 PYBIND11_ENUM_OP_CONV("__lt__",   a <  b);
1493                 PYBIND11_ENUM_OP_CONV("__gt__",   a >  b);
1494                 PYBIND11_ENUM_OP_CONV("__le__",   a <= b);
1495                 PYBIND11_ENUM_OP_CONV("__ge__",   a >= b);
1496                 PYBIND11_ENUM_OP_CONV("__and__",  a &  b);
1497                 PYBIND11_ENUM_OP_CONV("__rand__", a &  b);
1498                 PYBIND11_ENUM_OP_CONV("__or__",   a |  b);
1499                 PYBIND11_ENUM_OP_CONV("__ror__",  a |  b);
1500                 PYBIND11_ENUM_OP_CONV("__xor__",  a ^  b);
1501                 PYBIND11_ENUM_OP_CONV("__rxor__", a ^  b);
1502                 m_base.attr("__invert__") = cpp_function(
1503                     [](object arg) { return ~(int_(arg)); }, is_method(m_base));
1504             }
1505         } else {
1506             PYBIND11_ENUM_OP_STRICT("__eq__",  int_(a).equal(int_(b)), return false);
1507             PYBIND11_ENUM_OP_STRICT("__ne__", !int_(a).equal(int_(b)), return true);
1508
1509             if (is_arithmetic) {
1510                 #define PYBIND11_THROW throw type_error("Expected an enumeration of matching type!");
1511                 PYBIND11_ENUM_OP_STRICT("__lt__", int_(a) <  int_(b), PYBIND11_THROW);
1512                 PYBIND11_ENUM_OP_STRICT("__gt__", int_(a) >  int_(b), PYBIND11_THROW);
1513                 PYBIND11_ENUM_OP_STRICT("__le__", int_(a) <= int_(b), PYBIND11_THROW);
1514                 PYBIND11_ENUM_OP_STRICT("__ge__", int_(a) >= int_(b), PYBIND11_THROW);
1515                 #undef PYBIND11_THROW
1516             }
1517         }
1518
1519         #undef PYBIND11_ENUM_OP_CONV_LHS
1520         #undef PYBIND11_ENUM_OP_CONV
1521         #undef PYBIND11_ENUM_OP_STRICT
1522
1523         object getstate = cpp_function(
1524             [](object arg) { return int_(arg); }, is_method(m_base));
1525
1526         m_base.attr("__getstate__") = getstate;
1527         m_base.attr("__hash__") = getstate;
1528     }
1529
1530     PYBIND11_NOINLINE void value(char const* name_, object value, const char *doc = nullptr) {
1531         dict entries = m_base.attr("__entries");
1532         str name(name_);
1533         if (entries.contains(name)) {
1534             std::string type_name = (std::string) str(m_base.attr("__name__"));
1535             throw value_error(type_name + ": element \"" + std::string(name_) + "\" already exists!");
1536         }
1537
1538         entries[name] = std::make_pair(value, doc);
1539         m_base.attr(name) = value;
1540     }
1541
1542     PYBIND11_NOINLINE void export_values() {
1543         dict entries = m_base.attr("__entries");
1544         for (const auto &kv : entries)
1545             m_parent.attr(kv.first) = kv.second[int_(0)];
1546     }
1547
1548     handle m_base;
1549     handle m_parent;
1550 };
1551
1552 NAMESPACE_END(detail)
1553
1554 /// Binds C++ enumerations and enumeration classes to Python
1555 template <typename Type> class enum_ : public class_<Type> {
1556 public:
1557     using Base = class_<Type>;
1558     using Base::def;
1559     using Base::attr;
1560     using Base::def_property_readonly;
1561     using Base::def_property_readonly_static;
1562     using Scalar = typename std::underlying_type<Type>::type;
1563
1564     template <typename... Extra>
1565     enum_(const handle &scope, const char *name, const Extra&... extra)
1566       : class_<Type>(scope, name, extra...), m_base(*this, scope) {
1567         constexpr bool is_arithmetic = detail::any_of<std::is_same<arithmetic, Extra>...>::value;
1568         constexpr bool is_convertible = std::is_convertible<Type, Scalar>::value;
1569         m_base.init(is_arithmetic, is_convertible);
1570
1571         def(init([](Scalar i) { return static_cast<Type>(i); }));
1572         def("__int__", [](Type value) { return (Scalar) value; });
1573         #if PY_MAJOR_VERSION < 3
1574             def("__long__", [](Type value) { return (Scalar) value; });
1575         #endif
1576         #if PY_MAJOR_VERSION > 3 || (PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION >= 8)
1577             def("__index__", [](Type value) { return (Scalar) value; });
1578         #endif
1579
1580         cpp_function setstate(
1581             [](Type &value, Scalar arg) { value = static_cast<Type>(arg); },
1582             is_method(*this));
1583         attr("__setstate__") = setstate;
1584     }
1585
1586     /// Export enumeration entries into the parent scope
1587     enum_& export_values() {
1588         m_base.export_values();
1589         return *this;
1590     }
1591
1592     /// Add an enumeration entry
1593     enum_& value(char const* name, Type value, const char *doc = nullptr) {
1594         m_base.value(name, pybind11::cast(value, return_value_policy::copy), doc);
1595         return *this;
1596     }
1597
1598 private:
1599     detail::enum_base m_base;
1600 };
1601
1602 NAMESPACE_BEGIN(detail)
1603
1604
1605 inline void keep_alive_impl(handle nurse, handle patient) {
1606     if (!nurse || !patient)
1607         pybind11_fail("Could not activate keep_alive!");
1608
1609     if (patient.is_none() || nurse.is_none())
1610         return; /* Nothing to keep alive or nothing to be kept alive by */
1611
1612     auto tinfo = all_type_info(Py_TYPE(nurse.ptr()));
1613     if (!tinfo.empty()) {
1614         /* It's a pybind-registered type, so we can store the patient in the
1615          * internal list. */
1616         add_patient(nurse.ptr(), patient.ptr());
1617     }
1618     else {
1619         /* Fall back to clever approach based on weak references taken from
1620          * Boost.Python. This is not used for pybind-registered types because
1621          * the objects can be destroyed out-of-order in a GC pass. */
1622         cpp_function disable_lifesupport(
1623             [patient](handle weakref) { patient.dec_ref(); weakref.dec_ref(); });
1624
1625         weakref wr(nurse, disable_lifesupport);
1626
1627         patient.inc_ref(); /* reference patient and leak the weak reference */
1628         (void) wr.release();
1629     }
1630 }
1631
1632 PYBIND11_NOINLINE inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret) {
1633     auto get_arg = [&](size_t n) {
1634         if (n == 0)
1635             return ret;
1636         else if (n == 1 && call.init_self)
1637             return call.init_self;
1638         else if (n <= call.args.size())
1639             return call.args[n - 1];
1640         return handle();
1641     };
1642
1643     keep_alive_impl(get_arg(Nurse), get_arg(Patient));
1644 }
1645
1646 inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type) {
1647     auto res = get_internals().registered_types_py
1648 #ifdef __cpp_lib_unordered_map_try_emplace
1649         .try_emplace(type);
1650 #else
1651         .emplace(type, std::vector<detail::type_info *>());
1652 #endif
1653     if (res.second) {
1654         // New cache entry created; set up a weak reference to automatically remove it if the type
1655         // gets destroyed:
1656         weakref((PyObject *) type, cpp_function([type](handle wr) {
1657             get_internals().registered_types_py.erase(type);
1658             wr.dec_ref();
1659         })).release();
1660     }
1661
1662     return res;
1663 }
1664
1665 template <typename Iterator, typename Sentinel, bool KeyIterator, return_value_policy Policy>
1666 struct iterator_state {
1667     Iterator it;
1668     Sentinel end;
1669     bool first_or_done;
1670 };
1671
1672 NAMESPACE_END(detail)
1673
1674 /// Makes a python iterator from a first and past-the-end C++ InputIterator.
1675 template <return_value_policy Policy = return_value_policy::reference_internal,
1676           typename Iterator,
1677           typename Sentinel,
1678           typename ValueType = decltype(*std::declval<Iterator>()),
1679           typename... Extra>
1680 iterator make_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1681     typedef detail::iterator_state<Iterator, Sentinel, false, Policy> state;
1682
1683     if (!detail::get_type_info(typeid(state), false)) {
1684         class_<state>(handle(), "iterator", pybind11::module_local())
1685             .def("__iter__", [](state &s) -> state& { return s; })
1686             .def("__next__", [](state &s) -> ValueType {
1687                 if (!s.first_or_done)
1688                     ++s.it;
1689                 else
1690                     s.first_or_done = false;
1691                 if (s.it == s.end) {
1692                     s.first_or_done = true;
1693                     throw stop_iteration();
1694                 }
1695                 return *s.it;
1696             }, std::forward<Extra>(extra)..., Policy);
1697     }
1698
1699     return cast(state{first, last, true});
1700 }
1701
1702 /// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a
1703 /// first and past-the-end InputIterator.
1704 template <return_value_policy Policy = return_value_policy::reference_internal,
1705           typename Iterator,
1706           typename Sentinel,
1707           typename KeyType = decltype((*std::declval<Iterator>()).first),
1708           typename... Extra>
1709 iterator make_key_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1710     typedef detail::iterator_state<Iterator, Sentinel, true, Policy> state;
1711
1712     if (!detail::get_type_info(typeid(state), false)) {
1713         class_<state>(handle(), "iterator", pybind11::module_local())
1714             .def("__iter__", [](state &s) -> state& { return s; })
1715             .def("__next__", [](state &s) -> KeyType {
1716                 if (!s.first_or_done)
1717                     ++s.it;
1718                 else
1719                     s.first_or_done = false;
1720                 if (s.it == s.end) {
1721                     s.first_or_done = true;
1722                     throw stop_iteration();
1723                 }
1724                 return (*s.it).first;
1725             }, std::forward<Extra>(extra)..., Policy);
1726     }
1727
1728     return cast(state{first, last, true});
1729 }
1730
1731 /// Makes an iterator over values of an stl container or other 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_iterator(Type &value, Extra&&... extra) {
1735     return make_iterator<Policy>(std::begin(value), std::end(value), extra...);
1736 }
1737
1738 /// Makes an iterator over the keys (`.first`) of a stl map-like container supporting
1739 /// `std::begin()`/`std::end()`
1740 template <return_value_policy Policy = return_value_policy::reference_internal,
1741           typename Type, typename... Extra> iterator make_key_iterator(Type &value, Extra&&... extra) {
1742     return make_key_iterator<Policy>(std::begin(value), std::end(value), extra...);
1743 }
1744
1745 template <typename InputType, typename OutputType> void implicitly_convertible() {
1746     struct set_flag {
1747         bool &flag;
1748         set_flag(bool &flag) : flag(flag) { flag = true; }
1749         ~set_flag() { flag = false; }
1750     };
1751     auto implicit_caster = [](PyObject *obj, PyTypeObject *type) -> PyObject * {
1752         static bool currently_used = false;
1753         if (currently_used) // implicit conversions are non-reentrant
1754             return nullptr;
1755         set_flag flag_helper(currently_used);
1756         if (!detail::make_caster<InputType>().load(obj, false))
1757             return nullptr;
1758         tuple args(1);
1759         args[0] = obj;
1760         PyObject *result = PyObject_Call((PyObject *) type, args.ptr(), nullptr);
1761         if (result == nullptr)
1762             PyErr_Clear();
1763         return result;
1764     };
1765
1766     if (auto tinfo = detail::get_type_info(typeid(OutputType)))
1767         tinfo->implicit_conversions.push_back(implicit_caster);
1768     else
1769         pybind11_fail("implicitly_convertible: Unable to find type " + type_id<OutputType>());
1770 }
1771
1772 template <typename ExceptionTranslator>
1773 void register_exception_translator(ExceptionTranslator&& translator) {
1774     detail::get_internals().registered_exception_translators.push_front(
1775         std::forward<ExceptionTranslator>(translator));
1776 }
1777
1778 /**
1779  * Wrapper to generate a new Python exception type.
1780  *
1781  * This should only be used with PyErr_SetString for now.
1782  * It is not (yet) possible to use as a py::base.
1783  * Template type argument is reserved for future use.
1784  */
1785 template <typename type>
1786 class exception : public object {
1787 public:
1788     exception() = default;
1789     exception(handle scope, const char *name, PyObject *base = PyExc_Exception) {
1790         std::string full_name = scope.attr("__name__").cast<std::string>() +
1791                                 std::string(".") + name;
1792         m_ptr = PyErr_NewException(const_cast<char *>(full_name.c_str()), base, NULL);
1793         if (hasattr(scope, name))
1794             pybind11_fail("Error during initialization: multiple incompatible "
1795                           "definitions with name \"" + std::string(name) + "\"");
1796         scope.attr(name) = *this;
1797     }
1798
1799     // Sets the current python exception to this exception object with the given message
1800     void operator()(const char *message) {
1801         PyErr_SetString(m_ptr, message);
1802     }
1803 };
1804
1805 NAMESPACE_BEGIN(detail)
1806 // Returns a reference to a function-local static exception object used in the simple
1807 // register_exception approach below.  (It would be simpler to have the static local variable
1808 // directly in register_exception, but that makes clang <3.5 segfault - issue #1349).
1809 template <typename CppException>
1810 exception<CppException> &get_exception_object() { static exception<CppException> ex; return ex; }
1811 NAMESPACE_END(detail)
1812
1813 /**
1814  * Registers a Python exception in `m` of the given `name` and installs an exception translator to
1815  * translate the C++ exception to the created Python exception using the exceptions what() method.
1816  * This is intended for simple exception translations; for more complex translation, register the
1817  * exception object and translator directly.
1818  */
1819 template <typename CppException>
1820 exception<CppException> &register_exception(handle scope,
1821                                             const char *name,
1822                                             PyObject *base = PyExc_Exception) {
1823     auto &ex = detail::get_exception_object<CppException>();
1824     if (!ex) ex = exception<CppException>(scope, name, base);
1825
1826     register_exception_translator([](std::exception_ptr p) {
1827         if (!p) return;
1828         try {
1829             std::rethrow_exception(p);
1830         } catch (const CppException &e) {
1831             detail::get_exception_object<CppException>()(e.what());
1832         }
1833     });
1834     return ex;
1835 }
1836
1837 NAMESPACE_BEGIN(detail)
1838 PYBIND11_NOINLINE inline void print(tuple args, dict kwargs) {
1839     auto strings = tuple(args.size());
1840     for (size_t i = 0; i < args.size(); ++i) {
1841         strings[i] = str(args[i]);
1842     }
1843     auto sep = kwargs.contains("sep") ? kwargs["sep"] : cast(" ");
1844     auto line = sep.attr("join")(strings);
1845
1846     object file;
1847     if (kwargs.contains("file")) {
1848         file = kwargs["file"].cast<object>();
1849     } else {
1850         try {
1851             file = module::import("sys").attr("stdout");
1852         } catch (const error_already_set &) {
1853             /* If print() is called from code that is executed as
1854                part of garbage collection during interpreter shutdown,
1855                importing 'sys' can fail. Give up rather than crashing the
1856                interpreter in this case. */
1857             return;
1858         }
1859     }
1860
1861     auto write = file.attr("write");
1862     write(line);
1863     write(kwargs.contains("end") ? kwargs["end"] : cast("\n"));
1864
1865     if (kwargs.contains("flush") && kwargs["flush"].cast<bool>())
1866         file.attr("flush")();
1867 }
1868 NAMESPACE_END(detail)
1869
1870 template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
1871 void print(Args &&...args) {
1872     auto c = detail::collect_arguments<policy>(std::forward<Args>(args)...);
1873     detail::print(c.args(), c.kwargs());
1874 }
1875
1876 #if defined(WITH_THREAD) && !defined(PYPY_VERSION)
1877
1878 /* The functions below essentially reproduce the PyGILState_* API using a RAII
1879  * pattern, but there are a few important differences:
1880  *
1881  * 1. When acquiring the GIL from an non-main thread during the finalization
1882  *    phase, the GILState API blindly terminates the calling thread, which
1883  *    is often not what is wanted. This API does not do this.
1884  *
1885  * 2. The gil_scoped_release function can optionally cut the relationship
1886  *    of a PyThreadState and its associated thread, which allows moving it to
1887  *    another thread (this is a fairly rare/advanced use case).
1888  *
1889  * 3. The reference count of an acquired thread state can be controlled. This
1890  *    can be handy to prevent cases where callbacks issued from an external
1891  *    thread would otherwise constantly construct and destroy thread state data
1892  *    structures.
1893  *
1894  * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an
1895  * example which uses features 2 and 3 to migrate the Python thread of
1896  * execution to another thread (to run the event loop on the original thread,
1897  * in this case).
1898  */
1899
1900 class gil_scoped_acquire {
1901 public:
1902     PYBIND11_NOINLINE gil_scoped_acquire() {
1903         auto const &internals = detail::get_internals();
1904         tstate = (PyThreadState *) PYBIND11_TLS_GET_VALUE(internals.tstate);
1905
1906         if (!tstate) {
1907             /* Check if the GIL was acquired using the PyGILState_* API instead (e.g. if
1908                calling from a Python thread). Since we use a different key, this ensures
1909                we don't create a new thread state and deadlock in PyEval_AcquireThread
1910                below. Note we don't save this state with internals.tstate, since we don't
1911                create it we would fail to clear it (its reference count should be > 0). */
1912             tstate = PyGILState_GetThisThreadState();
1913         }
1914
1915         if (!tstate) {
1916             tstate = PyThreadState_New(internals.istate);
1917             #if !defined(NDEBUG)
1918                 if (!tstate)
1919                     pybind11_fail("scoped_acquire: could not create thread state!");
1920             #endif
1921             tstate->gilstate_counter = 0;
1922             PYBIND11_TLS_REPLACE_VALUE(internals.tstate, tstate);
1923         } else {
1924             release = detail::get_thread_state_unchecked() != tstate;
1925         }
1926
1927         if (release) {
1928             /* Work around an annoying assertion in PyThreadState_Swap */
1929             #if defined(Py_DEBUG)
1930                 PyInterpreterState *interp = tstate->interp;
1931                 tstate->interp = nullptr;
1932             #endif
1933             PyEval_AcquireThread(tstate);
1934             #if defined(Py_DEBUG)
1935                 tstate->interp = interp;
1936             #endif
1937         }
1938
1939         inc_ref();
1940     }
1941
1942     void inc_ref() {
1943         ++tstate->gilstate_counter;
1944     }
1945
1946     PYBIND11_NOINLINE void dec_ref() {
1947         --tstate->gilstate_counter;
1948         #if !defined(NDEBUG)
1949             if (detail::get_thread_state_unchecked() != tstate)
1950                 pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!");
1951             if (tstate->gilstate_counter < 0)
1952                 pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!");
1953         #endif
1954         if (tstate->gilstate_counter == 0) {
1955             #if !defined(NDEBUG)
1956                 if (!release)
1957                     pybind11_fail("scoped_acquire::dec_ref(): internal error!");
1958             #endif
1959             PyThreadState_Clear(tstate);
1960             PyThreadState_DeleteCurrent();
1961             PYBIND11_TLS_DELETE_VALUE(detail::get_internals().tstate);
1962             release = false;
1963         }
1964     }
1965
1966     PYBIND11_NOINLINE ~gil_scoped_acquire() {
1967         dec_ref();
1968         if (release)
1969            PyEval_SaveThread();
1970     }
1971 private:
1972     PyThreadState *tstate = nullptr;
1973     bool release = true;
1974 };
1975
1976 class gil_scoped_release {
1977 public:
1978     explicit gil_scoped_release(bool disassoc = false) : disassoc(disassoc) {
1979         // `get_internals()` must be called here unconditionally in order to initialize
1980         // `internals.tstate` for subsequent `gil_scoped_acquire` calls. Otherwise, an
1981         // initialization race could occur as multiple threads try `gil_scoped_acquire`.
1982         const auto &internals = detail::get_internals();
1983         tstate = PyEval_SaveThread();
1984         if (disassoc) {
1985             auto key = internals.tstate;
1986             PYBIND11_TLS_DELETE_VALUE(key);
1987         }
1988     }
1989     ~gil_scoped_release() {
1990         if (!tstate)
1991             return;
1992         PyEval_RestoreThread(tstate);
1993         if (disassoc) {
1994             auto key = detail::get_internals().tstate;
1995             PYBIND11_TLS_REPLACE_VALUE(key, tstate);
1996         }
1997     }
1998 private:
1999     PyThreadState *tstate;
2000     bool disassoc;
2001 };
2002 #elif defined(PYPY_VERSION)
2003 class gil_scoped_acquire {
2004     PyGILState_STATE state;
2005 public:
2006     gil_scoped_acquire() { state = PyGILState_Ensure(); }
2007     ~gil_scoped_acquire() { PyGILState_Release(state); }
2008 };
2009
2010 class gil_scoped_release {
2011     PyThreadState *state;
2012 public:
2013     gil_scoped_release() { state = PyEval_SaveThread(); }
2014     ~gil_scoped_release() { PyEval_RestoreThread(state); }
2015 };
2016 #else
2017 class gil_scoped_acquire { };
2018 class gil_scoped_release { };
2019 #endif
2020
2021 error_already_set::~error_already_set() {
2022     if (m_type) {
2023         gil_scoped_acquire gil;
2024         error_scope scope;
2025         m_type.release().dec_ref();
2026         m_value.release().dec_ref();
2027         m_trace.release().dec_ref();
2028     }
2029 }
2030
2031 inline function get_type_overload(const void *this_ptr, const detail::type_info *this_type, const char *name)  {
2032     handle self = detail::get_object_handle(this_ptr, this_type);
2033     if (!self)
2034         return function();
2035     handle type = self.get_type();
2036     auto key = std::make_pair(type.ptr(), name);
2037
2038     /* Cache functions that aren't overloaded in Python to avoid
2039        many costly Python dictionary lookups below */
2040     auto &cache = detail::get_internals().inactive_overload_cache;
2041     if (cache.find(key) != cache.end())
2042         return function();
2043
2044     function overload = getattr(self, name, function());
2045     if (overload.is_cpp_function()) {
2046         cache.insert(key);
2047         return function();
2048     }
2049
2050     /* Don't call dispatch code if invoked from overridden function.
2051        Unfortunately this doesn't work on PyPy. */
2052 #if !defined(PYPY_VERSION)
2053     PyFrameObject *frame = PyThreadState_Get()->frame;
2054     if (frame && (std::string) str(frame->f_code->co_name) == name &&
2055         frame->f_code->co_argcount > 0) {
2056         PyFrame_FastToLocals(frame);
2057         PyObject *self_caller = PyDict_GetItem(
2058             frame->f_locals, PyTuple_GET_ITEM(frame->f_code->co_varnames, 0));
2059         if (self_caller == self.ptr())
2060             return function();
2061     }
2062 #else
2063     /* PyPy currently doesn't provide a detailed cpyext emulation of
2064        frame objects, so we have to emulate this using Python. This
2065        is going to be slow..*/
2066     dict d; d["self"] = self; d["name"] = pybind11::str(name);
2067     PyObject *result = PyRun_String(
2068         "import inspect\n"
2069         "frame = inspect.currentframe()\n"
2070         "if frame is not None:\n"
2071         "    frame = frame.f_back\n"
2072         "    if frame is not None and str(frame.f_code.co_name) == name and "
2073         "frame.f_code.co_argcount > 0:\n"
2074         "        self_caller = frame.f_locals[frame.f_code.co_varnames[0]]\n"
2075         "        if self_caller == self:\n"
2076         "            self = None\n",
2077         Py_file_input, d.ptr(), d.ptr());
2078     if (result == nullptr)
2079         throw error_already_set();
2080     if (d["self"].is_none())
2081         return function();
2082     Py_DECREF(result);
2083 #endif
2084
2085     return overload;
2086 }
2087
2088 /** \rst
2089   Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
2090
2091   :this_ptr: The pointer to the object the overload should be retrieved for. This should be the first
2092                    non-trampoline class encountered in the inheritance chain.
2093   :name: The name of the overloaded Python method to retrieve.
2094   :return: The Python method by this name from the object or an empty function wrapper.
2095  \endrst */
2096 template <class T> function get_overload(const T *this_ptr, const char *name) {
2097     auto tinfo = detail::get_type_info(typeid(T));
2098     return tinfo ? get_type_overload(this_ptr, tinfo, name) : function();
2099 }
2100
2101 #define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) { \
2102         pybind11::gil_scoped_acquire gil; \
2103         pybind11::function overload = pybind11::get_overload(static_cast<const cname *>(this), name); \
2104         if (overload) { \
2105             auto o = overload(__VA_ARGS__); \
2106             if (pybind11::detail::cast_is_temporary_value_reference<ret_type>::value) { \
2107                 static pybind11::detail::overload_caster_t<ret_type> caster; \
2108                 return pybind11::detail::cast_ref<ret_type>(std::move(o), caster); \
2109             } \
2110             else return pybind11::detail::cast_safe<ret_type>(std::move(o)); \
2111         } \
2112     }
2113
2114 /** \rst
2115     Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named 'fn'
2116     from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2117     the appropriate type. See :ref:`overriding_virtuals` for more information. This macro should be used when the method
2118     name in C is not the same as the method name in Python. For example with `__str__`.
2119
2120     .. code-block:: cpp
2121
2122       std::string toString() override {
2123         PYBIND11_OVERLOAD_NAME(
2124             std::string, // Return type (ret_type)
2125             Animal,      // Parent class (cname)
2126             toString,    // Name of function in C++ (name)
2127             "__str__",   // Name of method in Python (fn)
2128         );
2129       }
2130 \endrst */
2131 #define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \
2132     PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2133     return cname::fn(__VA_ARGS__)
2134
2135 /** \rst
2136     Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD_NAME`, except that it
2137     throws if no overload can be found.
2138 \endrst */
2139 #define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \
2140     PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2141     pybind11::pybind11_fail("Tried to call pure virtual function \"" PYBIND11_STRINGIFY(cname) "::" name "\"");
2142
2143 /** \rst
2144     Macro to populate the virtual method in the trampoline class. This macro tries to look up the method
2145     from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2146     the appropriate type. This macro should be used if the method name in C and in Python are identical.
2147     See :ref:`overriding_virtuals` for more information.
2148
2149     .. code-block:: cpp
2150
2151       class PyAnimal : public Animal {
2152       public:
2153           // Inherit the constructors
2154           using Animal::Animal;
2155
2156           // Trampoline (need one for each virtual function)
2157           std::string go(int n_times) override {
2158               PYBIND11_OVERLOAD_PURE(
2159                   std::string, // Return type (ret_type)
2160                   Animal,      // Parent class (cname)
2161                   go,          // Name of function in C++ (must match Python name) (fn)
2162                   n_times      // Argument(s) (...)
2163               );
2164           }
2165       };
2166 \endrst */
2167 #define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \
2168     PYBIND11_OVERLOAD_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2169
2170 /** \rst
2171     Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD`, except that it throws
2172     if no overload can be found.
2173 \endrst */
2174 #define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \
2175     PYBIND11_OVERLOAD_PURE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2176
2177 NAMESPACE_END(PYBIND11_NAMESPACE)
2178
2179 #if defined(_MSC_VER) && !defined(__INTEL_COMPILER)
2180 #  pragma warning(pop)
2181 #elif defined(__GNUG__) && !defined(__clang__)
2182 #  pragma GCC diagnostic pop
2183 #endif