###

# 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
  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_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++. 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 13 January, 2006

© Copyright Dave Abrahams 2006.