1[section boost/python/object.hpp] 2[section Introduction] 3Exposes 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`` 7class slice_nil; 8static const _ = slice_nil(); 9`` 10A 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`` 15C++ equivalent: 16`` 17x.slice(_,-1) 18x[slice(_,_,-1)] 19`` 20[endsect] 21[section Class `const_attribute_policies`] 22The policies which are used for proxies representing an attribute access to a const object. 23`` 24namespace 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`` 36static 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`] 46The policies which are used for proxies representing an attribute access to a mutable object. 47`` 48namespace 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`` 60static 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`` 68static 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`] 77The 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`` 79namespace 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`` 91static 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`] 101The 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`` 103namespace 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`` 115static 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`` 123static 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`] 132The policies which are used for proxies representing an item access (via the Python bracket operators []) to a const object. 133`` 134namespace 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`` 146static 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`] 155The policies which are used for proxies representing an item access (via the Python bracket operators []) to a mutable object. 156`` 157namespace 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`` 169static 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`` 176static 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`] 184The policies which are used for proxies representing an slice access (via the Python slice notation [x:y]) to a const object. 185`` 186namespace 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`` 198static 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`] 207The policies which are used for proxies representing an slice access to a mutable object. 208`` 209namespace 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`` 221static 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`` 228static 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`] 236This 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`` 238namespace 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`` 294object operator()() const; 295template <class A0> 296object operator()(A0 const&) const; 297template <class A0, class A1> 298object operator()(A0 const&, A1 const&) const; 299... 300template <class A0, class A1,...class An> 301object 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`` 323proxy<const_object_attribute> attr(char const* name) const; 324proxy<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`` 332proxy<const_object_objattribute> attr(const object& name) const; 333proxy<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`` 341template <class T> 342proxy<const_object_item> operator[](T const& key) const; 343template <class T> 344proxy<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`` 351template <class T, class V> 352proxy<const_object_slice> slice(T const& start; start, V const& finish) const 353template <class T, class V> 354proxy<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`] 362The 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`` 364namespace 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> 390explicit 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`] 416This 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`` 418namespace 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`` 462proxy const& operator=(proxy const& rhs) const; 463template <class T> 464inline 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`` 470template <class R> 471proxy operator+=(R const& rhs); 472template <class R> 473proxy operator-=(R const& rhs); 474template <class R> 475proxy operator*=(R const& rhs); 476template <class R> 477proxy operator/=(R const& rhs); 478template <class R> 479proxy operator%=(R const& rhs); 480template <class R> 481proxy operator<<=(R const& rhs); 482template <class R> 483proxy operator>>=(R const& rhs); 484template <class R> 485proxy operator&=(R const& rhs); 486template <class R> 487proxy 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`` 500template <class T> 501void del(proxy<T> const& x); 502`` 503[variablelist 504[[Effects][`x.del()`]] 505] 506`` 507template<class L,class R> object operator>(L const&l,R const&r); 508template<class L,class R> object operator>=(L const&l,R const&r); 509template<class L,class R> object operator<(L const&l,R const&r); 510template<class L,class R> object operator<=(L const&l,R const&r); 511template<class L,class R> object operator==(L const&l,R const&r); 512template<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`` 518template<class L,class R> object operator+(L const&l,R const&r); 519template<class L,class R> object operator-(L const&l,R const&r); 520template<class L,class R> object operator*(L const&l,R const&r); 521template<class L,class R> object operator/(L const&l,R const&r); 522template<class L,class R> object operator%(L const&l,R const&r); 523template<class L,class R> object operator<<(L const&l,R const&r); 524template<class L,class R> object operator>>(L const&l,R const&r); 525template<class L,class R> object operator&(L const&l,R const&r); 526template<class L,class R> object operator^(L const&l,R const&r); 527template<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`` 533template<class R> object& operator+=(object&l,R const&r); 534template<class R> object& operator-=(object&l,R const&r); 535template<class R> object& operator*=(object&l,R const&r); 536template<class R> object& operator/=(object&l,R const&r); 537template<class R> object& operator%=(object&l,R const&r); 538template<class R> object& operator<<=(object&l,R const&r) 539template<class R> object& operator>>=(object&l,R const&r); 540template<class R> object& operator&=(object&l,R const&r); 541template<class R> object& operator^=(object&l,R const&r); 542template<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] 555Python code: 556`` 557def sum_items(seq): 558 result = 0 559 for x in seq: 560 result += x 561 return result 562`` 563C++ version 564`` 565object 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] 575