2 pybind11/pybind11.h: Main header file of the C++11 python
3 binding generator library
5 Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
7 All rights reserved. Use of this source code is governed by a
8 BSD-style license that can be found in the LICENSE file.
13 #pragma clang diagnostic push
14 #pragma clang diagnostic ignored "-Wunused-value"
17 #if defined(__INTEL_COMPILER)
19 # pragma warning disable 68 // integer conversion resulted in a change of sign
20 # pragma warning disable 186 // pointless comparison of unsigned integer with zero
21 # pragma warning disable 878 // incompatible exception specifications
22 # pragma warning disable 1334 // the "template" keyword used for syntactic disambiguation may only be used within a template
23 # pragma warning disable 1682 // implicit conversion of a 64-bit integral type to a smaller integral type (potential portability problem)
24 # pragma warning disable 1786 // function "strdup" was declared deprecated
25 # pragma warning disable 1875 // offsetof applied to non-POD (Plain Old Data) types is nonstandard
26 # pragma warning disable 2196 // warning #2196: routine is both "inline" and "noinline"
27 #elif defined(_MSC_VER)
28 # pragma warning(push)
29 # pragma warning(disable: 4100) // warning C4100: Unreferenced formal parameter
30 # pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
31 # pragma warning(disable: 4512) // warning C4512: Assignment operator was implicitly defined as deleted
32 # pragma warning(disable: 4800) // warning C4800: 'int': forcing value to bool 'true' or 'false' (performance warning)
33 # pragma warning(disable: 4996) // warning C4996: The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name
34 # pragma warning(disable: 4702) // warning C4702: unreachable code
35 # pragma warning(disable: 4522) // warning C4522: multiple assignment operators specified
36 #elif defined(__GNUG__) && !defined(__clang__)
37 # pragma GCC diagnostic push
38 # pragma GCC diagnostic ignored "-Wunused-but-set-parameter"
39 # pragma GCC diagnostic ignored "-Wunused-but-set-variable"
40 # pragma GCC diagnostic ignored "-Wmissing-field-initializers"
41 # pragma GCC diagnostic ignored "-Wstrict-aliasing"
42 # pragma GCC diagnostic ignored "-Wattributes"
44 # pragma GCC diagnostic ignored "-Wnoexcept-type"
50 #include "detail/class.h"
51 #include "detail/init.h"
53 #if defined(__GNUG__) && !defined(__clang__)
57 NAMESPACE_BEGIN(PYBIND11_NAMESPACE
)
59 /// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object
60 class cpp_function
: public function
{
63 cpp_function(std::nullptr_t
) { }
65 /// Construct a cpp_function from a vanilla function pointer
66 template <typename Return
, typename
... Args
, typename
... Extra
>
67 cpp_function(Return (*f
)(Args
...), const Extra
&... extra
) {
68 initialize(f
, f
, extra
...);
71 /// Construct a cpp_function from a lambda function (possibly with internal state)
72 template <typename Func
, typename
... Extra
,
73 typename
= detail::enable_if_t
<detail::is_lambda
<Func
>::value
>>
74 cpp_function(Func
&&f
, const Extra
&... extra
) {
75 initialize(std::forward
<Func
>(f
),
76 (detail::function_signature_t
<Func
> *) nullptr, extra
...);
79 /// Construct a cpp_function from a class method (non-const)
80 template <typename Return
, typename Class
, typename
... Arg
, typename
... Extra
>
81 cpp_function(Return (Class::*f
)(Arg
...), const Extra
&... extra
) {
82 initialize([f
](Class
*c
, Arg
... args
) -> Return
{ return (c
->*f
)(args
...); },
83 (Return (*) (Class
*, Arg
...)) nullptr, extra
...);
86 /// Construct a cpp_function from a class method (const)
87 template <typename Return
, typename Class
, typename
... Arg
, typename
... Extra
>
88 cpp_function(Return (Class::*f
)(Arg
...) const, const Extra
&... extra
) {
89 initialize([f
](const Class
*c
, Arg
... args
) -> Return
{ return (c
->*f
)(args
...); },
90 (Return (*)(const Class
*, Arg
...)) nullptr, extra
...);
93 /// Return the function name
94 object
name() const { return attr("__name__"); }
97 /// Space optimization: don't inline this frequently instantiated fragment
98 PYBIND11_NOINLINE
detail::function_record
*make_function_record() {
99 return new detail::function_record();
102 /// Special internal constructor for functors, lambda functions, etc.
103 template <typename Func
, typename Return
, typename
... Args
, typename
... Extra
>
104 void initialize(Func
&&f
, Return (*)(Args
...), const Extra
&... extra
) {
105 using namespace detail
;
106 struct capture
{ remove_reference_t
<Func
> f
; };
108 /* Store the function including any extra state it might have (e.g. a lambda capture object) */
109 auto rec
= make_function_record();
111 /* Store the capture object directly in the function record if there is enough space */
112 if (sizeof(capture
) <= sizeof(rec
->data
)) {
113 /* Without these pragmas, GCC warns that there might not be
114 enough space to use the placement new operator. However, the
115 'if' statement above ensures that this is the case. */
116 #if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
117 # pragma GCC diagnostic push
118 # pragma GCC diagnostic ignored "-Wplacement-new"
120 new ((capture
*) &rec
->data
) capture
{ std::forward
<Func
>(f
) };
121 #if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6
122 # pragma GCC diagnostic pop
124 if (!std::is_trivially_destructible
<Func
>::value
)
125 rec
->free_data
= [](function_record
*r
) { ((capture
*) &r
->data
)->~capture(); };
127 rec
->data
[0] = new capture
{ std::forward
<Func
>(f
) };
128 rec
->free_data
= [](function_record
*r
) { delete ((capture
*) r
->data
[0]); };
131 /* Type casters for the function arguments and return value */
132 using cast_in
= argument_loader
<Args
...>;
133 using cast_out
= make_caster
<
134 conditional_t
<std::is_void
<Return
>::value
, void_type
, Return
>
137 static_assert(expected_num_args
<Extra
...>(sizeof...(Args
), cast_in::has_args
, cast_in::has_kwargs
),
138 "The number of argument annotations does not match the number of function arguments");
140 /* Dispatch code which converts function arguments and performs the actual function call */
141 rec
->impl
= [](function_call
&call
) -> handle
{
142 cast_in args_converter
;
144 /* Try to cast the function arguments into the C++ domain */
145 if (!args_converter
.load_args(call
))
146 return PYBIND11_TRY_NEXT_OVERLOAD
;
148 /* Invoke call policy pre-call hook */
149 process_attributes
<Extra
...>::precall(call
);
151 /* Get a pointer to the capture object */
152 auto data
= (sizeof(capture
) <= sizeof(call
.func
.data
)
153 ? &call
.func
.data
: call
.func
.data
[0]);
154 capture
*cap
= const_cast<capture
*>(reinterpret_cast<const capture
*>(data
));
156 /* Override policy for rvalues -- usually to enforce rvp::move on an rvalue */
157 return_value_policy policy
= return_value_policy_override
<Return
>::policy(call
.func
.policy
);
159 /* Function scope guard -- defaults to the compile-to-nothing `void_type` */
160 using Guard
= extract_guard_t
<Extra
...>;
162 /* Perform the function call */
163 handle result
= cast_out::cast(
164 std::move(args_converter
).template call
<Return
, Guard
>(cap
->f
), policy
, call
.parent
);
166 /* Invoke call policy post-call hook */
167 process_attributes
<Extra
...>::postcall(call
, result
);
172 /* Process any user-provided function attributes */
173 process_attributes
<Extra
...>::init(extra
..., rec
);
175 /* Generate a readable signature describing the function's arguments and return value types */
176 static constexpr auto signature
= _("(") + cast_in::arg_names
+ _(") -> ") + cast_out::name
;
177 PYBIND11_DESCR_CONSTEXPR
auto types
= decltype(signature
)::types();
179 /* Register the function with Python from generic (non-templated) code */
180 initialize_generic(rec
, signature
.text
, types
.data(), sizeof...(Args
));
182 if (cast_in::has_args
) rec
->has_args
= true;
183 if (cast_in::has_kwargs
) rec
->has_kwargs
= true;
185 /* Stash some additional information used by an important optimization in 'functional.h' */
186 using FunctionType
= Return (*)(Args
...);
187 constexpr bool is_function_ptr
=
188 std::is_convertible
<Func
, FunctionType
>::value
&&
189 sizeof(capture
) == sizeof(void *);
190 if (is_function_ptr
) {
191 rec
->is_stateless
= true;
192 rec
->data
[1] = const_cast<void *>(reinterpret_cast<const void *>(&typeid(FunctionType
)));
196 /// Register a function call with Python (generic non-templated code goes here)
197 void initialize_generic(detail::function_record
*rec
, const char *text
,
198 const std::type_info
*const *types
, size_t args
) {
200 /* Create copies of all referenced C-style strings */
201 rec
->name
= strdup(rec
->name
? rec
->name
: "");
202 if (rec
->doc
) rec
->doc
= strdup(rec
->doc
);
203 for (auto &a
: rec
->args
) {
205 a
.name
= strdup(a
.name
);
207 a
.descr
= strdup(a
.descr
);
209 a
.descr
= strdup(a
.value
.attr("__repr__")().cast
<std::string
>().c_str());
212 rec
->is_constructor
= !strcmp(rec
->name
, "__init__") || !strcmp(rec
->name
, "__setstate__");
214 #if !defined(NDEBUG) && !defined(PYBIND11_DISABLE_NEW_STYLE_INIT_WARNING)
215 if (rec
->is_constructor
&& !rec
->is_new_style_constructor
) {
216 const auto class_name
= std::string(((PyTypeObject
*) rec
->scope
.ptr())->tp_name
);
217 const auto func_name
= std::string(rec
->name
);
220 ("pybind11-bound class '" + class_name
+ "' is using an old-style "
221 "placement-new '" + func_name
+ "' which has been deprecated. See "
222 "the upgrade guide in pybind11's docs. This message is only visible "
223 "when compiled in debug mode.").c_str(), 0
228 /* Generate a proper function signature */
229 std::string signature
;
230 size_t type_index
= 0, arg_index
= 0;
231 for (auto *pc
= text
; *pc
!= '\0'; ++pc
) {
235 // Write arg name for everything except *args and **kwargs.
236 if (*(pc
+ 1) == '*')
239 if (arg_index
< rec
->args
.size() && rec
->args
[arg_index
].name
) {
240 signature
+= rec
->args
[arg_index
].name
;
241 } else if (arg_index
== 0 && rec
->is_method
) {
244 signature
+= "arg" + std::to_string(arg_index
- (rec
->is_method
? 1 : 0));
247 } else if (c
== '}') {
248 // Write default value if available.
249 if (arg_index
< rec
->args
.size() && rec
->args
[arg_index
].descr
) {
251 signature
+= rec
->args
[arg_index
].descr
;
254 } else if (c
== '%') {
255 const std::type_info
*t
= types
[type_index
++];
257 pybind11_fail("Internal error while parsing type signature (1)");
258 if (auto tinfo
= detail::get_type_info(*t
)) {
259 handle
th((PyObject
*) tinfo
->type
);
261 th
.attr("__module__").cast
<std::string
>() + "." +
262 th
.attr("__qualname__").cast
<std::string
>(); // Python 3.3+, but we backport it to earlier versions
263 } else if (rec
->is_new_style_constructor
&& arg_index
== 0) {
264 // A new-style `__init__` takes `self` as `value_and_holder`.
265 // Rewrite it to the proper class type.
267 rec
->scope
.attr("__module__").cast
<std::string
>() + "." +
268 rec
->scope
.attr("__qualname__").cast
<std::string
>();
270 std::string
tname(t
->name());
271 detail::clean_type_id(tname
);
278 if (arg_index
!= args
|| types
[type_index
] != nullptr)
279 pybind11_fail("Internal error while parsing type signature (2)");
281 #if PY_MAJOR_VERSION < 3
282 if (strcmp(rec
->name
, "__next__") == 0) {
283 std::free(rec
->name
);
284 rec
->name
= strdup("next");
285 } else if (strcmp(rec
->name
, "__bool__") == 0) {
286 std::free(rec
->name
);
287 rec
->name
= strdup("__nonzero__");
290 rec
->signature
= strdup(signature
.c_str());
291 rec
->args
.shrink_to_fit();
292 rec
->nargs
= (std::uint16_t) args
;
294 if (rec
->sibling
&& PYBIND11_INSTANCE_METHOD_CHECK(rec
->sibling
.ptr()))
295 rec
->sibling
= PYBIND11_INSTANCE_METHOD_GET_FUNCTION(rec
->sibling
.ptr());
297 detail::function_record
*chain
= nullptr, *chain_start
= rec
;
299 if (PyCFunction_Check(rec
->sibling
.ptr())) {
300 auto rec_capsule
= reinterpret_borrow
<capsule
>(PyCFunction_GET_SELF(rec
->sibling
.ptr()));
301 chain
= (detail::function_record
*) rec_capsule
;
302 /* Never append a method to an overload chain of a parent class;
303 instead, hide the parent's overloads in this case */
304 if (!chain
->scope
.is(rec
->scope
))
307 // Don't trigger for things like the default __init__, which are wrapper_descriptors that we are intentionally replacing
308 else if (!rec
->sibling
.is_none() && rec
->name
[0] != '_')
309 pybind11_fail("Cannot overload existing non-function object \"" + std::string(rec
->name
) +
310 "\" with a function of the same name");
314 /* No existing overload was found, create a new function object */
315 rec
->def
= new PyMethodDef();
316 std::memset(rec
->def
, 0, sizeof(PyMethodDef
));
317 rec
->def
->ml_name
= rec
->name
;
318 rec
->def
->ml_meth
= reinterpret_cast<PyCFunction
>(reinterpret_cast<void (*) (void)>(*dispatcher
));
319 rec
->def
->ml_flags
= METH_VARARGS
| METH_KEYWORDS
;
321 capsule
rec_capsule(rec
, [](void *ptr
) {
322 destruct((detail::function_record
*) ptr
);
327 if (hasattr(rec
->scope
, "__module__")) {
328 scope_module
= rec
->scope
.attr("__module__");
329 } else if (hasattr(rec
->scope
, "__name__")) {
330 scope_module
= rec
->scope
.attr("__name__");
334 m_ptr
= PyCFunction_NewEx(rec
->def
, rec_capsule
.ptr(), scope_module
.ptr());
336 pybind11_fail("cpp_function::cpp_function(): Could not allocate function object");
338 /* Append at the end of the overload chain */
339 m_ptr
= rec
->sibling
.ptr();
342 if (chain
->is_method
!= rec
->is_method
)
343 pybind11_fail("overloading a method with both static and instance methods is not supported; "
345 "compile in debug mode for more details"
347 "error while attempting to bind " + std::string(rec
->is_method
? "instance" : "static") + " method " +
348 std::string(pybind11::str(rec
->scope
.attr("__name__"))) + "." + std::string(rec
->name
) + signature
356 std::string signatures
;
358 /* Create a nice pydoc rec including all signatures and
359 docstrings of the functions in the overload chain */
360 if (chain
&& options::show_function_signatures()) {
361 // First a generic signature
362 signatures
+= rec
->name
;
363 signatures
+= "(*args, **kwargs)\n";
364 signatures
+= "Overloaded function.\n\n";
366 // Then specific overload signatures
367 bool first_user_def
= true;
368 for (auto it
= chain_start
; it
!= nullptr; it
= it
->next
) {
369 if (options::show_function_signatures()) {
370 if (index
> 0) signatures
+= "\n";
372 signatures
+= std::to_string(++index
) + ". ";
373 signatures
+= rec
->name
;
374 signatures
+= it
->signature
;
377 if (it
->doc
&& strlen(it
->doc
) > 0 && options::show_user_defined_docstrings()) {
378 // If we're appending another docstring, and aren't printing function signatures, we
379 // need to append a newline first:
380 if (!options::show_function_signatures()) {
381 if (first_user_def
) first_user_def
= false;
382 else signatures
+= "\n";
384 if (options::show_function_signatures()) signatures
+= "\n";
385 signatures
+= it
->doc
;
386 if (options::show_function_signatures()) signatures
+= "\n";
390 /* Install docstring */
391 PyCFunctionObject
*func
= (PyCFunctionObject
*) m_ptr
;
392 if (func
->m_ml
->ml_doc
)
393 std::free(const_cast<char *>(func
->m_ml
->ml_doc
));
394 func
->m_ml
->ml_doc
= strdup(signatures
.c_str());
396 if (rec
->is_method
) {
397 m_ptr
= PYBIND11_INSTANCE_METHOD_NEW(m_ptr
, rec
->scope
.ptr());
399 pybind11_fail("cpp_function::cpp_function(): Could not allocate instance method object");
404 /// When a cpp_function is GCed, release any memory allocated by pybind11
405 static void destruct(detail::function_record
*rec
) {
407 detail::function_record
*next
= rec
->next
;
410 std::free((char *) rec
->name
);
411 std::free((char *) rec
->doc
);
412 std::free((char *) rec
->signature
);
413 for (auto &arg
: rec
->args
) {
414 std::free(const_cast<char *>(arg
.name
));
415 std::free(const_cast<char *>(arg
.descr
));
419 std::free(const_cast<char *>(rec
->def
->ml_doc
));
427 /// Main dispatch logic for calls to functions bound using pybind11
428 static PyObject
*dispatcher(PyObject
*self
, PyObject
*args_in
, PyObject
*kwargs_in
) {
429 using namespace detail
;
431 /* Iterator over the list of potentially admissible overloads */
432 const function_record
*overloads
= (function_record
*) PyCapsule_GetPointer(self
, nullptr),
435 /* Need to know how many arguments + keyword arguments there are to pick the right overload */
436 const size_t n_args_in
= (size_t) PyTuple_GET_SIZE(args_in
);
438 handle parent
= n_args_in
> 0 ? PyTuple_GET_ITEM(args_in
, 0) : nullptr,
439 result
= PYBIND11_TRY_NEXT_OVERLOAD
;
441 auto self_value_and_holder
= value_and_holder();
442 if (overloads
->is_constructor
) {
443 const auto tinfo
= get_type_info((PyTypeObject
*) overloads
->scope
.ptr());
444 const auto pi
= reinterpret_cast<instance
*>(parent
.ptr());
445 self_value_and_holder
= pi
->get_value_and_holder(tinfo
, false);
447 if (!self_value_and_holder
.type
|| !self_value_and_holder
.inst
) {
448 PyErr_SetString(PyExc_TypeError
, "__init__(self, ...) called with invalid `self` argument");
452 // If this value is already registered it must mean __init__ is invoked multiple times;
453 // we really can't support that in C++, so just ignore the second __init__.
454 if (self_value_and_holder
.instance_registered())
455 return none().release().ptr();
459 // We do this in two passes: in the first pass, we load arguments with `convert=false`;
460 // in the second, we allow conversion (except for arguments with an explicit
461 // py::arg().noconvert()). This lets us prefer calls without conversion, with
462 // conversion as a fallback.
463 std::vector
<function_call
> second_pass
;
465 // However, if there are no overloads, we can just skip the no-convert pass entirely
466 const bool overloaded
= it
!= nullptr && it
->next
!= nullptr;
468 for (; it
!= nullptr; it
= it
->next
) {
470 /* For each overload:
471 1. Copy all positional arguments we were given, also checking to make sure that
472 named positional arguments weren't *also* specified via kwarg.
473 2. If we weren't given enough, try to make up the omitted ones by checking
474 whether they were provided by a kwarg matching the `py::arg("name")` name. If
475 so, use it (and remove it from kwargs; if not, see if the function binding
476 provided a default that we can use.
477 3. Ensure that either all keyword arguments were "consumed", or that the function
478 takes a kwargs argument to accept unconsumed kwargs.
479 4. Any positional arguments still left get put into a tuple (for args), and any
480 leftover kwargs get put into a dict.
481 5. Pack everything into a vector; if we have py::args or py::kwargs, they are an
482 extra tuple or dict at the end of the positional arguments.
483 6. Call the function call dispatcher (function_record::impl)
485 If one of these fail, move on to the next overload and keep trying until we get a
486 result other than PYBIND11_TRY_NEXT_OVERLOAD.
489 const function_record
&func
= *it
;
490 size_t pos_args
= func
.nargs
; // Number of positional arguments that we need
491 if (func
.has_args
) --pos_args
; // (but don't count py::args
492 if (func
.has_kwargs
) --pos_args
; // or py::kwargs)
494 if (!func
.has_args
&& n_args_in
> pos_args
)
495 continue; // Too many arguments for this overload
497 if (n_args_in
< pos_args
&& func
.args
.size() < pos_args
)
498 continue; // Not enough arguments given, and not enough defaults to fill in the blanks
500 function_call
call(func
, parent
);
502 size_t args_to_copy
= (std::min
)(pos_args
, n_args_in
); // Protect std::min with parentheses
503 size_t args_copied
= 0;
505 // 0. Inject new-style `self` argument
506 if (func
.is_new_style_constructor
) {
507 // The `value` may have been preallocated by an old-style `__init__`
508 // if it was a preceding candidate for overload resolution.
509 if (self_value_and_holder
)
510 self_value_and_holder
.type
->dealloc(self_value_and_holder
);
512 call
.init_self
= PyTuple_GET_ITEM(args_in
, 0);
513 call
.args
.push_back(reinterpret_cast<PyObject
*>(&self_value_and_holder
));
514 call
.args_convert
.push_back(false);
518 // 1. Copy any position arguments given.
519 bool bad_arg
= false;
520 for (; args_copied
< args_to_copy
; ++args_copied
) {
521 const argument_record
*arg_rec
= args_copied
< func
.args
.size() ? &func
.args
[args_copied
] : nullptr;
522 if (kwargs_in
&& arg_rec
&& arg_rec
->name
&& PyDict_GetItemString(kwargs_in
, arg_rec
->name
)) {
527 handle
arg(PyTuple_GET_ITEM(args_in
, args_copied
));
528 if (arg_rec
&& !arg_rec
->none
&& arg
.is_none()) {
532 call
.args
.push_back(arg
);
533 call
.args_convert
.push_back(arg_rec
? arg_rec
->convert
: true);
536 continue; // Maybe it was meant for another overload (issue #688)
538 // We'll need to copy this if we steal some kwargs for defaults
539 dict kwargs
= reinterpret_borrow
<dict
>(kwargs_in
);
541 // 2. Check kwargs and, failing that, defaults that may help complete the list
542 if (args_copied
< pos_args
) {
543 bool copied_kwargs
= false;
545 for (; args_copied
< pos_args
; ++args_copied
) {
546 const auto &arg
= func
.args
[args_copied
];
549 if (kwargs_in
&& arg
.name
)
550 value
= PyDict_GetItemString(kwargs
.ptr(), arg
.name
);
553 // Consume a kwargs value
554 if (!copied_kwargs
) {
555 kwargs
= reinterpret_steal
<dict
>(PyDict_Copy(kwargs
.ptr()));
556 copied_kwargs
= true;
558 PyDict_DelItemString(kwargs
.ptr(), arg
.name
);
559 } else if (arg
.value
) {
564 call
.args
.push_back(value
);
565 call
.args_convert
.push_back(arg
.convert
);
571 if (args_copied
< pos_args
)
572 continue; // Not enough arguments, defaults, or kwargs to fill the positional arguments
575 // 3. Check everything was consumed (unless we have a kwargs arg)
576 if (kwargs
&& kwargs
.size() > 0 && !func
.has_kwargs
)
577 continue; // Unconsumed kwargs, but no py::kwargs argument to accept them
579 // 4a. If we have a py::args argument, create a new tuple with leftovers
582 if (args_to_copy
== 0) {
583 // We didn't copy out any position arguments from the args_in tuple, so we
584 // can reuse it directly without copying:
585 extra_args
= reinterpret_borrow
<tuple
>(args_in
);
586 } else if (args_copied
>= n_args_in
) {
587 extra_args
= tuple(0);
589 size_t args_size
= n_args_in
- args_copied
;
590 extra_args
= tuple(args_size
);
591 for (size_t i
= 0; i
< args_size
; ++i
) {
592 extra_args
[i
] = PyTuple_GET_ITEM(args_in
, args_copied
+ i
);
595 call
.args
.push_back(extra_args
);
596 call
.args_convert
.push_back(false);
597 call
.args_ref
= std::move(extra_args
);
600 // 4b. If we have a py::kwargs, pass on any remaining kwargs
601 if (func
.has_kwargs
) {
603 kwargs
= dict(); // If we didn't get one, send an empty one
604 call
.args
.push_back(kwargs
);
605 call
.args_convert
.push_back(false);
606 call
.kwargs_ref
= std::move(kwargs
);
609 // 5. Put everything in a vector. Not technically step 5, we've been building it
610 // in `call.args` all along.
612 if (call
.args
.size() != func
.nargs
|| call
.args_convert
.size() != func
.nargs
)
613 pybind11_fail("Internal error: function call dispatcher inserted wrong number of arguments!");
616 std::vector
<bool> second_pass_convert
;
618 // We're in the first no-convert pass, so swap out the conversion flags for a
619 // set of all-false flags. If the call fails, we'll swap the flags back in for
620 // the conversion-allowed call below.
621 second_pass_convert
.resize(func
.nargs
, false);
622 call
.args_convert
.swap(second_pass_convert
);
625 // 6. Call the function.
627 loader_life_support guard
{};
628 result
= func
.impl(call
);
629 } catch (reference_cast_error
&) {
630 result
= PYBIND11_TRY_NEXT_OVERLOAD
;
633 if (result
.ptr() != PYBIND11_TRY_NEXT_OVERLOAD
)
637 // The (overloaded) call failed; if the call has at least one argument that
638 // permits conversion (i.e. it hasn't been explicitly specified `.noconvert()`)
639 // then add this call to the list of second pass overloads to try.
640 for (size_t i
= func
.is_method
? 1 : 0; i
< pos_args
; i
++) {
641 if (second_pass_convert
[i
]) {
642 // Found one: swap the converting flags back in and store the call for
644 call
.args_convert
.swap(second_pass_convert
);
645 second_pass
.push_back(std::move(call
));
652 if (overloaded
&& !second_pass
.empty() && result
.ptr() == PYBIND11_TRY_NEXT_OVERLOAD
) {
653 // The no-conversion pass finished without success, try again with conversion allowed
654 for (auto &call
: second_pass
) {
656 loader_life_support guard
{};
657 result
= call
.func
.impl(call
);
658 } catch (reference_cast_error
&) {
659 result
= PYBIND11_TRY_NEXT_OVERLOAD
;
662 if (result
.ptr() != PYBIND11_TRY_NEXT_OVERLOAD
) {
663 // The error reporting logic below expects 'it' to be valid, as it would be
664 // if we'd encountered this failure in the first-pass loop.
671 } catch (error_already_set
&e
) {
674 #if defined(__GNUG__) && !defined(__clang__)
675 } catch ( abi::__forced_unwind
& ) {
679 /* When an exception is caught, give each registered exception
680 translator a chance to translate it to a Python exception
681 in reverse order of registration.
683 A translator may choose to do one of the following:
685 - catch the exception and call PyErr_SetString or PyErr_SetObject
686 to set a standard (or custom) Python exception, or
687 - do nothing and let the exception fall through to the next translator, or
688 - delegate translation to the next translator by throwing a new type of exception. */
690 auto last_exception
= std::current_exception();
691 auto ®istered_exception_translators
= get_internals().registered_exception_translators
;
692 for (auto& translator
: registered_exception_translators
) {
694 translator(last_exception
);
696 last_exception
= std::current_exception();
701 PyErr_SetString(PyExc_SystemError
, "Exception escaped from default exception translator!");
705 auto append_note_if_missing_header_is_suspected
= [](std::string
&msg
) {
706 if (msg
.find("std::") != std::string::npos
) {
708 "Did you forget to `#include <pybind11/stl.h>`? Or <pybind11/complex.h>,\n"
709 "<pybind11/functional.h>, <pybind11/chrono.h>, etc. Some automatic\n"
710 "conversions are optional and require extra headers to be included\n"
711 "when compiling your pybind11 module.";
715 if (result
.ptr() == PYBIND11_TRY_NEXT_OVERLOAD
) {
716 if (overloads
->is_operator
)
717 return handle(Py_NotImplemented
).inc_ref().ptr();
719 std::string msg
= std::string(overloads
->name
) + "(): incompatible " +
720 std::string(overloads
->is_constructor
? "constructor" : "function") +
721 " arguments. The following argument types are supported:\n";
724 for (const function_record
*it2
= overloads
; it2
!= nullptr; it2
= it2
->next
) {
725 msg
+= " "+ std::to_string(++ctr
) + ". ";
727 bool wrote_sig
= false;
728 if (overloads
->is_constructor
) {
729 // For a constructor, rewrite `(self: Object, arg0, ...) -> NoneType` as `Object(arg0, ...)`
730 std::string sig
= it2
->signature
;
731 size_t start
= sig
.find('(') + 7; // skip "(self: "
732 if (start
< sig
.size()) {
733 // End at the , for the next argument
734 size_t end
= sig
.find(", "), next
= end
+ 2;
735 size_t ret
= sig
.rfind(" -> ");
736 // Or the ), if there is no comma:
737 if (end
>= sig
.size()) next
= end
= sig
.find(')');
738 if (start
< end
&& next
< sig
.size()) {
739 msg
.append(sig
, start
, end
- start
);
741 msg
.append(sig
, next
, ret
- next
);
746 if (!wrote_sig
) msg
+= it2
->signature
;
750 msg
+= "\nInvoked with: ";
751 auto args_
= reinterpret_borrow
<tuple
>(args_in
);
752 bool some_args
= false;
753 for (size_t ti
= overloads
->is_constructor
? 1 : 0; ti
< args_
.size(); ++ti
) {
754 if (!some_args
) some_args
= true;
756 msg
+= pybind11::repr(args_
[ti
]);
759 auto kwargs
= reinterpret_borrow
<dict
>(kwargs_in
);
760 if (kwargs
.size() > 0) {
761 if (some_args
) msg
+= "; ";
764 for (auto kwarg
: kwargs
) {
765 if (first
) first
= false;
767 msg
+= pybind11::str("{}={!r}").format(kwarg
.first
, kwarg
.second
);
772 append_note_if_missing_header_is_suspected(msg
);
773 PyErr_SetString(PyExc_TypeError
, msg
.c_str());
775 } else if (!result
) {
776 std::string msg
= "Unable to convert function return value to a "
777 "Python type! The signature was\n\t";
778 msg
+= it
->signature
;
779 append_note_if_missing_header_is_suspected(msg
);
780 PyErr_SetString(PyExc_TypeError
, msg
.c_str());
783 if (overloads
->is_constructor
&& !self_value_and_holder
.holder_constructed()) {
784 auto *pi
= reinterpret_cast<instance
*>(parent
.ptr());
785 self_value_and_holder
.type
->init_instance(pi
, nullptr);
792 /// Wrapper for Python extension modules
793 class module
: public object
{
795 PYBIND11_OBJECT_DEFAULT(module
, object
, PyModule_Check
)
797 /// Create a new top-level Python module with the given name and docstring
798 explicit module(const char *name
, const char *doc
= nullptr) {
799 if (!options::show_user_defined_docstrings()) doc
= nullptr;
800 #if PY_MAJOR_VERSION >= 3
801 PyModuleDef
*def
= new PyModuleDef();
802 std::memset(def
, 0, sizeof(PyModuleDef
));
807 m_ptr
= PyModule_Create(def
);
809 m_ptr
= Py_InitModule3(name
, nullptr, doc
);
811 if (m_ptr
== nullptr)
812 pybind11_fail("Internal error in module::module()");
817 Create Python binding for a new function within the module scope. ``Func``
818 can be a plain C++ function, a function pointer, or a lambda function. For
819 details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
821 template <typename Func
, typename
... Extra
>
822 module
&def(const char *name_
, Func
&&f
, const Extra
& ... extra
) {
823 cpp_function
func(std::forward
<Func
>(f
), name(name_
), scope(*this),
824 sibling(getattr(*this, name_
, none())), extra
...);
825 // NB: allow overwriting here because cpp_function sets up a chain with the intention of
826 // overwriting (and has already checked internally that it isn't overwriting non-functions).
827 add_object(name_
, func
, true /* overwrite */);
832 Create and return a new Python submodule with the given name and docstring.
833 This also works recursively, i.e.
837 py::module m("example", "pybind11 example plugin");
838 py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
839 py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
841 module
def_submodule(const char *name
, const char *doc
= nullptr) {
842 std::string full_name
= std::string(PyModule_GetName(m_ptr
))
843 + std::string(".") + std::string(name
);
844 auto result
= reinterpret_borrow
<module
>(PyImport_AddModule(full_name
.c_str()));
845 if (doc
&& options::show_user_defined_docstrings())
846 result
.attr("__doc__") = pybind11::str(doc
);
851 /// Import and return a module or throws `error_already_set`.
852 static module
import(const char *name
) {
853 PyObject
*obj
= PyImport_ImportModule(name
);
855 throw error_already_set();
856 return reinterpret_steal
<module
>(obj
);
859 /// Reload the module or throws `error_already_set`.
861 PyObject
*obj
= PyImport_ReloadModule(ptr());
863 throw error_already_set();
864 *this = reinterpret_steal
<module
>(obj
);
867 // Adds an object to the module using the given name. Throws if an object with the given name
870 // overwrite should almost always be false: attempting to overwrite objects that pybind11 has
871 // established will, in most cases, break things.
872 PYBIND11_NOINLINE
void add_object(const char *name
, handle obj
, bool overwrite
= false) {
873 if (!overwrite
&& hasattr(*this, name
))
874 pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" +
875 std::string(name
) + "\"");
877 PyModule_AddObject(ptr(), name
, obj
.inc_ref().ptr() /* steals a reference */);
881 /// \ingroup python_builtins
882 /// Return a dictionary representing the global variables in the current execution frame,
883 /// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded).
884 inline dict
globals() {
885 PyObject
*p
= PyEval_GetGlobals();
886 return reinterpret_borrow
<dict
>(p
? p
: module::import("__main__").attr("__dict__").ptr());
889 NAMESPACE_BEGIN(detail
)
890 /// Generic support for creating new Python heap types
891 class generic_type
: public object
{
892 template <typename
...> friend class class_
;
894 PYBIND11_OBJECT_DEFAULT(generic_type
, object
, PyType_Check
)
896 void initialize(const type_record
&rec
) {
897 if (rec
.scope
&& hasattr(rec
.scope
, rec
.name
))
898 pybind11_fail("generic_type: cannot initialize type \"" + std::string(rec
.name
) +
899 "\": an object with that name is already defined");
901 if (rec
.module_local
? get_local_type_info(*rec
.type
) : get_global_type_info(*rec
.type
))
902 pybind11_fail("generic_type: type \"" + std::string(rec
.name
) +
903 "\" is already registered!");
905 m_ptr
= make_new_python_type(rec
);
907 /* Register supplemental type information in C++ dict */
908 auto *tinfo
= new detail::type_info();
909 tinfo
->type
= (PyTypeObject
*) m_ptr
;
910 tinfo
->cpptype
= rec
.type
;
911 tinfo
->type_size
= rec
.type_size
;
912 tinfo
->type_align
= rec
.type_align
;
913 tinfo
->operator_new
= rec
.operator_new
;
914 tinfo
->holder_size_in_ptrs
= size_in_ptrs(rec
.holder_size
);
915 tinfo
->init_instance
= rec
.init_instance
;
916 tinfo
->dealloc
= rec
.dealloc
;
917 tinfo
->simple_type
= true;
918 tinfo
->simple_ancestors
= true;
919 tinfo
->default_holder
= rec
.default_holder
;
920 tinfo
->module_local
= rec
.module_local
;
922 auto &internals
= get_internals();
923 auto tindex
= std::type_index(*rec
.type
);
924 tinfo
->direct_conversions
= &internals
.direct_conversions
[tindex
];
925 if (rec
.module_local
)
926 registered_local_types_cpp()[tindex
] = tinfo
;
928 internals
.registered_types_cpp
[tindex
] = tinfo
;
929 internals
.registered_types_py
[(PyTypeObject
*) m_ptr
] = { tinfo
};
931 if (rec
.bases
.size() > 1 || rec
.multiple_inheritance
) {
932 mark_parents_nonsimple(tinfo
->type
);
933 tinfo
->simple_ancestors
= false;
935 else if (rec
.bases
.size() == 1) {
936 auto parent_tinfo
= get_type_info((PyTypeObject
*) rec
.bases
[0].ptr());
937 tinfo
->simple_ancestors
= parent_tinfo
->simple_ancestors
;
940 if (rec
.module_local
) {
941 // Stash the local typeinfo and loader so that external modules can access it.
942 tinfo
->module_local_load
= &type_caster_generic::local_load
;
943 setattr(m_ptr
, PYBIND11_MODULE_LOCAL_ID
, capsule(tinfo
));
947 /// Helper function which tags all parents of a type using mult. inheritance
948 void mark_parents_nonsimple(PyTypeObject
*value
) {
949 auto t
= reinterpret_borrow
<tuple
>(value
->tp_bases
);
951 auto tinfo2
= get_type_info((PyTypeObject
*) h
.ptr());
953 tinfo2
->simple_type
= false;
954 mark_parents_nonsimple((PyTypeObject
*) h
.ptr());
958 void install_buffer_funcs(
959 buffer_info
*(*get_buffer
)(PyObject
*, void *),
960 void *get_buffer_data
) {
961 PyHeapTypeObject
*type
= (PyHeapTypeObject
*) m_ptr
;
962 auto tinfo
= detail::get_type_info(&type
->ht_type
);
964 if (!type
->ht_type
.tp_as_buffer
)
966 "To be able to register buffer protocol support for the type '" +
967 std::string(tinfo
->type
->tp_name
) +
968 "' the associated class<>(..) invocation must "
969 "include the pybind11::buffer_protocol() annotation!");
971 tinfo
->get_buffer
= get_buffer
;
972 tinfo
->get_buffer_data
= get_buffer_data
;
975 // rec_func must be set for either fget or fset.
976 void def_property_static_impl(const char *name
,
977 handle fget
, handle fset
,
978 detail::function_record
*rec_func
) {
979 const auto is_static
= rec_func
&& !(rec_func
->is_method
&& rec_func
->scope
);
980 const auto has_doc
= rec_func
&& rec_func
->doc
&& pybind11::options::show_user_defined_docstrings();
981 auto property
= handle((PyObject
*) (is_static
? get_internals().static_property_type
982 : &PyProperty_Type
));
983 attr(name
) = property(fget
.ptr() ? fget
: none(),
984 fset
.ptr() ? fset
: none(),
986 pybind11::str(has_doc
? rec_func
->doc
: ""));
990 /// Set the pointer to operator new if it exists. The cast is needed because it can be overloaded.
991 template <typename T
, typename
= void_t
<decltype(static_cast<void *(*)(size_t)>(T::operator new))>>
992 void set_operator_new(type_record
*r
) { r
->operator_new
= &T::operator new; }
994 template <typename
> void set_operator_new(...) { }
996 template <typename T
, typename SFINAE
= void> struct has_operator_delete
: std::false_type
{ };
997 template <typename T
> struct has_operator_delete
<T
, void_t
<decltype(static_cast<void (*)(void *)>(T::operator delete))>>
998 : std::true_type
{ };
999 template <typename T
, typename SFINAE
= void> struct has_operator_delete_size
: std::false_type
{ };
1000 template <typename T
> struct has_operator_delete_size
<T
, void_t
<decltype(static_cast<void (*)(void *, size_t)>(T::operator delete))>>
1001 : std::true_type
{ };
1002 /// Call class-specific delete if it exists or global otherwise. Can also be an overload set.
1003 template <typename T
, enable_if_t
<has_operator_delete
<T
>::value
, int> = 0>
1004 void call_operator_delete(T
*p
, size_t, size_t) { T::operator delete(p
); }
1005 template <typename T
, enable_if_t
<!has_operator_delete
<T
>::value
&& has_operator_delete_size
<T
>::value
, int> = 0>
1006 void call_operator_delete(T
*p
, size_t s
, size_t) { T::operator delete(p
, s
); }
1008 inline void call_operator_delete(void *p
, size_t s
, size_t a
) {
1010 #if defined(PYBIND11_CPP17)
1011 if (a
> __STDCPP_DEFAULT_NEW_ALIGNMENT__
)
1012 ::operator delete(p
, s
, std::align_val_t(a
));
1014 ::operator delete(p
, s
);
1016 ::operator delete(p
);
1020 NAMESPACE_END(detail
)
1022 /// Given a pointer to a member function, cast it to its `Derived` version.
1023 /// Forward everything else unchanged.
1024 template <typename
/*Derived*/, typename F
>
1025 auto method_adaptor(F
&&f
) -> decltype(std::forward
<F
>(f
)) { return std::forward
<F
>(f
); }
1027 template <typename Derived
, typename Return
, typename Class
, typename
... Args
>
1028 auto method_adaptor(Return (Class::*pmf
)(Args
...)) -> Return (Derived::*)(Args
...) {
1029 static_assert(detail::is_accessible_base_of
<Class
, Derived
>::value
,
1030 "Cannot bind an inaccessible base class method; use a lambda definition instead");
1034 template <typename Derived
, typename Return
, typename Class
, typename
... Args
>
1035 auto method_adaptor(Return (Class::*pmf
)(Args
...) const) -> Return (Derived::*)(Args
...) const {
1036 static_assert(detail::is_accessible_base_of
<Class
, Derived
>::value
,
1037 "Cannot bind an inaccessible base class method; use a lambda definition instead");
1041 template <typename type_
, typename
... options
>
1042 class class_
: public detail::generic_type
{
1043 template <typename T
> using is_holder
= detail::is_holder_type
<type_
, T
>;
1044 template <typename T
> using is_subtype
= detail::is_strict_base_of
<type_
, T
>;
1045 template <typename T
> using is_base
= detail::is_strict_base_of
<T
, type_
>;
1046 // struct instead of using here to help MSVC:
1047 template <typename T
> struct is_valid_class_option
:
1048 detail::any_of
<is_holder
<T
>, is_subtype
<T
>, is_base
<T
>> {};
1052 using type_alias
= detail::exactly_one_t
<is_subtype
, void, options
...>;
1053 constexpr static bool has_alias
= !std::is_void
<type_alias
>::value
;
1054 using holder_type
= detail::exactly_one_t
<is_holder
, std::unique_ptr
<type
>, options
...>;
1056 static_assert(detail::all_of
<is_valid_class_option
<options
>...>::value
,
1057 "Unknown/invalid class_ template parameters provided");
1059 static_assert(!has_alias
|| std::is_polymorphic
<type
>::value
,
1060 "Cannot use an alias class with a non-polymorphic type");
1062 PYBIND11_OBJECT(class_
, generic_type
, PyType_Check
)
1064 template <typename
... Extra
>
1065 class_(handle scope
, const char *name
, const Extra
&... extra
) {
1066 using namespace detail
;
1068 // MI can only be specified via class_ template options, not constructor parameters
1070 none_of
<is_pyobject
<Extra
>...>::value
|| // no base class arguments, or:
1071 ( constexpr_sum(is_pyobject
<Extra
>::value
...) == 1 && // Exactly one base
1072 constexpr_sum(is_base
<options
>::value
...) == 0 && // no template option bases
1073 none_of
<std::is_same
<multiple_inheritance
, Extra
>...>::value
), // no multiple_inheritance attr
1074 "Error: multiple inheritance bases must be specified via class_ template options");
1077 record
.scope
= scope
;
1079 record
.type
= &typeid(type
);
1080 record
.type_size
= sizeof(conditional_t
<has_alias
, type_alias
, type
>);
1081 record
.type_align
= alignof(conditional_t
<has_alias
, type_alias
, type
>&);
1082 record
.holder_size
= sizeof(holder_type
);
1083 record
.init_instance
= init_instance
;
1084 record
.dealloc
= dealloc
;
1085 record
.default_holder
= detail::is_instantiation
<std::unique_ptr
, holder_type
>::value
;
1087 set_operator_new
<type
>(&record
);
1089 /* Register base classes specified via template arguments to class_, if any */
1090 PYBIND11_EXPAND_SIDE_EFFECTS(add_base
<options
>(record
));
1092 /* Process optional arguments, if any */
1093 process_attributes
<Extra
...>::init(extra
..., &record
);
1095 generic_type::initialize(record
);
1098 auto &instances
= record
.module_local
? registered_local_types_cpp() : get_internals().registered_types_cpp
;
1099 instances
[std::type_index(typeid(type_alias
))] = instances
[std::type_index(typeid(type
))];
1103 template <typename Base
, detail::enable_if_t
<is_base
<Base
>::value
, int> = 0>
1104 static void add_base(detail::type_record
&rec
) {
1105 rec
.add_base(typeid(Base
), [](void *src
) -> void * {
1106 return static_cast<Base
*>(reinterpret_cast<type
*>(src
));
1110 template <typename Base
, detail::enable_if_t
<!is_base
<Base
>::value
, int> = 0>
1111 static void add_base(detail::type_record
&) { }
1113 template <typename Func
, typename
... Extra
>
1114 class_
&def(const char *name_
, Func
&& f
, const Extra
&... extra
) {
1115 cpp_function
cf(method_adaptor
<type
>(std::forward
<Func
>(f
)), name(name_
), is_method(*this),
1116 sibling(getattr(*this, name_
, none())), extra
...);
1117 attr(cf
.name()) = cf
;
1121 template <typename Func
, typename
... Extra
> class_
&
1122 def_static(const char *name_
, Func
&&f
, const Extra
&... extra
) {
1123 static_assert(!std::is_member_function_pointer
<Func
>::value
,
1124 "def_static(...) called with a non-static member function pointer");
1125 cpp_function
cf(std::forward
<Func
>(f
), name(name_
), scope(*this),
1126 sibling(getattr(*this, name_
, none())), extra
...);
1127 attr(cf
.name()) = staticmethod(cf
);
1131 template <detail::op_id id
, detail::op_type ot
, typename L
, typename R
, typename
... Extra
>
1132 class_
&def(const detail::op_
<id
, ot
, L
, R
> &op
, const Extra
&... extra
) {
1133 op
.execute(*this, extra
...);
1137 template <detail::op_id id
, detail::op_type ot
, typename L
, typename R
, typename
... Extra
>
1138 class_
& def_cast(const detail::op_
<id
, ot
, L
, R
> &op
, const Extra
&... extra
) {
1139 op
.execute_cast(*this, extra
...);
1143 template <typename
... Args
, typename
... Extra
>
1144 class_
&def(const detail::initimpl::constructor
<Args
...> &init
, const Extra
&... extra
) {
1145 init
.execute(*this, extra
...);
1149 template <typename
... Args
, typename
... Extra
>
1150 class_
&def(const detail::initimpl::alias_constructor
<Args
...> &init
, const Extra
&... extra
) {
1151 init
.execute(*this, extra
...);
1155 template <typename
... Args
, typename
... Extra
>
1156 class_
&def(detail::initimpl::factory
<Args
...> &&init
, const Extra
&... extra
) {
1157 std::move(init
).execute(*this, extra
...);
1161 template <typename
... Args
, typename
... Extra
>
1162 class_
&def(detail::initimpl::pickle_factory
<Args
...> &&pf
, const Extra
&...extra
) {
1163 std::move(pf
).execute(*this, extra
...);
1167 template <typename Func
> class_
& def_buffer(Func
&&func
) {
1168 struct capture
{ Func func
; };
1169 capture
*ptr
= new capture
{ std::forward
<Func
>(func
) };
1170 install_buffer_funcs([](PyObject
*obj
, void *ptr
) -> buffer_info
* {
1171 detail::make_caster
<type
> caster
;
1172 if (!caster
.load(obj
, false))
1174 return new buffer_info(((capture
*) ptr
)->func(caster
));
1179 template <typename Return
, typename Class
, typename
... Args
>
1180 class_
&def_buffer(Return (Class::*func
)(Args
...)) {
1181 return def_buffer([func
] (type
&obj
) { return (obj
.*func
)(); });
1184 template <typename Return
, typename Class
, typename
... Args
>
1185 class_
&def_buffer(Return (Class::*func
)(Args
...) const) {
1186 return def_buffer([func
] (const type
&obj
) { return (obj
.*func
)(); });
1189 template <typename C
, typename D
, typename
... Extra
>
1190 class_
&def_readwrite(const char *name
, D
C::*pm
, const Extra
&... extra
) {
1191 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)");
1192 cpp_function
fget([pm
](const type
&c
) -> const D
&{ return c
.*pm
; }, is_method(*this)),
1193 fset([pm
](type
&c
, const D
&value
) { c
.*pm
= value
; }, is_method(*this));
1194 def_property(name
, fget
, fset
, return_value_policy::reference_internal
, extra
...);
1198 template <typename C
, typename D
, typename
... Extra
>
1199 class_
&def_readonly(const char *name
, const D
C::*pm
, const Extra
& ...extra
) {
1200 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)");
1201 cpp_function
fget([pm
](const type
&c
) -> const D
&{ return c
.*pm
; }, is_method(*this));
1202 def_property_readonly(name
, fget
, return_value_policy::reference_internal
, extra
...);
1206 template <typename D
, typename
... Extra
>
1207 class_
&def_readwrite_static(const char *name
, D
*pm
, const Extra
& ...extra
) {
1208 cpp_function
fget([pm
](object
) -> const D
&{ return *pm
; }, scope(*this)),
1209 fset([pm
](object
, const D
&value
) { *pm
= value
; }, scope(*this));
1210 def_property_static(name
, fget
, fset
, return_value_policy::reference
, extra
...);
1214 template <typename D
, typename
... Extra
>
1215 class_
&def_readonly_static(const char *name
, const D
*pm
, const Extra
& ...extra
) {
1216 cpp_function
fget([pm
](object
) -> const D
&{ return *pm
; }, scope(*this));
1217 def_property_readonly_static(name
, fget
, return_value_policy::reference
, extra
...);
1221 /// Uses return_value_policy::reference_internal by default
1222 template <typename Getter
, typename
... Extra
>
1223 class_
&def_property_readonly(const char *name
, const Getter
&fget
, const Extra
& ...extra
) {
1224 return def_property_readonly(name
, cpp_function(method_adaptor
<type
>(fget
)),
1225 return_value_policy::reference_internal
, extra
...);
1228 /// Uses cpp_function's return_value_policy by default
1229 template <typename
... Extra
>
1230 class_
&def_property_readonly(const char *name
, const cpp_function
&fget
, const Extra
& ...extra
) {
1231 return def_property(name
, fget
, nullptr, extra
...);
1234 /// Uses return_value_policy::reference by default
1235 template <typename Getter
, typename
... Extra
>
1236 class_
&def_property_readonly_static(const char *name
, const Getter
&fget
, const Extra
& ...extra
) {
1237 return def_property_readonly_static(name
, cpp_function(fget
), return_value_policy::reference
, extra
...);
1240 /// Uses cpp_function's return_value_policy by default
1241 template <typename
... Extra
>
1242 class_
&def_property_readonly_static(const char *name
, const cpp_function
&fget
, const Extra
& ...extra
) {
1243 return def_property_static(name
, fget
, nullptr, extra
...);
1246 /// Uses return_value_policy::reference_internal by default
1247 template <typename Getter
, typename Setter
, typename
... Extra
>
1248 class_
&def_property(const char *name
, const Getter
&fget
, const Setter
&fset
, const Extra
& ...extra
) {
1249 return def_property(name
, fget
, cpp_function(method_adaptor
<type
>(fset
)), extra
...);
1251 template <typename Getter
, typename
... Extra
>
1252 class_
&def_property(const char *name
, const Getter
&fget
, const cpp_function
&fset
, const Extra
& ...extra
) {
1253 return def_property(name
, cpp_function(method_adaptor
<type
>(fget
)), fset
,
1254 return_value_policy::reference_internal
, extra
...);
1257 /// Uses cpp_function's return_value_policy by default
1258 template <typename
... Extra
>
1259 class_
&def_property(const char *name
, const cpp_function
&fget
, const cpp_function
&fset
, const Extra
& ...extra
) {
1260 return def_property_static(name
, fget
, fset
, is_method(*this), extra
...);
1263 /// Uses return_value_policy::reference by default
1264 template <typename Getter
, typename
... Extra
>
1265 class_
&def_property_static(const char *name
, const Getter
&fget
, const cpp_function
&fset
, const Extra
& ...extra
) {
1266 return def_property_static(name
, cpp_function(fget
), fset
, return_value_policy::reference
, extra
...);
1269 /// Uses cpp_function's return_value_policy by default
1270 template <typename
... Extra
>
1271 class_
&def_property_static(const char *name
, const cpp_function
&fget
, const cpp_function
&fset
, const Extra
& ...extra
) {
1272 static_assert( 0 == detail::constexpr_sum(std::is_base_of
<arg
, Extra
>::value
...),
1273 "Argument annotations are not allowed for properties");
1274 auto rec_fget
= get_function_record(fget
), rec_fset
= get_function_record(fset
);
1275 auto *rec_active
= rec_fget
;
1277 char *doc_prev
= rec_fget
->doc
; /* 'extra' field may include a property-specific documentation string */
1278 detail::process_attributes
<Extra
...>::init(extra
..., rec_fget
);
1279 if (rec_fget
->doc
&& rec_fget
->doc
!= doc_prev
) {
1281 rec_fget
->doc
= strdup(rec_fget
->doc
);
1285 char *doc_prev
= rec_fset
->doc
;
1286 detail::process_attributes
<Extra
...>::init(extra
..., rec_fset
);
1287 if (rec_fset
->doc
&& rec_fset
->doc
!= doc_prev
) {
1289 rec_fset
->doc
= strdup(rec_fset
->doc
);
1291 if (! rec_active
) rec_active
= rec_fset
;
1293 def_property_static_impl(name
, fget
, fset
, rec_active
);
1298 /// Initialize holder object, variant 1: object derives from enable_shared_from_this
1299 template <typename T
>
1300 static void init_holder(detail::instance
*inst
, detail::value_and_holder
&v_h
,
1301 const holder_type
* /* unused */, const std::enable_shared_from_this
<T
> * /* dummy */) {
1303 auto sh
= std::dynamic_pointer_cast
<typename
holder_type::element_type
>(
1304 v_h
.value_ptr
<type
>()->shared_from_this());
1306 new (std::addressof(v_h
.holder
<holder_type
>())) holder_type(std::move(sh
));
1307 v_h
.set_holder_constructed();
1309 } catch (const std::bad_weak_ptr
&) {}
1311 if (!v_h
.holder_constructed() && inst
->owned
) {
1312 new (std::addressof(v_h
.holder
<holder_type
>())) holder_type(v_h
.value_ptr
<type
>());
1313 v_h
.set_holder_constructed();
1317 static void init_holder_from_existing(const detail::value_and_holder
&v_h
,
1318 const holder_type
*holder_ptr
, std::true_type
/*is_copy_constructible*/) {
1319 new (std::addressof(v_h
.holder
<holder_type
>())) holder_type(*reinterpret_cast<const holder_type
*>(holder_ptr
));
1322 static void init_holder_from_existing(const detail::value_and_holder
&v_h
,
1323 const holder_type
*holder_ptr
, std::false_type
/*is_copy_constructible*/) {
1324 new (std::addressof(v_h
.holder
<holder_type
>())) holder_type(std::move(*const_cast<holder_type
*>(holder_ptr
)));
1327 /// Initialize holder object, variant 2: try to construct from existing holder object, if possible
1328 static void init_holder(detail::instance
*inst
, detail::value_and_holder
&v_h
,
1329 const holder_type
*holder_ptr
, const void * /* dummy -- not enable_shared_from_this<T>) */) {
1331 init_holder_from_existing(v_h
, holder_ptr
, std::is_copy_constructible
<holder_type
>());
1332 v_h
.set_holder_constructed();
1333 } else if (inst
->owned
|| detail::always_construct_holder
<holder_type
>::value
) {
1334 new (std::addressof(v_h
.holder
<holder_type
>())) holder_type(v_h
.value_ptr
<type
>());
1335 v_h
.set_holder_constructed();
1339 /// Performs instance initialization including constructing a holder and registering the known
1340 /// instance. Should be called as soon as the `type` value_ptr is set for an instance. Takes an
1341 /// optional pointer to an existing holder to use; if not specified and the instance is
1342 /// `.owned`, a new holder will be constructed to manage the value pointer.
1343 static void init_instance(detail::instance
*inst
, const void *holder_ptr
) {
1344 auto v_h
= inst
->get_value_and_holder(detail::get_type_info(typeid(type
)));
1345 if (!v_h
.instance_registered()) {
1346 register_instance(inst
, v_h
.value_ptr(), v_h
.type
);
1347 v_h
.set_instance_registered();
1349 init_holder(inst
, v_h
, (const holder_type
*) holder_ptr
, v_h
.value_ptr
<type
>());
1352 /// Deallocates an instance; via holder, if constructed; otherwise via operator delete.
1353 static void dealloc(detail::value_and_holder
&v_h
) {
1354 if (v_h
.holder_constructed()) {
1355 v_h
.holder
<holder_type
>().~holder_type();
1356 v_h
.set_holder_constructed(false);
1359 detail::call_operator_delete(v_h
.value_ptr
<type
>(),
1360 v_h
.type
->type_size
,
1361 v_h
.type
->type_align
1364 v_h
.value_ptr() = nullptr;
1367 static detail::function_record
*get_function_record(handle h
) {
1368 h
= detail::get_function(h
);
1369 return h
? (detail::function_record
*) reinterpret_borrow
<capsule
>(PyCFunction_GET_SELF(h
.ptr()))
1374 /// Binds an existing constructor taking arguments Args...
1375 template <typename
... Args
> detail::initimpl::constructor
<Args
...> init() { return {}; }
1376 /// Like `init<Args...>()`, but the instance is always constructed through the alias class (even
1377 /// when not inheriting on the Python side).
1378 template <typename
... Args
> detail::initimpl::alias_constructor
<Args
...> init_alias() { return {}; }
1380 /// Binds a factory function as a constructor
1381 template <typename Func
, typename Ret
= detail::initimpl::factory
<Func
>>
1382 Ret
init(Func
&&f
) { return {std::forward
<Func
>(f
)}; }
1384 /// Dual-argument factory function: the first function is called when no alias is needed, the second
1385 /// when an alias is needed (i.e. due to python-side inheritance). Arguments must be identical.
1386 template <typename CFunc
, typename AFunc
, typename Ret
= detail::initimpl::factory
<CFunc
, AFunc
>>
1387 Ret
init(CFunc
&&c
, AFunc
&&a
) {
1388 return {std::forward
<CFunc
>(c
), std::forward
<AFunc
>(a
)};
1391 /// Binds pickling functions `__getstate__` and `__setstate__` and ensures that the type
1392 /// returned by `__getstate__` is the same as the argument accepted by `__setstate__`.
1393 template <typename GetState
, typename SetState
>
1394 detail::initimpl::pickle_factory
<GetState
, SetState
> pickle(GetState
&&g
, SetState
&&s
) {
1395 return {std::forward
<GetState
>(g
), std::forward
<SetState
>(s
)};
1398 NAMESPACE_BEGIN(detail
)
1400 enum_base(handle base
, handle parent
) : m_base(base
), m_parent(parent
) { }
1402 PYBIND11_NOINLINE
void init(bool is_arithmetic
, bool is_convertible
) {
1403 m_base
.attr("__entries") = dict();
1404 auto property
= handle((PyObject
*) &PyProperty_Type
);
1405 auto static_property
= handle((PyObject
*) get_internals().static_property_type
);
1407 m_base
.attr("__repr__") = cpp_function(
1408 [](handle arg
) -> str
{
1409 handle type
= arg
.get_type();
1410 object type_name
= type
.attr("__name__");
1411 dict entries
= type
.attr("__entries");
1412 for (const auto &kv
: entries
) {
1413 object other
= kv
.second
[int_(0)];
1414 if (other
.equal(arg
))
1415 return pybind11::str("{}.{}").format(type_name
, kv
.first
);
1417 return pybind11::str("{}.???").format(type_name
);
1418 }, is_method(m_base
)
1421 m_base
.attr("name") = property(cpp_function(
1422 [](handle arg
) -> str
{
1423 dict entries
= arg
.get_type().attr("__entries");
1424 for (const auto &kv
: entries
) {
1425 if (handle(kv
.second
[int_(0)]).equal(arg
))
1426 return pybind11::str(kv
.first
);
1429 }, is_method(m_base
)
1432 m_base
.attr("__doc__") = static_property(cpp_function(
1433 [](handle arg
) -> std::string
{
1434 std::string docstring
;
1435 dict entries
= arg
.attr("__entries");
1436 if (((PyTypeObject
*) arg
.ptr())->tp_doc
)
1437 docstring
+= std::string(((PyTypeObject
*) arg
.ptr())->tp_doc
) + "\n\n";
1438 docstring
+= "Members:";
1439 for (const auto &kv
: entries
) {
1440 auto key
= std::string(pybind11::str(kv
.first
));
1441 auto comment
= kv
.second
[int_(1)];
1442 docstring
+= "\n\n " + key
;
1443 if (!comment
.is_none())
1444 docstring
+= " : " + (std::string
) pybind11::str(comment
);
1448 ), none(), none(), "");
1450 m_base
.attr("__members__") = static_property(cpp_function(
1451 [](handle arg
) -> dict
{
1452 dict entries
= arg
.attr("__entries"), m
;
1453 for (const auto &kv
: entries
)
1454 m
[kv
.first
] = kv
.second
[int_(0)];
1456 }), none(), none(), ""
1459 #define PYBIND11_ENUM_OP_STRICT(op, expr, strict_behavior) \
1460 m_base.attr(op) = cpp_function( \
1461 [](object a, object b) { \
1462 if (!a.get_type().is(b.get_type())) \
1468 #define PYBIND11_ENUM_OP_CONV(op, expr) \
1469 m_base.attr(op) = cpp_function( \
1470 [](object a_, object b_) { \
1471 int_ a(a_), b(b_); \
1476 #define PYBIND11_ENUM_OP_CONV_LHS(op, expr) \
1477 m_base.attr(op) = cpp_function( \
1478 [](object a_, object b) { \
1484 if (is_convertible
) {
1485 PYBIND11_ENUM_OP_CONV_LHS("__eq__", !b
.is_none() && a
.equal(b
));
1486 PYBIND11_ENUM_OP_CONV_LHS("__ne__", b
.is_none() || !a
.equal(b
));
1488 if (is_arithmetic
) {
1489 PYBIND11_ENUM_OP_CONV("__lt__", a
< b
);
1490 PYBIND11_ENUM_OP_CONV("__gt__", a
> b
);
1491 PYBIND11_ENUM_OP_CONV("__le__", a
<= b
);
1492 PYBIND11_ENUM_OP_CONV("__ge__", a
>= b
);
1493 PYBIND11_ENUM_OP_CONV("__and__", a
& b
);
1494 PYBIND11_ENUM_OP_CONV("__rand__", a
& b
);
1495 PYBIND11_ENUM_OP_CONV("__or__", a
| b
);
1496 PYBIND11_ENUM_OP_CONV("__ror__", a
| b
);
1497 PYBIND11_ENUM_OP_CONV("__xor__", a
^ b
);
1498 PYBIND11_ENUM_OP_CONV("__rxor__", a
^ b
);
1499 m_base
.attr("__invert__") = cpp_function(
1500 [](object arg
) { return ~(int_(arg
)); }, is_method(m_base
));
1503 PYBIND11_ENUM_OP_STRICT("__eq__", int_(a
).equal(int_(b
)), return false);
1504 PYBIND11_ENUM_OP_STRICT("__ne__", !int_(a
).equal(int_(b
)), return true);
1506 if (is_arithmetic
) {
1507 #define PYBIND11_THROW throw type_error("Expected an enumeration of matching type!");
1508 PYBIND11_ENUM_OP_STRICT("__lt__", int_(a
) < int_(b
), PYBIND11_THROW
);
1509 PYBIND11_ENUM_OP_STRICT("__gt__", int_(a
) > int_(b
), PYBIND11_THROW
);
1510 PYBIND11_ENUM_OP_STRICT("__le__", int_(a
) <= int_(b
), PYBIND11_THROW
);
1511 PYBIND11_ENUM_OP_STRICT("__ge__", int_(a
) >= int_(b
), PYBIND11_THROW
);
1512 #undef PYBIND11_THROW
1516 #undef PYBIND11_ENUM_OP_CONV_LHS
1517 #undef PYBIND11_ENUM_OP_CONV
1518 #undef PYBIND11_ENUM_OP_STRICT
1520 object getstate
= cpp_function(
1521 [](object arg
) { return int_(arg
); }, is_method(m_base
));
1523 m_base
.attr("__getstate__") = getstate
;
1524 m_base
.attr("__hash__") = getstate
;
1527 PYBIND11_NOINLINE
void value(char const* name_
, object value
, const char *doc
= nullptr) {
1528 dict entries
= m_base
.attr("__entries");
1530 if (entries
.contains(name
)) {
1531 std::string type_name
= (std::string
) str(m_base
.attr("__name__"));
1532 throw value_error(type_name
+ ": element \"" + std::string(name_
) + "\" already exists!");
1535 entries
[name
] = std::make_pair(value
, doc
);
1536 m_base
.attr(name
) = value
;
1539 PYBIND11_NOINLINE
void export_values() {
1540 dict entries
= m_base
.attr("__entries");
1541 for (const auto &kv
: entries
)
1542 m_parent
.attr(kv
.first
) = kv
.second
[int_(0)];
1549 NAMESPACE_END(detail
)
1551 /// Binds C++ enumerations and enumeration classes to Python
1552 template <typename Type
> class enum_
: public class_
<Type
> {
1554 using Base
= class_
<Type
>;
1557 using Base::def_property_readonly
;
1558 using Base::def_property_readonly_static
;
1559 using Scalar
= typename
std::underlying_type
<Type
>::type
;
1561 template <typename
... Extra
>
1562 enum_(const handle
&scope
, const char *name
, const Extra
&... extra
)
1563 : class_
<Type
>(scope
, name
, extra
...), m_base(*this, scope
) {
1564 constexpr bool is_arithmetic
= detail::any_of
<std::is_same
<arithmetic
, Extra
>...>::value
;
1565 constexpr bool is_convertible
= std::is_convertible
<Type
, Scalar
>::value
;
1566 m_base
.init(is_arithmetic
, is_convertible
);
1568 def(init([](Scalar i
) { return static_cast<Type
>(i
); }));
1569 def("__int__", [](Type value
) { return (Scalar
) value
; });
1570 #if PY_MAJOR_VERSION < 3
1571 def("__long__", [](Type value
) { return (Scalar
) value
; });
1573 #if PY_MAJOR_VERSION >= 3 && PY_MINOR_VERSION >= 8
1574 def("__index__", [](Type value
) { return (Scalar
) value
; });
1577 cpp_function
setstate(
1578 [](Type
&value
, Scalar arg
) { value
= static_cast<Type
>(arg
); },
1580 attr("__setstate__") = setstate
;
1583 /// Export enumeration entries into the parent scope
1584 enum_
& export_values() {
1585 m_base
.export_values();
1589 /// Add an enumeration entry
1590 enum_
& value(char const* name
, Type value
, const char *doc
= nullptr) {
1591 m_base
.value(name
, pybind11::cast(value
, return_value_policy::copy
), doc
);
1596 detail::enum_base m_base
;
1599 NAMESPACE_BEGIN(detail
)
1602 inline void keep_alive_impl(handle nurse
, handle patient
) {
1603 if (!nurse
|| !patient
)
1604 pybind11_fail("Could not activate keep_alive!");
1606 if (patient
.is_none() || nurse
.is_none())
1607 return; /* Nothing to keep alive or nothing to be kept alive by */
1609 auto tinfo
= all_type_info(Py_TYPE(nurse
.ptr()));
1610 if (!tinfo
.empty()) {
1611 /* It's a pybind-registered type, so we can store the patient in the
1613 add_patient(nurse
.ptr(), patient
.ptr());
1616 /* Fall back to clever approach based on weak references taken from
1617 * Boost.Python. This is not used for pybind-registered types because
1618 * the objects can be destroyed out-of-order in a GC pass. */
1619 cpp_function
disable_lifesupport(
1620 [patient
](handle weakref
) { patient
.dec_ref(); weakref
.dec_ref(); });
1622 weakref
wr(nurse
, disable_lifesupport
);
1624 patient
.inc_ref(); /* reference patient and leak the weak reference */
1625 (void) wr
.release();
1629 PYBIND11_NOINLINE
inline void keep_alive_impl(size_t Nurse
, size_t Patient
, function_call
&call
, handle ret
) {
1630 auto get_arg
= [&](size_t n
) {
1633 else if (n
== 1 && call
.init_self
)
1634 return call
.init_self
;
1635 else if (n
<= call
.args
.size())
1636 return call
.args
[n
- 1];
1640 keep_alive_impl(get_arg(Nurse
), get_arg(Patient
));
1643 inline std::pair
<decltype(internals::registered_types_py
)::iterator
, bool> all_type_info_get_cache(PyTypeObject
*type
) {
1644 auto res
= get_internals().registered_types_py
1645 #ifdef __cpp_lib_unordered_map_try_emplace
1648 .emplace(type
, std::vector
<detail::type_info
*>());
1651 // New cache entry created; set up a weak reference to automatically remove it if the type
1653 weakref((PyObject
*) type
, cpp_function([type
](handle wr
) {
1654 get_internals().registered_types_py
.erase(type
);
1662 template <typename Iterator
, typename Sentinel
, bool KeyIterator
, return_value_policy Policy
>
1663 struct iterator_state
{
1669 NAMESPACE_END(detail
)
1671 /// Makes a python iterator from a first and past-the-end C++ InputIterator.
1672 template <return_value_policy Policy
= return_value_policy::reference_internal
,
1675 typename ValueType
= decltype(*std::declval
<Iterator
>()),
1677 iterator
make_iterator(Iterator first
, Sentinel last
, Extra
&&... extra
) {
1678 typedef detail::iterator_state
<Iterator
, Sentinel
, false, Policy
> state
;
1680 if (!detail::get_type_info(typeid(state
), false)) {
1681 class_
<state
>(handle(), "iterator", pybind11::module_local())
1682 .def("__iter__", [](state
&s
) -> state
& { return s
; })
1683 .def("__next__", [](state
&s
) -> ValueType
{
1684 if (!s
.first_or_done
)
1687 s
.first_or_done
= false;
1688 if (s
.it
== s
.end
) {
1689 s
.first_or_done
= true;
1690 throw stop_iteration();
1693 }, std::forward
<Extra
>(extra
)..., Policy
);
1696 return cast(state
{first
, last
, true});
1699 /// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a
1700 /// first and past-the-end InputIterator.
1701 template <return_value_policy Policy
= return_value_policy::reference_internal
,
1704 typename KeyType
= decltype((*std::declval
<Iterator
>()).first
),
1706 iterator
make_key_iterator(Iterator first
, Sentinel last
, Extra
&&... extra
) {
1707 typedef detail::iterator_state
<Iterator
, Sentinel
, true, Policy
> state
;
1709 if (!detail::get_type_info(typeid(state
), false)) {
1710 class_
<state
>(handle(), "iterator", pybind11::module_local())
1711 .def("__iter__", [](state
&s
) -> state
& { return s
; })
1712 .def("__next__", [](state
&s
) -> KeyType
{
1713 if (!s
.first_or_done
)
1716 s
.first_or_done
= false;
1717 if (s
.it
== s
.end
) {
1718 s
.first_or_done
= true;
1719 throw stop_iteration();
1721 return (*s
.it
).first
;
1722 }, std::forward
<Extra
>(extra
)..., Policy
);
1725 return cast(state
{first
, last
, true});
1728 /// Makes an iterator over values of an stl container or other container supporting
1729 /// `std::begin()`/`std::end()`
1730 template <return_value_policy Policy
= return_value_policy::reference_internal
,
1731 typename Type
, typename
... Extra
> iterator
make_iterator(Type
&value
, Extra
&&... extra
) {
1732 return make_iterator
<Policy
>(std::begin(value
), std::end(value
), extra
...);
1735 /// Makes an iterator over the keys (`.first`) of a stl map-like container supporting
1736 /// `std::begin()`/`std::end()`
1737 template <return_value_policy Policy
= return_value_policy::reference_internal
,
1738 typename Type
, typename
... Extra
> iterator
make_key_iterator(Type
&value
, Extra
&&... extra
) {
1739 return make_key_iterator
<Policy
>(std::begin(value
), std::end(value
), extra
...);
1742 template <typename InputType
, typename OutputType
> void implicitly_convertible() {
1745 set_flag(bool &flag
) : flag(flag
) { flag
= true; }
1746 ~set_flag() { flag
= false; }
1748 auto implicit_caster
= [](PyObject
*obj
, PyTypeObject
*type
) -> PyObject
* {
1749 static bool currently_used
= false;
1750 if (currently_used
) // implicit conversions are non-reentrant
1752 set_flag
flag_helper(currently_used
);
1753 if (!detail::make_caster
<InputType
>().load(obj
, false))
1757 PyObject
*result
= PyObject_Call((PyObject
*) type
, args
.ptr(), nullptr);
1758 if (result
== nullptr)
1763 if (auto tinfo
= detail::get_type_info(typeid(OutputType
)))
1764 tinfo
->implicit_conversions
.push_back(implicit_caster
);
1766 pybind11_fail("implicitly_convertible: Unable to find type " + type_id
<OutputType
>());
1769 template <typename ExceptionTranslator
>
1770 void register_exception_translator(ExceptionTranslator
&& translator
) {
1771 detail::get_internals().registered_exception_translators
.push_front(
1772 std::forward
<ExceptionTranslator
>(translator
));
1776 * Wrapper to generate a new Python exception type.
1778 * This should only be used with PyErr_SetString for now.
1779 * It is not (yet) possible to use as a py::base.
1780 * Template type argument is reserved for future use.
1782 template <typename type
>
1783 class exception
: public object
{
1785 exception() = default;
1786 exception(handle scope
, const char *name
, PyObject
*base
= PyExc_Exception
) {
1787 std::string full_name
= scope
.attr("__name__").cast
<std::string
>() +
1788 std::string(".") + name
;
1789 m_ptr
= PyErr_NewException(const_cast<char *>(full_name
.c_str()), base
, NULL
);
1790 if (hasattr(scope
, name
))
1791 pybind11_fail("Error during initialization: multiple incompatible "
1792 "definitions with name \"" + std::string(name
) + "\"");
1793 scope
.attr(name
) = *this;
1796 // Sets the current python exception to this exception object with the given message
1797 void operator()(const char *message
) {
1798 PyErr_SetString(m_ptr
, message
);
1802 NAMESPACE_BEGIN(detail
)
1803 // Returns a reference to a function-local static exception object used in the simple
1804 // register_exception approach below. (It would be simpler to have the static local variable
1805 // directly in register_exception, but that makes clang <3.5 segfault - issue #1349).
1806 template <typename CppException
>
1807 exception
<CppException
> &get_exception_object() { static exception
<CppException
> ex
; return ex
; }
1808 NAMESPACE_END(detail
)
1811 * Registers a Python exception in `m` of the given `name` and installs an exception translator to
1812 * translate the C++ exception to the created Python exception using the exceptions what() method.
1813 * This is intended for simple exception translations; for more complex translation, register the
1814 * exception object and translator directly.
1816 template <typename CppException
>
1817 exception
<CppException
> ®ister_exception(handle scope
,
1819 PyObject
*base
= PyExc_Exception
) {
1820 auto &ex
= detail::get_exception_object
<CppException
>();
1821 if (!ex
) ex
= exception
<CppException
>(scope
, name
, base
);
1823 register_exception_translator([](std::exception_ptr p
) {
1826 std::rethrow_exception(p
);
1827 } catch (const CppException
&e
) {
1828 detail::get_exception_object
<CppException
>()(e
.what());
1834 NAMESPACE_BEGIN(detail
)
1835 PYBIND11_NOINLINE
inline void print(tuple args
, dict kwargs
) {
1836 auto strings
= tuple(args
.size());
1837 for (size_t i
= 0; i
< args
.size(); ++i
) {
1838 strings
[i
] = str(args
[i
]);
1840 auto sep
= kwargs
.contains("sep") ? kwargs
["sep"] : cast(" ");
1841 auto line
= sep
.attr("join")(strings
);
1844 if (kwargs
.contains("file")) {
1845 file
= kwargs
["file"].cast
<object
>();
1848 file
= module::import("sys").attr("stdout");
1849 } catch (const error_already_set
&) {
1850 /* If print() is called from code that is executed as
1851 part of garbage collection during interpreter shutdown,
1852 importing 'sys' can fail. Give up rather than crashing the
1853 interpreter in this case. */
1858 auto write
= file
.attr("write");
1860 write(kwargs
.contains("end") ? kwargs
["end"] : cast("\n"));
1862 if (kwargs
.contains("flush") && kwargs
["flush"].cast
<bool>())
1863 file
.attr("flush")();
1865 NAMESPACE_END(detail
)
1867 template <return_value_policy policy
= return_value_policy::automatic_reference
, typename
... Args
>
1868 void print(Args
&&...args
) {
1869 auto c
= detail::collect_arguments
<policy
>(std::forward
<Args
>(args
)...);
1870 detail::print(c
.args(), c
.kwargs());
1873 #if defined(WITH_THREAD) && !defined(PYPY_VERSION)
1875 /* The functions below essentially reproduce the PyGILState_* API using a RAII
1876 * pattern, but there are a few important differences:
1878 * 1. When acquiring the GIL from an non-main thread during the finalization
1879 * phase, the GILState API blindly terminates the calling thread, which
1880 * is often not what is wanted. This API does not do this.
1882 * 2. The gil_scoped_release function can optionally cut the relationship
1883 * of a PyThreadState and its associated thread, which allows moving it to
1884 * another thread (this is a fairly rare/advanced use case).
1886 * 3. The reference count of an acquired thread state can be controlled. This
1887 * can be handy to prevent cases where callbacks issued from an external
1888 * thread would otherwise constantly construct and destroy thread state data
1891 * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an
1892 * example which uses features 2 and 3 to migrate the Python thread of
1893 * execution to another thread (to run the event loop on the original thread,
1897 class gil_scoped_acquire
{
1899 PYBIND11_NOINLINE
gil_scoped_acquire() {
1900 auto const &internals
= detail::get_internals();
1901 tstate
= (PyThreadState
*) PYBIND11_TLS_GET_VALUE(internals
.tstate
);
1904 /* Check if the GIL was acquired using the PyGILState_* API instead (e.g. if
1905 calling from a Python thread). Since we use a different key, this ensures
1906 we don't create a new thread state and deadlock in PyEval_AcquireThread
1907 below. Note we don't save this state with internals.tstate, since we don't
1908 create it we would fail to clear it (its reference count should be > 0). */
1909 tstate
= PyGILState_GetThisThreadState();
1913 tstate
= PyThreadState_New(internals
.istate
);
1914 #if !defined(NDEBUG)
1916 pybind11_fail("scoped_acquire: could not create thread state!");
1918 tstate
->gilstate_counter
= 0;
1919 PYBIND11_TLS_REPLACE_VALUE(internals
.tstate
, tstate
);
1921 release
= detail::get_thread_state_unchecked() != tstate
;
1925 /* Work around an annoying assertion in PyThreadState_Swap */
1926 #if defined(Py_DEBUG)
1927 PyInterpreterState
*interp
= tstate
->interp
;
1928 tstate
->interp
= nullptr;
1930 PyEval_AcquireThread(tstate
);
1931 #if defined(Py_DEBUG)
1932 tstate
->interp
= interp
;
1940 ++tstate
->gilstate_counter
;
1943 PYBIND11_NOINLINE
void dec_ref() {
1944 --tstate
->gilstate_counter
;
1945 #if !defined(NDEBUG)
1946 if (detail::get_thread_state_unchecked() != tstate
)
1947 pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!");
1948 if (tstate
->gilstate_counter
< 0)
1949 pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!");
1951 if (tstate
->gilstate_counter
== 0) {
1952 #if !defined(NDEBUG)
1954 pybind11_fail("scoped_acquire::dec_ref(): internal error!");
1956 PyThreadState_Clear(tstate
);
1957 PyThreadState_DeleteCurrent();
1958 PYBIND11_TLS_DELETE_VALUE(detail::get_internals().tstate
);
1963 PYBIND11_NOINLINE
~gil_scoped_acquire() {
1966 PyEval_SaveThread();
1969 PyThreadState
*tstate
= nullptr;
1970 bool release
= true;
1973 class gil_scoped_release
{
1975 explicit gil_scoped_release(bool disassoc
= false) : disassoc(disassoc
) {
1976 // `get_internals()` must be called here unconditionally in order to initialize
1977 // `internals.tstate` for subsequent `gil_scoped_acquire` calls. Otherwise, an
1978 // initialization race could occur as multiple threads try `gil_scoped_acquire`.
1979 const auto &internals
= detail::get_internals();
1980 tstate
= PyEval_SaveThread();
1982 auto key
= internals
.tstate
;
1983 PYBIND11_TLS_DELETE_VALUE(key
);
1986 ~gil_scoped_release() {
1989 PyEval_RestoreThread(tstate
);
1991 auto key
= detail::get_internals().tstate
;
1992 PYBIND11_TLS_REPLACE_VALUE(key
, tstate
);
1996 PyThreadState
*tstate
;
1999 #elif defined(PYPY_VERSION)
2000 class gil_scoped_acquire
{
2001 PyGILState_STATE state
;
2003 gil_scoped_acquire() { state
= PyGILState_Ensure(); }
2004 ~gil_scoped_acquire() { PyGILState_Release(state
); }
2007 class gil_scoped_release
{
2008 PyThreadState
*state
;
2010 gil_scoped_release() { state
= PyEval_SaveThread(); }
2011 ~gil_scoped_release() { PyEval_RestoreThread(state
); }
2014 class gil_scoped_acquire
{ };
2015 class gil_scoped_release
{ };
2018 error_already_set::~error_already_set() {
2020 gil_scoped_acquire gil
;
2022 m_type
.release().dec_ref();
2023 m_value
.release().dec_ref();
2024 m_trace
.release().dec_ref();
2028 inline function
get_type_overload(const void *this_ptr
, const detail::type_info
*this_type
, const char *name
) {
2029 handle self
= detail::get_object_handle(this_ptr
, this_type
);
2032 handle type
= self
.get_type();
2033 auto key
= std::make_pair(type
.ptr(), name
);
2035 /* Cache functions that aren't overloaded in Python to avoid
2036 many costly Python dictionary lookups below */
2037 auto &cache
= detail::get_internals().inactive_overload_cache
;
2038 if (cache
.find(key
) != cache
.end())
2041 function overload
= getattr(self
, name
, function());
2042 if (overload
.is_cpp_function()) {
2047 /* Don't call dispatch code if invoked from overridden function.
2048 Unfortunately this doesn't work on PyPy. */
2049 #if !defined(PYPY_VERSION)
2050 PyFrameObject
*frame
= PyThreadState_Get()->frame
;
2051 if (frame
&& (std::string
) str(frame
->f_code
->co_name
) == name
&&
2052 frame
->f_code
->co_argcount
> 0) {
2053 PyFrame_FastToLocals(frame
);
2054 PyObject
*self_caller
= PyDict_GetItem(
2055 frame
->f_locals
, PyTuple_GET_ITEM(frame
->f_code
->co_varnames
, 0));
2056 if (self_caller
== self
.ptr())
2060 /* PyPy currently doesn't provide a detailed cpyext emulation of
2061 frame objects, so we have to emulate this using Python. This
2062 is going to be slow..*/
2063 dict d
; d
["self"] = self
; d
["name"] = pybind11::str(name
);
2064 PyObject
*result
= PyRun_String(
2066 "frame = inspect.currentframe()\n"
2067 "if frame is not None:\n"
2068 " frame = frame.f_back\n"
2069 " if frame is not None and str(frame.f_code.co_name) == name and "
2070 "frame.f_code.co_argcount > 0:\n"
2071 " self_caller = frame.f_locals[frame.f_code.co_varnames[0]]\n"
2072 " if self_caller == self:\n"
2074 Py_file_input
, d
.ptr(), d
.ptr());
2075 if (result
== nullptr)
2076 throw error_already_set();
2077 if (d
["self"].is_none())
2086 Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
2088 :this_ptr: The pointer to the object the overload should be retrieved for. This should be the first
2089 non-trampoline class encountered in the inheritance chain.
2090 :name: The name of the overloaded Python method to retrieve.
2091 :return: The Python method by this name from the object or an empty function wrapper.
2093 template <class T
> function
get_overload(const T
*this_ptr
, const char *name
) {
2094 auto tinfo
= detail::get_type_info(typeid(T
));
2095 return tinfo
? get_type_overload(this_ptr
, tinfo
, name
) : function();
2098 #define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) { \
2099 pybind11::gil_scoped_acquire gil; \
2100 pybind11::function overload = pybind11::get_overload(static_cast<const cname *>(this), name); \
2102 auto o = overload(__VA_ARGS__); \
2103 if (pybind11::detail::cast_is_temporary_value_reference<ret_type>::value) { \
2104 static pybind11::detail::overload_caster_t<ret_type> caster; \
2105 return pybind11::detail::cast_ref<ret_type>(std::move(o), caster); \
2107 else return pybind11::detail::cast_safe<ret_type>(std::move(o)); \
2112 Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named 'fn'
2113 from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2114 the appropriate type. See :ref:`overriding_virtuals` for more information. This macro should be used when the method
2115 name in C is not the same as the method name in Python. For example with `__str__`.
2119 std::string toString() override {
2120 PYBIND11_OVERLOAD_NAME(
2121 std::string, // Return type (ret_type)
2122 Animal, // Parent class (cname)
2123 toString, // Name of function in C++ (name)
2124 "__str__", // Name of method in Python (fn)
2128 #define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \
2129 PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2130 return cname::fn(__VA_ARGS__)
2133 Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD_NAME`, except that it
2134 throws if no overload can be found.
2136 #define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \
2137 PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \
2138 pybind11::pybind11_fail("Tried to call pure virtual function \"" PYBIND11_STRINGIFY(cname) "::" name "\"");
2141 Macro to populate the virtual method in the trampoline class. This macro tries to look up the method
2142 from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return
2143 the appropriate type. This macro should be used if the method name in C and in Python are identical.
2144 See :ref:`overriding_virtuals` for more information.
2148 class PyAnimal : public Animal {
2150 // Inherit the constructors
2151 using Animal::Animal;
2153 // Trampoline (need one for each virtual function)
2154 std::string go(int n_times) override {
2155 PYBIND11_OVERLOAD_PURE(
2156 std::string, // Return type (ret_type)
2157 Animal, // Parent class (cname)
2158 go, // Name of function in C++ (must match Python name) (fn)
2159 n_times // Argument(s) (...)
2164 #define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \
2165 PYBIND11_OVERLOAD_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2168 Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD`, except that it throws
2169 if no overload can be found.
2171 #define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \
2172 PYBIND11_OVERLOAD_PURE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__)
2174 NAMESPACE_END(PYBIND11_NAMESPACE
)
2176 #if defined(_MSC_VER) && !defined(__INTEL_COMPILER)
2177 # pragma warning(pop)
2178 #elif defined(__GNUG__) && !defined(__clang__)
2179 # pragma GCC diagnostic pop
2183 #pragma clang diagnostic pop