pybind11.h 77.1 KB
Newer Older
Wenzel Jakob's avatar
Wenzel Jakob committed
1
/*
Wenzel Jakob's avatar
Wenzel Jakob committed
2
3
    pybind11/pybind11.h: Main header file of the C++11 python
    binding generator library
Wenzel Jakob's avatar
Wenzel Jakob committed
4

5
    Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
Wenzel Jakob's avatar
Wenzel Jakob committed
6
7
8
9
10

    All rights reserved. Use of this source code is governed by a
    BSD-style license that can be found in the LICENSE file.
*/

11
#pragma once
Wenzel Jakob's avatar
Wenzel Jakob committed
12
13

#if defined(_MSC_VER)
Wenzel Jakob's avatar
Wenzel Jakob committed
14
#  pragma warning(push)
15
#  pragma warning(disable: 4100) // warning C4100: Unreferenced formal parameter
Wenzel Jakob's avatar
Wenzel Jakob committed
16
#  pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
17
#  pragma warning(disable: 4512) // warning C4512: Assignment operator was implicitly defined as deleted
Wenzel Jakob's avatar
Wenzel Jakob committed
18
19
#  pragma warning(disable: 4800) // warning C4800: 'int': forcing value to bool 'true' or 'false' (performance warning)
#  pragma warning(disable: 4996) // warning C4996: The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name
Wenzel Jakob's avatar
Wenzel Jakob committed
20
#  pragma warning(disable: 4702) // warning C4702: unreachable code
21
#  pragma warning(disable: 4522) // warning C4522: multiple assignment operators specified
22
#elif defined(__INTEL_COMPILER)
Ben Pritchard's avatar
Ben Pritchard committed
23
#  pragma warning(push)
24
25
26
#  pragma warning(disable: 186)   // pointless comparison of unsigned integer with zero
#  pragma warning(disable: 1334)  // the "template" keyword used for syntactic disambiguation may only be used within a template
#  pragma warning(disable: 2196)  // warning #2196: routine is both "inline" and "noinline"
27
#elif defined(__GNUG__) && !defined(__clang__)
Wenzel Jakob's avatar
Wenzel Jakob committed
28
29
30
31
#  pragma GCC diagnostic push
#  pragma GCC diagnostic ignored "-Wunused-but-set-parameter"
#  pragma GCC diagnostic ignored "-Wunused-but-set-variable"
#  pragma GCC diagnostic ignored "-Wmissing-field-initializers"
Wenzel Jakob's avatar
Wenzel Jakob committed
32
33
#  pragma GCC diagnostic ignored "-Wstrict-aliasing"
#  pragma GCC diagnostic ignored "-Wattributes"
34
35
36
#  if __GNUC__ >= 7
#    pragma GCC diagnostic ignored "-Wnoexcept-type"
#  endif
Wenzel Jakob's avatar
Wenzel Jakob committed
37
38
#endif

Wenzel Jakob's avatar
Wenzel Jakob committed
39
#include "attr.h"
40
#include "options.h"
41
#include "class_support.h"
Wenzel Jakob's avatar
Wenzel Jakob committed
42

43
NAMESPACE_BEGIN(pybind11)
Wenzel Jakob's avatar
Wenzel Jakob committed
44

Wenzel Jakob's avatar
Wenzel Jakob committed
45
/// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object
46
class cpp_function : public function {
Wenzel Jakob's avatar
Wenzel Jakob committed
47
public:
48
    cpp_function() { }
Wenzel Jakob's avatar
Wenzel Jakob committed
49

50
    /// Construct a cpp_function from a vanilla function pointer
51
52
    template <typename Return, typename... Args, typename... Extra>
    cpp_function(Return (*f)(Args...), const Extra&... extra) {
53
        initialize(f, f, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
54
55
    }

56
    /// Construct a cpp_function from a lambda function (possibly with internal state)
57
58
59
60
61
62
    template <typename Func, typename... Extra, typename = detail::enable_if_t<
        detail::satisfies_none_of<
            typename std::remove_reference<Func>::type,
            std::is_function, std::is_pointer, std::is_member_pointer
        >::value>
    >
63
    cpp_function(Func &&f, const Extra&... extra) {
64
        using FuncType = typename detail::remove_class<decltype(&std::remove_reference<Func>::type::operator())>::type;
65
        initialize(std::forward<Func>(f),
66
                   (FuncType *) nullptr, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
67
68
    }

69
    /// Construct a cpp_function from a class method (non-const)
70
71
    template <typename Return, typename Class, typename... Arg, typename... Extra>
    cpp_function(Return (Class::*f)(Arg...), const Extra&... extra) {
72
        initialize([f](Class *c, Arg... args) -> Return { return (c->*f)(args...); },
73
                   (Return (*) (Class *, Arg...)) nullptr, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
74
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
75

76
    /// Construct a cpp_function from a class method (const)
77
78
    template <typename Return, typename Class, typename... Arg, typename... Extra>
    cpp_function(Return (Class::*f)(Arg...) const, const Extra&... extra) {
79
        initialize([f](const Class *c, Arg... args) -> Return { return (c->*f)(args...); },
80
                   (Return (*)(const Class *, Arg ...)) nullptr, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
81
82
    }

83
    /// Return the function name
Wenzel Jakob's avatar
Wenzel Jakob committed
84
    object name() const { return attr("__name__"); }
85

86
protected:
87
88
89
90
91
    /// Space optimization: don't inline this frequently instantiated fragment
    PYBIND11_NOINLINE detail::function_record *make_function_record() {
        return new detail::function_record();
    }

92
    /// Special internal constructor for functors, lambda functions, etc.
93
94
    template <typename Func, typename Return, typename... Args, typename... Extra>
    void initialize(Func &&f, Return (*)(Args...), const Extra&... extra) {
95

96
        struct capture { typename std::remove_reference<Func>::type f; };
Wenzel Jakob's avatar
Wenzel Jakob committed
97

98
        /* Store the function including any extra state it might have (e.g. a lambda capture object) */
99
        auto rec = make_function_record();
100

101
102
        /* Store the capture object directly in the function record if there is enough space */
        if (sizeof(capture) <= sizeof(rec->data)) {
103
104
105
            /* Without these pragmas, GCC warns that there might not be
               enough space to use the placement new operator. However, the
               'if' statement above ensures that this is the case. */
106
#if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
107
108
109
#  pragma GCC diagnostic push
#  pragma GCC diagnostic ignored "-Wplacement-new"
#endif
110
            new ((capture *) &rec->data) capture { std::forward<Func>(f) };
111
#if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
112
113
#  pragma GCC diagnostic pop
#endif
114
115
116
117
118
119
            if (!std::is_trivially_destructible<Func>::value)
                rec->free_data = [](detail::function_record *r) { ((capture *) &r->data)->~capture(); };
        } else {
            rec->data[0] = new capture { std::forward<Func>(f) };
            rec->free_data = [](detail::function_record *r) { delete ((capture *) r->data[0]); };
        }
120

121
        /* Type casters for the function arguments and return value */
122
123
124
125
        using cast_in = detail::argument_loader<Args...>;
        using cast_out = detail::make_caster<
            detail::conditional_t<std::is_void<Return>::value, detail::void_type, Return>
        >;
Wenzel Jakob's avatar
Wenzel Jakob committed
126

127
        static_assert(detail::expected_num_args<Extra...>(sizeof...(Args), cast_in::has_args, cast_in::has_kwargs),
128
                      "The number of argument annotations does not match the number of function arguments");
129

130
        /* Dispatch code which converts function arguments and performs the actual function call */
131
        rec->impl = [](detail::function_call &call) -> handle {
132
            cast_in args_converter;
133
134

            /* Try to cast the function arguments into the C++ domain */
135
            if (!args_converter.load_args(call))
136
137
                return PYBIND11_TRY_NEXT_OVERLOAD;

Wenzel Jakob's avatar
Wenzel Jakob committed
138
            /* Invoke call policy pre-call hook */
139
            detail::process_attributes<Extra...>::precall(call);
140
141

            /* Get a pointer to the capture object */
142
143
144
            auto data = (sizeof(capture) <= sizeof(call.func.data)
                         ? &call.func.data : call.func.data[0]);
            capture *cap = const_cast<capture *>(reinterpret_cast<const capture *>(data));
145

146
147
            /* Override policy for rvalues -- usually to enforce rvp::move on an rvalue */
            const auto policy = detail::return_value_policy_override<Return>::policy(call.func.policy);
148

Dean Moldovan's avatar
Dean Moldovan committed
149
150
151
            /* Function scope guard -- defaults to the compile-to-nothing `void_type` */
            using Guard = detail::extract_guard_t<Extra...>;

152
            /* Perform the function call */
Dean Moldovan's avatar
Dean Moldovan committed
153
            handle result = cast_out::cast(args_converter.template call<Return, Guard>(cap->f),
154
                                           policy, call.parent);
Wenzel Jakob's avatar
Wenzel Jakob committed
155
156

            /* Invoke call policy post-call hook */
157
            detail::process_attributes<Extra...>::postcall(call, result);
158

159
            return result;
Wenzel Jakob's avatar
Wenzel Jakob committed
160
161
        };

Wenzel Jakob's avatar
Wenzel Jakob committed
162
163
        /* Process any user-provided function attributes */
        detail::process_attributes<Extra...>::init(extra..., rec);
164
165

        /* Generate a readable signature describing the function's arguments and return value types */
166
        using detail::descr; using detail::_;
167
        PYBIND11_DESCR signature = _("(") + cast_in::arg_names() + _(") -> ") + cast_out::name();
168
169

        /* Register the function with Python from generic (non-templated) code */
170
        initialize_generic(rec, signature.text(), signature.types(), sizeof...(Args));
171
172
173

        if (cast_in::has_args) rec->has_args = true;
        if (cast_in::has_kwargs) rec->has_kwargs = true;
174
175

        /* Stash some additional information used by an important optimization in 'functional.h' */
176
        using FunctionType = Return (*)(Args...);
177
178
179
180
181
        constexpr bool is_function_ptr =
            std::is_convertible<Func, FunctionType>::value &&
            sizeof(capture) == sizeof(void *);
        if (is_function_ptr) {
            rec->is_stateless = true;
182
            rec->data[1] = const_cast<void *>(reinterpret_cast<const void *>(&typeid(FunctionType)));
183
        }
184
185
    }

186
    /// Register a function call with Python (generic non-templated code goes here)
187
    void initialize_generic(detail::function_record *rec, const char *text,
188
                            const std::type_info *const *types, size_t args) {
Wenzel Jakob's avatar
Wenzel Jakob committed
189

190
        /* Create copies of all referenced C-style strings */
Wenzel Jakob's avatar
Wenzel Jakob committed
191
192
193
        rec->name = strdup(rec->name ? rec->name : "");
        if (rec->doc) rec->doc = strdup(rec->doc);
        for (auto &a: rec->args) {
194
195
196
197
198
            if (a.name)
                a.name = strdup(a.name);
            if (a.descr)
                a.descr = strdup(a.descr);
            else if (a.value)
199
                a.descr = strdup(a.value.attr("__repr__")().cast<std::string>().c_str());
200
        }
201

202
203
204
205
206
207
208
209
210
        /* Generate a proper function signature */
        std::string signature;
        size_t type_depth = 0, char_index = 0, type_index = 0, arg_index = 0;
        while (true) {
            char c = text[char_index++];
            if (c == '\0')
                break;

            if (c == '{') {
211
                // Write arg name for everything except *args, **kwargs and return type.
212
                if (type_depth == 0 && text[char_index] != '*' && arg_index < args) {
213
                    if (!rec->args.empty() && rec->args[arg_index].name) {
214
                        signature += rec->args[arg_index].name;
215
                    } else if (arg_index == 0 && rec->is_method) {
216
217
                        signature += "self";
                    } else {
218
                        signature += "arg" + std::to_string(arg_index - (rec->is_method ? 1 : 0));
219
220
                    }
                    signature += ": ";
221
222
223
224
                }
                ++type_depth;
            } else if (c == '}') {
                --type_depth;
225
                if (type_depth == 0) {
226
227
                    if (arg_index < rec->args.size() && rec->args[arg_index].descr) {
                        signature += "=";
Wenzel Jakob's avatar
Wenzel Jakob committed
228
                        signature += rec->args[arg_index].descr;
229
230
231
232
233
                    }
                    arg_index++;
                }
            } else if (c == '%') {
                const std::type_info *t = types[type_index++];
234
                if (!t)
235
                    pybind11_fail("Internal error while parsing type signature (1)");
236
                if (auto tinfo = detail::get_type_info(*t)) {
Wenzel Jakob's avatar
Wenzel Jakob committed
237
238
239
240
241
#if defined(PYPY_VERSION)
                    signature += handle((PyObject *) tinfo->type)
                                     .attr("__module__")
                                     .cast<std::string>() + ".";
#endif
242
                    signature += tinfo->type->tp_name;
243
244
245
246
247
248
249
250
251
                } else {
                    std::string tname(t->name());
                    detail::clean_type_id(tname);
                    signature += tname;
                }
            } else {
                signature += c;
            }
        }
252
        if (type_depth != 0 || types[type_index] != nullptr)
253
            pybind11_fail("Internal error while parsing type signature (2)");
254

255
        #if !defined(PYBIND11_CONSTEXPR_DESCR)
256
257
258
            delete[] types;
            delete[] text;
        #endif
259

260
#if PY_MAJOR_VERSION < 3
Wenzel Jakob's avatar
Wenzel Jakob committed
261
262
263
        if (strcmp(rec->name, "__next__") == 0) {
            std::free(rec->name);
            rec->name = strdup("next");
264
265
266
        } else if (strcmp(rec->name, "__bool__") == 0) {
            std::free(rec->name);
            rec->name = strdup("__nonzero__");
267
        }
268
#endif
Wenzel Jakob's avatar
Wenzel Jakob committed
269
270
        rec->signature = strdup(signature.c_str());
        rec->args.shrink_to_fit();
271
        rec->is_constructor = !strcmp(rec->name, "__init__") || !strcmp(rec->name, "__setstate__");
272
        rec->nargs = (std::uint16_t) args;
273

274
275
        if (rec->sibling && PYBIND11_INSTANCE_METHOD_CHECK(rec->sibling.ptr()))
            rec->sibling = PYBIND11_INSTANCE_METHOD_GET_FUNCTION(rec->sibling.ptr());
276

Wenzel Jakob's avatar
Wenzel Jakob committed
277
        detail::function_record *chain = nullptr, *chain_start = rec;
278
279
        if (rec->sibling) {
            if (PyCFunction_Check(rec->sibling.ptr())) {
Wenzel Jakob's avatar
Wenzel Jakob committed
280
                auto rec_capsule = reinterpret_borrow<capsule>(PyCFunction_GET_SELF(rec->sibling.ptr()));
281
282
283
                chain = (detail::function_record *) rec_capsule;
                /* Never append a method to an overload chain of a parent class;
                   instead, hide the parent's overloads in this case */
284
                if (!chain->scope.is(rec->scope))
285
286
287
288
289
290
                    chain = nullptr;
            }
            // Don't trigger for things like the default __init__, which are wrapper_descriptors that we are intentionally replacing
            else if (!rec->sibling.is_none() && rec->name[0] != '_')
                pybind11_fail("Cannot overload existing non-function object \"" + std::string(rec->name) +
                        "\" with a function of the same name");
291
292
        }

Wenzel Jakob's avatar
Wenzel Jakob committed
293
        if (!chain) {
294
            /* No existing overload was found, create a new function object */
Wenzel Jakob's avatar
Wenzel Jakob committed
295
296
297
298
299
            rec->def = new PyMethodDef();
            memset(rec->def, 0, sizeof(PyMethodDef));
            rec->def->ml_name = rec->name;
            rec->def->ml_meth = reinterpret_cast<PyCFunction>(*dispatcher);
            rec->def->ml_flags = METH_VARARGS | METH_KEYWORDS;
300

301
302
            capsule rec_capsule(rec, [](void *ptr) {
                destruct((detail::function_record *) ptr);
303
            });
304
305
306

            object scope_module;
            if (rec->scope) {
307
308
309
310
311
                if (hasattr(rec->scope, "__module__")) {
                    scope_module = rec->scope.attr("__module__");
                } else if (hasattr(rec->scope, "__name__")) {
                    scope_module = rec->scope.attr("__name__");
                }
312
313
314
            }

            m_ptr = PyCFunction_NewEx(rec->def, rec_capsule.ptr(), scope_module.ptr());
Wenzel Jakob's avatar
Wenzel Jakob committed
315
            if (!m_ptr)
316
                pybind11_fail("cpp_function::cpp_function(): Could not allocate function object");
Wenzel Jakob's avatar
Wenzel Jakob committed
317
        } else {
318
            /* Append at the end of the overload chain */
Wenzel Jakob's avatar
Wenzel Jakob committed
319
            m_ptr = rec->sibling.ptr();
Wenzel Jakob's avatar
Wenzel Jakob committed
320
            inc_ref();
Wenzel Jakob's avatar
Wenzel Jakob committed
321
            chain_start = chain;
322
323
324
325
326
327
328
329
330
            if (chain->is_method != rec->is_method)
                pybind11_fail("overloading a method with both static and instance methods is not supported; "
                    #if defined(NDEBUG)
                        "compile in debug mode for more details"
                    #else
                        "error while attempting to bind " + std::string(rec->is_method ? "instance" : "static") + " method " +
                        std::string(pybind11::str(rec->scope.attr("__name__"))) + "." + std::string(rec->name) + signature
                    #endif
                );
Wenzel Jakob's avatar
Wenzel Jakob committed
331
332
333
            while (chain->next)
                chain = chain->next;
            chain->next = rec;
Wenzel Jakob's avatar
Wenzel Jakob committed
334
        }
335

Wenzel Jakob's avatar
Wenzel Jakob committed
336
        std::string signatures;
337
        int index = 0;
Wenzel Jakob's avatar
Wenzel Jakob committed
338
        /* Create a nice pydoc rec including all signatures and
339
           docstrings of the functions in the overload chain */
340
        if (chain && options::show_function_signatures()) {
341
342
343
344
345
346
            // First a generic signature
            signatures += rec->name;
            signatures += "(*args, **kwargs)\n";
            signatures += "Overloaded function.\n\n";
        }
        // Then specific overload signatures
347
        bool first_user_def = true;
Wenzel Jakob's avatar
Wenzel Jakob committed
348
        for (auto it = chain_start; it != nullptr; it = it->next) {
349
            if (options::show_function_signatures()) {
350
                if (index > 0) signatures += "\n";
351
352
353
354
                if (chain)
                    signatures += std::to_string(++index) + ". ";
                signatures += rec->name;
                signatures += it->signature;
355
                signatures += "\n";
356
357
            }
            if (it->doc && strlen(it->doc) > 0 && options::show_user_defined_docstrings()) {
358
359
360
361
362
363
                // If we're appending another docstring, and aren't printing function signatures, we
                // need to append a newline first:
                if (!options::show_function_signatures()) {
                    if (first_user_def) first_user_def = false;
                    else signatures += "\n";
                }
364
                if (options::show_function_signatures()) signatures += "\n";
365
                signatures += it->doc;
366
                if (options::show_function_signatures()) signatures += "\n";
367
            }
Wenzel Jakob's avatar
Wenzel Jakob committed
368
        }
Wenzel Jakob's avatar
Wenzel Jakob committed
369
370

        /* Install docstring */
Wenzel Jakob's avatar
Wenzel Jakob committed
371
372
        PyCFunctionObject *func = (PyCFunctionObject *) m_ptr;
        if (func->m_ml->ml_doc)
373
            std::free(const_cast<char *>(func->m_ml->ml_doc));
Wenzel Jakob's avatar
Wenzel Jakob committed
374
        func->m_ml->ml_doc = strdup(signatures.c_str());
Wenzel Jakob's avatar
Wenzel Jakob committed
375

376
377
        if (rec->is_method) {
            m_ptr = PYBIND11_INSTANCE_METHOD_NEW(m_ptr, rec->scope.ptr());
Wenzel Jakob's avatar
Wenzel Jakob committed
378
            if (!m_ptr)
379
                pybind11_fail("cpp_function::cpp_function(): Could not allocate instance method object");
Wenzel Jakob's avatar
Wenzel Jakob committed
380
381
382
            Py_DECREF(func);
        }
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
383
384
385
386
387
388

    /// When a cpp_function is GCed, release any memory allocated by pybind11
    static void destruct(detail::function_record *rec) {
        while (rec) {
            detail::function_record *next = rec->next;
            if (rec->free_data)
389
                rec->free_data(rec);
Wenzel Jakob's avatar
Wenzel Jakob committed
390
391
392
393
            std::free((char *) rec->name);
            std::free((char *) rec->doc);
            std::free((char *) rec->signature);
            for (auto &arg: rec->args) {
394
395
                std::free(const_cast<char *>(arg.name));
                std::free(const_cast<char *>(arg.descr));
Wenzel Jakob's avatar
Wenzel Jakob committed
396
397
398
                arg.value.dec_ref();
            }
            if (rec->def) {
399
                std::free(const_cast<char *>(rec->def->ml_doc));
Wenzel Jakob's avatar
Wenzel Jakob committed
400
401
402
403
404
405
406
407
                delete rec->def;
            }
            delete rec;
            rec = next;
        }
    }

    /// Main dispatch logic for calls to functions bound using pybind11
408
    static PyObject *dispatcher(PyObject *self, PyObject *args_in, PyObject *kwargs_in) {
409
410
        using namespace detail;

Wenzel Jakob's avatar
Wenzel Jakob committed
411
        /* Iterator over the list of potentially admissible overloads */
412
413
        function_record *overloads = (function_record *) PyCapsule_GetPointer(self, nullptr),
                        *it = overloads;
Wenzel Jakob's avatar
Wenzel Jakob committed
414
415

        /* Need to know how many arguments + keyword arguments there are to pick the right overload */
416
        const size_t n_args_in = (size_t) PyTuple_GET_SIZE(args_in);
Wenzel Jakob's avatar
Wenzel Jakob committed
417

418
        handle parent = n_args_in > 0 ? PyTuple_GET_ITEM(args_in, 0) : nullptr,
Wenzel Jakob's avatar
Wenzel Jakob committed
419
               result = PYBIND11_TRY_NEXT_OVERLOAD;
420

Wenzel Jakob's avatar
Wenzel Jakob committed
421
        try {
422
423
424
425
426
427
428
429
430
            // We do this in two passes: in the first pass, we load arguments with `convert=false`;
            // in the second, we allow conversion (except for arguments with an explicit
            // py::arg().noconvert()).  This lets us prefer calls without conversion, with
            // conversion as a fallback.
            std::vector<function_call> second_pass;

            // However, if there are no overloads, we can just skip the no-convert pass entirely
            const bool overloaded = it != nullptr && it->next != nullptr;

Wenzel Jakob's avatar
Wenzel Jakob committed
431
            for (; it != nullptr; it = it->next) {
432

Wenzel Jakob's avatar
Wenzel Jakob committed
433
                /* For each overload:
434
435
                   1. Copy all positional arguments we were given, also checking to make sure that
                      named positional arguments weren't *also* specified via kwarg.
436
                   2. If we weren't given enough, try to make up the omitted ones by checking
437
438
439
440
441
442
443
444
445
446
447
448
449
                      whether they were provided by a kwarg matching the `py::arg("name")` name.  If
                      so, use it (and remove it from kwargs; if not, see if the function binding
                      provided a default that we can use.
                   3. Ensure that either all keyword arguments were "consumed", or that the function
                      takes a kwargs argument to accept unconsumed kwargs.
                   4. Any positional arguments still left get put into a tuple (for args), and any
                      leftover kwargs get put into a dict.
                   5. Pack everything into a vector; if we have py::args or py::kwargs, they are an
                      extra tuple or dict at the end of the positional arguments.
                   6. Call the function call dispatcher (function_record::impl)

                   If one of these fail, move on to the next overload and keep trying until we get a
                   result other than PYBIND11_TRY_NEXT_OVERLOAD.
Wenzel Jakob's avatar
Wenzel Jakob committed
450
451
                 */

452
453
454
455
                function_record &func = *it;
                size_t pos_args = func.nargs;    // Number of positional arguments that we need
                if (func.has_args) --pos_args;   // (but don't count py::args
                if (func.has_kwargs) --pos_args; //  or py::kwargs)
Wenzel Jakob's avatar
Wenzel Jakob committed
456

457
                if (!func.has_args && n_args_in > pos_args)
458
459
                    continue; // Too many arguments for this overload

460
                if (n_args_in < pos_args && func.args.size() < pos_args)
461
462
                    continue; // Not enough arguments given, and not enough defaults to fill in the blanks

463
                function_call call(func, parent);
Wenzel Jakob's avatar
Wenzel Jakob committed
464

465
466
467
468
                size_t args_to_copy = std::min(pos_args, n_args_in);
                size_t args_copied = 0;

                // 1. Copy any position arguments given.
469
                bool bad_kwarg = false;
470
                for (; args_copied < args_to_copy; ++args_copied) {
471
472
473
474
                    if (kwargs_in && args_copied < func.args.size() && func.args[args_copied].name
                            && PyDict_GetItemString(kwargs_in, func.args[args_copied].name)) {
                        bad_kwarg = true;
                        break;
475
476
                    }

477
                    call.args.push_back(PyTuple_GET_ITEM(args_in, args_copied));
478
                    call.args_convert.push_back(args_copied < func.args.size() ? func.args[args_copied].convert : true);
479
                }
480
481
                if (bad_kwarg)
                    continue; // Maybe it was meant for another overload (issue #688)
482
483
484
485
486
487
488
489
490

                // We'll need to copy this if we steal some kwargs for defaults
                dict kwargs = reinterpret_borrow<dict>(kwargs_in);

                // 2. Check kwargs and, failing that, defaults that may help complete the list
                if (args_copied < pos_args) {
                    bool copied_kwargs = false;

                    for (; args_copied < pos_args; ++args_copied) {
491
                        const auto &arg = func.args[args_copied];
492
493

                        handle value;
494
                        if (kwargs_in && arg.name)
495
                            value = PyDict_GetItemString(kwargs.ptr(), arg.name);
Wenzel Jakob's avatar
Wenzel Jakob committed
496
497

                        if (value) {
498
499
500
501
502
503
                            // Consume a kwargs value
                            if (!copied_kwargs) {
                                kwargs = reinterpret_steal<dict>(PyDict_Copy(kwargs.ptr()));
                                copied_kwargs = true;
                            }
                            PyDict_DelItemString(kwargs.ptr(), arg.name);
504
                        } else if (arg.value) {
505
506
507
                            value = arg.value;
                        }

508
                        if (value) {
509
                            call.args.push_back(value);
510
511
                            call.args_convert.push_back(arg.convert);
                        }
512
                        else
Wenzel Jakob's avatar
Wenzel Jakob committed
513
                            break;
514
515
516
517
518
519
520
                    }

                    if (args_copied < pos_args)
                        continue; // Not enough arguments, defaults, or kwargs to fill the positional arguments
                }

                // 3. Check everything was consumed (unless we have a kwargs arg)
521
                if (kwargs && kwargs.size() > 0 && !func.has_kwargs)
522
523
524
525
                    continue; // Unconsumed kwargs, but no py::kwargs argument to accept them

                // 4a. If we have a py::args argument, create a new tuple with leftovers
                tuple extra_args;
526
                if (func.has_args) {
527
528
529
530
                    if (args_to_copy == 0) {
                        // We didn't copy out any position arguments from the args_in tuple, so we
                        // can reuse it directly without copying:
                        extra_args = reinterpret_borrow<tuple>(args_in);
531
                    } else if (args_copied >= n_args_in) {
532
                        extra_args = tuple(0);
533
                    } else {
534
535
536
537
538
                        size_t args_size = n_args_in - args_copied;
                        extra_args = tuple(args_size);
                        for (size_t i = 0; i < args_size; ++i) {
                            handle item = PyTuple_GET_ITEM(args_in, args_copied + i);
                            extra_args[i] = item.inc_ref().ptr();
Wenzel Jakob's avatar
Wenzel Jakob committed
539
540
                        }
                    }
541
                    call.args.push_back(extra_args);
542
                    call.args_convert.push_back(false);
Wenzel Jakob's avatar
Wenzel Jakob committed
543
                }
544

545
                // 4b. If we have a py::kwargs, pass on any remaining kwargs
546
                if (func.has_kwargs) {
547
548
                    if (!kwargs.ptr())
                        kwargs = dict(); // If we didn't get one, send an empty one
549
                    call.args.push_back(kwargs);
550
                    call.args_convert.push_back(false);
551
552
                }

553
554
555
                // 5. Put everything in a vector.  Not technically step 5, we've been building it
                // in `call.args` all along.
                #if !defined(NDEBUG)
556
                if (call.args.size() != func.nargs || call.args_convert.size() != func.nargs)
557
558
                    pybind11_fail("Internal error: function call dispatcher inserted wrong number of arguments!");
                #endif
559

560
561
562
563
564
565
566
567
568
                std::vector<bool> second_pass_convert;
                if (overloaded) {
                    // We're in the first no-convert pass, so swap out the conversion flags for a
                    // set of all-false flags.  If the call fails, we'll swap the flags back in for
                    // the conversion-allowed call below.
                    second_pass_convert.resize(func.nargs, false);
                    call.args_convert.swap(second_pass_convert);
                }

569
                // 6. Call the function.
570
                try {
571
                    result = func.impl(call);
572
                } catch (reference_cast_error &) {
573
574
                    result = PYBIND11_TRY_NEXT_OVERLOAD;
                }
Wenzel Jakob's avatar
Wenzel Jakob committed
575
576
577

                if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD)
                    break;
578

579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
                if (overloaded) {
                    // The (overloaded) call failed; if the call has at least one argument that
                    // permits conversion (i.e. it hasn't been explicitly specified `.noconvert()`)
                    // then add this call to the list of second pass overloads to try.
                    for (size_t i = func.is_method ? 1 : 0; i < pos_args; i++) {
                        if (second_pass_convert[i]) {
                            // Found one: swap the converting flags back in and store the call for
                            // the second pass.
                            call.args_convert.swap(second_pass_convert);
                            second_pass.push_back(std::move(call));
                            break;
                        }
                    }
                }
            }

            if (overloaded && !second_pass.empty() && result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) {
                // The no-conversion pass finished without success, try again with conversion allowed
                for (auto &call : second_pass) {
                    try {
                        result = call.func.impl(call);
                    } catch (reference_cast_error &) {
                        result = PYBIND11_TRY_NEXT_OVERLOAD;
                    }

                    if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD)
                        break;
                }
Wenzel Jakob's avatar
Wenzel Jakob committed
607
            }
608
609
        } catch (error_already_set &e) {
            e.restore();
610
            return nullptr;
Wenzel Jakob's avatar
Wenzel Jakob committed
611
        } catch (...) {
612
613
614
            /* When an exception is caught, give each registered exception
               translator a chance to translate it to a Python exception
               in reverse order of registration.
615

616
               A translator may choose to do one of the following:
617

618
619
620
621
622
                - catch the exception and call PyErr_SetString or PyErr_SetObject
                  to set a standard (or custom) Python exception, or
                - do nothing and let the exception fall through to the next translator, or
                - delegate translation to the next translator by throwing a new type of exception. */

623
            auto last_exception = std::current_exception();
624
            auto &registered_exception_translators = get_internals().registered_exception_translators;
625
626
627
628
629
630
631
632
633
634
            for (auto& translator : registered_exception_translators) {
                try {
                    translator(last_exception);
                } catch (...) {
                    last_exception = std::current_exception();
                    continue;
                }
                return nullptr;
            }
            PyErr_SetString(PyExc_SystemError, "Exception escaped from default exception translator!");
Wenzel Jakob's avatar
Wenzel Jakob committed
635
636
637
638
            return nullptr;
        }

        if (result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) {
639
640
641
            if (overloads->is_operator)
                return handle(Py_NotImplemented).inc_ref().ptr();

642
643
644
645
            std::string msg = std::string(overloads->name) + "(): incompatible " +
                std::string(overloads->is_constructor ? "constructor" : "function") +
                " arguments. The following argument types are supported:\n";

Wenzel Jakob's avatar
Wenzel Jakob committed
646
            int ctr = 0;
647
            for (function_record *it2 = overloads; it2 != nullptr; it2 = it2->next) {
Wenzel Jakob's avatar
Wenzel Jakob committed
648
                msg += "    "+ std::to_string(++ctr) + ". ";
649
650
651

                bool wrote_sig = false;
                if (overloads->is_constructor) {
652
                    // For a constructor, rewrite `(self: Object, arg0, ...) -> NoneType` as `Object(arg0, ...)`
653
                    std::string sig = it2->signature;
654
                    size_t start = sig.find('(') + 7; // skip "(self: "
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
                    if (start < sig.size()) {
                        // End at the , for the next argument
                        size_t end = sig.find(", "), next = end + 2;
                        size_t ret = sig.rfind(" -> ");
                        // Or the ), if there is no comma:
                        if (end >= sig.size()) next = end = sig.find(')');
                        if (start < end && next < sig.size()) {
                            msg.append(sig, start, end - start);
                            msg += '(';
                            msg.append(sig, next, ret - next);
                            wrote_sig = true;
                        }
                    }
                }
                if (!wrote_sig) msg += it2->signature;

Wenzel Jakob's avatar
Wenzel Jakob committed
671
672
                msg += "\n";
            }
673
            msg += "\nInvoked with: ";
674
            auto args_ = reinterpret_borrow<tuple>(args_in);
675
            bool some_args = false;
676
            for (size_t ti = overloads->is_constructor ? 1 : 0; ti < args_.size(); ++ti) {
677
678
                if (!some_args) some_args = true;
                else msg += ", ";
679
                msg += pybind11::repr(args_[ti]);
680
            }
681
682
683
684
685
686
687
688
689
690
691
692
693
694
            if (kwargs_in) {
                auto kwargs = reinterpret_borrow<dict>(kwargs_in);
                if (kwargs.size() > 0) {
                    if (some_args) msg += "; ";
                    msg += "kwargs: ";
                    bool first = true;
                    for (auto kwarg : kwargs) {
                        if (first) first = false;
                        else msg += ", ";
                        msg += pybind11::str("{}={!r}").format(kwarg.first, kwarg.second);
                    }
                }
            }

Wenzel Jakob's avatar
Wenzel Jakob committed
695
696
697
698
699
700
701
702
703
704
            PyErr_SetString(PyExc_TypeError, msg.c_str());
            return nullptr;
        } else if (!result) {
            std::string msg = "Unable to convert function return value to a "
                              "Python type! The signature was\n\t";
            msg += it->signature;
            PyErr_SetString(PyExc_TypeError, msg.c_str());
            return nullptr;
        } else {
            if (overloads->is_constructor) {
705
                /* When a constructor ran successfully, the corresponding
Wenzel Jakob's avatar
Wenzel Jakob committed
706
                   holder type (e.g. std::unique_ptr) must still be initialized. */
707
                auto tinfo = get_type_info(Py_TYPE(parent.ptr()));
708
                tinfo->init_holder(parent.ptr(), nullptr);
Wenzel Jakob's avatar
Wenzel Jakob committed
709
710
711
712
            }
            return result.ptr();
        }
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
713
714
};

715
/// Wrapper for Python extension modules
Wenzel Jakob's avatar
Wenzel Jakob committed
716
717
class module : public object {
public:
718
    PYBIND11_OBJECT_DEFAULT(module, object, PyModule_Check)
Wenzel Jakob's avatar
Wenzel Jakob committed
719

720
    /// Create a new top-level Python module with the given name and docstring
721
    explicit module(const char *name, const char *doc = nullptr) {
722
        if (!options::show_user_defined_docstrings()) doc = nullptr;
723
#if PY_MAJOR_VERSION >= 3
Wenzel Jakob's avatar
Wenzel Jakob committed
724
725
726
727
728
729
730
        PyModuleDef *def = new PyModuleDef();
        memset(def, 0, sizeof(PyModuleDef));
        def->m_name = name;
        def->m_doc = doc;
        def->m_size = -1;
        Py_INCREF(def);
        m_ptr = PyModule_Create(def);
731
732
733
#else
        m_ptr = Py_InitModule3(name, nullptr, doc);
#endif
Wenzel Jakob's avatar
Wenzel Jakob committed
734
        if (m_ptr == nullptr)
735
            pybind11_fail("Internal error in module::module()");
Wenzel Jakob's avatar
Wenzel Jakob committed
736
737
738
        inc_ref();
    }

739
740
741
742
743
    /** \rst
        Create Python binding for a new function within the module scope. ``Func``
        can be a plain C++ function, a function pointer, or a lambda function. For
        details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
    \endrst */
744
    template <typename Func, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
745
    module &def(const char *name_, Func &&f, const Extra& ... extra) {
746
747
        cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
                          sibling(getattr(*this, name_, none())), extra...);
748
749
750
        // NB: allow overwriting here because cpp_function sets up a chain with the intention of
        // overwriting (and has already checked internally that it isn't overwriting non-functions).
        add_object(name_, func, true /* overwrite */);
Wenzel Jakob's avatar
Wenzel Jakob committed
751
752
753
        return *this;
    }

754
755
756
757
758
759
760
761
762
763
    /** \rst
        Create and return a new Python submodule with the given name and docstring.
        This also works recursively, i.e.

        .. code-block:: cpp

            py::module m("example", "pybind11 example plugin");
            py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
            py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
    \endrst */
764
    module def_submodule(const char *name, const char *doc = nullptr) {
Wenzel Jakob's avatar
Wenzel Jakob committed
765
766
        std::string full_name = std::string(PyModule_GetName(m_ptr))
            + std::string(".") + std::string(name);
767
        auto result = reinterpret_borrow<module>(PyImport_AddModule(full_name.c_str()));
768
        if (doc && options::show_user_defined_docstrings())
769
            result.attr("__doc__") = pybind11::str(doc);
Wenzel Jakob's avatar
Wenzel Jakob committed
770
771
772
        attr(name) = result;
        return result;
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
773

774
    /// Import and return a module or throws `error_already_set`.
Wenzel Jakob's avatar
Wenzel Jakob committed
775
    static module import(const char *name) {
776
777
        PyObject *obj = PyImport_ImportModule(name);
        if (!obj)
778
            throw error_already_set();
779
        return reinterpret_steal<module>(obj);
Wenzel Jakob's avatar
Wenzel Jakob committed
780
    }
781
782
783
784
785
786

    // Adds an object to the module using the given name.  Throws if an object with the given name
    // already exists.
    //
    // overwrite should almost always be false: attempting to overwrite objects that pybind11 has
    // established will, in most cases, break things.
787
    PYBIND11_NOINLINE void add_object(const char *name, handle obj, bool overwrite = false) {
788
789
790
791
        if (!overwrite && hasattr(*this, name))
            pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" +
                    std::string(name) + "\"");

792
        PyModule_AddObject(ptr(), name, obj.inc_ref().ptr() /* steals a reference */);
793
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
794
795
796
};

NAMESPACE_BEGIN(detail)
Wenzel Jakob's avatar
Wenzel Jakob committed
797
/// Generic support for creating new Python heap types
798
class generic_type : public object {
799
    template <typename...> friend class class_;
Wenzel Jakob's avatar
Wenzel Jakob committed
800
public:
801
    PYBIND11_OBJECT_DEFAULT(generic_type, object, PyType_Check)
Wenzel Jakob's avatar
Wenzel Jakob committed
802
protected:
803
804
805
806
    void initialize(const type_record &rec) {
        if (rec.scope && hasattr(rec.scope, rec.name))
            pybind11_fail("generic_type: cannot initialize type \"" + std::string(rec.name) +
                          "\": an object with that name is already defined");
807

808
809
        if (get_type_info(*rec.type))
            pybind11_fail("generic_type: type \"" + std::string(rec.name) +
810
811
                          "\" is already registered!");

812
        m_ptr = make_new_python_type(rec);
813
814

        /* Register supplemental type information in C++ dict */
815
816
        auto *tinfo = new detail::type_info();
        tinfo->type = (PyTypeObject *) m_ptr;
817
        tinfo->cpptype = rec.type;
818
        tinfo->type_size = rec.type_size;
819
        tinfo->operator_new = rec.operator_new;
820
821
        tinfo->init_holder = rec.init_holder;
        tinfo->dealloc = rec.dealloc;
822
823
        tinfo->simple_type = true;
        tinfo->simple_ancestors = true;
824
825
826

        auto &internals = get_internals();
        auto tindex = std::type_index(*rec.type);
827
        tinfo->direct_conversions = &internals.direct_conversions[tindex];
828
        tinfo->default_holder = rec.default_holder;
829
        internals.registered_types_cpp[tindex] = tinfo;
830
        internals.registered_types_py[m_ptr] = tinfo;
Wenzel Jakob's avatar
Wenzel Jakob committed
831

832
        if (rec.bases.size() > 1 || rec.multiple_inheritance) {
833
            mark_parents_nonsimple(tinfo->type);
834
835
836
837
838
839
            tinfo->simple_ancestors = false;
        }
        else if (rec.bases.size() == 1) {
            auto parent_tinfo = get_type_info((PyTypeObject *) rec.bases[0].ptr());
            tinfo->simple_ancestors = parent_tinfo->simple_ancestors;
        }
Wenzel Jakob's avatar
Wenzel Jakob committed
840
841
    }

Wenzel Jakob's avatar
Wenzel Jakob committed
842
843
    /// Helper function which tags all parents of a type using mult. inheritance
    void mark_parents_nonsimple(PyTypeObject *value) {
844
        auto t = reinterpret_borrow<tuple>(value->tp_bases);
Wenzel Jakob's avatar
Wenzel Jakob committed
845
846
847
848
849
850
851
852
        for (handle h : t) {
            auto tinfo2 = get_type_info((PyTypeObject *) h.ptr());
            if (tinfo2)
                tinfo2->simple_type = false;
            mark_parents_nonsimple((PyTypeObject *) h.ptr());
        }
    }

Wenzel Jakob's avatar
Wenzel Jakob committed
853
854
855
    void install_buffer_funcs(
            buffer_info *(*get_buffer)(PyObject *, void *),
            void *get_buffer_data) {
Wenzel Jakob's avatar
Wenzel Jakob committed
856
        PyHeapTypeObject *type = (PyHeapTypeObject*) m_ptr;
857
        auto tinfo = detail::get_type_info(&type->ht_type);
Wenzel Jakob's avatar
Wenzel Jakob committed
858
859
860
861
862
863
864
865

        if (!type->ht_type.tp_as_buffer)
            pybind11_fail(
                "To be able to register buffer protocol support for the type '" +
                std::string(tinfo->type->tp_name) +
                "' the associated class<>(..) invocation must "
                "include the pybind11::buffer_protocol() annotation!");

866
867
        tinfo->get_buffer = get_buffer;
        tinfo->get_buffer_data = get_buffer_data;
Wenzel Jakob's avatar
Wenzel Jakob committed
868
869
    }

Wenzel Jakob's avatar
Wenzel Jakob committed
870
871
872
    void def_property_static_impl(const char *name,
                                  handle fget, handle fset,
                                  detail::function_record *rec_fget) {
873
874
875
876
877
878
879
880
881
        const auto is_static = !(rec_fget->is_method && rec_fget->scope);
        const auto has_doc = rec_fget->doc && pybind11::options::show_user_defined_docstrings();

        auto property = handle((PyObject *) (is_static ? get_internals().static_property_type
                                                       : &PyProperty_Type));
        attr(name) = property(fget.ptr() ? fget : none(),
                              fset.ptr() ? fset : none(),
                              /*deleter*/none(),
                              pybind11::str(has_doc ? rec_fget->doc : ""));
Wenzel Jakob's avatar
Wenzel Jakob committed
882
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
883
};
884

885
886
887
888
889
890
891
892
893
894
895
896
/// Set the pointer to operator new if it exists. The cast is needed because it can be overloaded.
template <typename T, typename = void_t<decltype(static_cast<void *(*)(size_t)>(T::operator new))>>
void set_operator_new(type_record *r) { r->operator_new = &T::operator new; }

template <typename> void set_operator_new(...) { }

/// Call class-specific delete if it exists or global otherwise. Can also be an overload set.
template <typename T, typename = void_t<decltype(static_cast<void (*)(void *)>(T::operator delete))>>
void call_operator_delete(T *p) { T::operator delete(p); }

inline void call_operator_delete(void *p) { ::operator delete(p); }

Wenzel Jakob's avatar
Wenzel Jakob committed
897
898
NAMESPACE_END(detail)

899
template <typename type_, typename... options>
Wenzel Jakob's avatar
Wenzel Jakob committed
900
class class_ : public detail::generic_type {
901
902
    template <typename T> using is_holder = detail::is_holder_type<type_, T>;
    template <typename T> using is_subtype = detail::bool_constant<std::is_base_of<type_, T>::value && !std::is_same<T, type_>::value>;
Wenzel Jakob's avatar
Wenzel Jakob committed
903
    template <typename T> using is_base = detail::bool_constant<std::is_base_of<T, type_>::value && !std::is_same<T, type_>::value>;
904
905
906
    // struct instead of using here to help MSVC:
    template <typename T> struct is_valid_class_option :
        detail::any_of<is_holder<T>, is_subtype<T>, is_base<T>> {};
907

Wenzel Jakob's avatar
Wenzel Jakob committed
908
public:
909
    using type = type_;
910
    using type_alias = detail::exactly_one_t<is_subtype, void, options...>;
911
    constexpr static bool has_alias = !std::is_void<type_alias>::value;
912
    using holder_type = detail::exactly_one_t<is_holder, std::unique_ptr<type>, options...>;
913
914
    using instance_type = detail::instance<type, holder_type>;

915
    static_assert(detail::all_of<is_valid_class_option<options>...>::value,
916
            "Unknown/invalid class_ template parameters provided");
Wenzel Jakob's avatar
Wenzel Jakob committed
917

918
    PYBIND11_OBJECT(class_, generic_type, PyType_Check)
Wenzel Jakob's avatar
Wenzel Jakob committed
919

Wenzel Jakob's avatar
Wenzel Jakob committed
920
921
    template <typename... Extra>
    class_(handle scope, const char *name, const Extra &... extra) {
922
923
924
925
926
927
928
929
930
931
932
        using namespace detail;

        // MI can only be specified via class_ template options, not constructor parameters
        static_assert(
            none_of<is_pyobject<Extra>...>::value || // no base class arguments, or:
            (   constexpr_sum(is_pyobject<Extra>::value...) == 1 && // Exactly one base
                constexpr_sum(is_base<options>::value...)   == 0 && // no template option bases
                none_of<std::is_same<multiple_inheritance, Extra>...>::value), // no multiple_inheritance attr
            "Error: multiple inheritance bases must be specified via class_ template options");

        type_record record;
Wenzel Jakob's avatar
Wenzel Jakob committed
933
934
935
        record.scope = scope;
        record.name = name;
        record.type = &typeid(type);
936
        record.type_size = sizeof(conditional_t<has_alias, type_alias, type>);
Wenzel Jakob's avatar
Wenzel Jakob committed
937
938
939
        record.instance_size = sizeof(instance_type);
        record.init_holder = init_holder;
        record.dealloc = dealloc;
940
        record.default_holder = std::is_same<holder_type, std::unique_ptr<type>>::value;
Wenzel Jakob's avatar
Wenzel Jakob committed
941

942
943
        set_operator_new<type>(&record);

Wenzel Jakob's avatar
Wenzel Jakob committed
944
        /* Register base classes specified via template arguments to class_, if any */
945
        bool unused[] = { (add_base<options>(record), false)..., false };
Wenzel Jakob's avatar
Wenzel Jakob committed
946
        (void) unused;
947

Wenzel Jakob's avatar
Wenzel Jakob committed
948
        /* Process optional arguments, if any */
949
        process_attributes<Extra...>::init(extra..., &record);
Wenzel Jakob's avatar
Wenzel Jakob committed
950

951
        generic_type::initialize(record);
952

953
        if (has_alias) {
954
            auto &instances = get_internals().registered_types_cpp;
955
956
            instances[std::type_index(typeid(type_alias))] = instances[std::type_index(typeid(type))];
        }
Wenzel Jakob's avatar
Wenzel Jakob committed
957
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
958

959
    template <typename Base, detail::enable_if_t<is_base<Base>::value, int> = 0>
Wenzel Jakob's avatar
Wenzel Jakob committed
960
961
962
963
964
965
    static void add_base(detail::type_record &rec) {
        rec.add_base(&typeid(Base), [](void *src) -> void * {
            return static_cast<Base *>(reinterpret_cast<type *>(src));
        });
    }

966
    template <typename Base, detail::enable_if_t<!is_base<Base>::value, int> = 0>
Wenzel Jakob's avatar
Wenzel Jakob committed
967
968
    static void add_base(detail::type_record &) { }

969
    template <typename Func, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
970
    class_ &def(const char *name_, Func&& f, const Extra&... extra) {
971
972
        cpp_function cf(std::forward<Func>(f), name(name_), is_method(*this),
                        sibling(getattr(*this, name_, none())), extra...);
973
        attr(cf.name()) = cf;
Wenzel Jakob's avatar
Wenzel Jakob committed
974
975
976
        return *this;
    }

977
    template <typename Func, typename... Extra> class_ &
978
979
980
    def_static(const char *name_, Func &&f, const Extra&... extra) {
        static_assert(!std::is_member_function_pointer<Func>::value,
                "def_static(...) called with a non-static member function pointer");
981
982
        cpp_function cf(std::forward<Func>(f), name(name_), scope(*this),
                        sibling(getattr(*this, name_, none())), extra...);
983
        attr(cf.name()) = cf;
Wenzel Jakob's avatar
Wenzel Jakob committed
984
985
986
        return *this;
    }

987
    template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
988
    class_ &def(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
989
        op.execute(*this, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
990
991
992
        return *this;
    }

993
    template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
994
    class_ & def_cast(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
995
        op.execute_cast(*this, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
996
997
998
        return *this;
    }

999
    template <typename... Args, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
1000
    class_ &def(const detail::init<Args...> &init, const Extra&... extra) {
1001
        init.execute(*this, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1002
1003
1004
        return *this;
    }

1005
1006
    template <typename... Args, typename... Extra>
    class_ &def(const detail::init_alias<Args...> &init, const Extra&... extra) {
1007
        init.execute(*this, extra...);
1008
1009
1010
        return *this;
    }

1011
    template <typename Func> class_& def_buffer(Func &&func) {
Wenzel Jakob's avatar
Wenzel Jakob committed
1012
1013
1014
        struct capture { Func func; };
        capture *ptr = new capture { std::forward<Func>(func) };
        install_buffer_funcs([](PyObject *obj, void *ptr) -> buffer_info* {
1015
            detail::make_caster<type> caster;
Wenzel Jakob's avatar
Wenzel Jakob committed
1016
1017
            if (!caster.load(obj, false))
                return nullptr;
Wenzel Jakob's avatar
Wenzel Jakob committed
1018
1019
            return new buffer_info(((capture *) ptr)->func(caster));
        }, ptr);
Wenzel Jakob's avatar
Wenzel Jakob committed
1020
1021
1022
        return *this;
    }

1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
    template <typename Return, typename Class, typename... Args>
    class_ &def_buffer(Return (Class::*func)(Args...)) {
        return def_buffer([func] (type &obj) { return (obj.*func)(); });
    }

    template <typename Return, typename Class, typename... Args>
    class_ &def_buffer(Return (Class::*func)(Args...) const) {
        return def_buffer([func] (const type &obj) { return (obj.*func)(); });
    }

1033
    template <typename C, typename D, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
1034
    class_ &def_readwrite(const char *name, D C::*pm, const Extra&... extra) {
1035
1036
1037
        cpp_function fget([pm](const C &c) -> const D &{ return c.*pm; }, is_method(*this)),
                     fset([pm](C &c, const D &value) { c.*pm = value; }, is_method(*this));
        def_property(name, fget, fset, return_value_policy::reference_internal, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1038
1039
1040
        return *this;
    }

1041
    template <typename C, typename D, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
1042
    class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra) {
1043
1044
        cpp_function fget([pm](const C &c) -> const D &{ return c.*pm; }, is_method(*this));
        def_property_readonly(name, fget, return_value_policy::reference_internal, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1045
1046
1047
        return *this;
    }

1048
    template <typename D, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
1049
    class_ &def_readwrite_static(const char *name, D *pm, const Extra& ...extra) {
1050
1051
1052
        cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this)),
                     fset([pm](object, const D &value) { *pm = value; }, scope(*this));
        def_property_static(name, fget, fset, return_value_policy::reference, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1053
1054
1055
        return *this;
    }

1056
    template <typename D, typename... Extra>
Wenzel Jakob's avatar
Wenzel Jakob committed
1057
    class_ &def_readonly_static(const char *name, const D *pm, const Extra& ...extra) {
1058
1059
        cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this));
        def_property_readonly_static(name, fget, return_value_policy::reference, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1060
1061
1062
        return *this;
    }

1063
1064
1065
1066
1067
1068
1069
    /// Uses return_value_policy::reference_internal by default
    template <typename Getter, typename... Extra>
    class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra) {
        return def_property_readonly(name, cpp_function(fget), return_value_policy::reference_internal, extra...);
    }

    /// Uses cpp_function's return_value_policy by default
1070
1071
    template <typename... Extra>
    class_ &def_property_readonly(const char *name, const cpp_function &fget, const Extra& ...extra) {
1072
1073
1074
1075
1076
1077
1078
        return def_property(name, fget, cpp_function(), extra...);
    }

    /// Uses return_value_policy::reference by default
    template <typename Getter, typename... Extra>
    class_ &def_property_readonly_static(const char *name, const Getter &fget, const Extra& ...extra) {
        return def_property_readonly_static(name, cpp_function(fget), return_value_policy::reference, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1079
1080
    }

1081
    /// Uses cpp_function's return_value_policy by default
1082
1083
    template <typename... Extra>
    class_ &def_property_readonly_static(const char *name, const cpp_function &fget, const Extra& ...extra) {
1084
1085
1086
1087
1088
1089
1090
        return def_property_static(name, fget, cpp_function(), extra...);
    }

    /// Uses return_value_policy::reference_internal by default
    template <typename Getter, typename... Extra>
    class_ &def_property(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
        return def_property(name, cpp_function(fget), fset, return_value_policy::reference_internal, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1091
1092
    }

1093
    /// Uses cpp_function's return_value_policy by default
1094
1095
    template <typename... Extra>
    class_ &def_property(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1096
        return def_property_static(name, fget, fset, is_method(*this), extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1097
1098
    }

1099
1100
1101
1102
1103
1104
1105
    /// Uses return_value_policy::reference by default
    template <typename Getter, typename... Extra>
    class_ &def_property_static(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
        return def_property_static(name, cpp_function(fget), fset, return_value_policy::reference, extra...);
    }

    /// Uses cpp_function's return_value_policy by default
1106
1107
1108
    template <typename... Extra>
    class_ &def_property_static(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
        auto rec_fget = get_function_record(fget), rec_fset = get_function_record(fset);
1109
        char *doc_prev = rec_fget->doc; /* 'extra' field may include a property-specific documentation string */
1110
        detail::process_attributes<Extra...>::init(extra..., rec_fget);
1111
1112
1113
1114
1115
1116
        if (rec_fget->doc && rec_fget->doc != doc_prev) {
            free(doc_prev);
            rec_fget->doc = strdup(rec_fget->doc);
        }
        if (rec_fset) {
            doc_prev = rec_fset->doc;
1117
            detail::process_attributes<Extra...>::init(extra..., rec_fset);
1118
1119
1120
1121
1122
            if (rec_fset->doc && rec_fset->doc != doc_prev) {
                free(doc_prev);
                rec_fset->doc = strdup(rec_fset->doc);
            }
        }
Wenzel Jakob's avatar
Wenzel Jakob committed
1123
        def_property_static_impl(name, fget, fset, rec_fget);
Wenzel Jakob's avatar
Wenzel Jakob committed
1124
1125
        return *this;
    }
1126

Wenzel Jakob's avatar
Wenzel Jakob committed
1127
private:
1128
1129
1130
    /// Initialize holder object, variant 1: object derives from enable_shared_from_this
    template <typename T>
    static void init_holder_helper(instance_type *inst, const holder_type * /* unused */, const std::enable_shared_from_this<T> * /* dummy */) {
1131
        try {
1132
1133
1134
            auto sh = std::dynamic_pointer_cast<typename holder_type::element_type>(inst->value->shared_from_this());
            if (sh) {
                new (&inst->holder) holder_type(std::move(sh));
1135
1136
                inst->holder_constructed = true;
            }
1137
1138
1139
1140
        } catch (const std::bad_weak_ptr &) {}
        if (!inst->holder_constructed && inst->owned) {
            new (&inst->holder) holder_type(inst->value);
            inst->holder_constructed = true;
1141
        }
1142
1143
    }

1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
    static void init_holder_from_existing(instance_type *inst, const holder_type *holder_ptr,
                                          std::true_type /*is_copy_constructible*/) {
        new (&inst->holder) holder_type(*holder_ptr);
    }

    static void init_holder_from_existing(instance_type *inst, const holder_type *holder_ptr,
                                          std::false_type /*is_copy_constructible*/) {
        new (&inst->holder) holder_type(std::move(*const_cast<holder_type *>(holder_ptr)));
    }

1154
1155
    /// Initialize holder object, variant 2: try to construct from existing holder object, if possible
    static void init_holder_helper(instance_type *inst, const holder_type *holder_ptr, const void * /* dummy */) {
1156
        if (holder_ptr) {
1157
            init_holder_from_existing(inst, holder_ptr, std::is_copy_constructible<holder_type>());
1158
            inst->holder_constructed = true;
1159
        } else if (inst->owned || detail::always_construct_holder<holder_type>::value) {
1160
            new (&inst->holder) holder_type(inst->value);
1161
1162
            inst->holder_constructed = true;
        }
1163
1164
1165
1166
1167
1168
    }

    /// Initialize holder object of an instance, possibly given a pointer to an existing holder
    static void init_holder(PyObject *inst_, const void *holder_ptr) {
        auto inst = (instance_type *) inst_;
        init_holder_helper(inst, (const holder_type *) holder_ptr, inst->value);
1169
1170
    }

Wenzel Jakob's avatar
Wenzel Jakob committed
1171
1172
    static void dealloc(PyObject *inst_) {
        instance_type *inst = (instance_type *) inst_;
1173
1174
1175
        if (inst->holder_constructed)
            inst->holder.~holder_type();
        else if (inst->owned)
1176
            detail::call_operator_delete(inst->value);
Wenzel Jakob's avatar
Wenzel Jakob committed
1177
    }
1178
1179
1180

    static detail::function_record *get_function_record(handle h) {
        h = detail::get_function(h);
Wenzel Jakob's avatar
Wenzel Jakob committed
1181
        return h ? (detail::function_record *) reinterpret_borrow<capsule>(PyCFunction_GET_SELF(h.ptr()))
1182
                 : nullptr;
1183
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
1184
1185
1186
1187
1188
};

/// Binds C++ enumerations and enumeration classes to Python
template <typename Type> class enum_ : public class_<Type> {
public:
1189
    using class_<Type>::def;
1190
    using class_<Type>::def_property_readonly_static;
1191
1192
    using Scalar = typename std::underlying_type<Type>::type;

Wenzel Jakob's avatar
Wenzel Jakob committed
1193
1194
    template <typename... Extra>
    enum_(const handle &scope, const char *name, const Extra&... extra)
1195
      : class_<Type>(scope, name, extra...), m_entries(), m_parent(scope) {
1196

1197
        constexpr bool is_arithmetic = detail::any_of<std::is_same<arithmetic, Extra>...>::value;
1198

1199
1200
1201
1202
1203
1204
1205
        auto m_entries_ptr = m_entries.inc_ref().ptr();
        def("__repr__", [name, m_entries_ptr](Type value) -> pybind11::str {
            for (const auto &kv : reinterpret_borrow<dict>(m_entries_ptr)) {
                if (pybind11::cast<Type>(kv.second) == value)
                    return pybind11::str("{}.{}").format(name, kv.first);
            }
            return pybind11::str("{}.???").format(name);
Wenzel Jakob's avatar
Wenzel Jakob committed
1206
        });
1207
1208
1209
1210
1211
1212
        def_property_readonly_static("__members__", [m_entries_ptr](object /* self */) {
            dict m;
            for (const auto &kv : reinterpret_borrow<dict>(m_entries_ptr))
                m[kv.first] = kv.second;
            return m;
        }, return_value_policy::copy);
1213
1214
        def("__init__", [](Type& value, Scalar i) { value = (Type)i; });
        def("__int__", [](Type value) { return (Scalar) value; });
1215
1216
1217
        #if PY_MAJOR_VERSION < 3
            def("__long__", [](Type value) { return (Scalar) value; });
        #endif
1218
1219
        def("__eq__", [](const Type &value, Type *value2) { return value2 && value == *value2; });
        def("__ne__", [](const Type &value, Type *value2) { return !value2 || value != *value2; });
1220
1221
1222
1223
1224
1225
1226
        if (is_arithmetic) {
            def("__lt__", [](const Type &value, Type *value2) { return value2 && value < *value2; });
            def("__gt__", [](const Type &value, Type *value2) { return value2 && value > *value2; });
            def("__le__", [](const Type &value, Type *value2) { return value2 && value <= *value2; });
            def("__ge__", [](const Type &value, Type *value2) { return value2 && value >= *value2; });
        }
        if (std::is_convertible<Type, Scalar>::value) {
1227
1228
            // Don't provide comparison with the underlying type if the enum isn't convertible,
            // i.e. if Type is a scoped enum, mirroring the C++ behaviour.  (NB: we explicitly
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
            // convert Type to Scalar below anyway because this needs to compile).
            def("__eq__", [](const Type &value, Scalar value2) { return (Scalar) value == value2; });
            def("__ne__", [](const Type &value, Scalar value2) { return (Scalar) value != value2; });
            if (is_arithmetic) {
                def("__lt__", [](const Type &value, Scalar value2) { return (Scalar) value < value2; });
                def("__gt__", [](const Type &value, Scalar value2) { return (Scalar) value > value2; });
                def("__le__", [](const Type &value, Scalar value2) { return (Scalar) value <= value2; });
                def("__ge__", [](const Type &value, Scalar value2) { return (Scalar) value >= value2; });
                def("__invert__", [](const Type &value) { return ~((Scalar) value); });
                def("__and__", [](const Type &value, Scalar value2) { return (Scalar) value & value2; });
                def("__or__", [](const Type &value, Scalar value2) { return (Scalar) value | value2; });
                def("__xor__", [](const Type &value, Scalar value2) { return (Scalar) value ^ value2; });
                def("__rand__", [](const Type &value, Scalar value2) { return (Scalar) value & value2; });
                def("__ror__", [](const Type &value, Scalar value2) { return (Scalar) value | value2; });
                def("__rxor__", [](const Type &value, Scalar value2) { return (Scalar) value ^ value2; });
                def("__and__", [](const Type &value, const Type &value2) { return (Scalar) value & (Scalar) value2; });
                def("__or__", [](const Type &value, const Type &value2) { return (Scalar) value | (Scalar) value2; });
                def("__xor__", [](const Type &value, const Type &value2) { return (Scalar) value ^ (Scalar) value2; });
            }
1248
        }
1249
        def("__hash__", [](const Type &value) { return (Scalar) value; });
Wenzel Jakob's avatar
Wenzel Jakob committed
1250
        // Pickling and unpickling -- needed for use with the 'multiprocessing' module
1251
1252
        def("__getstate__", [](const Type &value) { return pybind11::make_tuple((Scalar) value); });
        def("__setstate__", [](Type &p, tuple t) { new (&p) Type((Type) t[0].cast<Scalar>()); });
Wenzel Jakob's avatar
Wenzel Jakob committed
1253
1254
1255
    }

    /// Export enumeration entries into the parent scope
1256
1257
1258
    enum_& export_values() {
        for (const auto &kv : m_entries)
            m_parent.attr(kv.first) = kv.second;
1259
        return *this;
Wenzel Jakob's avatar
Wenzel Jakob committed
1260
1261
1262
1263
    }

    /// Add an enumeration entry
    enum_& value(char const* name, Type value) {
1264
1265
1266
        auto v = pybind11::cast(value, return_value_policy::copy);
        this->attr(name) = v;
        m_entries[pybind11::str(name)] = v;
Wenzel Jakob's avatar
Wenzel Jakob committed
1267
1268
        return *this;
    }
1269

Wenzel Jakob's avatar
Wenzel Jakob committed
1270
private:
1271
    dict m_entries;
Wenzel Jakob's avatar
Wenzel Jakob committed
1272
    handle m_parent;
Wenzel Jakob's avatar
Wenzel Jakob committed
1273
1274
1275
};

NAMESPACE_BEGIN(detail)
1276
template <typename... Args> struct init {
1277
1278
    template <typename Class, typename... Extra, enable_if_t<!Class::has_alias, int> = 0>
    static void execute(Class &cl, const Extra&... extra) {
1279
        using Base = typename Class::type;
Wenzel Jakob's avatar
Wenzel Jakob committed
1280
        /// Function which calls a specific C++ in-place constructor
1281
        cl.def("__init__", [](Base *self_, Args... args) { new (self_) Base(args...); }, extra...);
1282
1283
    }

1284
    template <typename Class, typename... Extra,
1285
1286
1287
              enable_if_t<Class::has_alias &&
                          std::is_constructible<typename Class::type, Args...>::value, int> = 0>
    static void execute(Class &cl, const Extra&... extra) {
1288
1289
1290
1291
        using Base = typename Class::type;
        using Alias = typename Class::type_alias;
        handle cl_type = cl;
        cl.def("__init__", [cl_type](handle self_, Args... args) {
1292
                if (self_.get_type().is(cl_type))
1293
                    new (self_.cast<Base *>()) Base(args...);
1294
                else
1295
                    new (self_.cast<Alias *>()) Alias(args...);
1296
1297
1298
            }, extra...);
    }

1299
    template <typename Class, typename... Extra,
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
              enable_if_t<Class::has_alias &&
                          !std::is_constructible<typename Class::type, Args...>::value, int> = 0>
    static void execute(Class &cl, const Extra&... extra) {
        init_alias<Args...>::execute(cl, extra...);
    }
};
template <typename... Args> struct init_alias {
    template <typename Class, typename... Extra,
              enable_if_t<Class::has_alias && std::is_constructible<typename Class::type_alias, Args...>::value, int> = 0>
    static void execute(Class &cl, const Extra&... extra) {
1310
1311
        using Alias = typename Class::type_alias;
        cl.def("__init__", [](Alias *self_, Args... args) { new (self_) Alias(args...); }, extra...);
Wenzel Jakob's avatar
Wenzel Jakob committed
1312
1313
    }
};
1314

1315

1316
inline void keep_alive_impl(handle nurse, handle patient) {
1317
    /* Clever approach based on weak references taken from Boost.Python */
1318
    if (!nurse || !patient)
1319
        pybind11_fail("Could not activate keep_alive!");
1320

1321
    if (patient.is_none() || nurse.is_none())
1322
        return; /* Nothing to keep alive or nothing to be kept alive by */
1323

1324
    cpp_function disable_lifesupport(
1325
        [patient](handle weakref) { patient.dec_ref(); weakref.dec_ref(); });
1326

1327
    weakref wr(nurse, disable_lifesupport);
1328

1329
1330
    patient.inc_ref(); /* reference patient and leak the weak reference */
    (void) wr.release();
1331
1332
}

1333
PYBIND11_NOINLINE inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret) {
1334
    keep_alive_impl(
1335
1336
        Nurse   == 0 ? ret : Nurse   <= call.args.size() ? call.args[Nurse   - 1] : handle(),
        Patient == 0 ? ret : Patient <= call.args.size() ? call.args[Patient - 1] : handle()
1337
    );
1338
1339
}

1340
template <typename Iterator, typename Sentinel, bool KeyIterator, return_value_policy Policy>
1341
1342
1343
struct iterator_state {
    Iterator it;
    Sentinel end;
1344
1345
    bool first;
};
1346

Wenzel Jakob's avatar
Wenzel Jakob committed
1347
1348
NAMESPACE_END(detail)

1349
template <typename... Args> detail::init<Args...> init() { return detail::init<Args...>(); }
1350
template <typename... Args> detail::init_alias<Args...> init_alias() { return detail::init_alias<Args...>(); }
Wenzel Jakob's avatar
Wenzel Jakob committed
1351

1352
/// Makes a python iterator from a first and past-the-end C++ InputIterator.
1353
1354
template <return_value_policy Policy = return_value_policy::reference_internal,
          typename Iterator,
1355
          typename Sentinel,
1356
1357
          typename ValueType = decltype(*std::declval<Iterator>()),
          typename... Extra>
1358
iterator make_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1359
    typedef detail::iterator_state<Iterator, Sentinel, false, Policy> state;
1360

Wenzel Jakob's avatar
Wenzel Jakob committed
1361
    if (!detail::get_type_info(typeid(state), false)) {
1362
        class_<state>(handle(), "iterator")
1363
            .def("__iter__", [](state &s) -> state& { return s; })
1364
            .def("__next__", [](state &s) -> ValueType {
1365
1366
1367
1368
                if (!s.first)
                    ++s.it;
                else
                    s.first = false;
1369
1370
                if (s.it == s.end)
                    throw stop_iteration();
1371
                return *s.it;
1372
            }, std::forward<Extra>(extra)..., Policy);
1373
1374
    }

1375
    return (iterator) cast(state { first, last, true });
1376
}
1377

1378
1379
/// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a
/// first and past-the-end InputIterator.
1380
1381
template <return_value_policy Policy = return_value_policy::reference_internal,
          typename Iterator,
1382
          typename Sentinel,
1383
          typename KeyType = decltype((*std::declval<Iterator>()).first),
1384
          typename... Extra>
1385
iterator make_key_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1386
    typedef detail::iterator_state<Iterator, Sentinel, true, Policy> state;
1387

Wenzel Jakob's avatar
Wenzel Jakob committed
1388
    if (!detail::get_type_info(typeid(state), false)) {
1389
        class_<state>(handle(), "iterator")
1390
1391
1392
1393
1394
1395
1396
1397
            .def("__iter__", [](state &s) -> state& { return s; })
            .def("__next__", [](state &s) -> KeyType {
                if (!s.first)
                    ++s.it;
                else
                    s.first = false;
                if (s.it == s.end)
                    throw stop_iteration();
1398
                return (*s.it).first;
1399
            }, std::forward<Extra>(extra)..., Policy);
1400
1401
1402
1403
    }

    return (iterator) cast(state { first, last, true });
}
1404

1405
1406
/// Makes an iterator over values of an stl container or other container supporting
/// `std::begin()`/`std::end()`
1407
1408
1409
template <return_value_policy Policy = return_value_policy::reference_internal,
          typename Type, typename... Extra> iterator make_iterator(Type &value, Extra&&... extra) {
    return make_iterator<Policy>(std::begin(value), std::end(value), extra...);
1410
1411
}

1412
1413
/// Makes an iterator over the keys (`.first`) of a stl map-like container supporting
/// `std::begin()`/`std::end()`
1414
1415
1416
template <return_value_policy Policy = return_value_policy::reference_internal,
          typename Type, typename... Extra> iterator make_key_iterator(Type &value, Extra&&... extra) {
    return make_key_iterator<Policy>(std::begin(value), std::end(value), extra...);
1417
1418
}

Wenzel Jakob's avatar
Wenzel Jakob committed
1419
template <typename InputType, typename OutputType> void implicitly_convertible() {
1420
    auto implicit_caster = [](PyObject *obj, PyTypeObject *type) -> PyObject * {
1421
        if (!detail::make_caster<InputType>().load(obj, false))
Wenzel Jakob's avatar
Wenzel Jakob committed
1422
1423
1424
1425
1426
1427
1428
1429
            return nullptr;
        tuple args(1);
        args[0] = obj;
        PyObject *result = PyObject_Call((PyObject *) type, args.ptr(), nullptr);
        if (result == nullptr)
            PyErr_Clear();
        return result;
    };
1430
1431
1432
1433

    if (auto tinfo = detail::get_type_info(typeid(OutputType)))
        tinfo->implicit_conversions.push_back(implicit_caster);
    else
1434
        pybind11_fail("implicitly_convertible: Unable to find type " + type_id<OutputType>());
Wenzel Jakob's avatar
Wenzel Jakob committed
1435
1436
}

1437
1438
1439
1440
1441
1442
template <typename ExceptionTranslator>
void register_exception_translator(ExceptionTranslator&& translator) {
    detail::get_internals().registered_exception_translators.push_front(
        std::forward<ExceptionTranslator>(translator));
}

1443
1444
/**
 * Wrapper to generate a new Python exception type.
1445
1446
1447
1448
1449
1450
1451
1452
 *
 * This should only be used with PyErr_SetString for now.
 * It is not (yet) possible to use as a py::base.
 * Template type argument is reserved for future use.
 */
template <typename type>
class exception : public object {
public:
1453
1454
1455
    exception(handle scope, const char *name, PyObject *base = PyExc_Exception) {
        std::string full_name = scope.attr("__name__").cast<std::string>() +
                                std::string(".") + name;
1456
        m_ptr = PyErr_NewException(const_cast<char *>(full_name.c_str()), base, NULL);
1457
1458
1459
1460
        if (hasattr(scope, name))
            pybind11_fail("Error during initialization: multiple incompatible "
                          "definitions with name \"" + std::string(name) + "\"");
        scope.attr(name) = *this;
1461
    }
1462
1463
1464
1465
1466

    // Sets the current python exception to this exception object with the given message
    void operator()(const char *message) {
        PyErr_SetString(m_ptr, message);
    }
1467
1468
};

1469
1470
/**
 * Registers a Python exception in `m` of the given `name` and installs an exception translator to
1471
1472
1473
1474
 * translate the C++ exception to the created Python exception using the exceptions what() method.
 * This is intended for simple exception translations; for more complex translation, register the
 * exception object and translator directly.
 */
1475
1476
1477
1478
1479
template <typename CppException>
exception<CppException> &register_exception(handle scope,
                                            const char *name,
                                            PyObject *base = PyExc_Exception) {
    static exception<CppException> ex(scope, name, base);
1480
1481
1482
1483
    register_exception_translator([](std::exception_ptr p) {
        if (!p) return;
        try {
            std::rethrow_exception(p);
1484
        } catch (const CppException &e) {
1485
1486
1487
1488
1489
1490
            ex(e.what());
        }
    });
    return ex;
}

Dean Moldovan's avatar
Dean Moldovan committed
1491
1492
1493
1494
NAMESPACE_BEGIN(detail)
PYBIND11_NOINLINE inline void print(tuple args, dict kwargs) {
    auto strings = tuple(args.size());
    for (size_t i = 0; i < args.size(); ++i) {
1495
        strings[i] = str(args[i]);
Dean Moldovan's avatar
Dean Moldovan committed
1496
    }
1497
    auto sep = kwargs.contains("sep") ? kwargs["sep"] : cast(" ");
1498
    auto line = sep.attr("join")(strings);
Dean Moldovan's avatar
Dean Moldovan committed
1499

1500
1501
1502
1503
1504
1505
    object file;
    if (kwargs.contains("file")) {
        file = kwargs["file"].cast<object>();
    } else {
        try {
            file = module::import("sys").attr("stdout");
1506
        } catch (const error_already_set &) {
1507
1508
1509
1510
1511
1512
1513
1514
            /* If print() is called from code that is executed as
               part of garbage collection during interpreter shutdown,
               importing 'sys' can fail. Give up rather than crashing the
               interpreter in this case. */
            return;
        }
    }

1515
    auto write = file.attr("write");
Dean Moldovan's avatar
Dean Moldovan committed
1516
    write(line);
1517
    write(kwargs.contains("end") ? kwargs["end"] : cast("\n"));
Dean Moldovan's avatar
Dean Moldovan committed
1518

1519
    if (kwargs.contains("flush") && kwargs["flush"].cast<bool>())
1520
        file.attr("flush")();
Dean Moldovan's avatar
Dean Moldovan committed
1521
1522
1523
1524
1525
1526
1527
1528
1529
}
NAMESPACE_END(detail)

template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
void print(Args &&...args) {
    auto c = detail::collect_arguments<policy>(std::forward<Args>(args)...);
    detail::print(c.args(), c.kwargs());
}

Wenzel Jakob's avatar
Wenzel Jakob committed
1530
#if defined(WITH_THREAD) && !defined(PYPY_VERSION)
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544

/* The functions below essentially reproduce the PyGILState_* API using a RAII
 * pattern, but there are a few important differences:
 *
 * 1. When acquiring the GIL from an non-main thread during the finalization
 *    phase, the GILState API blindly terminates the calling thread, which
 *    is often not what is wanted. This API does not do this.
 *
 * 2. The gil_scoped_release function can optionally cut the relationship
 *    of a PyThreadState and its associated thread, which allows moving it to
 *    another thread (this is a fairly rare/advanced use case).
 *
 * 3. The reference count of an acquired thread state can be controlled. This
 *    can be handy to prevent cases where callbacks issued from an external
1545
1546
 *    thread would otherwise constantly construct and destroy thread state data
 *    structures.
1547
1548
1549
1550
1551
 *
 * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an
 * example which uses features 2 and 3 to migrate the Python thread of
 * execution to another thread (to run the event loop on the original thread,
 * in this case).
1552
 */
Wenzel Jakob's avatar
Wenzel Jakob committed
1553
1554
1555

class gil_scoped_acquire {
public:
1556
    PYBIND11_NOINLINE gil_scoped_acquire() {
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
        auto const &internals = detail::get_internals();
        tstate = (PyThreadState *) PyThread_get_key_value(internals.tstate);

        if (!tstate) {
            tstate = PyThreadState_New(internals.istate);
            #if !defined(NDEBUG)
                if (!tstate)
                    pybind11_fail("scoped_acquire: could not create thread state!");
            #endif
            tstate->gilstate_counter = 0;
1567
1568
1569
            #if PY_MAJOR_VERSION < 3
                PyThread_delete_key_value(internals.tstate);
            #endif
1570
1571
            PyThread_set_key_value(internals.tstate, tstate);
        } else {
1572
            release = detail::get_thread_state_unchecked() != tstate;
1573
1574
1575
1576
        }

        if (release) {
            /* Work around an annoying assertion in PyThreadState_Swap */
1577
1578
1579
1580
            #if defined(Py_DEBUG)
                PyInterpreterState *interp = tstate->interp;
                tstate->interp = nullptr;
            #endif
1581
            PyEval_AcquireThread(tstate);
1582
1583
1584
            #if defined(Py_DEBUG)
                tstate->interp = interp;
            #endif
1585
1586
1587
1588
1589
1590
1591
1592
1593
        }

        inc_ref();
    }

    void inc_ref() {
        ++tstate->gilstate_counter;
    }

1594
    PYBIND11_NOINLINE void dec_ref() {
1595
1596
        --tstate->gilstate_counter;
        #if !defined(NDEBUG)
1597
            if (detail::get_thread_state_unchecked() != tstate)
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
                pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!");
            if (tstate->gilstate_counter < 0)
                pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!");
        #endif
        if (tstate->gilstate_counter == 0) {
            #if !defined(NDEBUG)
                if (!release)
                    pybind11_fail("scoped_acquire::dec_ref(): internal error!");
            #endif
            PyThreadState_Clear(tstate);
            PyThreadState_DeleteCurrent();
1609
            PyThread_delete_key_value(detail::get_internals().tstate);
1610
1611
1612
1613
            release = false;
        }
    }

1614
    PYBIND11_NOINLINE ~gil_scoped_acquire() {
1615
1616
1617
1618
1619
1620
1621
        dec_ref();
        if (release)
           PyEval_SaveThread();
    }
private:
    PyThreadState *tstate = nullptr;
    bool release = true;
Wenzel Jakob's avatar
Wenzel Jakob committed
1622
1623
1624
1625
};

class gil_scoped_release {
public:
1626
    explicit gil_scoped_release(bool disassoc = false) : disassoc(disassoc) {
1627
        tstate = PyEval_SaveThread();
1628
        if (disassoc) {
1629
            auto key = detail::get_internals().tstate;
1630
1631
1632
1633
1634
1635
            #if PY_MAJOR_VERSION < 3
                PyThread_delete_key_value(key);
            #else
                PyThread_set_key_value(key, nullptr);
            #endif
        }
1636
1637
1638
1639
1640
    }
    ~gil_scoped_release() {
        if (!tstate)
            return;
        PyEval_RestoreThread(tstate);
1641
        if (disassoc) {
1642
            auto key = detail::get_internals().tstate;
1643
1644
1645
1646
1647
            #if PY_MAJOR_VERSION < 3
                PyThread_delete_key_value(key);
            #endif
            PyThread_set_key_value(key, tstate);
        }
1648
1649
1650
1651
    }
private:
    PyThreadState *tstate;
    bool disassoc;
Wenzel Jakob's avatar
Wenzel Jakob committed
1652
};
Wenzel Jakob's avatar
Wenzel Jakob committed
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
#elif defined(PYPY_VERSION)
class gil_scoped_acquire {
    PyGILState_STATE state;
public:
    gil_scoped_acquire() { state = PyGILState_Ensure(); }
    ~gil_scoped_acquire() { PyGILState_Release(state); }
};

class gil_scoped_release {
    PyThreadState *state;
public:
    gil_scoped_release() { state = PyEval_SaveThread(); }
    ~gil_scoped_release() { PyEval_RestoreThread(state); }
};
1667
1668
1669
#else
class gil_scoped_acquire { };
class gil_scoped_release { };
1670
#endif
Wenzel Jakob's avatar
Wenzel Jakob committed
1671

1672
1673
1674
error_already_set::~error_already_set() {
    if (value) {
        gil_scoped_acquire gil;
1675
        clear();
1676
1677
1678
    }
}

1679
inline function get_type_overload(const void *this_ptr, const detail::type_info *this_type, const char *name)  {
Wenzel Jakob's avatar
Wenzel Jakob committed
1680
1681
    handle self = detail::get_object_handle(this_ptr, this_type);
    if (!self)
1682
        return function();
Wenzel Jakob's avatar
Wenzel Jakob committed
1683
    handle type = self.get_type();
1684
1685
    auto key = std::make_pair(type.ptr(), name);

1686
1687
    /* Cache functions that aren't overloaded in Python to avoid
       many costly Python dictionary lookups below */
1688
1689
1690
1691
    auto &cache = detail::get_internals().inactive_overload_cache;
    if (cache.find(key) != cache.end())
        return function();

Wenzel Jakob's avatar
Wenzel Jakob committed
1692
    function overload = getattr(self, name, function());
1693
1694
1695
1696
    if (overload.is_cpp_function()) {
        cache.insert(key);
        return function();
    }
1697

Wenzel Jakob's avatar
Wenzel Jakob committed
1698
1699
1700
    /* Don't call dispatch code if invoked from overridden function.
       Unfortunately this doesn't work on PyPy. */
#if !defined(PYPY_VERSION)
1701
    PyFrameObject *frame = PyThreadState_Get()->frame;
1702
    if (frame && (std::string) str(frame->f_code->co_name) == name &&
1703
1704
1705
1706
        frame->f_code->co_argcount > 0) {
        PyFrame_FastToLocals(frame);
        PyObject *self_caller = PyDict_GetItem(
            frame->f_locals, PyTuple_GET_ITEM(frame->f_code->co_varnames, 0));
Wenzel Jakob's avatar
Wenzel Jakob committed
1707
        if (self_caller == self.ptr())
1708
1709
            return function();
    }
Wenzel Jakob's avatar
Wenzel Jakob committed
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
#else
    /* PyPy currently doesn't provide a detailed cpyext emulation of
       frame objects, so we have to emulate this using Python. This
       is going to be slow..*/
    dict d; d["self"] = self; d["name"] = pybind11::str(name);
    PyObject *result = PyRun_String(
        "import inspect\n"
        "frame = inspect.currentframe()\n"
        "if frame is not None:\n"
        "    frame = frame.f_back\n"
        "    if frame is not None and str(frame.f_code.co_name) == name and "
        "frame.f_code.co_argcount > 0:\n"
        "        self_caller = frame.f_locals[frame.f_code.co_varnames[0]]\n"
        "        if self_caller == self:\n"
        "            self = None\n",
        Py_file_input, d.ptr(), d.ptr());
    if (result == nullptr)
        throw error_already_set();
1728
    if (d["self"].is_none())
Wenzel Jakob's avatar
Wenzel Jakob committed
1729
1730
1731
1732
        return function();
    Py_DECREF(result);
#endif

1733
1734
1735
    return overload;
}

1736
template <class T> function get_overload(const T *this_ptr, const char *name) {
1737
1738
    auto tinfo = detail::get_type_info(typeid(T));
    return tinfo ? get_type_overload(this_ptr, tinfo, name) : function();
1739
1740
}

1741
#define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) { \
1742
        pybind11::gil_scoped_acquire gil; \
1743
        pybind11::function overload = pybind11::get_overload(static_cast<const cname *>(this), name); \
1744
        if (overload) { \
1745
            auto o = overload(__VA_ARGS__); \
1746
            if (pybind11::detail::cast_is_temporary_value_reference<ret_type>::value) { \
1747
1748
                static pybind11::detail::overload_caster_t<ret_type> caster; \
                return pybind11::detail::cast_ref<ret_type>(std::move(o), caster); \
1749
1750
1751
1752
            } \
            else return pybind11::detail::cast_safe<ret_type>(std::move(o)); \
        } \
    }
1753

1754
#define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \
1755
    PYBIND11_OVERLOAD_INT(ret_type, cname, name, __VA_ARGS__) \
1756
    return cname::fn(__VA_ARGS__)
1757

1758
#define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \
1759
    PYBIND11_OVERLOAD_INT(ret_type, cname, name, __VA_ARGS__) \
1760
1761
1762
1763
1764
1765
1766
    pybind11::pybind11_fail("Tried to call pure virtual function \"" #cname "::" name "\"");

#define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \
    PYBIND11_OVERLOAD_NAME(ret_type, cname, #fn, fn, __VA_ARGS__)

#define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \
    PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, #fn, fn, __VA_ARGS__)
1767

1768
NAMESPACE_END(pybind11)
Wenzel Jakob's avatar
Wenzel Jakob committed
1769
1770

#if defined(_MSC_VER)
Wenzel Jakob's avatar
Wenzel Jakob committed
1771
#  pragma warning(pop)
1772
1773
#elif defined(__INTEL_COMPILER)
/* Leave ignored warnings on */
1774
#elif defined(__GNUG__) && !defined(__clang__)
Wenzel Jakob's avatar
Wenzel Jakob committed
1775
#  pragma GCC diagnostic pop
Wenzel Jakob's avatar
Wenzel Jakob committed
1776
#endif