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().inc_ref();
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().inc_ref();
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().inc_ref();
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_same<void, intrinsic_t<T>>::value, void> cast_safe(object &&) {}
1183template <typename T>
1184enable_if_t<detail::none_of<cast_is_temporary_value_reference<T>,
1185 std::is_same<void, intrinsic_t<T>>>::value,
1186 T>
1187cast_safe(object &&o) {
1188 return pybind11::cast<T>(std::move(o));
1189}
1190
1191PYBIND11_NAMESPACE_END(detail)
1192
1193// The overloads could coexist, i.e. the #if is not strictly speaking needed,
1194// but it is an easy minor optimization.
1195#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1196inline cast_error cast_error_unable_to_convert_call_arg() {
1197 return cast_error("Unable to convert call argument to Python object (#define "
1198 "PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1199}
1200#else
1201inline cast_error cast_error_unable_to_convert_call_arg(const std::string &name,
1202 const std::string &type) {
1203 return cast_error("Unable to convert call argument '" + name + "' of type '" + type
1204 + "' to Python object");
1205}
1206#endif
1207
1208template <return_value_policy policy = return_value_policy::automatic_reference>
1209tuple make_tuple() {
1210 return tuple(0);
1211}
1212
1213template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args>
1214tuple make_tuple(Args &&...args_) {
1215 constexpr size_t size = sizeof...(Args);
1216 std::array<object, size> args{{reinterpret_steal<object>(
1217 detail::make_caster<Args>::cast(std::forward<Args>(args_), policy, nullptr))...}};
1218 for (size_t i = 0; i < args.size(); i++) {
1219 if (!args[i]) {
1220#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1221 throw cast_error_unable_to_convert_call_arg();
1222#else
1223 std::array<std::string, size> argtypes{{type_id<Args>()...}};
1224 throw cast_error_unable_to_convert_call_arg(std::to_string(i), argtypes[i]);
1225#endif
1226 }
1227 }
1228 tuple result(size);
1229 int counter = 0;
1230 for (auto &arg_value : args) {
1231 PyTuple_SET_ITEM(result.ptr(), counter++, arg_value.release().ptr());
1232 }
1233 return result;
1234}
1235
1236/// \ingroup annotations
1237/// Annotation for arguments
1238struct arg {
1239 /// Constructs an argument with the name of the argument; if null or omitted, this is a
1240 /// positional argument.
1241 constexpr explicit arg(const char *name = nullptr)
1242 : name(name), flag_noconvert(false), flag_none(true) {}
1243 /// Assign a value to this argument
1244 template <typename T>
1245 arg_v operator=(T &&value) const;
1246 /// Indicate that the type should not be converted in the type caster
1247 arg &noconvert(bool flag = true) {
1248 flag_noconvert = flag;
1249 return *this;
1250 }
1251 /// Indicates that the argument should/shouldn't allow None (e.g. for nullable pointer args)
1252 arg &none(bool flag = true) {
1253 flag_none = flag;
1254 return *this;
1255 }
1256
1257 const char *name; ///< If non-null, this is a named kwargs argument
1258 bool flag_noconvert : 1; ///< If set, do not allow conversion (requires a supporting type
1259 ///< caster!)
1260 bool flag_none : 1; ///< If set (the default), allow None to be passed to this argument
1261};
1262
1263/// \ingroup annotations
1264/// Annotation for arguments with values
1265struct arg_v : arg {
1266private:
1267 template <typename T>
1268 arg_v(arg &&base, T &&x, const char *descr = nullptr)
1269 : arg(base), value(reinterpret_steal<object>(detail::make_caster<T>::cast(
1270 std::forward<T>(x), return_value_policy::automatic, {}))),
1271 descr(descr)
1272#if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1273 ,
1274 type(type_id<T>())
1275#endif
1276 {
1277 // Workaround! See:
1278 // https://github.com/pybind/pybind11/issues/2336
1279 // https://github.com/pybind/pybind11/pull/2685#issuecomment-731286700
1280 if (PyErr_Occurred()) {
1281 PyErr_Clear();
1282 }
1283 }
1284
1285public:
1286 /// Direct construction with name, default, and description
1287 template <typename T>
1288 arg_v(const char *name, T &&x, const char *descr = nullptr)
1289 : arg_v(arg(name), std::forward<T>(x), descr) {}
1290
1291 /// Called internally when invoking `py::arg("a") = value`
1292 template <typename T>
1293 arg_v(const arg &base, T &&x, const char *descr = nullptr)
1294 : arg_v(arg(base), std::forward<T>(x), descr) {}
1295
1296 /// Same as `arg::noconvert()`, but returns *this as arg_v&, not arg&
1297 arg_v &noconvert(bool flag = true) {
1298 arg::noconvert(flag);
1299 return *this;
1300 }
1301
1302 /// Same as `arg::nonone()`, but returns *this as arg_v&, not arg&
1303 arg_v &none(bool flag = true) {
1304 arg::none(flag);
1305 return *this;
1306 }
1307
1308 /// The default value
1309 object value;
1310 /// The (optional) description of the default value
1311 const char *descr;
1312#if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1313 /// The C++ type name of the default value (only available when compiled in debug mode)
1314 std::string type;
1315#endif
1316};
1317
1318/// \ingroup annotations
1319/// Annotation indicating that all following arguments are keyword-only; the is the equivalent of
1320/// an unnamed '*' argument
1321struct kw_only {};
1322
1323/// \ingroup annotations
1324/// Annotation indicating that all previous arguments are positional-only; the is the equivalent of
1325/// an unnamed '/' argument (in Python 3.8)
1326struct pos_only {};
1327
1328template <typename T>
1329arg_v arg::operator=(T &&value) const {
1330 return {*this, std::forward<T>(value)};
1331}
1332
1333/// Alias for backward compatibility -- to be removed in version 2.0
1334template <typename /*unused*/>
1335using arg_t = arg_v;
1336
1337inline namespace literals {
1338/** \rst
1339 String literal version of `arg`
1340 \endrst */
1341constexpr arg operator"" _a(const char *name, size_t) { return arg(name); }
1342} // namespace literals
1343
1344PYBIND11_NAMESPACE_BEGIN(detail)
1345
1346template <typename T>
1347using is_kw_only = std::is_same<intrinsic_t<T>, kw_only>;
1348template <typename T>
1349using is_pos_only = std::is_same<intrinsic_t<T>, pos_only>;
1350
1351// forward declaration (definition in attr.h)
1352struct function_record;
1353
1354/// Internal data associated with a single function call
1355struct function_call {
1356 function_call(const function_record &f, handle p); // Implementation in attr.h
1357
1358 /// The function data:
1359 const function_record &func;
1360
1361 /// Arguments passed to the function:
1362 std::vector<handle> args;
1363
1364 /// The `convert` value the arguments should be loaded with
1365 std::vector<bool> args_convert;
1366
1367 /// Extra references for the optional `py::args` and/or `py::kwargs` arguments (which, if
1368 /// present, are also in `args` but without a reference).
1369 object args_ref, kwargs_ref;
1370
1371 /// The parent, if any
1372 handle parent;
1373
1374 /// If this is a call to an initializer, this argument contains `self`
1375 handle init_self;
1376};
1377
1378/// Helper class which loads arguments for C++ functions called from Python
1379template <typename... Args>
1380class argument_loader {
1381 using indices = make_index_sequence<sizeof...(Args)>;
1382
1383 template <typename Arg>
1384 using argument_is_args = std::is_same<intrinsic_t<Arg>, args>;
1385 template <typename Arg>
1386 using argument_is_kwargs = std::is_same<intrinsic_t<Arg>, kwargs>;
1387 // Get kwargs argument position, or -1 if not present:
1388 static constexpr auto kwargs_pos = constexpr_last<argument_is_kwargs, Args...>();
1389
1390 static_assert(kwargs_pos == -1 || kwargs_pos == (int) sizeof...(Args) - 1,
1391 "py::kwargs is only permitted as the last argument of a function");
1392
1393public:
1394 static constexpr bool has_kwargs = kwargs_pos != -1;
1395
1396 // py::args argument position; -1 if not present.
1397 static constexpr int args_pos = constexpr_last<argument_is_args, Args...>();
1398
1399 static_assert(args_pos == -1 || args_pos == constexpr_first<argument_is_args, Args...>(),
1400 "py::args cannot be specified more than once");
1401
1402 static constexpr auto arg_names = concat(type_descr(make_caster<Args>::name)...);
1403
1404 bool load_args(function_call &call) { return load_impl_sequence(call, indices{}); }
1405
1406 template <typename Return, typename Guard, typename Func>
1407 // NOLINTNEXTLINE(readability-const-return-type)
1408 enable_if_t<!std::is_void<Return>::value, Return> call(Func &&f) && {
1409 return std::move(*this).template call_impl<remove_cv_t<Return>>(
1410 std::forward<Func>(f), indices{}, Guard{});
1411 }
1412
1413 template <typename Return, typename Guard, typename Func>
1414 enable_if_t<std::is_void<Return>::value, void_type> call(Func &&f) && {
1415 std::move(*this).template call_impl<remove_cv_t<Return>>(
1416 std::forward<Func>(f), indices{}, Guard{});
1417 return void_type();
1418 }
1419
1420private:
1421 static bool load_impl_sequence(function_call &, index_sequence<>) { return true; }
1422
1423 template <size_t... Is>
1424 bool load_impl_sequence(function_call &call, index_sequence<Is...>) {
1425#ifdef __cpp_fold_expressions
1426 if ((... || !std::get<Is>(argcasters).load(call.args[Is], call.args_convert[Is]))) {
1427 return false;
1428 }
1429#else
1430 for (bool r : {std::get<Is>(argcasters).load(call.args[Is], call.args_convert[Is])...}) {
1431 if (!r) {
1432 return false;
1433 }
1434 }
1435#endif
1436 return true;
1437 }
1438
1439 template <typename Return, typename Func, size_t... Is, typename Guard>
1440 Return call_impl(Func &&f, index_sequence<Is...>, Guard &&) && {
1441 return std::forward<Func>(f)(cast_op<Args>(std::move(std::get<Is>(argcasters)))...);
1442 }
1443
1444 std::tuple<make_caster<Args>...> argcasters;
1445};
1446
1447/// Helper class which collects only positional arguments for a Python function call.
1448/// A fancier version below can collect any argument, but this one is optimal for simple calls.
1449template <return_value_policy policy>
1450class simple_collector {
1451public:
1452 template <typename... Ts>
1453 explicit simple_collector(Ts &&...values)
1454 : m_args(pybind11::make_tuple<policy>(std::forward<Ts>(values)...)) {}
1455
1456 const tuple &args() const & { return m_args; }
1457 dict kwargs() const { return {}; }
1458
1459 tuple args() && { return std::move(m_args); }
1460
1461 /// Call a Python function and pass the collected arguments
1462 object call(PyObject *ptr) const {
1463 PyObject *result = PyObject_CallObject(ptr, m_args.ptr());
1464 if (!result) {
1465 throw error_already_set();
1466 }
1467 return reinterpret_steal<object>(result);
1468 }
1469
1470private:
1471 tuple m_args;
1472};
1473
1474/// Helper class which collects positional, keyword, * and ** arguments for a Python function call
1475template <return_value_policy policy>
1476class unpacking_collector {
1477public:
1478 template <typename... Ts>
1479 explicit unpacking_collector(Ts &&...values) {
1480 // Tuples aren't (easily) resizable so a list is needed for collection,
1481 // but the actual function call strictly requires a tuple.
1482 auto args_list = list();
1483 using expander = int[];
1484 (void) expander{0, (process(args_list, std::forward<Ts>(values)), 0)...};
1485
1486 m_args = std::move(args_list);
1487 }
1488
1489 const tuple &args() const & { return m_args; }
1490 const dict &kwargs() const & { return m_kwargs; }
1491
1492 tuple args() && { return std::move(m_args); }
1493 dict kwargs() && { return std::move(m_kwargs); }
1494
1495 /// Call a Python function and pass the collected arguments
1496 object call(PyObject *ptr) const {
1497 PyObject *result = PyObject_Call(ptr, m_args.ptr(), m_kwargs.ptr());
1498 if (!result) {
1499 throw error_already_set();
1500 }
1501 return reinterpret_steal<object>(result);
1502 }
1503
1504private:
1505 template <typename T>
1506 void process(list &args_list, T &&x) {
1507 auto o = reinterpret_steal<object>(
1508 detail::make_caster<T>::cast(std::forward<T>(x), policy, {}));
1509 if (!o) {
1510#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1511 throw cast_error_unable_to_convert_call_arg();
1512#else
1513 throw cast_error_unable_to_convert_call_arg(std::to_string(args_list.size()),
1514 type_id<T>());
1515#endif
1516 }
1517 args_list.append(std::move(o));
1518 }
1519
1520 void process(list &args_list, detail::args_proxy ap) {
1521 for (auto a : ap) {
1522 args_list.append(a);
1523 }
1524 }
1525
1526 void process(list & /*args_list*/, arg_v a) {
1527 if (!a.name) {
1528#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1529 nameless_argument_error();
1530#else
1531 nameless_argument_error(a.type);
1532#endif
1533 }
1534 if (m_kwargs.contains(a.name)) {
1535#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1536 multiple_values_error();
1537#else
1538 multiple_values_error(a.name);
1539#endif
1540 }
1541 if (!a.value) {
1542#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1543 throw cast_error_unable_to_convert_call_arg();
1544#else
1545 throw cast_error_unable_to_convert_call_arg(a.name, a.type);
1546#endif
1547 }
1548 m_kwargs[a.name] = a.value;
1549 }
1550
1551 void process(list & /*args_list*/, detail::kwargs_proxy kp) {
1552 if (!kp) {
1553 return;
1554 }
1555 for (auto k : reinterpret_borrow<dict>(kp)) {
1556 if (m_kwargs.contains(k.first)) {
1557#if !defined(PYBIND11_DETAILED_ERROR_MESSAGES)
1558 multiple_values_error();
1559#else
1560 multiple_values_error(str(k.first));
1561#endif
1562 }
1563 m_kwargs[k.first] = k.second;
1564 }
1565 }
1566
1567 [[noreturn]] static void nameless_argument_error() {
1568 throw type_error(
1569 "Got kwargs without a name; only named arguments "
1570 "may be passed via py::arg() to a python function call. "
1571 "(#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1572 }
1573 [[noreturn]] static void nameless_argument_error(const std::string &type) {
1574 throw type_error("Got kwargs without a name of type '" + type
1575 + "'; only named "
1576 "arguments may be passed via py::arg() to a python function call. ");
1577 }
1578 [[noreturn]] static void multiple_values_error() {
1579 throw type_error(
1580 "Got multiple values for keyword argument "
1581 "(#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for details)");
1582 }
1583
1584 [[noreturn]] static void multiple_values_error(const std::string &name) {
1585 throw type_error("Got multiple values for keyword argument '" + name + "'");
1586 }
1587
1588private:
1589 tuple m_args;
1590 dict m_kwargs;
1591};
1592
1593// [workaround(intel)] Separate function required here
1594// We need to put this into a separate function because the Intel compiler
1595// fails to compile enable_if_t<!all_of<is_positional<Args>...>::value>
1596// (tested with ICC 2021.1 Beta 20200827).
1597template <typename... Args>
1598constexpr bool args_are_all_positional() {
1599 return all_of<is_positional<Args>...>::value;
1600}
1601
1602/// Collect only positional arguments for a Python function call
1603template <return_value_policy policy,
1604 typename... Args,
1605 typename = enable_if_t<args_are_all_positional<Args...>()>>
1606simple_collector<policy> collect_arguments(Args &&...args) {
1607 return simple_collector<policy>(std::forward<Args>(args)...);
1608}
1609
1610/// Collect all arguments, including keywords and unpacking (only instantiated when needed)
1611template <return_value_policy policy,
1612 typename... Args,
1613 typename = enable_if_t<!args_are_all_positional<Args...>()>>
1614unpacking_collector<policy> collect_arguments(Args &&...args) {
1615 // Following argument order rules for generalized unpacking according to PEP 448
1616 static_assert(constexpr_last<is_positional, Args...>()
1617 < constexpr_first<is_keyword_or_ds, Args...>()
1618 && constexpr_last<is_s_unpacking, Args...>()
1619 < constexpr_first<is_ds_unpacking, Args...>(),
1620 "Invalid function call: positional args must precede keywords and ** unpacking; "
1621 "* unpacking must precede ** unpacking");
1622 return unpacking_collector<policy>(std::forward<Args>(args)...);
1623}
1624
1625template <typename Derived>
1626template <return_value_policy policy, typename... Args>
1627object object_api<Derived>::operator()(Args &&...args) const {
1628#ifndef NDEBUG
1629 if (!PyGILState_Check()) {
1630 pybind11_fail("pybind11::object_api<>::operator() PyGILState_Check() failure.");
1631 }
1632#endif
1633 return detail::collect_arguments<policy>(std::forward<Args>(args)...).call(derived().ptr());
1634}
1635
1636template <typename Derived>
1637template <return_value_policy policy, typename... Args>
1638object object_api<Derived>::call(Args &&...args) const {
1639 return operator()<policy>(std::forward<Args>(args)...);
1640}
1641
1642PYBIND11_NAMESPACE_END(detail)
1643
1644template <typename T>
1645handle type::handle_of() {
1646 static_assert(std::is_base_of<detail::type_caster_generic, detail::make_caster<T>>::value,
1647 "py::type::of<T> only supports the case where T is a registered C++ types.");
1648
1649 return detail::get_type_handle(typeid(T), true);
1650}
1651
1652#define PYBIND11_MAKE_OPAQUE(...) \
1653 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE) \
1654 namespace detail { \
1655 template <> \
1656 class type_caster<__VA_ARGS__> : public type_caster_base<__VA_ARGS__> {}; \
1657 } \
1658 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
1659
1660/// Lets you pass a type containing a `,` through a macro parameter without needing a separate
1661/// typedef, e.g.:
1662/// `PYBIND11_OVERRIDE(PYBIND11_TYPE(ReturnType<A, B>), PYBIND11_TYPE(Parent<C, D>), f, arg)`
1663#define PYBIND11_TYPE(...) __VA_ARGS__
1664
1665PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
1666