File indexing completed on 2026-07-27 09:46:18
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011 #pragma once
0012
0013 #include "detail/common.h"
0014 #include "cast.h"
0015 #include "trampoline_self_life_support.h"
0016
0017 #include <functional>
0018
0019 PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
0020
0021
0022
0023
0024
0025 struct is_method {
0026 handle class_;
0027 explicit is_method(const handle &c) : class_(c) {}
0028 };
0029
0030
0031 struct is_setter {};
0032
0033
0034 struct is_operator {};
0035
0036
0037 struct is_final {};
0038
0039
0040 struct scope {
0041 handle value;
0042 explicit scope(const handle &s) : value(s) {}
0043 };
0044
0045
0046 struct doc {
0047 const char *value;
0048 explicit doc(const char *value) : value(value) {}
0049 };
0050
0051
0052 struct name {
0053 const char *value;
0054 explicit name(const char *value) : value(value) {}
0055 };
0056
0057
0058 struct sibling {
0059 handle value;
0060 explicit sibling(const handle &value) : value(value.ptr()) {}
0061 };
0062
0063
0064 template <typename T>
0065 struct base {
0066
0067 PYBIND11_DEPRECATED(
0068 "base<T>() was deprecated in favor of specifying 'T' as a template argument to class_")
0069 base() = default;
0070 };
0071
0072
0073 template <size_t Nurse, size_t Patient>
0074 struct keep_alive {};
0075
0076
0077 struct multiple_inheritance {};
0078
0079
0080 struct dynamic_attr {};
0081
0082
0083 struct buffer_protocol {};
0084
0085
0086
0087 struct release_gil_before_calling_cpp_dtor {};
0088
0089
0090 struct metaclass {
0091 handle value;
0092
0093 PYBIND11_DEPRECATED("py::metaclass() is no longer required. It's turned on by default now.")
0094 metaclass() = default;
0095
0096
0097 explicit metaclass(handle value) : value(value) {}
0098 };
0099
0100
0101
0102
0103
0104
0105
0106
0107
0108
0109 struct custom_type_setup {
0110 using callback = std::function<void(PyHeapTypeObject *heap_type)>;
0111
0112 explicit custom_type_setup(callback value) : value(std::move(value)) {}
0113
0114 callback value;
0115 };
0116
0117
0118 struct module_local {
0119 const bool value;
0120 constexpr explicit module_local(bool v = true) : value(v) {}
0121 };
0122
0123
0124 struct arithmetic {};
0125
0126
0127 struct prepend {};
0128
0129
0130
0131
0132
0133
0134
0135
0136
0137
0138
0139
0140
0141
0142
0143
0144
0145
0146
0147 template <typename... Ts>
0148 struct call_guard;
0149
0150 template <>
0151 struct call_guard<> {
0152 using type = detail::void_type;
0153 };
0154
0155 template <typename T>
0156 struct call_guard<T> {
0157 static_assert(std::is_default_constructible<T>::value,
0158 "The guard type must be default constructible");
0159
0160 using type = T;
0161 };
0162
0163 template <typename T, typename... Ts>
0164 struct call_guard<T, Ts...> {
0165 struct type {
0166 T guard{};
0167 typename call_guard<Ts...>::type next{};
0168 };
0169 };
0170
0171
0172
0173 PYBIND11_NAMESPACE_BEGIN(detail)
0174
0175 enum op_id : int;
0176 enum op_type : int;
0177 struct undefined_t;
0178 template <op_id id, op_type ot, typename L = undefined_t, typename R = undefined_t>
0179 struct op_;
0180 void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret);
0181
0182
0183 struct argument_record {
0184 const char *name;
0185 const char *descr;
0186 handle value;
0187 bool convert : 1;
0188 bool none : 1;
0189
0190 argument_record(const char *name, const char *descr, handle value, bool convert, bool none)
0191 : name(name), descr(descr), value(value), convert(convert), none(none) {}
0192 };
0193
0194
0195
0196 #define PYBIND11_DETAIL_FUNCTION_RECORD_ABI_ID "v1"
0197 struct function_record {
0198 function_record()
0199 : is_constructor(false), is_new_style_constructor(false), is_stateless(false),
0200 is_operator(false), is_method(false), is_setter(false), has_args(false),
0201 has_kwargs(false), prepend(false) {}
0202
0203
0204 char *name = nullptr;
0205
0206
0207 char *doc = nullptr;
0208
0209
0210 char *signature = nullptr;
0211
0212
0213 std::vector<argument_record> args;
0214
0215
0216 handle (*impl)(function_call &) = nullptr;
0217
0218
0219 void *data[3] = {};
0220
0221
0222 void (*free_data)(function_record *ptr) = nullptr;
0223
0224
0225 return_value_policy policy = return_value_policy::automatic;
0226
0227
0228 bool is_constructor : 1;
0229
0230
0231 bool is_new_style_constructor : 1;
0232
0233
0234 bool is_stateless : 1;
0235
0236
0237 bool is_operator : 1;
0238
0239
0240 bool is_method : 1;
0241
0242
0243 bool is_setter : 1;
0244
0245
0246 bool has_args : 1;
0247
0248
0249 bool has_kwargs : 1;
0250
0251
0252 bool prepend : 1;
0253
0254
0255 std::uint16_t nargs;
0256
0257
0258
0259 std::uint16_t nargs_pos = 0;
0260
0261
0262 std::uint16_t nargs_pos_only = 0;
0263
0264
0265 PyMethodDef *def = nullptr;
0266
0267
0268 handle scope;
0269
0270
0271 handle sibling;
0272
0273
0274 function_record *next = nullptr;
0275 };
0276
0277
0278 #define PYBIND11_ENSURE_PRECONDITION_FOR_FUNCTIONAL_H_PERFORMANCE_OPTIMIZATIONS(...) \
0279 static_assert( \
0280 __VA_ARGS__, \
0281 "Violation of precondition for pybind11/functional.h performance optimizations!")
0282
0283
0284 struct type_record {
0285 PYBIND11_NOINLINE type_record()
0286 : multiple_inheritance(false), dynamic_attr(false), buffer_protocol(false),
0287 module_local(false), is_final(false), release_gil_before_calling_cpp_dtor(false) {}
0288
0289
0290 handle scope;
0291
0292
0293 const char *name = nullptr;
0294
0295
0296 const std::type_info *type = nullptr;
0297
0298
0299 size_t type_size = 0;
0300
0301
0302 size_t type_align = 0;
0303
0304
0305 size_t holder_size = 0;
0306
0307
0308 void *(*operator_new)(size_t) = nullptr;
0309
0310
0311 void (*init_instance)(instance *, const void *) = nullptr;
0312
0313
0314 void (*dealloc)(detail::value_and_holder &) = nullptr;
0315
0316
0317
0318
0319 get_trampoline_self_life_support_fn get_trampoline_self_life_support
0320 = [](void *) -> trampoline_self_life_support * { return nullptr; };
0321
0322
0323 list bases;
0324
0325
0326 const char *doc = nullptr;
0327
0328
0329 handle metaclass;
0330
0331
0332 custom_type_setup::callback custom_type_setup_callback;
0333
0334
0335 bool multiple_inheritance : 1;
0336
0337
0338 bool dynamic_attr : 1;
0339
0340
0341 bool buffer_protocol : 1;
0342
0343
0344 bool module_local : 1;
0345
0346
0347 bool is_final : 1;
0348
0349
0350 bool release_gil_before_calling_cpp_dtor : 1;
0351
0352 holder_enum_t holder_enum_v = holder_enum_t::undefined;
0353
0354 PYBIND11_NOINLINE void add_base(const std::type_info &base, void *(*caster)(void *) ) {
0355 auto *base_info = detail::get_type_info(base, false);
0356 if (!base_info) {
0357 std::string tname(base.name());
0358 detail::clean_type_id(tname);
0359 pybind11_fail("generic_type: type \"" + std::string(name)
0360 + "\" referenced unknown base type \"" + tname + "\"");
0361 }
0362
0363
0364 bool this_has_unique_ptr_holder = (holder_enum_v == holder_enum_t::std_unique_ptr);
0365 bool base_has_unique_ptr_holder
0366 = (base_info->holder_enum_v == holder_enum_t::std_unique_ptr);
0367 if (this_has_unique_ptr_holder != base_has_unique_ptr_holder) {
0368 std::string tname(base.name());
0369 detail::clean_type_id(tname);
0370 pybind11_fail("generic_type: type \"" + std::string(name) + "\" "
0371 + (this_has_unique_ptr_holder ? "does not have" : "has")
0372 + " a non-default holder type while its base \"" + tname + "\" "
0373 + (base_has_unique_ptr_holder ? "does not" : "does"));
0374 }
0375
0376 bases.append(reinterpret_cast<PyObject *>(base_info->type));
0377
0378 #ifdef PYBIND11_BACKWARD_COMPATIBILITY_TP_DICTOFFSET
0379 dynamic_attr |= base_info->type->tp_dictoffset != 0;
0380 #else
0381 dynamic_attr |= (base_info->type->tp_flags & Py_TPFLAGS_MANAGED_DICT) != 0;
0382 #endif
0383
0384 if (caster) {
0385 base_info->implicit_casts.emplace_back(type, caster);
0386 }
0387 }
0388 };
0389
0390 inline function_call::function_call(const function_record &f, handle p) : func(f), parent(p) {
0391 args.reserve(f.nargs);
0392 args_convert.reserve(f.nargs);
0393 }
0394
0395
0396 struct is_new_style_constructor {};
0397
0398
0399
0400
0401
0402
0403
0404 template <typename T, typename SFINAE = void>
0405 struct process_attribute;
0406
0407 template <typename T>
0408 struct process_attribute_default {
0409
0410 static void init(const T &, function_record *) {}
0411 static void init(const T &, type_record *) {}
0412 static void precall(function_call &) {}
0413 static void postcall(function_call &, handle) {}
0414 };
0415
0416
0417 template <>
0418 struct process_attribute<name> : process_attribute_default<name> {
0419 static void init(const name &n, function_record *r) { r->name = const_cast<char *>(n.value); }
0420 };
0421
0422
0423 template <>
0424 struct process_attribute<doc> : process_attribute_default<doc> {
0425 static void init(const doc &n, function_record *r) { r->doc = const_cast<char *>(n.value); }
0426 };
0427
0428
0429 template <>
0430 struct process_attribute<const char *> : process_attribute_default<const char *> {
0431 static void init(const char *d, function_record *r) { r->doc = const_cast<char *>(d); }
0432 static void init(const char *d, type_record *r) { r->doc = d; }
0433 };
0434 template <>
0435 struct process_attribute<char *> : process_attribute<const char *> {};
0436
0437
0438 template <>
0439 struct process_attribute<return_value_policy> : process_attribute_default<return_value_policy> {
0440 static void init(const return_value_policy &p, function_record *r) { r->policy = p; }
0441 };
0442
0443
0444
0445 template <>
0446 struct process_attribute<sibling> : process_attribute_default<sibling> {
0447 static void init(const sibling &s, function_record *r) { r->sibling = s.value; }
0448 };
0449
0450
0451 template <>
0452 struct process_attribute<is_method> : process_attribute_default<is_method> {
0453 static void init(const is_method &s, function_record *r) {
0454 r->is_method = true;
0455 r->scope = s.class_;
0456 }
0457 };
0458
0459
0460 template <>
0461 struct process_attribute<is_setter> : process_attribute_default<is_setter> {
0462 static void init(const is_setter &, function_record *r) { r->is_setter = true; }
0463 };
0464
0465
0466 template <>
0467 struct process_attribute<scope> : process_attribute_default<scope> {
0468 static void init(const scope &s, function_record *r) { r->scope = s.value; }
0469 };
0470
0471
0472 template <>
0473 struct process_attribute<is_operator> : process_attribute_default<is_operator> {
0474 static void init(const is_operator &, function_record *r) { r->is_operator = true; }
0475 };
0476
0477 template <>
0478 struct process_attribute<is_new_style_constructor>
0479 : process_attribute_default<is_new_style_constructor> {
0480 static void init(const is_new_style_constructor &, function_record *r) {
0481 r->is_new_style_constructor = true;
0482 }
0483 };
0484
0485 inline void check_kw_only_arg(const arg &a, function_record *r) {
0486 if (r->args.size() > r->nargs_pos && (!a.name || a.name[0] == '\0')) {
0487 pybind11_fail("arg(): cannot specify an unnamed argument after a kw_only() annotation or "
0488 "args() argument");
0489 }
0490 }
0491
0492 inline void append_self_arg_if_needed(function_record *r) {
0493 if (r->is_method && r->args.empty()) {
0494 r->args.emplace_back("self", nullptr, handle(), true, false);
0495 }
0496 }
0497
0498
0499 template <>
0500 struct process_attribute<arg> : process_attribute_default<arg> {
0501 static void init(const arg &a, function_record *r) {
0502 append_self_arg_if_needed(r);
0503 r->args.emplace_back(a.name, nullptr, handle(), !a.flag_noconvert, a.flag_none);
0504
0505 check_kw_only_arg(a, r);
0506 }
0507 };
0508
0509
0510 template <>
0511 struct process_attribute<arg_v> : process_attribute_default<arg_v> {
0512 static void init(const arg_v &a, function_record *r) {
0513 if (r->is_method && r->args.empty()) {
0514 r->args.emplace_back(
0515 "self", nullptr, handle(), true, false);
0516 }
0517
0518 if (!a.value) {
0519 #if defined(PYBIND11_DETAILED_ERROR_MESSAGES)
0520 std::string descr("'");
0521 if (a.name) {
0522 descr += std::string(a.name) + ": ";
0523 }
0524 descr += a.type + "'";
0525 if (r->is_method) {
0526 if (r->name) {
0527 descr += " in method '" + (std::string) str(r->scope) + "."
0528 + (std::string) r->name + "'";
0529 } else {
0530 descr += " in method of '" + (std::string) str(r->scope) + "'";
0531 }
0532 } else if (r->name) {
0533 descr += " in function '" + (std::string) r->name + "'";
0534 }
0535 pybind11_fail("arg(): could not convert default argument " + descr
0536 + " into a Python object (type not registered yet?)");
0537 #else
0538 pybind11_fail("arg(): could not convert default argument "
0539 "into a Python object (type not registered yet?). "
0540 "#define PYBIND11_DETAILED_ERROR_MESSAGES or compile in debug mode for "
0541 "more information.");
0542 #endif
0543 }
0544 r->args.emplace_back(a.name, a.descr, a.value.inc_ref(), !a.flag_noconvert, a.flag_none);
0545
0546 check_kw_only_arg(a, r);
0547 }
0548 };
0549
0550
0551 template <>
0552 struct process_attribute<kw_only> : process_attribute_default<kw_only> {
0553 static void init(const kw_only &, function_record *r) {
0554 append_self_arg_if_needed(r);
0555 if (r->has_args && r->nargs_pos != static_cast<std::uint16_t>(r->args.size())) {
0556 pybind11_fail("Mismatched args() and kw_only(): they must occur at the same relative "
0557 "argument location (or omit kw_only() entirely)");
0558 }
0559 r->nargs_pos = static_cast<std::uint16_t>(r->args.size());
0560 }
0561 };
0562
0563
0564 template <>
0565 struct process_attribute<pos_only> : process_attribute_default<pos_only> {
0566 static void init(const pos_only &, function_record *r) {
0567 append_self_arg_if_needed(r);
0568 r->nargs_pos_only = static_cast<std::uint16_t>(r->args.size());
0569 if (r->nargs_pos_only > r->nargs_pos) {
0570 pybind11_fail("pos_only(): cannot follow a py::args() argument");
0571 }
0572
0573 }
0574 };
0575
0576
0577
0578 template <typename T>
0579 struct process_attribute<T, enable_if_t<is_pyobject<T>::value>>
0580 : process_attribute_default<handle> {
0581 static void init(const handle &h, type_record *r) { r->bases.append(h); }
0582 };
0583
0584
0585 template <typename T>
0586 struct process_attribute<base<T>> : process_attribute_default<base<T>> {
0587 static void init(const base<T> &, type_record *r) { r->add_base(typeid(T), nullptr); }
0588 };
0589
0590
0591 template <>
0592 struct process_attribute<multiple_inheritance> : process_attribute_default<multiple_inheritance> {
0593 static void init(const multiple_inheritance &, type_record *r) {
0594 r->multiple_inheritance = true;
0595 }
0596 };
0597
0598 template <>
0599 struct process_attribute<dynamic_attr> : process_attribute_default<dynamic_attr> {
0600 static void init(const dynamic_attr &, type_record *r) { r->dynamic_attr = true; }
0601 };
0602
0603 template <>
0604 struct process_attribute<custom_type_setup> {
0605 static void init(const custom_type_setup &value, type_record *r) {
0606 r->custom_type_setup_callback = value.value;
0607 }
0608 };
0609
0610 template <>
0611 struct process_attribute<is_final> : process_attribute_default<is_final> {
0612 static void init(const is_final &, type_record *r) { r->is_final = true; }
0613 };
0614
0615 template <>
0616 struct process_attribute<buffer_protocol> : process_attribute_default<buffer_protocol> {
0617 static void init(const buffer_protocol &, type_record *r) { r->buffer_protocol = true; }
0618 };
0619
0620 template <>
0621 struct process_attribute<metaclass> : process_attribute_default<metaclass> {
0622 static void init(const metaclass &m, type_record *r) { r->metaclass = m.value; }
0623 };
0624
0625 template <>
0626 struct process_attribute<module_local> : process_attribute_default<module_local> {
0627 static void init(const module_local &l, type_record *r) { r->module_local = l.value; }
0628 };
0629
0630 template <>
0631 struct process_attribute<release_gil_before_calling_cpp_dtor>
0632 : process_attribute_default<release_gil_before_calling_cpp_dtor> {
0633 static void init(const release_gil_before_calling_cpp_dtor &, type_record *r) {
0634 r->release_gil_before_calling_cpp_dtor = true;
0635 }
0636 };
0637
0638
0639 template <>
0640 struct process_attribute<prepend> : process_attribute_default<prepend> {
0641 static void init(const prepend &, function_record *r) { r->prepend = true; }
0642 };
0643
0644
0645 template <>
0646 struct process_attribute<arithmetic> : process_attribute_default<arithmetic> {};
0647
0648 template <typename... Ts>
0649 struct process_attribute<call_guard<Ts...>> : process_attribute_default<call_guard<Ts...>> {};
0650
0651
0652
0653
0654
0655
0656 template <size_t Nurse, size_t Patient>
0657 struct process_attribute<keep_alive<Nurse, Patient>>
0658 : public process_attribute_default<keep_alive<Nurse, Patient>> {
0659 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N != 0 && P != 0, int> = 0>
0660 static void precall(function_call &call) {
0661 keep_alive_impl(Nurse, Patient, call, handle());
0662 }
0663 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N != 0 && P != 0, int> = 0>
0664 static void postcall(function_call &, handle) {}
0665 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N == 0 || P == 0, int> = 0>
0666 static void precall(function_call &) {}
0667 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N == 0 || P == 0, int> = 0>
0668 static void postcall(function_call &call, handle ret) {
0669 keep_alive_impl(Nurse, Patient, call, ret);
0670 }
0671 };
0672
0673
0674 template <typename... Args>
0675 struct process_attributes {
0676 static void init(const Args &...args, function_record *r) {
0677 PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(r);
0678 PYBIND11_WORKAROUND_INCORRECT_GCC_UNUSED_BUT_SET_PARAMETER(r);
0679 using expander = int[];
0680 (void) expander{
0681 0, ((void) process_attribute<typename std::decay<Args>::type>::init(args, r), 0)...};
0682 }
0683 static void init(const Args &...args, type_record *r) {
0684 PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(r);
0685 PYBIND11_WORKAROUND_INCORRECT_GCC_UNUSED_BUT_SET_PARAMETER(r);
0686 using expander = int[];
0687 (void) expander{0,
0688 (process_attribute<typename std::decay<Args>::type>::init(args, r), 0)...};
0689 }
0690 static void precall(function_call &call) {
0691 PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(call);
0692 using expander = int[];
0693 (void) expander{0,
0694 (process_attribute<typename std::decay<Args>::type>::precall(call), 0)...};
0695 }
0696 static void postcall(function_call &call, handle fn_ret) {
0697 PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(call, fn_ret);
0698 PYBIND11_WORKAROUND_INCORRECT_GCC_UNUSED_BUT_SET_PARAMETER(fn_ret);
0699 using expander = int[];
0700 (void) expander{
0701 0, (process_attribute<typename std::decay<Args>::type>::postcall(call, fn_ret), 0)...};
0702 }
0703 };
0704
0705 template <typename T>
0706 struct is_keep_alive : std::false_type {};
0707
0708 template <size_t Nurse, size_t Patient>
0709 struct is_keep_alive<keep_alive<Nurse, Patient>> : std::true_type {};
0710
0711 template <typename T>
0712 using is_call_guard = is_instantiation<call_guard, T>;
0713
0714
0715 template <typename... Extra>
0716 using extract_guard_t = typename exactly_one_t<is_call_guard, call_guard<>, Extra...>::type;
0717
0718
0719 template <typename... Extra,
0720 size_t named = constexpr_sum(std::is_base_of<arg, Extra>::value...),
0721 size_t self = constexpr_sum(std::is_same<is_method, Extra>::value...)>
0722 constexpr bool expected_num_args(size_t nargs, bool has_args, bool has_kwargs) {
0723 PYBIND11_WORKAROUND_INCORRECT_MSVC_C4100(nargs, has_args, has_kwargs);
0724 return named == 0
0725 || (self + named + static_cast<size_t>(has_args) + static_cast<size_t>(has_kwargs))
0726 == nargs;
0727 }
0728
0729 PYBIND11_NAMESPACE_END(detail)
0730 PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)