2 pybind11/cast.h: Partial template specializations to cast between
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.
14 #include "detail/typeid.h"
15 #include "detail/descr.h"
16 #include "detail/internals.h"
20 #include <type_traits>
22 #if defined(PYBIND11_CPP17)
23 # if defined(__has_include)
24 # if __has_include(<string_view>)
25 # define PYBIND11_HAS_STRING_VIEW
27 # elif defined(_MSC_VER)
28 # define PYBIND11_HAS_STRING_VIEW
31 #ifdef PYBIND11_HAS_STRING_VIEW
32 #include <string_view>
35 NAMESPACE_BEGIN(PYBIND11_NAMESPACE
)
36 NAMESPACE_BEGIN(detail
)
38 /// A life support system for temporary objects created by `type_caster::load()`.
39 /// Adding a patient will keep it alive up until the enclosing function returns.
40 class loader_life_support
{
42 /// A new patient frame is created when a function is entered
43 loader_life_support() {
44 get_internals().loader_patient_stack
.push_back(nullptr);
47 /// ... and destroyed after it returns
48 ~loader_life_support() {
49 auto &stack
= get_internals().loader_patient_stack
;
51 pybind11_fail("loader_life_support: internal error");
53 auto ptr
= stack
.back();
57 // A heuristic to reduce the stack's capacity (e.g. after long recursive calls)
58 if (stack
.capacity() > 16 && stack
.size() != 0 && stack
.capacity() / stack
.size() > 2)
59 stack
.shrink_to_fit();
62 /// This can only be used inside a pybind11-bound function, either by `argument_loader`
63 /// at argument preparation time or by `py::cast()` at execution time.
64 PYBIND11_NOINLINE
static void add_patient(handle h
) {
65 auto &stack
= get_internals().loader_patient_stack
;
67 throw cast_error("When called outside a bound function, py::cast() cannot "
68 "do Python -> C++ conversions which require the creation "
69 "of temporary values");
71 auto &list_ptr
= stack
.back();
72 if (list_ptr
== nullptr) {
73 list_ptr
= PyList_New(1);
75 pybind11_fail("loader_life_support: error allocating list");
76 PyList_SET_ITEM(list_ptr
, 0, h
.inc_ref().ptr());
78 auto result
= PyList_Append(list_ptr
, h
.ptr());
80 pybind11_fail("loader_life_support: error adding patient");
85 // Gets the cache entry for the given type, creating it if necessary. The return value is the pair
86 // returned by emplace, i.e. an iterator for the entry and a bool set to `true` if the entry was
88 inline std::pair
<decltype(internals::registered_types_py
)::iterator
, bool> all_type_info_get_cache(PyTypeObject
*type
);
90 // Populates a just-created cache entry.
91 PYBIND11_NOINLINE
inline void all_type_info_populate(PyTypeObject
*t
, std::vector
<type_info
*> &bases
) {
92 std::vector
<PyTypeObject
*> check
;
93 for (handle parent
: reinterpret_borrow
<tuple
>(t
->tp_bases
))
94 check
.push_back((PyTypeObject
*) parent
.ptr());
96 auto const &type_dict
= get_internals().registered_types_py
;
97 for (size_t i
= 0; i
< check
.size(); i
++) {
99 // Ignore Python2 old-style class super type:
100 if (!PyType_Check((PyObject
*) type
)) continue;
102 // Check `type` in the current set of registered python types:
103 auto it
= type_dict
.find(type
);
104 if (it
!= type_dict
.end()) {
105 // We found a cache entry for it, so it's either pybind-registered or has pre-computed
106 // pybind bases, but we have to make sure we haven't already seen the type(s) before: we
107 // want to follow Python/virtual C++ rules that there should only be one instance of a
109 for (auto *tinfo
: it
->second
) {
110 // NB: Could use a second set here, rather than doing a linear search, but since
111 // having a large number of immediate pybind11-registered types seems fairly
112 // unlikely, that probably isn't worthwhile.
114 for (auto *known
: bases
) {
115 if (known
== tinfo
) { found
= true; break; }
117 if (!found
) bases
.push_back(tinfo
);
120 else if (type
->tp_bases
) {
121 // It's some python type, so keep follow its bases classes to look for one or more
123 if (i
+ 1 == check
.size()) {
124 // When we're at the end, we can pop off the current element to avoid growing
125 // `check` when adding just one base (which is typical--i.e. when there is no
126 // multiple inheritance)
130 for (handle parent
: reinterpret_borrow
<tuple
>(type
->tp_bases
))
131 check
.push_back((PyTypeObject
*) parent
.ptr());
137 * Extracts vector of type_info pointers of pybind-registered roots of the given Python type. Will
138 * be just 1 pybind type for the Python type of a pybind-registered class, or for any Python-side
139 * derived class that uses single inheritance. Will contain as many types as required for a Python
140 * class that uses multiple inheritance to inherit (directly or indirectly) from multiple
141 * pybind-registered classes. Will be empty if neither the type nor any base classes are
144 * The value is cached for the lifetime of the Python type.
146 inline const std::vector
<detail::type_info
*> &all_type_info(PyTypeObject
*type
) {
147 auto ins
= all_type_info_get_cache(type
);
149 // New cache entry: populate it
150 all_type_info_populate(type
, ins
.first
->second
);
152 return ins
.first
->second
;
156 * Gets a single pybind11 type info for a python type. Returns nullptr if neither the type nor any
157 * ancestors are pybind11-registered. Throws an exception if there are multiple bases--use
158 * `all_type_info` instead if you want to support multiple bases.
160 PYBIND11_NOINLINE
inline detail::type_info
* get_type_info(PyTypeObject
*type
) {
161 auto &bases
= all_type_info(type
);
162 if (bases
.size() == 0)
164 if (bases
.size() > 1)
165 pybind11_fail("pybind11::detail::get_type_info: type has multiple pybind11-registered bases");
166 return bases
.front();
169 inline detail::type_info
*get_local_type_info(const std::type_index
&tp
) {
170 auto &locals
= registered_local_types_cpp();
171 auto it
= locals
.find(tp
);
172 if (it
!= locals
.end())
177 inline detail::type_info
*get_global_type_info(const std::type_index
&tp
) {
178 auto &types
= get_internals().registered_types_cpp
;
179 auto it
= types
.find(tp
);
180 if (it
!= types
.end())
185 /// Return the type info for a given C++ type; on lookup failure can either throw or return nullptr.
186 PYBIND11_NOINLINE
inline detail::type_info
*get_type_info(const std::type_index
&tp
,
187 bool throw_if_missing
= false) {
188 if (auto ltype
= get_local_type_info(tp
))
190 if (auto gtype
= get_global_type_info(tp
))
193 if (throw_if_missing
) {
194 std::string tname
= tp
.name();
195 detail::clean_type_id(tname
);
196 pybind11_fail("pybind11::detail::get_type_info: unable to find type info for \"" + tname
+ "\"");
201 PYBIND11_NOINLINE
inline handle
get_type_handle(const std::type_info
&tp
, bool throw_if_missing
) {
202 detail::type_info
*type_info
= get_type_info(tp
, throw_if_missing
);
203 return handle(type_info
? ((PyObject
*) type_info
->type
) : nullptr);
206 struct value_and_holder
{
207 instance
*inst
= nullptr;
209 const detail::type_info
*type
= nullptr;
212 // Main constructor for a found value/holder:
213 value_and_holder(instance
*i
, const detail::type_info
*type
, size_t vpos
, size_t index
) :
214 inst
{i
}, index
{index
}, type
{type
},
215 vh
{inst
->simple_layout
? inst
->simple_value_holder
: &inst
->nonsimple
.values_and_holders
[vpos
]}
218 // Default constructor (used to signal a value-and-holder not found by get_value_and_holder())
219 value_and_holder() {}
221 // Used for past-the-end iterator
222 value_and_holder(size_t index
) : index
{index
} {}
224 template <typename V
= void> V
*&value_ptr() const {
225 return reinterpret_cast<V
*&>(vh
[0]);
227 // True if this `value_and_holder` has a non-null value pointer
228 explicit operator bool() const { return value_ptr(); }
230 template <typename H
> H
&holder() const {
231 return reinterpret_cast<H
&>(vh
[1]);
233 bool holder_constructed() const {
234 return inst
->simple_layout
235 ? inst
->simple_holder_constructed
236 : inst
->nonsimple
.status
[index
] & instance::status_holder_constructed
;
238 void set_holder_constructed(bool v
= true) {
239 if (inst
->simple_layout
)
240 inst
->simple_holder_constructed
= v
;
242 inst
->nonsimple
.status
[index
] |= instance::status_holder_constructed
;
244 inst
->nonsimple
.status
[index
] &= (uint8_t) ~instance::status_holder_constructed
;
246 bool instance_registered() const {
247 return inst
->simple_layout
248 ? inst
->simple_instance_registered
249 : inst
->nonsimple
.status
[index
] & instance::status_instance_registered
;
251 void set_instance_registered(bool v
= true) {
252 if (inst
->simple_layout
)
253 inst
->simple_instance_registered
= v
;
255 inst
->nonsimple
.status
[index
] |= instance::status_instance_registered
;
257 inst
->nonsimple
.status
[index
] &= (uint8_t) ~instance::status_instance_registered
;
261 // Container for accessing and iterating over an instance's values/holders
262 struct values_and_holders
{
265 using type_vec
= std::vector
<detail::type_info
*>;
266 const type_vec
&tinfo
;
269 values_and_holders(instance
*inst
) : inst
{inst
}, tinfo(all_type_info(Py_TYPE(inst
))) {}
273 instance
*inst
= nullptr;
274 const type_vec
*types
= nullptr;
275 value_and_holder curr
;
276 friend struct values_and_holders
;
277 iterator(instance
*inst
, const type_vec
*tinfo
)
278 : inst
{inst
}, types
{tinfo
},
279 curr(inst
/* instance */,
280 types
->empty() ? nullptr : (*types
)[0] /* type info */,
281 0, /* vpos: (non-simple types only): the first vptr comes first */
284 // Past-the-end iterator:
285 iterator(size_t end
) : curr(end
) {}
287 bool operator==(const iterator
&other
) { return curr
.index
== other
.curr
.index
; }
288 bool operator!=(const iterator
&other
) { return curr
.index
!= other
.curr
.index
; }
289 iterator
&operator++() {
290 if (!inst
->simple_layout
)
291 curr
.vh
+= 1 + (*types
)[curr
.index
]->holder_size_in_ptrs
;
293 curr
.type
= curr
.index
< types
->size() ? (*types
)[curr
.index
] : nullptr;
296 value_and_holder
&operator*() { return curr
; }
297 value_and_holder
*operator->() { return &curr
; }
300 iterator
begin() { return iterator(inst
, &tinfo
); }
301 iterator
end() { return iterator(tinfo
.size()); }
303 iterator
find(const type_info
*find_type
) {
304 auto it
= begin(), endit
= end();
305 while (it
!= endit
&& it
->type
!= find_type
) ++it
;
309 size_t size() { return tinfo
.size(); }
313 * Extracts C++ value and holder pointer references from an instance (which may contain multiple
314 * values/holders for python-side multiple inheritance) that match the given type. Throws an error
315 * if the given type (or ValueType, if omitted) is not a pybind11 base of the given instance. If
316 * `find_type` is omitted (or explicitly specified as nullptr) the first value/holder are returned,
317 * regardless of type (and the resulting .type will be nullptr).
319 * The returned object should be short-lived: in particular, it must not outlive the called-upon
322 PYBIND11_NOINLINE
inline value_and_holder
instance::get_value_and_holder(const type_info
*find_type
/*= nullptr default in common.h*/, bool throw_if_missing
/*= true in common.h*/) {
323 // Optimize common case:
324 if (!find_type
|| Py_TYPE(this) == find_type
->type
)
325 return value_and_holder(this, find_type
, 0, 0);
327 detail::values_and_holders
vhs(this);
328 auto it
= vhs
.find(find_type
);
332 if (!throw_if_missing
)
333 return value_and_holder();
336 pybind11_fail("pybind11::detail::instance::get_value_and_holder: "
337 "type is not a pybind11 base of the given instance "
338 "(compile in debug mode for type details)");
340 pybind11_fail("pybind11::detail::instance::get_value_and_holder: `" +
341 std::string(find_type
->type
->tp_name
) + "' is not a pybind11 base of the given `" +
342 std::string(Py_TYPE(this)->tp_name
) + "' instance");
346 PYBIND11_NOINLINE
inline void instance::allocate_layout() {
347 auto &tinfo
= all_type_info(Py_TYPE(this));
349 const size_t n_types
= tinfo
.size();
352 pybind11_fail("instance allocation failed: new instance has no pybind11-registered base types");
355 n_types
== 1 && tinfo
.front()->holder_size_in_ptrs
<= instance_simple_holder_in_ptrs();
357 // Simple path: no python-side multiple inheritance, and a small-enough holder
359 simple_value_holder
[0] = nullptr;
360 simple_holder_constructed
= false;
361 simple_instance_registered
= false;
363 else { // multiple base types or a too-large holder
364 // Allocate space to hold: [v1*][h1][v2*][h2]...[bb...] where [vN*] is a value pointer,
365 // [hN] is the (uninitialized) holder instance for value N, and [bb...] is a set of bool
366 // values that tracks whether each associated holder has been initialized. Each [block] is
367 // padded, if necessary, to an integer multiple of sizeof(void *).
369 for (auto t
: tinfo
) {
370 space
+= 1; // value pointer
371 space
+= t
->holder_size_in_ptrs
; // holder instance
373 size_t flags_at
= space
;
374 space
+= size_in_ptrs(n_types
); // status bytes (holder_constructed and instance_registered)
376 // Allocate space for flags, values, and holders, and initialize it to 0 (flags and values,
377 // in particular, need to be 0). Use Python's memory allocation functions: in Python 3.6
378 // they default to using pymalloc, which is designed to be efficient for small allocations
379 // like the one we're doing here; in earlier versions (and for larger allocations) they are
380 // just wrappers around malloc.
381 #if PY_VERSION_HEX >= 0x03050000
382 nonsimple
.values_and_holders
= (void **) PyMem_Calloc(space
, sizeof(void *));
383 if (!nonsimple
.values_and_holders
) throw std::bad_alloc();
385 nonsimple
.values_and_holders
= (void **) PyMem_New(void *, space
);
386 if (!nonsimple
.values_and_holders
) throw std::bad_alloc();
387 std::memset(nonsimple
.values_and_holders
, 0, space
* sizeof(void *));
389 nonsimple
.status
= reinterpret_cast<uint8_t *>(&nonsimple
.values_and_holders
[flags_at
]);
394 PYBIND11_NOINLINE
inline void instance::deallocate_layout() {
396 PyMem_Free(nonsimple
.values_and_holders
);
399 PYBIND11_NOINLINE
inline bool isinstance_generic(handle obj
, const std::type_info
&tp
) {
400 handle type
= detail::get_type_handle(tp
, false);
403 return isinstance(obj
, type
);
406 PYBIND11_NOINLINE
inline std::string
error_string() {
407 if (!PyErr_Occurred()) {
408 PyErr_SetString(PyExc_RuntimeError
, "Unknown internal error occurred");
409 return "Unknown internal error occurred";
412 error_scope scope
; // Preserve error state
414 std::string errorString
;
416 errorString
+= handle(scope
.type
).attr("__name__").cast
<std::string
>();
420 errorString
+= (std::string
) str(scope
.value
);
422 PyErr_NormalizeException(&scope
.type
, &scope
.value
, &scope
.trace
);
424 #if PY_MAJOR_VERSION >= 3
425 if (scope
.trace
!= nullptr)
426 PyException_SetTraceback(scope
.value
, scope
.trace
);
429 #if !defined(PYPY_VERSION)
431 PyTracebackObject
*trace
= (PyTracebackObject
*) scope
.trace
;
433 /* Get the deepest trace possible */
434 while (trace
->tb_next
)
435 trace
= trace
->tb_next
;
437 PyFrameObject
*frame
= trace
->tb_frame
;
438 errorString
+= "\n\nAt:\n";
440 int lineno
= PyFrame_GetLineNumber(frame
);
442 " " + handle(frame
->f_code
->co_filename
).cast
<std::string
>() +
443 "(" + std::to_string(lineno
) + "): " +
444 handle(frame
->f_code
->co_name
).cast
<std::string
>() + "\n";
445 frame
= frame
->f_back
;
453 PYBIND11_NOINLINE
inline handle
get_object_handle(const void *ptr
, const detail::type_info
*type
) {
454 auto &instances
= get_internals().registered_instances
;
455 auto range
= instances
.equal_range(ptr
);
456 for (auto it
= range
.first
; it
!= range
.second
; ++it
) {
457 for (auto vh
: values_and_holders(it
->second
)) {
459 return handle((PyObject
*) it
->second
);
465 inline PyThreadState
*get_thread_state_unchecked() {
466 #if defined(PYPY_VERSION)
467 return PyThreadState_GET();
468 #elif PY_VERSION_HEX < 0x03000000
469 return _PyThreadState_Current
;
470 #elif PY_VERSION_HEX < 0x03050000
471 return (PyThreadState
*) _Py_atomic_load_relaxed(&_PyThreadState_Current
);
472 #elif PY_VERSION_HEX < 0x03050200
473 return (PyThreadState
*) _PyThreadState_Current
.value
;
475 return _PyThreadState_UncheckedGet();
479 // Forward declarations
480 inline void keep_alive_impl(handle nurse
, handle patient
);
481 inline PyObject
*make_new_instance(PyTypeObject
*type
);
483 class type_caster_generic
{
485 PYBIND11_NOINLINE
type_caster_generic(const std::type_info
&type_info
)
486 : typeinfo(get_type_info(type_info
)), cpptype(&type_info
) { }
488 type_caster_generic(const type_info
*typeinfo
)
489 : typeinfo(typeinfo
), cpptype(typeinfo
? typeinfo
->cpptype
: nullptr) { }
491 bool load(handle src
, bool convert
) {
492 return load_impl
<type_caster_generic
>(src
, convert
);
495 PYBIND11_NOINLINE
static handle
cast(const void *_src
, return_value_policy policy
, handle parent
,
496 const detail::type_info
*tinfo
,
497 void *(*copy_constructor
)(const void *),
498 void *(*move_constructor
)(const void *),
499 const void *existing_holder
= nullptr) {
500 if (!tinfo
) // no type info: error will be set already
503 void *src
= const_cast<void *>(_src
);
505 return none().release();
507 auto it_instances
= get_internals().registered_instances
.equal_range(src
);
508 for (auto it_i
= it_instances
.first
; it_i
!= it_instances
.second
; ++it_i
) {
509 for (auto instance_type
: detail::all_type_info(Py_TYPE(it_i
->second
))) {
510 if (instance_type
&& same_type(*instance_type
->cpptype
, *tinfo
->cpptype
))
511 return handle((PyObject
*) it_i
->second
).inc_ref();
515 auto inst
= reinterpret_steal
<object
>(make_new_instance(tinfo
->type
));
516 auto wrapper
= reinterpret_cast<instance
*>(inst
.ptr());
517 wrapper
->owned
= false;
518 void *&valueptr
= values_and_holders(wrapper
).begin()->value_ptr();
521 case return_value_policy::automatic
:
522 case return_value_policy::take_ownership
:
524 wrapper
->owned
= true;
527 case return_value_policy::automatic_reference
:
528 case return_value_policy::reference
:
530 wrapper
->owned
= false;
533 case return_value_policy::copy
:
534 if (copy_constructor
)
535 valueptr
= copy_constructor(src
);
537 throw cast_error("return_value_policy = copy, but the "
538 "object is non-copyable!");
539 wrapper
->owned
= true;
542 case return_value_policy::move
:
543 if (move_constructor
)
544 valueptr
= move_constructor(src
);
545 else if (copy_constructor
)
546 valueptr
= copy_constructor(src
);
548 throw cast_error("return_value_policy = move, but the "
549 "object is neither movable nor copyable!");
550 wrapper
->owned
= true;
553 case return_value_policy::reference_internal
:
555 wrapper
->owned
= false;
556 keep_alive_impl(inst
, parent
);
560 throw cast_error("unhandled return_value_policy: should not happen!");
563 tinfo
->init_instance(wrapper
, existing_holder
);
565 return inst
.release();
568 // Base methods for generic caster; there are overridden in copyable_holder_caster
569 void load_value(value_and_holder
&&v_h
) {
570 auto *&vptr
= v_h
.value_ptr();
571 // Lazy allocation for unallocated values:
572 if (vptr
== nullptr) {
573 auto *type
= v_h
.type
? v_h
.type
: typeinfo
;
574 if (type
->operator_new
) {
575 vptr
= type
->operator_new(type
->type_size
);
577 #if defined(PYBIND11_CPP17)
578 if (type
->type_align
> __STDCPP_DEFAULT_NEW_ALIGNMENT__
)
579 vptr
= ::operator new(type
->type_size
,
580 (std::align_val_t
) type
->type_align
);
583 vptr
= ::operator new(type
->type_size
);
588 bool try_implicit_casts(handle src
, bool convert
) {
589 for (auto &cast
: typeinfo
->implicit_casts
) {
590 type_caster_generic
sub_caster(*cast
.first
);
591 if (sub_caster
.load(src
, convert
)) {
592 value
= cast
.second(sub_caster
.value
);
598 bool try_direct_conversions(handle src
) {
599 for (auto &converter
: *typeinfo
->direct_conversions
) {
600 if (converter(src
.ptr(), value
))
605 void check_holder_compat() {}
607 PYBIND11_NOINLINE
static void *local_load(PyObject
*src
, const type_info
*ti
) {
608 auto caster
= type_caster_generic(ti
);
609 if (caster
.load(src
, false))
614 /// Try to load with foreign typeinfo, if available. Used when there is no
615 /// native typeinfo, or when the native one wasn't able to produce a value.
616 PYBIND11_NOINLINE
bool try_load_foreign_module_local(handle src
) {
617 constexpr auto *local_key
= PYBIND11_MODULE_LOCAL_ID
;
618 const auto pytype
= src
.get_type();
619 if (!hasattr(pytype
, local_key
))
622 type_info
*foreign_typeinfo
= reinterpret_borrow
<capsule
>(getattr(pytype
, local_key
));
623 // Only consider this foreign loader if actually foreign and is a loader of the correct cpp type
624 if (foreign_typeinfo
->module_local_load
== &local_load
625 || (cpptype
&& !same_type(*cpptype
, *foreign_typeinfo
->cpptype
)))
628 if (auto result
= foreign_typeinfo
->module_local_load(src
.ptr(), foreign_typeinfo
)) {
635 // Implementation of `load`; this takes the type of `this` so that it can dispatch the relevant
636 // bits of code between here and copyable_holder_caster where the two classes need different
637 // logic (without having to resort to virtual inheritance).
638 template <typename ThisT
>
639 PYBIND11_NOINLINE
bool load_impl(handle src
, bool convert
) {
640 if (!src
) return false;
641 if (!typeinfo
) return try_load_foreign_module_local(src
);
643 // Defer accepting None to other overloads (if we aren't in convert mode):
644 if (!convert
) return false;
649 auto &this_
= static_cast<ThisT
&>(*this);
650 this_
.check_holder_compat();
652 PyTypeObject
*srctype
= Py_TYPE(src
.ptr());
654 // Case 1: If src is an exact type match for the target type then we can reinterpret_cast
655 // the instance's value pointer to the target type:
656 if (srctype
== typeinfo
->type
) {
657 this_
.load_value(reinterpret_cast<instance
*>(src
.ptr())->get_value_and_holder());
660 // Case 2: We have a derived class
661 else if (PyType_IsSubtype(srctype
, typeinfo
->type
)) {
662 auto &bases
= all_type_info(srctype
);
663 bool no_cpp_mi
= typeinfo
->simple_type
;
665 // Case 2a: the python type is a Python-inherited derived class that inherits from just
666 // one simple (no MI) pybind11 class, or is an exact match, so the C++ instance is of
667 // the right type and we can use reinterpret_cast.
668 // (This is essentially the same as case 2b, but because not using multiple inheritance
669 // is extremely common, we handle it specially to avoid the loop iterator and type
670 // pointer lookup overhead)
671 if (bases
.size() == 1 && (no_cpp_mi
|| bases
.front()->type
== typeinfo
->type
)) {
672 this_
.load_value(reinterpret_cast<instance
*>(src
.ptr())->get_value_and_holder());
675 // Case 2b: the python type inherits from multiple C++ bases. Check the bases to see if
676 // we can find an exact match (or, for a simple C++ type, an inherited match); if so, we
677 // can safely reinterpret_cast to the relevant pointer.
678 else if (bases
.size() > 1) {
679 for (auto base
: bases
) {
680 if (no_cpp_mi
? PyType_IsSubtype(base
->type
, typeinfo
->type
) : base
->type
== typeinfo
->type
) {
681 this_
.load_value(reinterpret_cast<instance
*>(src
.ptr())->get_value_and_holder(base
));
687 // Case 2c: C++ multiple inheritance is involved and we couldn't find an exact type match
688 // in the registered bases, above, so try implicit casting (needed for proper C++ casting
689 // when MI is involved).
690 if (this_
.try_implicit_casts(src
, convert
))
694 // Perform an implicit conversion
696 for (auto &converter
: typeinfo
->implicit_conversions
) {
697 auto temp
= reinterpret_steal
<object
>(converter(src
.ptr(), typeinfo
->type
));
698 if (load_impl
<ThisT
>(temp
, false)) {
699 loader_life_support::add_patient(temp
);
703 if (this_
.try_direct_conversions(src
))
707 // Failed to match local typeinfo. Try again with global.
708 if (typeinfo
->module_local
) {
709 if (auto gtype
= get_global_type_info(*typeinfo
->cpptype
)) {
711 return load(src
, false);
715 // Global typeinfo has precedence over foreign module_local
716 return try_load_foreign_module_local(src
);
720 // Called to do type lookup and wrap the pointer and type in a pair when a dynamic_cast
721 // isn't needed or can't be used. If the type is unknown, sets the error and returns a pair
722 // with .second = nullptr. (p.first = nullptr is not an error: it becomes None).
723 PYBIND11_NOINLINE
static std::pair
<const void *, const type_info
*> src_and_type(
724 const void *src
, const std::type_info
&cast_type
, const std::type_info
*rtti_type
= nullptr) {
725 if (auto *tpi
= get_type_info(cast_type
))
726 return {src
, const_cast<const type_info
*>(tpi
)};
728 // Not found, set error:
729 std::string tname
= rtti_type
? rtti_type
->name() : cast_type
.name();
730 detail::clean_type_id(tname
);
731 std::string msg
= "Unregistered type : " + tname
;
732 PyErr_SetString(PyExc_TypeError
, msg
.c_str());
733 return {nullptr, nullptr};
736 const type_info
*typeinfo
= nullptr;
737 const std::type_info
*cpptype
= nullptr;
738 void *value
= nullptr;
742 * Determine suitable casting operator for pointer-or-lvalue-casting type casters. The type caster
743 * needs to provide `operator T*()` and `operator T&()` operators.
745 * If the type supports moving the value away via an `operator T&&() &&` method, it should use
746 * `movable_cast_op_type` instead.
748 template <typename T
>
750 conditional_t
<std::is_pointer
<remove_reference_t
<T
>>::value
,
751 typename
std::add_pointer
<intrinsic_t
<T
>>::type
,
752 typename
std::add_lvalue_reference
<intrinsic_t
<T
>>::type
>;
755 * Determine suitable casting operator for a type caster with a movable value. Such a type caster
756 * needs to provide `operator T*()`, `operator T&()`, and `operator T&&() &&`. The latter will be
757 * called in appropriate contexts where the value can be moved rather than copied.
759 * These operator are automatically provided when using the PYBIND11_TYPE_CASTER macro.
761 template <typename T
>
762 using movable_cast_op_type
=
763 conditional_t
<std::is_pointer
<typename
std::remove_reference
<T
>::type
>::value
,
764 typename
std::add_pointer
<intrinsic_t
<T
>>::type
,
765 conditional_t
<std::is_rvalue_reference
<T
>::value
,
766 typename
std::add_rvalue_reference
<intrinsic_t
<T
>>::type
,
767 typename
std::add_lvalue_reference
<intrinsic_t
<T
>>::type
>>;
769 // std::is_copy_constructible isn't quite enough: it lets std::vector<T> (and similar) through when
770 // T is non-copyable, but code containing such a copy constructor fails to actually compile.
771 template <typename T
, typename SFINAE
= void> struct is_copy_constructible
: std::is_copy_constructible
<T
> {};
773 // Specialization for types that appear to be copy constructible but also look like stl containers
774 // (we specifically check for: has `value_type` and `reference` with `reference = value_type&`): if
775 // so, copy constructability depends on whether the value_type is copy constructible.
776 template <typename Container
> struct is_copy_constructible
<Container
, enable_if_t
<all_of
<
777 std::is_copy_constructible
<Container
>,
778 std::is_same
<typename
Container::value_type
&, typename
Container::reference
>,
779 // Avoid infinite recursion
780 negation
<std::is_same
<Container
, typename
Container::value_type
>>
781 >::value
>> : is_copy_constructible
<typename
Container::value_type
> {};
783 #if !defined(PYBIND11_CPP17)
784 // Likewise for std::pair before C++17 (which mandates that the copy constructor not exist when the
785 // two types aren't themselves copy constructible).
786 template <typename T1
, typename T2
> struct is_copy_constructible
<std::pair
<T1
, T2
>>
787 : all_of
<is_copy_constructible
<T1
>, is_copy_constructible
<T2
>> {};
790 NAMESPACE_END(detail
)
792 // polymorphic_type_hook<itype>::get(src, tinfo) determines whether the object pointed
793 // to by `src` actually is an instance of some class derived from `itype`.
794 // If so, it sets `tinfo` to point to the std::type_info representing that derived
795 // type, and returns a pointer to the start of the most-derived object of that type
796 // (in which `src` is a subobject; this will be the same address as `src` in most
797 // single inheritance cases). If not, or if `src` is nullptr, it simply returns `src`
798 // and leaves `tinfo` at its default value of nullptr.
800 // The default polymorphic_type_hook just returns src. A specialization for polymorphic
801 // types determines the runtime type of the passed object and adjusts the this-pointer
802 // appropriately via dynamic_cast<void*>. This is what enables a C++ Animal* to appear
803 // to Python as a Dog (if Dog inherits from Animal, Animal is polymorphic, Dog is
804 // registered with pybind11, and this Animal is in fact a Dog).
806 // You may specialize polymorphic_type_hook yourself for types that want to appear
807 // polymorphic to Python but do not use C++ RTTI. (This is a not uncommon pattern
808 // in performance-sensitive applications, used most notably in LLVM.)
809 template <typename itype
, typename SFINAE
= void>
810 struct polymorphic_type_hook
812 static const void *get(const itype
*src
, const std::type_info
*&) { return src
; }
814 template <typename itype
>
815 struct polymorphic_type_hook
<itype
, detail::enable_if_t
<std::is_polymorphic
<itype
>::value
>>
817 static const void *get(const itype
*src
, const std::type_info
*& type
) {
818 type
= src
? &typeid(*src
) : nullptr;
819 return dynamic_cast<const void*>(src
);
823 NAMESPACE_BEGIN(detail
)
825 /// Generic type caster for objects stored on the heap
826 template <typename type
> class type_caster_base
: public type_caster_generic
{
827 using itype
= intrinsic_t
<type
>;
830 static constexpr auto name
= _
<type
>();
832 type_caster_base() : type_caster_base(typeid(type
)) { }
833 explicit type_caster_base(const std::type_info
&info
) : type_caster_generic(info
) { }
835 static handle
cast(const itype
&src
, return_value_policy policy
, handle parent
) {
836 if (policy
== return_value_policy::automatic
|| policy
== return_value_policy::automatic_reference
)
837 policy
= return_value_policy::copy
;
838 return cast(&src
, policy
, parent
);
841 static handle
cast(itype
&&src
, return_value_policy
, handle parent
) {
842 return cast(&src
, return_value_policy::move
, parent
);
845 // Returns a (pointer, type_info) pair taking care of necessary type lookup for a
846 // polymorphic type (using RTTI by default, but can be overridden by specializing
847 // polymorphic_type_hook). If the instance isn't derived, returns the base version.
848 static std::pair
<const void *, const type_info
*> src_and_type(const itype
*src
) {
849 auto &cast_type
= typeid(itype
);
850 const std::type_info
*instance_type
= nullptr;
851 const void *vsrc
= polymorphic_type_hook
<itype
>::get(src
, instance_type
);
852 if (instance_type
&& !same_type(cast_type
, *instance_type
)) {
853 // This is a base pointer to a derived type. If the derived type is registered
854 // with pybind11, we want to make the full derived object available.
855 // In the typical case where itype is polymorphic, we get the correct
856 // derived pointer (which may be != base pointer) by a dynamic_cast to
857 // most derived type. If itype is not polymorphic, we won't get here
858 // except via a user-provided specialization of polymorphic_type_hook,
859 // and the user has promised that no this-pointer adjustment is
860 // required in that case, so it's OK to use static_cast.
861 if (const auto *tpi
= get_type_info(*instance_type
))
864 // Otherwise we have either a nullptr, an `itype` pointer, or an unknown derived pointer, so
866 return type_caster_generic::src_and_type(src
, cast_type
, instance_type
);
869 static handle
cast(const itype
*src
, return_value_policy policy
, handle parent
) {
870 auto st
= src_and_type(src
);
871 return type_caster_generic::cast(
872 st
.first
, policy
, parent
, st
.second
,
873 make_copy_constructor(src
), make_move_constructor(src
));
876 static handle
cast_holder(const itype
*src
, const void *holder
) {
877 auto st
= src_and_type(src
);
878 return type_caster_generic::cast(
879 st
.first
, return_value_policy::take_ownership
, {}, st
.second
,
880 nullptr, nullptr, holder
);
883 template <typename T
> using cast_op_type
= detail::cast_op_type
<T
>;
885 operator itype
*() { return (type
*) value
; }
886 operator itype
&() { if (!value
) throw reference_cast_error(); return *((itype
*) value
); }
889 using Constructor
= void *(*)(const void *);
891 /* Only enabled when the types are {copy,move}-constructible *and* when the type
892 does not have a private operator new implementation. */
893 template <typename T
, typename
= enable_if_t
<is_copy_constructible
<T
>::value
>>
894 static auto make_copy_constructor(const T
*x
) -> decltype(new T(*x
), Constructor
{}) {
895 return [](const void *arg
) -> void * {
896 return new T(*reinterpret_cast<const T
*>(arg
));
900 template <typename T
, typename
= enable_if_t
<std::is_move_constructible
<T
>::value
>>
901 static auto make_move_constructor(const T
*x
) -> decltype(new T(std::move(*const_cast<T
*>(x
))), Constructor
{}) {
902 return [](const void *arg
) -> void * {
903 return new T(std::move(*const_cast<T
*>(reinterpret_cast<const T
*>(arg
))));
907 static Constructor
make_copy_constructor(...) { return nullptr; }
908 static Constructor
make_move_constructor(...) { return nullptr; }
911 template <typename type
, typename SFINAE
= void> class type_caster
: public type_caster_base
<type
> { };
912 template <typename type
> using make_caster
= type_caster
<intrinsic_t
<type
>>;
914 // Shortcut for calling a caster's `cast_op_type` cast operator for casting a type_caster to a T
915 template <typename T
> typename make_caster
<T
>::template cast_op_type
<T
> cast_op(make_caster
<T
> &caster
) {
916 return caster
.operator typename make_caster
<T
>::template cast_op_type
<T
>();
918 template <typename T
> typename make_caster
<T
>::template cast_op_type
<typename
std::add_rvalue_reference
<T
>::type
>
919 cast_op(make_caster
<T
> &&caster
) {
920 return std::move(caster
).operator
921 typename make_caster
<T
>::template cast_op_type
<typename
std::add_rvalue_reference
<T
>::type
>();
924 template <typename type
> class type_caster
<std::reference_wrapper
<type
>> {
926 using caster_t
= make_caster
<type
>;
928 using subcaster_cast_op_type
= typename
caster_t::template cast_op_type
<type
>;
929 static_assert(std::is_same
<typename
std::remove_const
<type
>::type
&, subcaster_cast_op_type
>::value
,
930 "std::reference_wrapper<T> caster requires T to have a caster with an `T &` operator");
932 bool load(handle src
, bool convert
) { return subcaster
.load(src
, convert
); }
933 static constexpr auto name
= caster_t::name
;
934 static handle
cast(const std::reference_wrapper
<type
> &src
, return_value_policy policy
, handle parent
) {
935 // It is definitely wrong to take ownership of this pointer, so mask that rvp
936 if (policy
== return_value_policy::take_ownership
|| policy
== return_value_policy::automatic
)
937 policy
= return_value_policy::automatic_reference
;
938 return caster_t::cast(&src
.get(), policy
, parent
);
940 template <typename T
> using cast_op_type
= std::reference_wrapper
<type
>;
941 operator std::reference_wrapper
<type
>() { return subcaster
.operator subcaster_cast_op_type
&(); }
944 #define PYBIND11_TYPE_CASTER(type, py_name) \
948 static constexpr auto name = py_name; \
949 template <typename T_, enable_if_t<std::is_same<type, remove_cv_t<T_>>::value, int> = 0> \
950 static handle cast(T_ *src, return_value_policy policy, handle parent) { \
951 if (!src) return none().release(); \
952 if (policy == return_value_policy::take_ownership) { \
953 auto h = cast(std::move(*src), policy, parent); delete src; return h; \
955 return cast(*src, policy, parent); \
958 operator type*() { return &value; } \
959 operator type&() { return value; } \
960 operator type&&() && { return std::move(value); } \
961 template <typename T_> using cast_op_type = pybind11::detail::movable_cast_op_type<T_>
964 template <typename CharT
> using is_std_char_type
= any_of
<
965 std::is_same
<CharT
, char>, /* std::string */
966 std::is_same
<CharT
, char16_t
>, /* std::u16string */
967 std::is_same
<CharT
, char32_t
>, /* std::u32string */
968 std::is_same
<CharT
, wchar_t> /* std::wstring */
971 template <typename T
>
972 struct type_caster
<T
, enable_if_t
<std::is_arithmetic
<T
>::value
&& !is_std_char_type
<T
>::value
>> {
973 using _py_type_0
= conditional_t
<sizeof(T
) <= sizeof(long), long, long long>;
974 using _py_type_1
= conditional_t
<std::is_signed
<T
>::value
, _py_type_0
, typename
std::make_unsigned
<_py_type_0
>::type
>;
975 using py_type
= conditional_t
<std::is_floating_point
<T
>::value
, double, _py_type_1
>;
978 bool load(handle src
, bool convert
) {
984 if (std::is_floating_point
<T
>::value
) {
985 if (convert
|| PyFloat_Check(src
.ptr()))
986 py_value
= (py_type
) PyFloat_AsDouble(src
.ptr());
989 } else if (PyFloat_Check(src
.ptr())) {
991 } else if (std::is_unsigned
<py_type
>::value
) {
992 py_value
= as_unsigned
<py_type
>(src
.ptr());
993 } else { // signed integer:
994 py_value
= sizeof(T
) <= sizeof(long)
995 ? (py_type
) PyLong_AsLong(src
.ptr())
996 : (py_type
) PYBIND11_LONG_AS_LONGLONG(src
.ptr());
999 bool py_err
= py_value
== (py_type
) -1 && PyErr_Occurred();
1001 // Protect std::numeric_limits::min/max with parentheses
1002 if (py_err
|| (std::is_integral
<T
>::value
&& sizeof(py_type
) != sizeof(T
) &&
1003 (py_value
< (py_type
) (std::numeric_limits
<T
>::min
)() ||
1004 py_value
> (py_type
) (std::numeric_limits
<T
>::max
)()))) {
1005 bool type_error
= py_err
&& PyErr_ExceptionMatches(
1006 #if PY_VERSION_HEX < 0x03000000 && !defined(PYPY_VERSION)
1013 if (type_error
&& convert
&& PyNumber_Check(src
.ptr())) {
1014 auto tmp
= reinterpret_steal
<object
>(std::is_floating_point
<T
>::value
1015 ? PyNumber_Float(src
.ptr())
1016 : PyNumber_Long(src
.ptr()));
1018 return load(tmp
, false);
1023 value
= (T
) py_value
;
1027 template<typename U
= T
>
1028 static typename
std::enable_if
<std::is_floating_point
<U
>::value
, handle
>::type
1029 cast(U src
, return_value_policy
/* policy */, handle
/* parent */) {
1030 return PyFloat_FromDouble((double) src
);
1033 template<typename U
= T
>
1034 static typename
std::enable_if
<!std::is_floating_point
<U
>::value
&& std::is_signed
<U
>::value
&& (sizeof(U
) <= sizeof(long)), handle
>::type
1035 cast(U src
, return_value_policy
/* policy */, handle
/* parent */) {
1036 return PYBIND11_LONG_FROM_SIGNED((long) src
);
1039 template<typename U
= T
>
1040 static typename
std::enable_if
<!std::is_floating_point
<U
>::value
&& std::is_unsigned
<U
>::value
&& (sizeof(U
) <= sizeof(unsigned long)), handle
>::type
1041 cast(U src
, return_value_policy
/* policy */, handle
/* parent */) {
1042 return PYBIND11_LONG_FROM_UNSIGNED((unsigned long) src
);
1045 template<typename U
= T
>
1046 static typename
std::enable_if
<!std::is_floating_point
<U
>::value
&& std::is_signed
<U
>::value
&& (sizeof(U
) > sizeof(long)), handle
>::type
1047 cast(U src
, return_value_policy
/* policy */, handle
/* parent */) {
1048 return PyLong_FromLongLong((long long) src
);
1051 template<typename U
= T
>
1052 static typename
std::enable_if
<!std::is_floating_point
<U
>::value
&& std::is_unsigned
<U
>::value
&& (sizeof(U
) > sizeof(unsigned long)), handle
>::type
1053 cast(U src
, return_value_policy
/* policy */, handle
/* parent */) {
1054 return PyLong_FromUnsignedLongLong((unsigned long long) src
);
1057 PYBIND11_TYPE_CASTER(T
, _
<std::is_integral
<T
>::value
>("int", "float"));
1060 template<typename T
> struct void_caster
{
1062 bool load(handle src
, bool) {
1063 if (src
&& src
.is_none())
1067 static handle
cast(T
, return_value_policy
/* policy */, handle
/* parent */) {
1068 return none().inc_ref();
1070 PYBIND11_TYPE_CASTER(T
, _("None"));
1073 template <> class type_caster
<void_type
> : public void_caster
<void_type
> {};
1075 template <> class type_caster
<void> : public type_caster
<void_type
> {
1077 using type_caster
<void_type
>::cast
;
1079 bool load(handle h
, bool) {
1082 } else if (h
.is_none()) {
1087 /* Check if this is a capsule */
1088 if (isinstance
<capsule
>(h
)) {
1089 value
= reinterpret_borrow
<capsule
>(h
);
1093 /* Check if this is a C++ type */
1094 auto &bases
= all_type_info((PyTypeObject
*) h
.get_type().ptr());
1095 if (bases
.size() == 1) { // Only allowing loading from a single-value type
1096 value
= values_and_holders(reinterpret_cast<instance
*>(h
.ptr())).begin()->value_ptr();
1104 static handle
cast(const void *ptr
, return_value_policy
/* policy */, handle
/* parent */) {
1106 return capsule(ptr
).release();
1108 return none().inc_ref();
1111 template <typename T
> using cast_op_type
= void*&;
1112 operator void *&() { return value
; }
1113 static constexpr auto name
= _("capsule");
1115 void *value
= nullptr;
1118 template <> class type_caster
<std::nullptr_t
> : public void_caster
<std::nullptr_t
> { };
1120 template <> class type_caster
<bool> {
1122 bool load(handle src
, bool convert
) {
1123 if (!src
) return false;
1124 else if (src
.ptr() == Py_True
) { value
= true; return true; }
1125 else if (src
.ptr() == Py_False
) { value
= false; return true; }
1126 else if (convert
|| !strcmp("numpy.bool_", Py_TYPE(src
.ptr())->tp_name
)) {
1127 // (allow non-implicit conversion for numpy booleans)
1129 Py_ssize_t res
= -1;
1130 if (src
.is_none()) {
1131 res
= 0; // None is implicitly converted to False
1133 #if defined(PYPY_VERSION)
1134 // On PyPy, check that "__bool__" (or "__nonzero__" on Python 2.7) attr exists
1135 else if (hasattr(src
, PYBIND11_BOOL_ATTR
)) {
1136 res
= PyObject_IsTrue(src
.ptr());
1139 // Alternate approach for CPython: this does the same as the above, but optimized
1140 // using the CPython API so as to avoid an unneeded attribute lookup.
1141 else if (auto tp_as_number
= src
.ptr()->ob_type
->tp_as_number
) {
1142 if (PYBIND11_NB_BOOL(tp_as_number
)) {
1143 res
= (*PYBIND11_NB_BOOL(tp_as_number
))(src
.ptr());
1147 if (res
== 0 || res
== 1) {
1154 static handle
cast(bool src
, return_value_policy
/* policy */, handle
/* parent */) {
1155 return handle(src
? Py_True
: Py_False
).inc_ref();
1157 PYBIND11_TYPE_CASTER(bool, _("bool"));
1160 // Helper class for UTF-{8,16,32} C++ stl strings:
1161 template <typename StringType
, bool IsView
= false> struct string_caster
{
1162 using CharT
= typename
StringType::value_type
;
1164 // Simplify life by being able to assume standard char sizes (the standard only guarantees
1165 // minimums, but Python requires exact sizes)
1166 static_assert(!std::is_same
<CharT
, char>::value
|| sizeof(CharT
) == 1, "Unsupported char size != 1");
1167 static_assert(!std::is_same
<CharT
, char16_t
>::value
|| sizeof(CharT
) == 2, "Unsupported char16_t size != 2");
1168 static_assert(!std::is_same
<CharT
, char32_t
>::value
|| sizeof(CharT
) == 4, "Unsupported char32_t size != 4");
1169 // wchar_t can be either 16 bits (Windows) or 32 (everywhere else)
1170 static_assert(!std::is_same
<CharT
, wchar_t>::value
|| sizeof(CharT
) == 2 || sizeof(CharT
) == 4,
1171 "Unsupported wchar_t size != 2/4");
1172 static constexpr size_t UTF_N
= 8 * sizeof(CharT
);
1174 bool load(handle src
, bool) {
1175 #if PY_MAJOR_VERSION < 3
1178 handle load_src
= src
;
1181 } else if (!PyUnicode_Check(load_src
.ptr())) {
1182 #if PY_MAJOR_VERSION >= 3
1183 return load_bytes(load_src
);
1185 if (sizeof(CharT
) == 1) {
1186 return load_bytes(load_src
);
1189 // The below is a guaranteed failure in Python 3 when PyUnicode_Check returns false
1190 if (!PYBIND11_BYTES_CHECK(load_src
.ptr()))
1193 temp
= reinterpret_steal
<object
>(PyUnicode_FromObject(load_src
.ptr()));
1194 if (!temp
) { PyErr_Clear(); return false; }
1199 object utfNbytes
= reinterpret_steal
<object
>(PyUnicode_AsEncodedString(
1200 load_src
.ptr(), UTF_N
== 8 ? "utf-8" : UTF_N
== 16 ? "utf-16" : "utf-32", nullptr));
1201 if (!utfNbytes
) { PyErr_Clear(); return false; }
1203 const CharT
*buffer
= reinterpret_cast<const CharT
*>(PYBIND11_BYTES_AS_STRING(utfNbytes
.ptr()));
1204 size_t length
= (size_t) PYBIND11_BYTES_SIZE(utfNbytes
.ptr()) / sizeof(CharT
);
1205 if (UTF_N
> 8) { buffer
++; length
--; } // Skip BOM for UTF-16/32
1206 value
= StringType(buffer
, length
);
1208 // If we're loading a string_view we need to keep the encoded Python object alive:
1210 loader_life_support::add_patient(utfNbytes
);
1215 static handle
cast(const StringType
&src
, return_value_policy
/* policy */, handle
/* parent */) {
1216 const char *buffer
= reinterpret_cast<const char *>(src
.data());
1217 ssize_t nbytes
= ssize_t(src
.size() * sizeof(CharT
));
1218 handle s
= decode_utfN(buffer
, nbytes
);
1219 if (!s
) throw error_already_set();
1223 PYBIND11_TYPE_CASTER(StringType
, _(PYBIND11_STRING_NAME
));
1226 static handle
decode_utfN(const char *buffer
, ssize_t nbytes
) {
1227 #if !defined(PYPY_VERSION)
1229 UTF_N
== 8 ? PyUnicode_DecodeUTF8(buffer
, nbytes
, nullptr) :
1230 UTF_N
== 16 ? PyUnicode_DecodeUTF16(buffer
, nbytes
, nullptr, nullptr) :
1231 PyUnicode_DecodeUTF32(buffer
, nbytes
, nullptr, nullptr);
1233 // PyPy seems to have multiple problems related to PyUnicode_UTF*: the UTF8 version
1234 // sometimes segfaults for unknown reasons, while the UTF16 and 32 versions require a
1235 // non-const char * arguments, which is also a nuisance, so bypass the whole thing by just
1236 // passing the encoding as a string value, which works properly:
1237 return PyUnicode_Decode(buffer
, nbytes
, UTF_N
== 8 ? "utf-8" : UTF_N
== 16 ? "utf-16" : "utf-32", nullptr);
1241 // When loading into a std::string or char*, accept a bytes object as-is (i.e.
1242 // without any encoding/decoding attempt). For other C++ char sizes this is a no-op.
1243 // which supports loading a unicode from a str, doesn't take this path.
1244 template <typename C
= CharT
>
1245 bool load_bytes(enable_if_t
<sizeof(C
) == 1, handle
> src
) {
1246 if (PYBIND11_BYTES_CHECK(src
.ptr())) {
1247 // We were passed a Python 3 raw bytes; accept it into a std::string or char*
1248 // without any encoding attempt.
1249 const char *bytes
= PYBIND11_BYTES_AS_STRING(src
.ptr());
1251 value
= StringType(bytes
, (size_t) PYBIND11_BYTES_SIZE(src
.ptr()));
1259 template <typename C
= CharT
>
1260 bool load_bytes(enable_if_t
<sizeof(C
) != 1, handle
>) { return false; }
1263 template <typename CharT
, class Traits
, class Allocator
>
1264 struct type_caster
<std::basic_string
<CharT
, Traits
, Allocator
>, enable_if_t
<is_std_char_type
<CharT
>::value
>>
1265 : string_caster
<std::basic_string
<CharT
, Traits
, Allocator
>> {};
1267 #ifdef PYBIND11_HAS_STRING_VIEW
1268 template <typename CharT
, class Traits
>
1269 struct type_caster
<std::basic_string_view
<CharT
, Traits
>, enable_if_t
<is_std_char_type
<CharT
>::value
>>
1270 : string_caster
<std::basic_string_view
<CharT
, Traits
>, true> {};
1273 // Type caster for C-style strings. We basically use a std::string type caster, but also add the
1274 // ability to use None as a nullptr char* (which the string caster doesn't allow).
1275 template <typename CharT
> struct type_caster
<CharT
, enable_if_t
<is_std_char_type
<CharT
>::value
>> {
1276 using StringType
= std::basic_string
<CharT
>;
1277 using StringCaster
= type_caster
<StringType
>;
1278 StringCaster str_caster
;
1282 bool load(handle src
, bool convert
) {
1283 if (!src
) return false;
1284 if (src
.is_none()) {
1285 // Defer accepting None to other overloads (if we aren't in convert mode):
1286 if (!convert
) return false;
1290 return str_caster
.load(src
, convert
);
1293 static handle
cast(const CharT
*src
, return_value_policy policy
, handle parent
) {
1294 if (src
== nullptr) return pybind11::none().inc_ref();
1295 return StringCaster::cast(StringType(src
), policy
, parent
);
1298 static handle
cast(CharT src
, return_value_policy policy
, handle parent
) {
1299 if (std::is_same
<char, CharT
>::value
) {
1300 handle s
= PyUnicode_DecodeLatin1((const char *) &src
, 1, nullptr);
1301 if (!s
) throw error_already_set();
1304 return StringCaster::cast(StringType(1, src
), policy
, parent
);
1307 operator CharT
*() { return none
? nullptr : const_cast<CharT
*>(static_cast<StringType
&>(str_caster
).c_str()); }
1310 throw value_error("Cannot convert None to a character");
1312 auto &value
= static_cast<StringType
&>(str_caster
);
1313 size_t str_len
= value
.size();
1315 throw value_error("Cannot convert empty string to a character");
1317 // If we're in UTF-8 mode, we have two possible failures: one for a unicode character that
1318 // is too high, and one for multiple unicode characters (caught later), so we need to figure
1319 // out how long the first encoded character is in bytes to distinguish between these two
1320 // errors. We also allow want to allow unicode characters U+0080 through U+00FF, as those
1321 // can fit into a single char value.
1322 if (StringCaster::UTF_N
== 8 && str_len
> 1 && str_len
<= 4) {
1323 unsigned char v0
= static_cast<unsigned char>(value
[0]);
1324 size_t char0_bytes
= !(v0
& 0x80) ? 1 : // low bits only: 0-127
1325 (v0
& 0xE0) == 0xC0 ? 2 : // 0b110xxxxx - start of 2-byte sequence
1326 (v0
& 0xF0) == 0xE0 ? 3 : // 0b1110xxxx - start of 3-byte sequence
1327 4; // 0b11110xxx - start of 4-byte sequence
1329 if (char0_bytes
== str_len
) {
1330 // If we have a 128-255 value, we can decode it into a single char:
1331 if (char0_bytes
== 2 && (v0
& 0xFC) == 0xC0) { // 0x110000xx 0x10xxxxxx
1332 one_char
= static_cast<CharT
>(((v0
& 3) << 6) + (static_cast<unsigned char>(value
[1]) & 0x3F));
1335 // Otherwise we have a single character, but it's > U+00FF
1336 throw value_error("Character code point not in range(0x100)");
1340 // UTF-16 is much easier: we can only have a surrogate pair for values above U+FFFF, thus a
1341 // surrogate pair with total length 2 instantly indicates a range error (but not a "your
1342 // string was too long" error).
1343 else if (StringCaster::UTF_N
== 16 && str_len
== 2) {
1344 one_char
= static_cast<CharT
>(value
[0]);
1345 if (one_char
>= 0xD800 && one_char
< 0xE000)
1346 throw value_error("Character code point not in range(0x10000)");
1350 throw value_error("Expected a character, but multi-character string found");
1352 one_char
= value
[0];
1356 static constexpr auto name
= _(PYBIND11_STRING_NAME
);
1357 template <typename _T
> using cast_op_type
= pybind11::detail::cast_op_type
<_T
>;
1360 // Base implementation for std::tuple and std::pair
1361 template <template<typename
...> class Tuple
, typename
... Ts
> class tuple_caster
{
1362 using type
= Tuple
<Ts
...>;
1363 static constexpr auto size
= sizeof...(Ts
);
1364 using indices
= make_index_sequence
<size
>;
1367 bool load(handle src
, bool convert
) {
1368 if (!isinstance
<sequence
>(src
))
1370 const auto seq
= reinterpret_borrow
<sequence
>(src
);
1371 if (seq
.size() != size
)
1373 return load_impl(seq
, convert
, indices
{});
1376 template <typename T
>
1377 static handle
cast(T
&&src
, return_value_policy policy
, handle parent
) {
1378 return cast_impl(std::forward
<T
>(src
), policy
, parent
, indices
{});
1381 static constexpr auto name
= _("Tuple[") + concat(make_caster
<Ts
>::name
...) + _("]");
1383 template <typename T
> using cast_op_type
= type
;
1385 operator type() & { return implicit_cast(indices
{}); }
1386 operator type() && { return std::move(*this).implicit_cast(indices
{}); }
1389 template <size_t... Is
>
1390 type
implicit_cast(index_sequence
<Is
...>) & { return type(cast_op
<Ts
>(std::get
<Is
>(subcasters
))...); }
1391 template <size_t... Is
>
1392 type
implicit_cast(index_sequence
<Is
...>) && { return type(cast_op
<Ts
>(std::move(std::get
<Is
>(subcasters
)))...); }
1394 static constexpr bool load_impl(const sequence
&, bool, index_sequence
<>) { return true; }
1396 template <size_t... Is
>
1397 bool load_impl(const sequence
&seq
, bool convert
, index_sequence
<Is
...>) {
1398 for (bool r
: {std::get
<Is
>(subcasters
).load(seq
[Is
], convert
)...})
1404 /* Implementation: Convert a C++ tuple into a Python tuple */
1405 template <typename T
, size_t... Is
>
1406 static handle
cast_impl(T
&&src
, return_value_policy policy
, handle parent
, index_sequence
<Is
...>) {
1407 std::array
<object
, size
> entries
{{
1408 reinterpret_steal
<object
>(make_caster
<Ts
>::cast(std::get
<Is
>(std::forward
<T
>(src
)), policy
, parent
))...
1410 for (const auto &entry
: entries
)
1415 for (auto & entry
: entries
)
1416 PyTuple_SET_ITEM(result
.ptr(), counter
++, entry
.release().ptr());
1417 return result
.release();
1420 Tuple
<make_caster
<Ts
>...> subcasters
;
1423 template <typename T1
, typename T2
> class type_caster
<std::pair
<T1
, T2
>>
1424 : public tuple_caster
<std::pair
, T1
, T2
> {};
1426 template <typename
... Ts
> class type_caster
<std::tuple
<Ts
...>>
1427 : public tuple_caster
<std::tuple
, Ts
...> {};
1429 /// Helper class which abstracts away certain actions. Users can provide specializations for
1430 /// custom holders, but it's only necessary if the type has a non-standard interface.
1431 template <typename T
>
1432 struct holder_helper
{
1433 static auto get(const T
&p
) -> decltype(p
.get()) { return p
.get(); }
1436 /// Type caster for holder types like std::shared_ptr, etc.
1437 template <typename type
, typename holder_type
>
1438 struct copyable_holder_caster
: public type_caster_base
<type
> {
1440 using base
= type_caster_base
<type
>;
1441 static_assert(std::is_base_of
<base
, type_caster
<type
>>::value
,
1442 "Holder classes are only supported for custom types");
1445 using base::typeinfo
;
1448 bool load(handle src
, bool convert
) {
1449 return base::template load_impl
<copyable_holder_caster
<type
, holder_type
>>(src
, convert
);
1452 explicit operator type
*() { return this->value
; }
1453 explicit operator type
&() { return *(this->value
); }
1454 explicit operator holder_type
*() { return std::addressof(holder
); }
1456 // Workaround for Intel compiler bug
1457 // see pybind11 issue 94
1458 #if defined(__ICC) || defined(__INTEL_COMPILER)
1459 operator holder_type
&() { return holder
; }
1461 explicit operator holder_type
&() { return holder
; }
1464 static handle
cast(const holder_type
&src
, return_value_policy
, handle
) {
1465 const auto *ptr
= holder_helper
<holder_type
>::get(src
);
1466 return type_caster_base
<type
>::cast_holder(ptr
, &src
);
1470 friend class type_caster_generic
;
1471 void check_holder_compat() {
1472 if (typeinfo
->default_holder
)
1473 throw cast_error("Unable to load a custom holder type from a default-holder instance");
1476 bool load_value(value_and_holder
&&v_h
) {
1477 if (v_h
.holder_constructed()) {
1478 value
= v_h
.value_ptr();
1479 holder
= v_h
.template holder
<holder_type
>();
1482 throw cast_error("Unable to cast from non-held to held instance (T& to Holder<T>) "
1484 "(compile in debug mode for type information)");
1486 "of type '" + type_id
<holder_type
>() + "''");
1491 template <typename T
= holder_type
, detail::enable_if_t
<!std::is_constructible
<T
, const T
&, type
*>::value
, int> = 0>
1492 bool try_implicit_casts(handle
, bool) { return false; }
1494 template <typename T
= holder_type
, detail::enable_if_t
<std::is_constructible
<T
, const T
&, type
*>::value
, int> = 0>
1495 bool try_implicit_casts(handle src
, bool convert
) {
1496 for (auto &cast
: typeinfo
->implicit_casts
) {
1497 copyable_holder_caster
sub_caster(*cast
.first
);
1498 if (sub_caster
.load(src
, convert
)) {
1499 value
= cast
.second(sub_caster
.value
);
1500 holder
= holder_type(sub_caster
.holder
, (type
*) value
);
1507 static bool try_direct_conversions(handle
) { return false; }
1513 /// Specialize for the common std::shared_ptr, so users don't need to
1514 template <typename T
>
1515 class type_caster
<std::shared_ptr
<T
>> : public copyable_holder_caster
<T
, std::shared_ptr
<T
>> { };
1517 template <typename type
, typename holder_type
>
1518 struct move_only_holder_caster
{
1519 static_assert(std::is_base_of
<type_caster_base
<type
>, type_caster
<type
>>::value
,
1520 "Holder classes are only supported for custom types");
1522 static handle
cast(holder_type
&&src
, return_value_policy
, handle
) {
1523 auto *ptr
= holder_helper
<holder_type
>::get(src
);
1524 return type_caster_base
<type
>::cast_holder(ptr
, std::addressof(src
));
1526 static constexpr auto name
= type_caster_base
<type
>::name
;
1529 template <typename type
, typename deleter
>
1530 class type_caster
<std::unique_ptr
<type
, deleter
>>
1531 : public move_only_holder_caster
<type
, std::unique_ptr
<type
, deleter
>> { };
1533 template <typename type
, typename holder_type
>
1534 using type_caster_holder
= conditional_t
<is_copy_constructible
<holder_type
>::value
,
1535 copyable_holder_caster
<type
, holder_type
>,
1536 move_only_holder_caster
<type
, holder_type
>>;
1538 template <typename T
, bool Value
= false> struct always_construct_holder
{ static constexpr bool value
= Value
; };
1540 /// Create a specialization for custom holder types (silently ignores std::shared_ptr)
1541 #define PYBIND11_DECLARE_HOLDER_TYPE(type, holder_type, ...) \
1542 namespace pybind11 { namespace detail { \
1543 template <typename type> \
1544 struct always_construct_holder<holder_type> : always_construct_holder<void, ##__VA_ARGS__> { }; \
1545 template <typename type> \
1546 class type_caster<holder_type, enable_if_t<!is_shared_ptr<holder_type>::value>> \
1547 : public type_caster_holder<type, holder_type> { }; \
1550 // PYBIND11_DECLARE_HOLDER_TYPE holder types:
1551 template <typename base
, typename holder
> struct is_holder_type
:
1552 std::is_base_of
<detail::type_caster_holder
<base
, holder
>, detail::type_caster
<holder
>> {};
1553 // Specialization for always-supported unique_ptr holders:
1554 template <typename base
, typename deleter
> struct is_holder_type
<base
, std::unique_ptr
<base
, deleter
>> :
1557 template <typename T
> struct handle_type_name
{ static constexpr auto name
= _
<T
>(); };
1558 template <> struct handle_type_name
<bytes
> { static constexpr auto name
= _(PYBIND11_BYTES_NAME
); };
1559 template <> struct handle_type_name
<args
> { static constexpr auto name
= _("*args"); };
1560 template <> struct handle_type_name
<kwargs
> { static constexpr auto name
= _("**kwargs"); };
1562 template <typename type
>
1563 struct pyobject_caster
{
1564 template <typename T
= type
, enable_if_t
<std::is_same
<T
, handle
>::value
, int> = 0>
1565 bool load(handle src
, bool /* convert */) { value
= src
; return static_cast<bool>(value
); }
1567 template <typename T
= type
, enable_if_t
<std::is_base_of
<object
, T
>::value
, int> = 0>
1568 bool load(handle src
, bool /* convert */) {
1569 if (!isinstance
<type
>(src
))
1571 value
= reinterpret_borrow
<type
>(src
);
1575 static handle
cast(const handle
&src
, return_value_policy
/* policy */, handle
/* parent */) {
1576 return src
.inc_ref();
1578 PYBIND11_TYPE_CASTER(type
, handle_type_name
<type
>::name
);
1581 template <typename T
>
1582 class type_caster
<T
, enable_if_t
<is_pyobject
<T
>::value
>> : public pyobject_caster
<T
> { };
1584 // Our conditions for enabling moving are quite restrictive:
1586 // - T needs to be a non-const, non-pointer, non-reference type
1587 // - type_caster<T>::operator T&() must exist
1588 // - the type must be move constructible (obviously)
1590 // - if the type is non-copy-constructible, the object must be the sole owner of the type (i.e. it
1591 // must have ref_count() == 1)h
1592 // If any of the above are not satisfied, we fall back to copying.
1593 template <typename T
> using move_is_plain_type
= satisfies_none_of
<T
,
1594 std::is_void
, std::is_pointer
, std::is_reference
, std::is_const
1596 template <typename T
, typename SFINAE
= void> struct move_always
: std::false_type
{};
1597 template <typename T
> struct move_always
<T
, enable_if_t
<all_of
<
1598 move_is_plain_type
<T
>,
1599 negation
<is_copy_constructible
<T
>>,
1600 std::is_move_constructible
<T
>,
1601 std::is_same
<decltype(std::declval
<make_caster
<T
>>().operator T
&()), T
&>
1602 >::value
>> : std::true_type
{};
1603 template <typename T
, typename SFINAE
= void> struct move_if_unreferenced
: std::false_type
{};
1604 template <typename T
> struct move_if_unreferenced
<T
, enable_if_t
<all_of
<
1605 move_is_plain_type
<T
>,
1606 negation
<move_always
<T
>>,
1607 std::is_move_constructible
<T
>,
1608 std::is_same
<decltype(std::declval
<make_caster
<T
>>().operator T
&()), T
&>
1609 >::value
>> : std::true_type
{};
1610 template <typename T
> using move_never
= none_of
<move_always
<T
>, move_if_unreferenced
<T
>>;
1612 // Detect whether returning a `type` from a cast on type's type_caster is going to result in a
1613 // reference or pointer to a local variable of the type_caster. Basically, only
1614 // non-reference/pointer `type`s and reference/pointers from a type_caster_generic are safe;
1615 // everything else returns a reference/pointer to a local variable.
1616 template <typename type
> using cast_is_temporary_value_reference
= bool_constant
<
1617 (std::is_reference
<type
>::value
|| std::is_pointer
<type
>::value
) &&
1618 !std::is_base_of
<type_caster_generic
, make_caster
<type
>>::value
&&
1619 !std::is_same
<intrinsic_t
<type
>, void>::value
1622 // When a value returned from a C++ function is being cast back to Python, we almost always want to
1623 // force `policy = move`, regardless of the return value policy the function/method was declared
1625 template <typename Return
, typename SFINAE
= void> struct return_value_policy_override
{
1626 static return_value_policy
policy(return_value_policy p
) { return p
; }
1629 template <typename Return
> struct return_value_policy_override
<Return
,
1630 detail::enable_if_t
<std::is_base_of
<type_caster_generic
, make_caster
<Return
>>::value
, void>> {
1631 static return_value_policy
policy(return_value_policy p
) {
1632 return !std::is_lvalue_reference
<Return
>::value
&&
1633 !std::is_pointer
<Return
>::value
1634 ? return_value_policy::move
: p
;
1638 // Basic python -> C++ casting; throws if casting fails
1639 template <typename T
, typename SFINAE
> type_caster
<T
, SFINAE
> &load_type(type_caster
<T
, SFINAE
> &conv
, const handle
&handle
) {
1640 if (!conv
.load(handle
, true)) {
1642 throw cast_error("Unable to cast Python instance to C++ type (compile in debug mode for details)");
1644 throw cast_error("Unable to cast Python instance of type " +
1645 (std::string
) str(handle
.get_type()) + " to C++ type '" + type_id
<T
>() + "'");
1650 // Wrapper around the above that also constructs and returns a type_caster
1651 template <typename T
> make_caster
<T
> load_type(const handle
&handle
) {
1652 make_caster
<T
> conv
;
1653 load_type(conv
, handle
);
1657 NAMESPACE_END(detail
)
1659 // pytype -> C++ type
1660 template <typename T
, detail::enable_if_t
<!detail::is_pyobject
<T
>::value
, int> = 0>
1661 T
cast(const handle
&handle
) {
1662 using namespace detail
;
1663 static_assert(!cast_is_temporary_value_reference
<T
>::value
,
1664 "Unable to cast type to reference: value is local to type caster");
1665 return cast_op
<T
>(load_type
<T
>(handle
));
1668 // pytype -> pytype (calls converting constructor)
1669 template <typename T
, detail::enable_if_t
<detail::is_pyobject
<T
>::value
, int> = 0>
1670 T
cast(const handle
&handle
) { return T(reinterpret_borrow
<object
>(handle
)); }
1672 // C++ type -> py::object
1673 template <typename T
, detail::enable_if_t
<!detail::is_pyobject
<T
>::value
, int> = 0>
1674 object
cast(const T
&value
, return_value_policy policy
= return_value_policy::automatic_reference
,
1675 handle parent
= handle()) {
1676 if (policy
== return_value_policy::automatic
)
1677 policy
= std::is_pointer
<T
>::value
? return_value_policy::take_ownership
: return_value_policy::copy
;
1678 else if (policy
== return_value_policy::automatic_reference
)
1679 policy
= std::is_pointer
<T
>::value
? return_value_policy::reference
: return_value_policy::copy
;
1680 return reinterpret_steal
<object
>(detail::make_caster
<T
>::cast(value
, policy
, parent
));
1683 template <typename T
> T
handle::cast() const { return pybind11::cast
<T
>(*this); }
1684 template <> inline void handle::cast() const { return; }
1686 template <typename T
>
1687 detail::enable_if_t
<!detail::move_never
<T
>::value
, T
> move(object
&&obj
) {
1688 if (obj
.ref_count() > 1)
1690 throw cast_error("Unable to cast Python instance to C++ rvalue: instance has multiple references"
1691 " (compile in debug mode for details)");
1693 throw cast_error("Unable to move from Python " + (std::string
) str(obj
.get_type()) +
1694 " instance to C++ " + type_id
<T
>() + " instance: instance has multiple references");
1697 // Move into a temporary and return that, because the reference may be a local value of `conv`
1698 T ret
= std::move(detail::load_type
<T
>(obj
).operator T
&());
1702 // Calling cast() on an rvalue calls pybind::cast with the object rvalue, which does:
1703 // - If we have to move (because T has no copy constructor), do it. This will fail if the moved
1704 // object has multiple references, but trying to copy will fail to compile.
1705 // - If both movable and copyable, check ref count: if 1, move; otherwise copy
1706 // - Otherwise (not movable), copy.
1707 template <typename T
> detail::enable_if_t
<detail::move_always
<T
>::value
, T
> cast(object
&&object
) {
1708 return move
<T
>(std::move(object
));
1710 template <typename T
> detail::enable_if_t
<detail::move_if_unreferenced
<T
>::value
, T
> cast(object
&&object
) {
1711 if (object
.ref_count() > 1)
1712 return cast
<T
>(object
);
1714 return move
<T
>(std::move(object
));
1716 template <typename T
> detail::enable_if_t
<detail::move_never
<T
>::value
, T
> cast(object
&&object
) {
1717 return cast
<T
>(object
);
1720 template <typename T
> T
object::cast() const & { return pybind11::cast
<T
>(*this); }
1721 template <typename T
> T
object::cast() && { return pybind11::cast
<T
>(std::move(*this)); }
1722 template <> inline void object::cast() const & { return; }
1723 template <> inline void object::cast() && { return; }
1725 NAMESPACE_BEGIN(detail
)
1727 // Declared in pytypes.h:
1728 template <typename T
, enable_if_t
<!is_pyobject
<T
>::value
, int>>
1729 object
object_or_cast(T
&&o
) { return pybind11::cast(std::forward
<T
>(o
)); }
1731 struct overload_unused
{}; // Placeholder type for the unneeded (and dead code) static variable in the OVERLOAD_INT macro
1732 template <typename ret_type
> using overload_caster_t
= conditional_t
<
1733 cast_is_temporary_value_reference
<ret_type
>::value
, make_caster
<ret_type
>, overload_unused
>;
1735 // Trampoline use: for reference/pointer types to value-converted values, we do a value cast, then
1736 // store the result in the given variable. For other types, this is a no-op.
1737 template <typename T
> enable_if_t
<cast_is_temporary_value_reference
<T
>::value
, T
> cast_ref(object
&&o
, make_caster
<T
> &caster
) {
1738 return cast_op
<T
>(load_type(caster
, o
));
1740 template <typename T
> enable_if_t
<!cast_is_temporary_value_reference
<T
>::value
, T
> cast_ref(object
&&, overload_unused
&) {
1741 pybind11_fail("Internal error: cast_ref fallback invoked"); }
1743 // Trampoline use: Having a pybind11::cast with an invalid reference type is going to static_assert, even
1744 // though if it's in dead code, so we provide a "trampoline" to pybind11::cast that only does anything in
1745 // cases where pybind11::cast is valid.
1746 template <typename T
> enable_if_t
<!cast_is_temporary_value_reference
<T
>::value
, T
> cast_safe(object
&&o
) {
1747 return pybind11::cast
<T
>(std::move(o
)); }
1748 template <typename T
> enable_if_t
<cast_is_temporary_value_reference
<T
>::value
, T
> cast_safe(object
&&) {
1749 pybind11_fail("Internal error: cast_safe fallback invoked"); }
1750 template <> inline void cast_safe
<void>(object
&&) {}
1752 NAMESPACE_END(detail
)
1754 template <return_value_policy policy
= return_value_policy::automatic_reference
>
1755 tuple
make_tuple() { return tuple(0); }
1757 template <return_value_policy policy
= return_value_policy::automatic_reference
,
1758 typename
... Args
> tuple
make_tuple(Args
&&... args_
) {
1759 constexpr size_t size
= sizeof...(Args
);
1760 std::array
<object
, size
> args
{
1761 { reinterpret_steal
<object
>(detail::make_caster
<Args
>::cast(
1762 std::forward
<Args
>(args_
), policy
, nullptr))... }
1764 for (size_t i
= 0; i
< args
.size(); i
++) {
1767 throw cast_error("make_tuple(): unable to convert arguments to Python object (compile in debug mode for details)");
1769 std::array
<std::string
, size
> argtypes
{ {type_id
<Args
>()...} };
1770 throw cast_error("make_tuple(): unable to convert argument of type '" +
1771 argtypes
[i
] + "' to Python object");
1777 for (auto &arg_value
: args
)
1778 PyTuple_SET_ITEM(result
.ptr(), counter
++, arg_value
.release().ptr());
1782 /// \ingroup annotations
1783 /// Annotation for arguments
1785 /// Constructs an argument with the name of the argument; if null or omitted, this is a positional argument.
1786 constexpr explicit arg(const char *name
= nullptr) : name(name
), flag_noconvert(false), flag_none(true) { }
1787 /// Assign a value to this argument
1788 template <typename T
> arg_v
operator=(T
&&value
) const;
1789 /// Indicate that the type should not be converted in the type caster
1790 arg
&noconvert(bool flag
= true) { flag_noconvert
= flag
; return *this; }
1791 /// Indicates that the argument should/shouldn't allow None (e.g. for nullable pointer args)
1792 arg
&none(bool flag
= true) { flag_none
= flag
; return *this; }
1794 const char *name
; ///< If non-null, this is a named kwargs argument
1795 bool flag_noconvert
: 1; ///< If set, do not allow conversion (requires a supporting type caster!)
1796 bool flag_none
: 1; ///< If set (the default), allow None to be passed to this argument
1799 /// \ingroup annotations
1800 /// Annotation for arguments with values
1801 struct arg_v
: arg
{
1803 template <typename T
>
1804 arg_v(arg
&&base
, T
&&x
, const char *descr
= nullptr)
1806 value(reinterpret_steal
<object
>(
1807 detail::make_caster
<T
>::cast(x
, return_value_policy::automatic
, {})
1810 #if !defined(NDEBUG)
1811 , type(type_id
<T
>())
1816 /// Direct construction with name, default, and description
1817 template <typename T
>
1818 arg_v(const char *name
, T
&&x
, const char *descr
= nullptr)
1819 : arg_v(arg(name
), std::forward
<T
>(x
), descr
) { }
1821 /// Called internally when invoking `py::arg("a") = value`
1822 template <typename T
>
1823 arg_v(const arg
&base
, T
&&x
, const char *descr
= nullptr)
1824 : arg_v(arg(base
), std::forward
<T
>(x
), descr
) { }
1826 /// Same as `arg::noconvert()`, but returns *this as arg_v&, not arg&
1827 arg_v
&noconvert(bool flag
= true) { arg::noconvert(flag
); return *this; }
1829 /// Same as `arg::nonone()`, but returns *this as arg_v&, not arg&
1830 arg_v
&none(bool flag
= true) { arg::none(flag
); return *this; }
1832 /// The default value
1834 /// The (optional) description of the default value
1836 #if !defined(NDEBUG)
1837 /// The C++ type name of the default value (only available when compiled in debug mode)
1842 template <typename T
>
1843 arg_v
arg::operator=(T
&&value
) const { return {std::move(*this), std::forward
<T
>(value
)}; }
1845 /// Alias for backward compatibility -- to be removed in version 2.0
1846 template <typename
/*unused*/> using arg_t
= arg_v
;
1848 inline namespace literals
{
1850 String literal version of `arg`
1852 constexpr arg
operator"" _a(const char *name
, size_t) { return arg(name
); }
1855 NAMESPACE_BEGIN(detail
)
1857 // forward declaration (definition in attr.h)
1858 struct function_record
;
1860 /// Internal data associated with a single function call
1861 struct function_call
{
1862 function_call(const function_record
&f
, handle p
); // Implementation in attr.h
1864 /// The function data:
1865 const function_record
&func
;
1867 /// Arguments passed to the function:
1868 std::vector
<handle
> args
;
1870 /// The `convert` value the arguments should be loaded with
1871 std::vector
<bool> args_convert
;
1873 /// Extra references for the optional `py::args` and/or `py::kwargs` arguments (which, if
1874 /// present, are also in `args` but without a reference).
1875 object args_ref
, kwargs_ref
;
1877 /// The parent, if any
1880 /// If this is a call to an initializer, this argument contains `self`
1885 /// Helper class which loads arguments for C++ functions called from Python
1886 template <typename
... Args
>
1887 class argument_loader
{
1888 using indices
= make_index_sequence
<sizeof...(Args
)>;
1890 template <typename Arg
> using argument_is_args
= std::is_same
<intrinsic_t
<Arg
>, args
>;
1891 template <typename Arg
> using argument_is_kwargs
= std::is_same
<intrinsic_t
<Arg
>, kwargs
>;
1892 // Get args/kwargs argument positions relative to the end of the argument list:
1893 static constexpr auto args_pos
= constexpr_first
<argument_is_args
, Args
...>() - (int) sizeof...(Args
),
1894 kwargs_pos
= constexpr_first
<argument_is_kwargs
, Args
...>() - (int) sizeof...(Args
);
1896 static constexpr bool args_kwargs_are_last
= kwargs_pos
>= - 1 && args_pos
>= kwargs_pos
- 1;
1898 static_assert(args_kwargs_are_last
, "py::args/py::kwargs are only permitted as the last argument(s) of a function");
1901 static constexpr bool has_kwargs
= kwargs_pos
< 0;
1902 static constexpr bool has_args
= args_pos
< 0;
1904 static constexpr auto arg_names
= concat(type_descr(make_caster
<Args
>::name
)...);
1906 bool load_args(function_call
&call
) {
1907 return load_impl_sequence(call
, indices
{});
1910 template <typename Return
, typename Guard
, typename Func
>
1911 enable_if_t
<!std::is_void
<Return
>::value
, Return
> call(Func
&&f
) && {
1912 return std::move(*this).template call_impl
<Return
>(std::forward
<Func
>(f
), indices
{}, Guard
{});
1915 template <typename Return
, typename Guard
, typename Func
>
1916 enable_if_t
<std::is_void
<Return
>::value
, void_type
> call(Func
&&f
) && {
1917 std::move(*this).template call_impl
<Return
>(std::forward
<Func
>(f
), indices
{}, Guard
{});
1923 static bool load_impl_sequence(function_call
&, index_sequence
<>) { return true; }
1925 template <size_t... Is
>
1926 bool load_impl_sequence(function_call
&call
, index_sequence
<Is
...>) {
1927 for (bool r
: {std::get
<Is
>(argcasters
).load(call
.args
[Is
], call
.args_convert
[Is
])...})
1933 template <typename Return
, typename Func
, size_t... Is
, typename Guard
>
1934 Return
call_impl(Func
&&f
, index_sequence
<Is
...>, Guard
&&) {
1935 return std::forward
<Func
>(f
)(cast_op
<Args
>(std::move(std::get
<Is
>(argcasters
)))...);
1938 std::tuple
<make_caster
<Args
>...> argcasters
;
1941 /// Helper class which collects only positional arguments for a Python function call.
1942 /// A fancier version below can collect any argument, but this one is optimal for simple calls.
1943 template <return_value_policy policy
>
1944 class simple_collector
{
1946 template <typename
... Ts
>
1947 explicit simple_collector(Ts
&&...values
)
1948 : m_args(pybind11::make_tuple
<policy
>(std::forward
<Ts
>(values
)...)) { }
1950 const tuple
&args() const & { return m_args
; }
1951 dict
kwargs() const { return {}; }
1953 tuple
args() && { return std::move(m_args
); }
1955 /// Call a Python function and pass the collected arguments
1956 object
call(PyObject
*ptr
) const {
1957 PyObject
*result
= PyObject_CallObject(ptr
, m_args
.ptr());
1959 throw error_already_set();
1960 return reinterpret_steal
<object
>(result
);
1967 /// Helper class which collects positional, keyword, * and ** arguments for a Python function call
1968 template <return_value_policy policy
>
1969 class unpacking_collector
{
1971 template <typename
... Ts
>
1972 explicit unpacking_collector(Ts
&&...values
) {
1973 // Tuples aren't (easily) resizable so a list is needed for collection,
1974 // but the actual function call strictly requires a tuple.
1975 auto args_list
= list();
1976 int _
[] = { 0, (process(args_list
, std::forward
<Ts
>(values
)), 0)... };
1979 m_args
= std::move(args_list
);
1982 const tuple
&args() const & { return m_args
; }
1983 const dict
&kwargs() const & { return m_kwargs
; }
1985 tuple
args() && { return std::move(m_args
); }
1986 dict
kwargs() && { return std::move(m_kwargs
); }
1988 /// Call a Python function and pass the collected arguments
1989 object
call(PyObject
*ptr
) const {
1990 PyObject
*result
= PyObject_Call(ptr
, m_args
.ptr(), m_kwargs
.ptr());
1992 throw error_already_set();
1993 return reinterpret_steal
<object
>(result
);
1997 template <typename T
>
1998 void process(list
&args_list
, T
&&x
) {
1999 auto o
= reinterpret_steal
<object
>(detail::make_caster
<T
>::cast(std::forward
<T
>(x
), policy
, {}));
2002 argument_cast_error();
2004 argument_cast_error(std::to_string(args_list
.size()), type_id
<T
>());
2007 args_list
.append(o
);
2010 void process(list
&args_list
, detail::args_proxy ap
) {
2011 for (const auto &a
: ap
)
2012 args_list
.append(a
);
2015 void process(list
&/*args_list*/, arg_v a
) {
2018 nameless_argument_error();
2020 nameless_argument_error(a
.type
);
2023 if (m_kwargs
.contains(a
.name
)) {
2025 multiple_values_error();
2027 multiple_values_error(a
.name
);
2032 argument_cast_error();
2034 argument_cast_error(a
.name
, a
.type
);
2037 m_kwargs
[a
.name
] = a
.value
;
2040 void process(list
&/*args_list*/, detail::kwargs_proxy kp
) {
2043 for (const auto &k
: reinterpret_borrow
<dict
>(kp
)) {
2044 if (m_kwargs
.contains(k
.first
)) {
2046 multiple_values_error();
2048 multiple_values_error(str(k
.first
));
2051 m_kwargs
[k
.first
] = k
.second
;
2055 [[noreturn
]] static void nameless_argument_error() {
2056 throw type_error("Got kwargs without a name; only named arguments "
2057 "may be passed via py::arg() to a python function call. "
2058 "(compile in debug mode for details)");
2060 [[noreturn
]] static void nameless_argument_error(std::string type
) {
2061 throw type_error("Got kwargs without a name of type '" + type
+ "'; only named "
2062 "arguments may be passed via py::arg() to a python function call. ");
2064 [[noreturn
]] static void multiple_values_error() {
2065 throw type_error("Got multiple values for keyword argument "
2066 "(compile in debug mode for details)");
2069 [[noreturn
]] static void multiple_values_error(std::string name
) {
2070 throw type_error("Got multiple values for keyword argument '" + name
+ "'");
2073 [[noreturn
]] static void argument_cast_error() {
2074 throw cast_error("Unable to convert call argument to Python object "
2075 "(compile in debug mode for details)");
2078 [[noreturn
]] static void argument_cast_error(std::string name
, std::string type
) {
2079 throw cast_error("Unable to convert call argument '" + name
2080 + "' of type '" + type
+ "' to Python object");
2088 /// Collect only positional arguments for a Python function call
2089 template <return_value_policy policy
, typename
... Args
,
2090 typename
= enable_if_t
<all_of
<is_positional
<Args
>...>::value
>>
2091 simple_collector
<policy
> collect_arguments(Args
&&...args
) {
2092 return simple_collector
<policy
>(std::forward
<Args
>(args
)...);
2095 /// Collect all arguments, including keywords and unpacking (only instantiated when needed)
2096 template <return_value_policy policy
, typename
... Args
,
2097 typename
= enable_if_t
<!all_of
<is_positional
<Args
>...>::value
>>
2098 unpacking_collector
<policy
> collect_arguments(Args
&&...args
) {
2099 // Following argument order rules for generalized unpacking according to PEP 448
2101 constexpr_last
<is_positional
, Args
...>() < constexpr_first
<is_keyword_or_ds
, Args
...>()
2102 && constexpr_last
<is_s_unpacking
, Args
...>() < constexpr_first
<is_ds_unpacking
, Args
...>(),
2103 "Invalid function call: positional args must precede keywords and ** unpacking; "
2104 "* unpacking must precede ** unpacking"
2106 return unpacking_collector
<policy
>(std::forward
<Args
>(args
)...);
2109 template <typename Derived
>
2110 template <return_value_policy policy
, typename
... Args
>
2111 object object_api
<Derived
>::operator()(Args
&&...args
) const {
2112 return detail::collect_arguments
<policy
>(std::forward
<Args
>(args
)...).call(derived().ptr());
2115 template <typename Derived
>
2116 template <return_value_policy policy
, typename
... Args
>
2117 object object_api
<Derived
>::call(Args
&&...args
) const {
2118 return operator()<policy
>(std::forward
<Args
>(args
)...);
2121 NAMESPACE_END(detail
)
2123 #define PYBIND11_MAKE_OPAQUE(...) \
2124 namespace pybind11 { namespace detail { \
2125 template<> class type_caster<__VA_ARGS__> : public type_caster_base<__VA_ARGS__> { }; \
2128 /// Lets you pass a type containing a `,` through a macro parameter without needing a separate
2129 /// typedef, e.g.: `PYBIND11_OVERLOAD(PYBIND11_TYPE(ReturnType<A, B>), PYBIND11_TYPE(Parent<C, D>), f, arg)`
2130 #define PYBIND11_TYPE(...) __VA_ARGS__
2132 NAMESPACE_END(PYBIND11_NAMESPACE
)