1/*
2 pybind11/cast.h: Partial template specializations to cast between
3 C++ and Python types
4
5 Copyright (c) 2016 Wenzel Jakob <[email protected]>
6
7 All rights reserved. Use of this source code is governed by a
8 BSD-style license that can be found in the LICENSE file.
9*/
10
11#pragma once
12
13#include "detail/common.h"
14#include "detail/descr.h"
15#include "detail/type_caster_base.h"
16#include "detail/typeid.h"
17#include "pytypes.h"
18
19#include <array>
20#include <cstring>
21#include <functional>
22#include <iosfwd>
23#include <iterator>
24#include <memory>
25#include <string>
26#include <tuple>
27#include <type_traits>
28#include <utility>
29#include <vector>
30
31PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
32PYBIND11_NAMESPACE_BEGIN(detail)
33
34template <typename type, typename SFINAE = void>
35class type_caster : public type_caster_base<type> {};
36template <typename type>
37using make_caster = type_caster<intrinsic_t<type>>;
38
39// Shortcut for calling a caster's `cast_op_type` cast operator for casting a type_caster to a T
40template <typename T>
41typename make_caster<T>::template cast_op_type<T> cast_op(make_caster<T> &caster) {
42 return caster.operator typename make_caster<T>::template cast_op_type<T>();
43}
44template <typename T>
45typename make_caster<T>::template cast_op_type<typename std::add_rvalue_reference<T>::type>
46cast_op(make_caster<T> &&caster) {
47 return std::move(caster).operator typename make_caster<T>::
48 template cast_op_type<typename std::add_rvalue_reference<T>::type>();
49}
50
51template <typename type>
52class type_caster<std::reference_wrapper<type>> {
53private:
54 using caster_t = make_caster<type>;
55 caster_t subcaster;
56 using reference_t = type &;
57 using subcaster_cast_op_type = typename caster_t::template cast_op_type<reference_t>;
58
59 static_assert(
60 std::is_same<typename std::remove_const<type>::type &, subcaster_cast_op_type>::value
61 || std::is_same<reference_t, subcaster_cast_op_type>::value,
62 "std::reference_wrapper<T> caster requires T to have a caster with an "
63 "`operator T &()` or `operator const T &()`");
64
65public:
66 bool load(handle src, bool convert) { return subcaster.load(src, convert); }
67 static constexpr auto name = caster_t::name;
68 static handle
69 cast(const std::reference_wrapper<type> &src, return_value_policy policy, handle parent) {
70 // It is definitely wrong to take ownership of this pointer, so mask that rvp
71 if (policy == return_value_policy::take_ownership
72 || policy == return_value_policy::automatic) {
73 policy = return_value_policy::automatic_reference;
74 }
75 return caster_t::cast(&src.get(), policy, parent);
76 }
77 template <typename T>
78 using cast_op_type = std::reference_wrapper<type>;
79 explicit operator std::reference_wrapper<type>() { return cast_op<type &>(subcaster); }
80};
81
82#define PYBIND11_TYPE_CASTER(type, py_name) \
83protected: \
84 type value; \
85 \
86public: \
87 static constexpr auto name = py_name; \
88 template <typename T_, \
89 ::pybind11::detail::enable_if_t< \
90 std::is_same<type, ::pybind11::detail::remove_cv_t<T_>>::value, \
91 int> = 0> \
92 static ::pybind11::handle cast( \
93 T_ *src, ::pybind11::return_value_policy policy, ::pybind11::handle parent) { \
94 if (!src) \
95 return ::pybind11::none().release(); \
96 if (policy == ::pybind11::return_value_policy::take_ownership) { \
97 auto h = cast(std::move(*src), policy, parent); \
98 delete src; \
99 return h; \
100 } \
101 return cast(*src, policy, parent); \
102 } \
103 operator type *() { return &value; } /* NOLINT(bugprone-macro-parentheses) */ \
104 operator type &() { return value; } /* NOLINT(bugprone-macro-parentheses) */ \
105 operator type &&() && { return std::move(value); } /* NOLINT(bugprone-macro-parentheses) */ \
106 template <typename T_> \
107 using cast_op_type = ::pybind11::detail::movable_cast_op_type<T_>
108
109template <typename CharT>
110using is_std_char_type = any_of<std::is_same<CharT, char>, /* std::string */
111#if defined(PYBIND11_HAS_U8STRING)
112 std::is_same<CharT, char8_t>, /* std::u8string */
113#endif
114 std::is_same<CharT, char16_t>, /* std::u16string */
115 std::is_same<CharT, char32_t>, /* std::u32string */
116 std::is_same<CharT, wchar_t> /* std::wstring */
117 >;
118
119template <typename T>
120struct type_caster<T, enable_if_t<std::is_arithmetic<T>::value && !is_std_char_type<T>::value>> {
121 using _py_type_0 = conditional_t<sizeof(T) <= sizeof(long), long, long long>;
122 using _py_type_1 = conditional_t<std::is_signed<T>::value,
123 _py_type_0,
124 typename std::make_unsigned<_py_type_0>::type>;
125 using py_type = conditional_t<std::is_floating_point<T>::value, double, _py_type_1>;
126
127public:
128 bool load(handle src, bool convert) {
129 py_type py_value;
130
131 if (!src) {
132 return false;
133 }
134
135#if !defined(PYPY_VERSION)
136 auto index_check = [](PyObject *o) { return PyIndex_Check(o); };
137#else
138 // In PyPy 7.3.3, `PyIndex_Check` is implemented by calling `__index__`,
139 // while CPython only considers the existence of `nb_index`/`__index__`.
140 auto index_check = [](PyObject *o) { return hasattr(o, "__index__"); };
141#endif
142
143 if (std::is_floating_point<T>::value) {
144 if (convert || PyFloat_Check(src.ptr())) {
145 py_value = (py_type) PyFloat_AsDouble(src.ptr());
146 } else {
147 return false;
148 }
149 } else if (PyFloat_Check(src.ptr())
150 || (!convert && !PYBIND11_LONG_CHECK(src.ptr()) && !index_check(src.ptr()))) {
151 return false;
152 } else {
153 handle src_or_index = src;
154 // PyPy: 7.3.7's 3.8 does not implement PyLong_*'s __index__ calls.
155#if PY_VERSION_HEX < 0x03080000 || defined(PYPY_VERSION)
156 object index;
157 if (!PYBIND11_LONG_CHECK(src.ptr())) { // So: index_check(src.ptr())
158 index = reinterpret_steal<object>(PyNumber_Index(src.ptr()));
159 if (!index) {
160 PyErr_Clear();
161 if (!convert)
162 return false;
163 } else {
164 src_or_index = index;
165 }
166 }
167#endif
168 if (std::is_unsigned<py_type>::value) {
169 py_value = as_unsigned<py_type>(src_or_index.ptr());
170 } else { // signed integer:
171 py_value = sizeof(T) <= sizeof(long)
172 ? (py_type) PyLong_AsLong(src_or_index.ptr())
173 : (py_type) PYBIND11_LONG_AS_LONGLONG(src_or_index.ptr());
174 }
175 }
176
177 // Python API reported an error
178 bool py_err = py_value == (py_type) -1 && PyErr_Occurred();
179
180 // Check to see if the conversion is valid (integers should match exactly)
181 // Signed/unsigned checks happen elsewhere
182 if (py_err
183 || (std::is_integral<T>::value && sizeof(py_type) != sizeof(T)
184 && py_value != (py_type) (T) py_value)) {
185 PyErr_Clear();
186 if (py_err && convert && (PyNumber_Check(src.ptr()) != 0)) {
187 auto tmp = reinterpret_steal<object>(std::is_floating_point<T>::value
188 ? PyNumber_Float(src.ptr())
189 : PyNumber_Long(src.ptr()));
190 PyErr_Clear();
191 return load(tmp, false);
192 }
193 return false;
194 }
195
196 value = (T) py_value;
197 return true;
198 }
199
200 template <typename U = T>
201 static typename std::enable_if<std::is_floating_point<U>::value, handle>::type
202 cast(U src, return_value_policy /* policy */, handle /* parent */) {
203 return PyFloat_FromDouble((double) src);
204 }
205
206 template <typename U = T>
207 static typename std::enable_if<!std::is_floating_point<U>::value && std::is_signed<U>::value
208 && (sizeof(U) <= sizeof(long)),
209 handle>::type
210 cast(U src, return_value_policy /* policy */, handle /* parent */) {
211 return PYBIND11_LONG_FROM_SIGNED((long) src);
212 }
213
214 template <typename U = T>
215 static typename std::enable_if<!std::is_floating_point<U>::value && std::is_unsigned<U>::value
216 && (sizeof(U) <= sizeof(unsigned long)),
217 handle>::type
218 cast(U src, return_value_policy /* policy */, handle /* parent */) {
219 return PYBIND11_LONG_FROM_UNSIGNED((unsigned long) src);
220 }
221
222 template <typename U = T>
223 static typename std::enable_if<!std::is_floating_point<U>::value && std::is_signed<U>::value
224 && (sizeof(U) > sizeof(long)),
225 handle>::type
226 cast(U src, return_value_policy /* policy */, handle /* parent */) {
227 return PyLong_FromLongLong((long long) src);
228 }
229
230 template <typename U = T>
231 static typename std::enable_if<!std::is_floating_point<U>::value && std::is_unsigned<U>::value
232 && (sizeof(U) > sizeof(unsigned long)),
233 handle>::type
234 cast(U src, return_value_policy /* policy */, handle /* parent */) {
235 return PyLong_FromUnsignedLongLong((unsigned long long) src);
236 }
237
238 PYBIND11_TYPE_CASTER(T, const_name<std::is_integral<T>::value>("int", "float"));
239};
240
241template <typename T>
242struct void_caster {
243public:
244 bool load(handle src, bool) {
245 if (src && src.is_none()) {
246 return true;
247 }
248 return false;
249 }
250 static handle cast(T, return_value_policy /* policy */, handle /* parent */) {
251 return none().release();
252 }
253 PYBIND11_TYPE_CASTER(T, const_name("None"));
254};
255
256template <>
257class type_caster<void_type> : public void_caster<void_type> {};
258
259template <>
260class type_caster<void> : public type_caster<void_type> {
261public:
262 using type_caster<void_type>::cast;
263
264 bool load(handle h, bool) {
265 if (!h) {
266 return false;
267 }
268 if (h.is_none()) {
269 value = nullptr;
270 return true;
271 }
272
273 /* Check if this is a capsule */
274 if (isinstance<capsule>(h)) {
275 value = reinterpret_borrow<capsule>(h);
276 return true;
277 }
278
279 /* Check if this is a C++ type */
280 const auto &bases = all_type_info((PyTypeObject *) type::handle_of(h).ptr());
281 if (bases.size() == 1) { // Only allowing loading from a single-value type
282 value = values_and_holders(reinterpret_cast<instance *>(h.ptr())).begin()->value_ptr();
283 return true;
284 }
285
286 /* Fail */
287 return false;
288 }
289
290 static handle cast(const void *ptr, return_value_policy /* policy */, handle /* parent */) {
291 if (ptr) {
292 return capsule(ptr).release();
293 }
294 return none().release();
295 }
296
297 template <typename T>
298 using cast_op_type = void *&;
299 explicit operator void *&() { return value; }
300 static constexpr auto name = const_name("capsule");
301
302private:
303 void *value = nullptr;
304};
305
306template <>
307class type_caster<std::nullptr_t> : public void_caster<std::nullptr_t> {};
308
309template <>
310class type_caster<bool> {
311public:
312 bool load(handle src, bool convert) {
313 if (!src) {
314 return false;
315 }
316 if (src.ptr() == Py_True) {
317 value = true;
318 return true;
319 }
320 if (src.ptr() == Py_False) {
321 value = false;
322 return true;
323 }
324 if (convert || (std::strcmp("numpy.bool_", Py_TYPE(src.ptr())->tp_name) == 0)) {
325 // (allow non-implicit conversion for numpy booleans)
326
327 Py_ssize_t res = -1;
328 if (src.is_none()) {
329 res = 0; // None is implicitly converted to False
330 }
331#if defined(PYPY_VERSION)
332 // On PyPy, check that "__bool__" attr exists
333 else if (hasattr(src, PYBIND11_BOOL_ATTR)) {
334 res = PyObject_IsTrue(src.ptr());
335 }
336#else
337 // Alternate approach for CPython: this does the same as the above, but optimized
338 // using the CPython API so as to avoid an unneeded attribute lookup.
339 else if (auto *tp_as_number = src.ptr()->ob_type->tp_as_number) {
340 if (PYBIND11_NB_BOOL(tp_as_number)) {
341 res = (*PYBIND11_NB_BOOL(tp_as_number))(src.ptr());
342 }
343 }
344#endif
345 if (res == 0 || res == 1) {
346 value = (res != 0);
347 return true;
348 }
349 PyErr_Clear();
350 }
351 return false;
352 }
353 static handle cast(bool src, return_value_policy /* policy */, handle /* parent */) {
354 return handle(src ? Py_True : Py_False).inc_ref();
355 }
356 PYBIND11_TYPE_CASTER(bool, const_name("bool"));
357};
358
359// Helper class for UTF-{8,16,32} C++ stl strings:
360template <typename StringType, bool IsView = false>
361struct string_caster {
362 using CharT = typename StringType::value_type;
363
364 // Simplify life by being able to assume standard char sizes (the standard only guarantees
365 // minimums, but Python requires exact sizes)
366 static_assert(!std::is_same<CharT, char>::value || sizeof(CharT) == 1,
367 "Unsupported char size != 1");
368#if defined(PYBIND11_HAS_U8STRING)
369 static_assert(!std::is_same<CharT, char8_t>::value || sizeof(CharT) == 1,
370 "Unsupported char8_t size != 1");
371#endif
372 static_assert(!std::is_same<CharT, char16_t>::value || sizeof(CharT) == 2,
373 "Unsupported char16_t size != 2");
374 static_assert(!std::is_same<CharT, char32_t>::value || sizeof(CharT) == 4,
375 "Unsupported char32_t size != 4");
376 // wchar_t can be either 16 bits (Windows) or 32 (everywhere else)
377 static_assert(!std::is_same<CharT, wchar_t>::value || sizeof(CharT) == 2 || sizeof(CharT) == 4,
378 "Unsupported wchar_t size != 2/4");
379 static constexpr size_t UTF_N = 8 * sizeof(CharT);
380
381 bool load(handle src, bool) {
382 handle load_src = src;
383 if (!src) {
384 return false;
385 }
386 if (!PyUnicode_Check(load_src.ptr())) {
387 return load_raw(load_src);
388 }
389
390 // For UTF-8 we avoid the need for a temporary `bytes` object by using
391 // `PyUnicode_AsUTF8AndSize`.
392 if (PYBIND11_SILENCE_MSVC_C4127(UTF_N == 8)) {
393 Py_ssize_t size = -1;
394 const auto *buffer
395 = reinterpret_cast<const CharT *>(PyUnicode_AsUTF8AndSize(load_src.ptr(), &size));
396 if (!buffer) {
397 PyErr_Clear();
398 return false;
399 }
400 value = StringType(buffer, static_cast<size_t>(size));
401 return true;
402 }
403
404 auto utfNbytes
405 = reinterpret_steal<object>(PyUnicode_AsEncodedString(load_src.ptr(),
406 UTF_N == 8 ? "utf-8"
407 : UTF_N == 16 ? "utf-16"
408 : "utf-32",
409 nullptr));
410 if (!utfNbytes) {
411 PyErr_Clear();
412 return false;
413 }
414
415 const auto *buffer
416 = reinterpret_cast<const CharT *>(PYBIND11_BYTES_AS_STRING(utfNbytes.ptr()));
417 size_t length = (size_t) PYBIND11_BYTES_SIZE(utfNbytes.ptr()) / sizeof(CharT);
418 // Skip BOM for UTF-16/32
419 if (PYBIND11_SILENCE_MSVC_C4127(UTF_N > 8)) {
420 buffer++;
421 length--;
422 }
423 value = StringType(buffer, length);
424
425 // If we're loading a string_view we need to keep the encoded Python object alive:
426 if (IsView) {
427 loader_life_support::add_patient(utfNbytes);
428 }
429
430 return true;
431 }
432
433 static handle
434 cast(const StringType &src, return_value_policy /* policy */, handle /* parent */) {
435 const char *buffer = reinterpret_cast<const char *>(src.data());
436 auto nbytes = ssize_t(src.size() * sizeof(CharT));
437 handle s = decode_utfN(buffer, nbytes);
438 if (!s) {
439 throw error_already_set();
440 }
441 return s;
442 }
443
444 PYBIND11_TYPE_CASTER(StringType, const_name(PYBIND11_STRING_NAME));
445
446private:
447 static handle decode_utfN(const char *buffer, ssize_t nbytes) {
448#if !defined(PYPY_VERSION)
449 return UTF_N == 8 ? PyUnicode_DecodeUTF8(buffer, nbytes, nullptr)
450 : UTF_N == 16 ? PyUnicode_DecodeUTF16(buffer, nbytes, nullptr, nullptr)
451 : PyUnicode_DecodeUTF32(buffer, nbytes, nullptr, nullptr);
452#else
453 // PyPy segfaults when on PyUnicode_DecodeUTF16 (and possibly on PyUnicode_DecodeUTF32 as
454 // well), so bypass the whole thing by just passing the encoding as a string value, which
455 // works properly:
456 return PyUnicode_Decode(buffer,
457 nbytes,
458 UTF_N == 8 ? "utf-8"
459 : UTF_N == 16 ? "utf-16"
460 : "utf-32",
461 nullptr);
462#endif
463 }
464
465 // When loading into a std::string or char*, accept a bytes/bytearray object as-is (i.e.
466 // without any encoding/decoding attempt). For other C++ char sizes this is a no-op.
467 // which supports loading a unicode from a str, doesn't take this path.
468 template <typename C = CharT>
469 bool load_raw(enable_if_t<std::is_same<C, char>::value, handle> src) {
470 if (PYBIND11_BYTES_CHECK(src.ptr())) {
471 // We were passed raw bytes; accept it into a std::string or char*
472 // without any encoding attempt.
473 const char *bytes = PYBIND11_BYTES_AS_STRING(src.ptr());
474 if (!bytes) {
475 pybind11_fail("Unexpected PYBIND11_BYTES_AS_STRING() failure.");
476 }
477 value = StringType(bytes, (size_t) PYBIND11_BYTES_SIZE(src.ptr()));
478 return true;
479 }
480 if (PyByteArray_Check(src.ptr())) {
481 // We were passed a bytearray; accept it into a std::string or char*
482 // without any encoding attempt.
483 const char *bytearray = PyByteArray_AsString(src.ptr());
484 if (!bytearray) {
485 pybind11_fail("Unexpected PyByteArray_AsString() failure.");
486 }
487 value = StringType(bytearray, (size_t) PyByteArray_Size(src.ptr()));
488 return true;
489 }
490
491 return false;
492 }
493
494 template <typename C = CharT>
495 bool load_raw(enable_if_t<!std::is_same<C, char>::value, handle>) {
496 return false;
497 }
498};
499
500template <typename CharT, class Traits, class Allocator>
501struct type_caster<std::basic_string<CharT, Traits, Allocator>,
502 enable_if_t<is_std_char_type<CharT>::value>>
503 : string_caster<std::basic_string<CharT, Traits, Allocator>> {};
504
505#ifdef PYBIND11_HAS_STRING_VIEW
506template <typename CharT, class Traits>
507struct type_caster<std::basic_string_view<CharT, Traits>,
508 enable_if_t<is_std_char_type<CharT>::value>>
509 : string_caster<std::basic_string_view<CharT, Traits>, true> {};
510#endif
511
512// Type caster for C-style strings. We basically use a std::string type caster, but also add the
513// ability to use None as a nullptr char* (which the string caster doesn't allow).
514template <typename CharT>
515struct type_caster<CharT, enable_if_t<is_std_char_type<CharT>::value>> {
516 using StringType = std::basic_string<CharT>;
517 using StringCaster = make_caster<StringType>;
518 StringCaster str_caster;
519 bool none = false;
520 CharT one_char = 0;
521
522public:
523 bool load(handle src, bool convert) {
524 if (!src) {
525 return false;
526 }
527 if (src.is_none()) {
528 // Defer accepting None to other overloads (if we aren't in convert mode):
529 if (!convert) {
530 return false;
531 }
532 none = true;
533 return true;
534 }
535 return str_caster.load(src, convert);
536 }
537
538 static handle cast(const CharT *src, return_value_policy policy, handle parent) {
539 if (src == nullptr) {
540 return pybind11::none().release();
541 }
542 return StringCaster::cast(StringType(src), policy, parent);
543 }
544
545 static handle cast(CharT src, return_value_policy policy, handle parent) {
546 if (std::is_same<char, CharT>::value) {
547 handle s = PyUnicode_DecodeLatin1((const char *) &src, 1, nullptr);
548 if (!s) {
549 throw error_already_set();
550 }
551 return s;
552 }
553 return StringCaster::cast(StringType(1, src), policy, parent);
554 }
555
556 explicit operator CharT *() {
557 return none ? nullptr : const_cast<CharT *>(static_cast<StringType &>(str_caster).c_str());
558 }
559 explicit operator CharT &() {
560 if (none) {
561 throw value_error("Cannot convert None to a character");
562 }
563
564 auto &value = static_cast<StringType &>(str_caster);
565 size_t str_len = value.size();
566 if (str_len == 0) {
567 throw value_error("Cannot convert empty string to a character");
568 }
569
570 // If we're in UTF-8 mode, we have two possible failures: one for a unicode character that
571 // is too high, and one for multiple unicode characters (caught later), so we need to
572 // figure out how long the first encoded character is in bytes to distinguish between these
573 // two errors. We also allow want to allow unicode characters U+0080 through U+00FF, as
574 // those can fit into a single char value.
575 if (PYBIND11_SILENCE_MSVC_C4127(StringCaster::UTF_N == 8) && str_len > 1 && str_len <= 4) {
576 auto v0 = static_cast<unsigned char>(value[0]);
577 // low bits only: 0-127
578 // 0b110xxxxx - start of 2-byte sequence
579 // 0b1110xxxx - start of 3-byte sequence
580 // 0b11110xxx - start of 4-byte sequence
581 size_t char0_bytes = (v0 & 0x80) == 0 ? 1
582 : (v0 & 0xE0) == 0xC0 ? 2
583 : (v0 & 0xF0) == 0xE0 ? 3
584 : 4;
585
586 if (char0_bytes == str_len) {
587 // If we have a 128-255 value, we can decode it into a single char:
588 if (char0_bytes == 2 && (v0 & 0xFC) == 0xC0) { // 0x110000xx 0x10xxxxxx
589 one_char = static_cast<CharT>(((v0 & 3) << 6)
590 + (static_cast<unsigned char>(value[1]) & 0x3F));
591 return one_char;
592 }
593 // Otherwise we have a single character, but it's > U+00FF
594 throw value_error("Character code point not in range(0x100)");
595 }
596 }
597
598 // UTF-16 is much easier: we can only have a surrogate pair for values above U+FFFF, thus a
599 // surrogate pair with total length 2 instantly indicates a range error (but not a "your
600 // string was too long" error).
601 else if (PYBIND11_SILENCE_MSVC_C4127(StringCaster::UTF_N == 16) && str_len == 2) {
602 one_char = static_cast<CharT>(value[0]);
603 if (one_char >= 0xD800 && one_char < 0xE000) {
604 throw value_error("Character code point not in range(0x10000)");
605 }
606 }
607
608 if (str_len != 1) {
609 throw value_error("Expected a character, but multi-character string found");
610 }
611
612 one_char = value[0];
613 return one_char;
614 }
615
616 static constexpr auto name = const_name(PYBIND11_STRING_NAME);
617 template <typename _T>
618 using cast_op_type = pybind11::detail::cast_op_type<_T>;
619};
620
621// Base implementation for std::tuple and std::pair
622template <template <typename...> class Tuple, typename... Ts>
623class tuple_caster {
624 using type = Tuple<Ts...>;
625 static constexpr auto size = sizeof...(Ts);
626 using indices = make_index_sequence<size>;
627
628public:
629 bool load(handle src, bool convert) {
630 if (!isinstance<sequence>(src)) {
631 return false;
632 }
633 const auto seq = reinterpret_borrow<sequence>(src);
634 if (seq.size() != size) {
635 return false;
636 }
637 return load_impl(seq, convert, indices{});
638 }
639
640 template <typename T>
641 static handle cast(T &&src, return_value_policy policy, handle parent) {
642 return cast_impl(std::forward<T>(src), policy, parent, indices{});
643 }
644
645 // copied from the PYBIND11_TYPE_CASTER macro
646 template <typename T>
647 static handle cast(T *src, return_value_policy policy, handle parent) {
648 if (!src) {
649 return none().release();
650 }
651 if (policy == return_value_policy::take_ownership) {
652 auto h = cast(std::move(*src), policy, parent);
653 delete src;
654 return h;
655 }
656 return cast(*src, policy, parent);
657 }
658
659 static constexpr auto name
660 = const_name("Tuple[") + concat(make_caster<Ts>::name...) + const_name("]");
661
662 template <typename T>
663 using cast_op_type = type;
664
665 explicit operator type() & { return implicit_cast(indices{}); }
666 explicit operator type() && { return std::move(*this).implicit_cast(indices{}); }
667
668protected:
669 template <size_t... Is>
670 type implicit_cast(index_sequence<Is...>) & {
671 return type(cast_op<Ts>(std::get<Is>(subcasters))...);
672 }
673 template <size_t... Is>
674 type implicit_cast(index_sequence<Is...>) && {
675 return type(cast_op<Ts>(std::move(std::get<Is>(subcasters)))...);
676 }
677
678 static constexpr bool load_impl(const sequence &, bool, index_sequence<>) { return true; }
679
680 template <size_t... Is>
681 bool load_impl(const sequence &seq, bool convert, index_sequence<Is...>) {
682#ifdef __cpp_fold_expressions
683 if ((... || !std::get<Is>(subcasters).load(seq[Is], convert))) {
684 return false;
685 }
686#else
687 for (bool r : {std::get<Is>(subcasters).load(seq[Is], convert)...}) {
688 if (!r) {
689 return false;
690 }
691 }
692#endif
693 return true;
694 }
695
696 /* Implementation: Convert a C++ tuple into a Python tuple */
697 template <typename T, size_t... Is>
698 static handle
699 cast_impl(T &&src, return_value_policy policy, handle parent, index_sequence<Is...>) {
700 PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(src, policy, parent);
701 PYBIND11_WORKAROUND_INCORRECT_GCC_UNUSED_BUT_SET_PARAMETER(policy, parent);
702 std::array<object, size> entries{{reinterpret_steal<object>(
703 make_caster<Ts>::cast(std::get<Is>(std::forward<T>(src)), policy, parent))...}};
704 for (const auto &entry : entries) {
705 if (!entry) {
706 return handle();
707 }
708 }
709 tuple result(size);
710 int counter = 0;
711 for (auto &entry : entries) {
712 PyTuple_SET_ITEM(result.ptr(), counter++, entry.release().ptr());
713 }
714 return result.release();
715 }
716
717 Tuple<make_caster<Ts>...> subcasters;
718};
719
720template <typename T1, typename T2>
721class type_caster<std::pair<T1, T2>> : public tuple_caster<std::pair, T1, T2> {};
722
723template <typename... Ts>
724class type_caster<std::tuple<Ts...>> : public tuple_caster<std::tuple, Ts...> {};
725
726/// Helper class which abstracts away certain actions. Users can provide specializations for
727/// custom holders, but it's only necessary if the type has a non-standard interface.
728template <typename T>
729struct holder_helper {
730 static auto get(const T &p) -> decltype(p.get()) { return p.get(); }
731};
732
733/// Type caster for holder types like std::shared_ptr, etc.
734/// The SFINAE hook is provided to help work around the current lack of support
735/// for smart-pointer interoperability. Please consider it an implementation
736/// detail that may change in the future, as formal support for smart-pointer
737/// interoperability is added into pybind11.
738template <typename type, typename holder_type, typename SFINAE = void>
739struct copyable_holder_caster : public type_caster_base<type> {
740public:
741 using base = type_caster_base<type>;
742 static_assert(std::is_base_of<base, type_caster<type>>::value,
743 "Holder classes are only supported for custom types");
744 using base::base;
745 using base::cast;
746 using base::typeinfo;
747 using base::value;
748
749 bool load(handle src, bool convert) {
750 return base::template load_impl<copyable_holder_caster<type, holder_type>>(src, convert);
751 }
752
753 explicit operator type *() { return this->value; }
754 // static_cast works around compiler error with MSVC 17 and CUDA 10.2
755 // see issue #2180
756 explicit operator type &() { return *(static_cast<type *>(this->value)); }
757 explicit operator holder_type *() { return std::addressof(holder); }
758 explicit operator holder_type &() { return holder; }
759
760 static handle cast(const holder_type &src, return_value_policy, handle) {
761 const auto *ptr = holder_helper<holder_type>::get(src);
762 return type_caster_base<type>::cast_holder(ptr, &src);
763 }
764
765protected:
766 friend class type_caster_generic;
767 void check_holder_compat() {
768 if (typeinfo->default_holder) {
769 throw cast_error("Unable to load a custom holder type from a default-holder instance");
770 }
771 }
772
773 bool load_value(value_and_holder &&v_h) {
774 if (v_h.holder_constructed()) {
775 value = v_h.value_ptr();
776 holder = v_h.template holder<holder_type>();
777 return true;
778 }
779 throw cast_error("Unable to cast from non-held to held instance (T& to Holder<T>) "
780#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
781 "(#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for "
782 "type information)");
783#else
784 "of type '"
785 + type_id<holder_type>() + "''");
786#endif
787 }
788
789 template <typename T = holder_type,
790 detail::enable_if_t<!std::is_constructible<T, const T &, type *>::value, int> = 0>
791 bool try_implicit_casts(handle, bool) {
792 return false;
793 }
794
795 template <typename T = holder_type,
796 detail::enable_if_t<std::is_constructible<T, const T &, type *>::value, int> = 0>
797 bool try_implicit_casts(handle src, bool convert) {
798 for (auto &cast : typeinfo->implicit_casts) {
799 copyable_holder_caster sub_caster(*cast.first);
800 if (sub_caster.load(src, convert)) {
801 value = cast.second(sub_caster.value);
802 holder = holder_type(sub_caster.holder, (type *) value);
803 return true;
804 }
805 }
806 return false;
807 }
808
809 static bool try_direct_conversions(handle) { return false; }
810
811 holder_type holder;
812};
813
814/// Specialize for the common std::shared_ptr, so users don't need to
815template <typename T>
816class type_caster<std::shared_ptr<T>> : public copyable_holder_caster<T, std::shared_ptr<T>> {};
817
818/// Type caster for holder types like std::unique_ptr.
819/// Please consider the SFINAE hook an implementation detail, as explained
820/// in the comment for the copyable_holder_caster.
821template <typename type, typename holder_type, typename SFINAE = void>
822struct move_only_holder_caster {
823 static_assert(std::is_base_of<type_caster_base<type>, type_caster<type>>::value,
824 "Holder classes are only supported for custom types");
825
826 static handle cast(holder_type &&src, return_value_policy, handle) {
827 auto *ptr = holder_helper<holder_type>::get(src);
828 return type_caster_base<type>::cast_holder(ptr, std::addressof(src));
829 }
830 static constexpr auto name = type_caster_base<type>::name;
831};
832
833template <typename type, typename deleter>
834class type_caster<std::unique_ptr<type, deleter>>
835 : public move_only_holder_caster<type, std::unique_ptr<type, deleter>> {};
836
837template <typename type, typename holder_type>
838using type_caster_holder = conditional_t<is_copy_constructible<holder_type>::value,
839 copyable_holder_caster<type, holder_type>,
840 move_only_holder_caster<type, holder_type>>;
841
842template <typename T, bool Value = false>
843struct always_construct_holder {
844 static constexpr bool value = Value;
845};
846
847/// Create a specialization for custom holder types (silently ignores std::shared_ptr)
848#define PYBIND11_DECLARE_HOLDER_TYPE(type, holder_type, ...) \
849 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) \
850 namespace detail { \
851 template <typename type> \
852 struct always_construct_holder<holder_type> : always_construct_holder<void, ##__VA_ARGS__> { \
853 }; \
854 template <typename type> \
855 class type_caster<holder_type, enable_if_t<!is_shared_ptr<holder_type>::value>> \
856 : public type_caster_holder<type, holder_type> {}; \
857 } \
858 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
859
860// PYBIND11_DECLARE_HOLDER_TYPE holder types:
861template <typename base, typename holder>
862struct is_holder_type
863 : std::is_base_of<detail::type_caster_holder<base, holder>, detail::type_caster<holder>> {};
864// Specialization for always-supported unique_ptr holders:
865template <typename base, typename deleter>
866struct is_holder_type<base, std::unique_ptr<base, deleter>> : std::true_type {};
867
868template <typename T>
869struct handle_type_name {
870 static constexpr auto name = const_name<T>();
871};
872template <>
873struct handle_type_name<bool_> {
874 static constexpr auto name = const_name("bool");
875};
876template <>
877struct handle_type_name<bytes> {
878 static constexpr auto name = const_name(PYBIND11_BYTES_NAME);
879};
880template <>
881struct handle_type_name<int_> {
882 static constexpr auto name = const_name("int");
883};
884template <>
885struct handle_type_name<iterable> {
886 static constexpr auto name = const_name("Iterable");
887};
888template <>
889struct handle_type_name<iterator> {
890 static constexpr auto name = const_name("Iterator");
891};
892template <>
893struct handle_type_name<float_> {
894 static constexpr auto name = const_name("float");
895};
896template <>
897struct handle_type_name<none> {
898 static constexpr auto name = const_name("None");
899};
900template <>
901struct handle_type_name<args> {
902 static constexpr auto name = const_name("*args");
903};
904template <>
905struct handle_type_name<kwargs> {
906 static constexpr auto name = const_name("**kwargs");
907};
908
909template <typename type>
910struct pyobject_caster {
911 template <typename T = type, enable_if_t<std::is_same<T, handle>::value, int> = 0>
912 pyobject_caster() : value() {}
913
914 // `type` may not be default constructible (e.g. frozenset, anyset). Initializing `value`
915 // to a nil handle is safe since it will only be accessed if `load` succeeds.
916 template <typename T = type, enable_if_t<std::is_base_of<object, T>::value, int> = 0>
917 pyobject_caster() : value(reinterpret_steal<type>(handle())) {}
918
919 template <typename T = type, enable_if_t<std::is_same<T, handle>::value, int> = 0>
920 bool load(handle src, bool /* convert */) {
921 value = src;
922 return static_cast<bool>(value);
923 }
924
925 template <typename T = type, enable_if_t<std::is_base_of<object, T>::value, int> = 0>
926 bool load(handle src, bool /* convert */) {
927 if (!isinstance<type>(src)) {
928 return false;
929 }
930 value = reinterpret_borrow<type>(src);
931 return true;
932 }
933
934 static handle cast(const handle &src, return_value_policy /* policy */, handle /* parent */) {
935 return src.inc_ref();
936 }
937 PYBIND11_TYPE_CASTER(type, handle_type_name<type>::name);
938};
939
940template <typename T>
941class type_caster<T, enable_if_t<is_pyobject<T>::value>> : public pyobject_caster<T> {};
942
943// Our conditions for enabling moving are quite restrictive:
944// At compile time:
945// - T needs to be a non-const, non-pointer, non-reference type
946// - type_caster<T>::operator T&() must exist
947// - the type must be move constructible (obviously)
948// At run-time:
949// - if the type is non-copy-constructible, the object must be the sole owner of the type (i.e. it
950// must have ref_count() == 1)h
951// If any of the above are not satisfied, we fall back to copying.
952template <typename T>
953using move_is_plain_type
954 = satisfies_none_of<T, std::is_void, std::is_pointer, std::is_reference, std::is_const>;
955template <typename T, typename SFINAE = void>
956struct move_always : std::false_type {};
957template <typename T>
958struct move_always<
959 T,
960 enable_if_t<
961 all_of<move_is_plain_type<T>,
962 negation<is_copy_constructible<T>>,
963 std::is_move_constructible<T>,
964 std::is_same<decltype(std::declval<make_caster<T>>().operator T &()), T &>>::value>>
965 : std::true_type {};
966template <typename T, typename SFINAE = void>
967struct move_if_unreferenced : std::false_type {};
968template <typename T>
969struct move_if_unreferenced<
970 T,
971 enable_if_t<
972 all_of<move_is_plain_type<T>,
973 negation<move_always<T>>,
974 std::is_move_constructible<T>,
975 std::is_same<decltype(std::declval<make_caster<T>>().operator T &()), T &>>::value>>
976 : std::true_type {};
977template <typename T>
978using move_never = none_of<move_always<T>, move_if_unreferenced<T>>;
979
980// Detect whether returning a `type` from a cast on type's type_caster is going to result in a
981// reference or pointer to a local variable of the type_caster. Basically, only
982// non-reference/pointer `type`s and reference/pointers from a type_caster_generic are safe;
983// everything else returns a reference/pointer to a local variable.
984template <typename type>
985using cast_is_temporary_value_reference
986 = bool_constant<(std::is_reference<type>::value || std::is_pointer<type>::value)
987 && !std::is_base_of<type_caster_generic, make_caster<type>>::value
988 && !std::is_same<intrinsic_t<type>, void>::value>;
989
990// When a value returned from a C++ function is being cast back to Python, we almost always want to
991// force `policy = move`, regardless of the return value policy the function/method was declared
992// with.
993template <typename Return, typename SFINAE = void>
994struct return_value_policy_override {
995 static return_value_policy policy(return_value_policy p) { return p; }
996};
997
998template <typename Return>
999struct return_value_policy_override<
1000 Return,
1001 detail::enable_if_t<std::is_base_of<type_caster_generic, make_caster<Return>>::value, void>> {
1002 static return_value_policy policy(return_value_policy p) {
1003 return !std::is_lvalue_reference<Return>::value && !std::is_pointer<Return>::value
1004 ? return_value_policy::move
1005 : p;
1006 }
1007};
1008
1009// Basic python -> C++ casting; throws if casting fails
1010template <typename T, typename SFINAE>
1011type_caster<T, SFINAE> &load_type(type_caster<T, SFINAE> &conv, const handle &handle) {
1012 static_assert(!detail::is_pyobject<T>::value,
1013 "Internal error: type_caster should only be used for C++ types");
1014 if (!conv.load(handle, true)) {
1015#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1016 throw cast_error("Unable to cast Python instance to C++ type (#define "
1017 "PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1018#else
1019 throw cast_error("Unable to cast Python instance of type "
1020 + (std::string) str(type::handle_of(handle)) + " to C++ type '"
1021 + type_id<T>() + "'");
1022#endif
1023 }
1024 return conv;
1025}
1026// Wrapper around the above that also constructs and returns a type_caster
1027template <typename T>
1028make_caster<T> load_type(const handle &handle) {
1029 make_caster<T> conv;
1030 load_type(conv, handle);
1031 return conv;
1032}
1033
1034PYBIND11_NAMESPACE_END(detail)
1035
1036// pytype -> C++ type
1037template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0>
1038T cast(const handle &handle) {
1039 using namespace detail;
1040 static_assert(!cast_is_temporary_value_reference<T>::value,
1041 "Unable to cast type to reference: value is local to type caster");
1042 return cast_op<T>(load_type<T>(handle));
1043}
1044
1045// pytype -> pytype (calls converting constructor)
1046template <typename T, detail::enable_if_t<detail::is_pyobject<T>::value, int> = 0>
1047T cast(const handle &handle) {
1048 return T(reinterpret_borrow<object>(handle));
1049}
1050
1051// C++ type -> py::object
1052template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0>
1053object cast(T &&value,
1054 return_value_policy policy = return_value_policy::automatic_reference,
1055 handle parent = handle()) {
1056 using no_ref_T = typename std::remove_reference<T>::type;
1057 if (policy == return_value_policy::automatic) {
1058 policy = std::is_pointer<no_ref_T>::value ? return_value_policy::take_ownership
1059 : std::is_lvalue_reference<T>::value ? return_value_policy::copy
1060 : return_value_policy::move;
1061 } else if (policy == return_value_policy::automatic_reference) {
1062 policy = std::is_pointer<no_ref_T>::value ? return_value_policy::reference
1063 : std::is_lvalue_reference<T>::value ? return_value_policy::copy
1064 : return_value_policy::move;
1065 }
1066 return reinterpret_steal<object>(
1067 detail::make_caster<T>::cast(std::forward<T>(value), policy, parent));
1068}
1069
1070template <typename T>
1071T handle::cast() const {
1072 return pybind11::cast<T>(*this);
1073}
1074template <>
1075inline void handle::cast() const {
1076 return;
1077}
1078
1079template <typename T>
1080detail::enable_if_t<!detail::move_never<T>::value, T> move(object &&obj) {
1081 if (obj.ref_count() > 1) {
1082#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1083 throw cast_error(
1084 "Unable to cast Python instance to C++ rvalue: instance has multiple references"
1085 " (#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1086#else
1087 throw cast_error("Unable to move from Python " + (std::string) str(type::handle_of(obj))
1088 + " instance to C++ " + type_id<T>()
1089 + " instance: instance has multiple references");
1090#endif
1091 }
1092
1093 // Move into a temporary and return that, because the reference may be a local value of `conv`
1094 T ret = std::move(detail::load_type<T>(obj).operator T &());
1095 return ret;
1096}
1097
1098// Calling cast() on an rvalue calls pybind11::cast with the object rvalue, which does:
1099// - If we have to move (because T has no copy constructor), do it. This will fail if the moved
1100// object has multiple references, but trying to copy will fail to compile.
1101// - If both movable and copyable, check ref count: if 1, move; otherwise copy
1102// - Otherwise (not movable), copy.
1103template <typename T>
1104detail::enable_if_t<!detail::is_pyobject<T>::value && detail::move_always<T>::value, T>
1105cast(object &&object) {
1106 return move<T>(std::move(object));
1107}
1108template <typename T>
1109detail::enable_if_t<!detail::is_pyobject<T>::value && detail::move_if_unreferenced<T>::value, T>
1110cast(object &&object) {
1111 if (object.ref_count() > 1) {
1112 return cast<T>(object);
1113 }
1114 return move<T>(std::move(object));
1115}
1116template <typename T>
1117detail::enable_if_t<!detail::is_pyobject<T>::value && detail::move_never<T>::value, T>
1118cast(object &&object) {
1119 return cast<T>(object);
1120}
1121
1122// pytype rvalue -> pytype (calls converting constructor)
1123template <typename T>
1124detail::enable_if_t<detail::is_pyobject<T>::value, T> cast(object &&object) {
1125 return T(std::move(object));
1126}
1127
1128template <typename T>
1129T object::cast() const & {
1130 return pybind11::cast<T>(*this);
1131}
1132template <typename T>
1133T object::cast() && {
1134 return pybind11::cast<T>(std::move(*this));
1135}
1136template <>
1137inline void object::cast() const & {
1138 return;
1139}
1140template <>
1141inline void object::cast() && {
1142 return;
1143}
1144
1145PYBIND11_NAMESPACE_BEGIN(detail)
1146
1147// Declared in pytypes.h:
1148template <typename T, enable_if_t<!is_pyobject<T>::value, int>>
1149object object_or_cast(T &&o) {
1150 return pybind11::cast(std::forward<T>(o));
1151}
1152
1153// Placeholder type for the unneeded (and dead code) static variable in the
1154// PYBIND11_OVERRIDE_OVERRIDE macro
1155struct override_unused {};
1156template <typename ret_type>
1157using override_caster_t = conditional_t<cast_is_temporary_value_reference<ret_type>::value,
1158 make_caster<ret_type>,
1159 override_unused>;
1160
1161// Trampoline use: for reference/pointer types to value-converted values, we do a value cast, then
1162// store the result in the given variable. For other types, this is a no-op.
1163template <typename T>
1164enable_if_t<cast_is_temporary_value_reference<T>::value, T> cast_ref(object &&o,
1165 make_caster<T> &caster) {
1166 return cast_op<T>(load_type(caster, o));
1167}
1168template <typename T>
1169enable_if_t<!cast_is_temporary_value_reference<T>::value, T> cast_ref(object &&,
1170 override_unused &) {
1171 pybind11_fail("Internal error: cast_ref fallback invoked");
1172}
1173
1174// Trampoline use: Having a pybind11::cast with an invalid reference type is going to
1175// static_assert, even though if it's in dead code, so we provide a "trampoline" to pybind11::cast
1176// that only does anything in cases where pybind11::cast is valid.
1177template <typename T>
1178enable_if_t<cast_is_temporary_value_reference<T>::value, T> cast_safe(object &&) {
1179 pybind11_fail("Internal error: cast_safe fallback invoked");
1180}
1181template <typename T>
1182enable_if_t<std::is_void<T>::value, void> cast_safe(object &&) {}
1183template <typename T>
1184enable_if_t<detail::none_of<cast_is_temporary_value_reference<T>, std::is_void<T>>::value, T>
1185cast_safe(object &&o) {
1186 return pybind11::cast<T>(std::move(o));
1187}
1188
1189PYBIND11_NAMESPACE_END(detail)
1190
1191// The overloads could coexist, i.e. the #if is not strictly speaking needed,
1192// but it is an easy minor optimization.
1193#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1194inline cast_error cast_error_unable_to_convert_call_arg() {
1195 return cast_error("Unable to convert call argument to Python object (#define "
1196 "PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1197}
1198#else
1199inline cast_error cast_error_unable_to_convert_call_arg(const std::string &name,
1200 const std::string &type) {
1201 return cast_error("Unable to convert call argument '" + name + "' of type '" + type
1202 + "' to Python object");
1203}
1204#endif
1205
1206template <return_value_policy policy = return_value_policy::automatic_reference>
1207tuple make_tuple() {
1208 return tuple(0);
1209}
1210
1211template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
1212tuple make_tuple(Args &&...args_) {
1213 constexpr size_t size = sizeof...(Args);
1214 std::array<object, size> args{{reinterpret_steal<object>(
1215 detail::make_caster<Args>::cast(std::forward<Args>(args_), policy, nullptr))...}};
1216 for (size_t i = 0; i < args.size(); i++) {
1217 if (!args[i]) {
1218#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1219 throw cast_error_unable_to_convert_call_arg();
1220#else
1221 std::array<std::string, size> argtypes{{type_id<Args>()...}};
1222 throw cast_error_unable_to_convert_call_arg(std::to_string(i), argtypes[i]);
1223#endif
1224 }
1225 }
1226 tuple result(size);
1227 int counter = 0;
1228 for (auto &arg_value : args) {
1229 PyTuple_SET_ITEM(result.ptr(), counter++, arg_value.release().ptr());
1230 }
1231 return result;
1232}
1233
1234/// \ingroup annotations
1235/// Annotation for arguments
1236struct arg {
1237 /// Constructs an argument with the name of the argument; if null or omitted, this is a
1238 /// positional argument.
1239 constexpr explicit arg(const char *name = nullptr)
1240 : name(name), flag_noconvert(false), flag_none(true) {}
1241 /// Assign a value to this argument
1242 template <typename T>
1243 arg_v operator=(T &&value) const;
1244 /// Indicate that the type should not be converted in the type caster
1245 arg &noconvert(bool flag = true) {
1246 flag_noconvert = flag;
1247 return *this;
1248 }
1249 /// Indicates that the argument should/shouldn't allow None (e.g. for nullable pointer args)
1250 arg &none(bool flag = true) {
1251 flag_none = flag;
1252 return *this;
1253 }
1254
1255 const char *name; ///< If non-null, this is a named kwargs argument
1256 bool flag_noconvert : 1; ///< If set, do not allow conversion (requires a supporting type
1257 ///< caster!)
1258 bool flag_none : 1; ///< If set (the default), allow None to be passed to this argument
1259};
1260
1261/// \ingroup annotations
1262/// Annotation for arguments with values
1263struct arg_v : arg {
1264private:
1265 template <typename T>
1266 arg_v(arg &&base, T &&x, const char *descr = nullptr)
1267 : arg(base), value(reinterpret_steal<object>(detail::make_caster<T>::cast(
1268 std::forward<T>(x), return_value_policy::automatic, {}))),
1269 descr(descr)
1270#if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1271 ,
1272 type(type_id<T>())
1273#endif
1274 {
1275 // Workaround! See:
1276 // https://github.com/pybind/pybind11/issues/2336
1277 // https://github.com/pybind/pybind11/pull/2685#issuecomment-731286700
1278 if (PyErr_Occurred()) {
1279 PyErr_Clear();
1280 }
1281 }
1282
1283public:
1284 /// Direct construction with name, default, and description
1285 template <typename T>
1286 arg_v(const char *name, T &&x, const char *descr = nullptr)
1287 : arg_v(arg(name), std::forward<T>(x), descr) {}
1288
1289 /// Called internally when invoking `py::arg("a") = value`
1290 template <typename T>
1291 arg_v(const arg &base, T &&x, const char *descr = nullptr)
1292 : arg_v(arg(base), std::forward<T>(x), descr) {}
1293
1294 /// Same as `arg::noconvert()`, but returns *this as arg_v&, not arg&
1295 arg_v &noconvert(bool flag = true) {
1296 arg::noconvert(flag);
1297 return *this;
1298 }
1299
1300 /// Same as `arg::nonone()`, but returns *this as arg_v&, not arg&
1301 arg_v &none(bool flag = true) {
1302 arg::none(flag);
1303 return *this;
1304 }
1305
1306 /// The default value
1307 object value;
1308 /// The (optional) description of the default value
1309 const char *descr;
1310#if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1311 /// The C++ type name of the default value (only available when compiled in debug mode)
1312 std::string type;
1313#endif
1314};
1315
1316/// \ingroup annotations
1317/// Annotation indicating that all following arguments are keyword-only; the is the equivalent of
1318/// an unnamed '*' argument
1319struct kw_only {};
1320
1321/// \ingroup annotations
1322/// Annotation indicating that all previous arguments are positional-only; the is the equivalent of
1323/// an unnamed '/' argument (in Python 3.8)
1324struct pos_only {};
1325
1326template <typename T>
1327arg_v arg::operator=(T &&value) const {
1328 return {*this, std::forward<T>(value)};
1329}
1330
1331/// Alias for backward compatibility -- to be removed in version 2.0
1332template <typename /*unused*/>
1333using arg_t = arg_v;
1334
1335inline namespace literals {
1336/** \rst
1337 String literal version of `arg`
1338 \endrst */
1339constexpr arg operator"" _a(const char *name, size_t) { return arg(name); }
1340} // namespace literals
1341
1342PYBIND11_NAMESPACE_BEGIN(detail)
1343
1344template <typename T>
1345using is_kw_only = std::is_same<intrinsic_t<T>, kw_only>;
1346template <typename T>
1347using is_pos_only = std::is_same<intrinsic_t<T>, pos_only>;
1348
1349// forward declaration (definition in attr.h)
1350struct function_record;
1351
1352/// Internal data associated with a single function call
1353struct function_call {
1354 function_call(const function_record &f, handle p); // Implementation in attr.h
1355
1356 /// The function data:
1357 const function_record &func;
1358
1359 /// Arguments passed to the function:
1360 std::vector<handle> args;
1361
1362 /// The `convert` value the arguments should be loaded with
1363 std::vector<bool> args_convert;
1364
1365 /// Extra references for the optional `py::args` and/or `py::kwargs` arguments (which, if
1366 /// present, are also in `args` but without a reference).
1367 object args_ref, kwargs_ref;
1368
1369 /// The parent, if any
1370 handle parent;
1371
1372 /// If this is a call to an initializer, this argument contains `self`
1373 handle init_self;
1374};
1375
1376/// Helper class which loads arguments for C++ functions called from Python
1377template <typename... Args>
1378class argument_loader {
1379 using indices = make_index_sequence<sizeof...(Args)>;
1380
1381 template <typename Arg>
1382 using argument_is_args = std::is_same<intrinsic_t<Arg>, args>;
1383 template <typename Arg>
1384 using argument_is_kwargs = std::is_same<intrinsic_t<Arg>, kwargs>;
1385 // Get kwargs argument position, or -1 if not present:
1386 static constexpr auto kwargs_pos = constexpr_last<argument_is_kwargs, Args...>();
1387
1388 static_assert(kwargs_pos == -1 || kwargs_pos == (int) sizeof...(Args) - 1,
1389 "py::kwargs is only permitted as the last argument of a function");
1390
1391public:
1392 static constexpr bool has_kwargs = kwargs_pos != -1;
1393
1394 // py::args argument position; -1 if not present.
1395 static constexpr int args_pos = constexpr_last<argument_is_args, Args...>();
1396
1397 static_assert(args_pos == -1 || args_pos == constexpr_first<argument_is_args, Args...>(),
1398 "py::args cannot be specified more than once");
1399
1400 static constexpr auto arg_names = concat(type_descr(make_caster<Args>::name)...);
1401
1402 bool load_args(function_call &call) { return load_impl_sequence(call, indices{}); }
1403
1404 template <typename Return, typename Guard, typename Func>
1405 // NOLINTNEXTLINE(readability-const-return-type)
1406 enable_if_t<!std::is_void<Return>::value, Return> call(Func &&f) && {
1407 return std::move(*this).template call_impl<remove_cv_t<Return>>(
1408 std::forward<Func>(f), indices{}, Guard{});
1409 }
1410
1411 template <typename Return, typename Guard, typename Func>
1412 enable_if_t<std::is_void<Return>::value, void_type> call(Func &&f) && {
1413 std::move(*this).template call_impl<remove_cv_t<Return>>(
1414 std::forward<Func>(f), indices{}, Guard{});
1415 return void_type();
1416 }
1417
1418private:
1419 static bool load_impl_sequence(function_call &, index_sequence<>) { return true; }
1420
1421 template <size_t... Is>
1422 bool load_impl_sequence(function_call &call, index_sequence<Is...>) {
1423#ifdef __cpp_fold_expressions
1424 if ((... || !std::get<Is>(argcasters).load(call.args[Is], call.args_convert[Is]))) {
1425 return false;
1426 }
1427#else
1428 for (bool r : {std::get<Is>(argcasters).load(call.args[Is], call.args_convert[Is])...}) {
1429 if (!r) {
1430 return false;
1431 }
1432 }
1433#endif
1434 return true;
1435 }
1436
1437 template <typename Return, typename Func, size_t... Is, typename Guard>
1438 Return call_impl(Func &&f, index_sequence<Is...>, Guard &&) && {
1439 return std::forward<Func>(f)(cast_op<Args>(std::move(std::get<Is>(argcasters)))...);
1440 }
1441
1442 std::tuple<make_caster<Args>...> argcasters;
1443};
1444
1445/// Helper class which collects only positional arguments for a Python function call.
1446/// A fancier version below can collect any argument, but this one is optimal for simple calls.
1447template <return_value_policy policy>
1448class simple_collector {
1449public:
1450 template <typename... Ts>
1451 explicit simple_collector(Ts &&...values)
1452 : m_args(pybind11::make_tuple<policy>(std::forward<Ts>(values)...)) {}
1453
1454 const tuple &args() const & { return m_args; }
1455 dict kwargs() const { return {}; }
1456
1457 tuple args() && { return std::move(m_args); }
1458
1459 /// Call a Python function and pass the collected arguments
1460 object call(PyObject *ptr) const {
1461 PyObject *result = PyObject_CallObject(ptr, m_args.ptr());
1462 if (!result) {
1463 throw error_already_set();
1464 }
1465 return reinterpret_steal<object>(result);
1466 }
1467
1468private:
1469 tuple m_args;
1470};
1471
1472/// Helper class which collects positional, keyword, * and ** arguments for a Python function call
1473template <return_value_policy policy>
1474class unpacking_collector {
1475public:
1476 template <typename... Ts>
1477 explicit unpacking_collector(Ts &&...values) {
1478 // Tuples aren't (easily) resizable so a list is needed for collection,
1479 // but the actual function call strictly requires a tuple.
1480 auto args_list = list();
1481 using expander = int[];
1482 (void) expander{0, (process(args_list, std::forward<Ts>(values)), 0)...};
1483
1484 m_args = std::move(args_list);
1485 }
1486
1487 const tuple &args() const & { return m_args; }
1488 const dict &kwargs() const & { return m_kwargs; }
1489
1490 tuple args() && { return std::move(m_args); }
1491 dict kwargs() && { return std::move(m_kwargs); }
1492
1493 /// Call a Python function and pass the collected arguments
1494 object call(PyObject *ptr) const {
1495 PyObject *result = PyObject_Call(ptr, m_args.ptr(), m_kwargs.ptr());
1496 if (!result) {
1497 throw error_already_set();
1498 }
1499 return reinterpret_steal<object>(result);
1500 }
1501
1502private:
1503 template <typename T>
1504 void process(list &args_list, T &&x) {
1505 auto o = reinterpret_steal<object>(
1506 detail::make_caster<T>::cast(std::forward<T>(x), policy, {}));
1507 if (!o) {
1508#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1509 throw cast_error_unable_to_convert_call_arg();
1510#else
1511 throw cast_error_unable_to_convert_call_arg(std::to_string(args_list.size()),
1512 type_id<T>());
1513#endif
1514 }
1515 args_list.append(std::move(o));
1516 }
1517
1518 void process(list &args_list, detail::args_proxy ap) {
1519 for (auto a : ap) {
1520 args_list.append(a);
1521 }
1522 }
1523
1524 void process(list & /*args_list*/, arg_v a) {
1525 if (!a.name) {
1526#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1527 nameless_argument_error();
1528#else
1529 nameless_argument_error(a.type);
1530#endif
1531 }
1532 if (m_kwargs.contains(a.name)) {
1533#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1534 multiple_values_error();
1535#else
1536 multiple_values_error(a.name);
1537#endif
1538 }
1539 if (!a.value) {
1540#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1541 throw cast_error_unable_to_convert_call_arg();
1542#else
1543 throw cast_error_unable_to_convert_call_arg(a.name, a.type);
1544#endif
1545 }
1546 m_kwargs[a.name] = std::move(a.value);
1547 }
1548
1549 void process(list & /*args_list*/, detail::kwargs_proxy kp) {
1550 if (!kp) {
1551 return;
1552 }
1553 for (auto k : reinterpret_borrow<dict>(kp)) {
1554 if (m_kwargs.contains(k.first)) {
1555#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1556 multiple_values_error();
1557#else
1558 multiple_values_error(str(k.first));
1559#endif
1560 }
1561 m_kwargs[k.first] = k.second;
1562 }
1563 }
1564
1565 [[noreturn]] static void nameless_argument_error() {
1566 throw type_error(
1567 "Got kwargs without a name; only named arguments "
1568 "may be passed via py::arg() to a python function call. "
1569 "(#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1570 }
1571 [[noreturn]] static void nameless_argument_error(const std::string &type) {
1572 throw type_error("Got kwargs without a name of type '" + type
1573 + "'; only named "
1574 "arguments may be passed via py::arg() to a python function call. ");
1575 }
1576 [[noreturn]] static void multiple_values_error() {
1577 throw type_error(
1578 "Got multiple values for keyword argument "
1579 "(#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1580 }
1581
1582 [[noreturn]] static void multiple_values_error(const std::string &name) {
1583 throw type_error("Got multiple values for keyword argument '" + name + "'");
1584 }
1585
1586private:
1587 tuple m_args;
1588 dict m_kwargs;
1589};
1590
1591// [workaround(intel)] Separate function required here
1592// We need to put this into a separate function because the Intel compiler
1593// fails to compile enable_if_t<!all_of<is_positional<Args>...>::value>
1594// (tested with ICC 2021.1 Beta 20200827).
1595template <typename... Args>
1596constexpr bool args_are_all_positional() {
1597 return all_of<is_positional<Args>...>::value;
1598}
1599
1600/// Collect only positional arguments for a Python function call
1601template <return_value_policy policy,
1602 typename... Args,
1603 typename = enable_if_t<args_are_all_positional<Args...>()>>
1604simple_collector<policy> collect_arguments(Args &&...args) {
1605 return simple_collector<policy>(std::forward<Args>(args)...);
1606}
1607
1608/// Collect all arguments, including keywords and unpacking (only instantiated when needed)
1609template <return_value_policy policy,
1610 typename... Args,
1611 typename = enable_if_t<!args_are_all_positional<Args...>()>>
1612unpacking_collector<policy> collect_arguments(Args &&...args) {
1613 // Following argument order rules for generalized unpacking according to PEP 448
1614 static_assert(constexpr_last<is_positional, Args...>()
1615 < constexpr_first<is_keyword_or_ds, Args...>()
1616 && constexpr_last<is_s_unpacking, Args...>()
1617 < constexpr_first<is_ds_unpacking, Args...>(),
1618 "Invalid function call: positional args must precede keywords and ** unpacking; "
1619 "* unpacking must precede ** unpacking");
1620 return unpacking_collector<policy>(std::forward<Args>(args)...);
1621}
1622
1623template <typename Derived>
1624template <return_value_policy policy, typename... Args>
1625object object_api<Derived>::operator()(Args &&...args) const {
1626#ifndef NDEBUG
1627 if (!PyGILState_Check()) {
1628 pybind11_fail("pybind11::object_api<>::operator() PyGILState_Check() failure.");
1629 }
1630#endif
1631 return detail::collect_arguments<policy>(std::forward<Args>(args)...).call(derived().ptr());
1632}
1633
1634template <typename Derived>
1635template <return_value_policy policy, typename... Args>
1636object object_api<Derived>::call(Args &&...args) const {
1637 return operator()<policy>(std::forward<Args>(args)...);
1638}
1639
1640PYBIND11_NAMESPACE_END(detail)
1641
1642template <typename T>
1643handle type::handle_of() {
1644 static_assert(std::is_base_of<detail::type_caster_generic, detail::make_caster<T>>::value,
1645 "py::type::of<T> only supports the case where T is a registered C++ types.");
1646
1647 return detail::get_type_handle(typeid(T), true);
1648}
1649
1650#define PYBIND11_MAKE_OPAQUE(...) \
1651 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) \
1652 namespace detail { \
1653 template <> \
1654 class type_caster<__VA_ARGS__> : public type_caster_base<__VA_ARGS__> {}; \
1655 } \
1656 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
1657
1658/// Lets you pass a type containing a `,` through a macro parameter without needing a separate
1659/// typedef, e.g.:
1660/// `PYBIND11_OVERRIDE(PYBIND11_TYPE(ReturnType<A, B>), PYBIND11_TYPE(Parent<C, D>), f, arg)`
1661#define PYBIND11_TYPE(...) __VA_ARGS__
1662
1663PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
1664