1/* 2 pybind11/pybind11.h: Main header file of the C++11 python 3 binding generator library 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#if defined(__INTEL_COMPILER) 14# pragma warning push 15# pragma warning disable 68 // integer conversion resulted in a change of sign 16# pragma warning disable 186 // pointless comparison of unsigned integer with zero 17# pragma warning disable 878 // incompatible exception specifications 18# pragma warning disable 1334 // the "template" keyword used for syntactic disambiguation may only be used within a template 19# pragma warning disable 1682 // implicit conversion of a 64-bit integral type to a smaller integral type (potential portability problem) 20# pragma warning disable 1786 // function "strdup" was declared deprecated 21# pragma warning disable 1875 // offsetof applied to non-POD (Plain Old Data) types is nonstandard 22# pragma warning disable 2196 // warning #2196: routine is both "inline" and "noinline" 23#elif defined(_MSC_VER) 24# pragma warning(push) 25# pragma warning(disable: 4100) // warning C4100: Unreferenced formal parameter 26# pragma warning(disable: 4127) // warning C4127: Conditional expression is constant 27# pragma warning(disable: 4512) // warning C4512: Assignment operator was implicitly defined as deleted 28# pragma warning(disable: 4800) // warning C4800: 'int': forcing value to bool 'true' or 'false' (performance warning) 29# pragma warning(disable: 4996) // warning C4996: The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name 30# pragma warning(disable: 4702) // warning C4702: unreachable code 31# pragma warning(disable: 4522) // warning C4522: multiple assignment operators specified 32#elif defined(__GNUG__) && !defined(__clang__) 33# pragma GCC diagnostic push 34# pragma GCC diagnostic ignored "-Wunused-but-set-parameter" 35# pragma GCC diagnostic ignored "-Wunused-but-set-variable" 36# pragma GCC diagnostic ignored "-Wmissing-field-initializers" 37# pragma GCC diagnostic ignored "-Wstrict-aliasing" 38# pragma GCC diagnostic ignored "-Wattributes" 39# if __GNUC__ >= 7 40# pragma GCC diagnostic ignored "-Wnoexcept-type" 41# endif 42#endif 43 44#include "attr.h" 45#include "options.h" 46#include "detail/class.h" 47#include "detail/init.h" 48 49#if defined(__GNUG__) && !defined(__clang__) 50# include <cxxabi.h> 51#endif 52 53NAMESPACE_BEGIN(PYBIND11_NAMESPACE) 54 55/// Wraps an arbitrary C++ function/method/lambda function/.. into a callable Python object 56class cpp_function : public function { 57public: 58 cpp_function() { } 59 cpp_function(std::nullptr_t) { } 60 61 /// Construct a cpp_function from a vanilla function pointer 62 template <typename Return, typename... Args, typename... Extra> 63 cpp_function(Return (*f)(Args...), const Extra&... extra) { 64 initialize(f, f, extra...); 65 } 66 67 /// Construct a cpp_function from a lambda function (possibly with internal state) 68 template <typename Func, typename... Extra, 69 typename = detail::enable_if_t<detail::is_lambda<Func>::value>> 70 cpp_function(Func &&f, const Extra&... extra) { 71 initialize(std::forward<Func>(f), 72 (detail::function_signature_t<Func> *) nullptr, extra...); 73 } 74 75 /// Construct a cpp_function from a class method (non-const) 76 template <typename Return, typename Class, typename... Arg, typename... Extra> 77 cpp_function(Return (Class::*f)(Arg...), const Extra&... extra) { 78 initialize([f](Class *c, Arg... args) -> Return { return (c->*f)(args...); }, 79 (Return (*) (Class *, Arg...)) nullptr, extra...); 80 } 81 82 /// Construct a cpp_function from a class method (const) 83 template <typename Return, typename Class, typename... Arg, typename... Extra> 84 cpp_function(Return (Class::*f)(Arg...) const, const Extra&... extra) { 85 initialize([f](const Class *c, Arg... args) -> Return { return (c->*f)(args...); }, 86 (Return (*)(const Class *, Arg ...)) nullptr, extra...); 87 } 88 89 /// Return the function name 90 object name() const { return attr("__name__"); } 91 92protected: 93 /// Space optimization: don't inline this frequently instantiated fragment 94 PYBIND11_NOINLINE detail::function_record *make_function_record() { 95 return new detail::function_record(); 96 } 97 98 /// Special internal constructor for functors, lambda functions, etc. 99 template <typename Func, typename Return, typename... Args, typename... Extra> 100 void initialize(Func &&f, Return (*)(Args...), const Extra&... extra) { 101 using namespace detail; 102 struct capture { remove_reference_t<Func> f; }; 103 104 /* Store the function including any extra state it might have (e.g. a lambda capture object) */ 105 auto rec = make_function_record(); 106 107 /* Store the capture object directly in the function record if there is enough space */ 108 if (sizeof(capture) <= sizeof(rec->data)) { 109 /* Without these pragmas, GCC warns that there might not be 110 enough space to use the placement new operator. However, the 111 'if' statement above ensures that this is the case. */ 112#if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6 113# pragma GCC diagnostic push 114# pragma GCC diagnostic ignored "-Wplacement-new" 115#endif 116 new ((capture *) &rec->data) capture { std::forward<Func>(f) }; 117#if defined(__GNUG__) && !defined(__clang__) && __GNUC__ >= 6 118# pragma GCC diagnostic pop 119#endif 120 if (!std::is_trivially_destructible<Func>::value) 121 rec->free_data = [](function_record *r) { ((capture *) &r->data)->~capture(); }; 122 } else { 123 rec->data[0] = new capture { std::forward<Func>(f) }; 124 rec->free_data = [](function_record *r) { delete ((capture *) r->data[0]); }; 125 } 126 127 /* Type casters for the function arguments and return value */ 128 using cast_in = argument_loader<Args...>; 129 using cast_out = make_caster< 130 conditional_t<std::is_void<Return>::value, void_type, Return> 131 >; 132 133 static_assert(expected_num_args<Extra...>(sizeof...(Args), cast_in::has_args, cast_in::has_kwargs), 134 "The number of argument annotations does not match the number of function arguments"); 135 136 /* Dispatch code which converts function arguments and performs the actual function call */ 137 rec->impl = [](function_call &call) -> handle { 138 cast_in args_converter; 139 140 /* Try to cast the function arguments into the C++ domain */ 141 if (!args_converter.load_args(call)) 142 return PYBIND11_TRY_NEXT_OVERLOAD; 143 144 /* Invoke call policy pre-call hook */ 145 process_attributes<Extra...>::precall(call); 146 147 /* Get a pointer to the capture object */ 148 auto data = (sizeof(capture) <= sizeof(call.func.data) 149 ? &call.func.data : call.func.data[0]); 150 capture *cap = const_cast<capture *>(reinterpret_cast<const capture *>(data)); 151 152 /* Override policy for rvalues -- usually to enforce rvp::move on an rvalue */ 153 return_value_policy policy = return_value_policy_override<Return>::policy(call.func.policy); 154 155 /* Function scope guard -- defaults to the compile-to-nothing `void_type` */ 156 using Guard = extract_guard_t<Extra...>; 157 158 /* Perform the function call */ 159 handle result = cast_out::cast( 160 std::move(args_converter).template call<Return, Guard>(cap->f), policy, call.parent); 161 162 /* Invoke call policy post-call hook */ 163 process_attributes<Extra...>::postcall(call, result); 164 165 return result; 166 }; 167 168 /* Process any user-provided function attributes */ 169 process_attributes<Extra...>::init(extra..., rec); 170 171 /* Generate a readable signature describing the function's arguments and return value types */ 172 static constexpr auto signature = _("(") + cast_in::arg_names + _(") -> ") + cast_out::name; 173 PYBIND11_DESCR_CONSTEXPR auto types = decltype(signature)::types(); 174 175 /* Register the function with Python from generic (non-templated) code */ 176 initialize_generic(rec, signature.text, types.data(), sizeof...(Args)); 177 178 if (cast_in::has_args) rec->has_args = true; 179 if (cast_in::has_kwargs) rec->has_kwargs = true; 180 181 /* Stash some additional information used by an important optimization in 'functional.h' */ 182 using FunctionType = Return (*)(Args...); 183 constexpr bool is_function_ptr = 184 std::is_convertible<Func, FunctionType>::value && 185 sizeof(capture) == sizeof(void *); 186 if (is_function_ptr) { 187 rec->is_stateless = true; 188 rec->data[1] = const_cast<void *>(reinterpret_cast<const void *>(&typeid(FunctionType))); 189 } 190 } 191 192 /// Register a function call with Python (generic non-templated code goes here) 193 void initialize_generic(detail::function_record *rec, const char *text, 194 const std::type_info *const *types, size_t args) { 195 196 /* Create copies of all referenced C-style strings */ 197 rec->name = strdup(rec->name ? rec->name : ""); 198 if (rec->doc) rec->doc = strdup(rec->doc); 199 for (auto &a: rec->args) { 200 if (a.name) 201 a.name = strdup(a.name); 202 if (a.descr) 203 a.descr = strdup(a.descr); 204 else if (a.value) 205 a.descr = strdup(a.value.attr("__repr__")().cast<std::string>().c_str()); 206 } 207 208 rec->is_constructor = !strcmp(rec->name, "__init__") || !strcmp(rec->name, "__setstate__"); 209 210#if !defined(NDEBUG) && !defined(PYBIND11_DISABLE_NEW_STYLE_INIT_WARNING) 211 if (rec->is_constructor && !rec->is_new_style_constructor) { 212 const auto class_name = std::string(((PyTypeObject *) rec->scope.ptr())->tp_name); 213 const auto func_name = std::string(rec->name); 214 PyErr_WarnEx( 215 PyExc_FutureWarning, 216 ("pybind11-bound class '" + class_name + "' is using an old-style " 217 "placement-new '" + func_name + "' which has been deprecated. See " 218 "the upgrade guide in pybind11's docs. This message is only visible " 219 "when compiled in debug mode.").c_str(), 0 220 ); 221 } 222#endif 223 224 /* Generate a proper function signature */ 225 std::string signature; 226 size_t type_index = 0, arg_index = 0; 227 for (auto *pc = text; *pc != '\0'; ++pc) { 228 const auto c = *pc; 229 230 if (c == '{') { 231 // Write arg name for everything except *args and **kwargs. 232 if (*(pc + 1) == '*') 233 continue; 234 235 if (arg_index < rec->args.size() && rec->args[arg_index].name) { 236 signature += rec->args[arg_index].name; 237 } else if (arg_index == 0 && rec->is_method) { 238 signature += "self"; 239 } else { 240 signature += "arg" + std::to_string(arg_index - (rec->is_method ? 1 : 0)); 241 } 242 signature += ": "; 243 } else if (c == '}') { 244 // Write default value if available. 245 if (arg_index < rec->args.size() && rec->args[arg_index].descr) { 246 signature += " = "; 247 signature += rec->args[arg_index].descr; 248 } 249 arg_index++; 250 } else if (c == '%') { 251 const std::type_info *t = types[type_index++]; 252 if (!t) 253 pybind11_fail("Internal error while parsing type signature (1)"); 254 if (auto tinfo = detail::get_type_info(*t)) { 255 handle th((PyObject *) tinfo->type); 256 signature += 257 th.attr("__module__").cast<std::string>() + "." + 258 th.attr("__qualname__").cast<std::string>(); // Python 3.3+, but we backport it to earlier versions 259 } else if (rec->is_new_style_constructor && arg_index == 0) { 260 // A new-style `__init__` takes `self` as `value_and_holder`. 261 // Rewrite it to the proper class type. 262 signature += 263 rec->scope.attr("__module__").cast<std::string>() + "." + 264 rec->scope.attr("__qualname__").cast<std::string>(); 265 } else { 266 std::string tname(t->name()); 267 detail::clean_type_id(tname); 268 signature += tname; 269 } 270 } else { 271 signature += c; 272 } 273 } 274 if (arg_index != args || types[type_index] != nullptr) 275 pybind11_fail("Internal error while parsing type signature (2)"); 276 277#if PY_MAJOR_VERSION < 3 278 if (strcmp(rec->name, "__next__") == 0) { 279 std::free(rec->name); 280 rec->name = strdup("next"); 281 } else if (strcmp(rec->name, "__bool__") == 0) { 282 std::free(rec->name); 283 rec->name = strdup("__nonzero__"); 284 } 285#endif 286 rec->signature = strdup(signature.c_str()); 287 rec->args.shrink_to_fit(); 288 rec->nargs = (std::uint16_t) args; 289 290 if (rec->sibling && PYBIND11_INSTANCE_METHOD_CHECK(rec->sibling.ptr())) 291 rec->sibling = PYBIND11_INSTANCE_METHOD_GET_FUNCTION(rec->sibling.ptr()); 292 293 detail::function_record *chain = nullptr, *chain_start = rec; 294 if (rec->sibling) { 295 if (PyCFunction_Check(rec->sibling.ptr())) { 296 auto rec_capsule = reinterpret_borrow<capsule>(PyCFunction_GET_SELF(rec->sibling.ptr())); 297 chain = (detail::function_record *) rec_capsule; 298 /* Never append a method to an overload chain of a parent class; 299 instead, hide the parent's overloads in this case */ 300 if (!chain->scope.is(rec->scope)) 301 chain = nullptr; 302 } 303 // Don't trigger for things like the default __init__, which are wrapper_descriptors that we are intentionally replacing 304 else if (!rec->sibling.is_none() && rec->name[0] != '_') 305 pybind11_fail("Cannot overload existing non-function object \"" + std::string(rec->name) + 306 "\" with a function of the same name"); 307 } 308 309 if (!chain) { 310 /* No existing overload was found, create a new function object */ 311 rec->def = new PyMethodDef(); 312 std::memset(rec->def, 0, sizeof(PyMethodDef)); 313 rec->def->ml_name = rec->name; 314 rec->def->ml_meth = reinterpret_cast<PyCFunction>(reinterpret_cast<void (*) (void)>(*dispatcher)); 315 rec->def->ml_flags = METH_VARARGS | METH_KEYWORDS; 316 317 capsule rec_capsule(rec, [](void *ptr) { 318 destruct((detail::function_record *) ptr); 319 }); 320 321 object scope_module; 322 if (rec->scope) { 323 if (hasattr(rec->scope, "__module__")) { 324 scope_module = rec->scope.attr("__module__"); 325 } else if (hasattr(rec->scope, "__name__")) { 326 scope_module = rec->scope.attr("__name__"); 327 } 328 } 329 330 m_ptr = PyCFunction_NewEx(rec->def, rec_capsule.ptr(), scope_module.ptr()); 331 if (!m_ptr) 332 pybind11_fail("cpp_function::cpp_function(): Could not allocate function object"); 333 } else { 334 /* Append at the end of the overload chain */ 335 m_ptr = rec->sibling.ptr(); 336 inc_ref(); 337 chain_start = chain; 338 if (chain->is_method != rec->is_method) 339 pybind11_fail("overloading a method with both static and instance methods is not supported; " 340 #if defined(NDEBUG) 341 "compile in debug mode for more details" 342 #else 343 "error while attempting to bind " + std::string(rec->is_method ? "instance" : "static") + " method " + 344 std::string(pybind11::str(rec->scope.attr("__name__"))) + "." + std::string(rec->name) + signature 345 #endif 346 ); 347 while (chain->next) 348 chain = chain->next; 349 chain->next = rec; 350 } 351 352 std::string signatures; 353 int index = 0; 354 /* Create a nice pydoc rec including all signatures and 355 docstrings of the functions in the overload chain */ 356 if (chain && options::show_function_signatures()) { 357 // First a generic signature 358 signatures += rec->name; 359 signatures += "(*args, **kwargs)\n"; 360 signatures += "Overloaded function.\n\n"; 361 } 362 // Then specific overload signatures 363 bool first_user_def = true; 364 for (auto it = chain_start; it != nullptr; it = it->next) { 365 if (options::show_function_signatures()) { 366 if (index > 0) signatures += "\n"; 367 if (chain) 368 signatures += std::to_string(++index) + ". "; 369 signatures += rec->name; 370 signatures += it->signature; 371 signatures += "\n"; 372 } 373 if (it->doc && strlen(it->doc) > 0 && options::show_user_defined_docstrings()) { 374 // If we're appending another docstring, and aren't printing function signatures, we 375 // need to append a newline first: 376 if (!options::show_function_signatures()) { 377 if (first_user_def) first_user_def = false; 378 else signatures += "\n"; 379 } 380 if (options::show_function_signatures()) signatures += "\n"; 381 signatures += it->doc; 382 if (options::show_function_signatures()) signatures += "\n"; 383 } 384 } 385 386 /* Install docstring */ 387 PyCFunctionObject *func = (PyCFunctionObject *) m_ptr; 388 if (func->m_ml->ml_doc) 389 std::free(const_cast<char *>(func->m_ml->ml_doc)); 390 func->m_ml->ml_doc = strdup(signatures.c_str()); 391 392 if (rec->is_method) { 393 m_ptr = PYBIND11_INSTANCE_METHOD_NEW(m_ptr, rec->scope.ptr()); 394 if (!m_ptr) 395 pybind11_fail("cpp_function::cpp_function(): Could not allocate instance method object"); 396 Py_DECREF(func); 397 } 398 } 399 400 /// When a cpp_function is GCed, release any memory allocated by pybind11 401 static void destruct(detail::function_record *rec) { 402 while (rec) { 403 detail::function_record *next = rec->next; 404 if (rec->free_data) 405 rec->free_data(rec); 406 std::free((char *) rec->name); 407 std::free((char *) rec->doc); 408 std::free((char *) rec->signature); 409 for (auto &arg: rec->args) { 410 std::free(const_cast<char *>(arg.name)); 411 std::free(const_cast<char *>(arg.descr)); 412 arg.value.dec_ref(); 413 } 414 if (rec->def) { 415 std::free(const_cast<char *>(rec->def->ml_doc)); 416 delete rec->def; 417 } 418 delete rec; 419 rec = next; 420 } 421 } 422 423 /// Main dispatch logic for calls to functions bound using pybind11 424 static PyObject *dispatcher(PyObject *self, PyObject *args_in, PyObject *kwargs_in) { 425 using namespace detail; 426 427 /* Iterator over the list of potentially admissible overloads */ 428 const function_record *overloads = (function_record *) PyCapsule_GetPointer(self, nullptr), 429 *it = overloads; 430 431 /* Need to know how many arguments + keyword arguments there are to pick the right overload */ 432 const size_t n_args_in = (size_t) PyTuple_GET_SIZE(args_in); 433 434 handle parent = n_args_in > 0 ? PyTuple_GET_ITEM(args_in, 0) : nullptr, 435 result = PYBIND11_TRY_NEXT_OVERLOAD; 436 437 auto self_value_and_holder = value_and_holder(); 438 if (overloads->is_constructor) { 439 const auto tinfo = get_type_info((PyTypeObject *) overloads->scope.ptr()); 440 const auto pi = reinterpret_cast<instance *>(parent.ptr()); 441 self_value_and_holder = pi->get_value_and_holder(tinfo, false); 442 443 if (!self_value_and_holder.type || !self_value_and_holder.inst) { 444 PyErr_SetString(PyExc_TypeError, "__init__(self, ...) called with invalid `self` argument"); 445 return nullptr; 446 } 447 448 // If this value is already registered it must mean __init__ is invoked multiple times; 449 // we really can't support that in C++, so just ignore the second __init__. 450 if (self_value_and_holder.instance_registered()) 451 return none().release().ptr(); 452 } 453 454 try { 455 // We do this in two passes: in the first pass, we load arguments with `convert=false`; 456 // in the second, we allow conversion (except for arguments with an explicit 457 // py::arg().noconvert()). This lets us prefer calls without conversion, with 458 // conversion as a fallback. 459 std::vector<function_call> second_pass; 460 461 // However, if there are no overloads, we can just skip the no-convert pass entirely 462 const bool overloaded = it != nullptr && it->next != nullptr; 463 464 for (; it != nullptr; it = it->next) { 465 466 /* For each overload: 467 1. Copy all positional arguments we were given, also checking to make sure that 468 named positional arguments weren't *also* specified via kwarg. 469 2. If we weren't given enough, try to make up the omitted ones by checking 470 whether they were provided by a kwarg matching the `py::arg("name")` name. If 471 so, use it (and remove it from kwargs; if not, see if the function binding 472 provided a default that we can use. 473 3. Ensure that either all keyword arguments were "consumed", or that the function 474 takes a kwargs argument to accept unconsumed kwargs. 475 4. Any positional arguments still left get put into a tuple (for args), and any 476 leftover kwargs get put into a dict. 477 5. Pack everything into a vector; if we have py::args or py::kwargs, they are an 478 extra tuple or dict at the end of the positional arguments. 479 6. Call the function call dispatcher (function_record::impl) 480 481 If one of these fail, move on to the next overload and keep trying until we get a 482 result other than PYBIND11_TRY_NEXT_OVERLOAD. 483 */ 484 485 const function_record &func = *it; 486 size_t pos_args = func.nargs; // Number of positional arguments that we need 487 if (func.has_args) --pos_args; // (but don't count py::args 488 if (func.has_kwargs) --pos_args; // or py::kwargs) 489 490 if (!func.has_args && n_args_in > pos_args) 491 continue; // Too many arguments for this overload 492 493 if (n_args_in < pos_args && func.args.size() < pos_args) 494 continue; // Not enough arguments given, and not enough defaults to fill in the blanks 495 496 function_call call(func, parent); 497 498 size_t args_to_copy = (std::min)(pos_args, n_args_in); // Protect std::min with parentheses 499 size_t args_copied = 0; 500 501 // 0. Inject new-style `self` argument 502 if (func.is_new_style_constructor) { 503 // The `value` may have been preallocated by an old-style `__init__` 504 // if it was a preceding candidate for overload resolution. 505 if (self_value_and_holder) 506 self_value_and_holder.type->dealloc(self_value_and_holder); 507 508 call.init_self = PyTuple_GET_ITEM(args_in, 0); 509 call.args.push_back(reinterpret_cast<PyObject *>(&self_value_and_holder)); 510 call.args_convert.push_back(false); 511 ++args_copied; 512 } 513 514 // 1. Copy any position arguments given. 515 bool bad_arg = false; 516 for (; args_copied < args_to_copy; ++args_copied) { 517 const argument_record *arg_rec = args_copied < func.args.size() ? &func.args[args_copied] : nullptr; 518 if (kwargs_in && arg_rec && arg_rec->name && PyDict_GetItemString(kwargs_in, arg_rec->name)) { 519 bad_arg = true; 520 break; 521 } 522 523 handle arg(PyTuple_GET_ITEM(args_in, args_copied)); 524 if (arg_rec && !arg_rec->none && arg.is_none()) { 525 bad_arg = true; 526 break; 527 } 528 call.args.push_back(arg); 529 call.args_convert.push_back(arg_rec ? arg_rec->convert : true); 530 } 531 if (bad_arg) 532 continue; // Maybe it was meant for another overload (issue #688) 533 534 // We'll need to copy this if we steal some kwargs for defaults 535 dict kwargs = reinterpret_borrow<dict>(kwargs_in); 536 537 // 2. Check kwargs and, failing that, defaults that may help complete the list 538 if (args_copied < pos_args) { 539 bool copied_kwargs = false; 540 541 for (; args_copied < pos_args; ++args_copied) { 542 const auto &arg = func.args[args_copied]; 543 544 handle value; 545 if (kwargs_in && arg.name) 546 value = PyDict_GetItemString(kwargs.ptr(), arg.name); 547 548 if (value) { 549 // Consume a kwargs value 550 if (!copied_kwargs) { 551 kwargs = reinterpret_steal<dict>(PyDict_Copy(kwargs.ptr())); 552 copied_kwargs = true; 553 } 554 PyDict_DelItemString(kwargs.ptr(), arg.name); 555 } else if (arg.value) { 556 value = arg.value; 557 } 558 559 if (value) { 560 call.args.push_back(value); 561 call.args_convert.push_back(arg.convert); 562 } 563 else 564 break; 565 } 566 567 if (args_copied < pos_args) 568 continue; // Not enough arguments, defaults, or kwargs to fill the positional arguments 569 } 570 571 // 3. Check everything was consumed (unless we have a kwargs arg) 572 if (kwargs && kwargs.size() > 0 && !func.has_kwargs) 573 continue; // Unconsumed kwargs, but no py::kwargs argument to accept them 574 575 // 4a. If we have a py::args argument, create a new tuple with leftovers 576 if (func.has_args) { 577 tuple extra_args; 578 if (args_to_copy == 0) { 579 // We didn't copy out any position arguments from the args_in tuple, so we 580 // can reuse it directly without copying: 581 extra_args = reinterpret_borrow<tuple>(args_in); 582 } else if (args_copied >= n_args_in) { 583 extra_args = tuple(0); 584 } else { 585 size_t args_size = n_args_in - args_copied; 586 extra_args = tuple(args_size); 587 for (size_t i = 0; i < args_size; ++i) { 588 extra_args[i] = PyTuple_GET_ITEM(args_in, args_copied + i); 589 } 590 } 591 call.args.push_back(extra_args); 592 call.args_convert.push_back(false); 593 call.args_ref = std::move(extra_args); 594 } 595 596 // 4b. If we have a py::kwargs, pass on any remaining kwargs 597 if (func.has_kwargs) { 598 if (!kwargs.ptr()) 599 kwargs = dict(); // If we didn't get one, send an empty one 600 call.args.push_back(kwargs); 601 call.args_convert.push_back(false); 602 call.kwargs_ref = std::move(kwargs); 603 } 604 605 // 5. Put everything in a vector. Not technically step 5, we've been building it 606 // in `call.args` all along. 607 #if !defined(NDEBUG) 608 if (call.args.size() != func.nargs || call.args_convert.size() != func.nargs) 609 pybind11_fail("Internal error: function call dispatcher inserted wrong number of arguments!"); 610 #endif 611 612 std::vector<bool> second_pass_convert; 613 if (overloaded) { 614 // We're in the first no-convert pass, so swap out the conversion flags for a 615 // set of all-false flags. If the call fails, we'll swap the flags back in for 616 // the conversion-allowed call below. 617 second_pass_convert.resize(func.nargs, false); 618 call.args_convert.swap(second_pass_convert); 619 } 620 621 // 6. Call the function. 622 try { 623 loader_life_support guard{}; 624 result = func.impl(call); 625 } catch (reference_cast_error &) { 626 result = PYBIND11_TRY_NEXT_OVERLOAD; 627 } 628 629 if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD) 630 break; 631 632 if (overloaded) { 633 // The (overloaded) call failed; if the call has at least one argument that 634 // permits conversion (i.e. it hasn't been explicitly specified `.noconvert()`) 635 // then add this call to the list of second pass overloads to try. 636 for (size_t i = func.is_method ? 1 : 0; i < pos_args; i++) { 637 if (second_pass_convert[i]) { 638 // Found one: swap the converting flags back in and store the call for 639 // the second pass. 640 call.args_convert.swap(second_pass_convert); 641 second_pass.push_back(std::move(call)); 642 break; 643 } 644 } 645 } 646 } 647 648 if (overloaded && !second_pass.empty() && result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) { 649 // The no-conversion pass finished without success, try again with conversion allowed 650 for (auto &call : second_pass) { 651 try { 652 loader_life_support guard{}; 653 result = call.func.impl(call); 654 } catch (reference_cast_error &) { 655 result = PYBIND11_TRY_NEXT_OVERLOAD; 656 } 657 658 if (result.ptr() != PYBIND11_TRY_NEXT_OVERLOAD) { 659 // The error reporting logic below expects 'it' to be valid, as it would be 660 // if we'd encountered this failure in the first-pass loop. 661 if (!result) 662 it = &call.func; 663 break; 664 } 665 } 666 } 667 } catch (error_already_set &e) { 668 e.restore(); 669 return nullptr; 670#if defined(__GNUG__) && !defined(__clang__) 671 } catch ( abi::__forced_unwind& ) { 672 throw; 673#endif 674 } catch (...) { 675 /* When an exception is caught, give each registered exception 676 translator a chance to translate it to a Python exception 677 in reverse order of registration. 678 679 A translator may choose to do one of the following: 680 681 - catch the exception and call PyErr_SetString or PyErr_SetObject 682 to set a standard (or custom) Python exception, or 683 - do nothing and let the exception fall through to the next translator, or 684 - delegate translation to the next translator by throwing a new type of exception. */ 685 686 auto last_exception = std::current_exception(); 687 auto ®istered_exception_translators = get_internals().registered_exception_translators; 688 for (auto& translator : registered_exception_translators) { 689 try { 690 translator(last_exception); 691 } catch (...) { 692 last_exception = std::current_exception(); 693 continue; 694 } 695 return nullptr; 696 } 697 PyErr_SetString(PyExc_SystemError, "Exception escaped from default exception translator!"); 698 return nullptr; 699 } 700 701 auto append_note_if_missing_header_is_suspected = [](std::string &msg) { 702 if (msg.find("std::") != std::string::npos) { 703 msg += "\n\n" 704 "Did you forget to `#include <pybind11/stl.h>`? Or <pybind11/complex.h>,\n" 705 "<pybind11/functional.h>, <pybind11/chrono.h>, etc. Some automatic\n" 706 "conversions are optional and require extra headers to be included\n" 707 "when compiling your pybind11 module."; 708 } 709 }; 710 711 if (result.ptr() == PYBIND11_TRY_NEXT_OVERLOAD) { 712 if (overloads->is_operator) 713 return handle(Py_NotImplemented).inc_ref().ptr(); 714 715 std::string msg = std::string(overloads->name) + "(): incompatible " + 716 std::string(overloads->is_constructor ? "constructor" : "function") + 717 " arguments. The following argument types are supported:\n"; 718 719 int ctr = 0; 720 for (const function_record *it2 = overloads; it2 != nullptr; it2 = it2->next) { 721 msg += " "+ std::to_string(++ctr) + ". "; 722 723 bool wrote_sig = false; 724 if (overloads->is_constructor) { 725 // For a constructor, rewrite `(self: Object, arg0, ...) -> NoneType` as `Object(arg0, ...)` 726 std::string sig = it2->signature; 727 size_t start = sig.find('(') + 7; // skip "(self: " 728 if (start < sig.size()) { 729 // End at the , for the next argument 730 size_t end = sig.find(", "), next = end + 2; 731 size_t ret = sig.rfind(" -> "); 732 // Or the ), if there is no comma: 733 if (end >= sig.size()) next = end = sig.find(')'); 734 if (start < end && next < sig.size()) { 735 msg.append(sig, start, end - start); 736 msg += '('; 737 msg.append(sig, next, ret - next); 738 wrote_sig = true; 739 } 740 } 741 } 742 if (!wrote_sig) msg += it2->signature; 743 744 msg += "\n"; 745 } 746 msg += "\nInvoked with: "; 747 auto args_ = reinterpret_borrow<tuple>(args_in); 748 bool some_args = false; 749 for (size_t ti = overloads->is_constructor ? 1 : 0; ti < args_.size(); ++ti) { 750 if (!some_args) some_args = true; 751 else msg += ", "; 752 msg += pybind11::repr(args_[ti]); 753 } 754 if (kwargs_in) { 755 auto kwargs = reinterpret_borrow<dict>(kwargs_in); 756 if (kwargs.size() > 0) { 757 if (some_args) msg += "; "; 758 msg += "kwargs: "; 759 bool first = true; 760 for (auto kwarg : kwargs) { 761 if (first) first = false; 762 else msg += ", "; 763 msg += pybind11::str("{}={!r}").format(kwarg.first, kwarg.second); 764 } 765 } 766 } 767 768 append_note_if_missing_header_is_suspected(msg); 769 PyErr_SetString(PyExc_TypeError, msg.c_str()); 770 return nullptr; 771 } else if (!result) { 772 std::string msg = "Unable to convert function return value to a " 773 "Python type! The signature was\n\t"; 774 msg += it->signature; 775 append_note_if_missing_header_is_suspected(msg); 776 PyErr_SetString(PyExc_TypeError, msg.c_str()); 777 return nullptr; 778 } else { 779 if (overloads->is_constructor && !self_value_and_holder.holder_constructed()) { 780 auto *pi = reinterpret_cast<instance *>(parent.ptr()); 781 self_value_and_holder.type->init_instance(pi, nullptr); 782 } 783 return result.ptr(); 784 } 785 } 786}; 787 788/// Wrapper for Python extension modules 789class module : public object { 790public: 791 PYBIND11_OBJECT_DEFAULT(module, object, PyModule_Check) 792 793 /// Create a new top-level Python module with the given name and docstring 794 explicit module(const char *name, const char *doc = nullptr) { 795 if (!options::show_user_defined_docstrings()) doc = nullptr; 796#if PY_MAJOR_VERSION >= 3 797 PyModuleDef *def = new PyModuleDef(); 798 std::memset(def, 0, sizeof(PyModuleDef)); 799 def->m_name = name; 800 def->m_doc = doc; 801 def->m_size = -1; 802 Py_INCREF(def); 803 m_ptr = PyModule_Create(def); 804#else 805 m_ptr = Py_InitModule3(name, nullptr, doc); 806#endif 807 if (m_ptr == nullptr) 808 pybind11_fail("Internal error in module::module()"); 809 inc_ref(); 810 } 811 812 /** \rst 813 Create Python binding for a new function within the module scope. ``Func`` 814 can be a plain C++ function, a function pointer, or a lambda function. For 815 details on the ``Extra&& ... extra`` argument, see section :ref:`extras`. 816 \endrst */ 817 template <typename Func, typename... Extra> 818 module &def(const char *name_, Func &&f, const Extra& ... extra) { 819 cpp_function func(std::forward<Func>(f), name(name_), scope(*this), 820 sibling(getattr(*this, name_, none())), extra...); 821 // NB: allow overwriting here because cpp_function sets up a chain with the intention of 822 // overwriting (and has already checked internally that it isn't overwriting non-functions). 823 add_object(name_, func, true /* overwrite */); 824 return *this; 825 } 826 827 /** \rst 828 Create and return a new Python submodule with the given name and docstring. 829 This also works recursively, i.e. 830 831 .. code-block:: cpp 832 833 py::module m("example", "pybind11 example plugin"); 834 py::module m2 = m.def_submodule("sub", "A submodule of 'example'"); 835 py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'"); 836 \endrst */ 837 module def_submodule(const char *name, const char *doc = nullptr) { 838 std::string full_name = std::string(PyModule_GetName(m_ptr)) 839 + std::string(".") + std::string(name); 840 auto result = reinterpret_borrow<module>(PyImport_AddModule(full_name.c_str())); 841 if (doc && options::show_user_defined_docstrings()) 842 result.attr("__doc__") = pybind11::str(doc); 843 attr(name) = result; 844 return result; 845 } 846 847 /// Import and return a module or throws `error_already_set`. 848 static module import(const char *name) { 849 PyObject *obj = PyImport_ImportModule(name); 850 if (!obj) 851 throw error_already_set(); 852 return reinterpret_steal<module>(obj); 853 } 854 855 /// Reload the module or throws `error_already_set`. 856 void reload() { 857 PyObject *obj = PyImport_ReloadModule(ptr()); 858 if (!obj) 859 throw error_already_set(); 860 *this = reinterpret_steal<module>(obj); 861 } 862 863 // Adds an object to the module using the given name. Throws if an object with the given name 864 // already exists. 865 // 866 // overwrite should almost always be false: attempting to overwrite objects that pybind11 has 867 // established will, in most cases, break things. 868 PYBIND11_NOINLINE void add_object(const char *name, handle obj, bool overwrite = false) { 869 if (!overwrite && hasattr(*this, name)) 870 pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" + 871 std::string(name) + "\""); 872 873 PyModule_AddObject(ptr(), name, obj.inc_ref().ptr() /* steals a reference */); 874 } 875}; 876 877/// \ingroup python_builtins 878/// Return a dictionary representing the global variables in the current execution frame, 879/// or ``__main__.__dict__`` if there is no frame (usually when the interpreter is embedded). 880inline dict globals() { 881 PyObject *p = PyEval_GetGlobals(); 882 return reinterpret_borrow<dict>(p ? p : module::import("__main__").attr("__dict__").ptr()); 883} 884 885NAMESPACE_BEGIN(detail) 886/// Generic support for creating new Python heap types 887class generic_type : public object { 888 template <typename...> friend class class_; 889public: 890 PYBIND11_OBJECT_DEFAULT(generic_type, object, PyType_Check) 891protected: 892 void initialize(const type_record &rec) { 893 if (rec.scope && hasattr(rec.scope, rec.name)) 894 pybind11_fail("generic_type: cannot initialize type \"" + std::string(rec.name) + 895 "\": an object with that name is already defined"); 896 897 if (rec.module_local ? get_local_type_info(*rec.type) : get_global_type_info(*rec.type)) 898 pybind11_fail("generic_type: type \"" + std::string(rec.name) + 899 "\" is already registered!"); 900 901 m_ptr = make_new_python_type(rec); 902 903 /* Register supplemental type information in C++ dict */ 904 auto *tinfo = new detail::type_info(); 905 tinfo->type = (PyTypeObject *) m_ptr; 906 tinfo->cpptype = rec.type; 907 tinfo->type_size = rec.type_size; 908 tinfo->type_align = rec.type_align; 909 tinfo->operator_new = rec.operator_new; 910 tinfo->holder_size_in_ptrs = size_in_ptrs(rec.holder_size); 911 tinfo->init_instance = rec.init_instance; 912 tinfo->dealloc = rec.dealloc; 913 tinfo->simple_type = true; 914 tinfo->simple_ancestors = true; 915 tinfo->default_holder = rec.default_holder; 916 tinfo->module_local = rec.module_local; 917 918 auto &internals = get_internals(); 919 auto tindex = std::type_index(*rec.type); 920 tinfo->direct_conversions = &internals.direct_conversions[tindex]; 921 if (rec.module_local) 922 registered_local_types_cpp()[tindex] = tinfo; 923 else 924 internals.registered_types_cpp[tindex] = tinfo; 925 internals.registered_types_py[(PyTypeObject *) m_ptr] = { tinfo }; 926 927 if (rec.bases.size() > 1 || rec.multiple_inheritance) { 928 mark_parents_nonsimple(tinfo->type); 929 tinfo->simple_ancestors = false; 930 } 931 else if (rec.bases.size() == 1) { 932 auto parent_tinfo = get_type_info((PyTypeObject *) rec.bases[0].ptr()); 933 tinfo->simple_ancestors = parent_tinfo->simple_ancestors; 934 } 935 936 if (rec.module_local) { 937 // Stash the local typeinfo and loader so that external modules can access it. 938 tinfo->module_local_load = &type_caster_generic::local_load; 939 setattr(m_ptr, PYBIND11_MODULE_LOCAL_ID, capsule(tinfo)); 940 } 941 } 942 943 /// Helper function which tags all parents of a type using mult. inheritance 944 void mark_parents_nonsimple(PyTypeObject *value) { 945 auto t = reinterpret_borrow<tuple>(value->tp_bases); 946 for (handle h : t) { 947 auto tinfo2 = get_type_info((PyTypeObject *) h.ptr()); 948 if (tinfo2) 949 tinfo2->simple_type = false; 950 mark_parents_nonsimple((PyTypeObject *) h.ptr()); 951 } 952 } 953 954 void install_buffer_funcs( 955 buffer_info *(*get_buffer)(PyObject *, void *), 956 void *get_buffer_data) { 957 PyHeapTypeObject *type = (PyHeapTypeObject*) m_ptr; 958 auto tinfo = detail::get_type_info(&type->ht_type); 959 960 if (!type->ht_type.tp_as_buffer) 961 pybind11_fail( 962 "To be able to register buffer protocol support for the type '" + 963 std::string(tinfo->type->tp_name) + 964 "' the associated class<>(..) invocation must " 965 "include the pybind11::buffer_protocol() annotation!"); 966 967 tinfo->get_buffer = get_buffer; 968 tinfo->get_buffer_data = get_buffer_data; 969 } 970 971 // rec_func must be set for either fget or fset. 972 void def_property_static_impl(const char *name, 973 handle fget, handle fset, 974 detail::function_record *rec_func) { 975 const auto is_static = rec_func && !(rec_func->is_method && rec_func->scope); 976 const auto has_doc = rec_func && rec_func->doc && pybind11::options::show_user_defined_docstrings(); 977 auto property = handle((PyObject *) (is_static ? get_internals().static_property_type 978 : &PyProperty_Type)); 979 attr(name) = property(fget.ptr() ? fget : none(), 980 fset.ptr() ? fset : none(), 981 /*deleter*/none(), 982 pybind11::str(has_doc ? rec_func->doc : "")); 983 } 984}; 985 986/// Set the pointer to operator new if it exists. The cast is needed because it can be overloaded. 987template <typename T, typename = void_t<decltype(static_cast<void *(*)(size_t)>(T::operator new))>> 988void set_operator_new(type_record *r) { r->operator_new = &T::operator new; } 989 990template <typename> void set_operator_new(...) { } 991 992template <typename T, typename SFINAE = void> struct has_operator_delete : std::false_type { }; 993template <typename T> struct has_operator_delete<T, void_t<decltype(static_cast<void (*)(void *)>(T::operator delete))>> 994 : std::true_type { }; 995template <typename T, typename SFINAE = void> struct has_operator_delete_size : std::false_type { }; 996template <typename T> struct has_operator_delete_size<T, void_t<decltype(static_cast<void (*)(void *, size_t)>(T::operator delete))>> 997 : std::true_type { }; 998/// Call class-specific delete if it exists or global otherwise. Can also be an overload set. 999template <typename T, enable_if_t<has_operator_delete<T>::value, int> = 0> 1000void call_operator_delete(T *p, size_t, size_t) { T::operator delete(p); } 1001template <typename T, enable_if_t<!has_operator_delete<T>::value && has_operator_delete_size<T>::value, int> = 0> 1002void call_operator_delete(T *p, size_t s, size_t) { T::operator delete(p, s); } 1003 1004inline void call_operator_delete(void *p, size_t s, size_t a) { 1005 (void)s; (void)a; 1006#if defined(PYBIND11_CPP17) 1007 if (a > __STDCPP_DEFAULT_NEW_ALIGNMENT__) 1008 ::operator delete(p, s, std::align_val_t(a)); 1009 else 1010 ::operator delete(p, s); 1011#else 1012 ::operator delete(p); 1013#endif 1014} 1015 1016NAMESPACE_END(detail) 1017 1018/// Given a pointer to a member function, cast it to its `Derived` version. 1019/// Forward everything else unchanged. 1020template <typename /*Derived*/, typename F> 1021auto method_adaptor(F &&f) -> decltype(std::forward<F>(f)) { return std::forward<F>(f); } 1022 1023template <typename Derived, typename Return, typename Class, typename... Args> 1024auto method_adaptor(Return (Class::*pmf)(Args...)) -> Return (Derived::*)(Args...) { 1025 static_assert(detail::is_accessible_base_of<Class, Derived>::value, 1026 "Cannot bind an inaccessible base class method; use a lambda definition instead"); 1027 return pmf; 1028} 1029 1030template <typename Derived, typename Return, typename Class, typename... Args> 1031auto method_adaptor(Return (Class::*pmf)(Args...) const) -> Return (Derived::*)(Args...) const { 1032 static_assert(detail::is_accessible_base_of<Class, Derived>::value, 1033 "Cannot bind an inaccessible base class method; use a lambda definition instead"); 1034 return pmf; 1035} 1036 1037template <typename type_, typename... options> 1038class class_ : public detail::generic_type { 1039 template <typename T> using is_holder = detail::is_holder_type<type_, T>; 1040 template <typename T> using is_subtype = detail::is_strict_base_of<type_, T>; 1041 template <typename T> using is_base = detail::is_strict_base_of<T, type_>; 1042 // struct instead of using here to help MSVC: 1043 template <typename T> struct is_valid_class_option : 1044 detail::any_of<is_holder<T>, is_subtype<T>, is_base<T>> {}; 1045 1046public: 1047 using type = type_; 1048 using type_alias = detail::exactly_one_t<is_subtype, void, options...>; 1049 constexpr static bool has_alias = !std::is_void<type_alias>::value; 1050 using holder_type = detail::exactly_one_t<is_holder, std::unique_ptr<type>, options...>; 1051 1052 static_assert(detail::all_of<is_valid_class_option<options>...>::value, 1053 "Unknown/invalid class_ template parameters provided"); 1054 1055 static_assert(!has_alias || std::is_polymorphic<type>::value, 1056 "Cannot use an alias class with a non-polymorphic type"); 1057 1058 PYBIND11_OBJECT(class_, generic_type, PyType_Check) 1059 1060 template <typename... Extra> 1061 class_(handle scope, const char *name, const Extra &... extra) { 1062 using namespace detail; 1063 1064 // MI can only be specified via class_ template options, not constructor parameters 1065 static_assert( 1066 none_of<is_pyobject<Extra>...>::value || // no base class arguments, or: 1067 ( constexpr_sum(is_pyobject<Extra>::value...) == 1 && // Exactly one base 1068 constexpr_sum(is_base<options>::value...) == 0 && // no template option bases 1069 none_of<std::is_same<multiple_inheritance, Extra>...>::value), // no multiple_inheritance attr 1070 "Error: multiple inheritance bases must be specified via class_ template options"); 1071 1072 type_record record; 1073 record.scope = scope; 1074 record.name = name; 1075 record.type = &typeid(type); 1076 record.type_size = sizeof(conditional_t<has_alias, type_alias, type>); 1077 record.type_align = alignof(conditional_t<has_alias, type_alias, type>&); 1078 record.holder_size = sizeof(holder_type); 1079 record.init_instance = init_instance; 1080 record.dealloc = dealloc; 1081 record.default_holder = detail::is_instantiation<std::unique_ptr, holder_type>::value; 1082 1083 set_operator_new<type>(&record); 1084 1085 /* Register base classes specified via template arguments to class_, if any */ 1086 PYBIND11_EXPAND_SIDE_EFFECTS(add_base<options>(record)); 1087 1088 /* Process optional arguments, if any */ 1089 process_attributes<Extra...>::init(extra..., &record); 1090 1091 generic_type::initialize(record); 1092 1093 if (has_alias) { 1094 auto &instances = record.module_local ? registered_local_types_cpp() : get_internals().registered_types_cpp; 1095 instances[std::type_index(typeid(type_alias))] = instances[std::type_index(typeid(type))]; 1096 } 1097 } 1098 1099 template <typename Base, detail::enable_if_t<is_base<Base>::value, int> = 0> 1100 static void add_base(detail::type_record &rec) { 1101 rec.add_base(typeid(Base), [](void *src) -> void * { 1102 return static_cast<Base *>(reinterpret_cast<type *>(src)); 1103 }); 1104 } 1105 1106 template <typename Base, detail::enable_if_t<!is_base<Base>::value, int> = 0> 1107 static void add_base(detail::type_record &) { } 1108 1109 template <typename Func, typename... Extra> 1110 class_ &def(const char *name_, Func&& f, const Extra&... extra) { 1111 cpp_function cf(method_adaptor<type>(std::forward<Func>(f)), name(name_), is_method(*this), 1112 sibling(getattr(*this, name_, none())), extra...); 1113 attr(cf.name()) = cf; 1114 return *this; 1115 } 1116 1117 template <typename Func, typename... Extra> class_ & 1118 def_static(const char *name_, Func &&f, const Extra&... extra) { 1119 static_assert(!std::is_member_function_pointer<Func>::value, 1120 "def_static(...) called with a non-static member function pointer"); 1121 cpp_function cf(std::forward<Func>(f), name(name_), scope(*this), 1122 sibling(getattr(*this, name_, none())), extra...); 1123 attr(cf.name()) = staticmethod(cf); 1124 return *this; 1125 } 1126 1127 template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra> 1128 class_ &def(const detail::op_<id, ot, L, R> &op, const Extra&... extra) { 1129 op.execute(*this, extra...); 1130 return *this; 1131 } 1132 1133 template <detail::op_id id, detail::op_type ot, typename L, typename R, typename... Extra> 1134 class_ & def_cast(const detail::op_<id, ot, L, R> &op, const Extra&... extra) { 1135 op.execute_cast(*this, extra...); 1136 return *this; 1137 } 1138 1139 template <typename... Args, typename... Extra> 1140 class_ &def(const detail::initimpl::constructor<Args...> &init, const Extra&... extra) { 1141 init.execute(*this, extra...); 1142 return *this; 1143 } 1144 1145 template <typename... Args, typename... Extra> 1146 class_ &def(const detail::initimpl::alias_constructor<Args...> &init, const Extra&... extra) { 1147 init.execute(*this, extra...); 1148 return *this; 1149 } 1150 1151 template <typename... Args, typename... Extra> 1152 class_ &def(detail::initimpl::factory<Args...> &&init, const Extra&... extra) { 1153 std::move(init).execute(*this, extra...); 1154 return *this; 1155 } 1156 1157 template <typename... Args, typename... Extra> 1158 class_ &def(detail::initimpl::pickle_factory<Args...> &&pf, const Extra &...extra) { 1159 std::move(pf).execute(*this, extra...); 1160 return *this; 1161 } 1162 1163 template <typename Func> class_& def_buffer(Func &&func) { 1164 struct capture { Func func; }; 1165 capture *ptr = new capture { std::forward<Func>(func) }; 1166 install_buffer_funcs([](PyObject *obj, void *ptr) -> buffer_info* { 1167 detail::make_caster<type> caster; 1168 if (!caster.load(obj, false)) 1169 return nullptr; 1170 return new buffer_info(((capture *) ptr)->func(caster)); 1171 }, ptr); 1172 return *this; 1173 } 1174 1175 template <typename Return, typename Class, typename... Args> 1176 class_ &def_buffer(Return (Class::*func)(Args...)) { 1177 return def_buffer([func] (type &obj) { return (obj.*func)(); }); 1178 } 1179 1180 template <typename Return, typename Class, typename... Args> 1181 class_ &def_buffer(Return (Class::*func)(Args...) const) { 1182 return def_buffer([func] (const type &obj) { return (obj.*func)(); }); 1183 } 1184 1185 template <typename C, typename D, typename... Extra> 1186 class_ &def_readwrite(const char *name, D C::*pm, const Extra&... extra) { 1187 static_assert(std::is_same<C, type>::value || std::is_base_of<C, type>::value, "def_readwrite() requires a class member (or base class member)"); 1188 cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this)), 1189 fset([pm](type &c, const D &value) { c.*pm = value; }, is_method(*this)); 1190 def_property(name, fget, fset, return_value_policy::reference_internal, extra...); 1191 return *this; 1192 } 1193 1194 template <typename C, typename D, typename... Extra> 1195 class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra) { 1196 static_assert(std::is_same<C, type>::value || std::is_base_of<C, type>::value, "def_readonly() requires a class member (or base class member)"); 1197 cpp_function fget([pm](const type &c) -> const D &{ return c.*pm; }, is_method(*this)); 1198 def_property_readonly(name, fget, return_value_policy::reference_internal, extra...); 1199 return *this; 1200 } 1201 1202 template <typename D, typename... Extra> 1203 class_ &def_readwrite_static(const char *name, D *pm, const Extra& ...extra) { 1204 cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this)), 1205 fset([pm](object, const D &value) { *pm = value; }, scope(*this)); 1206 def_property_static(name, fget, fset, return_value_policy::reference, extra...); 1207 return *this; 1208 } 1209 1210 template <typename D, typename... Extra> 1211 class_ &def_readonly_static(const char *name, const D *pm, const Extra& ...extra) { 1212 cpp_function fget([pm](object) -> const D &{ return *pm; }, scope(*this)); 1213 def_property_readonly_static(name, fget, return_value_policy::reference, extra...); 1214 return *this; 1215 } 1216 1217 /// Uses return_value_policy::reference_internal by default 1218 template <typename Getter, typename... Extra> 1219 class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra) { 1220 return def_property_readonly(name, cpp_function(method_adaptor<type>(fget)), 1221 return_value_policy::reference_internal, extra...); 1222 } 1223 1224 /// Uses cpp_function's return_value_policy by default 1225 template <typename... Extra> 1226 class_ &def_property_readonly(const char *name, const cpp_function &fget, const Extra& ...extra) { 1227 return def_property(name, fget, nullptr, extra...); 1228 } 1229 1230 /// Uses return_value_policy::reference by default 1231 template <typename Getter, typename... Extra> 1232 class_ &def_property_readonly_static(const char *name, const Getter &fget, const Extra& ...extra) { 1233 return def_property_readonly_static(name, cpp_function(fget), return_value_policy::reference, extra...); 1234 } 1235 1236 /// Uses cpp_function's return_value_policy by default 1237 template <typename... Extra> 1238 class_ &def_property_readonly_static(const char *name, const cpp_function &fget, const Extra& ...extra) { 1239 return def_property_static(name, fget, nullptr, extra...); 1240 } 1241 1242 /// Uses return_value_policy::reference_internal by default 1243 template <typename Getter, typename Setter, typename... Extra> 1244 class_ &def_property(const char *name, const Getter &fget, const Setter &fset, const Extra& ...extra) { 1245 return def_property(name, fget, cpp_function(method_adaptor<type>(fset)), extra...); 1246 } 1247 template <typename Getter, typename... Extra> 1248 class_ &def_property(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) { 1249 return def_property(name, cpp_function(method_adaptor<type>(fget)), fset, 1250 return_value_policy::reference_internal, extra...); 1251 } 1252 1253 /// Uses cpp_function's return_value_policy by default 1254 template <typename... Extra> 1255 class_ &def_property(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) { 1256 return def_property_static(name, fget, fset, is_method(*this), extra...); 1257 } 1258 1259 /// Uses return_value_policy::reference by default 1260 template <typename Getter, typename... Extra> 1261 class_ &def_property_static(const char *name, const Getter &fget, const cpp_function &fset, const Extra& ...extra) { 1262 return def_property_static(name, cpp_function(fget), fset, return_value_policy::reference, extra...); 1263 } 1264 1265 /// Uses cpp_function's return_value_policy by default 1266 template <typename... Extra> 1267 class_ &def_property_static(const char *name, const cpp_function &fget, const cpp_function &fset, const Extra& ...extra) { 1268 static_assert( 0 == detail::constexpr_sum(std::is_base_of<arg, Extra>::value...), 1269 "Argument annotations are not allowed for properties"); 1270 auto rec_fget = get_function_record(fget), rec_fset = get_function_record(fset); 1271 auto *rec_active = rec_fget; 1272 if (rec_fget) { 1273 char *doc_prev = rec_fget->doc; /* 'extra' field may include a property-specific documentation string */ 1274 detail::process_attributes<Extra...>::init(extra..., rec_fget); 1275 if (rec_fget->doc && rec_fget->doc != doc_prev) { 1276 free(doc_prev); 1277 rec_fget->doc = strdup(rec_fget->doc); 1278 } 1279 } 1280 if (rec_fset) { 1281 char *doc_prev = rec_fset->doc; 1282 detail::process_attributes<Extra...>::init(extra..., rec_fset); 1283 if (rec_fset->doc && rec_fset->doc != doc_prev) { 1284 free(doc_prev); 1285 rec_fset->doc = strdup(rec_fset->doc); 1286 } 1287 if (! rec_active) rec_active = rec_fset; 1288 } 1289 def_property_static_impl(name, fget, fset, rec_active); 1290 return *this; 1291 } 1292 1293private: 1294 /// Initialize holder object, variant 1: object derives from enable_shared_from_this 1295 template <typename T> 1296 static void init_holder(detail::instance *inst, detail::value_and_holder &v_h, 1297 const holder_type * /* unused */, const std::enable_shared_from_this<T> * /* dummy */) { 1298 try { 1299 auto sh = std::dynamic_pointer_cast<typename holder_type::element_type>( 1300 v_h.value_ptr<type>()->shared_from_this()); 1301 if (sh) { 1302 new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(sh)); 1303 v_h.set_holder_constructed(); 1304 } 1305 } catch (const std::bad_weak_ptr &) {} 1306 1307 if (!v_h.holder_constructed() && inst->owned) { 1308 new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>()); 1309 v_h.set_holder_constructed(); 1310 } 1311 } 1312 1313 static void init_holder_from_existing(const detail::value_and_holder &v_h, 1314 const holder_type *holder_ptr, std::true_type /*is_copy_constructible*/) { 1315 new (std::addressof(v_h.holder<holder_type>())) holder_type(*reinterpret_cast<const holder_type *>(holder_ptr)); 1316 } 1317 1318 static void init_holder_from_existing(const detail::value_and_holder &v_h, 1319 const holder_type *holder_ptr, std::false_type /*is_copy_constructible*/) { 1320 new (std::addressof(v_h.holder<holder_type>())) holder_type(std::move(*const_cast<holder_type *>(holder_ptr))); 1321 } 1322 1323 /// Initialize holder object, variant 2: try to construct from existing holder object, if possible 1324 static void init_holder(detail::instance *inst, detail::value_and_holder &v_h, 1325 const holder_type *holder_ptr, const void * /* dummy -- not enable_shared_from_this<T>) */) { 1326 if (holder_ptr) { 1327 init_holder_from_existing(v_h, holder_ptr, std::is_copy_constructible<holder_type>()); 1328 v_h.set_holder_constructed(); 1329 } else if (inst->owned || detail::always_construct_holder<holder_type>::value) { 1330 new (std::addressof(v_h.holder<holder_type>())) holder_type(v_h.value_ptr<type>()); 1331 v_h.set_holder_constructed(); 1332 } 1333 } 1334 1335 /// Performs instance initialization including constructing a holder and registering the known 1336 /// instance. Should be called as soon as the `type` value_ptr is set for an instance. Takes an 1337 /// optional pointer to an existing holder to use; if not specified and the instance is 1338 /// `.owned`, a new holder will be constructed to manage the value pointer. 1339 static void init_instance(detail::instance *inst, const void *holder_ptr) { 1340 auto v_h = inst->get_value_and_holder(detail::get_type_info(typeid(type))); 1341 if (!v_h.instance_registered()) { 1342 register_instance(inst, v_h.value_ptr(), v_h.type); 1343 v_h.set_instance_registered(); 1344 } 1345 init_holder(inst, v_h, (const holder_type *) holder_ptr, v_h.value_ptr<type>()); 1346 } 1347 1348 /// Deallocates an instance; via holder, if constructed; otherwise via operator delete. 1349 static void dealloc(detail::value_and_holder &v_h) { 1350 if (v_h.holder_constructed()) { 1351 v_h.holder<holder_type>().~holder_type(); 1352 v_h.set_holder_constructed(false); 1353 } 1354 else { 1355 detail::call_operator_delete(v_h.value_ptr<type>(), 1356 v_h.type->type_size, 1357 v_h.type->type_align 1358 ); 1359 } 1360 v_h.value_ptr() = nullptr; 1361 } 1362 1363 static detail::function_record *get_function_record(handle h) { 1364 h = detail::get_function(h); 1365 return h ? (detail::function_record *) reinterpret_borrow<capsule>(PyCFunction_GET_SELF(h.ptr())) 1366 : nullptr; 1367 } 1368}; 1369 1370/// Binds an existing constructor taking arguments Args... 1371template <typename... Args> detail::initimpl::constructor<Args...> init() { return {}; } 1372/// Like `init<Args...>()`, but the instance is always constructed through the alias class (even 1373/// when not inheriting on the Python side). 1374template <typename... Args> detail::initimpl::alias_constructor<Args...> init_alias() { return {}; } 1375 1376/// Binds a factory function as a constructor 1377template <typename Func, typename Ret = detail::initimpl::factory<Func>> 1378Ret init(Func &&f) { return {std::forward<Func>(f)}; } 1379 1380/// Dual-argument factory function: the first function is called when no alias is needed, the second 1381/// when an alias is needed (i.e. due to python-side inheritance). Arguments must be identical. 1382template <typename CFunc, typename AFunc, typename Ret = detail::initimpl::factory<CFunc, AFunc>> 1383Ret init(CFunc &&c, AFunc &&a) { 1384 return {std::forward<CFunc>(c), std::forward<AFunc>(a)}; 1385} 1386 1387/// Binds pickling functions `__getstate__` and `__setstate__` and ensures that the type 1388/// returned by `__getstate__` is the same as the argument accepted by `__setstate__`. 1389template <typename GetState, typename SetState> 1390detail::initimpl::pickle_factory<GetState, SetState> pickle(GetState &&g, SetState &&s) { 1391 return {std::forward<GetState>(g), std::forward<SetState>(s)}; 1392} 1393 1394NAMESPACE_BEGIN(detail) 1395struct enum_base { 1396 enum_base(handle base, handle parent) : m_base(base), m_parent(parent) { } 1397 1398 PYBIND11_NOINLINE void init(bool is_arithmetic, bool is_convertible) { 1399 m_base.attr("__entries") = dict(); 1400 auto property = handle((PyObject *) &PyProperty_Type); 1401 auto static_property = handle((PyObject *) get_internals().static_property_type); 1402 1403 m_base.attr("__repr__") = cpp_function( 1404 [](handle arg) -> str { 1405 handle type = arg.get_type(); 1406 object type_name = type.attr("__name__"); 1407 dict entries = type.attr("__entries"); 1408 for (const auto &kv : entries) { 1409 object other = kv.second[int_(0)]; 1410 if (other.equal(arg)) 1411 return pybind11::str("{}.{}").format(type_name, kv.first); 1412 } 1413 return pybind11::str("{}.???").format(type_name); 1414 }, is_method(m_base) 1415 ); 1416 1417 m_base.attr("name") = property(cpp_function( 1418 [](handle arg) -> str { 1419 dict entries = arg.get_type().attr("__entries"); 1420 for (const auto &kv : entries) { 1421 if (handle(kv.second[int_(0)]).equal(arg)) 1422 return pybind11::str(kv.first); 1423 } 1424 return "???"; 1425 }, is_method(m_base) 1426 )); 1427 1428 m_base.attr("__doc__") = static_property(cpp_function( 1429 [](handle arg) -> std::string { 1430 std::string docstring; 1431 dict entries = arg.attr("__entries"); 1432 if (((PyTypeObject *) arg.ptr())->tp_doc) 1433 docstring += std::string(((PyTypeObject *) arg.ptr())->tp_doc) + "\n\n"; 1434 docstring += "Members:"; 1435 for (const auto &kv : entries) { 1436 auto key = std::string(pybind11::str(kv.first)); 1437 auto comment = kv.second[int_(1)]; 1438 docstring += "\n\n " + key; 1439 if (!comment.is_none()) 1440 docstring += " : " + (std::string) pybind11::str(comment); 1441 } 1442 return docstring; 1443 } 1444 ), none(), none(), ""); 1445 1446 m_base.attr("__members__") = static_property(cpp_function( 1447 [](handle arg) -> dict { 1448 dict entries = arg.attr("__entries"), m; 1449 for (const auto &kv : entries) 1450 m[kv.first] = kv.second[int_(0)]; 1451 return m; 1452 }), none(), none(), "" 1453 ); 1454 1455 #define PYBIND11_ENUM_OP_STRICT(op, expr, strict_behavior) \ 1456 m_base.attr(op) = cpp_function( \ 1457 [](object a, object b) { \ 1458 if (!a.get_type().is(b.get_type())) \ 1459 strict_behavior; \ 1460 return expr; \ 1461 }, \ 1462 is_method(m_base)) 1463 1464 #define PYBIND11_ENUM_OP_CONV(op, expr) \ 1465 m_base.attr(op) = cpp_function( \ 1466 [](object a_, object b_) { \ 1467 int_ a(a_), b(b_); \ 1468 return expr; \ 1469 }, \ 1470 is_method(m_base)) 1471 1472 #define PYBIND11_ENUM_OP_CONV_LHS(op, expr) \ 1473 m_base.attr(op) = cpp_function( \ 1474 [](object a_, object b) { \ 1475 int_ a(a_); \ 1476 return expr; \ 1477 }, \ 1478 is_method(m_base)) 1479 1480 if (is_convertible) { 1481 PYBIND11_ENUM_OP_CONV_LHS("__eq__", !b.is_none() && a.equal(b)); 1482 PYBIND11_ENUM_OP_CONV_LHS("__ne__", b.is_none() || !a.equal(b)); 1483 1484 if (is_arithmetic) { 1485 PYBIND11_ENUM_OP_CONV("__lt__", a < b); 1486 PYBIND11_ENUM_OP_CONV("__gt__", a > b); 1487 PYBIND11_ENUM_OP_CONV("__le__", a <= b); 1488 PYBIND11_ENUM_OP_CONV("__ge__", a >= b); 1489 PYBIND11_ENUM_OP_CONV("__and__", a & b); 1490 PYBIND11_ENUM_OP_CONV("__rand__", a & b); 1491 PYBIND11_ENUM_OP_CONV("__or__", a | b); 1492 PYBIND11_ENUM_OP_CONV("__ror__", a | b); 1493 PYBIND11_ENUM_OP_CONV("__xor__", a ^ b); 1494 PYBIND11_ENUM_OP_CONV("__rxor__", a ^ b); 1495 m_base.attr("__invert__") = cpp_function( 1496 [](object arg) { return ~(int_(arg)); }, is_method(m_base)); 1497 } 1498 } else { 1499 PYBIND11_ENUM_OP_STRICT("__eq__", int_(a).equal(int_(b)), return false); 1500 PYBIND11_ENUM_OP_STRICT("__ne__", !int_(a).equal(int_(b)), return true); 1501 1502 if (is_arithmetic) { 1503 #define PYBIND11_THROW throw type_error("Expected an enumeration of matching type!"); 1504 PYBIND11_ENUM_OP_STRICT("__lt__", int_(a) < int_(b), PYBIND11_THROW); 1505 PYBIND11_ENUM_OP_STRICT("__gt__", int_(a) > int_(b), PYBIND11_THROW); 1506 PYBIND11_ENUM_OP_STRICT("__le__", int_(a) <= int_(b), PYBIND11_THROW); 1507 PYBIND11_ENUM_OP_STRICT("__ge__", int_(a) >= int_(b), PYBIND11_THROW); 1508 #undef PYBIND11_THROW 1509 } 1510 } 1511 1512 #undef PYBIND11_ENUM_OP_CONV_LHS 1513 #undef PYBIND11_ENUM_OP_CONV 1514 #undef PYBIND11_ENUM_OP_STRICT 1515 1516 object getstate = cpp_function( 1517 [](object arg) { return int_(arg); }, is_method(m_base)); 1518 1519 m_base.attr("__getstate__") = getstate; 1520 m_base.attr("__hash__") = getstate; 1521 } 1522 1523 PYBIND11_NOINLINE void value(char const* name_, object value, const char *doc = nullptr) { 1524 dict entries = m_base.attr("__entries"); 1525 str name(name_); 1526 if (entries.contains(name)) { 1527 std::string type_name = (std::string) str(m_base.attr("__name__")); 1528 throw value_error(type_name + ": element \"" + std::string(name_) + "\" already exists!"); 1529 } 1530 1531 entries[name] = std::make_pair(value, doc); 1532 m_base.attr(name) = value; 1533 } 1534 1535 PYBIND11_NOINLINE void export_values() { 1536 dict entries = m_base.attr("__entries"); 1537 for (const auto &kv : entries) 1538 m_parent.attr(kv.first) = kv.second[int_(0)]; 1539 } 1540 1541 handle m_base; 1542 handle m_parent; 1543}; 1544 1545NAMESPACE_END(detail) 1546 1547/// Binds C++ enumerations and enumeration classes to Python 1548template <typename Type> class enum_ : public class_<Type> { 1549public: 1550 using Base = class_<Type>; 1551 using Base::def; 1552 using Base::attr; 1553 using Base::def_property_readonly; 1554 using Base::def_property_readonly_static; 1555 using Scalar = typename std::underlying_type<Type>::type; 1556 1557 template <typename... Extra> 1558 enum_(const handle &scope, const char *name, const Extra&... extra) 1559 : class_<Type>(scope, name, extra...), m_base(*this, scope) { 1560 constexpr bool is_arithmetic = detail::any_of<std::is_same<arithmetic, Extra>...>::value; 1561 constexpr bool is_convertible = std::is_convertible<Type, Scalar>::value; 1562 m_base.init(is_arithmetic, is_convertible); 1563 1564 def(init([](Scalar i) { return static_cast<Type>(i); })); 1565 def("__int__", [](Type value) { return (Scalar) value; }); 1566 #if PY_MAJOR_VERSION < 3 1567 def("__long__", [](Type value) { return (Scalar) value; }); 1568 #endif 1569 #if PY_MAJOR_VERSION >= 3 && PY_MINOR_VERSION >= 8 1570 def("__index__", [](Type value) { return (Scalar) value; }); 1571 #endif 1572 1573 cpp_function setstate( 1574 [](Type &value, Scalar arg) { value = static_cast<Type>(arg); }, 1575 is_method(*this)); 1576 attr("__setstate__") = setstate; 1577 } 1578 1579 /// Export enumeration entries into the parent scope 1580 enum_& export_values() { 1581 m_base.export_values(); 1582 return *this; 1583 } 1584 1585 /// Add an enumeration entry 1586 enum_& value(char const* name, Type value, const char *doc = nullptr) { 1587 m_base.value(name, pybind11::cast(value, return_value_policy::copy), doc); 1588 return *this; 1589 } 1590 1591private: 1592 detail::enum_base m_base; 1593}; 1594 1595NAMESPACE_BEGIN(detail) 1596 1597 1598inline void keep_alive_impl(handle nurse, handle patient) { 1599 if (!nurse || !patient) 1600 pybind11_fail("Could not activate keep_alive!"); 1601 1602 if (patient.is_none() || nurse.is_none()) 1603 return; /* Nothing to keep alive or nothing to be kept alive by */ 1604 1605 auto tinfo = all_type_info(Py_TYPE(nurse.ptr())); 1606 if (!tinfo.empty()) { 1607 /* It's a pybind-registered type, so we can store the patient in the 1608 * internal list. */ 1609 add_patient(nurse.ptr(), patient.ptr()); 1610 } 1611 else { 1612 /* Fall back to clever approach based on weak references taken from 1613 * Boost.Python. This is not used for pybind-registered types because 1614 * the objects can be destroyed out-of-order in a GC pass. */ 1615 cpp_function disable_lifesupport( 1616 [patient](handle weakref) { patient.dec_ref(); weakref.dec_ref(); }); 1617 1618 weakref wr(nurse, disable_lifesupport); 1619 1620 patient.inc_ref(); /* reference patient and leak the weak reference */ 1621 (void) wr.release(); 1622 } 1623} 1624 1625PYBIND11_NOINLINE inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret) { 1626 auto get_arg = [&](size_t n) { 1627 if (n == 0) 1628 return ret; 1629 else if (n == 1 && call.init_self) 1630 return call.init_self; 1631 else if (n <= call.args.size()) 1632 return call.args[n - 1]; 1633 return handle(); 1634 }; 1635 1636 keep_alive_impl(get_arg(Nurse), get_arg(Patient)); 1637} 1638 1639inline std::pair<decltype(internals::registered_types_py)::iterator, bool> all_type_info_get_cache(PyTypeObject *type) { 1640 auto res = get_internals().registered_types_py 1641#ifdef __cpp_lib_unordered_map_try_emplace 1642 .try_emplace(type); 1643#else 1644 .emplace(type, std::vector<detail::type_info *>()); 1645#endif 1646 if (res.second) { 1647 // New cache entry created; set up a weak reference to automatically remove it if the type 1648 // gets destroyed: 1649 weakref((PyObject *) type, cpp_function([type](handle wr) { 1650 get_internals().registered_types_py.erase(type); 1651 wr.dec_ref(); 1652 })).release(); 1653 } 1654 1655 return res; 1656} 1657 1658template <typename Iterator, typename Sentinel, bool KeyIterator, return_value_policy Policy> 1659struct iterator_state { 1660 Iterator it; 1661 Sentinel end; 1662 bool first_or_done; 1663}; 1664 1665NAMESPACE_END(detail) 1666 1667/// Makes a python iterator from a first and past-the-end C++ InputIterator. 1668template <return_value_policy Policy = return_value_policy::reference_internal, 1669 typename Iterator, 1670 typename Sentinel, 1671 typename ValueType = decltype(*std::declval<Iterator>()), 1672 typename... Extra> 1673iterator make_iterator(Iterator first, Sentinel last, Extra &&... extra) { 1674 typedef detail::iterator_state<Iterator, Sentinel, false, Policy> state; 1675 1676 if (!detail::get_type_info(typeid(state), false)) { 1677 class_<state>(handle(), "iterator", pybind11::module_local()) 1678 .def("__iter__", [](state &s) -> state& { return s; }) 1679 .def("__next__", [](state &s) -> ValueType { 1680 if (!s.first_or_done) 1681 ++s.it; 1682 else 1683 s.first_or_done = false; 1684 if (s.it == s.end) { 1685 s.first_or_done = true; 1686 throw stop_iteration(); 1687 } 1688 return *s.it; 1689 }, std::forward<Extra>(extra)..., Policy); 1690 } 1691 1692 return cast(state{first, last, true}); 1693} 1694 1695/// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a 1696/// first and past-the-end InputIterator. 1697template <return_value_policy Policy = return_value_policy::reference_internal, 1698 typename Iterator, 1699 typename Sentinel, 1700 typename KeyType = decltype((*std::declval<Iterator>()).first), 1701 typename... Extra> 1702iterator make_key_iterator(Iterator first, Sentinel last, Extra &&... extra) { 1703 typedef detail::iterator_state<Iterator, Sentinel, true, Policy> state; 1704 1705 if (!detail::get_type_info(typeid(state), false)) { 1706 class_<state>(handle(), "iterator", pybind11::module_local()) 1707 .def("__iter__", [](state &s) -> state& { return s; }) 1708 .def("__next__", [](state &s) -> KeyType { 1709 if (!s.first_or_done) 1710 ++s.it; 1711 else 1712 s.first_or_done = false; 1713 if (s.it == s.end) { 1714 s.first_or_done = true; 1715 throw stop_iteration(); 1716 } 1717 return (*s.it).first; 1718 }, std::forward<Extra>(extra)..., Policy); 1719 } 1720 1721 return cast(state{first, last, true}); 1722} 1723 1724/// Makes an iterator over values of an stl container or other container supporting 1725/// `std::begin()`/`std::end()` 1726template <return_value_policy Policy = return_value_policy::reference_internal, 1727 typename Type, typename... Extra> iterator make_iterator(Type &value, Extra&&... extra) { 1728 return make_iterator<Policy>(std::begin(value), std::end(value), extra...); 1729} 1730 1731/// Makes an iterator over the keys (`.first`) of a stl map-like container supporting 1732/// `std::begin()`/`std::end()` 1733template <return_value_policy Policy = return_value_policy::reference_internal, 1734 typename Type, typename... Extra> iterator make_key_iterator(Type &value, Extra&&... extra) { 1735 return make_key_iterator<Policy>(std::begin(value), std::end(value), extra...); 1736} 1737 1738template <typename InputType, typename OutputType> void implicitly_convertible() { 1739 struct set_flag { 1740 bool &flag; 1741 set_flag(bool &flag) : flag(flag) { flag = true; } 1742 ~set_flag() { flag = false; } 1743 }; 1744 auto implicit_caster = [](PyObject *obj, PyTypeObject *type) -> PyObject * { 1745 static bool currently_used = false; 1746 if (currently_used) // implicit conversions are non-reentrant 1747 return nullptr; 1748 set_flag flag_helper(currently_used); 1749 if (!detail::make_caster<InputType>().load(obj, false)) 1750 return nullptr; 1751 tuple args(1); 1752 args[0] = obj; 1753 PyObject *result = PyObject_Call((PyObject *) type, args.ptr(), nullptr); 1754 if (result == nullptr) 1755 PyErr_Clear(); 1756 return result; 1757 }; 1758 1759 if (auto tinfo = detail::get_type_info(typeid(OutputType))) 1760 tinfo->implicit_conversions.push_back(implicit_caster); 1761 else 1762 pybind11_fail("implicitly_convertible: Unable to find type " + type_id<OutputType>()); 1763} 1764 1765template <typename ExceptionTranslator> 1766void register_exception_translator(ExceptionTranslator&& translator) { 1767 detail::get_internals().registered_exception_translators.push_front( 1768 std::forward<ExceptionTranslator>(translator)); 1769} 1770 1771/** 1772 * Wrapper to generate a new Python exception type. 1773 * 1774 * This should only be used with PyErr_SetString for now. 1775 * It is not (yet) possible to use as a py::base. 1776 * Template type argument is reserved for future use. 1777 */ 1778template <typename type> 1779class exception : public object { 1780public: 1781 exception() = default; 1782 exception(handle scope, const char *name, PyObject *base = PyExc_Exception) { 1783 std::string full_name = scope.attr("__name__").cast<std::string>() + 1784 std::string(".") + name; 1785 m_ptr = PyErr_NewException(const_cast<char *>(full_name.c_str()), base, NULL); 1786 if (hasattr(scope, name)) 1787 pybind11_fail("Error during initialization: multiple incompatible " 1788 "definitions with name \"" + std::string(name) + "\""); 1789 scope.attr(name) = *this; 1790 } 1791 1792 // Sets the current python exception to this exception object with the given message 1793 void operator()(const char *message) { 1794 PyErr_SetString(m_ptr, message); 1795 } 1796}; 1797 1798NAMESPACE_BEGIN(detail) 1799// Returns a reference to a function-local static exception object used in the simple 1800// register_exception approach below. (It would be simpler to have the static local variable 1801// directly in register_exception, but that makes clang <3.5 segfault - issue #1349). 1802template <typename CppException> 1803exception<CppException> &get_exception_object() { static exception<CppException> ex; return ex; } 1804NAMESPACE_END(detail) 1805 1806/** 1807 * Registers a Python exception in `m` of the given `name` and installs an exception translator to 1808 * translate the C++ exception to the created Python exception using the exceptions what() method. 1809 * This is intended for simple exception translations; for more complex translation, register the 1810 * exception object and translator directly. 1811 */ 1812template <typename CppException> 1813exception<CppException> ®ister_exception(handle scope, 1814 const char *name, 1815 PyObject *base = PyExc_Exception) { 1816 auto &ex = detail::get_exception_object<CppException>(); 1817 if (!ex) ex = exception<CppException>(scope, name, base); 1818 1819 register_exception_translator([](std::exception_ptr p) { 1820 if (!p) return; 1821 try { 1822 std::rethrow_exception(p); 1823 } catch (const CppException &e) { 1824 detail::get_exception_object<CppException>()(e.what()); 1825 } 1826 }); 1827 return ex; 1828} 1829 1830NAMESPACE_BEGIN(detail) 1831PYBIND11_NOINLINE inline void print(tuple args, dict kwargs) { 1832 auto strings = tuple(args.size()); 1833 for (size_t i = 0; i < args.size(); ++i) { 1834 strings[i] = str(args[i]); 1835 } 1836 auto sep = kwargs.contains("sep") ? kwargs["sep"] : cast(" "); 1837 auto line = sep.attr("join")(strings); 1838 1839 object file; 1840 if (kwargs.contains("file")) { 1841 file = kwargs["file"].cast<object>(); 1842 } else { 1843 try { 1844 file = module::import("sys").attr("stdout"); 1845 } catch (const error_already_set &) { 1846 /* If print() is called from code that is executed as 1847 part of garbage collection during interpreter shutdown, 1848 importing 'sys' can fail. Give up rather than crashing the 1849 interpreter in this case. */ 1850 return; 1851 } 1852 } 1853 1854 auto write = file.attr("write"); 1855 write(line); 1856 write(kwargs.contains("end") ? kwargs["end"] : cast("\n")); 1857 1858 if (kwargs.contains("flush") && kwargs["flush"].cast<bool>()) 1859 file.attr("flush")(); 1860} 1861NAMESPACE_END(detail) 1862 1863template <return_value_policy policy = return_value_policy::automatic_reference, typename... Args> 1864void print(Args &&...args) { 1865 auto c = detail::collect_arguments<policy>(std::forward<Args>(args)...); 1866 detail::print(c.args(), c.kwargs()); 1867} 1868 1869#if defined(WITH_THREAD) && !defined(PYPY_VERSION) 1870 1871/* The functions below essentially reproduce the PyGILState_* API using a RAII 1872 * pattern, but there are a few important differences: 1873 * 1874 * 1. When acquiring the GIL from an non-main thread during the finalization 1875 * phase, the GILState API blindly terminates the calling thread, which 1876 * is often not what is wanted. This API does not do this. 1877 * 1878 * 2. The gil_scoped_release function can optionally cut the relationship 1879 * of a PyThreadState and its associated thread, which allows moving it to 1880 * another thread (this is a fairly rare/advanced use case). 1881 * 1882 * 3. The reference count of an acquired thread state can be controlled. This 1883 * can be handy to prevent cases where callbacks issued from an external 1884 * thread would otherwise constantly construct and destroy thread state data 1885 * structures. 1886 * 1887 * See the Python bindings of NanoGUI (http://github.com/wjakob/nanogui) for an 1888 * example which uses features 2 and 3 to migrate the Python thread of 1889 * execution to another thread (to run the event loop on the original thread, 1890 * in this case). 1891 */ 1892 1893class gil_scoped_acquire { 1894public: 1895 PYBIND11_NOINLINE gil_scoped_acquire() { 1896 auto const &internals = detail::get_internals(); 1897 tstate = (PyThreadState *) PYBIND11_TLS_GET_VALUE(internals.tstate); 1898 1899 if (!tstate) { 1900 /* Check if the GIL was acquired using the PyGILState_* API instead (e.g. if 1901 calling from a Python thread). Since we use a different key, this ensures 1902 we don't create a new thread state and deadlock in PyEval_AcquireThread 1903 below. Note we don't save this state with internals.tstate, since we don't 1904 create it we would fail to clear it (its reference count should be > 0). */ 1905 tstate = PyGILState_GetThisThreadState(); 1906 } 1907 1908 if (!tstate) { 1909 tstate = PyThreadState_New(internals.istate); 1910 #if !defined(NDEBUG) 1911 if (!tstate) 1912 pybind11_fail("scoped_acquire: could not create thread state!"); 1913 #endif 1914 tstate->gilstate_counter = 0; 1915 PYBIND11_TLS_REPLACE_VALUE(internals.tstate, tstate); 1916 } else { 1917 release = detail::get_thread_state_unchecked() != tstate; 1918 } 1919 1920 if (release) { 1921 /* Work around an annoying assertion in PyThreadState_Swap */ 1922 #if defined(Py_DEBUG) 1923 PyInterpreterState *interp = tstate->interp; 1924 tstate->interp = nullptr; 1925 #endif 1926 PyEval_AcquireThread(tstate); 1927 #if defined(Py_DEBUG) 1928 tstate->interp = interp; 1929 #endif 1930 } 1931 1932 inc_ref(); 1933 } 1934 1935 void inc_ref() { 1936 ++tstate->gilstate_counter; 1937 } 1938 1939 PYBIND11_NOINLINE void dec_ref() { 1940 --tstate->gilstate_counter; 1941 #if !defined(NDEBUG) 1942 if (detail::get_thread_state_unchecked() != tstate) 1943 pybind11_fail("scoped_acquire::dec_ref(): thread state must be current!"); 1944 if (tstate->gilstate_counter < 0) 1945 pybind11_fail("scoped_acquire::dec_ref(): reference count underflow!"); 1946 #endif 1947 if (tstate->gilstate_counter == 0) { 1948 #if !defined(NDEBUG) 1949 if (!release) 1950 pybind11_fail("scoped_acquire::dec_ref(): internal error!"); 1951 #endif 1952 PyThreadState_Clear(tstate); 1953 PyThreadState_DeleteCurrent(); 1954 PYBIND11_TLS_DELETE_VALUE(detail::get_internals().tstate); 1955 release = false; 1956 } 1957 } 1958 1959 PYBIND11_NOINLINE ~gil_scoped_acquire() { 1960 dec_ref(); 1961 if (release) 1962 PyEval_SaveThread(); 1963 } 1964private: 1965 PyThreadState *tstate = nullptr; 1966 bool release = true; 1967}; 1968 1969class gil_scoped_release { 1970public: 1971 explicit gil_scoped_release(bool disassoc = false) : disassoc(disassoc) { 1972 // `get_internals()` must be called here unconditionally in order to initialize 1973 // `internals.tstate` for subsequent `gil_scoped_acquire` calls. Otherwise, an 1974 // initialization race could occur as multiple threads try `gil_scoped_acquire`. 1975 const auto &internals = detail::get_internals(); 1976 tstate = PyEval_SaveThread(); 1977 if (disassoc) { 1978 auto key = internals.tstate; 1979 PYBIND11_TLS_DELETE_VALUE(key); 1980 } 1981 } 1982 ~gil_scoped_release() { 1983 if (!tstate) 1984 return; 1985 PyEval_RestoreThread(tstate); 1986 if (disassoc) { 1987 auto key = detail::get_internals().tstate; 1988 PYBIND11_TLS_REPLACE_VALUE(key, tstate); 1989 } 1990 } 1991private: 1992 PyThreadState *tstate; 1993 bool disassoc; 1994}; 1995#elif defined(PYPY_VERSION) 1996class gil_scoped_acquire { 1997 PyGILState_STATE state; 1998public: 1999 gil_scoped_acquire() { state = PyGILState_Ensure(); } 2000 ~gil_scoped_acquire() { PyGILState_Release(state); } 2001}; 2002 2003class gil_scoped_release { 2004 PyThreadState *state; 2005public: 2006 gil_scoped_release() { state = PyEval_SaveThread(); } 2007 ~gil_scoped_release() { PyEval_RestoreThread(state); } 2008}; 2009#else 2010class gil_scoped_acquire { }; 2011class gil_scoped_release { }; 2012#endif 2013 2014error_already_set::~error_already_set() { 2015 if (m_type) { 2016 gil_scoped_acquire gil; 2017 error_scope scope; 2018 m_type.release().dec_ref(); 2019 m_value.release().dec_ref(); 2020 m_trace.release().dec_ref(); 2021 } 2022} 2023 2024inline function get_type_overload(const void *this_ptr, const detail::type_info *this_type, const char *name) { 2025 handle self = detail::get_object_handle(this_ptr, this_type); 2026 if (!self) 2027 return function(); 2028 handle type = self.get_type(); 2029 auto key = std::make_pair(type.ptr(), name); 2030 2031 /* Cache functions that aren't overloaded in Python to avoid 2032 many costly Python dictionary lookups below */ 2033 auto &cache = detail::get_internals().inactive_overload_cache; 2034 if (cache.find(key) != cache.end()) 2035 return function(); 2036 2037 function overload = getattr(self, name, function()); 2038 if (overload.is_cpp_function()) { 2039 cache.insert(key); 2040 return function(); 2041 } 2042 2043 /* Don't call dispatch code if invoked from overridden function. 2044 Unfortunately this doesn't work on PyPy. */ 2045#if !defined(PYPY_VERSION) 2046 PyFrameObject *frame = PyThreadState_Get()->frame; 2047 if (frame && (std::string) str(frame->f_code->co_name) == name && 2048 frame->f_code->co_argcount > 0) { 2049 PyFrame_FastToLocals(frame); 2050 PyObject *self_caller = PyDict_GetItem( 2051 frame->f_locals, PyTuple_GET_ITEM(frame->f_code->co_varnames, 0)); 2052 if (self_caller == self.ptr()) 2053 return function(); 2054 } 2055#else 2056 /* PyPy currently doesn't provide a detailed cpyext emulation of 2057 frame objects, so we have to emulate this using Python. This 2058 is going to be slow..*/ 2059 dict d; d["self"] = self; d["name"] = pybind11::str(name); 2060 PyObject *result = PyRun_String( 2061 "import inspect\n" 2062 "frame = inspect.currentframe()\n" 2063 "if frame is not None:\n" 2064 " frame = frame.f_back\n" 2065 " if frame is not None and str(frame.f_code.co_name) == name and " 2066 "frame.f_code.co_argcount > 0:\n" 2067 " self_caller = frame.f_locals[frame.f_code.co_varnames[0]]\n" 2068 " if self_caller == self:\n" 2069 " self = None\n", 2070 Py_file_input, d.ptr(), d.ptr()); 2071 if (result == nullptr) 2072 throw error_already_set(); 2073 if (d["self"].is_none()) 2074 return function(); 2075 Py_DECREF(result); 2076#endif 2077 2078 return overload; 2079} 2080 2081/** \rst 2082 Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr. 2083 2084 :this_ptr: The pointer to the object the overload should be retrieved for. This should be the first 2085 non-trampoline class encountered in the inheritance chain. 2086 :name: The name of the overloaded Python method to retrieve. 2087 :return: The Python method by this name from the object or an empty function wrapper. 2088 \endrst */ 2089template <class T> function get_overload(const T *this_ptr, const char *name) { 2090 auto tinfo = detail::get_type_info(typeid(T)); 2091 return tinfo ? get_type_overload(this_ptr, tinfo, name) : function(); 2092} 2093 2094#define PYBIND11_OVERLOAD_INT(ret_type, cname, name, ...) { \ 2095 pybind11::gil_scoped_acquire gil; \ 2096 pybind11::function overload = pybind11::get_overload(static_cast<const cname *>(this), name); \ 2097 if (overload) { \ 2098 auto o = overload(__VA_ARGS__); \ 2099 if (pybind11::detail::cast_is_temporary_value_reference<ret_type>::value) { \ 2100 static pybind11::detail::overload_caster_t<ret_type> caster; \ 2101 return pybind11::detail::cast_ref<ret_type>(std::move(o), caster); \ 2102 } \ 2103 else return pybind11::detail::cast_safe<ret_type>(std::move(o)); \ 2104 } \ 2105 } 2106 2107/** \rst 2108 Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named 'fn' 2109 from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return 2110 the appropriate type. See :ref:`overriding_virtuals` for more information. This macro should be used when the method 2111 name in C is not the same as the method name in Python. For example with `__str__`. 2112 2113 .. code-block:: cpp 2114 2115 std::string toString() override { 2116 PYBIND11_OVERLOAD_NAME( 2117 std::string, // Return type (ret_type) 2118 Animal, // Parent class (cname) 2119 toString, // Name of function in C++ (name) 2120 "__str__", // Name of method in Python (fn) 2121 ); 2122 } 2123\endrst */ 2124#define PYBIND11_OVERLOAD_NAME(ret_type, cname, name, fn, ...) \ 2125 PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \ 2126 return cname::fn(__VA_ARGS__) 2127 2128/** \rst 2129 Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD_NAME`, except that it 2130 throws if no overload can be found. 2131\endrst */ 2132#define PYBIND11_OVERLOAD_PURE_NAME(ret_type, cname, name, fn, ...) \ 2133 PYBIND11_OVERLOAD_INT(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), name, __VA_ARGS__) \ 2134 pybind11::pybind11_fail("Tried to call pure virtual function \"" PYBIND11_STRINGIFY(cname) "::" name "\""); 2135 2136/** \rst 2137 Macro to populate the virtual method in the trampoline class. This macro tries to look up the method 2138 from the Python side, deals with the :ref:`gil` and necessary argument conversions to call this method and return 2139 the appropriate type. This macro should be used if the method name in C and in Python are identical. 2140 See :ref:`overriding_virtuals` for more information. 2141 2142 .. code-block:: cpp 2143 2144 class PyAnimal : public Animal { 2145 public: 2146 // Inherit the constructors 2147 using Animal::Animal; 2148 2149 // Trampoline (need one for each virtual function) 2150 std::string go(int n_times) override { 2151 PYBIND11_OVERLOAD_PURE( 2152 std::string, // Return type (ret_type) 2153 Animal, // Parent class (cname) 2154 go, // Name of function in C++ (must match Python name) (fn) 2155 n_times // Argument(s) (...) 2156 ); 2157 } 2158 }; 2159\endrst */ 2160#define PYBIND11_OVERLOAD(ret_type, cname, fn, ...) \ 2161 PYBIND11_OVERLOAD_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__) 2162 2163/** \rst 2164 Macro for pure virtual functions, this function is identical to :c:macro:`PYBIND11_OVERLOAD`, except that it throws 2165 if no overload can be found. 2166\endrst */ 2167#define PYBIND11_OVERLOAD_PURE(ret_type, cname, fn, ...) \ 2168 PYBIND11_OVERLOAD_PURE_NAME(PYBIND11_TYPE(ret_type), PYBIND11_TYPE(cname), #fn, fn, __VA_ARGS__) 2169 2170NAMESPACE_END(PYBIND11_NAMESPACE) 2171 2172#if defined(_MSC_VER) && !defined(__INTEL_COMPILER) 2173# pragma warning(pop) 2174#elif defined(__GNUG__) && !defined(__clang__) 2175# pragma GCC diagnostic pop 2176#endif 2177