| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| |
| <!-- Copyright David Abrahams 2006. 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) --> |
| <html> |
| <head> |
| <meta name="generator" content= |
| "HTML Tidy for Cygwin (vers 1st September 2004), see www.w3.org"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-latin-1-dos"> |
| <link rel="stylesheet" type="text/css" href="../boost.css"> |
| |
| <title>Boost.Python - <boost/python/class.hpp>, |
| <boost/python/class_fwd.hpp></title> |
| </head> |
| |
| <body link="#0000FF" vlink="#800080"> |
| <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= |
| "header"> |
| <tr> |
| <td valign="top" width="300"> |
| <h3><a href="../../../../index.htm"><img height="86" width="277" alt= |
| "C++ Boost" src="../../../../boost.png" border="0"></a></h3> |
| </td> |
| |
| <td valign="top"> |
| <h1 align="center"><a href="../index.html">Boost.Python</a></h1> |
| |
| <h2 align="center">Headers <boost/python/class.hpp>, |
| <boost/python/class_fwd.hpp></h2> |
| </td> |
| </tr> |
| </table> |
| <hr> |
| |
| <h2>Contents</h2> |
| |
| <dl class="page-index"> |
| <dt><a href="#introduction">Introduction</a></dt> |
| |
| <dt><a href="#classes">Classes</a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#class_-spec">Class template |
| <code>class_</code></a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#class_-spec-synopsis">Class <code>class_</code> |
| synopsis</a></dt> |
| |
| <dt><a href="#class_-spec-ctors">Class <code>class_</code> |
| constructors</a></dt> |
| |
| <dt><a href="#class_-spec-modifiers">Class <code>class_</code> |
| modifier functions</a></dt> |
| </dl> |
| </dd> |
| |
| <dt><a href="#bases-spec">Class template <code>bases</code></a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#bases-spec-synopsis">Class template |
| <code>bases</code> synopsis</a></dt> |
| </dl> |
| </dd> |
| </dl> |
| </dd> |
| |
| <dt><a href="#examples">Example(s)</a></dt> |
| </dl> |
| <hr> |
| |
| <h2><a name="introduction" id="introduction"></a>Introduction</h2> |
| |
| <p><code><boost/python/class.hpp></code> defines the interface |
| through which users expose their C++ classes to Python. It declares the |
| <code>class_</code> class template, which is parameterized on the class |
| type being exposed. It also exposes the <code>init</code>, |
| <code>optional</code> and <code>bases</code> utility class templates, which |
| are used in conjunction with <code>class_</code>.</p> |
| |
| <p><code><boost/python/class_fwd.hpp></code> contains a forward |
| declaration of the <code>class_</code> class template.</p> |
| |
| <h2><a name="classes" id="classes"></a>Classes</h2> |
| |
| <h3><a name="class_-spec" id="class_-spec"></a>Class template |
| <code>class_<T, <font color="#007F00">Bases, HeldType, |
| NonCopyable</font>></code></h3> |
| |
| <p>Creates a Python class associated with the C++ type passed as its first |
| parameter. Although it has four template parameters, only the first one is |
| required. The three optional arguments can actually be supplied |
| <font color="#007F00"><b>in any order</b></font>; Boost.Python determines |
| the role of the argument from its type.<br> |
| <br></p> |
| |
| <table border="1" summary="class_ template parameters"> |
| <tr> |
| <th>Template Parameter</th> |
| |
| <th>Requirements</th> |
| |
| <th>Semantics</th> |
| |
| <th>Default</th> |
| </tr> |
| |
| <tr> |
| <td><code>T</code></td> |
| |
| <td>A class type.</td> |
| |
| <td>The class being wrapped</td> |
| </tr> |
| |
| <tr> |
| <td><code><font color="#007F00">Bases</font></code></td> |
| |
| <td>A specialization of <a href= |
| "#bases-spec"><code>bases<</code>...<code>></code></a> which |
| specifies previously-exposed C++ base classes of <code>T</code><a href= |
| "#footnote_1">[1]</a>.</td> |
| |
| <td>Registers <code>from_python</code> conversions from wrapped |
| <code>T</code> instances to each of its exposed direct and indirect |
| bases. For each polymorphic base <code>B</code>, registers conversions |
| from indirectly-held wrapped <code>B</code> instances to |
| <code>T</code>.</td> |
| |
| <td><code><a href="#bases-spec">bases<></a></code></td> |
| </tr> |
| |
| <tr> |
| <td><code><font color="#007F00">HeldType</font></code></td> |
| |
| <td>Must be <code>T</code>, a class derived from <code>T</code>, or a |
| <a href="Dereferenceable.html">Dereferenceable</a> type for which |
| <code><a href= |
| "pointee.html#pointee-spec">pointee</a><HeldType>::type</code> is |
| <code>T</code> or a class derived from <code>T</code>.</td> |
| |
| <td>Specifies the type that is actually embedded in a Python object |
| wrapping a <code>T</code> instance when <code>T</code>'s constructor is |
| called or when a <code>T</code> or <code>T*</code> is converted to |
| Python without the use of <a href= |
| "http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling"> |
| <code>ptr</code></a>, <a href= |
| "http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling"> |
| <code>ref</code></a>, or <a href="CallPolicies.html">Call Policies</a> |
| such as <code><a href= |
| "return_internal_reference.html">return_internal_reference</a></code>. |
| More details <a href="#HeldType">below</a>.</td> |
| |
| <td><code>T</code></td> |
| </tr> |
| |
| <tr> |
| <td><code><font color="#007F00">NonCopyable</font></code></td> |
| |
| <td>If supplied, must be <a href= |
| "../../../utility/utility.htm#Class_noncopyable">boost::noncopyable</a>.</td> |
| |
| <td>Suppresses automatic registration of <code>to_python</code> |
| conversions which copy <code>T</code> instances. Required when |
| <code>T</code> has no publicly-accessible copy constructor.</td> |
| |
| <td>An unspecified type other than |
| <code>boost::noncopyable</code>.</td> |
| </tr> |
| </table> |
| |
| <h4><a name="HeldType" id="HeldType">HeldType Semantics</a></h4> |
| |
| <ol> |
| <li>If <code>HeldType</code> is derived from T, its exposed |
| constructor(s) must accept an initial <code>PyObject*</code> argument |
| which refers back to the Python object that contains the |
| <code>HeldType</code> instance, as shown in <a href= |
| "call_method.html#examples">this example</a>. This argument is not |
| included in the <em><a href= |
| "init.html#init-expressions">init-expression</a></em> passed to <a href= |
| "#class_-spec-modifiers"><code>def(init_expr)</code></a>, below, nor is |
| it passed explicitly by users when Python instances of <code>T</code> are |
| created. This idiom allows C++ virtual functions which will be overridden |
| in Python to access the Python object so the Python method can be |
| invoked. Boost.Python automatically registers additional converters which |
| allow wrapped instances of <code>T</code> to be passed to wrapped C++ |
| functions expecting <code>HeldType</code> arguments.</li> |
| |
| <li>Because Boost.Python will always allow wrapped instances of |
| <code>T</code> to be passed in place of <code>HeldType</code> arguments, |
| specifying a smart pointer for <code>HeldType</code> allows users to pass |
| Python <code>T</code> instances where a smart pointer-to-<code>T</code> |
| is expected. Smart pointers such as <code>std::auto_ptr<></code> or |
| <code><a href= |
| "../../../smart_ptr/shared_ptr.htm">boost::shared_ptr<></a></code> |
| which contain a nested type <code>element_type</code> designating the |
| referent type are automatically supported; additional smart pointer types |
| can be supported by specializing <a href= |
| "pointee.html#pointee-spec">pointee<HeldType></a>.</li> |
| |
| <li>As in case 1 above, when <code>HeldType</code> is a smart pointer to |
| a class derived from <code>T</code>, the initial <code>PyObject*</code> |
| argument must be supplied by all of <code>HeldType</code>'s exposed |
| constructors.</li> |
| |
| <li>Except in cases 1 and 3, users may optionally specify that T itself |
| gets initialized with a similar initial <code>PyObject*</code> argument |
| by specializing <a href= |
| "has_back_reference.html#has_back_reference-spec">has_back_reference<T></a>.</li> |
| </ol> |
| |
| <h4><a name="class_-spec-synopsis" id="class_-spec-synopsis"></a>Class |
| template <code>class_</code> synopsis</h4> |
| <pre> |
| namespace boost { namespace python |
| { |
| template <class T |
| <font color="#007F00"> , class Bases = bases<> |
| , class HeldType = T |
| , class NonCopyable = <i>unspecified</i> |
| > |
| </font> class class_ : public <a href="object.html#object-spec">object</a> |
| { |
| // 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 <<i>unspecified</i>> |
| class_& def(<a href= |
| "operators.html#operator_-spec">detail::operator_</a><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(); |
| }; |
| }} |
| </pre> |
| |
| <h4><a name="class_-spec-ctors" id="class_-spec-ctors"></a>Class template |
| <code>class_</code> constructors</h4> |
| <pre> |
| 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); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>. If <code>docstring</code> is supplied, it must be an |
| <a href="definitions.html#ntbs">ntbs</a>. If <code>init_spec</code> is |
| supplied, it must be either the special enumeration constant |
| <code>no_init</code> or an <a href= |
| "init.html#init-expressions">init-expression</a> compatible with |
| <code>T</code>.</dt> |
| |
| <dt><b>Effects:</b> Constructs a <code>class_</code> object holding a |
| Boost.Python extension class named <code>name</code>. The |
| <code>name</code>d attribute of the <a href= |
| "scope.html#introduction">current scope</a> is bound to the new extension |
| class.</dt> |
| |
| <dd> |
| <ul> |
| <li>If supplied, the value of <code>docstring</code> is bound to the |
| <code>__doc__</code> attribute of the extension class.</li> |
| |
| <li>If <code>init_spec</code> is <code>no_init</code>, a special |
| <code>__init__</code> function is generated which always raises a |
| Python exception. Otherwise, <code>this->def(init_spec)</code> is |
| called.</li> |
| |
| <li>If <code>init_spec</code> is not supplied, |
| <code>this->def(init<>())</code> is called.</li> |
| </ul> |
| </dd> |
| |
| <dt><b>Rationale:</b>Allowing the user to specify constructor arguments |
| in the <code>class_<></code> constructor helps her to avoid the |
| common run-time errors which result from invoking wrapped member |
| functions without having exposed an <code>__init__</code> function which |
| creates the requisite <code>T</code> instance. Types which are not |
| default-constructible will cause a compile-time error unless |
| <code>Init</code> is supplied. The user must always supply |
| <code>name</code> as there is currently no portable method to derive the |
| text of the class name from its type.</dt> |
| </dl> |
| |
| <h4><a name="class_-spec-modifiers" id="class_-spec-modifiers"></a>Class |
| template <code>class_</code> modifier functions</h4> |
| <pre> |
| template <class Init> |
| class_& def(Init init_expr); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>init_expr</code> is the result of an <a href= |
| "init.html#init-expressions">init-expression</a> compatible with |
| <code>T</code>.</dt> |
| |
| <dt><b>Effects:</b> For each <a href="init.html#init-expressions">valid |
| prefix</a> <em>P</em> of <code>Init</code>, adds an |
| <code>__init__(</code>...<code>)</code> function overload to the |
| extension class accepting <em>P</em> as arguments. Each overload |
| generated constructs an object of <code>HeldType</code> according to the |
| semantics described <a href="#HeldType">above</a>, using a copy of |
| <code>init_expr</code>'s <a href="CallPolicies.html">call policies</a>. |
| If the longest <a href="init.html#init-expressions">valid prefix</a> of |
| <code>Init</code> contains <em>N</em> types and <code>init_expr</code> |
| holds <em>M</em> keywords, an initial sequence of the keywords are used |
| for all but the first <em>N</em> - <em>M</em> arguments of each |
| overload.</dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Allows users to easily expose a class' constructor |
| to Python.</dt> |
| </dl><br> |
| <pre> |
| 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); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>.</dt> |
| |
| <dd> |
| <ul> |
| <li>If <code>a1</code> is the result of an <a href= |
| "overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>, |
| only the second form is allowed and fn must be a pointer to function |
| or pointer to member function whose <a href="definitions.html#arity"> |
| arity</a> is the same as A1's <a href= |
| "overloads.html#overload-dispatch-expression"><em>maximum |
| arity</em></a>. |
| |
| <dl> |
| <dt><b>Effects:</b> For each prefix <em>P</em> of |
| <code>Fn</code>'s sequence of argument types, beginning with the |
| one whose length is <code>A1</code>'s <a href= |
| "overloads.html#overload-dispatch-expression"><em>minimum |
| arity</em></a>, adds a |
| <code><em>name</em>(</code>...<code>)</code> method overload to |
| the extension class. Each overload generated invokes |
| <code>a1</code>'s call-expression with <em>P</em>, using a copy |
| of <code>a1</code>'s <a href="CallPolicies.html">call |
| policies</a>. If the longest valid prefix of <code>A1</code> |
| contains <em>N</em> types and <code>a1</code> holds <em>M</em> |
| keywords, an initial sequence of the keywords are used for all |
| but the first <em>N</em> - <em>M</em> arguments of each |
| overload.<br></dt> |
| </dl> |
| </li> |
| |
| <li>Otherwise, a single method overload is built around fn, which |
| must not be null: |
| |
| <ul> |
| <li>If fn is a function pointer, its first argument must be of |
| the form <code>U</code>, <code>U <em>cv</em>&</code>, <code>U |
| <em>cv</em>*</code>, or <code>U <em>cv</em>* const&</code>, |
| where <code>T*</code> is convertible to <code>U*</code>, and |
| <code>a1</code>-<code>a3</code>, if supplied, may be selected in |
| any order from the table below.</li> |
| |
| <li>Otherwise, if fn is a member function pointer, its target |
| must be <code>T</code> or one of its public base classes, and |
| <code>a1</code>-<code>a3</code>, if supplied, may be selected in |
| any order from the table below.</li> |
| |
| <li>Otherwise, <code>Fn</code> must be [derived from] |
| <code><a href="object.html#object-spec">object</a></code>, and |
| <code>a1-a2</code>, if supplied, may be selcted in any order from |
| the first two rows of the table below. To be useful, |
| <code>fn</code> should be <a href= |
| "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6"> |
| callable</a>.</li> |
| </ul> |
| |
| <table border="1" summary="def() optional arguments"> |
| <tr> |
| <th>Memnonic Name</th> |
| |
| <th>Requirements/Type properties</th> |
| |
| <th>Effects</th> |
| </tr> |
| |
| <tr> |
| <td>docstring</td> |
| |
| <td>Any <a href="definitions.html#ntbs">ntbs</a>.</td> |
| |
| <td>Value will be bound to the <code>__doc__</code> attribute |
| of the resulting method overload. If an earlier overload |
| supplied a docstring, two newline characters and the new |
| docstring are appended to it.</td> |
| </tr> |
| |
| <tr> |
| <td>policies</td> |
| |
| <td>A model of <a href= |
| "CallPolicies.html">CallPolicies</a></td> |
| |
| <td>A copy will be used as the call policies of the resulting |
| method overload.</td> |
| </tr> |
| |
| <tr> |
| <td>keywords</td> |
| |
| <td>The result of a <a href= |
| "args.html#keyword-expression"><em>keyword-expression</em></a> |
| specifying no more arguments than the <a href= |
| "definitions.html#arity">arity</a> of <code>fn</code>.</td> |
| |
| <td>A copy will be used as the call policies of the resulting |
| method overload.</td> |
| </tr> |
| </table> |
| </li> |
| </ul> |
| </dd> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| </dl> |
| <pre> |
| class_& staticmethod(char const* name); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>, and corresponds to a method whose overloads have all |
| been defined.</dt> |
| |
| <dt><b>Effects:</b> Replaces the existing named attribute <i>x</i> with |
| the result of invoking <code>staticmethod(</code><i>x</i><code>)</code> |
| in Python. Specifies that the corresponding method is static and |
| therefore no object instance will be passed to it. This is equivalent to |
| the Python statement:</dt> |
| |
| <dd> |
| <pre> |
| setattr(self, name, staticmethod(getattr(self, name))) |
| </pre> |
| </dd> |
| |
| <dt><b>Note:</b> Attempting to invoke <code>def(name,...)</code> after |
| invoking <code>staticmethod(name)</code> will <a href= |
| "definitions.html#raise">raise</a> a RuntimeError.</dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| </dl><br> |
| <pre> |
| template <<i>unspecified</i>> |
| class_& def(<a href= |
| "operators.html#operator_-spec">detail::operator_</a><unspecified>); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Effects:</b> Adds a Python <a href= |
| "http://www.python.org/doc/ref/specialnames.html">special method</a> as |
| described <a href="operators.html">here</a>.</dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| </dl> |
| <pre> |
| template <class U> |
| class_& setattr(char const* name, U const& u); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>.</dt> |
| |
| <dt><b>Effects:</b> Converts u to Python and adds it to the attribute |
| dictionary of the extension class:</dt> |
| |
| <dd> |
| <blockquote> |
| <code><a href= |
| "http://www.python.org/doc/current/api/object.html#l2h-166">PyObject_SetAttrString</a>(this->ptr(), |
| name, <a href= |
| "object.html#object-spec-ctors">object</a>(u).ptr());</code> |
| </blockquote> |
| </dd> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| </dl><br> |
| <pre> |
| 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); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conform to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>.</dt> |
| |
| <dt><b>Effects:</b> Creates a new Python <a href= |
| "http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a> |
| class instance, passing <code><a href= |
| "object.html#object-spec-ctors">object</a>(fget)</code> (and |
| <code><a href="object.html#object-spec-ctors">object</a>(fset)</code> in |
| the second form) with an (optional) docstring <code>doc</code> to its |
| constructor, then adds that property to the Python class object under |
| construction with the given attribute <code>name</code>.</dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Allows users to easily expose functions that can be |
| invoked from Python with attribute access syntax.</dt> |
| </dl><br> |
| <pre> |
| 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); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>.</dt> |
| |
| <dt><b>Effects:</b> Creates a Boost.Python.StaticProperty object, passing |
| <code><a href="object.html#object-spec-ctors">object</a>(fget)</code> |
| (and <code><a href= |
| "object.html#object-spec-ctors">object</a>(fset)</code> in the second |
| form) to its constructor, then adds that property to the Python class |
| under construction with the given attribute <code>name</code>. |
| StaticProperty is a special subclass of Python's <a href= |
| "http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a> |
| class which can be called without an initial <code>self</code> |
| argument.</dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Allows users to easily expose functions that can be |
| invoked from Python with static attribute access syntax.</dt> |
| </dl><br> |
| <pre> |
| 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); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> <code>name</code> is an <a href= |
| "definitions.html#ntbs">ntbs</a> which conforms to Python's <a href= |
| "http://www.python.org/doc/current/ref/identifiers.html">identifier |
| naming rules</a>. <code>doc</code> is also an ntbs.</dt> |
| |
| <dt><b>Effects:</b></dt> |
| |
| <dd> |
| <pre> |
| this->add_property(name, <a href= |
| "data_members.html#make_getter-spec">make_getter</a>(pm), doc); |
| </pre>and |
| <pre> |
| this->add_static_property(name, <a href= |
| "data_members.html#make_getter-spec">make_getter</a>(d)); |
| </pre>respectively.<br> |
| <br> |
| </dd> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Allows users to easily expose a class' data member |
| or free variable such that it can be inspected from Python with a natural |
| syntax.</dt> |
| </dl> |
| <pre> |
| 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); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Effects:</b></dt> |
| |
| <dd> |
| <pre> |
| this->add_property(name, <a href= |
| "data_members.html#make_getter-spec">make_getter</a>(pm), <a href= |
| "data_members.html#make_setter-spec">make_setter</a>(pm), doc); |
| </pre>and |
| <pre> |
| this->add_static_property(name, <a href= |
| "data_members.html#make_getter-spec">make_getter</a>(d), <a href= |
| "data_members.html#make_setter-spec">make_setter</a>(d)); |
| </pre>respectively.<br> |
| <br> |
| </dd> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Allows users to easily expose a class' data or free |
| variable member such that it can be inspected and set from Python with a |
| natural syntax.</dt> |
| </dl> |
| <pre> |
| template <typename PickleSuite> |
| class_& def_pickle(PickleSuite const&); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Requires:</b> PickleSuite must be publically derived from <a href= |
| "pickle.html"><code>pickle_suite</code></a>.</dt> |
| |
| <dt><b>Effects:</b> Defines a legal combination of the special attributes |
| and methods: <code>__getinitargs__</code>, <code>__getstate__</code>, |
| <code>__setstate__</code>, <code>__getstate_manages_dict__</code>, |
| <code>__safe_for_unpickling__</code>, <code>__reduce__</code></dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Provides an <a href="pickle.html">easy to use |
| high-level interface</a> for establishing complete pickle support for the |
| wrapped class. The user is protected by compile-time consistency |
| checks.</dt> |
| </dl><br> |
| <pre> |
| class_& enable_pickling(); |
| </pre> |
| |
| <dl class="function-semantics"> |
| <dt><b>Effects:</b> Defines the <code>__reduce__</code> method and the |
| <code>__safe_for_unpickling__</code> attribute.</dt> |
| |
| <dt><b>Returns:</b> <code>*this</code></dt> |
| |
| <dt><b>Rationale:</b> Light-weight alternative to |
| <code>def_pickle()</code>. Enables implementation of <a href= |
| "pickle.html">pickle support</a> from Python.</dt> |
| </dl><br> |
| |
| <h3><a name="bases-spec" id="bases-spec"></a>Class template |
| <code>bases<T1, T2,</code>...<code>TN></code></h3> |
| |
| <p>An <a href="../../../mpl/doc/refmanual/forward-sequence.html">MPL |
| sequence</a> which can be used in |
| <code>class_<</code>...<code>></code> instantiations indicate a list |
| of base classes.</p> |
| |
| <h4><a name="bases-spec-synopsis" id="bases-spec-synopsis"></a>Class |
| template <code>bases</code> synopsis</h4> |
| <pre> |
| namespace boost { namespace python |
| { |
| template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>> |
| struct bases |
| {}; |
| }} |
| </pre> |
| |
| <h2><a name="examples" id="examples"></a>Example(s)</h2> |
| |
| <p>Given a C++ class declaration:</p> |
| <pre> |
| 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: |
| ... |
| }; |
| </pre>A corresponding Boost.Python extension class can be created with: |
| <pre> |
| 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) |
| ; |
| </pre> |
| <hr> |
| <a name="footnote_1" id="footnote_1">[1]</a> By "previously-exposed" we |
| mean that the for each <code>B</code> in <code>bases</code>, an instance of |
| <code>class_<B<font color="#007F00">, ...</font>></code> must have |
| already been constructed. |
| <pre> |
| class_<Base>("Base"); |
| class_<Derived, bases<Base> >("Derived"); |
| </pre>Revised |
| <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
| 1 November, 2005 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
| |
| <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave |
| Abrahams</a> 2002.</i></p> |
| </body> |
| </html> |
