Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.

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_objattribute_policies
Class const_objattribute_policies synopsis
Class const_objattribute_policies static functions
Class objattribute_policies
Class objattribute_policies synopsis
Class objattribute_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
len()
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

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

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

Class const_objattribute_policies synopsis

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.

Class objattribute_policies synopsis

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.

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*);
      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)
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.

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> 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.
inline 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;
}

Revised 27 May, 2008

© Copyright Dave Abrahams 2008.