ceph/src/boost/libs/python/doc/reference/object.qbk

   1 [section boost/python/object.hpp]
   2 [section Introduction]
   3 Exposes the generic Python object wrapper class object, and related classes. In order to avoid some potenential problems with argument-dependent lookup and the generalized operators defined on object, all these facilities are defined in namespace boost::python::api, and object is imported into namespace boost::python with a using-declaration.
   4 [endsect]
   5 [section Class `slice_nil`]
   6 ``
   7 class slice_nil;
   8 static const _ = slice_nil();
   9 ``
  10 A type that can be used to get the effect of leaving out an index in a Python slice expression:
  11 ``
  12 >>> x[:-1]
  13 >>> x[::-1]
  14 ``
  15 C++ equivalent:
  16 ``
  17 x.slice(_,-1)
  18 x[slice(_,_,-1)]
  19 ``
  20 [endsect]
  21 [section Class `const_attribute_policies`]
  22 The policies which are used for proxies representing an attribute access to a const object.
  23 ``
  24 namespace boost { namespace python { namespace api
  25 {
  26   struct const_attribute_policies
  27   {
  28       typedef char const* key_type;
  29       static object get(object const& target, char const* key);
  30   };
  31 }}}
  32 ``
  33 [endsect]
  34 [section Class `const_attribute_policies` static functions]
  35 ``
  36 static object get(object const& target, char const* key);
  37 ``
  38 [variablelist
  39 [[Requires][key is an [link ntbs].]]
  40 [[Effects][accesses the attribute of target named by key.]]
  41 [[Returns][An object managing the result of the attribute access.]]
  42 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
  43 ]
  44 [endsect]
  45 [section Class `attribute_policies`]
  46 The policies which are used for proxies representing an attribute access to a mutable object.
  47 ``
  48 namespace boost { namespace python { namespace api
  49 {
  50   struct attribute_policies : const_attribute_policies
  51   {
  52       static object const& set(object const& target, char const* key, object const& value);
  53       static void del(object const&target, char const* key);
  54   };
  55 }}}
  56 ``
  57 [endsect]
  58 [section Class `attribute_policies` static functions]
  59 ``
  60 static object const& set(object const& target, char const* key, object const& value);
  61 ``
  62 [variablelist
  63 [[Requires][key is an [link ntbs].]]
  64 [[Effects][sets the attribute of target named by key to value.]]
  65 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
  66 ]
  67 ``
  68 static void del(object const&target, char const* key);
  69 ``
  70 [variablelist
  71 [[Requires][key is an [link ntbs].]]
  72 [[Effects][deletes the attribute of target named by key.]]
  73 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
  74 ]
  75 [endsect]
  76 [section Class `const_objattribute_policies`]
  77 The policies which are used for proxies representing an attribute access to a const object when the attribute name is given as a const object.
  78 ``
  79 namespace boost { namespace python { namespace api
  80 {
  81   struct const_objattribute_policies
  82   {
  83       typedef object const& key_type;
  84       static object get(object const& target, object const& key);
  85   };
  86 }}}
  87 ``
  88 [endsect]
  89 [section Class `const_objattribute_policies` static functions]
  90 ``
  91 static object get(object const& target, object const& key);
  92 ``
  93 [variablelist
  94 [[Requires][key is an object holding a string.]]
  95 [[Effects][accesses the attribute of target named by key.]]
  96 [[Returns][An object managing the result of the attribute access.]]
  97 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
  98 ]
  99 [endsect]
 100 [section Class `objattribute_policies`]
 101 The policies which are used for proxies representing an attribute access to a mutable object when the attribute name is given as a const object.
 102 ``
 103 namespace boost { namespace python { namespace api
 104 {
 105   struct objattribute_policies : const_objattribute_policies
 106   {
 107       static object const& set(object const& target, object const& key, object const& value);
 108       static void del(object const&target, object const& key);
 109   };
 110 }}}
 111 ``
 112 [endsect]
 113 [section Class `objattribute_policies` static functions]
 114 ``
 115 static object const& set(object const& target, object const& key, object const& value);
 116 ``
 117 [variablelist
 118 [[Requires][key is an object holding a string.]]
 119 [[Effects][sets the attribute of target named by key to value.]]
 120 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 121 ]
 122 ``
 123 static void del(object const&target, object const& key);
 124 ``
 125 [variablelist
 126 [[Requires][key is an object holding a string.]]
 127 [[Effects][deletes the attribute of target named by key.]]
 128 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 129 ]
 130 [endsect]
 131 [section Class `const_item_policies`]
 132 The policies which are used for proxies representing an item access (via the Python bracket operators []) to a const object.
 133 ``
 134 namespace boost { namespace python { namespace api
 135 {
 136   struct const_item_policies
 137   {
 138       typedef object key_type;
 139       static object get(object const& target, object const& key);
 140   };
 141 }}}
 142 ``
 143 [endsect]
 144 [section Class `const_item_policies` static functions]
 145 ``
 146 static object get(object const& target, object const& key);
 147 ``
 148 [variablelist
 149 [[Effects][accesses the item of target specified by key.]]
 150 [[Returns][An object managing the result of the item access.]]
 151 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 152 ]
 153 [endsect]
 154 [section Class `item_policies`]
 155 The policies which are used for proxies representing an item access (via the Python bracket operators []) to a mutable object.
 156 ``
 157 namespace boost { namespace python { namespace api
 158 {
 159   struct item_policies : const_item_policies
 160   {
 161       static object const& set(object const& target, object const& key, object const& value);
 162       static void del(object const& target, object const& key);
 163   };
 164 }}}
 165 ``
 166 [endsect]
 167 [section Class `item_policies` static functions]
 168 ``
 169 static object const& set(object const& target, object const& key, object const& value);
 170 ``
 171 [variablelist
 172 [[Effects][sets the item of target specified by key to value.]]
 173 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 174 ]
 175 ``
 176 static void del(object const& target, object const& key);
 177 ``
 178 [variablelist
 179 [[Effects][deletes the item of target specified by key.]]
 180 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 181 ]
 182 [endsect]
 183 [section Class `const_slice_policies`]
 184 The policies which are used for proxies representing an slice access (via the Python slice notation [x:y]) to a const object.
 185 ``
 186 namespace boost { namespace python { namespace api
 187 {
 188   struct const_slice_policies
 189   {
 190       typedef std::pair<handle<>, handle<> > key_type;
 191       static object get(object const& target, key_type const& key);
 192   };
 193 }}}
 194 ``
 195 [endsect]
 196 [section Class `const_slice_policies` static functions]
 197 ``
 198 static object get(object const& target, key_type const& key);
 199 ``
 200 [variablelist
 201 [[Effects][accesses the slice of target specified by key.]]
 202 [[Returns][An object managing the result of the slice access.]]
 203 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 204 ]
 205 [endsect]
 206 [section Class `slice_policies`]
 207 The policies which are used for proxies representing an slice access to a mutable object.
 208 ``
 209 namespace boost { namespace python { namespace api
 210 {
 211   struct slice_policies : const_slice_policies
 212   {
 213       static object const& set(object const& target, key_type const& key, object const& value);
 214       static void del(object const& target, key_type const& key);
 215   };
 216 }}}
 217 ``
 218 [endsect]
 219 [section Class `slice_policies` static functions]
 220 ``
 221 static object const& set(object const& target, key_type const& key, object const& value);
 222 ``
 223 [variablelist
 224 [[Effects][sets the slice of target specified by key to value.]]
 225 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 226 ]
 227 ``
 228 static void del(object const& target, key_type const& key);
 229 ``
 230 [variablelist
 231 [[Effects][deletes the slice of target specified by key.]]
 232 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] if a Python exception is raised.]]
 233 ]
 234 [endsect]
 235 [section Class template `object_operators`]
 236 This is the base class of object and its proxy template used to supply common interface: member functions, and operators which must be defined within the class body. Its template parameter U is expected to be a class derived from object_operators<U>. In practice users should never use this class directly, but it is documented here because it supplies important interface to object and its proxies.
 237 ``
 238 namespace boost { namespace python { namespace api
 239 {
 240   template <class U>
 241   class object_operators
 242   {
 243    public:
 244       // function call
 245       //
 246       object operator()() const;
 247
 248       template <class A0>
 249       object operator()(A0 const&) const;
 250       template <class A0, class A1>
 251       object operator()(A0 const&, A1 const&) const;
 252       ...
 253       template <class A0, class A1,...class An>
 254       object operator()(A0 const&, A1 const&,...An const&) const;
 255
 256       detail::args_proxy operator* () const;
 257       object operator()(detail::args_proxy const &args) const;
 258       object operator()(detail::args_proxy const &args,
 259                         detail::kwds_proxy const &kwds) const;
 260
 261       // truth value testing
 262       //
 263       typedef unspecified bool_type;
 264       operator bool_type() const;
 265
 266       // Attribute access
 267       //
 268       proxy<const_object_attribute> attr(char const*) const;
 269       proxy<object_attribute> attr(char const*);
 270       proxy<const_object_objattribute> attr(object const&) const;
 271       proxy<object_objattribute> attr(object const&);
 272
 273       // item access
 274       //
 275       template <class T>
 276       proxy<const_object_item> operator[](T const& key) const;
 277
 278       template <class T>
 279       proxy<object_item> operator[](T const& key);
 280
 281       // slicing
 282       //
 283       template <class T, class V>
 284       proxy<const_object_slice> slice(T const& start, V const& end) const
 285
 286       template <class T, class V>
 287       proxy<object_slice> slice(T const& start, V const& end);
 288   };
 289 }}}
 290 ``
 291 [endsect]
 292 [section Class template `object_operators` observer functions]
 293 ``
 294 object operator()() const;
 295 template <class A0>
 296 object operator()(A0 const&) const;
 297 template <class A0, class A1>
 298 object operator()(A0 const&, A1 const&) const;
 299 ...
 300 template <class A0, class A1,...class An>
 301 object operator()(A0 const& a1, A1 const& a2,...An const& aN) const;
 302 ``
 303 [variablelist
 304 [[Effects][`call<object>(object(*static_cast<U*>(this)).ptr(), a1, a2,...aN)`]]
 305 ]
 306 ``object operator()(detail::args_proxy const &args) const; ``
 307 [variablelist
 308 [[Effects][`call object with arguments given by the tuple args`]]
 309 ]
 310 ``object operator()(detail::args_proxy const &args,
 311                   detail::kwds_proxy const &kwds) const;
 312
 313 ``
 314 [variablelist
 315 [[Effects][`call object with arguments given by the tuple args, and named arguments given by the dictionary kwds`]]
 316 ]
 317 ``operator bool_type() const;``
 318 [variablelist
 319 [[Effects][Tests truth value of `*this`.]]
 320 [[Returns][`call<object>(object(*static_cast<U*>(this)).ptr(), a1, a2,...aN)`]]
 321 ]
 322 ``
 323 proxy<const_object_attribute> attr(char const* name) const;
 324 proxy<object_attribute> attr(char const* name);
 325 ``
 326 [variablelist
 327 [[Requires][name is an [link ntbs].]]
 328 [[Effects][accesses the named attribute of *this.]]
 329 [[Returns][a proxy object which binds `object(*static_cast<U*>(this))` as its target, and name as its key.]]
 330 ]
 331 ``
 332 proxy<const_object_objattribute> attr(const object& name) const;
 333 proxy<object_objattribute> attr(const object& name);
 334 ``
 335 [variablelist
 336 [[Requires][name is a object holding a string.]]
 337 [[Effects][accesses the named attribute of `*this`.]]
 338 [[Returns][a proxy object which binds `object(*static_cast<U*>(this))` as its target, and name as its key.]]
 339 ]
 340 ``
 341 template <class T>
 342 proxy<const_object_item> operator[](T const& key) const;
 343 template <class T>
 344 proxy<object_item> operator[](T const& key);
 345 ``
 346 [variablelist
 347 [[Effects][accesses the item of `*this` indicated by key.]]
 348 [[Returns][a proxy object which binds `object(*static_cast<U*>(this))` as its target, and object(key) as its key.]]
 349 ]
 350 ``
 351 template <class T, class V>
 352 proxy<const_object_slice> slice(T const& start; start, V const& finish) const
 353 template <class T, class V>
 354 proxy<object_slice> slice(T const& start; start, V const& finish);
 355 ``
 356 [variablelist
 357 [[Effects][accesses the slice of `*this` indicated by `std::make_pair(object(start), object(finish))`.]]
 358 [[Returns][a proxy object which binds `object(*static_cast<U*>(this))` as its target, and `std::make_pair(object(start), object(finish))` as its key.]]
 359 ]
 360 [endsect]
 361 [section Class `object`]
 362 The intention is that object acts as much like a Python variable as possible. Thus expressions you'd expect to work in Python should generally work in the same way from C++. Most of object's interface is provided by its base class `object_operators<object>`, and the free functions defined in this header.
 363 ``
 364 namespace boost { namespace python { namespace api
 365 {
 366   class object : public object_operators<object>
 367   {
 368    public:
 369       object();
 370       object(object const&);
 371       template <class T>
 372       explicit object(T const& x);
 373
 374       ~object();
 375
 376       object& operator=(object const&);
 377       PyObject* ptr() const;
 378       bool is_none() const;
 379   };
 380 }}}
 381 ``
 382 [endsect]
 383 [section Class `object` constructors and destructor]
 384 ``object();``
 385 [variablelist
 386 [[Effects][Constructs an object managing a reference to the Python None object.]]
 387 [[Throws][nothing.]]
 388 ]
 389 ``template <class T>
 390 explicit object(T const& x);
 391 ``
 392 [variablelist
 393 [[Effects][converts x to python and manages a reference to it.]]
 394 [[Throws][[link high_level_components.boost_python_errors_hpp.class_error_already_set error_already_set] and sets a Python TypeError exception if no such conversion is possible.]]
 395 ]
 396 ``
 397 ~object();
 398 ``
 399 [variablelist
 400 [[Effects][decrements the reference count of the internally-held object.]]
 401 ]
 402 [endsect]
 403 [section Class `object` modifiers]
 404 ``PyObject* ptr() const;``
 405
 406 [variablelist
 407 [[Returns] [a pointer to the internally-held Python object.]]
 408 ]
 409 ``bool is_none() const;``
 410
 411 [variablelist
 412 [[Returns] [result of `(ptr() == Py_None)`]]
 413 ]
 414 [endsect]
 415 [section Class template `proxy`]
 416 This template is instantiated with various Policies described in this document in order to implement attribute, item, and slice access for object. It stores an object of type Policies::key_type.
 417 ``
 418 namespace boost { namespace python { namespace api
 419 {
 420   template <class Policies>
 421   class proxy : public object_operators<proxy<Policies> >
 422   {
 423    public:
 424       operator object() const;
 425
 426       proxy const& operator=(proxy const&) const;
 427       template <class T>
 428       inline proxy const& operator=(T const& rhs) const;
 429
 430       void del() const;
 431
 432       template <class R>
 433       proxy operator+=(R const& rhs);
 434       template <class R>
 435       proxy operator-=(R const& rhs);
 436       template <class R>
 437       proxy operator*=(R const& rhs);
 438       template <class R>
 439       proxy operator/=(R const& rhs);
 440       template <class R>
 441       proxy operator%=(R const& rhs);
 442       template <class R>
 443       proxy operator<<=(R const& rhs);
 444       template <class R>
 445       proxy operator>>=(R const& rhs);
 446       template <class R>
 447       proxy operator&=(R const& rhs);
 448       template <class R>
 449       proxy operator|=(R const& rhs);
 450   };
 451 }}}
 452 ``
 453 [endsect]
 454 [section Class template `proxy` observer functions]
 455 ``operator object() const;``
 456 [variablelist
 457 [[Effects][applies `Policies::get(target, key)` with the proxy's target and key objects.]]
 458 ]
 459 [endsect]
 460 [section Class template `proxy` modifier functions]
 461 ``
 462 proxy const& operator=(proxy const& rhs) const;
 463 template <class T>
 464 inline proxy const& operator=(T const& rhs) const;
 465 ``
 466 [variablelist
 467 [[Effects][ `Policies::set(target, key , object(rhs))` with the proxy's target and key objects.]]
 468 ]
 469 ``
 470 template <class R>
 471 proxy operator+=(R const& rhs);
 472 template <class R>
 473 proxy operator-=(R const& rhs);
 474 template <class R>
 475 proxy operator*=(R const& rhs);
 476 template <class R>
 477 proxy operator/=(R const& rhs);
 478 template <class R>
 479 proxy operator%=(R const& rhs);
 480 template <class R>
 481 proxy operator<<=(R const& rhs);
 482 template <class R>
 483 proxy operator>>=(R const& rhs);
 484 template <class R>
 485 proxy operator&=(R const& rhs);
 486 template <class R>
 487 proxy operator|=(R const& rhs);
 488 ``
 489 [variablelist
 490 [[Effects][for a given `operator@=`, `object(*this) @= rhs;`]]
 491 [[Returns][`*this`]]
 492 ]
 493 ``void del() const;``
 494 [variablelist
 495 [[Effects][Policies::del(target, key ) with the proxy's target and key objects.]]
 496 ]
 497 [endsect]
 498 [section Functions]
 499 ``
 500 template <class T>
 501 void del(proxy<T> const& x);
 502 ``
 503 [variablelist
 504 [[Effects][`x.del()`]]
 505 ]
 506 ``
 507 template<class L,class R> object operator>(L const&l,R const&r);
 508 template<class L,class R> object operator>=(L const&l,R const&r);
 509 template<class L,class R> object operator<(L const&l,R const&r);
 510 template<class L,class R> object operator<=(L const&l,R const&r);
 511 template<class L,class R> object operator==(L const&l,R const&r);
 512 template<class L,class R> object operator!=(L const&l,R const&r);
 513 ``
 514 [variablelist
 515 [[Effects][returns the result of applying the operator to `object(l)` and `object(r)`, respectively, in Python.]]
 516 ]
 517 ``
 518 template<class L,class R> object operator+(L const&l,R const&r);
 519 template<class L,class R> object operator-(L const&l,R const&r);
 520 template<class L,class R> object operator*(L const&l,R const&r);
 521 template<class L,class R> object operator/(L const&l,R const&r);
 522 template<class L,class R> object operator%(L const&l,R const&r);
 523 template<class L,class R> object operator<<(L const&l,R const&r);
 524 template<class L,class R> object operator>>(L const&l,R const&r);
 525 template<class L,class R> object operator&(L const&l,R const&r);
 526 template<class L,class R> object operator^(L const&l,R const&r);
 527 template<class L,class R> object operator|(L const&l,R const&r);
 528 ``
 529 [variablelist
 530 [[Effects][returns the result of applying the operator to `object(l)` and `object(r)`, respectively, in Python.]]
 531 ]
 532 ``
 533 template<class R> object& operator+=(object&l,R const&r);
 534 template<class R> object& operator-=(object&l,R const&r);
 535 template<class R> object& operator*=(object&l,R const&r);
 536 template<class R> object& operator/=(object&l,R const&r);
 537 template<class R> object& operator%=(object&l,R const&r);
 538 template<class R> object& operator<<=(object&l,R const&r)
 539 template<class R> object& operator>>=(object&l,R const&r);
 540 template<class R> object& operator&=(object&l,R const&r);
 541 template<class R> object& operator^=(object&l,R const&r);
 542 template<class R> object& operator|=(object&l,R const&r);
 543 ``
 544 [variablelist
 545 [[Effects][assigns to `l` the result of applying the corresponding Python inplace operator to `l` and `object(r)`, respectively.]]
 546 [[Returns][l]]
 547 ]
 548 ``long len(object const& obj);``
 549 [variablelist
 550 [[Effects][`PyObject_Length(obj.ptr())`]]
 551 [[Returns][`len()` of object.]]
 552 ]
 553 [endsect]
 554 [section Example]
 555 Python code:
 556 ``
 557 def sum_items(seq):
 558    result = 0
 559    for x in seq:
 560       result += x
 561    return result
 562 ``
 563 C++ version
 564 ``
 565 object sum_items(object seq)
 566 {
 567    object result = object(0);
 568    for (int i = 0; i < len(seq); ++i)
 569       result += seq[i];
 570    return result;
 571 }
 572 ``
 573 [endsect]
 574 [endsect]