diff --git a/doc/v2/object.html b/doc/v2/object.html new file mode 100644 index 00000000..8fcd05c5 --- /dev/null +++ b/doc/v2/object.html @@ -0,0 +1,925 @@ + + + + + + + + + Boost.Python - <boost/python/object.hpp> + + + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/object.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Types
+ +
+
+
slice_nil
+
+
+ +
Classes
+ +
+
+
Class + const_attribute_policies
+ +
+
+
Class + const_attribute_policies synopsis
+ +
Class + const_attribute_policies static functions
+
+
+ +
Class + attribute_policies
+ +
+
+
Class + attribute_policies synopsis
+ +
Class + attribute_policies static functions
+
+
+ +
Class + const_item_policies
+ +
+
+
Class + const_item_policies synopsis
+ +
Class + const_item_policies static functions
+
+
+ +
Class + item_policies
+ +
+
+
Class + item_policies synopsis
+ +
Class + item_policies static functions
+
+
+ +
Class + const_slice_policies
+ +
+
+
Class + const_slice_policies synopsis
+ +
Class + const_slice_policies static functions
+
+
+ +
Class + slice_policies
+ +
+
+
Class + slice_policies synopsis
+ +
Class + slice_policies static functions
+
+
+ +
Class + object_operators
+ +
+
+
Class + object_operators synopsis
+ +
Class + object_operators observer functions
+
+
+ +
Class object
+ +
+
+
Class object + synopsis
+ +
Class object + constructors and destructor
+ +
Class template + object modifier functions
+ +
Class template + object observer functions
+
+
+ +
Class template + proxy
+ +
+
+
Class template + proxy synopsis
+ +
Class template + proxy modifier functions
+ +
Class template + proxy observer functions
+
+
+
+
+ +
Functions
+ +
+
+
del
+ +
comparisons
+ +
binary operations
+ +
assignment operations
+
+ +
+
operators
+
+
+ +
Example
+
+
+ +

Introduction

+ +

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.

+ +

Types

+ +

+
+enum slice_nil { _ };
+
+ A type that can be used to get the effect of leaving out an index in a + Python slice expression: +
+>>> x[:-1]
+
+ C++ equivalent: +
+x.slice(_,-1)
+
+ +

Classes

+ + +

Class + const_attribute_policies

+ +

The policies which are used for proxies representing an attribute + access to a const object.

+ +

Class + const_attribute_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct const_attribute_policies
+  {
+      typedef char const* key_type;
+      static object get(object const& target, char const* key);
+  };
+}}}
+
+ +

Class + const_attribute_policies static functions

+
+static object get(object const& target, char const* key);
+
+ +
+
Requires: key is an ntbs.
+ +
Effects: accesses the attribute of target named + by key.
+ +
Returns: An object managing the result of the + attribute access.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ +

Class + attribute_policies

+ +

The policies which are used for proxies representing an attribute + access to a mutable object.

+ +

Class + attribute_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct attribute_policies : const_attribute_policies
+  {
+      static object const& set(object const& target, char const* key, object const& value);
+      static void del(object const&target, char const* key);
+  };
+}}}
+
+ +

Class + attribute_policies static functions

+
+static object const& set(object const& target, char const* key, object const& value);
+
+ +
+
Requires: key is an ntbs.
+ +
Effects: sets the attribute of target named by + key to value.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+
+static void del(object const&target, char const* key);
+
+ +
+
Requires: key is an ntbs.
+ +
Effects: deletes the attribute of target named + by key.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ + + +

Class + const_item_policies

+ +

The policies which are used for proxies representing an item access + (via the Python bracket operators []) to a + const object.

+ +

Class + const_item_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct const_item_policies
+  {
+      typedef object key_type;
+      static object get(object const& target, object const& key);
+  };
+}}}
+
+ +

Class + const_item_policies static functions

+
+static object get(object const& target, object const& key);
+
+ +
+
Effects: accesses the item of target specified + by key.
+ +
Returns: An object managing the result of the + item access.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ +

Class + item_policies

+ +

The policies which are used for proxies representing an item access + (via the Python bracket operators []) to a mutable + object.

+ +

Class + item_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct item_policies : const_item_policies
+  {
+      static object const& set(object const& target, object const& key, object const& value);
+      static void del(object const& target, object const& key);
+  };
+}}}
+
+ +

Class + item_policies static functions

+
+static object const& set(object const& target, object const& key, object const& value);
+
+ +
+
Effects: sets the item of target specified by + key to value.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+
+static void del(object const& target, object const& key);
+
+ +
+
Effects: deletes the item of target specified + by key.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ + + +

Class + const_slice_policies

+ +

The policies which are used for proxies representing an slice access + (via the Python slice notation + [x:y]) to a + const object.

+ +

Class + const_slice_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct const_slice_policies
+  {
+      typedef std::pair<handle<>, handle<> > key_type;
+      static object get(object const& target, key_type const& key);
+  };
+}}}
+
+ +

Class + const_slice_policies static functions

+
+static object get(object const& target, key_type const& key);
+
+ +
+
Effects: accesses the slice of target specified + by key.
+ +
Returns: An object managing the result of the + slice access.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ +

Class + slice_policies

+ +

The policies which are used for proxies representing an slice access + to a mutable object.

+ +

Class + slice_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct slice_policies : const_slice_policies
+  {
+      static object const& set(object const& target, key_type const& key, object const& value);
+      static void del(object const& target, key_type const& key);
+  };
+}}}
+
+ +

Class + slice_policies static functions

+
+static object const& set(object const& target, key_type const& key, object const& value);
+
+ +
+
Effects: sets the slice of target specified by + key to value.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+
+static void del(object const& target, key_type const& key);
+
+ +
+
Effects: deletes the slice of target specified + by key.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ + +

Class template + object_operators<U>

+ +

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.

+ +

Class template + object_operators synopsis

+
+namespace boost { namespace python { namespace api
+{
+  template <class U>
+  class object_operators
+  {
+   public:
+      // function call
+      //
+      object operator()() const;
+
+      template <class A0>
+      object operator()(A0 const&) const;
+      template <class A0, class A1>
+      object operator()(A0 const&, A1 const&) const;
+      ...
+      template <class A0, class A1,...class An>
+      object operator()(A0 const&, A1 const&,...An const&) const;
+
+      // truth value testing
+      //
+      typedef unspecified bool_type;
+      operator bool_type() const;
+
+      // Attribute access
+      //
+      proxy<const_object_attribute> attr(char const*) const;
+      proxy<object_attribute> attr(char const*);
+
+      // item access
+      //
+      template <class T>
+      proxy<const_object_item> operator[](T const& key) const;
+    
+      template <class T>
+      proxy<object_item> operator[](T const& key);
+
+      // slicing
+      //
+      template <class T, class V>
+      proxy<const_object_slice> slice(T const& start, V const& end) const
+    
+      template <class T, class V>
+      proxy<object_slice> slice(T const& start, V const& end);
+  };
+}}}
+
+ +

Class template + object_operators observer functions

+
+object operator()() const;
+template <class A0>
+object operator()(A0 const&) const;
+template <class A0, class A1>
+object operator()(A0 const&, A1 const&) const;
+...
+template <class A0, class A1,...class An>
+object operator()(A0 const& a1, A1 const& a2,...An const& aN) const;
+
+ +
+
Effects: + call<object>(object(*static_cast<U*>(this)).ptr(), a1, + a2,...aN)
+
+
+operator bool_type() const;
+
+ +
+
Effects: Tests truth value of *this.
+ +
Returns: + call<object>(object(*static_cast<U*>(this)).ptr(), a1, + a2,...aN)
+
+
+proxy<const_object_attribute> attr(char const* name) const;
+proxy<object_attribute> attr(char const* name);
+
+ +
+
Requires: name is an ntbs.
+ +
Effects: accesses the named attribute of + *this.
+ +
Returns: a proxy object which binds + object(*static_cast<U*>(this)) as its target, and + name as its key.
+
+
+template <class T>
+proxy<const_object_item> operator[](T const& key) const;
+template <class T>
+proxy<object_item> operator[](T const& key);
+
+ +
+
Effects: accesses the item of *this indicated + by key.
+ +
Returns: a proxy object which binds + object(*static_cast<U*>(this)) as its target, and + object(key) as its key.
+
+
+template <class T, class V>
+proxy<const_object_slice> slice(T const& start; start, V const& finish) const
+template <class T, class V>
+proxy<object_slice> slice(T const& start; start, V const& finish);
+
+ +
+
Effects: accesses the slice of *this indicated + by std::make_pair(object(start), object(finish)).
+ +
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.
+
+ + +

Class object

+ +

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++.

+ +

Class object + synopsis

+
+namespace boost { namespace python { namespace api
+{
+  class object : public object_operators<object>
+  {
+   public:
+      object();
+
+      object(object const&);
+      
+      template <class T>
+      explicit object(T const& x);
+
+      ~object();
+
+      object& operator=(object const&); 
+
+      PyObject* ptr() const;
+  };
+}}}
+
+ +

Class object + constructors and destructor

+
+object();
+
+ +
+
Effects: Constructs an object managing a reference to the + Python None object.
+ +
Throws: nothing.
+
+
+template <class T>
+explicit object(T const& x);
+
+ +
+
Effects: converts x to python and manages a + reference to it.
+ +
Throws: error_already_set and sets a Python + TypeError exception if no such conversion is + possible.
+
+
+~object();
+
+ +
+
Effects: decrements the reference count of the + internally-held object.
+
+ +

Class object + modifiers

+
+object& operator=(object const& rhs); 
+
+ +
+
Effects: increments the reference count of the object held + by rhs and decrements the reference count of the object + held by *this.
+
+ +

Class object + observers

+
+PyObject* ptr() const;
+
+ +
+
Returns: a pointer to the internally-held Python + object.
+
+ + +

Class template proxy

+ +

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.

+ +

Class template proxy + synopsis

+
+namespace boost { namespace python { namespace api
+{
+  template <class Policies>
+  class proxy : public object_operators<proxy<Policies> >
+  {
+   public:
+      operator object() const;
+
+      proxy const& operator=(proxy const&) const;
+      template <class T>
+      inline proxy const& operator=(T const& rhs) const;
+      
+      void del() const;
+
+      template <class R>
+      proxy operator+=(R const& rhs);
+      template <class R>
+      proxy operator-=(R const& rhs);
+      template <class R>
+      proxy operator*=(R const& rhs);
+      template <class R>
+      proxy operator/=(R const& rhs);
+      template <class R>
+      proxy operator%=(R const& rhs);
+      template <class R>
+      proxy operator<<=(R const& rhs);
+      template <class R>
+      proxy operator>>=(R const& rhs);
+      template <class R>
+      proxy operator&=(R const& rhs);
+      template <class R>
+      proxy operator|=(R const& rhs);
+  };
+}}}
+
+ +

Class template proxy + observer functions

+
+operator object() const;
+
+ +
+
Effects: applies + Policies::get(target, key + ) with the proxy's target and key objects.
+
+ +

Class template proxy + modifier functions

+
+proxy const& operator=(proxy const& rhs) const;
+template <class T>
+inline proxy const& operator=(T const& rhs) const;
+
+ +
+
Effects: + Policies::set(target, key + , object(rhs)) with the proxy's target and key + objects.
+
+
+template <class R>
+proxy operator+=(R const& rhs);
+template <class R>
+proxy operator-=(R const& rhs);
+template <class R>
+proxy operator*=(R const& rhs);
+template <class R>
+proxy operator/=(R const& rhs);
+template <class R>
+proxy operator%=(R const& rhs);
+template <class R>
+proxy operator<<=(R const& rhs);
+template <class R>
+proxy operator>>=(R const& rhs);
+template <class R>
+proxy operator&=(R const& rhs);
+template <class R>
+proxy operator|=(R const& rhs);
+
+ +
+
Effects: for a given operator@=, + object(*this) @= rhs;
+
Returns: *this
+
+
+void del() const;
+
+ +
+
Effects: + Policies::del(target, key + ) with the proxy's target and key objects.
+
+ + +

Functions

+
+template <class T>
+void del(proxy<T> const& x);
+
+ +
+
Effects: x.del()
+
+
+
+template<class L,class R> bool operator>(L const&l,R const&r);
+template<class L,class R> bool operator>=(L const&l,R const&r);
+template<class L,class R> bool operator<(L const&l,R const&r);
+template<class L,class R> bool operator<=(L const&l,R const&r);
+template<class L,class R> bool operator==(L const&l,R const&r);
+template<class L,class R> bool operator!=(L const&l,R const&r);
+
+ +
+
Effects: returns the result of applying the operator to + object(l) and object(r), respectively, in + Python.
+
+
+
+template<class L,class R> object operator+(L const&l,R const&r);
+template<class L,class R> object operator-(L const&l,R const&r);
+template<class L,class R> object operator*(L const&l,R const&r);
+template<class L,class R> object operator/(L const&l,R const&r);
+template<class L,class R> object operator%(L const&l,R const&r);
+template<class L,class R> object operator<<(L const&l,R const&r);
+template<class L,class R> object operator>>(L const&l,R const&r);
+template<class L,class R> object operator&(L const&l,R const&r);
+template<class L,class R> object operator^(L const&l,R const&r);
+template<class L,class R> object operator|(L const&l,R const&r);
+
+ +
+
Effects: returns the result of applying the operator to + object(l) and object(r), respectively, in + Python.
+
+
+
+template<class R> object& operator+=(object&l,R const&r);
+template<class R> object& operator-=(object&l,R const&r);
+template<class R> object& operator*=(object&l,R const&r);
+template<class R> object& operator/=(object&l,R const&r);
+template<class R> object& operator%=(object&l,R const&r);
+template<class R> object& operator<<=(object&l,R const&r)
+template<class R> object& operator>>=(object&l,R const&r);
+template<class R> object& operator&=(object&l,R const&r);
+template<class R> object& operator^=(object&l,R const&r);
+template<class R> object& operator|=(object&l,R const&r);
+
+ +
+
Effects: assigns to l the result of applying the + corresponding Python inplace operator to l and + object(r), respectively.
+ +
Returns: l.
+
+ +

Example

+ Python code: +
+def sum_items(seq):
+   result = 0
+   for x in seq:
+      result += x
+   return result
+
+ C++ version: +
+object sum_items(object seq)
+{
+   object result = object(0);
+   for (int i = 0; i < seq.attr("__len__")(); ++i)
+      result += seq[i];
+   return result;
+}
+
+ +

Revised + + 02 October, 2002 + +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ + +