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

boost/python/object.hpp
PrevUpHomeNext

boost/python/object.hpp

Introduction
Class slice_nil
Class const_attribute_policies
Class const_attribute_policies static functions
Class attribute_policies
Class attribute_policies static functions
Class const_objattribute_policies
Class const_objattribute_policies static functions
Class objattribute_policies
Class objattribute_policies static functions
Class const_item_policies
Class const_item_policies static functions
Class item_policies
Class item_policies static functions
Class const_slice_policies
Class const_slice_policies static functions
Class slice_policies
Class slice_policies static functions
Class template object_operators
Class template object_operators observer functions
Class object
Class object constructors and destructor
Class object modifiers
Class template proxy
Class template proxy observer functions
Class template proxy modifier functions
Functions
Example

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

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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);
  };
}}}

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.

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

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. 

PyObject* ptr() const;

Returns

a pointer to the internally-held Python object. 

bool is_none() const;

Returns

result of (ptr() == Py_None)

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);
  };
}}}

operator object() const;

Effects

applies Policies::get(target, key) with the proxy's target and key objects. 

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. 

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.

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;
}
Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt

PrevUpHomeNext