Boost.Python

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

Boost C++ Libraries

Boost.Python

Header <boost/python/object.hpp>

Contents

Introduction

Types

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 template object_operators<U>

Class template object_operators synopsis

Class template object_operators observer functions

Class object

Class object synopsis

Class object constructors and destructor

Class object modifiers

Class object observers

Class template proxy

Class template proxy synopsis

Class template proxy observer functions

Class template proxy modifier functions