boost/python/object.hpp

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.

Class `slice_nil`

class slice_nil;
static const _ = slice_nil();

A type that can be used to get the effect of leaving out an index in a Python slice expression:

>>> x[:-1]
>>> x[::-1]

C++ equivalent:

x.slice(_,-1)
x[slice(_,_,-1)]

Class `const_attribute_policies`

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

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.

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_objattribute_policies`

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.

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

Class `const_objattribute_policies` static functions

static object get(object const& target, object const& key);

Requires: key is an object holding a string.
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 `objattribute_policies`

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.

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

Class `objattribute_policies` static functions

static object const& set(object const& target, object const& key, object const& value);

Requires: key is an object holding a string.
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, object const& key);

Requires: key is an object holding a string.
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.

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.

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.

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.

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`

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.

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;

      detail::args_proxy operator* () const;
      object operator()(detail::args_proxy const &args) const;
      object operator()(detail::args_proxy const &args,
                        detail::kwds_proxy const &kwds) 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*);
      proxy<const_object_objattribute> attr(object const&) const;
      proxy<object_objattribute> attr(object 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)

object operator()(detail::args_proxy const &args) const;

Effects: call object with arguments given by the tuple args

object operator()(detail::args_proxy const &args,
                  detail::kwds_proxy const &kwds) const;

Effects: call object with arguments given by the tuple args, and named arguments given by the dictionary kwds

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.

proxy<const_object_objattribute> attr(const object& name) const;
proxy<object_objattribute> attr(const object& name);

Requires: name is a object holding a string.
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++. Most of object's interface is provided by its base class object_operators<object>, and the free functions defined in this header.

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;
      bool is_none() 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

PyObject* ptr() const;

Returns: a pointer to the internally-held Python object.

bool is_none() const;

Returns: result of (ptr() == Py_None)

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.

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

long len(object const& obj);

Effects: PyObject_Length(obj.ptr())
Returns: len() of object.

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 < len(seq); ++i)
      result += seq[i];
   return result;
}