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