2 pybind11/pybind11.h: Main header file of the C++11 python
3 binding generator library
5 Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
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.
13 #if defined(__INTEL_COMPILER)
15 # pragma warning disable 68 // integer conversion resulted in a change of sign
16 # pragma warning disable 186 // pointless comparison of unsigned integer with zero
17 # pragma warning disable 878 // incompatible exception specifications
18 # pragma warning disable 1334 // the "template" keyword used for syntactic disambiguation may only be used within a template
19 # pragma warning disable 1682 // implicit conversion of a 64-bit integral type to a smaller integral type (potential portability problem)
20 # pragma warning disable 1786 // function "strdup" was declared deprecated
21 # pragma warning disable 1875 // offsetof applied to non-POD (Plain Old Data) types is nonstandard
22 # pragma warning disable 2196 // warning #2196: routine is both "inline" and "noinline"
23 #elif defined(_MSC_VER)
24 # pragma warning(push)
25 # pragma warning(disable: 4100) // warning C4100: Unreferenced formal parameter
26 # pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
27 # pragma warning(disable: 4512) // warning C4512: Assignment operator was implicitly defined as deleted
28 # pragma warning(disable: 4800) // warning C4800: 'int': forcing value to bool 'true' or 'false' (performance warning)
29 # pragma warning(disable: 4996) // warning C4996: The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name
30 # pragma warning(disable: 4702) // warning C4702: unreachable code
31 # pragma warning(disable: 4522) // warning C4522: multiple assignment operators specified
32 #elif defined(__GNUG__) && !defined(__clang__)
33 # pragma GCC diagnostic push
34 # pragma GCC diagnostic ignored "-Wunused-but-set-parameter"
35 # pragma GCC diagnostic ignored "-Wunused-but-set-variable"
36 # pragma GCC diagnostic ignored "-Wmissing-field-initializers"
37 # pragma GCC diagnostic ignored "-Wstrict-aliasing"
38 # pragma GCC diagnostic ignored "-Wattributes"
40 # pragma GCC diagnostic ignored "-Wnoexcept-type"
46 #include "detail/class.h"
47 #include "detail/init.h"
49 #if defined(__GNUG__) && !defined(__clang__)
53 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
55 /// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object
56 class cpp_function : public function {
59 cpp_function(std::nullptr_t) { }
61 /// Construct a cpp_function from a vanilla function pointer
62 template <typename Return, typename... Args, typename... Extra>
63 cpp_function(Return (*f)(Args...), const Extra&... extra) {
64 initialize(f, f, extra...);
67 /// Construct a cpp_function from a lambda function (possibly with internal state)
68 template <typename Func, typename... Extra,
69 typename = detail::enable_if_t<detail::is_lambda<Func>::value>>
70 cpp_function(Func &&f, const Extra&... extra) {
71 initialize(std::forward<Func>(f),
72 (detail::function_signature_t<Func> *) nullptr, extra...);
75 /// Construct a cpp_function from a class method (non-const)
76 template <typename Return, typename Class, typename... Arg, typename... Extra>
77 cpp_function(Return (Class::*f)(Arg...), const Extra&... extra) {
78 initialize([f](Class *c, Arg... args) -> Return { return (c->*f)(args...); },
79 (Return (*) (Class *, Arg...)) nullptr, extra...);
82 /// Construct a cpp_function from a class method (const)
83 template <typename Return, typename Class, typename... Arg, typename... Extra>
84 cpp_function(Return (Class::*f)(Arg...) const, const Extra&... extra) {
85 initialize([f](const Class *c, Arg... args) -> Return { return (c->*f)(args...); },
86 (Return (*)(const Class *, Arg ...)) nullptr, extra...);
89 /// Return the function name
90 object name() const { return attr("__name__"); }
93 /// Space optimization: don't inline this frequently instantiated fragment
94 PYBIND11_NOINLINE detail::function_record *make_function_record() {
95 return new detail::function_record();
98 /// Special internal constructor for functors, lambda functions, etc.
99 template <typename Func, typename Return, typename... Args, typename... Extra>
100 void initialize(Func &&f, Return (*)(Args...), const Extra&... extra) {
101 using namespace detail;
102 struct capture { remove_reference_t<Func> f; };
104 /* Store the function including any extra state it might have (e.g. a lambda capture object) */
105 auto rec = make_function_record();
107 /* Store the capture object directly in the function record if there is enough space */
108 if (sizeof(capture) <= sizeof(rec->data)) {
109 /* Without these pragmas, GCC warns that there might not be
110 enough space to use the placement new operator. However, the
111 'if' statement above ensures that this is the case. */
112 #if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
113 # pragma GCC diagnostic push
114 # pragma GCC diagnostic ignored "-Wplacement-new"
116 new ((capture *) &rec->data) capture { std::forward<Func>(f) };
117 #if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
118 # pragma GCC diagnostic pop
120 if (!std::is_trivially_destructible<Func>::value)
121 rec->free_data = [](function_record *r) { ((capture *) &r->data)->~capture(); };
123 rec->data[0] = new capture { std::forward<Func>(f) };
124 rec->free_data = [](function_record *r) { delete ((capture *) r->data[0]); };
127 /* Type casters for the function arguments and return value */
128 using cast_in = argument_loader<Args...>;
129 using cast_out = make_caster<
130 conditional_t<std::is_void<Return>::value, void_type, Return>
133 static_assert(expected_num_args<Extra...>(sizeof...(Args), cast_in::has_args, cast_in::has_kwargs),
134 "The number of argument annotations does not match the number of function arguments");
136 /* Dispatch code which converts function arguments and performs the actual function call */
137 rec->impl = [](function_call &call) -> handle {
138 cast_in args_converter;
140 /* Try to cast the function arguments into the C++ domain */
141 if (!args_converter.load_args(call))
142 return PYBIND11_TRY_NEXT_OVERLOAD;
144 /* Invoke call policy pre-call hook */
145 process_attributes<Extra...>::precall(call);
147 /* Get a pointer to the capture object */
148 auto data = (sizeof(capture) <= sizeof(call.func.data)
149 ? &call.func.data : call.func.data[0]);
150 capture *cap = const_cast<capture *>(reinterpret_cast<const capture *>(data));
152 /* Override policy for rvalues -- usually to enforce rvp::move on an rvalue */
153 return_value_policy policy = return_value_policy_override<Return>::policy(call.func.policy);
155 /* Function scope guard -- defaults to the compile-to-nothing `void_type` */
156 using Guard = extract_guard_t<Extra...>;
158 /* Perform the function call */
159 handle result = cast_out::cast(
160 std::move(args_converter).template call<Return, Guard>(cap->f), policy, call.parent);
162 /* Invoke call policy post-call hook */
163 process_attributes<Extra...>::postcall(call, result);
168 /* Process any user-provided function attributes */
169 process_attributes<Extra...>::init(extra..., rec);
171 /* Generate a readable signature describing the function's arguments and return value types */
172 static constexpr auto signature = _("(") + cast_in::arg_names + _(") -> ") + cast_out::name;
173 PYBIND11_DESCR_CONSTEXPR auto types = decltype(signature)::types();
175 /* Register the function with Python from generic (non-templated) code */
176 initialize_generic(rec, signature.text, types.data(), sizeof...(Args));
178 if (cast_in::has_args) rec->has_args = true;
179 if (cast_in::has_kwargs) rec->has_kwargs = true;
181 /* Stash some additional information used by an important optimization in 'functional.h' */
182 using FunctionType = Return (*)(Args...);
183 constexpr bool is_function_ptr =
184 std::is_convertible<Func, FunctionType>::value &&
185 sizeof(capture) == sizeof(void *);
186 if (is_function_ptr) {
187 rec->is_stateless = true;
188 rec->data[1] = const_cast<void *>(reinterpret_cast<const void *>(&typeid(FunctionType)));
192 /// Register a function call with Python (generic non-templated code goes here)
193 void initialize_generic(detail::function_record *rec, const char *text,
194 const std::type_info *const *types, size_t args) {
196 /* Create copies of all referenced C-style strings */
197 rec->name = strdup(rec->name ? rec->name : "");
198 if (rec->doc) rec->doc = strdup(rec->doc);
199 for (auto &a: rec->args) {
201 a.name = strdup(a.name);
203 a.descr = strdup(a.descr);
205 a.descr = strdup(a.value.attr("__repr__")().cast<std::string>().c_str());
208 rec->is_constructor = !strcmp(rec->name, "__init__") || !strcmp(rec->name, "__setstate__");
210 #if !defined(NDEBUG) && !defined(PYBIND11_DISABLE_NEW_STYLE_INIT_WARNING)
211 if (rec->is_constructor && !rec->is_new_style_constructor) {
212 const auto class_name = std::string(((PyTypeObject *) rec->scope.ptr())->tp_name);
213 const auto func_name = std::string(rec->name);
216 ("pybind11-bound class '" + class_name + "' is using an old-style "
217 "placement-new '" + func_name + "' which has been deprecated. See "
218 "the upgrade guide in pybind11's docs. This message is only visible "
219 "when compiled in debug mode.").c_str(), 0
224 /* Generate a proper function signature */
225 std::string signature;
226 size_t type_index = 0, arg_index = 0;
227 for (auto *pc = text; *pc != '\0'; ++pc) {
231 // Write arg name for everything except *args and **kwargs.
232 if (*(pc + 1) == '*')
235 if (arg_index < rec->args.size() && rec->args[arg_index].name) {
236 signature += rec->args[arg_index].name;
237 } else if (arg_index == 0 && rec->is_method) {
240 signature += "arg" + std::to_string(arg_index - (rec->is_method ? 1 : 0));
243 } else if (c == '}') {
244 // Write default value if available.
245 if (arg_index < rec->args.size() && rec->args[arg_index].descr) {
247 signature += rec->args[arg_index].descr;
250 } else if (c == '%') {
251 const std::type_info *t = types[type_index++];
253 pybind11_fail("Internal error while parsing type signature (1)");
254 if (auto tinfo = detail::get_type_info(*t)) {
255 handle th((PyObject *) tinfo->type);
257 th.attr("__module__").cast<std::string>() + "." +
258 th.attr("__qualname__").cast<std::string>(); // Python 3.3+, but we backport it to earlier versions
259 } else if (rec->is_new_style_constructor && arg_index == 0) {
260 // A new-style `__init__` takes `self` as `value_and_holder`.
261 // Rewrite it to the proper class type.
263 rec->scope.attr("__module__").cast<std::string>() + "." +
264 rec->scope.attr("__qualname__").cast<std::string>();
266 std::string tname(t->name());
267 detail::clean_type_id(tname);
274 if (arg_index != args || types[type_index] != nullptr)
275 pybind11_fail("Internal error while parsing type signature (2)");
277 #if PY_MAJOR_VERSION < 3
278 if (strcmp(rec->name, "__next__") == 0) {
279 std::free(rec->name);
280 rec->name = strdup("next");
281 } else if (strcmp(rec->name, "__bool__") == 0) {
282 std::free(rec->name);
283 rec->name = strdup("__nonzero__");
286 rec->signature = strdup(signature.c_str());
287 rec->args.shrink_to_fit();
288 rec->nargs = (std::uint16_t) args;
290 if (rec->sibling && PYBIND11_INSTANCE_METHOD_CHECK(rec->sibling.ptr()))
291 rec->sibling = PYBIND11_INSTANCE_METHOD_GET_FUNCTION(rec->sibling.ptr());
293 detail::function_record *chain = nullptr, *chain_start = rec;
295 if (PyCFunction_Check(rec->sibling.ptr())) {
296 auto rec_capsule = reinterpret_borrow<capsule>(PyCFunction_GET_SELF(rec->sibling.ptr()));
297 chain = (detail::function_record *) rec_capsule;
298 /* Never append a method to an overload chain of a parent class;
299 instead, hide the parent's overloads in this case */
300 if (!chain->scope.is(rec->scope))
303 // Don't trigger for things like the default __init__, which are wrapper_descriptors that we are intentionally replacing
304 else if (!rec->sibling.is_none() && rec->name[0] != '_')
305 pybind11_fail("Cannot overload existing non-function object \"" + std::string(rec->name) +
306 "\" with a function of the same name");
310 /* No existing overload was found, create a new function object */
311 rec->def = new PyMethodDef();
312 std::memset(rec->def, 0, sizeof(PyMethodDef));
313 rec->def->ml_name = rec->name;
314 rec->def->ml_meth = reinterpret_cast<PyCFunction>(reinterpret_cast<void (*) (void)>(*dispatcher));
315 rec->def->ml_flags = METH_VARARGS | METH_KEYWORDS;
317 capsule rec_capsule(rec, [](void *ptr) {
318 destruct((detail::function_record *) ptr);
323 if (hasattr(rec->scope, "__module__")) {
324 scope_module = rec->scope.attr("__module__");
325 } else if (hasattr(rec->scope, "__name__")) {
326 scope_module = rec->scope.attr("__name__");
330 m_ptr = PyCFunction_NewEx(rec->def, rec_capsule.ptr(), scope_module.ptr());
332 pybind11_fail("cpp_function::cpp_function(): Could not allocate function object");
334 /* Append at the end of the overload chain */
335 m_ptr = rec->sibling.ptr();
338 if (chain->is_method != rec->is_method)
339 pybind11_fail("overloading a method with both static and instance methods is not supported; "
341 "compile in debug mode for more details"
343 "error while attempting to bind " + std::string(rec->is_method ? "instance" : "static") + " method " +
344 std::string(pybind11::str(rec->scope.attr("__name__"))) + "." + std::string(rec->name) + signature
352 std::string signatures;
354 /* Create a nice pydoc rec including all signatures and
355 docstrings of the functions in the overload chain */
356 if (chain && options::show_function_signatures()) {
357 // First a generic signature
358 signatures += rec->name;
359 signatures += "(*args, **kwargs)\n";
360 signatures += "Overloaded function.\n\n";
362 // Then specific overload signatures
363 bool first_user_def = true;
364 for (auto it = chain_start; it != nullptr; it = it->next) {
365 if (options::show_function_signatures()) {
366 if (index > 0) signatures += "\n";
368 signatures += std::to_string(++index) + ". ";
369 signatures += rec->name;
370 signatures += it->signature;
373 if (it->doc && strlen(it->doc) > 0 && options::show_user_defined_docstrings()) {
374 // If we're appending another docstring, and aren't printing function signatures, we
375 // need to append a newline first:
376 if (!options::show_function_signatures()) {
377 if (first_user_def) first_user_def = false;
378 else signatures += "\n";
380 if (options::show_function_signatures()) signatures += "\n";
381 signatures += it->doc;
382 if (options::show_function_signatures()) signatures += "\n";
386 /* Install docstring */
387 PyCFunctionObject *func = (PyCFunctionObject *) m_ptr;
388 if (func->m_ml->ml_doc)
389 std::free(const_cast<char *>(func->m_ml->ml_doc));
390 func->m_ml->ml_doc = strdup(signatures.c_str());
392 if (rec->is_method) {
393 m_ptr = PYBIND11_INSTANCE_METHOD_NEW(m_ptr, rec->scope.ptr());
395 pybind11_fail("cpp_function::cpp_function(): Could not allocate instance method object");
400 /// When a cpp_function is GCed, release any memory allocated by pybind11
401 static void destruct(detail::function_record *rec) {
403 detail::function_record *next = rec->next;
406 std::free((char *) rec->name);
407 std::free((char *) rec->doc);
408 std::free((char *) rec->signature);
409 for (auto &arg: rec->args) {
410 std::free(const_cast<char *>(arg.name));
411 std::free(const_cast<char *>(arg.descr));
415 std::free(const_cast<char *>(rec->def->ml_doc));
423 /// Main dispatch logic for calls to functions bound using pybind11
424 static PyObject *dispatcher(PyObject *self, PyObject *args_in, PyObject *kwargs_in) {
425 using namespace detail;
427 /* Iterator over the list of potentially admissible overloads */
428 const function_record *overloads = (function_record *) PyCapsule_GetPointer(self, nullptr),
431 /* Need to know how many arguments + keyword arguments there are to pick the right overload */
432 const size_t n_args_in = (size_t) PyTuple_GET_SIZE(args_in);
434 handle parent = n_args_in > 0 ? PyTuple_GET_ITEM(args_in, 0) : nullptr,
435 result = PYBIND11_TRY_NEXT_OVERLOAD;
437 auto self_value_and_holder = value_and_holder();
438 if (overloads->is_constructor) {
439 const auto tinfo = get_type_info((PyTypeObject *) overloads->scope.ptr());
440 const auto pi = reinterpret_cast<instance *>(parent.ptr());
441 self_value_and_holder = pi->get_value_and_holder(tinfo, false);
443 if (!self_value_and_holder.type || !self_value_and_holder.inst) {
444 PyErr_SetString(PyExc_TypeError, "__init__(self, ...) called with invalid `self` argument");
448 // If this value is already registered it must mean __init__ is invoked multiple times;
449 // we really can't support that in C++, so just ignore the second __init__.
450 if (self_value_and_holder.instance_registered())
451 return none().release().ptr();
455 // We do this in two passes: in the first pass, we load arguments with `convert=false`;
456 // in the second, we allow conversion (except for arguments with an explicit
457 // py::arg().noconvert()). This lets us prefer calls without conversion, with
458 // conversion as a fallback.
459 std::vector<function_call> second_pass;
461 // However, if there are no overloads, we can just skip the no-convert pass entirely
462 const bool overloaded = it != nullptr && it->next != nullptr;
464 for (; it != nullptr; it = it->next) {
466 /* For each overload:
467 1. Copy all positional arguments we were given, also checking to make sure that
468 named positional arguments weren't *also* specified via kwarg.
469 2. If we weren't given enough, try to make up the omitted ones by checking
470 whether they were provided by a kwarg matching the `py::arg("name")` name. If
471 so, use it (and remove it from kwargs; if not, see if the function binding
472 provided a default that we can use.
473 3. Ensure that either all keyword arguments were "consumed", or that the function
474 takes a kwargs argument to accept unconsumed kwargs.
475 4. Any positional arguments still left get put into a tuple (for args), and any
476 leftover kwargs get put into a dict.
477 5. Pack everything into a vector; if we have py::args or py::kwargs, they are an
478 extra tuple or dict at the end of the positional arguments.
479 6. Call the function call dispatcher (function_record::impl)
481 If one of these fail, move on to the next overload and keep trying until we get a
482 result other than PYBIND11_TRY_NEXT_OVERLOAD.
485 const function_record &func = *it;
486 size_t pos_args = func.nargs; // Number of positional arguments that we need
487 if (func.has_args) --pos_args; // (but don't count py::args
488 if (func.has_kwargs) --pos_args; // or py::kwargs)
490 if (!func.has_args && n_args_in > pos_args)
491 continue; // Too many arguments for this overload
493 if (n_args_in < pos_args && func.args.size() < pos_args)
494 continue; // Not enough arguments given, and not enough defaults to fill in the blanks
496 function_call call(func, parent);
498 size_t args_to_copy = (std::min)(pos_args, n_args_in); // Protect std::min with parentheses
499 size_t args_copied = 0;
501 // 0. Inject new-style `self` argument
502 if (func.is_new_style_constructor) {
503 // The `value` may have been preallocated by an old-style `__init__`
504 // if it was a preceding candidate for overload resolution.
505 if (self_value_and_holder)
506 self_value_and_holder.type->dealloc(self_value_and_holder);
508 call.init_self = PyTuple_GET_ITEM(args_in, 0);
509 call.args.push_back(reinterpret_cast<PyObject *>(&self_value_and_holder));
510 call.args_convert.push_back(false);
514 // 1. Copy any position arguments given.
515 bool bad_arg = false;
516 for (; args_copied < args_to_copy; ++args_copied) {
517 const argument_record *arg_rec = args_copied < func.args.size() ? &func.args[args_copied] : nullptr;
518 if (kwargs_in && arg_rec && arg_rec->name && PyDict_GetItemString(kwargs_in, arg_rec->name)) {
523 handle arg(PyTuple_GET_ITEM(args_in, args_copied));
524 if (arg_rec && !arg_rec->none && arg.is_none()) {
528 call.args.push_back(arg);
529 call.args_convert.push_back(arg_rec ? arg_rec->convert : true);
532 continue; // Maybe it was meant for another overload (issue #688)
534 // We'll need to copy this if we steal some kwargs for defaults
535 dict kwargs = reinterpret_borrow<dict>(kwargs_in);
537 // 2. Check kwargs and, failing that, defaults that may help complete the list
538 if (args_copied < pos_args) {
539 bool copied_kwargs = false;
541 for (; args_copied < pos_args; ++args_copied) {
542 const auto &arg = func.args[args_copied];
545 if (kwargs_in && arg.name)
546 value = PyDict_GetItemString(kwargs.ptr(), arg.name);
549 // Consume a kwargs value
550 if (!copied_kwargs) {
551 kwargs = reinterpret_steal<dict>(PyDict_Copy(kwargs.ptr()));
552 copied_kwargs = true;
554 PyDict_DelItemString(kwargs.ptr(), arg.name);
555 } else if (arg.value) {
560 call.args.push_back(value);
561 call.args_convert.push_back(arg.convert);
567 if (args_copied < pos_args)
568 continue; // Not enough arguments, defaults, or kwargs to fill the positional arguments
571 // 3. Check everything was consumed (unless we have a kwargs arg)
572 if (kwargs && kwargs.size() > 0 && !func.has_kwargs)
573 continue; // Unconsumed kwargs, but no py::kwargs argument to accept them
575 // 4a. If we have a py::args argument, create a new tuple with leftovers
578 if (args_to_copy == 0) {
579 // We didn't copy out any position arguments from the args_in tuple, so we
580 // can reuse it directly without copying:
581 extra_args = reinterpret_borrow<tuple>(args_in);
582 } else if (args_copied >= n_args_in) {
583 extra_args = tuple(0);
585 size_t args_size = n_args_in - args_copied;
586 extra_args = tuple(args_size);
587 for (size_t i = 0; i < args_size; ++i) {
588 extra_args[i] = PyTuple_GET_ITEM(args_in, args_copied + i);
591 call.args.push_back(extra_args);
592 call.args_convert.push_back(false);
593 call.args_ref = std::move(extra_args);
596 // 4b. If we have a py::kwargs, pass on any remaining kwargs
597 if (func.has_kwargs) {
599 kwargs = dict(); // If we didn't get one, send an empty one
600 call.args.push_back(kwargs);
601 call.args_convert.push_back(false);
602 call.kwargs_ref = std::move(kwargs);
605 // 5. Put everything in a vector. Not technically step 5, we've been building it
606 // in `call.args` all along.
608 if (call.args.size() != func.nargs || call.args_convert.size() != func.nargs)
609 pybind11_fail("Internal error: function call dispatcher inserted wrong number of arguments!");
612 std::vector<bool> second_pass_convert;
614 // We're in the first no-convert pass, so swap out the conversion flags for a
615 // set of all-false flags. If the call fails, we'll swap the flags back in for
616 // the conversion-allowed call below.
617 second_pass_convert.resize(func.nargs, false);
618 call.args_convert.swap(second_pass_convert);
621 // 6. Call the function.
623 loader_life_support guard{};
624 result = func.impl(call);
625 } catch (reference_cast_error &) {
626 result = PYBIND11_TRY_NEXT_OVERLOAD;
629 if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD)
633 // The (overloaded) call failed; if the call has at least one argument that
634 // permits conversion (i.e. it hasn't been explicitly specified `.noconvert()`)
635 // then add this call to the list of second pass overloads to try.
636 for (size_t i = func.is_method ? 1 : 0; i < pos_args; i++) {
637 if (second_pass_convert[i]) {
638 // Found one: swap the converting flags back in and store the call for
640 call.args_convert.swap(second_pass_convert);
641 second_pass.push_back(std::move(call));
648 if (overloaded && !second_pass.empty() && result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) {
649 // The no-conversion pass finished without success, try again with conversion allowed
650 for (auto &call : second_pass) {
652 loader_life_support guard{};
653 result = call.func.impl(call);
654 } catch (reference_cast_error &) {
655 result = PYBIND11_TRY_NEXT_OVERLOAD;
658 if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD) {
659 // The error reporting logic below expects 'it' to be valid, as it would be
660 // if we'd encountered this failure in the first-pass loop.
667 } catch (error_already_set &e) {
670 #if defined(__GNUG__) && !defined(__clang__)
671 } catch ( abi::__forced_unwind& ) {
675 /* When an exception is caught, give each registered exception
676 translator a chance to translate it to a Python exception
677 in reverse order of registration.
679 A translator may choose to do one of the following:
681 - catch the exception and call PyErr_SetString or PyErr_SetObject
682 to set a standard (or custom) Python exception, or
683 - do nothing and let the exception fall through to the next translator, or
684 - delegate translation to the next translator by throwing a new type of exception. */
686 auto last_exception = std::current_exception();
687 auto ®istered_exception_translators = get_internals().registered_exception_translators;
688 for (auto& translator : registered_exception_translators) {
690 translator(last_exception);
692 last_exception = std::current_exception();
697 PyErr_SetString(PyExc_SystemError, "Exception escaped from default exception translator!");
701 auto append_note_if_missing_header_is_suspected = [](std::string &msg) {
702 if (msg.find("std::") != std::string::npos) {
704 "Did you forget to `#include <pybind11/stl.h>`? Or <pybind11/complex.h>,\n"
705 "<pybind11/functional.h>, <pybind11/chrono.h>, etc. Some automatic\n"
706 "conversions are optional and require extra headers to be included\n"
707 "when compiling your pybind11 module.";
711 if (result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) {
712 if (overloads->is_operator)
713 return handle(Py_NotImplemented).inc_ref().ptr();
715 std::string msg = std::string(overloads->name) + "(): incompatible " +
716 std::string(overloads->is_constructor ? "constructor" : "function") +
717 " arguments. The following argument types are supported:\n";
720 for (const function_record *it2 = overloads; it2 != nullptr; it2 = it2->next) {
721 msg += " "+ std::to_string(++ctr) + ". ";
723 bool wrote_sig = false;
724 if (overloads->is_constructor) {
725 // For a constructor, rewrite `(self: Object, arg0, ...) -> NoneType` as `Object(arg0, ...)`
726 std::string sig = it2->signature;
727 size_t start = sig.find('(') + 7; // skip "(self: "
728 if (start < sig.size()) {
729 // End at the , for the next argument
730 size_t end = sig.find(", "), next = end + 2;
731 size_t ret = sig.rfind(" -> ");
732 // Or the ), if there is no comma:
733 if (end >= sig.size()) next = end = sig.find(')');
734 if (start < end && next < sig.size()) {
735 msg.append(sig, start, end - start);
737 msg.append(sig, next, ret - next);
742 if (!wrote_sig) msg += it2->signature;
746 msg += "\nInvoked with: ";
747 auto args_ = reinterpret_borrow<tuple>(args_in);
748 bool some_args = false;
749 for (size_t ti = overloads->is_constructor ? 1 : 0; ti < args_.size(); ++ti) {
750 if (!some_args) some_args = true;
752 msg += pybind11::repr(args_[ti]);
755 auto kwargs = reinterpret_borrow<dict>(kwargs_in);
756 if (kwargs.size() > 0) {
757 if (some_args) msg += "; ";
760 for (auto kwarg : kwargs) {
761 if (first) first = false;
763 msg += pybind11::str("{}={!r}").format(kwarg.first, kwarg.second);
768 append_note_if_missing_header_is_suspected(msg);
769 PyErr_SetString(PyExc_TypeError, msg.c_str());
771 } else if (!result) {
772 std::string msg = "Unable to convert function return value to a "
773 "Python type! The signature was\n\t";
774 msg += it->signature;
775 append_note_if_missing_header_is_suspected(msg);
776 PyErr_SetString(PyExc_TypeError, msg.c_str());
779 if (overloads->is_constructor && !self_value_and_holder.holder_constructed()) {
780 auto *pi = reinterpret_cast<instance *>(parent.ptr());
781 self_value_and_holder.type->init_instance(pi, nullptr);
788 /// Wrapper for Python extension modules
789 class module : public object {
791 PYBIND11_OBJECT_DEFAULT(module, object, PyModule_Check)
793 /// Create a new top-level Python module with the given name and docstring
794 explicit module(const char *name, const char *doc = nullptr) {
795 if (!options::show_user_defined_docstrings()) doc = nullptr;
796 #if PY_MAJOR_VERSION >= 3
797 PyModuleDef *def = new PyModuleDef();
798 std::memset(def, 0, sizeof(PyModuleDef));
803 m_ptr = PyModule_Create(def);
805 m_ptr = Py_InitModule3(name, nullptr, doc);
807 if (m_ptr == nullptr)
808 pybind11_fail("Internal error in module::module()");
813 Create Python binding for a new function within the module scope. ``Func``
814 can be a plain C++ function, a function pointer, or a lambda function. For
815 details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
817 template <typename Func, typename... Extra>
818 module &def(const char *name_, Func &&f, const Extra& ... extra) {
819 cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
820 sibling(getattr(*this, name_, none())), extra...);
821 // NB: allow overwriting here because cpp_function sets up a chain with the intention of
822 // overwriting (and has already checked internally that it isn't overwriting non-functions).
823 add_object(name_, func, true /* overwrite */);
828 Create and return a new Python submodule with the given name and docstring.
829 This also works recursively, i.e.
833 py::module m("example", "pybind11 example plugin");
834 py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
835 py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
837 module def_submodule(const char *name, const char *doc = nullptr) {
838 std::string full_name = std::string(PyModule_GetName(m_ptr))
839 + std::string(".") + std::string(name);
840 auto result = reinterpret_borrow<module>(PyImport_AddModule(full_name.c_str()));
841 if (doc && options::show_user_defined_docstrings())
842 result.attr("__doc__") = pybind11::str(doc);
847 /// Import and return a module or throws `error_already_set`.
848 static module import(const char *name) {
849 PyObject *obj = PyImport_ImportModule(name);
851 throw error_already_set();
852 return reinterpret_steal<module>(obj);
855 /// Reload the module or throws `error_already_set`.
857 PyObject *obj = PyImport_ReloadModule(ptr());
859 throw error_already_set();
860 *this = reinterpret_steal<module>(obj);
863 // Adds an object to the module using the given name. Throws if an object with the given name
866 // overwrite should almost always be false: attempting to overwrite objects that pybind11 has
867 // established will, in most cases, break things.
868 PYBIND11_NOINLINE void add_object(const char *name, handle obj, bool overwrite = false) {
869 if (!overwrite && hasattr(*this, name))
870 pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" +
871 std::string(name) + "\"");
873 PyModule_AddObject(ptr(), name, obj.inc_ref().ptr() /* steals a reference */);
877 /// \ingroup python_builtins
878 /// Return a dictionary representing the global variables in the current execution frame,
879 /// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded).
880 inline dict globals() {
881 PyObject *p = PyEval_GetGlobals();
882 return reinterpret_borrow<dict>(p ? p : module::import("__main__").attr("__dict__").ptr());
885 NAMESPACE_BEGIN(detail)
886 /// Generic support for creating new Python heap types
887 class generic_type : public object {
888 template <typename...> friend class class_;
890 PYBIND11_OBJECT_DEFAULT(generic_type, object, PyType_Check)
892 void initialize(const type_record &rec) {
893 if (rec.scope && hasattr(rec.scope, rec.name))
894 pybind11_fail("generic_type: cannot initialize type \"" + std::string(rec.name) +
895 "\": an object with that name is already defined");
897 if (rec.module_local ? get_local_type_info(*rec.type) : get_global_type_info(*rec.type))
898 pybind11_fail("generic_type: type \"" + std::string(rec.name) +
899 "\" is already registered!");
901 m_ptr = make_new_python_type(rec);
903 /* Register supplemental type information in C++ dict */
904 auto *tinfo = new detail::type_info();
905 tinfo->type = (PyTypeObject *) m_ptr;
906 tinfo->cpptype = rec.type;
907 tinfo->type_size = rec.type_size;
908 tinfo->type_align = rec.type_align;
909 tinfo->operator_new = rec.operator_new;
910 tinfo->holder_size_in_ptrs = size_in_ptrs(rec.holder_size);
911 tinfo->init_instance = rec.init_instance;
912 tinfo->dealloc = rec.dealloc;
913 tinfo->simple_type = true;
914 tinfo->simple_ancestors = true;
915 tinfo->default_holder = rec.default_holder;
916 tinfo->module_local = rec.module_local;
918 auto &internals = get_internals();
919 auto tindex = std::type_index(*rec.type);
920 tinfo->direct_conversions = &internals.direct_conversions[tindex];
921 if (rec.module_local)
922 registered_local_types_cpp()[tindex] = tinfo;
924 internals.registered_types_cpp[tindex] = tinfo;
925 internals.registered_types_py[(PyTypeObject *) m_ptr] = { tinfo };
927 if (rec.bases.size() > 1 || rec.multiple_inheritance) {
928 mark_parents_nonsimple(tinfo->type);
929 tinfo->simple_ancestors = false;
931 else if (rec.bases.size() == 1) {
932 auto parent_tinfo = get_type_info((PyTypeObject *) rec.bases[0].ptr());
933 tinfo->simple_ancestors = parent_tinfo->simple_ancestors;
936 if (rec.module_local) {
937 // Stash the local typeinfo and loader so that external modules can access it.
938 tinfo->module_local_load = &type_caster_generic::local_load;
939 setattr(m_ptr, PYBIND11_MODULE_LOCAL_ID, capsule(tinfo));
943 /// Helper function which tags all parents of a type using mult. inheritance
944 void mark_parents_nonsimple(PyTypeObject *value) {
945 auto t = reinterpret_borrow<tuple>(value->tp_bases);
947 auto tinfo2 = get_type_info((PyTypeObject *) h.ptr());
949 tinfo2->simple_type = false;
950 mark_parents_nonsimple((PyTypeObject *) h.ptr());
954 void install_buffer_funcs(
955 buffer_info *(*get_buffer)(PyObject *, void *),
956 void *get_buffer_data) {
957 PyHeapTypeObject *type = (PyHeapTypeObject*) m_ptr;
958 auto tinfo = detail::get_type_info(&type->ht_type);
960 if (!type->ht_type.tp_as_buffer)
962 "To be able to register buffer protocol support for the type '" +
963 std::string(tinfo->type->tp_name) +
964 "' the associated class<>(..) invocation must "
965 "include the pybind11::buffer_protocol() annotation!");
967 tinfo->get_buffer = get_buffer;
968 tinfo->get_buffer_data = get_buffer_data;
971 // rec_func must be set for either fget or fset.
972 void def_property_static_impl(const char *name,
973 handle fget, handle fset,
974 detail::function_record *rec_func) {
975 const auto is_static = rec_func && !(rec_func->is_method && rec_func->scope);
976 const auto has_doc = rec_func && rec_func->doc && pybind11::options::show_user_defined_docstrings();
977 auto property = handle((PyObject *) (is_static ? get_internals().static_property_type
978 : &PyProperty_Type));
979 attr(name) = property(fget.ptr() ? fget : none(),
980 fset.ptr() ? fset : none(),
982 pybind11::str(has_doc ? rec_func->doc : ""));
986 /// Set the pointer to operator new if it exists. The cast is needed because it can be overloaded.
987 template <typename T, typename = void_t<decltype(static_cast<void *(*)(size_t)>(T::operator new))>>
988 void set_operator_new(type_record *r) { r->operator_new = &T::operator new; }
990 template <typename> void set_operator_new(...) { }
992 template <typename T, typename SFINAE = void> struct has_operator_delete : std::false_type { };
993 template <typename T> struct has_operator_delete<T, void_t<decltype(static_cast<void (*)(void *)>(T::operator delete))>>
994 : std::true_type { };
995 template <typename T, typename SFINAE = void> struct has_operator_delete_size : std::false_type { };
996 template <typename T> struct has_operator_delete_size<T, void_t<decltype(static_cast<void (*)(void *, size_t)>(T::operator delete))>>
997 : std::true_type { };
998 /// Call class-specific delete if it exists or global otherwise. Can also be an overload set.
999 template <typename T, enable_if_t<has_operator_delete<T>::value, int> = 0>
1000 void call_operator_delete(T *p, size_t, size_t) { T::operator delete(p); }
1001 template <typename T, enable_if_t<!has_operator_delete<T>::value && has_operator_delete_size<T>::value, int> = 0>
1002 void call_operator_delete(T *p, size_t s, size_t) { T::operator delete(p, s); }
1004 inline void call_operator_delete(void *p, size_t s, size_t a) {
1006 #if defined(PYBIND11_CPP17)
1007 if (a > __STDCPP_DEFAULT_NEW_ALIGNMENT__)
1008 ::operator delete(p, s, std::align_val_t(a));
1010 ::operator delete(p, s);
1012 ::operator delete(p);
1016 NAMESPACE_END(detail)
1018 /// Given a pointer to a member function, cast it to its `Derived` version.
1019 /// Forward everything else unchanged.
1020 template <typename /*Derived*/, typename F>
1021 auto method_adaptor(F &&f) -> decltype(std::forward<F>(f)) { return std::forward<F>(f); }
1023 template <typename Derived, typename Return, typename Class, typename... Args>
1024 auto method_adaptor(Return (Class::*pmf)(Args...)) -> Return (Derived::*)(Args...) {
1025 static_assert(detail::is_accessible_base_of<Class, Derived>::value,
1026 "Cannot bind an inaccessible base class method; use a lambda definition instead");
1030 template <typename Derived, typename Return, typename Class, typename... Args>
1031 auto method_adaptor(Return (Class::*pmf)(Args...) const) -> Return (Derived::*)(Args...) const {
1032 static_assert(detail::is_accessible_base_of<Class, Derived>::value,
1033 "Cannot bind an inaccessible base class method; use a lambda definition instead");
1037 template <typename type_, typename... options>
1038 class class_ : public detail::generic_type {
1039 template <typename T> using is_holder = detail::is_holder_type<type_, T>;
1040 template <typename T> using is_subtype = detail::is_strict_base_of<type_, T>;
1041 template <typename T> using is_base = detail::is_strict_base_of<T, type_>;
1042 // struct instead of using here to help MSVC:
1043 template <typename T> struct is_valid_class_option :
1044 detail::any_of<is_holder<T>, is_subtype<T>, is_base<T>> {};
1048 using type_alias = detail::exactly_one_t<is_subtype, void, options...>;
1049 constexpr static bool has_alias = !std::is_void<type_alias>::value;
1050 using holder_type = detail::exactly_one_t<is_holder, std::unique_ptr<type>, options...>;
1052 static_assert(detail::all_of<is_valid_class_option<options>...>::value,
1053 "Unknown/invalid class_ template parameters provided");
1055 static_assert(!has_alias || std::is_polymorphic<type>::value,
1056 "Cannot use an alias class with a non-polymorphic type");
1058 PYBIND11_OBJECT(class_, generic_type, PyType_Check)
1060 template <typename... Extra>
1061 class_(handle scope, const char *name, const Extra &... extra) {
1062 using namespace detail;
1064 // MI can only be specified via class_ template options, not constructor parameters
1066 none_of<is_pyobject<Extra>...>::value || // no base class arguments, or:
1067 ( constexpr_sum(is_pyobject<Extra>::value...) == 1 && // Exactly one base
1068 constexpr_sum(is_base<options>::value...) == 0 && // no template option bases
1069 none_of<std::is_same<multiple_inheritance, Extra>...>::value), // no multiple_inheritance attr
1070 "Error: multiple inheritance bases must be specified via class_ template options");
1073 record.scope = scope;
1075 record.type = &typeid(type);
1076 record.type_size = sizeof(conditional_t<has_alias, type_alias, type>);
1077 record.type_align = alignof(conditional_t<has_alias, type_alias, type>&);
1078 record.holder_size = sizeof(holder_type);
1079 record.init_instance = init_instance;
1080 record.dealloc = dealloc;
1081 record.default_holder = detail::is_instantiation<std::unique_ptr, holder_type>::value;
1083 set_operator_new<type>(&record);
1085 /* Register base classes specified via template arguments to class_, if any */
1086 PYBIND11_EXPAND_SIDE_EFFECTS(add_base<options>(record));
1088 /* Process optional arguments, if any */
1089 process_attributes<Extra...>::init(extra..., &record);
1091 generic_type::initialize(record);
1094 auto &instances = record.module_local ? registered_local_types_cpp() : get_internals().registered_types_cpp;
1095 instances[std::type_index(typeid(type_alias))] = instances[std::type_index(typeid(type))];
1099 template <typename Base, detail::enable_if_t<is_base<Base>::value, int> = 0>
1100 static void add_base(detail::type_record &rec) {
1101 rec.add_base(typeid(Base), [](void *src) -> void * {
1102 return static_cast<Base *>(reinterpret_cast<type *>(src));
1106 template <typename Base, detail::enable_if_t<!is_base<Base>::value, int> = 0>
1107 static void add_base(detail::type_record &) { }
1109 template <typename Func, typename... Extra>
1110 class_ &def(const char *name_, Func&& f, const Extra&... extra) {
1111 cpp_function cf(method_adaptor<type>(std::forward<Func>(f)), name(name_), is_method(*this),
1112 sibling(getattr(*this, name_, none())), extra...);
1113 attr(cf.name()) = cf;
1117 template <typename Func, typename... Extra> class_ &
1118 def_static(const char *name_, Func &&f, const Extra&... extra) {
1119 static_assert(!std::is_member_function_pointer<Func>::value,
1120 "def_static(...) called with a non-static member function pointer");
1121 cpp_function cf(std::forward<Func>(f), name(name_), scope(*this),
1122 sibling(getattr(*this, name_, none())), extra...);
1123 attr(cf.name()) = staticmethod(cf);
1127 template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
1128 class_ &def(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
1129 op.execute(*this, extra...);
1133 template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra>
1134 class_ & def_cast(const detail::op_<id, ot, L, R> &op, const Extra&... extra) {
1135 op.execute_cast(*this, extra...);
1139 template <typename... Args, typename... Extra>
1140 class_ &def(const detail::initimpl::constructor<Args...> &init, const Extra&... extra) {
1141 init.execute(*this, extra...);
1145 template <typename... Args, typename... Extra>
1146 class_ &def(const detail::initimpl::alias_constructor<Args...> &init, const Extra&... extra) {
1147 init.execute(*this, extra...);
1151 template <typename... Args, typename... Extra>
1152 class_ &def(detail::initimpl::factory<Args...> &&init, const Extra&... extra) {
1153 std::move(init).execute(*this, extra...);
1157 template <typename... Args, typename... Extra>
1158 class_ &def(detail::initimpl::pickle_factory<Args...> &&pf, const Extra &...extra) {
1159 std::move(pf).execute(*this, extra...);
1163 template <typename Func> class_& def_buffer(Func &&func) {
1164 struct capture { Func func; };
1165 capture *ptr = new capture { std::forward<Func>(func) };
1166 install_buffer_funcs([](PyObject *obj, void *ptr) -> buffer_info* {
1167 detail::make_caster<type> caster;
1168 if (!caster.load(obj, false))
1170 return new buffer_info(((capture *) ptr)->func(caster));
1175 template <typename Return, typename Class, typename... Args>
1176 class_ &def_buffer(Return (Class::*func)(Args...)) {
1177 return def_buffer([func] (type &obj) { return (obj.*func)(); });
1180 template <typename Return, typename Class, typename... Args>
1181 class_ &def_buffer(Return (Class::*func)(Args...) const) {
1182 return def_buffer([func] (const type &obj) { return (obj.*func)(); });
1185 template <typename C, typename D, typename... Extra>
1186 class_ &def_readwrite(const char *name, D C::*pm, const Extra&... extra) {
1187 static_assert(std::is_same<C, type>::value || std::is_base_of<C, type>::value, "def_readwrite() requires a class member (or base class member)");
1188 cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this)),
1189 fset([pm](type &c, const D &value) { c.*pm = value; }, is_method(*this));
1190 def_property(name, fget, fset, return_value_policy::reference_internal, extra...);
1194 template <typename C, typename D, typename... Extra>
1195 class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra) {
1196 static_assert(std::is_same<C, type>::value || std::is_base_of<C, type>::value, "def_readonly() requires a class member (or base class member)");
1197 cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this));
1198 def_property_readonly(name, fget, return_value_policy::reference_internal, extra...);
1202 template <typename D, typename... Extra>
1203 class_ &def_readwrite_static(const char *name, D *pm, const Extra& ...extra) {
1204 cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this)),
1205 fset([pm](object, const D &value) { *pm = value; }, scope(*this));
1206 def_property_static(name, fget, fset, return_value_policy::reference, extra...);
1210 template <typename D, typename... Extra>
1211 class_ &def_readonly_static(const char *name, const D *pm, const Extra& ...extra) {
1212 cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this));
1213 def_property_readonly_static(name, fget, return_value_policy::reference, extra...);
1217 /// Uses return_value_policy::reference_internal by default
1218 template <typename Getter, typename... Extra>
1219 class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra) {
1220 return def_property_readonly(name, cpp_function(method_adaptor<type>(fget)),
1221 return_value_policy::reference_internal, extra...);
1224 /// Uses cpp_function's return_value_policy by default
1225 template <typename... Extra>
1226 class_ &def_property_readonly(const char *name, const cpp_function &fget, const Extra& ...extra) {
1227 return def_property(name, fget, nullptr, extra...);
1230 /// Uses return_value_policy::reference by default
1231 template <typename Getter, typename... Extra>
1232 class_ &def_property_readonly_static(const char *name, const Getter &fget, const Extra& ...extra) {
1233 return def_property_readonly_static(name, cpp_function(fget), return_value_policy::reference, extra...);
1236 /// Uses cpp_function's return_value_policy by default
1237 template <typename... Extra>
1238 class_ &def_property_readonly_static(const char *name, const cpp_function &fget, const Extra& ...extra) {
1239 return def_property_static(name, fget, nullptr, extra...);
1242 /// Uses return_value_policy::reference_internal by default
1243 template <typename Getter, typename Setter, typename... Extra>
1244 class_ &def_property(const char *name, const Getter &fget, const Setter &fset, const Extra& ...extra) {
1245 return def_property(name, fget, cpp_function(method_adaptor<type>(fset)), extra...);
1247 template <typename Getter, typename... Extra>
1248 class_ &def_property(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
1249 return def_property(name, cpp_function(method_adaptor<type>(fget)), fset,
1250 return_value_policy::reference_internal, extra...);
1253 /// Uses cpp_function's return_value_policy by default
1254 template <typename... Extra>
1255 class_ &def_property(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1256 return def_property_static(name, fget, fset, is_method(*this), extra...);
1259 /// Uses return_value_policy::reference by default
1260 template <typename Getter, typename... Extra>
1261 class_ &def_property_static(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) {
1262 return def_property_static(name, cpp_function(fget), fset, return_value_policy::reference, extra...);
1265 /// Uses cpp_function's return_value_policy by default
1266 template <typename... Extra>
1267 class_ &def_property_static(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) {
1268 static_assert( 0 == detail::constexpr_sum(std::is_base_of<arg, Extra>::value...),
1269 "Argument annotations are not allowed for properties");
1270 auto rec_fget = get_function_record(fget), rec_fset = get_function_record(fset);
1271 auto *rec_active = rec_fget;
1273 char *doc_prev = rec_fget->doc; /* 'extra' field may include a property-specific documentation string */
1274 detail::process_attributes<Extra...>::init(extra..., rec_fget);
1275 if (rec_fget->doc && rec_fget->doc != doc_prev) {
1277 rec_fget->doc = strdup(rec_fget->doc);
1281 char *doc_prev = rec_fset->doc;
1282 detail::process_attributes<Extra...>::init(extra..., rec_fset);
1283 if (rec_fset->doc && rec_fset->doc != doc_prev) {
1285 rec_fset->doc = strdup(rec_fset->doc);
1287 if (! rec_active) rec_active = rec_fset;
1289 def_property_static_impl(name, fget, fset, rec_active);
1294 /// Initialize holder object, variant 1: object derives from enable_shared_from_this
1295 template <typename T>
1296 static void init_holder(detail::instance *inst, detail::value_and_holder &v_h,
1297 const holder_type * /* unused */, const std::enable_shared_from_this<T> * /* dummy */) {
1299 auto sh = std::dynamic_pointer_cast<typename holder_type::element_type>(
1300 v_h.value_ptr<type>()->shared_from_this());
1302 new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(sh));
1303 v_h.set_holder_constructed();
1305 } catch (const std::bad_weak_ptr &) {}
1307 if (!v_h.holder_constructed() && inst->owned) {
1308 new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>());
1309 v_h.set_holder_constructed();
1313 static void init_holder_from_existing(const detail::value_and_holder &v_h,
1314 const holder_type *holder_ptr, std::true_type /*is_copy_constructible*/) {
1315 new (std::addressof(v_h.holder<holder_type>())) holder_type(*reinterpret_cast<const holder_type *>(holder_ptr));
1318 static void init_holder_from_existing(const detail::value_and_holder &v_h,
1319 const holder_type *holder_ptr, std::false_type /*is_copy_constructible*/) {
1320 new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(*const_cast<holder_type *>(holder_ptr)));
1323 /// Initialize holder object, variant 2: try to construct from existing holder object, if possible
1324 static void init_holder(detail::instance *inst, detail::value_and_holder &v_h,
1325 const holder_type *holder_ptr, const void * /* dummy -- not enable_shared_from_this<T>) */) {
1327 init_holder_from_existing(v_h, holder_ptr, std::is_copy_constructible<holder_type>());
1328 v_h.set_holder_constructed();
1329 } else if (inst->owned || detail::always_construct_holder<holder_type>::value) {
1330 new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>());
1331 v_h.set_holder_constructed();
1335 /// Performs instance initialization including constructing a holder and registering the known
1336 /// instance. Should be called as soon as the `type` value_ptr is set for an instance. Takes an
1337 /// optional pointer to an existing holder to use; if not specified and the instance is
1338 /// `.owned`, a new holder will be constructed to manage the value pointer.
1339 static void init_instance(detail::instance *inst, const void *holder_ptr) {
1340 auto v_h = inst->get_value_and_holder(detail::get_type_info(typeid(type)));
1341 if (!v_h.instance_registered()) {
1342 register_instance(inst, v_h.value_ptr(), v_h.type);
1343 v_h.set_instance_registered();
1345 init_holder(inst, v_h, (const holder_type *) holder_ptr, v_h.value_ptr<type>());
1348 /// Deallocates an instance; via holder, if constructed; otherwise via operator delete.
1349 static void dealloc(detail::value_and_holder &v_h) {
1350 if (v_h.holder_constructed()) {
1351 v_h.holder<holder_type>().~holder_type();
1352 v_h.set_holder_constructed(false);
1355 detail::call_operator_delete(v_h.value_ptr<type>(),
1356 v_h.type->type_size,
1357 v_h.type->type_align
1360 v_h.value_ptr() = nullptr;
1363 static detail::function_record *get_function_record(handle h) {
1364 h = detail::get_function(h);
1365 return h ? (detail::function_record *) reinterpret_borrow<capsule>(PyCFunction_GET_SELF(h.ptr()))
1370 /// Binds an existing constructor taking arguments Args...
1371 template <typename... Args> detail::initimpl::constructor<Args...> init() { return {}; }
1372 /// Like `init<Args...>()`, but the instance is always constructed through the alias class (even
1373 /// when not inheriting on the Python side).
1374 template <typename... Args> detail::initimpl::alias_constructor<Args...> init_alias() { return {}; }
1376 /// Binds a factory function as a constructor
1377 template <typename Func, typename Ret = detail::initimpl::factory<Func>>
1378 Ret init(Func &&f) { return {std::forward<Func>(f)}; }
1380 /// Dual-argument factory function: the first function is called when no alias is needed, the second
1381 /// when an alias is needed (i.e. due to python-side inheritance). Arguments must be identical.
1382 template <typename CFunc, typename AFunc, typename Ret = detail::initimpl::factory<CFunc, AFunc>>
1383 Ret init(CFunc &&c, AFunc &&a) {
1384 return {std::forward<CFunc>(c), std::forward<AFunc>(a)};
1387 /// Binds pickling functions `__getstate__` and `__setstate__` and ensures that the type
1388 /// returned by `__getstate__` is the same as the argument accepted by `__setstate__`.
1389 template <typename GetState, typename SetState>
1390 detail::initimpl::pickle_factory<GetState, SetState> pickle(GetState &&g, SetState &&s) {
1391 return {std::forward<GetState>(g), std::forward<SetState>(s)};
1394 NAMESPACE_BEGIN(detail)
1396 enum_base(handle base, handle parent) : m_base(base), m_parent(parent) { }
1398 PYBIND11_NOINLINE void init(bool is_arithmetic, bool is_convertible) {
1399 m_base.attr("__entries") = dict();
1400 auto property = handle((PyObject *) &PyProperty_Type);
1401 auto static_property = handle((PyObject *) get_internals().static_property_type);
1403 m_base.attr("__repr__") = cpp_function(
1404 [](handle arg) -> str {
1405 handle type = arg.get_type();
1406 object type_name = type.attr("__name__");
1407 dict entries = type.attr("__entries");
1408 for (const auto &kv : entries) {
1409 object other = kv.second[int_(0)];
1410 if (other.equal(arg))
1411 return pybind11::str("{}.{}").format(type_name, kv.first);
1413 return pybind11::str("{}.???").format(type_name);
1414 }, is_method(m_base)
1417 m_base.attr("name") = property(cpp_function(
1418 [](handle arg) -> str {
1419 dict entries = arg.get_type().attr("__entries");
1420 for (const auto &kv : entries) {
1421 if (handle(kv.second[int_(0)]).equal(arg))
1422 return pybind11::str(kv.first);
1425 }, is_method(m_base)
1428 m_base.attr("__doc__") = static_property(cpp_function(
1429 [](handle arg) -> std::string {
1430 std::string docstring;
1431 dict entries = arg.attr("__entries");
1432 if (((PyTypeObject *) arg.ptr())->tp_doc)
1433 docstring += std::string(((PyTypeObject *) arg.ptr())->tp_doc) + "\n\n";
1434 docstring += "Members:";
1435 for (const auto &kv : entries) {
1436 auto key = std::string(pybind11::str(kv.first));
1437 auto comment = kv.second[int_(1)];
1438 docstring += "\n\n " + key;
1439 if (!comment.is_none())
1440 docstring += " : " + (std::string) pybind11::str(comment);
1444 ), none(), none(), "");
1446 m_base.attr("__members__") = static_property(cpp_function(
1447 [](handle arg) -> dict {
1448 dict entries = arg.attr("__entries"), m;
1449 for (const auto &kv : entries)
1450 m[kv.first] = kv.second[int_(0)];
1452 }), none(), none(), ""
1455 #define PYBIND11_ENUM_OP_STRICT(op, expr, strict_behavior) \
1456 m_base.attr(op) = cpp_function( \
1457 [](object a, object b) { \
1458 if (!a.get_type().is(b.get_type())) \
1464 #define PYBIND11_ENUM_OP_CONV(op, expr) \
1465 m_base.attr(op) = cpp_function( \
1466 [](object a_, object b_) { \
1467 int_ a(a_), b(b_); \
1472 #define PYBIND11_ENUM_OP_CONV_LHS(op, expr) \
1473 m_base.attr(op) = cpp_function( \
1474 [](object a_, object b) { \
1480 if (is_convertible) {
1481 PYBIND11_ENUM_OP_CONV_LHS("__eq__", !b.is_none() && a.equal(b));
1482 PYBIND11_ENUM_OP_CONV_LHS("__ne__", b.is_none() || !a.equal(b));
1484 if (is_arithmetic) {
1485 PYBIND11_ENUM_OP_CONV("__lt__", a < b);
1486 PYBIND11_ENUM_OP_CONV("__gt__", a > b);
1487 PYBIND11_ENUM_OP_CONV("__le__", a <= b);
1488 PYBIND11_ENUM_OP_CONV("__ge__", a >= b);
1489 PYBIND11_ENUM_OP_CONV("__and__", a & b);
1490 PYBIND11_ENUM_OP_CONV("__rand__", a & b);
1491 PYBIND11_ENUM_OP_CONV("__or__", a | b);
1492 PYBIND11_ENUM_OP_CONV("__ror__", a | b);
1493 PYBIND11_ENUM_OP_CONV("__xor__", a ^ b);
1494 PYBIND11_ENUM_OP_CONV("__rxor__", a ^ b);
1495 m_base.attr("__invert__") = cpp_function(
1496 [](object arg) { return ~(int_(arg)); }, is_method(m_base));
1499 PYBIND11_ENUM_OP_STRICT("__eq__", int_(a).equal(int_(b)), return false);
1500 PYBIND11_ENUM_OP_STRICT("__ne__", !int_(a).equal(int_(b)), return true);
1502 if (is_arithmetic) {
1503 #define PYBIND11_THROW throw type_error("Expected an enumeration of matching type!");
1504 PYBIND11_ENUM_OP_STRICT("__lt__", int_(a) < int_(b), PYBIND11_THROW);
1505 PYBIND11_ENUM_OP_STRICT("__gt__", int_(a) > int_(b), PYBIND11_THROW);
1506 PYBIND11_ENUM_OP_STRICT("__le__", int_(a) <= int_(b), PYBIND11_THROW);
1507 PYBIND11_ENUM_OP_STRICT("__ge__", int_(a) >= int_(b), PYBIND11_THROW);
1508 #undef PYBIND11_THROW
1512 #undef PYBIND11_ENUM_OP_CONV_LHS
1513 #undef PYBIND11_ENUM_OP_CONV
1514 #undef PYBIND11_ENUM_OP_STRICT
1516 object getstate = cpp_function(
1517 [](object arg) { return int_(arg); }, is_method(m_base));
1519 m_base.attr("__getstate__") = getstate;
1520 m_base.attr("__hash__") = getstate;
1523 PYBIND11_NOINLINE void value(char const* name_, object value, const char *doc = nullptr) {
1524 dict entries = m_base.attr("__entries");
1526 if (entries.contains(name)) {
1527 std::string type_name = (std::string) str(m_base.attr("__name__"));
1528 throw value_error(type_name + ": element \"" + std::string(name_) + "\" already exists!");
1531 entries[name] = std::make_pair(value, doc);
1532 m_base.attr(name) = value;
1535 PYBIND11_NOINLINE void export_values() {
1536 dict entries = m_base.attr("__entries");
1537 for (const auto &kv : entries)
1538 m_parent.attr(kv.first) = kv.second[int_(0)];
1545 NAMESPACE_END(detail)
1547 /// Binds C++ enumerations and enumeration classes to Python
1548 template <typename Type> class enum_ : public class_<Type> {
1550 using Base = class_<Type>;
1553 using Base::def_property_readonly;
1554 using Base::def_property_readonly_static;
1555 using Scalar = typename std::underlying_type<Type>::type;
1557 template <typename... Extra>
1558 enum_(const handle &scope, const char *name, const Extra&... extra)
1559 : class_<Type>(scope, name, extra...), m_base(*this, scope) {
1560 constexpr bool is_arithmetic = detail::any_of<std::is_same<arithmetic, Extra>...>::value;
1561 constexpr bool is_convertible = std::is_convertible<Type, Scalar>::value;
1562 m_base.init(is_arithmetic, is_convertible);
1564 def(init([](Scalar i) { return static_cast<Type>(i); }));
1565 def("__int__", [](Type value) { return (Scalar) value; });
1566 #if PY_MAJOR_VERSION < 3
1567 def("__long__", [](Type value) { return (Scalar) value; });
1569 #if PY_MAJOR_VERSION > 3 || (PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION >= 8)
1570 def("__index__", [](Type value) { return (Scalar) value; });
1573 cpp_function setstate(
1574 [](Type &value, Scalar arg) { value = static_cast<Type>(arg); },
1576 attr("__setstate__") = setstate;
1579 /// Export enumeration entries into the parent scope
1580 enum_& export_values() {
1581 m_base.export_values();
1585 /// Add an enumeration entry
1586 enum_& value(char const* name, Type value, const char *doc = nullptr) {
1587 m_base.value(name, pybind11::cast(value, return_value_policy::copy), doc);
1592 detail::enum_base m_base;
1595 NAMESPACE_BEGIN(detail)
1598 inline void keep_alive_impl(handle nurse, handle patient) {
1599 if (!nurse || !patient)
1600 pybind11_fail("Could not activate keep_alive!");
1602 if (patient.is_none() || nurse.is_none())
1603 return; /* Nothing to keep alive or nothing to be kept alive by */
1605 auto tinfo = all_type_info(Py_TYPE(nurse.ptr()));
1606 if (!tinfo.empty()) {
1607 /* It's a pybind-registered type, so we can store the patient in the
1609 add_patient(nurse.ptr(), patient.ptr());
1612 /* Fall back to clever approach based on weak references taken from
1613 * Boost.Python. This is not used for pybind-registered types because
1614 * the objects can be destroyed out-of-order in a GC pass. */
1615 cpp_function disable_lifesupport(
1616 [patient](handle weakref) { patient.dec_ref(); weakref.dec_ref(); });
1618 weakref wr(nurse, disable_lifesupport);
1620 patient.inc_ref(); /* reference patient and leak the weak reference */
1621 (void) wr.release();
1625 PYBIND11_NOINLINE inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret) {
1626 auto get_arg = [&](size_t n) {
1629 else if (n == 1 && call.init_self)
1630 return call.init_self;
1631 else if (n <= call.args.size())
1632 return call.args[n - 1];
1636 keep_alive_impl(get_arg(Nurse), get_arg(Patient));
1639 inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type) {
1640 auto res = get_internals().registered_types_py
1641 #ifdef __cpp_lib_unordered_map_try_emplace
1644 .emplace(type, std::vector<detail::type_info *>());
1647 // New cache entry created; set up a weak reference to automatically remove it if the type
1649 weakref((PyObject *) type, cpp_function([type](handle wr) {
1650 get_internals().registered_types_py.erase(type);
1658 template <typename Iterator, typename Sentinel, bool KeyIterator, return_value_policy Policy>
1659 struct iterator_state {
1665 NAMESPACE_END(detail)
1667 /// Makes a python iterator from a first and past-the-end C++ InputIterator.
1668 template <return_value_policy Policy = return_value_policy::reference_internal,
1671 typename ValueType = decltype(*std::declval<Iterator>()),
1673 iterator make_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1674 typedef detail::iterator_state<Iterator, Sentinel, false, Policy> state;
1676 if (!detail::get_type_info(typeid(state), false)) {
1677 class_<state>(handle(), "iterator", pybind11::module_local())
1678 .def("__iter__", [](state &s) -> state& { return s; })
1679 .def("__next__", [](state &s) -> ValueType {
1680 if (!s.first_or_done)
1683 s.first_or_done = false;
1684 if (s.it == s.end) {
1685 s.first_or_done = true;
1686 throw stop_iteration();
1689 }, std::forward<Extra>(extra)..., Policy);
1692 return cast(state{first, last, true});
1695 /// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a
1696 /// first and past-the-end InputIterator.
1697 template <return_value_policy Policy = return_value_policy::reference_internal,
1700 typename KeyType = decltype((*std::declval<Iterator>()).first),
1702 iterator make_key_iterator(Iterator first, Sentinel last, Extra &&... extra) {
1703 typedef detail::iterator_state<Iterator, Sentinel, true, Policy> state;
1705 if (!detail::get_type_info(typeid(state), false)) {
1706 class_<state>(handle(), "iterator", pybind11::module_local())
1707 .def("__iter__", [](state &s) -> state& { return s; })
1708 .def("__next__", [](state &s) -> KeyType {
1709 if (!s.first_or_done)
1712 s.first_or_done = false;
1713 if (s.it == s.end) {
1714 s.first_or_done = true;
1715 throw stop_iteration();
1717 return (*s.it).first;
1718 }, std::forward<Extra>(extra)..., Policy);
1721 return cast(state{first, last, true});
1724 /// Makes an iterator over values of an stl container or other container supporting
1725 /// `std::begin()`/`std::end()`
1726 template <return_value_policy Policy = return_value_policy::reference_internal,
1727 typename Type, typename... Extra> iterator make_iterator(Type &value, Extra&&... extra) {
1728 return make_iterator<Policy>(std::begin(value), std::end(value), extra...);
1731 /// Makes an iterator over the keys (`.first`) of a stl map-like container supporting
1732 /// `std::begin()`/`std::end()`
1733 template <return_value_policy Policy = return_value_policy::reference_internal,
1734 typename Type, typename... Extra> iterator make_key_iterator(Type &value, Extra&&... extra) {
1735 return make_key_iterator<Policy>(std::begin(value), std::end(value), extra...);
1738 template <typename InputType, typename OutputType> void implicitly_convertible() {
1741 set_flag(bool &flag) : flag(flag) { flag = true; }
1742 ~set_flag() { flag = false; }
1744 auto implicit_caster = [](PyObject *obj, PyTypeObject *type) -> PyObject * {
1745 static bool currently_used = false;
1746 if (currently_used) // implicit conversions are non-reentrant
1748 set_flag flag_helper(currently_used);
1749 if (!detail::make_caster<InputType>().load(obj, false))
1753 PyObject *result = PyObject_Call((PyObject *) type, args.ptr(), nullptr);
1754 if (result == nullptr)
1759 if (auto tinfo = detail::get_type_info(typeid(OutputType)))
1760 tinfo->implicit_conversions.push_back(implicit_caster);
1762 pybind11_fail("implicitly_convertible: Unable to find type " + type_id<OutputType>());
1765 template <typename ExceptionTranslator>
1766 void register_exception_translator(ExceptionTranslator&& translator) {
1767 detail::get_internals().registered_exception_translators.push_front(
1768 std::forward<ExceptionTranslator>(translator));
1772 * Wrapper to generate a new Python exception type.
1774 * This should only be used with PyErr_SetString for now.
1775 * It is not (yet) possible to use as a py::base.
1776 * Template type argument is reserved for future use.
1778 template <typename type>
1779 class exception : public object {
1781 exception() = default;
1782 exception(handle scope, const char *name, PyObject *base = PyExc_Exception) {
1783 std::string full_name = scope.attr("__name__").cast<std::string>() +
1784 std::string(".") + name;
1785 m_ptr = PyErr_NewException(const_cast<char *>(full_name.c_str()), base, NULL);
1786 if (hasattr(scope, name))
1787 pybind11_fail("Error during initialization: multiple incompatible "
1788 "definitions with name \"" + std::string(name) + "\"");
1789 scope.attr(name) = *this;
1792 // Sets the current python exception to this exception object with the given message
1793 void operator()(const char *message) {
1794 PyErr_SetString(m_ptr, message);
1798 NAMESPACE_BEGIN(detail)
1799 // Returns a reference to a function-local static exception object used in the simple
1800 // register_exception approach below. (It would be simpler to have the static local variable
1801 // directly in register_exception, but that makes clang <3.5 segfault - issue #1349).
1802 template <typename CppException>
1803 exception<CppException> &get_exception_object() { static exception<CppException> ex; return ex; }
1804 NAMESPACE_END(detail)
1807 * Registers a Python exception in `m` of the given `name` and installs an exception translator to
1808 * translate the C++ exception to the created Python exception using the exceptions what() method.
1809 * This is intended for simple exception translations; for more complex translation, register the
1810 * exception object and translator directly.
1812 template <typename CppException>
1813 exception<CppException> ®ister_exception(handle scope,
1815 PyObject *base = PyExc_Exception) {
1816 auto &ex = detail::get_exception_object<CppException>();
1817 if (!ex) ex = exception<CppException>(scope, name, base);
1819 register_exception_translator([](std::exception_ptr p) {
1822 std::rethrow_exception(p);
1823 } catch (const CppException &e) {
1824 detail::get_exception_object<CppException>()(e.what());
1830 NAMESPACE_BEGIN(detail)
1831 PYBIND11_NOINLINE inline void print(tuple args, dict kwargs) {
1832 auto strings = tuple(args.size());
1833 for (size_t i = 0; i < args.size(); ++i) {
1834 strings[i] = str(args[i]);
1836 auto sep = kwargs.contains("sep") ? kwargs["sep"] : cast(" ");
1837 auto line = sep.attr("join")(strings);
1840 if (kwargs.contains("file")) {
1841 file = kwargs["file"].cast<object>();
1844 file = module::import("sys").attr("stdout");
1845 } catch (const error_already_set &) {
1846 /* If print() is called from code that is executed as
1847 part of garbage collection during interpreter shutdown,
1848 importing 'sys' can fail. Give up rather than crashing the
1849 interpreter in this case. */
1854 auto write = file.attr("write");
1856 write(kwargs.contains("end") ? kwargs["end"] : cast("\n"));
1858 if (kwargs.contains("flush") && kwargs["flush"].cast<bool>())
1859 file.attr("flush")();
1861 NAMESPACE_END(detail)
1863 template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
1864 void print(Args &&...args) {
1865 auto c = detail::collect_arguments<policy>(std::forward<Args>(args)...);
1866 detail::print(c.args(), c.kwargs());
1869 #if defined(WITH_THREAD) && !defined(PYPY_VERSION)
1871 /* The functions below essentially reproduce the PyGILState_* API using a RAII
1872 * pattern, but there are a few important differences:
1874 * 1. When acquiring the GIL from an non-main thread during the finalization
1875 * phase, the GILState API blindly terminates the calling thread, which
1876 * is often not what is wanted. This API does not do this.
1878 * 2. The gil_scoped_release function can optionally cut the relationship
1879 * of a PyThreadState and its associated thread, which allows moving it to
1880 * another thread (this is a fairly rare/advanced use case).
1882 * 3. The reference count of an acquired thread state can be controlled. This
1883 * can be handy to prevent cases where callbacks issued from an external
1884 * thread would otherwise constantly construct and destroy thread state data
1887 * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an
1888 * example which uses features 2 and 3 to migrate the Python thread of
1889 * execution to another thread (to run the event loop on the original thread,
1893 class gil_scoped_acquire {
1895 PYBIND11_NOINLINE gil_scoped_acquire() {
1896 auto const &internals = detail::get_internals();
1897 tstate = (PyThreadState *) PYBIND11_TLS_GET_VALUE(internals.tstate);
1900 /* Check if the GIL was acquired using the PyGILState_* API instead (e.g. if
1901 calling from a Python thread). Since we use a different key, this ensures
1902 we don't create a new thread state and deadlock in PyEval_AcquireThread
1903 below. Note we don't save this state with internals.tstate, since we don't
1904 create it we would fail to clear it (its reference count should be > 0). */
1905 tstate = PyGILState_GetThisThreadState();
1909 tstate = PyThreadState_New(internals.istate);
1910 #if !defined(NDEBUG)
1912 pybind11_fail("scoped_acquire: could not create thread state!");
1914 tstate->gilstate_counter = 0;
1915 PYBIND11_TLS_REPLACE_VALUE(internals.tstate, tstate);
1917 release = detail::get_thread_state_unchecked() != tstate;
1921 /* Work around an annoying assertion in PyThreadState_Swap */
1922 #if defined(Py_DEBUG)
1923 PyInterpreterState *interp = tstate->interp;
1924 tstate->interp = nullptr;
1926 PyEval_AcquireThread(tstate);
1927 #if defined(Py_DEBUG)
1928 tstate->interp = interp;
1936 ++tstate->gilstate_counter;
1939 PYBIND11_NOINLINE void dec_ref() {
1940 --tstate->gilstate_counter;
1941 #if !defined(NDEBUG)
1942 if (detail::get_thread_state_unchecked() != tstate)
1943 pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!");
1944 if (tstate->gilstate_counter < 0)
1945 pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!");
1947 if (tstate->gilstate_counter == 0) {
1948 #if !defined(NDEBUG)
1950 pybind11_fail("scoped_acquire::dec_ref(): internal error!");
1952 PyThreadState_Clear(tstate);
1953 PyThreadState_DeleteCurrent();
1954 PYBIND11_TLS_DELETE_VALUE(detail::get_internals().tstate);
1959 PYBIND11_NOINLINE ~gil_scoped_acquire() {
1962 PyEval_SaveThread();
1965 PyThreadState *tstate = nullptr;
1966 bool release = true;
1969 class gil_scoped_release {
1971 explicit gil_scoped_release(bool disassoc = false) : disassoc(disassoc) {
1972 // `get_internals()` must be called here unconditionally in order to initialize
1973 // `internals.tstate` for subsequent `gil_scoped_acquire` calls. Otherwise, an
1974 // initialization race could occur as multiple threads try `gil_scoped_acquire`.
1975 const auto &internals = detail::get_internals();
1976 tstate = PyEval_SaveThread();
1978 auto key = internals.tstate;
1979 PYBIND11_TLS_DELETE_VALUE(key);
1982 ~gil_scoped_release() {
1985 PyEval_RestoreThread(tstate);
1987 auto key = detail::get_internals().tstate;
1988 PYBIND11_TLS_REPLACE_VALUE(key, tstate);
1992 PyThreadState *tstate;
1995 #elif defined(PYPY_VERSION)
1996 class gil_scoped_acquire {
1997 PyGILState_STATE state;
1999 gil_scoped_acquire() { state = PyGILState_Ensure(); }
2000 ~gil_scoped_acquire() { PyGILState_Release(state); }
2003 class gil_scoped_release {
2004 PyThreadState *state;
2006 gil_scoped_release() { state = PyEval_SaveThread(); }
2007 ~gil_scoped_release() { PyEval_RestoreThread(state); }
2010 class gil_scoped_acquire { };
2011 class gil_scoped_release { };
2014 error_already_set::~error_already_set() {
2016 gil_scoped_acquire gil;
2018 m_type.release().dec_ref();
2019 m_value.release().dec_ref();
2020 m_trace.release().dec_ref();
2024 inline function get_type_overload(const void *this_ptr, const detail::type_info *this_type, const char *name) {
2025 handle self = detail::get_object_handle(this_ptr, this_type);
2028 handle type = self.get_type();
2029 auto key = std::make_pair(type.ptr(), name);
2031 /* Cache functions that aren't overloaded in Python to avoid
2032 many costly Python dictionary lookups below */
2033 auto &cache = detail::get_internals().inactive_overload_cache;
2034 if (cache.find(key) != cache.end())
2037 function overload = getattr(self, name, function());
2038 if (overload.is_cpp_function()) {
2043 /* Don't call dispatch code if invoked from overridden function.
2044 Unfortunately this doesn't work on PyPy. */
2045 #if !defined(PYPY_VERSION)
2046 PyFrameObject *frame = PyThreadState_Get()->frame;
2047 if (frame && (std::string) str(frame->f_code->co_name) == name &&
2048 frame->f_code->co_argcount > 0) {
2049 PyFrame_FastToLocals(frame);
2050 PyObject *self_caller = PyDict_GetItem(
2051 frame->f_locals, PyTuple_GET_ITEM(frame->f_code->co_varnames, 0));
2052 if (self_caller == self.ptr())
2056 /* PyPy currently doesn't provide a detailed cpyext emulation of
2057 frame objects, so we have to emulate this using Python. This
2058 is going to be slow..*/
2059 dict d; d["self"] = self; d["name"] = pybind11::str(name);
2060 PyObject *result = PyRun_String(
2062 "frame = inspect.currentframe()\n"
2063 "if frame is not None:\n"
2064 " frame = frame.f_back\n"
2065 " if frame is not None and str(frame.f_code.co_name) == name and "
2066 "frame.f_code.co_argcount > 0:\n"
2067 " self_caller = frame.f_locals[frame.f_code.co_varnames[0]]\n"
2068 " if self_caller == self:\n"
2070 Py_file_input, d.ptr(), d.ptr());
2071 if (result == nullptr)
2072 throw error_already_set();
2073 if (d["self"].is_none())
2082 Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
2084 :this_ptr: The pointer to the object the overload should be retrieved for. This should be the first
2085 non-trampoline class encountered in the inheritance chain.
2086 :name: The name of the overloaded Python method to retrieve.
2087 :return: The Python method by this name from the object or an empty function wrapper.
2089 template <class T> function get_overload(const T *this_ptr, const char *name) {
2090 auto tinfo = detail::get_type_info(typeid(T));
2091 return tinfo ? get_type_overload(this_ptr, tinfo, name) : function();
2094 #define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) { \
2095 pybind11::gil_scoped_acquire gil; \
2096 pybind11::function overload = pybind11::get_overload(static_cast<const cname *>(this), name); \
2098 auto o = overload(__VA_ARGS__); \
2099 if (pybind11::detail::cast_is_temporary_value_reference<ret_type>::value) { \
2100 static pybind11::detail::overload_caster_t<ret_type> caster; \
2101 return pybind11::detail::cast_ref<ret_type>(std::move(o), caster); \
2103 else return pybind11::detail::cast_safe<ret_type>(std::move(o)); \
2108 Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named 'fn'
2109 from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2110 the appropriate type. See :ref:`overriding_virtuals` for more information. This macro should be used when the method
2111 name in C is not the same as the method name in Python. For example with `__str__`.
2115 std::string toString() override {
2116 PYBIND11_OVERLOAD_NAME(
2117 std::string, // Return type (ret_type)
2118 Animal, // Parent class (cname)
2119 toString, // Name of function in C++ (name)
2120 "__str__", // Name of method in Python (fn)
2124 #define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \
2125 PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2126 return cname::fn(__VA_ARGS__)
2129 Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD_NAME`, except that it
2130 throws if no overload can be found.
2132 #define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \
2133 PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2134 pybind11::pybind11_fail("Tried to call pure virtual function \"" PYBIND11_STRINGIFY(cname) "::" name "\"");
2137 Macro to populate the virtual method in the trampoline class. This macro tries to look up the method
2138 from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2139 the appropriate type. This macro should be used if the method name in C and in Python are identical.
2140 See :ref:`overriding_virtuals` for more information.
2144 class PyAnimal : public Animal {
2146 // Inherit the constructors
2147 using Animal::Animal;
2149 // Trampoline (need one for each virtual function)
2150 std::string go(int n_times) override {
2151 PYBIND11_OVERLOAD_PURE(
2152 std::string, // Return type (ret_type)
2153 Animal, // Parent class (cname)
2154 go, // Name of function in C++ (must match Python name) (fn)
2155 n_times // Argument(s) (...)
2160 #define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \
2161 PYBIND11_OVERLOAD_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2164 Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD`, except that it throws
2165 if no overload can be found.
2167 #define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \
2168 PYBIND11_OVERLOAD_PURE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2170 NAMESPACE_END(PYBIND11_NAMESPACE)
2172 #if defined(_MSC_VER) && !defined(__INTEL_COMPILER)
2173 # pragma warning(pop)
2174 #elif defined(__GNUG__) && !defined(__clang__)
2175 # pragma GCC diagnostic pop