]>
Commit | Line | Data |
---|---|---|
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] |