cast.h revision 12391:ceeca8b41e4b
1/* 2 pybind11/cast.h: Partial template specializations to cast between 3 C++ and Python types 4 5 Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch> 6 7 All rights reserved. Use of this source code is governed by a 8 BSD-style license that can be found in the LICENSE file. 9*/ 10 11#pragma once 12 13#include "pytypes.h" 14#include "detail/typeid.h" 15#include "detail/descr.h" 16#include "detail/internals.h" 17#include <array> 18#include <limits> 19#include <tuple> 20 21#if defined(PYBIND11_CPP17) 22# if defined(__has_include) 23# if __has_include(<string_view>) 24# define PYBIND11_HAS_STRING_VIEW 25# endif 26# elif defined(_MSC_VER) 27# define PYBIND11_HAS_STRING_VIEW 28# endif 29#endif 30#ifdef PYBIND11_HAS_STRING_VIEW 31#include <string_view> 32#endif 33 34NAMESPACE_BEGIN(PYBIND11_NAMESPACE) 35NAMESPACE_BEGIN(detail) 36 37/// A life support system for temporary objects created by `type_caster::load()`. 38/// Adding a patient will keep it alive up until the enclosing function returns. 39class loader_life_support { 40public: 41 /// A new patient frame is created when a function is entered 42 loader_life_support() { 43 get_internals().loader_patient_stack.push_back(nullptr); 44 } 45 46 /// ... and destroyed after it returns 47 ~loader_life_support() { 48 auto &stack = get_internals().loader_patient_stack; 49 if (stack.empty()) 50 pybind11_fail("loader_life_support: internal error"); 51 52 auto ptr = stack.back(); 53 stack.pop_back(); 54 Py_CLEAR(ptr); 55 56 // A heuristic to reduce the stack's capacity (e.g. after long recursive calls) 57 if (stack.capacity() > 16 && stack.size() != 0 && stack.capacity() / stack.size() > 2) 58 stack.shrink_to_fit(); 59 } 60 61 /// This can only be used inside a pybind11-bound function, either by `argument_loader` 62 /// at argument preparation time or by `py::cast()` at execution time. 63 PYBIND11_NOINLINE static void add_patient(handle h) { 64 auto &stack = get_internals().loader_patient_stack; 65 if (stack.empty()) 66 throw cast_error("When called outside a bound function, py::cast() cannot " 67 "do Python -> C++ conversions which require the creation " 68 "of temporary values"); 69 70 auto &list_ptr = stack.back(); 71 if (list_ptr == nullptr) { 72 list_ptr = PyList_New(1); 73 if (!list_ptr) 74 pybind11_fail("loader_life_support: error allocating list"); 75 PyList_SET_ITEM(list_ptr, 0, h.inc_ref().ptr()); 76 } else { 77 auto result = PyList_Append(list_ptr, h.ptr()); 78 if (result == -1) 79 pybind11_fail("loader_life_support: error adding patient"); 80 } 81 } 82}; 83 84// Gets the cache entry for the given type, creating it if necessary. The return value is the pair 85// returned by emplace, i.e. an iterator for the entry and a bool set to `true` if the entry was 86// just created. 87inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type); 88 89// Populates a just-created cache entry. 90PYBIND11_NOINLINE inline void all_type_info_populate(PyTypeObject *t, std::vector<type_info *> &bases) { 91 std::vector<PyTypeObject *> check; 92 for (handle parent : reinterpret_borrow<tuple>(t->tp_bases)) 93 check.push_back((PyTypeObject *) parent.ptr()); 94 95 auto const &type_dict = get_internals().registered_types_py; 96 for (size_t i = 0; i < check.size(); i++) { 97 auto type = check[i]; 98 // Ignore Python2 old-style class super type: 99 if (!PyType_Check((PyObject *) type)) continue; 100 101 // Check `type` in the current set of registered python types: 102 auto it = type_dict.find(type); 103 if (it != type_dict.end()) { 104 // We found a cache entry for it, so it's either pybind-registered or has pre-computed 105 // pybind bases, but we have to make sure we haven't already seen the type(s) before: we 106 // want to follow Python/virtual C++ rules that there should only be one instance of a 107 // common base. 108 for (auto *tinfo : it->second) { 109 // NB: Could use a second set here, rather than doing a linear search, but since 110 // having a large number of immediate pybind11-registered types seems fairly 111 // unlikely, that probably isn't worthwhile. 112 bool found = false; 113 for (auto *known : bases) { 114 if (known == tinfo) { found = true; break; } 115 } 116 if (!found) bases.push_back(tinfo); 117 } 118 } 119 else if (type->tp_bases) { 120 // It's some python type, so keep follow its bases classes to look for one or more 121 // registered types 122 if (i + 1 == check.size()) { 123 // When we're at the end, we can pop off the current element to avoid growing 124 // `check` when adding just one base (which is typical--i.e. when there is no 125 // multiple inheritance) 126 check.pop_back(); 127 i--; 128 } 129 for (handle parent : reinterpret_borrow<tuple>(type->tp_bases)) 130 check.push_back((PyTypeObject *) parent.ptr()); 131 } 132 } 133} 134 135/** 136 * Extracts vector of type_info pointers of pybind-registered roots of the given Python type. Will 137 * be just 1 pybind type for the Python type of a pybind-registered class, or for any Python-side 138 * derived class that uses single inheritance. Will contain as many types as required for a Python 139 * class that uses multiple inheritance to inherit (directly or indirectly) from multiple 140 * pybind-registered classes. Will be empty if neither the type nor any base classes are 141 * pybind-registered. 142 * 143 * The value is cached for the lifetime of the Python type. 144 */ 145inline const std::vector<detail::type_info *> &all_type_info(PyTypeObject *type) { 146 auto ins = all_type_info_get_cache(type); 147 if (ins.second) 148 // New cache entry: populate it 149 all_type_info_populate(type, ins.first->second); 150 151 return ins.first->second; 152} 153 154/** 155 * Gets a single pybind11 type info for a python type. Returns nullptr if neither the type nor any 156 * ancestors are pybind11-registered. Throws an exception if there are multiple bases--use 157 * `all_type_info` instead if you want to support multiple bases. 158 */ 159PYBIND11_NOINLINE inline detail::type_info* get_type_info(PyTypeObject *type) { 160 auto &bases = all_type_info(type); 161 if (bases.size() == 0) 162 return nullptr; 163 if (bases.size() > 1) 164 pybind11_fail("pybind11::detail::get_type_info: type has multiple pybind11-registered bases"); 165 return bases.front(); 166} 167 168inline detail::type_info *get_local_type_info(const std::type_index &tp) { 169 auto &locals = registered_local_types_cpp(); 170 auto it = locals.find(tp); 171 if (it != locals.end()) 172 return it->second; 173 return nullptr; 174} 175 176inline detail::type_info *get_global_type_info(const std::type_index &tp) { 177 auto &types = get_internals().registered_types_cpp; 178 auto it = types.find(tp); 179 if (it != types.end()) 180 return it->second; 181 return nullptr; 182} 183 184/// Return the type info for a given C++ type; on lookup failure can either throw or return nullptr. 185PYBIND11_NOINLINE inline detail::type_info *get_type_info(const std::type_index &tp, 186 bool throw_if_missing = false) { 187 if (auto ltype = get_local_type_info(tp)) 188 return ltype; 189 if (auto gtype = get_global_type_info(tp)) 190 return gtype; 191 192 if (throw_if_missing) { 193 std::string tname = tp.name(); 194 detail::clean_type_id(tname); 195 pybind11_fail("pybind11::detail::get_type_info: unable to find type info for \"" + tname + "\""); 196 } 197 return nullptr; 198} 199 200PYBIND11_NOINLINE inline handle get_type_handle(const std::type_info &tp, bool throw_if_missing) { 201 detail::type_info *type_info = get_type_info(tp, throw_if_missing); 202 return handle(type_info ? ((PyObject *) type_info->type) : nullptr); 203} 204 205struct value_and_holder { 206 instance *inst; 207 size_t index; 208 const detail::type_info *type; 209 void **vh; 210 211 // Main constructor for a found value/holder: 212 value_and_holder(instance *i, const detail::type_info *type, size_t vpos, size_t index) : 213 inst{i}, index{index}, type{type}, 214 vh{inst->simple_layout ? inst->simple_value_holder : &inst->nonsimple.values_and_holders[vpos]} 215 {} 216 217 // Default constructor (used to signal a value-and-holder not found by get_value_and_holder()) 218 value_and_holder() : inst{nullptr} {} 219 220 // Used for past-the-end iterator 221 value_and_holder(size_t index) : index{index} {} 222 223 template <typename V = void> V *&value_ptr() const { 224 return reinterpret_cast<V *&>(vh[0]); 225 } 226 // True if this `value_and_holder` has a non-null value pointer 227 explicit operator bool() const { return value_ptr(); } 228 229 template <typename H> H &holder() const { 230 return reinterpret_cast<H &>(vh[1]); 231 } 232 bool holder_constructed() const { 233 return inst->simple_layout 234 ? inst->simple_holder_constructed 235 : inst->nonsimple.status[index] & instance::status_holder_constructed; 236 } 237 void set_holder_constructed(bool v = true) { 238 if (inst->simple_layout) 239 inst->simple_holder_constructed = v; 240 else if (v) 241 inst->nonsimple.status[index] |= instance::status_holder_constructed; 242 else 243 inst->nonsimple.status[index] &= (uint8_t) ~instance::status_holder_constructed; 244 } 245 bool instance_registered() const { 246 return inst->simple_layout 247 ? inst->simple_instance_registered 248 : inst->nonsimple.status[index] & instance::status_instance_registered; 249 } 250 void set_instance_registered(bool v = true) { 251 if (inst->simple_layout) 252 inst->simple_instance_registered = v; 253 else if (v) 254 inst->nonsimple.status[index] |= instance::status_instance_registered; 255 else 256 inst->nonsimple.status[index] &= (uint8_t) ~instance::status_instance_registered; 257 } 258}; 259 260// Container for accessing and iterating over an instance's values/holders 261struct values_and_holders { 262private: 263 instance *inst; 264 using type_vec = std::vector<detail::type_info *>; 265 const type_vec &tinfo; 266 267public: 268 values_and_holders(instance *inst) : inst{inst}, tinfo(all_type_info(Py_TYPE(inst))) {} 269 270 struct iterator { 271 private: 272 instance *inst; 273 const type_vec *types; 274 value_and_holder curr; 275 friend struct values_and_holders; 276 iterator(instance *inst, const type_vec *tinfo) 277 : inst{inst}, types{tinfo}, 278 curr(inst /* instance */, 279 types->empty() ? nullptr : (*types)[0] /* type info */, 280 0, /* vpos: (non-simple types only): the first vptr comes first */ 281 0 /* index */) 282 {} 283 // Past-the-end iterator: 284 iterator(size_t end) : curr(end) {} 285 public: 286 bool operator==(const iterator &other) { return curr.index == other.curr.index; } 287 bool operator!=(const iterator &other) { return curr.index != other.curr.index; } 288 iterator &operator++() { 289 if (!inst->simple_layout) 290 curr.vh += 1 + (*types)[curr.index]->holder_size_in_ptrs; 291 ++curr.index; 292 curr.type = curr.index < types->size() ? (*types)[curr.index] : nullptr; 293 return *this; 294 } 295 value_and_holder &operator*() { return curr; } 296 value_and_holder *operator->() { return &curr; } 297 }; 298 299 iterator begin() { return iterator(inst, &tinfo); } 300 iterator end() { return iterator(tinfo.size()); } 301 302 iterator find(const type_info *find_type) { 303 auto it = begin(), endit = end(); 304 while (it != endit && it->type != find_type) ++it; 305 return it; 306 } 307 308 size_t size() { return tinfo.size(); } 309}; 310 311/** 312 * Extracts C++ value and holder pointer references from an instance (which may contain multiple 313 * values/holders for python-side multiple inheritance) that match the given type. Throws an error 314 * if the given type (or ValueType, if omitted) is not a pybind11 base of the given instance. If 315 * `find_type` is omitted (or explicitly specified as nullptr) the first value/holder are returned, 316 * regardless of type (and the resulting .type will be nullptr). 317 * 318 * The returned object should be short-lived: in particular, it must not outlive the called-upon 319 * instance. 320 */ 321PYBIND11_NOINLINE inline value_and_holder instance::get_value_and_holder(const type_info *find_type /*= nullptr default in common.h*/, bool throw_if_missing /*= true in common.h*/) { 322 // Optimize common case: 323 if (!find_type || Py_TYPE(this) == find_type->type) 324 return value_and_holder(this, find_type, 0, 0); 325 326 detail::values_and_holders vhs(this); 327 auto it = vhs.find(find_type); 328 if (it != vhs.end()) 329 return *it; 330 331 if (!throw_if_missing) 332 return value_and_holder(); 333 334#if defined(NDEBUG) 335 pybind11_fail("pybind11::detail::instance::get_value_and_holder: " 336 "type is not a pybind11 base of the given instance " 337 "(compile in debug mode for type details)"); 338#else 339 pybind11_fail("pybind11::detail::instance::get_value_and_holder: `" + 340 std::string(find_type->type->tp_name) + "' is not a pybind11 base of the given `" + 341 std::string(Py_TYPE(this)->tp_name) + "' instance"); 342#endif 343} 344 345PYBIND11_NOINLINE inline void instance::allocate_layout() { 346 auto &tinfo = all_type_info(Py_TYPE(this)); 347 348 const size_t n_types = tinfo.size(); 349 350 if (n_types == 0) 351 pybind11_fail("instance allocation failed: new instance has no pybind11-registered base types"); 352 353 simple_layout = 354 n_types == 1 && tinfo.front()->holder_size_in_ptrs <= instance_simple_holder_in_ptrs(); 355 356 // Simple path: no python-side multiple inheritance, and a small-enough holder 357 if (simple_layout) { 358 simple_value_holder[0] = nullptr; 359 simple_holder_constructed = false; 360 simple_instance_registered = false; 361 } 362 else { // multiple base types or a too-large holder 363 // Allocate space to hold: [v1*][h1][v2*][h2]...[bb...] where [vN*] is a value pointer, 364 // [hN] is the (uninitialized) holder instance for value N, and [bb...] is a set of bool 365 // values that tracks whether each associated holder has been initialized. Each [block] is 366 // padded, if necessary, to an integer multiple of sizeof(void *). 367 size_t space = 0; 368 for (auto t : tinfo) { 369 space += 1; // value pointer 370 space += t->holder_size_in_ptrs; // holder instance 371 } 372 size_t flags_at = space; 373 space += size_in_ptrs(n_types); // status bytes (holder_constructed and instance_registered) 374 375 // Allocate space for flags, values, and holders, and initialize it to 0 (flags and values, 376 // in particular, need to be 0). Use Python's memory allocation functions: in Python 3.6 377 // they default to using pymalloc, which is designed to be efficient for small allocations 378 // like the one we're doing here; in earlier versions (and for larger allocations) they are 379 // just wrappers around malloc. 380#if PY_VERSION_HEX >= 0x03050000 381 nonsimple.values_and_holders = (void **) PyMem_Calloc(space, sizeof(void *)); 382 if (!nonsimple.values_and_holders) throw std::bad_alloc(); 383#else 384 nonsimple.values_and_holders = (void **) PyMem_New(void *, space); 385 if (!nonsimple.values_and_holders) throw std::bad_alloc(); 386 std::memset(nonsimple.values_and_holders, 0, space * sizeof(void *)); 387#endif 388 nonsimple.status = reinterpret_cast<uint8_t *>(&nonsimple.values_and_holders[flags_at]); 389 } 390 owned = true; 391} 392 393PYBIND11_NOINLINE inline void instance::deallocate_layout() { 394 if (!simple_layout) 395 PyMem_Free(nonsimple.values_and_holders); 396} 397 398PYBIND11_NOINLINE inline bool isinstance_generic(handle obj, const std::type_info &tp) { 399 handle type = detail::get_type_handle(tp, false); 400 if (!type) 401 return false; 402 return isinstance(obj, type); 403} 404 405PYBIND11_NOINLINE inline std::string error_string() { 406 if (!PyErr_Occurred()) { 407 PyErr_SetString(PyExc_RuntimeError, "Unknown internal error occurred"); 408 return "Unknown internal error occurred"; 409 } 410 411 error_scope scope; // Preserve error state 412 413 std::string errorString; 414 if (scope.type) { 415 errorString += handle(scope.type).attr("__name__").cast<std::string>(); 416 errorString += ": "; 417 } 418 if (scope.value) 419 errorString += (std::string) str(scope.value); 420 421 PyErr_NormalizeException(&scope.type, &scope.value, &scope.trace); 422 423#if PY_MAJOR_VERSION >= 3 424 if (scope.trace != nullptr) 425 PyException_SetTraceback(scope.value, scope.trace); 426#endif 427 428#if !defined(PYPY_VERSION) 429 if (scope.trace) { 430 PyTracebackObject *trace = (PyTracebackObject *) scope.trace; 431 432 /* Get the deepest trace possible */ 433 while (trace->tb_next) 434 trace = trace->tb_next; 435 436 PyFrameObject *frame = trace->tb_frame; 437 errorString += "\n\nAt:\n"; 438 while (frame) { 439 int lineno = PyFrame_GetLineNumber(frame); 440 errorString += 441 " " + handle(frame->f_code->co_filename).cast<std::string>() + 442 "(" + std::to_string(lineno) + "): " + 443 handle(frame->f_code->co_name).cast<std::string>() + "\n"; 444 frame = frame->f_back; 445 } 446 } 447#endif 448 449 return errorString; 450} 451 452PYBIND11_NOINLINE inline handle get_object_handle(const void *ptr, const detail::type_info *type ) { 453 auto &instances = get_internals().registered_instances; 454 auto range = instances.equal_range(ptr); 455 for (auto it = range.first; it != range.second; ++it) { 456 for (auto vh : values_and_holders(it->second)) { 457 if (vh.type == type) 458 return handle((PyObject *) it->second); 459 } 460 } 461 return handle(); 462} 463 464inline PyThreadState *get_thread_state_unchecked() { 465#if defined(PYPY_VERSION) 466 return PyThreadState_GET(); 467#elif PY_VERSION_HEX < 0x03000000 468 return _PyThreadState_Current; 469#elif PY_VERSION_HEX < 0x03050000 470 return (PyThreadState*) _Py_atomic_load_relaxed(&_PyThreadState_Current); 471#elif PY_VERSION_HEX < 0x03050200 472 return (PyThreadState*) _PyThreadState_Current.value; 473#else 474 return _PyThreadState_UncheckedGet(); 475#endif 476} 477 478// Forward declarations 479inline void keep_alive_impl(handle nurse, handle patient); 480inline PyObject *make_new_instance(PyTypeObject *type); 481 482class type_caster_generic { 483public: 484 PYBIND11_NOINLINE type_caster_generic(const std::type_info &type_info) 485 : typeinfo(get_type_info(type_info)), cpptype(&type_info) { } 486 487 type_caster_generic(const type_info *typeinfo) 488 : typeinfo(typeinfo), cpptype(typeinfo ? typeinfo->cpptype : nullptr) { } 489 490 bool load(handle src, bool convert) { 491 return load_impl<type_caster_generic>(src, convert); 492 } 493 494 PYBIND11_NOINLINE static handle cast(const void *_src, return_value_policy policy, handle parent, 495 const detail::type_info *tinfo, 496 void *(*copy_constructor)(const void *), 497 void *(*move_constructor)(const void *), 498 const void *existing_holder = nullptr) { 499 if (!tinfo) // no type info: error will be set already 500 return handle(); 501 502 void *src = const_cast<void *>(_src); 503 if (src == nullptr) 504 return none().release(); 505 506 auto it_instances = get_internals().registered_instances.equal_range(src); 507 for (auto it_i = it_instances.first; it_i != it_instances.second; ++it_i) { 508 for (auto instance_type : detail::all_type_info(Py_TYPE(it_i->second))) { 509 if (instance_type && same_type(*instance_type->cpptype, *tinfo->cpptype)) 510 return handle((PyObject *) it_i->second).inc_ref(); 511 } 512 } 513 514 auto inst = reinterpret_steal<object>(make_new_instance(tinfo->type)); 515 auto wrapper = reinterpret_cast<instance *>(inst.ptr()); 516 wrapper->owned = false; 517 void *&valueptr = values_and_holders(wrapper).begin()->value_ptr(); 518 519 switch (policy) { 520 case return_value_policy::automatic: 521 case return_value_policy::take_ownership: 522 valueptr = src; 523 wrapper->owned = true; 524 break; 525 526 case return_value_policy::automatic_reference: 527 case return_value_policy::reference: 528 valueptr = src; 529 wrapper->owned = false; 530 break; 531 532 case return_value_policy::copy: 533 if (copy_constructor) 534 valueptr = copy_constructor(src); 535 else 536 throw cast_error("return_value_policy = copy, but the " 537 "object is non-copyable!"); 538 wrapper->owned = true; 539 break; 540 541 case return_value_policy::move: 542 if (move_constructor) 543 valueptr = move_constructor(src); 544 else if (copy_constructor) 545 valueptr = copy_constructor(src); 546 else 547 throw cast_error("return_value_policy = move, but the " 548 "object is neither movable nor copyable!"); 549 wrapper->owned = true; 550 break; 551 552 case return_value_policy::reference_internal: 553 valueptr = src; 554 wrapper->owned = false; 555 keep_alive_impl(inst, parent); 556 break; 557 558 default: 559 throw cast_error("unhandled return_value_policy: should not happen!"); 560 } 561 562 tinfo->init_instance(wrapper, existing_holder); 563 564 return inst.release(); 565 } 566 567 // Base methods for generic caster; there are overridden in copyable_holder_caster 568 void load_value(value_and_holder &&v_h) { 569 auto *&vptr = v_h.value_ptr(); 570 // Lazy allocation for unallocated values: 571 if (vptr == nullptr) { 572 auto *type = v_h.type ? v_h.type : typeinfo; 573 vptr = type->operator_new(type->type_size); 574 } 575 value = vptr; 576 } 577 bool try_implicit_casts(handle src, bool convert) { 578 for (auto &cast : typeinfo->implicit_casts) { 579 type_caster_generic sub_caster(*cast.first); 580 if (sub_caster.load(src, convert)) { 581 value = cast.second(sub_caster.value); 582 return true; 583 } 584 } 585 return false; 586 } 587 bool try_direct_conversions(handle src) { 588 for (auto &converter : *typeinfo->direct_conversions) { 589 if (converter(src.ptr(), value)) 590 return true; 591 } 592 return false; 593 } 594 void check_holder_compat() {} 595 596 PYBIND11_NOINLINE static void *local_load(PyObject *src, const type_info *ti) { 597 auto caster = type_caster_generic(ti); 598 if (caster.load(src, false)) 599 return caster.value; 600 return nullptr; 601 } 602 603 /// Try to load with foreign typeinfo, if available. Used when there is no 604 /// native typeinfo, or when the native one wasn't able to produce a value. 605 PYBIND11_NOINLINE bool try_load_foreign_module_local(handle src) { 606 constexpr auto *local_key = PYBIND11_MODULE_LOCAL_ID; 607 const auto pytype = src.get_type(); 608 if (!hasattr(pytype, local_key)) 609 return false; 610 611 type_info *foreign_typeinfo = reinterpret_borrow<capsule>(getattr(pytype, local_key)); 612 // Only consider this foreign loader if actually foreign and is a loader of the correct cpp type 613 if (foreign_typeinfo->module_local_load == &local_load 614 || (cpptype && !same_type(*cpptype, *foreign_typeinfo->cpptype))) 615 return false; 616 617 if (auto result = foreign_typeinfo->module_local_load(src.ptr(), foreign_typeinfo)) { 618 value = result; 619 return true; 620 } 621 return false; 622 } 623 624 // Implementation of `load`; this takes the type of `this` so that it can dispatch the relevant 625 // bits of code between here and copyable_holder_caster where the two classes need different 626 // logic (without having to resort to virtual inheritance). 627 template <typename ThisT> 628 PYBIND11_NOINLINE bool load_impl(handle src, bool convert) { 629 if (!src) return false; 630 if (!typeinfo) return try_load_foreign_module_local(src); 631 if (src.is_none()) { 632 // Defer accepting None to other overloads (if we aren't in convert mode): 633 if (!convert) return false; 634 value = nullptr; 635 return true; 636 } 637 638 auto &this_ = static_cast<ThisT &>(*this); 639 this_.check_holder_compat(); 640 641 PyTypeObject *srctype = Py_TYPE(src.ptr()); 642 643 // Case 1: If src is an exact type match for the target type then we can reinterpret_cast 644 // the instance's value pointer to the target type: 645 if (srctype == typeinfo->type) { 646 this_.load_value(reinterpret_cast<instance *>(src.ptr())->get_value_and_holder()); 647 return true; 648 } 649 // Case 2: We have a derived class 650 else if (PyType_IsSubtype(srctype, typeinfo->type)) { 651 auto &bases = all_type_info(srctype); 652 bool no_cpp_mi = typeinfo->simple_type; 653 654 // Case 2a: the python type is a Python-inherited derived class that inherits from just 655 // one simple (no MI) pybind11 class, or is an exact match, so the C++ instance is of 656 // the right type and we can use reinterpret_cast. 657 // (This is essentially the same as case 2b, but because not using multiple inheritance 658 // is extremely common, we handle it specially to avoid the loop iterator and type 659 // pointer lookup overhead) 660 if (bases.size() == 1 && (no_cpp_mi || bases.front()->type == typeinfo->type)) { 661 this_.load_value(reinterpret_cast<instance *>(src.ptr())->get_value_and_holder()); 662 return true; 663 } 664 // Case 2b: the python type inherits from multiple C++ bases. Check the bases to see if 665 // we can find an exact match (or, for a simple C++ type, an inherited match); if so, we 666 // can safely reinterpret_cast to the relevant pointer. 667 else if (bases.size() > 1) { 668 for (auto base : bases) { 669 if (no_cpp_mi ? PyType_IsSubtype(base->type, typeinfo->type) : base->type == typeinfo->type) { 670 this_.load_value(reinterpret_cast<instance *>(src.ptr())->get_value_and_holder(base)); 671 return true; 672 } 673 } 674 } 675 676 // Case 2c: C++ multiple inheritance is involved and we couldn't find an exact type match 677 // in the registered bases, above, so try implicit casting (needed for proper C++ casting 678 // when MI is involved). 679 if (this_.try_implicit_casts(src, convert)) 680 return true; 681 } 682 683 // Perform an implicit conversion 684 if (convert) { 685 for (auto &converter : typeinfo->implicit_conversions) { 686 auto temp = reinterpret_steal<object>(converter(src.ptr(), typeinfo->type)); 687 if (load_impl<ThisT>(temp, false)) { 688 loader_life_support::add_patient(temp); 689 return true; 690 } 691 } 692 if (this_.try_direct_conversions(src)) 693 return true; 694 } 695 696 // Failed to match local typeinfo. Try again with global. 697 if (typeinfo->module_local) { 698 if (auto gtype = get_global_type_info(*typeinfo->cpptype)) { 699 typeinfo = gtype; 700 return load(src, false); 701 } 702 } 703 704 // Global typeinfo has precedence over foreign module_local 705 return try_load_foreign_module_local(src); 706 } 707 708 709 // Called to do type lookup and wrap the pointer and type in a pair when a dynamic_cast 710 // isn't needed or can't be used. If the type is unknown, sets the error and returns a pair 711 // with .second = nullptr. (p.first = nullptr is not an error: it becomes None). 712 PYBIND11_NOINLINE static std::pair<const void *, const type_info *> src_and_type( 713 const void *src, const std::type_info &cast_type, const std::type_info *rtti_type = nullptr) { 714 if (auto *tpi = get_type_info(cast_type)) 715 return {src, const_cast<const type_info *>(tpi)}; 716 717 // Not found, set error: 718 std::string tname = rtti_type ? rtti_type->name() : cast_type.name(); 719 detail::clean_type_id(tname); 720 std::string msg = "Unregistered type : " + tname; 721 PyErr_SetString(PyExc_TypeError, msg.c_str()); 722 return {nullptr, nullptr}; 723 } 724 725 const type_info *typeinfo = nullptr; 726 const std::type_info *cpptype = nullptr; 727 void *value = nullptr; 728}; 729 730/** 731 * Determine suitable casting operator for pointer-or-lvalue-casting type casters. The type caster 732 * needs to provide `operator T*()` and `operator T&()` operators. 733 * 734 * If the type supports moving the value away via an `operator T&&() &&` method, it should use 735 * `movable_cast_op_type` instead. 736 */ 737template <typename T> 738using cast_op_type = 739 conditional_t<std::is_pointer<remove_reference_t<T>>::value, 740 typename std::add_pointer<intrinsic_t<T>>::type, 741 typename std::add_lvalue_reference<intrinsic_t<T>>::type>; 742 743/** 744 * Determine suitable casting operator for a type caster with a movable value. Such a type caster 745 * needs to provide `operator T*()`, `operator T&()`, and `operator T&&() &&`. The latter will be 746 * called in appropriate contexts where the value can be moved rather than copied. 747 * 748 * These operator are automatically provided when using the PYBIND11_TYPE_CASTER macro. 749 */ 750template <typename T> 751using movable_cast_op_type = 752 conditional_t<std::is_pointer<typename std::remove_reference<T>::type>::value, 753 typename std::add_pointer<intrinsic_t<T>>::type, 754 conditional_t<std::is_rvalue_reference<T>::value, 755 typename std::add_rvalue_reference<intrinsic_t<T>>::type, 756 typename std::add_lvalue_reference<intrinsic_t<T>>::type>>; 757 758// std::is_copy_constructible isn't quite enough: it lets std::vector<T> (and similar) through when 759// T is non-copyable, but code containing such a copy constructor fails to actually compile. 760template <typename T, typename SFINAE = void> struct is_copy_constructible : std::is_copy_constructible<T> {}; 761 762// Specialization for types that appear to be copy constructible but also look like stl containers 763// (we specifically check for: has `value_type` and `reference` with `reference = value_type&`): if 764// so, copy constructability depends on whether the value_type is copy constructible. 765template <typename Container> struct is_copy_constructible<Container, enable_if_t<all_of< 766 std::is_copy_constructible<Container>, 767 std::is_same<typename Container::value_type &, typename Container::reference> 768 >::value>> : is_copy_constructible<typename Container::value_type> {}; 769 770#if !defined(PYBIND11_CPP17) 771// Likewise for std::pair before C++17 (which mandates that the copy constructor not exist when the 772// two types aren't themselves copy constructible). 773template <typename T1, typename T2> struct is_copy_constructible<std::pair<T1, T2>> 774 : all_of<is_copy_constructible<T1>, is_copy_constructible<T2>> {}; 775#endif 776 777/// Generic type caster for objects stored on the heap 778template <typename type> class type_caster_base : public type_caster_generic { 779 using itype = intrinsic_t<type>; 780public: 781 static PYBIND11_DESCR name() { return type_descr(_<type>()); } 782 783 type_caster_base() : type_caster_base(typeid(type)) { } 784 explicit type_caster_base(const std::type_info &info) : type_caster_generic(info) { } 785 786 static handle cast(const itype &src, return_value_policy policy, handle parent) { 787 if (policy == return_value_policy::automatic || policy == return_value_policy::automatic_reference) 788 policy = return_value_policy::copy; 789 return cast(&src, policy, parent); 790 } 791 792 static handle cast(itype &&src, return_value_policy, handle parent) { 793 return cast(&src, return_value_policy::move, parent); 794 } 795 796 // Returns a (pointer, type_info) pair taking care of necessary RTTI type lookup for a 797 // polymorphic type. If the instance isn't derived, returns the non-RTTI base version. 798 template <typename T = itype, enable_if_t<std::is_polymorphic<T>::value, int> = 0> 799 static std::pair<const void *, const type_info *> src_and_type(const itype *src) { 800 const void *vsrc = src; 801 auto &cast_type = typeid(itype); 802 const std::type_info *instance_type = nullptr; 803 if (vsrc) { 804 instance_type = &typeid(*src); 805 if (!same_type(cast_type, *instance_type)) { 806 // This is a base pointer to a derived type; if it is a pybind11-registered type, we 807 // can get the correct derived pointer (which may be != base pointer) by a 808 // dynamic_cast to most derived type: 809 if (auto *tpi = get_type_info(*instance_type)) 810 return {dynamic_cast<const void *>(src), const_cast<const type_info *>(tpi)}; 811 } 812 } 813 // Otherwise we have either a nullptr, an `itype` pointer, or an unknown derived pointer, so 814 // don't do a cast 815 return type_caster_generic::src_and_type(vsrc, cast_type, instance_type); 816 } 817 818 // Non-polymorphic type, so no dynamic casting; just call the generic version directly 819 template <typename T = itype, enable_if_t<!std::is_polymorphic<T>::value, int> = 0> 820 static std::pair<const void *, const type_info *> src_and_type(const itype *src) { 821 return type_caster_generic::src_and_type(src, typeid(itype)); 822 } 823 824 static handle cast(const itype *src, return_value_policy policy, handle parent) { 825 auto st = src_and_type(src); 826 return type_caster_generic::cast( 827 st.first, policy, parent, st.second, 828 make_copy_constructor(src), make_move_constructor(src)); 829 } 830 831 static handle cast_holder(const itype *src, const void *holder) { 832 auto st = src_and_type(src); 833 return type_caster_generic::cast( 834 st.first, return_value_policy::take_ownership, {}, st.second, 835 nullptr, nullptr, holder); 836 } 837 838 template <typename T> using cast_op_type = cast_op_type<T>; 839 840 operator itype*() { return (type *) value; } 841 operator itype&() { if (!value) throw reference_cast_error(); return *((itype *) value); } 842 843protected: 844 using Constructor = void *(*)(const void *); 845 846 /* Only enabled when the types are {copy,move}-constructible *and* when the type 847 does not have a private operator new implementation. */ 848 template <typename T, typename = enable_if_t<is_copy_constructible<T>::value>> 849 static auto make_copy_constructor(const T *x) -> decltype(new T(*x), Constructor{}) { 850 return [](const void *arg) -> void * { 851 return new T(*reinterpret_cast<const T *>(arg)); 852 }; 853 } 854 855 template <typename T, typename = enable_if_t<std::is_move_constructible<T>::value>> 856 static auto make_move_constructor(const T *x) -> decltype(new T(std::move(*const_cast<T *>(x))), Constructor{}) { 857 return [](const void *arg) -> void * { 858 return new T(std::move(*const_cast<T *>(reinterpret_cast<const T *>(arg)))); 859 }; 860 } 861 862 static Constructor make_copy_constructor(...) { return nullptr; } 863 static Constructor make_move_constructor(...) { return nullptr; } 864}; 865 866template <typename type, typename SFINAE = void> class type_caster : public type_caster_base<type> { }; 867template <typename type> using make_caster = type_caster<intrinsic_t<type>>; 868 869// Shortcut for calling a caster's `cast_op_type` cast operator for casting a type_caster to a T 870template <typename T> typename make_caster<T>::template cast_op_type<T> cast_op(make_caster<T> &caster) { 871 return caster.operator typename make_caster<T>::template cast_op_type<T>(); 872} 873template <typename T> typename make_caster<T>::template cast_op_type<typename std::add_rvalue_reference<T>::type> 874cast_op(make_caster<T> &&caster) { 875 return std::move(caster).operator 876 typename make_caster<T>::template cast_op_type<typename std::add_rvalue_reference<T>::type>(); 877} 878 879template <typename type> class type_caster<std::reference_wrapper<type>> { 880private: 881 using caster_t = make_caster<type>; 882 caster_t subcaster; 883 using subcaster_cast_op_type = typename caster_t::template cast_op_type<type>; 884 static_assert(std::is_same<typename std::remove_const<type>::type &, subcaster_cast_op_type>::value, 885 "std::reference_wrapper<T> caster requires T to have a caster with an `T &` operator"); 886public: 887 bool load(handle src, bool convert) { return subcaster.load(src, convert); } 888 static PYBIND11_DESCR name() { return caster_t::name(); } 889 static handle cast(const std::reference_wrapper<type> &src, return_value_policy policy, handle parent) { 890 // It is definitely wrong to take ownership of this pointer, so mask that rvp 891 if (policy == return_value_policy::take_ownership || policy == return_value_policy::automatic) 892 policy = return_value_policy::automatic_reference; 893 return caster_t::cast(&src.get(), policy, parent); 894 } 895 template <typename T> using cast_op_type = std::reference_wrapper<type>; 896 operator std::reference_wrapper<type>() { return subcaster.operator subcaster_cast_op_type&(); } 897}; 898 899#define PYBIND11_TYPE_CASTER(type, py_name) \ 900 protected: \ 901 type value; \ 902 public: \ 903 static PYBIND11_DESCR name() { return type_descr(py_name); } \ 904 template <typename T_, enable_if_t<std::is_same<type, remove_cv_t<T_>>::value, int> = 0> \ 905 static handle cast(T_ *src, return_value_policy policy, handle parent) { \ 906 if (!src) return none().release(); \ 907 if (policy == return_value_policy::take_ownership) { \ 908 auto h = cast(std::move(*src), policy, parent); delete src; return h; \ 909 } else { \ 910 return cast(*src, policy, parent); \ 911 } \ 912 } \ 913 operator type*() { return &value; } \ 914 operator type&() { return value; } \ 915 operator type&&() && { return std::move(value); } \ 916 template <typename T_> using cast_op_type = pybind11::detail::movable_cast_op_type<T_> 917 918 919template <typename CharT> using is_std_char_type = any_of< 920 std::is_same<CharT, char>, /* std::string */ 921 std::is_same<CharT, char16_t>, /* std::u16string */ 922 std::is_same<CharT, char32_t>, /* std::u32string */ 923 std::is_same<CharT, wchar_t> /* std::wstring */ 924>; 925 926template <typename T> 927struct type_caster<T, enable_if_t<std::is_arithmetic<T>::value && !is_std_char_type<T>::value>> { 928 using _py_type_0 = conditional_t<sizeof(T) <= sizeof(long), long, long long>; 929 using _py_type_1 = conditional_t<std::is_signed<T>::value, _py_type_0, typename std::make_unsigned<_py_type_0>::type>; 930 using py_type = conditional_t<std::is_floating_point<T>::value, double, _py_type_1>; 931public: 932 933 bool load(handle src, bool convert) { 934 py_type py_value; 935 936 if (!src) 937 return false; 938 939 if (std::is_floating_point<T>::value) { 940 if (convert || PyFloat_Check(src.ptr())) 941 py_value = (py_type) PyFloat_AsDouble(src.ptr()); 942 else 943 return false; 944 } else if (PyFloat_Check(src.ptr())) { 945 return false; 946 } else if (std::is_unsigned<py_type>::value) { 947 py_value = as_unsigned<py_type>(src.ptr()); 948 } else { // signed integer: 949 py_value = sizeof(T) <= sizeof(long) 950 ? (py_type) PyLong_AsLong(src.ptr()) 951 : (py_type) PYBIND11_LONG_AS_LONGLONG(src.ptr()); 952 } 953 954 bool py_err = py_value == (py_type) -1 && PyErr_Occurred(); 955 if (py_err || (std::is_integral<T>::value && sizeof(py_type) != sizeof(T) && 956 (py_value < (py_type) std::numeric_limits<T>::min() || 957 py_value > (py_type) std::numeric_limits<T>::max()))) { 958 bool type_error = py_err && PyErr_ExceptionMatches( 959#if PY_VERSION_HEX < 0x03000000 && !defined(PYPY_VERSION) 960 PyExc_SystemError 961#else 962 PyExc_TypeError 963#endif 964 ); 965 PyErr_Clear(); 966 if (type_error && convert && PyNumber_Check(src.ptr())) { 967 auto tmp = reinterpret_steal<object>(std::is_floating_point<T>::value 968 ? PyNumber_Float(src.ptr()) 969 : PyNumber_Long(src.ptr())); 970 PyErr_Clear(); 971 return load(tmp, false); 972 } 973 return false; 974 } 975 976 value = (T) py_value; 977 return true; 978 } 979 980 static handle cast(T src, return_value_policy /* policy */, handle /* parent */) { 981 if (std::is_floating_point<T>::value) { 982 return PyFloat_FromDouble((double) src); 983 } else if (sizeof(T) <= sizeof(long)) { 984 if (std::is_signed<T>::value) 985 return PyLong_FromLong((long) src); 986 else 987 return PyLong_FromUnsignedLong((unsigned long) src); 988 } else { 989 if (std::is_signed<T>::value) 990 return PyLong_FromLongLong((long long) src); 991 else 992 return PyLong_FromUnsignedLongLong((unsigned long long) src); 993 } 994 } 995 996 PYBIND11_TYPE_CASTER(T, _<std::is_integral<T>::value>("int", "float")); 997}; 998 999template<typename T> struct void_caster { 1000public: 1001 bool load(handle src, bool) { 1002 if (src && src.is_none()) 1003 return true; 1004 return false; 1005 } 1006 static handle cast(T, return_value_policy /* policy */, handle /* parent */) { 1007 return none().inc_ref(); 1008 } 1009 PYBIND11_TYPE_CASTER(T, _("None")); 1010}; 1011 1012template <> class type_caster<void_type> : public void_caster<void_type> {}; 1013 1014template <> class type_caster<void> : public type_caster<void_type> { 1015public: 1016 using type_caster<void_type>::cast; 1017 1018 bool load(handle h, bool) { 1019 if (!h) { 1020 return false; 1021 } else if (h.is_none()) { 1022 value = nullptr; 1023 return true; 1024 } 1025 1026 /* Check if this is a capsule */ 1027 if (isinstance<capsule>(h)) { 1028 value = reinterpret_borrow<capsule>(h); 1029 return true; 1030 } 1031 1032 /* Check if this is a C++ type */ 1033 auto &bases = all_type_info((PyTypeObject *) h.get_type().ptr()); 1034 if (bases.size() == 1) { // Only allowing loading from a single-value type 1035 value = values_and_holders(reinterpret_cast<instance *>(h.ptr())).begin()->value_ptr(); 1036 return true; 1037 } 1038 1039 /* Fail */ 1040 return false; 1041 } 1042 1043 static handle cast(const void *ptr, return_value_policy /* policy */, handle /* parent */) { 1044 if (ptr) 1045 return capsule(ptr).release(); 1046 else 1047 return none().inc_ref(); 1048 } 1049 1050 template <typename T> using cast_op_type = void*&; 1051 operator void *&() { return value; } 1052 static PYBIND11_DESCR name() { return type_descr(_("capsule")); } 1053private: 1054 void *value = nullptr; 1055}; 1056 1057template <> class type_caster<std::nullptr_t> : public void_caster<std::nullptr_t> { }; 1058 1059template <> class type_caster<bool> { 1060public: 1061 bool load(handle src, bool convert) { 1062 if (!src) return false; 1063 else if (src.ptr() == Py_True) { value = true; return true; } 1064 else if (src.ptr() == Py_False) { value = false; return true; } 1065 else if (convert || !strcmp("numpy.bool_", Py_TYPE(src.ptr())->tp_name)) { 1066 // (allow non-implicit conversion for numpy booleans) 1067 1068 Py_ssize_t res = -1; 1069 if (src.is_none()) { 1070 res = 0; // None is implicitly converted to False 1071 } 1072 #if defined(PYPY_VERSION) 1073 // On PyPy, check that "__bool__" (or "__nonzero__" on Python 2.7) attr exists 1074 else if (hasattr(src, PYBIND11_BOOL_ATTR)) { 1075 res = PyObject_IsTrue(src.ptr()); 1076 } 1077 #else 1078 // Alternate approach for CPython: this does the same as the above, but optimized 1079 // using the CPython API so as to avoid an unneeded attribute lookup. 1080 else if (auto tp_as_number = src.ptr()->ob_type->tp_as_number) { 1081 if (PYBIND11_NB_BOOL(tp_as_number)) { 1082 res = (*PYBIND11_NB_BOOL(tp_as_number))(src.ptr()); 1083 } 1084 } 1085 #endif 1086 if (res == 0 || res == 1) { 1087 value = (bool) res; 1088 return true; 1089 } 1090 } 1091 return false; 1092 } 1093 static handle cast(bool src, return_value_policy /* policy */, handle /* parent */) { 1094 return handle(src ? Py_True : Py_False).inc_ref(); 1095 } 1096 PYBIND11_TYPE_CASTER(bool, _("bool")); 1097}; 1098 1099// Helper class for UTF-{8,16,32} C++ stl strings: 1100template <typename StringType, bool IsView = false> struct string_caster { 1101 using CharT = typename StringType::value_type; 1102 1103 // Simplify life by being able to assume standard char sizes (the standard only guarantees 1104 // minimums, but Python requires exact sizes) 1105 static_assert(!std::is_same<CharT, char>::value || sizeof(CharT) == 1, "Unsupported char size != 1"); 1106 static_assert(!std::is_same<CharT, char16_t>::value || sizeof(CharT) == 2, "Unsupported char16_t size != 2"); 1107 static_assert(!std::is_same<CharT, char32_t>::value || sizeof(CharT) == 4, "Unsupported char32_t size != 4"); 1108 // wchar_t can be either 16 bits (Windows) or 32 (everywhere else) 1109 static_assert(!std::is_same<CharT, wchar_t>::value || sizeof(CharT) == 2 || sizeof(CharT) == 4, 1110 "Unsupported wchar_t size != 2/4"); 1111 static constexpr size_t UTF_N = 8 * sizeof(CharT); 1112 1113 bool load(handle src, bool) { 1114#if PY_MAJOR_VERSION < 3 1115 object temp; 1116#endif 1117 handle load_src = src; 1118 if (!src) { 1119 return false; 1120 } else if (!PyUnicode_Check(load_src.ptr())) { 1121#if PY_MAJOR_VERSION >= 3 1122 return load_bytes(load_src); 1123#else 1124 if (sizeof(CharT) == 1) { 1125 return load_bytes(load_src); 1126 } 1127 1128 // The below is a guaranteed failure in Python 3 when PyUnicode_Check returns false 1129 if (!PYBIND11_BYTES_CHECK(load_src.ptr())) 1130 return false; 1131 1132 temp = reinterpret_steal<object>(PyUnicode_FromObject(load_src.ptr())); 1133 if (!temp) { PyErr_Clear(); return false; } 1134 load_src = temp; 1135#endif 1136 } 1137 1138 object utfNbytes = reinterpret_steal<object>(PyUnicode_AsEncodedString( 1139 load_src.ptr(), UTF_N == 8 ? "utf-8" : UTF_N == 16 ? "utf-16" : "utf-32", nullptr)); 1140 if (!utfNbytes) { PyErr_Clear(); return false; } 1141 1142 const CharT *buffer = reinterpret_cast<const CharT *>(PYBIND11_BYTES_AS_STRING(utfNbytes.ptr())); 1143 size_t length = (size_t) PYBIND11_BYTES_SIZE(utfNbytes.ptr()) / sizeof(CharT); 1144 if (UTF_N > 8) { buffer++; length--; } // Skip BOM for UTF-16/32 1145 value = StringType(buffer, length); 1146 1147 // If we're loading a string_view we need to keep the encoded Python object alive: 1148 if (IsView) 1149 loader_life_support::add_patient(utfNbytes); 1150 1151 return true; 1152 } 1153 1154 static handle cast(const StringType &src, return_value_policy /* policy */, handle /* parent */) { 1155 const char *buffer = reinterpret_cast<const char *>(src.data()); 1156 ssize_t nbytes = ssize_t(src.size() * sizeof(CharT)); 1157 handle s = decode_utfN(buffer, nbytes); 1158 if (!s) throw error_already_set(); 1159 return s; 1160 } 1161 1162 PYBIND11_TYPE_CASTER(StringType, _(PYBIND11_STRING_NAME)); 1163 1164private: 1165 static handle decode_utfN(const char *buffer, ssize_t nbytes) { 1166#if !defined(PYPY_VERSION) 1167 return 1168 UTF_N == 8 ? PyUnicode_DecodeUTF8(buffer, nbytes, nullptr) : 1169 UTF_N == 16 ? PyUnicode_DecodeUTF16(buffer, nbytes, nullptr, nullptr) : 1170 PyUnicode_DecodeUTF32(buffer, nbytes, nullptr, nullptr); 1171#else 1172 // PyPy seems to have multiple problems related to PyUnicode_UTF*: the UTF8 version 1173 // sometimes segfaults for unknown reasons, while the UTF16 and 32 versions require a 1174 // non-const char * arguments, which is also a nuissance, so bypass the whole thing by just 1175 // passing the encoding as a string value, which works properly: 1176 return PyUnicode_Decode(buffer, nbytes, UTF_N == 8 ? "utf-8" : UTF_N == 16 ? "utf-16" : "utf-32", nullptr); 1177#endif 1178 } 1179 1180 // When loading into a std::string or char*, accept a bytes object as-is (i.e. 1181 // without any encoding/decoding attempt). For other C++ char sizes this is a no-op. 1182 // which supports loading a unicode from a str, doesn't take this path. 1183 template <typename C = CharT> 1184 bool load_bytes(enable_if_t<sizeof(C) == 1, handle> src) { 1185 if (PYBIND11_BYTES_CHECK(src.ptr())) { 1186 // We were passed a Python 3 raw bytes; accept it into a std::string or char* 1187 // without any encoding attempt. 1188 const char *bytes = PYBIND11_BYTES_AS_STRING(src.ptr()); 1189 if (bytes) { 1190 value = StringType(bytes, (size_t) PYBIND11_BYTES_SIZE(src.ptr())); 1191 return true; 1192 } 1193 } 1194 1195 return false; 1196 } 1197 1198 template <typename C = CharT> 1199 bool load_bytes(enable_if_t<sizeof(C) != 1, handle>) { return false; } 1200}; 1201 1202template <typename CharT, class Traits, class Allocator> 1203struct type_caster<std::basic_string<CharT, Traits, Allocator>, enable_if_t<is_std_char_type<CharT>::value>> 1204 : string_caster<std::basic_string<CharT, Traits, Allocator>> {}; 1205 1206#ifdef PYBIND11_HAS_STRING_VIEW 1207template <typename CharT, class Traits> 1208struct type_caster<std::basic_string_view<CharT, Traits>, enable_if_t<is_std_char_type<CharT>::value>> 1209 : string_caster<std::basic_string_view<CharT, Traits>, true> {}; 1210#endif 1211 1212// Type caster for C-style strings. We basically use a std::string type caster, but also add the 1213// ability to use None as a nullptr char* (which the string caster doesn't allow). 1214template <typename CharT> struct type_caster<CharT, enable_if_t<is_std_char_type<CharT>::value>> { 1215 using StringType = std::basic_string<CharT>; 1216 using StringCaster = type_caster<StringType>; 1217 StringCaster str_caster; 1218 bool none = false; 1219public: 1220 bool load(handle src, bool convert) { 1221 if (!src) return false; 1222 if (src.is_none()) { 1223 // Defer accepting None to other overloads (if we aren't in convert mode): 1224 if (!convert) return false; 1225 none = true; 1226 return true; 1227 } 1228 return str_caster.load(src, convert); 1229 } 1230 1231 static handle cast(const CharT *src, return_value_policy policy, handle parent) { 1232 if (src == nullptr) return pybind11::none().inc_ref(); 1233 return StringCaster::cast(StringType(src), policy, parent); 1234 } 1235 1236 static handle cast(CharT src, return_value_policy policy, handle parent) { 1237 if (std::is_same<char, CharT>::value) { 1238 handle s = PyUnicode_DecodeLatin1((const char *) &src, 1, nullptr); 1239 if (!s) throw error_already_set(); 1240 return s; 1241 } 1242 return StringCaster::cast(StringType(1, src), policy, parent); 1243 } 1244 1245 operator CharT*() { return none ? nullptr : const_cast<CharT *>(static_cast<StringType &>(str_caster).c_str()); } 1246 operator CharT() { 1247 if (none) 1248 throw value_error("Cannot convert None to a character"); 1249 1250 auto &value = static_cast<StringType &>(str_caster); 1251 size_t str_len = value.size(); 1252 if (str_len == 0) 1253 throw value_error("Cannot convert empty string to a character"); 1254 1255 // If we're in UTF-8 mode, we have two possible failures: one for a unicode character that 1256 // is too high, and one for multiple unicode characters (caught later), so we need to figure 1257 // out how long the first encoded character is in bytes to distinguish between these two 1258 // errors. We also allow want to allow unicode characters U+0080 through U+00FF, as those 1259 // can fit into a single char value. 1260 if (StringCaster::UTF_N == 8 && str_len > 1 && str_len <= 4) { 1261 unsigned char v0 = static_cast<unsigned char>(value[0]); 1262 size_t char0_bytes = !(v0 & 0x80) ? 1 : // low bits only: 0-127 1263 (v0 & 0xE0) == 0xC0 ? 2 : // 0b110xxxxx - start of 2-byte sequence 1264 (v0 & 0xF0) == 0xE0 ? 3 : // 0b1110xxxx - start of 3-byte sequence 1265 4; // 0b11110xxx - start of 4-byte sequence 1266 1267 if (char0_bytes == str_len) { 1268 // If we have a 128-255 value, we can decode it into a single char: 1269 if (char0_bytes == 2 && (v0 & 0xFC) == 0xC0) { // 0x110000xx 0x10xxxxxx 1270 return static_cast<CharT>(((v0 & 3) << 6) + (static_cast<unsigned char>(value[1]) & 0x3F)); 1271 } 1272 // Otherwise we have a single character, but it's > U+00FF 1273 throw value_error("Character code point not in range(0x100)"); 1274 } 1275 } 1276 1277 // UTF-16 is much easier: we can only have a surrogate pair for values above U+FFFF, thus a 1278 // surrogate pair with total length 2 instantly indicates a range error (but not a "your 1279 // string was too long" error). 1280 else if (StringCaster::UTF_N == 16 && str_len == 2) { 1281 char16_t v0 = static_cast<char16_t>(value[0]); 1282 if (v0 >= 0xD800 && v0 < 0xE000) 1283 throw value_error("Character code point not in range(0x10000)"); 1284 } 1285 1286 if (str_len != 1) 1287 throw value_error("Expected a character, but multi-character string found"); 1288 1289 return value[0]; 1290 } 1291 1292 static PYBIND11_DESCR name() { return type_descr(_(PYBIND11_STRING_NAME)); } 1293 template <typename _T> using cast_op_type = remove_reference_t<pybind11::detail::cast_op_type<_T>>; 1294}; 1295 1296// Base implementation for std::tuple and std::pair 1297template <template<typename...> class Tuple, typename... Ts> class tuple_caster { 1298 using type = Tuple<Ts...>; 1299 static constexpr auto size = sizeof...(Ts); 1300 using indices = make_index_sequence<size>; 1301public: 1302 1303 bool load(handle src, bool convert) { 1304 if (!isinstance<sequence>(src)) 1305 return false; 1306 const auto seq = reinterpret_borrow<sequence>(src); 1307 if (seq.size() != size) 1308 return false; 1309 return load_impl(seq, convert, indices{}); 1310 } 1311 1312 template <typename T> 1313 static handle cast(T &&src, return_value_policy policy, handle parent) { 1314 return cast_impl(std::forward<T>(src), policy, parent, indices{}); 1315 } 1316 1317 static PYBIND11_DESCR name() { 1318 return type_descr(_("Tuple[") + detail::concat(make_caster<Ts>::name()...) + _("]")); 1319 } 1320 1321 template <typename T> using cast_op_type = type; 1322 1323 operator type() & { return implicit_cast(indices{}); } 1324 operator type() && { return std::move(*this).implicit_cast(indices{}); } 1325 1326protected: 1327 template <size_t... Is> 1328 type implicit_cast(index_sequence<Is...>) & { return type(cast_op<Ts>(std::get<Is>(subcasters))...); } 1329 template <size_t... Is> 1330 type implicit_cast(index_sequence<Is...>) && { return type(cast_op<Ts>(std::move(std::get<Is>(subcasters)))...); } 1331 1332 static constexpr bool load_impl(const sequence &, bool, index_sequence<>) { return true; } 1333 1334 template <size_t... Is> 1335 bool load_impl(const sequence &seq, bool convert, index_sequence<Is...>) { 1336 for (bool r : {std::get<Is>(subcasters).load(seq[Is], convert)...}) 1337 if (!r) 1338 return false; 1339 return true; 1340 } 1341 1342 /* Implementation: Convert a C++ tuple into a Python tuple */ 1343 template <typename T, size_t... Is> 1344 static handle cast_impl(T &&src, return_value_policy policy, handle parent, index_sequence<Is...>) { 1345 std::array<object, size> entries{{ 1346 reinterpret_steal<object>(make_caster<Ts>::cast(std::get<Is>(std::forward<T>(src)), policy, parent))... 1347 }}; 1348 for (const auto &entry: entries) 1349 if (!entry) 1350 return handle(); 1351 tuple result(size); 1352 int counter = 0; 1353 for (auto & entry: entries) 1354 PyTuple_SET_ITEM(result.ptr(), counter++, entry.release().ptr()); 1355 return result.release(); 1356 } 1357 1358 Tuple<make_caster<Ts>...> subcasters; 1359}; 1360 1361template <typename T1, typename T2> class type_caster<std::pair<T1, T2>> 1362 : public tuple_caster<std::pair, T1, T2> {}; 1363 1364template <typename... Ts> class type_caster<std::tuple<Ts...>> 1365 : public tuple_caster<std::tuple, Ts...> {}; 1366 1367/// Helper class which abstracts away certain actions. Users can provide specializations for 1368/// custom holders, but it's only necessary if the type has a non-standard interface. 1369template <typename T> 1370struct holder_helper { 1371 static auto get(const T &p) -> decltype(p.get()) { return p.get(); } 1372}; 1373 1374/// Type caster for holder types like std::shared_ptr, etc. 1375template <typename type, typename holder_type> 1376struct copyable_holder_caster : public type_caster_base<type> { 1377public: 1378 using base = type_caster_base<type>; 1379 static_assert(std::is_base_of<base, type_caster<type>>::value, 1380 "Holder classes are only supported for custom types"); 1381 using base::base; 1382 using base::cast; 1383 using base::typeinfo; 1384 using base::value; 1385 1386 bool load(handle src, bool convert) { 1387 return base::template load_impl<copyable_holder_caster<type, holder_type>>(src, convert); 1388 } 1389 1390 explicit operator type*() { return this->value; } 1391 explicit operator type&() { return *(this->value); } 1392 explicit operator holder_type*() { return &holder; } 1393 1394 // Workaround for Intel compiler bug 1395 // see pybind11 issue 94 1396 #if defined(__ICC) || defined(__INTEL_COMPILER) 1397 operator holder_type&() { return holder; } 1398 #else 1399 explicit operator holder_type&() { return holder; } 1400 #endif 1401 1402 static handle cast(const holder_type &src, return_value_policy, handle) { 1403 const auto *ptr = holder_helper<holder_type>::get(src); 1404 return type_caster_base<type>::cast_holder(ptr, &src); 1405 } 1406 1407protected: 1408 friend class type_caster_generic; 1409 void check_holder_compat() { 1410 if (typeinfo->default_holder) 1411 throw cast_error("Unable to load a custom holder type from a default-holder instance"); 1412 } 1413 1414 bool load_value(value_and_holder &&v_h) { 1415 if (v_h.holder_constructed()) { 1416 value = v_h.value_ptr(); 1417 holder = v_h.holder<holder_type>(); 1418 return true; 1419 } else { 1420 throw cast_error("Unable to cast from non-held to held instance (T& to Holder<T>) " 1421#if defined(NDEBUG) 1422 "(compile in debug mode for type information)"); 1423#else 1424 "of type '" + type_id<holder_type>() + "''"); 1425#endif 1426 } 1427 } 1428 1429 template <typename T = holder_type, detail::enable_if_t<!std::is_constructible<T, const T &, type*>::value, int> = 0> 1430 bool try_implicit_casts(handle, bool) { return false; } 1431 1432 template <typename T = holder_type, detail::enable_if_t<std::is_constructible<T, const T &, type*>::value, int> = 0> 1433 bool try_implicit_casts(handle src, bool convert) { 1434 for (auto &cast : typeinfo->implicit_casts) { 1435 copyable_holder_caster sub_caster(*cast.first); 1436 if (sub_caster.load(src, convert)) { 1437 value = cast.second(sub_caster.value); 1438 holder = holder_type(sub_caster.holder, (type *) value); 1439 return true; 1440 } 1441 } 1442 return false; 1443 } 1444 1445 static bool try_direct_conversions(handle) { return false; } 1446 1447 1448 holder_type holder; 1449}; 1450 1451/// Specialize for the common std::shared_ptr, so users don't need to 1452template <typename T> 1453class type_caster<std::shared_ptr<T>> : public copyable_holder_caster<T, std::shared_ptr<T>> { }; 1454 1455template <typename type, typename holder_type> 1456struct move_only_holder_caster { 1457 static_assert(std::is_base_of<type_caster_base<type>, type_caster<type>>::value, 1458 "Holder classes are only supported for custom types"); 1459 1460 static handle cast(holder_type &&src, return_value_policy, handle) { 1461 auto *ptr = holder_helper<holder_type>::get(src); 1462 return type_caster_base<type>::cast_holder(ptr, &src); 1463 } 1464 static PYBIND11_DESCR name() { return type_caster_base<type>::name(); } 1465}; 1466 1467template <typename type, typename deleter> 1468class type_caster<std::unique_ptr<type, deleter>> 1469 : public move_only_holder_caster<type, std::unique_ptr<type, deleter>> { }; 1470 1471template <typename type, typename holder_type> 1472using type_caster_holder = conditional_t<is_copy_constructible<holder_type>::value, 1473 copyable_holder_caster<type, holder_type>, 1474 move_only_holder_caster<type, holder_type>>; 1475 1476template <typename T, bool Value = false> struct always_construct_holder { static constexpr bool value = Value; }; 1477 1478/// Create a specialization for custom holder types (silently ignores std::shared_ptr) 1479#define PYBIND11_DECLARE_HOLDER_TYPE(type, holder_type, ...) \ 1480 namespace pybind11 { namespace detail { \ 1481 template <typename type> \ 1482 struct always_construct_holder<holder_type> : always_construct_holder<void, ##__VA_ARGS__> { }; \ 1483 template <typename type> \ 1484 class type_caster<holder_type, enable_if_t<!is_shared_ptr<holder_type>::value>> \ 1485 : public type_caster_holder<type, holder_type> { }; \ 1486 }} 1487 1488// PYBIND11_DECLARE_HOLDER_TYPE holder types: 1489template <typename base, typename holder> struct is_holder_type : 1490 std::is_base_of<detail::type_caster_holder<base, holder>, detail::type_caster<holder>> {}; 1491// Specialization for always-supported unique_ptr holders: 1492template <typename base, typename deleter> struct is_holder_type<base, std::unique_ptr<base, deleter>> : 1493 std::true_type {}; 1494 1495template <typename T> struct handle_type_name { static PYBIND11_DESCR name() { return _<T>(); } }; 1496template <> struct handle_type_name<bytes> { static PYBIND11_DESCR name() { return _(PYBIND11_BYTES_NAME); } }; 1497template <> struct handle_type_name<args> { static PYBIND11_DESCR name() { return _("*args"); } }; 1498template <> struct handle_type_name<kwargs> { static PYBIND11_DESCR name() { return _("**kwargs"); } }; 1499 1500template <typename type> 1501struct pyobject_caster { 1502 template <typename T = type, enable_if_t<std::is_same<T, handle>::value, int> = 0> 1503 bool load(handle src, bool /* convert */) { value = src; return static_cast<bool>(value); } 1504 1505 template <typename T = type, enable_if_t<std::is_base_of<object, T>::value, int> = 0> 1506 bool load(handle src, bool /* convert */) { 1507 if (!isinstance<type>(src)) 1508 return false; 1509 value = reinterpret_borrow<type>(src); 1510 return true; 1511 } 1512 1513 static handle cast(const handle &src, return_value_policy /* policy */, handle /* parent */) { 1514 return src.inc_ref(); 1515 } 1516 PYBIND11_TYPE_CASTER(type, handle_type_name<type>::name()); 1517}; 1518 1519template <typename T> 1520class type_caster<T, enable_if_t<is_pyobject<T>::value>> : public pyobject_caster<T> { }; 1521 1522// Our conditions for enabling moving are quite restrictive: 1523// At compile time: 1524// - T needs to be a non-const, non-pointer, non-reference type 1525// - type_caster<T>::operator T&() must exist 1526// - the type must be move constructible (obviously) 1527// At run-time: 1528// - if the type is non-copy-constructible, the object must be the sole owner of the type (i.e. it 1529// must have ref_count() == 1)h 1530// If any of the above are not satisfied, we fall back to copying. 1531template <typename T> using move_is_plain_type = satisfies_none_of<T, 1532 std::is_void, std::is_pointer, std::is_reference, std::is_const 1533>; 1534template <typename T, typename SFINAE = void> struct move_always : std::false_type {}; 1535template <typename T> struct move_always<T, enable_if_t<all_of< 1536 move_is_plain_type<T>, 1537 negation<is_copy_constructible<T>>, 1538 std::is_move_constructible<T>, 1539 std::is_same<decltype(std::declval<make_caster<T>>().operator T&()), T&> 1540>::value>> : std::true_type {}; 1541template <typename T, typename SFINAE = void> struct move_if_unreferenced : std::false_type {}; 1542template <typename T> struct move_if_unreferenced<T, enable_if_t<all_of< 1543 move_is_plain_type<T>, 1544 negation<move_always<T>>, 1545 std::is_move_constructible<T>, 1546 std::is_same<decltype(std::declval<make_caster<T>>().operator T&()), T&> 1547>::value>> : std::true_type {}; 1548template <typename T> using move_never = none_of<move_always<T>, move_if_unreferenced<T>>; 1549 1550// Detect whether returning a `type` from a cast on type's type_caster is going to result in a 1551// reference or pointer to a local variable of the type_caster. Basically, only 1552// non-reference/pointer `type`s and reference/pointers from a type_caster_generic are safe; 1553// everything else returns a reference/pointer to a local variable. 1554template <typename type> using cast_is_temporary_value_reference = bool_constant< 1555 (std::is_reference<type>::value || std::is_pointer<type>::value) && 1556 !std::is_base_of<type_caster_generic, make_caster<type>>::value 1557>; 1558 1559// When a value returned from a C++ function is being cast back to Python, we almost always want to 1560// force `policy = move`, regardless of the return value policy the function/method was declared 1561// with. Some classes (most notably Eigen::Ref and related) need to avoid this, and so can do so by 1562// specializing this struct. 1563template <typename Return, typename SFINAE = void> struct return_value_policy_override { 1564 static return_value_policy policy(return_value_policy p) { 1565 return !std::is_lvalue_reference<Return>::value && !std::is_pointer<Return>::value 1566 ? return_value_policy::move : p; 1567 } 1568}; 1569 1570// Basic python -> C++ casting; throws if casting fails 1571template <typename T, typename SFINAE> type_caster<T, SFINAE> &load_type(type_caster<T, SFINAE> &conv, const handle &handle) { 1572 if (!conv.load(handle, true)) { 1573#if defined(NDEBUG) 1574 throw cast_error("Unable to cast Python instance to C++ type (compile in debug mode for details)"); 1575#else 1576 throw cast_error("Unable to cast Python instance of type " + 1577 (std::string) str(handle.get_type()) + " to C++ type '" + type_id<T>() + "''"); 1578#endif 1579 } 1580 return conv; 1581} 1582// Wrapper around the above that also constructs and returns a type_caster 1583template <typename T> make_caster<T> load_type(const handle &handle) { 1584 make_caster<T> conv; 1585 load_type(conv, handle); 1586 return conv; 1587} 1588 1589NAMESPACE_END(detail) 1590 1591// pytype -> C++ type 1592template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0> 1593T cast(const handle &handle) { 1594 using namespace detail; 1595 static_assert(!cast_is_temporary_value_reference<T>::value, 1596 "Unable to cast type to reference: value is local to type caster"); 1597 return cast_op<T>(load_type<T>(handle)); 1598} 1599 1600// pytype -> pytype (calls converting constructor) 1601template <typename T, detail::enable_if_t<detail::is_pyobject<T>::value, int> = 0> 1602T cast(const handle &handle) { return T(reinterpret_borrow<object>(handle)); } 1603 1604// C++ type -> py::object 1605template <typename T, detail::enable_if_t<!detail::is_pyobject<T>::value, int> = 0> 1606object cast(const T &value, return_value_policy policy = return_value_policy::automatic_reference, 1607 handle parent = handle()) { 1608 if (policy == return_value_policy::automatic) 1609 policy = std::is_pointer<T>::value ? return_value_policy::take_ownership : return_value_policy::copy; 1610 else if (policy == return_value_policy::automatic_reference) 1611 policy = std::is_pointer<T>::value ? return_value_policy::reference : return_value_policy::copy; 1612 return reinterpret_steal<object>(detail::make_caster<T>::cast(value, policy, parent)); 1613} 1614 1615template <typename T> T handle::cast() const { return pybind11::cast<T>(*this); } 1616template <> inline void handle::cast() const { return; } 1617 1618template <typename T> 1619detail::enable_if_t<!detail::move_never<T>::value, T> move(object &&obj) { 1620 if (obj.ref_count() > 1) 1621#if defined(NDEBUG) 1622 throw cast_error("Unable to cast Python instance to C++ rvalue: instance has multiple references" 1623 " (compile in debug mode for details)"); 1624#else 1625 throw cast_error("Unable to move from Python " + (std::string) str(obj.get_type()) + 1626 " instance to C++ " + type_id<T>() + " instance: instance has multiple references"); 1627#endif 1628 1629 // Move into a temporary and return that, because the reference may be a local value of `conv` 1630 T ret = std::move(detail::load_type<T>(obj).operator T&()); 1631 return ret; 1632} 1633 1634// Calling cast() on an rvalue calls pybind::cast with the object rvalue, which does: 1635// - If we have to move (because T has no copy constructor), do it. This will fail if the moved 1636// object has multiple references, but trying to copy will fail to compile. 1637// - If both movable and copyable, check ref count: if 1, move; otherwise copy 1638// - Otherwise (not movable), copy. 1639template <typename T> detail::enable_if_t<detail::move_always<T>::value, T> cast(object &&object) { 1640 return move<T>(std::move(object)); 1641} 1642template <typename T> detail::enable_if_t<detail::move_if_unreferenced<T>::value, T> cast(object &&object) { 1643 if (object.ref_count() > 1) 1644 return cast<T>(object); 1645 else 1646 return move<T>(std::move(object)); 1647} 1648template <typename T> detail::enable_if_t<detail::move_never<T>::value, T> cast(object &&object) { 1649 return cast<T>(object); 1650} 1651 1652template <typename T> T object::cast() const & { return pybind11::cast<T>(*this); } 1653template <typename T> T object::cast() && { return pybind11::cast<T>(std::move(*this)); } 1654template <> inline void object::cast() const & { return; } 1655template <> inline void object::cast() && { return; } 1656 1657NAMESPACE_BEGIN(detail) 1658 1659// Declared in pytypes.h: 1660template <typename T, enable_if_t<!is_pyobject<T>::value, int>> 1661object object_or_cast(T &&o) { return pybind11::cast(std::forward<T>(o)); } 1662 1663struct overload_unused {}; // Placeholder type for the unneeded (and dead code) static variable in the OVERLOAD_INT macro 1664template <typename ret_type> using overload_caster_t = conditional_t< 1665 cast_is_temporary_value_reference<ret_type>::value, make_caster<ret_type>, overload_unused>; 1666 1667// Trampoline use: for reference/pointer types to value-converted values, we do a value cast, then 1668// store the result in the given variable. For other types, this is a no-op. 1669template <typename T> enable_if_t<cast_is_temporary_value_reference<T>::value, T> cast_ref(object &&o, make_caster<T> &caster) { 1670 return cast_op<T>(load_type(caster, o)); 1671} 1672template <typename T> enable_if_t<!cast_is_temporary_value_reference<T>::value, T> cast_ref(object &&, overload_unused &) { 1673 pybind11_fail("Internal error: cast_ref fallback invoked"); } 1674 1675// Trampoline use: Having a pybind11::cast with an invalid reference type is going to static_assert, even 1676// though if it's in dead code, so we provide a "trampoline" to pybind11::cast that only does anything in 1677// cases where pybind11::cast is valid. 1678template <typename T> enable_if_t<!cast_is_temporary_value_reference<T>::value, T> cast_safe(object &&o) { 1679 return pybind11::cast<T>(std::move(o)); } 1680template <typename T> enable_if_t<cast_is_temporary_value_reference<T>::value, T> cast_safe(object &&) { 1681 pybind11_fail("Internal error: cast_safe fallback invoked"); } 1682template <> inline void cast_safe<void>(object &&) {} 1683 1684NAMESPACE_END(detail) 1685 1686template <return_value_policy policy = return_value_policy::automatic_reference, 1687 typename... Args> tuple make_tuple(Args&&... args_) { 1688 constexpr size_t size = sizeof...(Args); 1689 std::array<object, size> args { 1690 { reinterpret_steal<object>(detail::make_caster<Args>::cast( 1691 std::forward<Args>(args_), policy, nullptr))... } 1692 }; 1693 for (size_t i = 0; i < args.size(); i++) { 1694 if (!args[i]) { 1695#if defined(NDEBUG) 1696 throw cast_error("make_tuple(): unable to convert arguments to Python object (compile in debug mode for details)"); 1697#else 1698 std::array<std::string, size> argtypes { {type_id<Args>()...} }; 1699 throw cast_error("make_tuple(): unable to convert argument of type '" + 1700 argtypes[i] + "' to Python object"); 1701#endif 1702 } 1703 } 1704 tuple result(size); 1705 int counter = 0; 1706 for (auto &arg_value : args) 1707 PyTuple_SET_ITEM(result.ptr(), counter++, arg_value.release().ptr()); 1708 return result; 1709} 1710 1711/// \ingroup annotations 1712/// Annotation for arguments 1713struct arg { 1714 /// Constructs an argument with the name of the argument; if null or omitted, this is a positional argument. 1715 constexpr explicit arg(const char *name = nullptr) : name(name), flag_noconvert(false), flag_none(true) { } 1716 /// Assign a value to this argument 1717 template <typename T> arg_v operator=(T &&value) const; 1718 /// Indicate that the type should not be converted in the type caster 1719 arg &noconvert(bool flag = true) { flag_noconvert = flag; return *this; } 1720 /// Indicates that the argument should/shouldn't allow None (e.g. for nullable pointer args) 1721 arg &none(bool flag = true) { flag_none = flag; return *this; } 1722 1723 const char *name; ///< If non-null, this is a named kwargs argument 1724 bool flag_noconvert : 1; ///< If set, do not allow conversion (requires a supporting type caster!) 1725 bool flag_none : 1; ///< If set (the default), allow None to be passed to this argument 1726}; 1727 1728/// \ingroup annotations 1729/// Annotation for arguments with values 1730struct arg_v : arg { 1731private: 1732 template <typename T> 1733 arg_v(arg &&base, T &&x, const char *descr = nullptr) 1734 : arg(base), 1735 value(reinterpret_steal<object>( 1736 detail::make_caster<T>::cast(x, return_value_policy::automatic, {}) 1737 )), 1738 descr(descr) 1739#if !defined(NDEBUG) 1740 , type(type_id<T>()) 1741#endif 1742 { } 1743 1744public: 1745 /// Direct construction with name, default, and description 1746 template <typename T> 1747 arg_v(const char *name, T &&x, const char *descr = nullptr) 1748 : arg_v(arg(name), std::forward<T>(x), descr) { } 1749 1750 /// Called internally when invoking `py::arg("a") = value` 1751 template <typename T> 1752 arg_v(const arg &base, T &&x, const char *descr = nullptr) 1753 : arg_v(arg(base), std::forward<T>(x), descr) { } 1754 1755 /// Same as `arg::noconvert()`, but returns *this as arg_v&, not arg& 1756 arg_v &noconvert(bool flag = true) { arg::noconvert(flag); return *this; } 1757 1758 /// Same as `arg::nonone()`, but returns *this as arg_v&, not arg& 1759 arg_v &none(bool flag = true) { arg::none(flag); return *this; } 1760 1761 /// The default value 1762 object value; 1763 /// The (optional) description of the default value 1764 const char *descr; 1765#if !defined(NDEBUG) 1766 /// The C++ type name of the default value (only available when compiled in debug mode) 1767 std::string type; 1768#endif 1769}; 1770 1771template <typename T> 1772arg_v arg::operator=(T &&value) const { return {std::move(*this), std::forward<T>(value)}; } 1773 1774/// Alias for backward compatibility -- to be removed in version 2.0 1775template <typename /*unused*/> using arg_t = arg_v; 1776 1777inline namespace literals { 1778/** \rst 1779 String literal version of `arg` 1780 \endrst */ 1781constexpr arg operator"" _a(const char *name, size_t) { return arg(name); } 1782} 1783 1784NAMESPACE_BEGIN(detail) 1785 1786// forward declaration (definition in attr.h) 1787struct function_record; 1788 1789/// Internal data associated with a single function call 1790struct function_call { 1791 function_call(function_record &f, handle p); // Implementation in attr.h 1792 1793 /// The function data: 1794 const function_record &func; 1795 1796 /// Arguments passed to the function: 1797 std::vector<handle> args; 1798 1799 /// The `convert` value the arguments should be loaded with 1800 std::vector<bool> args_convert; 1801 1802 /// The parent, if any 1803 handle parent; 1804 1805 /// If this is a call to an initializer, this argument contains `self` 1806 handle init_self; 1807}; 1808 1809 1810/// Helper class which loads arguments for C++ functions called from Python 1811template <typename... Args> 1812class argument_loader { 1813 using indices = make_index_sequence<sizeof...(Args)>; 1814 1815 template <typename Arg> using argument_is_args = std::is_same<intrinsic_t<Arg>, args>; 1816 template <typename Arg> using argument_is_kwargs = std::is_same<intrinsic_t<Arg>, kwargs>; 1817 // Get args/kwargs argument positions relative to the end of the argument list: 1818 static constexpr auto args_pos = constexpr_first<argument_is_args, Args...>() - (int) sizeof...(Args), 1819 kwargs_pos = constexpr_first<argument_is_kwargs, Args...>() - (int) sizeof...(Args); 1820 1821 static constexpr bool args_kwargs_are_last = kwargs_pos >= - 1 && args_pos >= kwargs_pos - 1; 1822 1823 static_assert(args_kwargs_are_last, "py::args/py::kwargs are only permitted as the last argument(s) of a function"); 1824 1825public: 1826 static constexpr bool has_kwargs = kwargs_pos < 0; 1827 static constexpr bool has_args = args_pos < 0; 1828 1829 static PYBIND11_DESCR arg_names() { return detail::concat(make_caster<Args>::name()...); } 1830 1831 bool load_args(function_call &call) { 1832 return load_impl_sequence(call, indices{}); 1833 } 1834 1835 template <typename Return, typename Guard, typename Func> 1836 enable_if_t<!std::is_void<Return>::value, Return> call(Func &&f) && { 1837 return std::move(*this).template call_impl<Return>(std::forward<Func>(f), indices{}, Guard{}); 1838 } 1839 1840 template <typename Return, typename Guard, typename Func> 1841 enable_if_t<std::is_void<Return>::value, void_type> call(Func &&f) && { 1842 std::move(*this).template call_impl<Return>(std::forward<Func>(f), indices{}, Guard{}); 1843 return void_type(); 1844 } 1845 1846private: 1847 1848 static bool load_impl_sequence(function_call &, index_sequence<>) { return true; } 1849 1850 template <size_t... Is> 1851 bool load_impl_sequence(function_call &call, index_sequence<Is...>) { 1852 for (bool r : {std::get<Is>(argcasters).load(call.args[Is], call.args_convert[Is])...}) 1853 if (!r) 1854 return false; 1855 return true; 1856 } 1857 1858 template <typename Return, typename Func, size_t... Is, typename Guard> 1859 Return call_impl(Func &&f, index_sequence<Is...>, Guard &&) { 1860 return std::forward<Func>(f)(cast_op<Args>(std::move(std::get<Is>(argcasters)))...); 1861 } 1862 1863 std::tuple<make_caster<Args>...> argcasters; 1864}; 1865 1866/// Helper class which collects only positional arguments for a Python function call. 1867/// A fancier version below can collect any argument, but this one is optimal for simple calls. 1868template <return_value_policy policy> 1869class simple_collector { 1870public: 1871 template <typename... Ts> 1872 explicit simple_collector(Ts &&...values) 1873 : m_args(pybind11::make_tuple<policy>(std::forward<Ts>(values)...)) { } 1874 1875 const tuple &args() const & { return m_args; } 1876 dict kwargs() const { return {}; } 1877 1878 tuple args() && { return std::move(m_args); } 1879 1880 /// Call a Python function and pass the collected arguments 1881 object call(PyObject *ptr) const { 1882 PyObject *result = PyObject_CallObject(ptr, m_args.ptr()); 1883 if (!result) 1884 throw error_already_set(); 1885 return reinterpret_steal<object>(result); 1886 } 1887 1888private: 1889 tuple m_args; 1890}; 1891 1892/// Helper class which collects positional, keyword, * and ** arguments for a Python function call 1893template <return_value_policy policy> 1894class unpacking_collector { 1895public: 1896 template <typename... Ts> 1897 explicit unpacking_collector(Ts &&...values) { 1898 // Tuples aren't (easily) resizable so a list is needed for collection, 1899 // but the actual function call strictly requires a tuple. 1900 auto args_list = list(); 1901 int _[] = { 0, (process(args_list, std::forward<Ts>(values)), 0)... }; 1902 ignore_unused(_); 1903 1904 m_args = std::move(args_list); 1905 } 1906 1907 const tuple &args() const & { return m_args; } 1908 const dict &kwargs() const & { return m_kwargs; } 1909 1910 tuple args() && { return std::move(m_args); } 1911 dict kwargs() && { return std::move(m_kwargs); } 1912 1913 /// Call a Python function and pass the collected arguments 1914 object call(PyObject *ptr) const { 1915 PyObject *result = PyObject_Call(ptr, m_args.ptr(), m_kwargs.ptr()); 1916 if (!result) 1917 throw error_already_set(); 1918 return reinterpret_steal<object>(result); 1919 } 1920 1921private: 1922 template <typename T> 1923 void process(list &args_list, T &&x) { 1924 auto o = reinterpret_steal<object>(detail::make_caster<T>::cast(std::forward<T>(x), policy, {})); 1925 if (!o) { 1926#if defined(NDEBUG) 1927 argument_cast_error(); 1928#else 1929 argument_cast_error(std::to_string(args_list.size()), type_id<T>()); 1930#endif 1931 } 1932 args_list.append(o); 1933 } 1934 1935 void process(list &args_list, detail::args_proxy ap) { 1936 for (const auto &a : ap) 1937 args_list.append(a); 1938 } 1939 1940 void process(list &/*args_list*/, arg_v a) { 1941 if (!a.name) 1942#if defined(NDEBUG) 1943 nameless_argument_error(); 1944#else 1945 nameless_argument_error(a.type); 1946#endif 1947 1948 if (m_kwargs.contains(a.name)) { 1949#if defined(NDEBUG) 1950 multiple_values_error(); 1951#else 1952 multiple_values_error(a.name); 1953#endif 1954 } 1955 if (!a.value) { 1956#if defined(NDEBUG) 1957 argument_cast_error(); 1958#else 1959 argument_cast_error(a.name, a.type); 1960#endif 1961 } 1962 m_kwargs[a.name] = a.value; 1963 } 1964 1965 void process(list &/*args_list*/, detail::kwargs_proxy kp) { 1966 if (!kp) 1967 return; 1968 for (const auto &k : reinterpret_borrow<dict>(kp)) { 1969 if (m_kwargs.contains(k.first)) { 1970#if defined(NDEBUG) 1971 multiple_values_error(); 1972#else 1973 multiple_values_error(str(k.first)); 1974#endif 1975 } 1976 m_kwargs[k.first] = k.second; 1977 } 1978 } 1979 1980 [[noreturn]] static void nameless_argument_error() { 1981 throw type_error("Got kwargs without a name; only named arguments " 1982 "may be passed via py::arg() to a python function call. " 1983 "(compile in debug mode for details)"); 1984 } 1985 [[noreturn]] static void nameless_argument_error(std::string type) { 1986 throw type_error("Got kwargs without a name of type '" + type + "'; only named " 1987 "arguments may be passed via py::arg() to a python function call. "); 1988 } 1989 [[noreturn]] static void multiple_values_error() { 1990 throw type_error("Got multiple values for keyword argument " 1991 "(compile in debug mode for details)"); 1992 } 1993 1994 [[noreturn]] static void multiple_values_error(std::string name) { 1995 throw type_error("Got multiple values for keyword argument '" + name + "'"); 1996 } 1997 1998 [[noreturn]] static void argument_cast_error() { 1999 throw cast_error("Unable to convert call argument to Python object " 2000 "(compile in debug mode for details)"); 2001 } 2002 2003 [[noreturn]] static void argument_cast_error(std::string name, std::string type) { 2004 throw cast_error("Unable to convert call argument '" + name 2005 + "' of type '" + type + "' to Python object"); 2006 } 2007 2008private: 2009 tuple m_args; 2010 dict m_kwargs; 2011}; 2012 2013/// Collect only positional arguments for a Python function call 2014template <return_value_policy policy, typename... Args, 2015 typename = enable_if_t<all_of<is_positional<Args>...>::value>> 2016simple_collector<policy> collect_arguments(Args &&...args) { 2017 return simple_collector<policy>(std::forward<Args>(args)...); 2018} 2019 2020/// Collect all arguments, including keywords and unpacking (only instantiated when needed) 2021template <return_value_policy policy, typename... Args, 2022 typename = enable_if_t<!all_of<is_positional<Args>...>::value>> 2023unpacking_collector<policy> collect_arguments(Args &&...args) { 2024 // Following argument order rules for generalized unpacking according to PEP 448 2025 static_assert( 2026 constexpr_last<is_positional, Args...>() < constexpr_first<is_keyword_or_ds, Args...>() 2027 && constexpr_last<is_s_unpacking, Args...>() < constexpr_first<is_ds_unpacking, Args...>(), 2028 "Invalid function call: positional args must precede keywords and ** unpacking; " 2029 "* unpacking must precede ** unpacking" 2030 ); 2031 return unpacking_collector<policy>(std::forward<Args>(args)...); 2032} 2033 2034template <typename Derived> 2035template <return_value_policy policy, typename... Args> 2036object object_api<Derived>::operator()(Args &&...args) const { 2037 return detail::collect_arguments<policy>(std::forward<Args>(args)...).call(derived().ptr()); 2038} 2039 2040template <typename Derived> 2041template <return_value_policy policy, typename... Args> 2042object object_api<Derived>::call(Args &&...args) const { 2043 return operator()<policy>(std::forward<Args>(args)...); 2044} 2045 2046NAMESPACE_END(detail) 2047 2048#define PYBIND11_MAKE_OPAQUE(Type) \ 2049 namespace pybind11 { namespace detail { \ 2050 template<> class type_caster<Type> : public type_caster_base<Type> { }; \ 2051 }} 2052 2053NAMESPACE_END(PYBIND11_NAMESPACE) 2054