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