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