Chapter 2. High Level Components

Содержание

<<boost/python/class.hpp>>определяет интерфейс, через который пользователи выставляют свои классы C++ на Python. В ней декларируется шаблон класса<class_>, который параметризуется по типу класса. В нем также представлены шаблоны<init>,<optional>и<bases>классов полезности, которые используются в сочетании с<class_>.

<<boost/python/class_fwd.hpp>>содержит переднюю декларацию шаблона<class_>класса.

Class template `class_<T, Bases, HeldType, NonCopyable>`

HeldType Semantics
Class template class_ synopsis
Class template class_ constructors
Class template class_ modifier functions

Создает класс Python, связанный с пройденным типом C++ в качестве первого параметра. Хотя он имеет четыре параметра шаблона, требуется только первый. Три необязательных аргумента могут быть предоставленыв любом порядке.Усиление. Python определяет роль аргумента по его типу.

Параметр шаблона	Требования	Семантика	по умолчанию
<`T`>	Тип класса.	Завернутый класс
Базы	Специализацияоснований<...>, которая определяет ранее открытые базовые классы C++<`T`>.	Регистрирует<`from_python`>преобразования из обернутых<`T`>экземпляров в каждый из его открытых прямых и косвенных оснований. Для каждого полиморфного основания<`B`>регистрирует преобразования из косвенно удерживаемых обернутых<`B`>экземпляров в<`T`>.	базы<>
HeldType	Должен быть<`T`>, класс, полученный из<`T`>, или, для которого<`pointee<HeldType>::type`>является<`T`>или классом, полученным из<`T`>.	Указывает тип, который фактически встроен в объект Python, обертывающий<`T`>экземпляр, когда<`T`>конструктор называется или когда<`T`>или<`T*`>преобразуется в Python без использованияptr,<`ref`>илиCall Policies, таких какreturn_internal_reference. Подробнее ниже.	<`T`>
Некопируемый	В случае поставки должно быть<`boost::noncopyable`> .	Подавляет автоматическую регистрацию<`to_python`>конверсий, которые копируют<`T`>экземпляров. Необходим, когда<`T`>не имеет общедоступного конструктора копий.	Неуказанный тип, кроме бустера::некопируемый.

HeldType Semantics

Если HeldType является производным от<T>, его открытый конструктор(ы) должен принять первоначальный аргумент<PyObject*>, который ссылается на объект Python, который содержит экземпляр HeldType, как показано в этом примере. Этот аргумент не включен вinit-выражение, переданноеdef (init_expr), ниже, и не передается явно пользователями, когда создаются экземпляры Python<T>. Эта идиома позволяет виртуальным функциям C++, которые будут переопределены в Python, получить доступ к объекту Python, чтобы можно было использовать метод Python. Повышаю. Python автоматически регистрирует дополнительные преобразователи, которые позволяют передавать завернутые экземпляры<T>для завернутых функций C++, ожидающих аргументов HeldType.
Потому что буст. Python всегда позволяет передавать завернутые экземпляры<T>вместо аргументов HeldType, указывая умный указатель для HeldType, что позволяет пользователям передавать экземпляры Python<T>, где ожидается умный указатель на T. Умные указатели, такие как<std::auto_ptr<>>или<boost::shared_ptr<>>, которые содержат вложенный тип<element_type>, обозначающий референтный тип, поддерживаются автоматически; дополнительные умные указатели могут поддерживаться специализацией<pointee<HeldType>>.
Как и в случае 1 выше, когда HeldType является умным указателем на класс, полученный из<T>, первоначальный аргумент<PyObject*>должен быть предоставлен всеми открытыми конструкторами HeldType.
За исключением случаев 1 и 3, пользователи могут необязательно указать, что T сам инициализируется с аналогичным исходным аргументом<PyObject*>, специализируясь наимеет_back_reference.

Class template `class_` synopsis

namespace boost { namespace python
{
template <class T
    , class Bases = bases<>
          , class HeldType = T
          , class NonCopyable = unspecified
         >
class class_ : public object
{
  // Constructors with default __init__
  class_(char const* name);
  class_(char const* name, char const* docstring);
  // Constructors, specifying non-default __init__
  template <class Init>
  class_(char const* name, Init);
  template <class Init>
  class_(char const* name, char const* docstring, Init);
  // Exposing additional __init__ functions
  template <class Init>
  class_& def(Init);
  // defining methods
  template <class F>
  class_& def(char const* name, F f);
  template <class Fn, class A1>
  class_& def(char const* name, Fn fn, A1 const&);
  template <class Fn, class A1, class A2>
  class_& def(char const* name, Fn fn, A1 const&, A2 const&);
  template <class Fn, class A1, class A2, class A3>
  class_& def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&);
  // declaring method as static
  class_& staticmethod(char const* name);
  // exposing operators
  template <unspecified>
  class_& def(detail::operator_<unspecified>);
  // Raw attribute modification
  template <class U>
  class_& setattr(char const* name, U const&);
  // exposing data members
  template <class D>
  class_& def_readonly(char const* name, D T::*pm);
  template <class D>
  class_& def_readwrite(char const* name, D T::*pm);
  // exposing static data members
  template <class D>
  class_& def_readonly(char const* name, D const& d);
  template <class D>
  class_& def_readwrite(char const* name, D& d);
  // property creation
  template <class Get>
  void add_property(char const* name, Get const& fget, char const* doc=0);
  template <class Get, class Set>
  void add_property(
      char const* name, Get const& fget, Set const& fset, char const* doc=0);
  template <class Get>
  void add_static_property(char const* name, Get const& fget);
  template <class Get, class Set>
  void add_static_property(char const* name, Get const& fget, Set const& fset);
  // pickle support
  template <typename PickleSuite>
  self& def_pickle(PickleSuite const&);
  self& enable_pickling();
};
}}

Class template `class_` constructors

class_(char const* name);
class_(char const* name, char const* docstring);
template <class Init>
class_(char const* name, Init init_spec);
template <class Init>
class_(char const* name, char const* docstring, Init init_spec);

Requires

Имяntbs, которое соответствует правилам именования идентификаторов Python. Если докстринг поставляется, он должен бытьntbs. Если<init_spec>подается, то это должна быть либо специальная постоянная перечисления<no_init>, либоinit-выражение, совместимое с<T>.

Effects

Построение объекта<class_>с поднятием. Класс расширений Python с именем. Названный атрибуттекущего объемасвязан с новым классом расширения.

При поставке значение докструн привязано к<__doc__>атрибуту класса расширения.
Если<init_spec>является<no_init>, генерируется специальная<__init__>функция, которая всегда вызывает исключение Python. В противном случае<this->def(init_spec)>называется.
Если<init_spec>не подается,<this->def(init<>())>вызывается.

Rationale

Позволяя пользователю указать аргументы конструктора в<class_<>>конструктор помогает ей избежать распространенных ошибок времени выполнения, которые возникают в результате вызова обернутых функций-членов без раскрытия функции<__init__>, которая создает необходимый экземпляр<T>. Типы, которые не могут быть построены по умолчанию, вызовут ошибку времени компиляции, если не поставляется<Init>. Пользователь должен всегда предоставлять имя, так как в настоящее время не существует портативного способа получения текста имени класса из его типа.

Class template `class_` modifier functions

template <class Init>
class_& def(Init init_expr);

Requires: <init_expr>является результатомinit-выражения, совместимого с<T>.
Effects: Для каждогодействительного префикса<P>из<Init>добавляется<__init__(...)>перегрузка функции в класс расширения, принимающий P в качестве аргументов. Каждая сгенерированная перегрузка создает объект HeldType в соответствии с описанной выше семантикой, используя копию политики вызова init_expr. Если самый длинныйдействительный префиксInit содержит N типов и init_expr содержит M ключевых слов, начальная последовательность ключевых слов используется для всех, кроме первых N - M аргументов каждой перегрузки.
Returns: <*this>
Rationale: Позволяет пользователям легко представить конструктор класса на Python.

template <class F>
class_& def(char const* name, Fn fn);
template <class Fn, class A1>
class_& def(char const* name, Fn fn, A1 const& a1);
template <class Fn, class A1, class A2>
class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2);
template <class Fn, class A1, class A2, class A3>
class_& def(char const* name, Fn fn, A1 const& a1, A2 const& a2, A3 const& a3);

Requires

Имяntbs, которое соответствует правилам именования идентификаторов Python. Если a1 является результатомперегрузки-диспетчеризации-экспрессии, допускается только вторая форма, и fn должен быть указателем для функции или указателем для функции члена, чьяаритмиясовпадает с максимальной аритмией A1.

Эффекты:Для каждого префикса<P>из<Fn>последовательности типов аргументов, начиная с того, длина которого составляет<A1>'sминимальной плотности, добавляется<name(...)>метод перегрузки в класс расширения. Каждая сгенерированная перегрузка вызывает экспрессию вызова a1 с<P>, используя копию политик вызова a1. Если самый длинный действительный префикс<A1>содержит<N>типов и a1 содержит<M>ключевые слова, начальная последовательность ключевых слов используется для всех, кроме первых<N-M>аргументов каждой перегрузки.

В противном случае строится единый способ перегрузки вокруг fn, который не должен быть нулевым:

Если fn является указателем функции, его первым аргументом должна быть форма U, U cv&, U cv*, или U cv* const&, где T* является конвертируемым в U*, и a1-a3, если поставляется, может быть выбран в любом порядке из таблицы ниже.
В противном случае, если fn является указателем функции члена, его целью должен быть T или один из его общедоступных базовых классов, и a1-a3, если он поставляется, может быть выбран в любом порядке из таблицы ниже.

В противном случае Fn должен быть [получен из]объекта, и a1-a2, если он поставляется, может быть выделен в любом порядке из первых двух строк таблицы ниже. Чтобы быть полезным, fn должен бытьвызывающим.

докстринг

Значение будет привязано к атрибуту __doc__ результирующей перегрузки метода. Если более ранняя перегрузка поставляла докструнку, к ней прилагаются два новых символа линии и новая докструнка.


Любыеntbs
	МодельCallPolicies	Копия будет использоваться в качестве политики вызова результирующего метода перегрузки.
Ключевые слова	Результат выраженияключевого слова, указывающего не больше аргументов, чемarityfn.	Копия будет использоваться в качестве политики вызова результирующего метода перегрузки.

Returns

<*this>

class_& staticmethod(char const* name);

Requires: Имяntbs, которое соответствует правилам именования идентификаторовPythonи соответствует методу, перегрузки которого были определены.
Effects: Заменяет существующий названный атрибут<x>результатом вызова<staticmethod(x)>в Python. Указывает, что соответствующий метод является статическим и, следовательно, не будет передан объектный экземпляр. Это эквивалентно утверждению Python:

setattr(self, name, staticmethod(getattr(self, name)))

Note: Попытка вызвать def (имя, ...) после вызова staticmethod (имя) подниметОшибку времени выполнения.
Returns: <*this>

template <unspecified>
class_& def(detail::operator_<unspecified>);

Effects: Добавляет Pythonспециальный метод, как описаноздесь.
Returns: <*this>

template <class U>
class_& setattr(char const* name, U const& u);

Requires

Имя - этоntbs, которое соответствует правилам именования идентификаторов Python.

Effects

Преобразует<u>в Python и добавляет его в словарь атрибутов класса расширений:

PyObject_SetAttrString(this->ptr(), name, object(u).ptr());

Returns

<*this>

template <class Get>
void add_property(char const* name, Get const& fget, char const* doc=0);
template <class Get, class Set>
void add_property(
      char const* name, Get const& fget, Set const& fset, char const* doc=0);

Requires: Имя - этоntbs, которые соответствуют правилам именования идентификаторов Python.
Effects: Создает новый экземпляр класса Python, передавая<object(fget)>(и<object(fset)>во второй форме) с (необязательной) докстрингом<doc>своему конструктору, затем добавляет это свойство к строящемуся объекту класса Python с заданным именем атрибута.
Returns: <*this>
Rationale: Позволяет пользователям легко выставлять функции, которые могут быть вызваны из Python с синтаксисом доступа к атрибутам.

template <class Get>
void add_static_property(char const* name, Get const& fget);
template <class Get, class Set>
void add_static_property(char const* name, Get const& fget, Set const& fset);

Requires: Имя - этоntbs, которое соответствует правилам именования идентификаторов Python.
Effects: Создает объект Boost.Python.StaticProperty, передавая<object(fget)>(и<object(fset)>во второй форме) своему конструктору, затем добавляет это свойство в строящийся класс Python с заданным именем атрибута. StaticProperty - это особый подкласс класса свойств Python, который можно назвать без первоначального самоаргумента.
Returns: <*this>
Rationale: Позволяет пользователям легко выставлять функции, которые могут быть вызваны из Python со статическим синтаксисом доступа к атрибутам.

template <class D>
class_& def_readonly(char const* name, D T::*pm, char const* doc=0);
template <class D>
class_& def_readonly(char const* name, D const& d);

Requires

Имя - этоntbs, которое соответствует правилам именования идентификаторов Python.<doc>также являетсяntbs.

Effects

this->add_property(name, make_getter(pm), doc);

this->add_static_property(name, make_getter(d));

соответственно.

Returns

<*this>

Rationale

Позволяет пользователям легко разоблачать элемент данных класса или бесплатную переменную, чтобы ее можно было проверить с помощью естественного синтаксиса.

template <class D>
class_& def_readwrite(char const* name, D T::*pm, char const* doc=0);
template <class D>
class_& def_readwrite(char const* name, D& d);

Effects

this->add_property(name, make_getter(pm), make_setter(pm), doc);

this->add_static_property(name, make_getter(d), make_setter(d));

соответственно.

Returns

<*this>

Rationale

Позволяет пользователям легко разоблачать данные класса или бесплатный переменный элемент, чтобы его можно было проверить и установить из Python с естественным синтаксисом.

template <typename PickleSuite>
class_& def_pickle(PickleSuite const&);

Requires: PickleSuite должен быть публично получен изpickle_suite.
Effects: Определяет правовую комбинацию специальных атрибутов и методов: __getinitargs__, __getstate__, __setstate__, __getstate_manages_dict__, __safe_for_unpickling__, __reduce__
Returns: <*this>
Rationale: Обеспечиваетпростой в использовании высокоуровневый интерфейсдля установки полнойподдержки огурцовдля класса обертывания. Пользователь защищен проверками согласованности времени компиляции.

class_& enable_pickling();

Effects: Метод __reduce__ и атрибут __safe_for_unpickling__.
Returns: <*this>
Rationale: Легкая альтернатива def_pickle(). Позволяет реализовать поддержку пикселей от Python.

Class template bases<T1, T2, ...TN>

Class template bases synopsis

Последовательность MPL, которая может быть использована в class_<...>инстанциациях, указывает на список базовых классов.

Class template bases synopsis

namespace boost { namespace python
{
  template <T1 = unspecified,...Tn = unspecified>
  struct bases
  {};
}}

Examples

Объявление класса C++:

class Foo : public Bar, public Baz
{
 public:
   Foo(int x, char const* y);
   Foo(double);
   std::string const& name() { return m_name; }
   void name(char const*);
   double value; // public data
 private:
   ...
};

соответствующего повышения. Класс расширения Python может быть создан с помощью:

using namespace boost::python;
class_<Foo,bases<Bar,Baz> >("Foo",
          "This is Foo's docstring."
          "It describes our Foo extension class",
          init<int,char const*>(args("x","y"), "__init__ docstring")
          )
   .def(init<double>())
   .def("get_name", &Foo::get_name, return_internal_reference<>())
   .def("set_name", &Foo::set_name)
   .def_readwrite("value", &Foo::value);

Статья Chapter 2. High Level Components раздела Boost.Python Reference Manual Boost.Python Reference Manual может быть полезна для разработчиков на c++ и boost.

Chapter 2. High Level Components

Boost , Boost.Python Reference Manual , Boost.Python Reference Manual

Boost C++ Libraries

Chapter 2. High Level Components

boost/python/class.hpp

Introduction

Class template `class_<T, Bases, HeldType, NonCopyable>`

HeldType Semantics

Class template `class_` synopsis

Class template `class_` constructors

Class template `class_` modifier functions

Class template bases<T1, T2, ...TN>

Class template bases synopsis

Examples