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