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