C++ Boost

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.

弳撻࣐ython攏㵄碗 object 찆䏠閥ࡣ ΪKᜃ┘⎊풀5⩕ң衲gument-dependent lookup㩉ϣ썊 법߼code>object樒嵄ͨӃԋˣ縐ϳ揖Ί̢㬍 ˹Ӑբ餾߶蒥Ӛ namespace boost::python::api㬍 ⢇Ҡobject ͨ齍 usingɹ÷㨵sing-declaration㩼/i> 弈렼code>namespace boost::pythonᣍ

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:

һ趀Ѝ㬍 OڴﵽԚPython疆챭䯊햐ʡ”˷ҽ儐繻ᣍ

>>> x[:-1]
>>> x[::-1]
C++ equivalent:

刐組C++㺼/p>

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.

const object Њ䐔烎ʊዹ᭏ֵIJ߂ԡ㍊

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.
Ҫdz㺼/b> key ʇ趠ntbs᣼/dt>
黣꼯b> 烎ʠtarget uזΪ key 儊䐔᣼/dt>
絻أ꼯b> һ趹܀튴烎ʽṻ傻 object
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set

Class attribute_policies

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

龜䐔 object Њ䐔烎ʊዹ᭏ֵIJ߂ԡ㍊

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.
Ҫdz㺼/b> key ʇ趠ntbs᣼/dt>
黣꼯b> target uזΪ key 儊䐔ɨփΪ value᣼/dt>
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set
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.
Ҫdz㺼/b> key ʇ趠ntbs.
黣꼯b> ɾ㽠target uזΪ key 儊䐔᣼/dt>
ŗ㶣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set

Class const_item_policies

The policies which are used for proxies representing an item access (via the Python bracket operators []) to a const object.

龜ͨ齊ython罀躅ԋˣ綆[]㩍 攠const object Ќ兒烎ʊዹ᭏ֵIJ߂ԡ㍊

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.
黣꼯b> 烎ʠtarget Ӊ key ָ樵Č兒ᣍ
絻أ꼯b> һ趹܀팵Ŀ烎ʽṻ儠object
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set

Class item_policies

The policies which are used for proxies representing an item access (via the Python bracket operators []) to a mutable object.

龜ͨ齊ython罀躅ԋˣ綆[]㩍 政ɱ䐔 object Ќ兒烎ʊዹ᭏ֵIJ߂ԡ㍊

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.
黣꼯b> target Ӊ key ָ樵Č兒ɨփΪ value᣼/dt>
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set
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.
黣꼯b> ɾ㽠target Ӊ key ָ樵Č兒᣼/dt>
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set

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.

龜ͨ齷ֆ췻 [x:y]㩍 攠const object ֆ췃Ίʱ˹᭏ֵIJ߂ԡ㍊

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.
黣꼯b> 烎ʠtarget Ӊ key ָ樵ķֆ졣
絻أ꼯b> һ趹܀Ƭ烎ʽṻ儠object
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set

Class slice_policies

The policies which are used for proxies representing an slice access to a mutable object.

龜䐔 object ֆ췃Ίʱ˹᭏ֵIJ߂ԡ㍊

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.
黣꼯b> target Ӊ key ָ樵ķֆ쉨փΪ value᣼/dt>
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set
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.
黣꼯b> ɾ㽠target Ӊ key ָ樵ķֆ졣
ŗҬ㣣꼯b> ȧ黑PythonҬ㣣씲ŗ㶠error_already_set

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.

բʇ object 儻造㬍 ˼儴ꀭ㨼code>proxy㩄㰥ͨ㣌ṩ髹ⵄ퓿ڣꍊ 촱ؐ딚 ֐樒嵄㉔ắʽꍔˋ㷻ᣍ ˼億㰥⎊code>U ҪdzΪ object_operators<U> 儅ɉꀠᣍ ʵ슉ϓu粻Ӧ胖ὓʹӃ脹࣬բ/載ĵ劇ҲΪ˼ϲ object 찆䴺-̡驖ؒ굄퓿ڡ㍊

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)
黣꼯b> ⢶Ƞ*this truth ֵ᣼/dt>
絻أ꼯b> 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.
Ҫdz㺼/b> name ʇ趠ntbs᣼/dt>
黣꼯b> 烎ʠ*this uΪ name 儊䐔ᣍ
絻أ꼯b> һ躎㶨 target Ϊ object(*static_cast<U*>(this))㬍 key Ϊ name 儴ꀭ攏㡣 ᣼/dt>
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.
黣꼯b> 烎ʠ*this Ӊ key ָ÷儌兒᣼/dt>
絻أ꼯b> һ躎㶨 target Ϊ object(*static_cast<U*>(this))㬍 key Ϊ object(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.
黣꼯b> 烎ʠ*this Ӊ std::make_pair(object(start), object(finish)) ָ÷儷ֆ졣
絻أ꼯b> һ躎㶨 target Ϊ object(*static_cast<U*>(this))㬍 key Ϊ std::make_pair(object(start), object(finish)) 儴ꀭ攏㡣

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.

Ŀ儊Ljaobject Ʉܵ؏ḶPythonᤁ բ֖᭴ͨ㣻ᒔϱԚPython֐һѹ儷튽ԋӚC++ᣍ object 儴㲿疽ӿڊǓɆ丰 object_operators<object>㬍 찒됩הӉꯊa>̡駔ģ썊 ˼C漶蒥Ӛբ趍玄쾖㍊

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.
黣꼯b> 鷫쒻趶ԏ㣬膠ԏ㹜-һ趍 ָϲPython None 攏㵄ҽӃ᣼/dt>
ŗҬ㣣꼯b> Ξ᣼/dt>
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.
黣꼯b> x ת뻵ython㬍 ⢹܀풻趶ԋ쵄ҽӃ᣼/dt>
ŗ㶣꼯b> ȧ黎޷軫բ֖ת뻣썊 Բŗ㶠error_already_set㬍 ⢉薃һ趠Python TypeError Ҭ㣡㼯dt>
~object();
Effects: decrements the reference count of the internally-held object.
黣꼯b> 坼儚⿳֓ԏ㵄ҽӃ솊

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.
黣꼯b> 地格code>rhs ˹㖓ԏ㵄ҽӃ솊 ⢵ݼ封code>*this ˹㖓ԏ㵄ҽӃ솊

Class object observers

PyObject* ptr() const;
Returns: a pointer to the internally-held Python object.
絻أ꼯b> һ趖蕫㬖菲Ě⿳֓Đython攏㡣 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.

胄㰥Ӊᾎĵʶ儸癤⟂Ԋ啥믣썊 Ŀ儊NJ取攠object 儊䐔ᢌ兒㬺ͷֆ췃Ίᣍ ˼ᣴ旅һ趀ЍΪ 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.
黣꼯b> Ӄ龜 target ꍠkey 攏㓦Ӄ Policies::get(target, key )

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.
黣꼯b> Ӄ龜 target ꍠkey 攏㓦Ӄ Policies::set(target, key , object(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);
template <class R>
proxy operator|=(R const& rhs);
Effects: for a given operator@=, object(*this) @= rhs;
Returns: *this
黣꼯b> 攓ڸ趨 operator@=㬍 object(*this) @= rhs;
絻أ꼯b> *this
void del() const;
Effects: Policies::del(target, key ) with the proxy's target and key objects.
黣꼯b> Ӄ龜 target ꍠkey 攏㓦Ӄ Policies::del(target, key )

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.
黣꼯b> 皰෵똶Ԡ object(l)object(r) Ԛ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.
絻أ꼯b> 皰෵똶ԍ object(l)object(r) ԚPython֐ӦӃԋˣ綿Ľṻ᣼/dt>

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.
黣꼯b> 皰ཫ l 賒廑攠 lobject(r) ӦӃϠӦ儐ythonؔˋ㷻㨩nplace operator㩵Ľṻᣍ
絻أ꼯b> 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.