mirror of
https://github.com/boostorg/python.git
synced 2026-01-21 05:02:17 +00:00
854 lines
31 KiB
HTML
854 lines
31 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<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="../../../../c++boost.gif" border="0"></a></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Python</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>
|
|
|
|
<dt><a href="#init-spec">Class template <code>init</code></a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#init-spec-synopsis">Class template
|
|
<code>init</code> synopsis</a></dt>
|
|
|
|
<dt><a href="#init-spec-ctors">Class <code>init</code>
|
|
constructors</a></dt>
|
|
|
|
<dt><a href=
|
|
"#init-expressions"><em>init-expressions</em></a></dt>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#optional-spec">Class template
|
|
<code>optional</code></a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#optional-spec-synopsis">Class template
|
|
<code>optional</code> synopsis</a></dt>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#init_with_call_policies-spec">Class template
|
|
<code>init_with_call_policies</code></a></dt>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#init_with_call_policies-spec-synopsis">Class
|
|
template <code>init_with_call_policies</code> synopsis</a></dt>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#examples">Example(s)</a></dt>
|
|
</dl>
|
|
<hr>
|
|
|
|
<h2><a name="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"></a>Classes</h2>
|
|
|
|
<h3><a name="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">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 which is actually embedded in a Python object
|
|
wrapping a <code>T</code> instance. 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%20noncopyable">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">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#example">this example</a>. This argument is not
|
|
included in the <em><a href=
|
|
"#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"></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&);
|
|
|
|
// 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);
|
|
|
|
// property creation
|
|
template <class Get>
|
|
void add_property(char const* name, Get const& fget);
|
|
template <class Get, class Set>
|
|
void add_property(char const* name, Get const& fget, Set const& fset);
|
|
|
|
// pickle support
|
|
void enable_pickling(bool getstate_manages_dict);
|
|
template <typename PickleSuite>
|
|
self& def_pickle(PickleSuite const&);
|
|
};
|
|
}}
|
|
</pre>
|
|
|
|
<h4><a name="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 a <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-expression">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"></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-expression">init-expression</a> compatible with
|
|
<code>T</code>.</dt>
|
|
|
|
<dt><b>Effects:</b> For each <a href="#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 valid prefix 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 a <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=
|
|
"OverloadDispatch.html"><em>overload-dispatch-expression</em></a>,
|
|
only the second is allowed and fn must be a pointer to [member]
|
|
function whose signature is compatible with A1.
|
|
|
|
<dl>
|
|
<dt><b>Effects:</b> For each <a href=
|
|
"OverloadDispatch.html#valid-prefix">valid prefix</a>
|
|
<em>P</em> of <code>A1</code>, adds a
|
|
<code><em>name</em>(</code>...<code>)</code> function 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.</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>
|
|
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 a ntbs 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);
|
|
template <class Get, class Set>
|
|
void add_property(char const* name, Get const& fget, Set const& fset);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> <code>name</code> is a ntbs 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 new Python <a href=
|
|
"http://www.python.org/current/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) 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 D>
|
|
class_& def_readonly(char const* name, D T::*pm);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> <code>name</code> is a ntbs 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></dt>
|
|
|
|
<dd>
|
|
<pre>
|
|
this->add_property(name, <a href=
|
|
"data_members.html#make_getter-spec">make_getter</a>(pm));
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><b>Returns:</b> <code>*this</code></dt>
|
|
|
|
<dt><b>Rationale:</b> Allows users to easily expose a class' data
|
|
member 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);
|
|
</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));
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><b>Returns:</b> <code>*this</code></dt>
|
|
|
|
<dt><b>Rationale:</b> Allows users to easily expose a class' data
|
|
member such that it can be inspected and set from Python with a natural
|
|
syntax.</dt>
|
|
</dl>
|
|
<pre>
|
|
void enable_pickling(bool getstate_manages_dict);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> {{Ralf}}</dt>
|
|
|
|
<dt><b>Effects:</b> {{Ralf}}</dt>
|
|
|
|
<dt><b>Rationale:</b> Allows users to easily expose functions that can
|
|
be invoked from Python with attribute access syntax.</dt>
|
|
</dl>
|
|
<pre>
|
|
template <typename PickleSuite>
|
|
class_& def_pickle(PickleSuite const&);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> {{Ralf}}</dt>
|
|
|
|
<dt><b>Effects:</b> {{Ralf}}</dt>
|
|
|
|
<dt><b>Returns:</b> <code>*this</code></dt>
|
|
|
|
<dt><b>Rationale:</b> {{Ralf}}</dt>
|
|
</dl>
|
|
<br>
|
|
|
|
|
|
<h3><a name="init-spec"></a>Class template <code>init<T1 =</code>
|
|
<i>unspecified</i><code>, T2 =</code>
|
|
<i>unspecified</i><code>,</code>...<code>Tn</code> =
|
|
<i>unspecified</i><code>></code></h3>
|
|
|
|
<p>A <a href="../../../mpl/doc/ref/Sequences.html">MPL sequence</a> which
|
|
can be used to specify a family of one or more <code>__init__</code>
|
|
functions. Only the last <code>T</code><i><small>i</small></i> supplied
|
|
may be an instantiation of <a href=
|
|
"#optional-spec"><code>optional</code></a><code><</code>...<code>></code>.</p>
|
|
|
|
<h4><a name="init-spec-synopsis"></a>Class template <code>init</code>
|
|
synopsis</h4>
|
|
<pre>
|
|
namespace boost { namespace python
|
|
{
|
|
template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>>
|
|
struct init
|
|
{
|
|
init(char const* doc = 0);
|
|
template <class Keywords> init(Keywords const& kw, char const* doc = 0);
|
|
template <class Keywords> init(char const* doc, Keywords const& kw);
|
|
|
|
template <class CallPolicies>
|
|
<em>unspecified</em> operator[](CallPolicies const& policies) const
|
|
};
|
|
}}
|
|
</pre>
|
|
|
|
<h4><a name="init-spec-ctors"></a>Class template <code>init</code>
|
|
constructors</h4>
|
|
<pre>
|
|
init(char const* doc = 0);
|
|
template <class Keywords> init(Keywords const& kw, char const* doc = 0);
|
|
template <class Keywords> init(char const* doc, Keywords const& kw);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> If supplied, <code>doc</code> is an <a href=
|
|
"definitions.html#ntbs">ntbs</a>. If supplied, <code>kw</code> is the
|
|
result of a <a href="args.html#keyword-expression"></a></dt>
|
|
|
|
<dt><b>Effects:</b> The result is an <em>init-expression</em> whose
|
|
<em>docstring</em> is <code>doc</code> and whose <em>keywords</em> are
|
|
a reference to <code>kw</code>. If the first form is used, the
|
|
resulting expression's <em>keywords</em> are empty. The expression's
|
|
<em>call policies</em> are an instance of <a href=
|
|
"default_call_policies.html#default_call_policies-spec">default_call_policies</a>.
|
|
If <code>T</code><i><small>n</small></i> is <a href=
|
|
"#optional-spec"><code>optional</code></a><code><U1, U2,</code>...
|
|
<code>U</code><small><i>m</i></small><code>></code>, the
|
|
expression's <em>valid prefixes</em> are given by:</dt>
|
|
|
|
<dd>
|
|
<blockquote>
|
|
(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>),
|
|
(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>
|
|
<code>, U1</code>),
|
|
(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>
|
|
<code>, U1, U2</code>),
|
|
...(<code>T1, T2,</code>...<code>T</code><i><small>n-1</small></i>
|
|
<code>, U1, U2,</code>...<code>U</code><i><small>m</small></i>).
|
|
</blockquote>
|
|
Otherwise, the expression has one <em>valid prefix</em> given by the
|
|
the template arguments the user specified.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h4><a name="init-spec-observers"></a>Class template <code>init</code>
|
|
observer functions</h4>
|
|
<pre>
|
|
template <class Policies>
|
|
<em>unspecified</em> operator[](Policies const& policies) const
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> Policies is a model of <a href=
|
|
"CallPolicies.html">CallPolicies</a>.</dt>
|
|
|
|
<dt><b>Effects:</b> Returns a new <a href=
|
|
"#init-expressions"><em>init-expression</em></a> with all the same
|
|
properties as the <code>init</code> object except that its
|
|
<em>callpolicies</em> are replaced by a reference to
|
|
<code>policies</code>.</dt>
|
|
</dl>
|
|
|
|
<h4><a name="init-expressions"><em>init-expressions</em></a></h4>
|
|
An <em>init-expression</em> is a transport vehicle for the following
|
|
properties, used to describe a family of <code>__init__</code> methods to
|
|
be generated for an extension class:
|
|
|
|
<dl class="properties">
|
|
<dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a> whose
|
|
value will bound to the method's <code>__doc__</code> attribute</dt>
|
|
|
|
<dt><b>keywords:</b> A <a href=
|
|
"args.html#keyword-expression">keyword-expression</a> which will be
|
|
used to name (a trailing subset of) the arguments to the generated
|
|
<code>__init__</code> function(s).</dt>
|
|
|
|
<dt><b>call policies:</b> An instance of a model of <a href=
|
|
"CallPolicies.html">CallPolicies</a>.</dt>
|
|
|
|
<dt><b>argument types:</b> An MPL sequence of C++ argument types which
|
|
will be used to construct the wrapped C++ object. An init expression
|
|
has one or more <b>valid prefixes</b> which are given by a sequence of
|
|
prefixes of its argument types.</dt>
|
|
</dl>
|
|
|
|
<h3><a name="optional-spec"></a>Class template <code>optional<T1
|
|
=</code> <i>unspecified</i><code>, T2 =</code>
|
|
<i>unspecified</i><code>,</code>...<code>Tn</code> =
|
|
<i>unspecified</i><code>></code></h3>
|
|
|
|
<p>A <a href="../../../mpl/doc/ref/Sequences.html">MPL sequence</a> which
|
|
can be used to specify the optional arguments to an <code>__init__</code>
|
|
function.</p>
|
|
|
|
<h4><a name="optional-spec-synopsis"></a>Class template
|
|
<code>optional</code> synopsis</h4>
|
|
<pre>
|
|
namespace boost { namespace python
|
|
{
|
|
template <T1 = <i>unspecified</i>,...T<i>n</i> = <i>unspecified</i>>
|
|
struct optional {};
|
|
}}
|
|
</pre>
|
|
|
|
<h3><a name="bases-spec"></a>Class template
|
|
<code>bases<T1, T2,</code>...<code>TN></code></h3>
|
|
|
|
<p>An <a href="../../../mpl/doc/ref/Sequences.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"></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"></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">[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 -->
|
|
29 Sept, 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
|
|
|
|
<p><i>© Copyright <a href=
|
|
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
|
|
Reserved.</i></p>
|
|
</body>
|
|
</html>
|
|
|