attr.h revision 12037:d28054ac6ec9
1/* 2 pybind11/pybind11.h: Infrastructure for processing custom 3 type and function attributes 4 5 Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch> 6 7 All rights reserved. Use of this source code is governed by a 8 BSD-style license that can be found in the LICENSE file. 9*/ 10 11#pragma once 12 13#include "cast.h" 14 15NAMESPACE_BEGIN(pybind11) 16 17/// \addtogroup annotations 18/// @{ 19 20/// Annotation for methods 21struct is_method { handle class_; is_method(const handle &c) : class_(c) { } }; 22 23/// Annotation for operators 24struct is_operator { }; 25 26/// Annotation for parent scope 27struct scope { handle value; scope(const handle &s) : value(s) { } }; 28 29/// Annotation for documentation 30struct doc { const char *value; doc(const char *value) : value(value) { } }; 31 32/// Annotation for function names 33struct name { const char *value; name(const char *value) : value(value) { } }; 34 35/// Annotation indicating that a function is an overload associated with a given "sibling" 36struct sibling { handle value; sibling(const handle &value) : value(value.ptr()) { } }; 37 38/// Annotation indicating that a class derives from another given type 39template <typename T> struct base { 40 PYBIND11_DEPRECATED("base<T>() was deprecated in favor of specifying 'T' as a template argument to class_") 41 base() { } 42}; 43 44/// Keep patient alive while nurse lives 45template <size_t Nurse, size_t Patient> struct keep_alive { }; 46 47/// Annotation indicating that a class is involved in a multiple inheritance relationship 48struct multiple_inheritance { }; 49 50/// Annotation which enables dynamic attributes, i.e. adds `__dict__` to a class 51struct dynamic_attr { }; 52 53/// Annotation which enables the buffer protocol for a type 54struct buffer_protocol { }; 55 56/// Annotation which requests that a special metaclass is created for a type 57struct metaclass { 58 handle value; 59 60 PYBIND11_DEPRECATED("py::metaclass() is no longer required. It's turned on by default now.") 61 metaclass() = default; 62 63 /// Override pybind11's default metaclass 64 explicit metaclass(handle value) : value(value) { } 65}; 66 67/// Annotation to mark enums as an arithmetic type 68struct arithmetic { }; 69 70/// @} annotations 71 72NAMESPACE_BEGIN(detail) 73/* Forward declarations */ 74enum op_id : int; 75enum op_type : int; 76struct undefined_t; 77template <op_id id, op_type ot, typename L = undefined_t, typename R = undefined_t> struct op_; 78template <typename... Args> struct init; 79template <typename... Args> struct init_alias; 80inline void keep_alive_impl(size_t Nurse, size_t Patient, function_call &call, handle ret); 81 82/// Internal data structure which holds metadata about a keyword argument 83struct argument_record { 84 const char *name; ///< Argument name 85 const char *descr; ///< Human-readable version of the argument value 86 handle value; ///< Associated Python object 87 bool convert : 1; ///< True if the argument is allowed to convert when loading 88 89 argument_record(const char *name, const char *descr, handle value, bool convert) 90 : name(name), descr(descr), value(value), convert(convert) { } 91}; 92 93/// Internal data structure which holds metadata about a bound function (signature, overloads, etc.) 94struct function_record { 95 function_record() 96 : is_constructor(false), is_stateless(false), is_operator(false), 97 has_args(false), has_kwargs(false), is_method(false) { } 98 99 /// Function name 100 char *name = nullptr; /* why no C++ strings? They generate heavier code.. */ 101 102 // User-specified documentation string 103 char *doc = nullptr; 104 105 /// Human-readable version of the function signature 106 char *signature = nullptr; 107 108 /// List of registered keyword arguments 109 std::vector<argument_record> args; 110 111 /// Pointer to lambda function which converts arguments and performs the actual call 112 handle (*impl) (function_call &) = nullptr; 113 114 /// Storage for the wrapped function pointer and captured data, if any 115 void *data[3] = { }; 116 117 /// Pointer to custom destructor for 'data' (if needed) 118 void (*free_data) (function_record *ptr) = nullptr; 119 120 /// Return value policy associated with this function 121 return_value_policy policy = return_value_policy::automatic; 122 123 /// True if name == '__init__' 124 bool is_constructor : 1; 125 126 /// True if this is a stateless function pointer 127 bool is_stateless : 1; 128 129 /// True if this is an operator (__add__), etc. 130 bool is_operator : 1; 131 132 /// True if the function has a '*args' argument 133 bool has_args : 1; 134 135 /// True if the function has a '**kwargs' argument 136 bool has_kwargs : 1; 137 138 /// True if this is a method 139 bool is_method : 1; 140 141 /// Number of arguments (including py::args and/or py::kwargs, if present) 142 std::uint16_t nargs; 143 144 /// Python method object 145 PyMethodDef *def = nullptr; 146 147 /// Python handle to the parent scope (a class or a module) 148 handle scope; 149 150 /// Python handle to the sibling function representing an overload chain 151 handle sibling; 152 153 /// Pointer to next overload 154 function_record *next = nullptr; 155}; 156 157/// Special data structure which (temporarily) holds metadata about a bound class 158struct type_record { 159 PYBIND11_NOINLINE type_record() 160 : multiple_inheritance(false), dynamic_attr(false), buffer_protocol(false) { } 161 162 /// Handle to the parent scope 163 handle scope; 164 165 /// Name of the class 166 const char *name = nullptr; 167 168 // Pointer to RTTI type_info data structure 169 const std::type_info *type = nullptr; 170 171 /// How large is the underlying C++ type? 172 size_t type_size = 0; 173 174 /// How large is pybind11::instance<type>? 175 size_t instance_size = 0; 176 177 /// The global operator new can be overridden with a class-specific variant 178 void *(*operator_new)(size_t) = ::operator new; 179 180 /// Function pointer to class_<..>::init_holder 181 void (*init_holder)(PyObject *, const void *) = nullptr; 182 183 /// Function pointer to class_<..>::dealloc 184 void (*dealloc)(PyObject *) = nullptr; 185 186 /// List of base classes of the newly created type 187 list bases; 188 189 /// Optional docstring 190 const char *doc = nullptr; 191 192 /// Custom metaclass (optional) 193 handle metaclass; 194 195 /// Multiple inheritance marker 196 bool multiple_inheritance : 1; 197 198 /// Does the class manage a __dict__? 199 bool dynamic_attr : 1; 200 201 /// Does the class implement the buffer protocol? 202 bool buffer_protocol : 1; 203 204 /// Is the default (unique_ptr) holder type used? 205 bool default_holder : 1; 206 207 PYBIND11_NOINLINE void add_base(const std::type_info *base, void *(*caster)(void *)) { 208 auto base_info = detail::get_type_info(*base, false); 209 if (!base_info) { 210 std::string tname(base->name()); 211 detail::clean_type_id(tname); 212 pybind11_fail("generic_type: type \"" + std::string(name) + 213 "\" referenced unknown base type \"" + tname + "\""); 214 } 215 216 if (default_holder != base_info->default_holder) { 217 std::string tname(base->name()); 218 detail::clean_type_id(tname); 219 pybind11_fail("generic_type: type \"" + std::string(name) + "\" " + 220 (default_holder ? "does not have" : "has") + 221 " a non-default holder type while its base \"" + tname + "\" " + 222 (base_info->default_holder ? "does not" : "does")); 223 } 224 225 bases.append((PyObject *) base_info->type); 226 227 if (base_info->type->tp_dictoffset != 0) 228 dynamic_attr = true; 229 230 if (caster) 231 base_info->implicit_casts.push_back(std::make_pair(type, caster)); 232 } 233}; 234 235inline function_call::function_call(function_record &f, handle p) : 236 func(f), parent(p) { 237 args.reserve(f.nargs); 238 args_convert.reserve(f.nargs); 239} 240 241/** 242 * Partial template specializations to process custom attributes provided to 243 * cpp_function_ and class_. These are either used to initialize the respective 244 * fields in the type_record and function_record data structures or executed at 245 * runtime to deal with custom call policies (e.g. keep_alive). 246 */ 247template <typename T, typename SFINAE = void> struct process_attribute; 248 249template <typename T> struct process_attribute_default { 250 /// Default implementation: do nothing 251 static void init(const T &, function_record *) { } 252 static void init(const T &, type_record *) { } 253 static void precall(function_call &) { } 254 static void postcall(function_call &, handle) { } 255}; 256 257/// Process an attribute specifying the function's name 258template <> struct process_attribute<name> : process_attribute_default<name> { 259 static void init(const name &n, function_record *r) { r->name = const_cast<char *>(n.value); } 260}; 261 262/// Process an attribute specifying the function's docstring 263template <> struct process_attribute<doc> : process_attribute_default<doc> { 264 static void init(const doc &n, function_record *r) { r->doc = const_cast<char *>(n.value); } 265}; 266 267/// Process an attribute specifying the function's docstring (provided as a C-style string) 268template <> struct process_attribute<const char *> : process_attribute_default<const char *> { 269 static void init(const char *d, function_record *r) { r->doc = const_cast<char *>(d); } 270 static void init(const char *d, type_record *r) { r->doc = const_cast<char *>(d); } 271}; 272template <> struct process_attribute<char *> : process_attribute<const char *> { }; 273 274/// Process an attribute indicating the function's return value policy 275template <> struct process_attribute<return_value_policy> : process_attribute_default<return_value_policy> { 276 static void init(const return_value_policy &p, function_record *r) { r->policy = p; } 277}; 278 279/// Process an attribute which indicates that this is an overloaded function associated with a given sibling 280template <> struct process_attribute<sibling> : process_attribute_default<sibling> { 281 static void init(const sibling &s, function_record *r) { r->sibling = s.value; } 282}; 283 284/// Process an attribute which indicates that this function is a method 285template <> struct process_attribute<is_method> : process_attribute_default<is_method> { 286 static void init(const is_method &s, function_record *r) { r->is_method = true; r->scope = s.class_; } 287}; 288 289/// Process an attribute which indicates the parent scope of a method 290template <> struct process_attribute<scope> : process_attribute_default<scope> { 291 static void init(const scope &s, function_record *r) { r->scope = s.value; } 292}; 293 294/// Process an attribute which indicates that this function is an operator 295template <> struct process_attribute<is_operator> : process_attribute_default<is_operator> { 296 static void init(const is_operator &, function_record *r) { r->is_operator = true; } 297}; 298 299/// Process a keyword argument attribute (*without* a default value) 300template <> struct process_attribute<arg> : process_attribute_default<arg> { 301 static void init(const arg &a, function_record *r) { 302 if (r->is_method && r->args.empty()) 303 r->args.emplace_back("self", nullptr, handle(), true /*convert*/); 304 r->args.emplace_back(a.name, nullptr, handle(), !a.flag_noconvert); 305 } 306}; 307 308/// Process a keyword argument attribute (*with* a default value) 309template <> struct process_attribute<arg_v> : process_attribute_default<arg_v> { 310 static void init(const arg_v &a, function_record *r) { 311 if (r->is_method && r->args.empty()) 312 r->args.emplace_back("self", nullptr /*descr*/, handle() /*parent*/, true /*convert*/); 313 314 if (!a.value) { 315#if !defined(NDEBUG) 316 std::string descr("'"); 317 if (a.name) descr += std::string(a.name) + ": "; 318 descr += a.type + "'"; 319 if (r->is_method) { 320 if (r->name) 321 descr += " in method '" + (std::string) str(r->scope) + "." + (std::string) r->name + "'"; 322 else 323 descr += " in method of '" + (std::string) str(r->scope) + "'"; 324 } else if (r->name) { 325 descr += " in function '" + (std::string) r->name + "'"; 326 } 327 pybind11_fail("arg(): could not convert default argument " 328 + descr + " into a Python object (type not registered yet?)"); 329#else 330 pybind11_fail("arg(): could not convert default argument " 331 "into a Python object (type not registered yet?). " 332 "Compile in debug mode for more information."); 333#endif 334 } 335 r->args.emplace_back(a.name, a.descr, a.value.inc_ref(), !a.flag_noconvert); 336 } 337}; 338 339/// Process a parent class attribute. Single inheritance only (class_ itself already guarantees that) 340template <typename T> 341struct process_attribute<T, enable_if_t<is_pyobject<T>::value>> : process_attribute_default<handle> { 342 static void init(const handle &h, type_record *r) { r->bases.append(h); } 343}; 344 345/// Process a parent class attribute (deprecated, does not support multiple inheritance) 346template <typename T> 347struct process_attribute<base<T>> : process_attribute_default<base<T>> { 348 static void init(const base<T> &, type_record *r) { r->add_base(&typeid(T), nullptr); } 349}; 350 351/// Process a multiple inheritance attribute 352template <> 353struct process_attribute<multiple_inheritance> : process_attribute_default<multiple_inheritance> { 354 static void init(const multiple_inheritance &, type_record *r) { r->multiple_inheritance = true; } 355}; 356 357template <> 358struct process_attribute<dynamic_attr> : process_attribute_default<dynamic_attr> { 359 static void init(const dynamic_attr &, type_record *r) { r->dynamic_attr = true; } 360}; 361 362template <> 363struct process_attribute<buffer_protocol> : process_attribute_default<buffer_protocol> { 364 static void init(const buffer_protocol &, type_record *r) { r->buffer_protocol = true; } 365}; 366 367template <> 368struct process_attribute<metaclass> : process_attribute_default<metaclass> { 369 static void init(const metaclass &m, type_record *r) { r->metaclass = m.value; } 370}; 371 372 373/// Process an 'arithmetic' attribute for enums (does nothing here) 374template <> 375struct process_attribute<arithmetic> : process_attribute_default<arithmetic> {}; 376 377/*** 378 * Process a keep_alive call policy -- invokes keep_alive_impl during the 379 * pre-call handler if both Nurse, Patient != 0 and use the post-call handler 380 * otherwise 381 */ 382template <size_t Nurse, size_t Patient> struct process_attribute<keep_alive<Nurse, Patient>> : public process_attribute_default<keep_alive<Nurse, Patient>> { 383 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N != 0 && P != 0, int> = 0> 384 static void precall(function_call &call) { keep_alive_impl(Nurse, Patient, call, handle()); } 385 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N != 0 && P != 0, int> = 0> 386 static void postcall(function_call &, handle) { } 387 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N == 0 || P == 0, int> = 0> 388 static void precall(function_call &) { } 389 template <size_t N = Nurse, size_t P = Patient, enable_if_t<N == 0 || P == 0, int> = 0> 390 static void postcall(function_call &call, handle ret) { keep_alive_impl(Nurse, Patient, call, ret); } 391}; 392 393/// Recursively iterate over variadic template arguments 394template <typename... Args> struct process_attributes { 395 static void init(const Args&... args, function_record *r) { 396 int unused[] = { 0, (process_attribute<typename std::decay<Args>::type>::init(args, r), 0) ... }; 397 ignore_unused(unused); 398 } 399 static void init(const Args&... args, type_record *r) { 400 int unused[] = { 0, (process_attribute<typename std::decay<Args>::type>::init(args, r), 0) ... }; 401 ignore_unused(unused); 402 } 403 static void precall(function_call &call) { 404 int unused[] = { 0, (process_attribute<typename std::decay<Args>::type>::precall(call), 0) ... }; 405 ignore_unused(unused); 406 } 407 static void postcall(function_call &call, handle fn_ret) { 408 int unused[] = { 0, (process_attribute<typename std::decay<Args>::type>::postcall(call, fn_ret), 0) ... }; 409 ignore_unused(unused); 410 } 411}; 412 413/// Check the number of named arguments at compile time 414template <typename... Extra, 415 size_t named = constexpr_sum(std::is_base_of<arg, Extra>::value...), 416 size_t self = constexpr_sum(std::is_same<is_method, Extra>::value...)> 417constexpr bool expected_num_args(size_t nargs, bool has_args, bool has_kwargs) { 418 return named == 0 || (self + named + has_args + has_kwargs) == nargs; 419} 420 421NAMESPACE_END(detail) 422NAMESPACE_END(pybind11) 423