boost/python/object.hpp

はじめに

汎用的な Python のオブジェクトラッパクラス object および関連クラスをエクスポートする。引数依存の探索および object が定義する汎化演算子に絡む潜在的な問題を避けるため、これらの機能はすべて名前空間 boost::python::api で定義され、object は using 宣言で名前空間 boost::python へインポートされている。

型

slice_nil

class slice_nil

class slice_nil;
static const _ = slice_nil();

次のように、Python のスライス式で添字を省く効果を得る型。

>>> x[:-1]
>>> x[::-1]

C++ で等価なことをするには、

x.slice(_,-1)
x[slice(_,_,-1)]

クラス

const_attribute_policies クラス

struct const_attribute_policies

const object への属性アクセスを表現するプロキシのためのポリシー。

const_attribute_policies クラスの概要

namespace boost { namespace python { namespace api
{
  struct const_attribute_policies
  {
      typedef char const* key_type;
      static object get(object const& target, char const* key);
  };
}}}

const_attribute_policies クラスの静的関数

static object get(object const &target, char const *key)

要件

key が ntbs。

効果

target の属性 key にアクセスする。

戻り値

属性アクセスの結果を管理する object。

例外

error_already_set -- Python の例外が送出した場合。

attribute_policies クラス

struct attribute_policies : const_attribute_policies

変更可能な object への属性アクセスを表現するプロキシのためのポリシー。

attribute_policies クラスの概要

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

attribute_policies クラスの静的関数

static object const &set(object const &target, char const *key, object const &value)

要件

key が ntbs。

効果

target の属性 key に value を設定する。

例外

error_already_set -- Python の例外が送出した場合。

static void del(object const &target, char const *key)

要件

key が ntbs。

効果

target の属性 key を削除する。

例外

error_already_set -- Python の例外が送出した場合。

const_objattribute_policies クラス

struct const_objattribute_policies

const object へのアクセス属性（属性名を const object で与える場合）を表現するプロキシのためのポリシー。

const_objattribute_policies クラスの概要

namespace boost { namespace python { namespace api
{
  struct const_objattribute_policies
  {
      typedef object const& key_type;
      static object get(object const& target, object const& key);
  };
}}}

const_objattribute_policies クラスの静的関数

static object get(object const &target, object const &key)

要件

key が文字列を保持する object。

効果

target の属性 key にアクセスする。

戻り値

属性アクセスの結果を管理する object。

例外

error_already_set -- Python の例外が送出した場合。

objattribute_policies クラス

struct objattribute_policies : const_objattribute_policies

変更可能な object へのアクセス属性（属性名を const object で与える場合）を表現するプロキシのためのポリシー。

objattribute_policies クラスの概要

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

objattribute_policies クラスの静的関数

static object const &set(object const &target, object const &key, object const &value)

要件

key が文字列を保持する object。

効果

target の属性 key に value を設定する。

例外

error_already_set -- Python の例外が送出した場合。

static void del(object const &target, object const &key)

要件

key が文字列を保持する object。

効果

target の属性 key を削除する。

例外

error_already_set -- Python の例外が送出した場合。

const_item_policies クラス

struct const_item_policies

const object への（Python の角括弧演算子 [] による）要素アクセスを表現するプロキシのためのポリシー。

const_item_policies クラスの概要

namespace boost { namespace python { namespace api
{
  struct const_item_policies
  {
      typedef object key_type;
      static object get(object const& target, object const& key);
  };
}}}

const_item_policies クラスの静的関数

static object get(object const &target, object const &key)

効果

target の key で指定する要素へアクセスする。

戻り値

属性アクセスの結果を管理する object。

例外

error_already_set -- Python の例外が送出した場合。

item_policies クラス

struct item_policies : const_item_policies

変更可能な object への（Python の角括弧演算子 [] による）要素アクセスを表現するプロキシのためのポリシー。

item_policies クラスの概要

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

item_policies クラスの静的関数

static object const &set(object const &target, object const &key, object const &value)

効果

target の key で指定する要素を value に設定する。

例外

error_already_set -- Python の例外が送出した場合。

static void del(object const &target, object const &key)

効果

target の key で指定する要素を削除する。

例外

error_already_set -- Python の例外が送出した場合。

const_slice_policies クラス

struct const_slice_policies

const object への（Python のスライス表記 [x:y] による）スライスアクセスを表現するプロキシのためのポリシー。

const_slice_policies クラスの概要

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

const_slice_policies クラスの静的関数

static object get(object const &target, key_type const &key)

効果

target の key で指定するスライスへアクセスする。

戻り値

スライスアクセスの結果を管理する object。

例外

error_already_set -- Python の例外が送出した場合。

slice_policies クラス

struct slice_policies : const_slice_policies

変更可能な object へのスライスアクセスを表現するプロキシのためのポリシー。

slice_policies クラスの概要

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

slice_policies クラスの静的関数

static object const &set(object const &target, key_type const &key, object const &value)

効果

target の key で指定するスライスに value を設定する。

例外

error_already_set -- Python の例外が送出した場合。

static void del(object const &target, key_type const &key)

効果

target の key で指定するスライスを削除する。

例外

error_already_set -- Python の例外が送出した場合。

object_operators<U> クラステンプレート

template<class U>
class object_operators

これは object およびその proxy テンプレートの基底クラスであり、共通のインターフェイス（メンバ関数およびクラス本体内で定義しなければならない演算子）を提供する。テンプレート引数 U は object_operators<U> の派生型という想定である。実際にはユーザはこのクラスを直接使用すべきではないが、object とそのプロキシに対して重要なインターフェイスを提供するので、ここに記載する。

object_operators クラステンプレートの概要

namespace boost { namespace python { namespace api
{
  template <class U>
  class object_operators
  {
   public:
      // 関数呼び出し
      //
      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;

      // 真偽値のテスト
      //
      typedef unspecified bool_type;
      operator bool_type() const;

      // 属性アクセス
      //
      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&);

      // 要素アクセス
      //
      template <class T>
      proxy<const_object_item> operator[](T const& key) const;

      template <class T>
      proxy<object_item> operator[](T const& key);

      // スライシング
      //
      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_operators クラステンプレートのオブザーバ関数

template<class ...Args>
object operator()(Args const&... args) const

効果

call<object>(object(*static_cast<U*>(this)).ptr(), args)

object operator()(detail::args_proxy const &args) const

効果

タプル args で与えた引数で object を呼び出す。

object operator()(detail::args_proxy const &args, detail::kwds_proxy const &kwds) const

効果

タプル args で与えた引数と辞書 kwds で与えた名前付き引数で object を呼び出す。

operator bool_type() const

効果

*this の真偽値をテストする。

戻り値

call<object>(object(*static_cast<U*>(this)).ptr(), args)

proxy<const_object_attribute> attr(char const*) const

proxy<object_attribute> attr(char const*)

要件

name が ntbs。

効果

*this の名前 name の属性にアクセスする。

戻り値

ターゲットに object(*static_cast<U*>(this)) を、キーに name を束縛した proxy オブジェクト。

proxy<const_object_objattribute> attr(object const&) const

proxy<object_objattribute> attr(object const&)

要件

name は文字列を保持する object。

効果

*this の名前 name の属性にアクセスする。

戻り値

ターゲットに object(*static_cast<U*>(this)) を、キーに name を束縛した proxy オブジェクト。

template<class T>
proxy<const_object_item> operator[](T const &key) const

template<class T>
proxy<object_item> operator[](T const &key)

効果

*this の key が示す要素にアクセスする。

戻り値

ターゲットに object(*static_cast<U*>(this)) を、キーに object(key) を束縛した proxy オブジェクト。

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)

効果

*this の std::make_pair(object(start), object(end)) が示すスライスにアクセスする。

戻り値

ターゲットに object(*static_cast<U*>(this)) を、キーに std::make_pair(object(start), object(end)) を束縛した proxy オブジェクト。

object クラス

class object : public object_operators<object>

目的は object が可能な限り Python の変数のように振舞うことである。これにより Python で動作する式は概して C++ でも同じ方法で動作するはずである。object の大部分のインターフェイスは、基底クラス object_operators<object> とこのヘッダが定義する自由関数が提供する。

object クラスの概要

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 クラスのコンストラクタおよびデストラクタ

object()

効果

Python の None オブジェクトへの参照を管理するオブジェクトを構築する。

例外

なし。

template<class T>
explicit object(T const &x)

効果

x を Python に変換し、それへの参照を管理する。

例外

error_already_set -- 上記の変換が不可能な場合（Python の TypeError 例外を設定する）。

~object()

効果

内部で保持するオブジェクトの参照カウントを減らす。

object クラスの変更メソッド

object &operator=(object const &rhs)

効果

rhs が保持するオブジェクトの参照カウントを増やし、*this が保持するオブジェクトの参照カウントを減らす。

object クラスのオブザーバ関数

PyObject *ptr() const

戻り値

内部で保持している Python オブジェクトへのポインタ。

bool is_none() const

戻り値

(ptr() == Py_None) の結果。

proxy クラステンプレート

template<class Policies>
class proxy : public object_operators<proxy<Policies>>

object に対する属性、要素およびスライスアクセスを実装するために、このドキュメントで述べた種々のポリシー（Policies）とともにこのテンプレートをインスタンス化する。Policies::key_type 型のオブジェクトを格納する。

proxy クラステンプレートの概要

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

proxy クラステンプレートのオブザーバ関数

operator object() const

効果

Policies::get(target, key) にプロキシのターゲットオブジェクトとキーオブジェクトを適用する。

proxy クラステンプレートの変更関数

proxy const &operator=(proxy const&) const

template<class T>
inline proxy const &operator=(T const &rhs) const

効果

プロキシのターゲットオブジェクトとキーオブジェクトを使用して 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)

効果

与えられた operator@= について、object(*this) @= rhs

戻り値

*this

void del() const

効果

プロキシのターゲットオブジェクトとキーオブジェクトを使用して Policies::del(target, key)。

関数

template<class T>
void del(proxy<T> const &x)

効果

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)

効果

Python 内で演算子をそれぞれ object(l) および object(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)

template<class L, class R>
object operator|(L const &l, R const &r)

効果

Python 内で演算子をそれぞれ object(l) および object(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)

template<class R>
object &operator|=(object &l, R const &r)

効果

対応する Python の複合演算子をそれぞれ l および object(r) に適用した結果をlに代入する。

戻り値

l

inline long len(object const &obj)

効果

PyObject_Length(obj.ptr())

戻り値

オブジェクトの len()

例

Python のコード

def sum_items(seq):
   result = 0
   for x in seq:
      result += x
   return result

C++ 版

object sum_items(object seq)
{
   object result = object(0);
   for (int i = 0; i < len(seq); ++i)
      result += seq[i];
   return result;
}