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