mirror of
https://github.com/boostorg/python.git
synced 2026-01-23 17:52:17 +00:00
329 lines
10 KiB
HTML
329 lines
10 KiB
HTML
<html>
|
|
<head>
|
|
<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>
|
|
|
|
<dl class="page-index">
|
|
|
|
<dt><a href="#class_-spec">Class template <code>class_</code></a></dt>
|
|
<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>
|
|
<dt><a href="#class_-spec-observers">Class <code>class_</code> observer functions</a></dt>
|
|
</dl>
|
|
|
|
<dt><a href="#bases-spec">Class template <code>bases</code></a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#bases-spec-synopsis">Class <code>bases</code> synopsis</a></dt>
|
|
</dl>
|
|
|
|
<dt><a href="#args-spec">Class template <code>args</code></a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#args-spec-synopsis">Class <code>args</code> synopsis</a></dt>
|
|
</dl>
|
|
|
|
</dl>
|
|
|
|
<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, and the <code>args</code> and
|
|
<code>bases</code> utility class templates in the anonymous
|
|
namespace (the latter definitions will probably be moved in a future
|
|
release).
|
|
|
|
<p>
|
|
<code><boost/python/class_fwd.hpp></code> contains a forward
|
|
declaration of the <code>class_</code> class template.
|
|
|
|
|
|
<h2><a name="classes"></a>Classes</h2>
|
|
|
|
<h3><a name="class_-spec">
|
|
</a>Class template <code>class_<T, Bases, <a
|
|
href="HolderGenerator.html">HolderGenerator</a>></code></h3>
|
|
|
|
<p>Creates a Python class associated with the C++ type passed as its
|
|
first parameter. Its template arguments are:
|
|
<br><br>
|
|
<table border="1" summary="class_ template parameters">
|
|
<tr>
|
|
<th>Parameter
|
|
<th>Description
|
|
<th>Default
|
|
<tr>
|
|
<td><code>T</code>
|
|
<td>The class being exposed to Python
|
|
<tr>
|
|
<td><code>Bases</code>
|
|
<td>An <a href="../../../mpl/doc/Sequences.html">MPL sequence</a> of C++ base classes
|
|
<td>An unspecified empty sequence
|
|
<tr>
|
|
<td><a href="HolderGenerator.html">HolderGenerator</a></code>
|
|
<td>A type generator for the holder which
|
|
maintains the C++ object inside the Python instance.
|
|
<td><code>boost::python::objects::value_holder_generator</code>
|
|
</table>
|
|
|
|
|
|
|
|
<h4><a name="class_-spec-synopsis"></a>Class template <code>class_</code> synopsis</h4>
|
|
<pre>
|
|
namespace boost { namespace python
|
|
{
|
|
|
|
template <class T
|
|
, class Bases = <i>none</i>
|
|
, class HolderGenerator = objects::value_holder_generator>
|
|
class class_
|
|
{
|
|
class_();
|
|
class_(char const* name);
|
|
|
|
template <class F>
|
|
class_& def(char const* name, F f);
|
|
|
|
template <class Fn, class CallPolicy>
|
|
class_& def(char const* name, Fn fn, CallPolicy policy);
|
|
|
|
template <class Args>
|
|
class_& def_init(Args const& = Args());
|
|
|
|
class_& def_init();
|
|
|
|
ref object() const;
|
|
};
|
|
}}
|
|
</pre>
|
|
|
|
<h4><a name="class_-spec-ctors"></a>Class template <code>class_</code> constructors</h4>
|
|
<pre>
|
|
class_()
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
|
|
<dt><b>Requires:</b> The platform's
|
|
<code>std::type_info::name()</code> implementation produces a string
|
|
which corresponds to the type's declaration in C++</dt>
|
|
|
|
<dt><b>Effects:</b> Constructs a <code>class_</code> object which
|
|
generates a Boost.Python extension class with the same name as
|
|
<code>T</code>.</dt>
|
|
|
|
<dt><b>Rationale:</b> Many platforms can generate reasonable names
|
|
for Python classes without user intervention.</dt>
|
|
|
|
</dl>
|
|
|
|
<pre>
|
|
class_(char const* name)
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
|
|
<dt><b>Requires:</b> Name 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> Constructs a <code>class_</code> object which
|
|
generates a Boost.Python extension class named
|
|
<code>name</code>.</dt>
|
|
|
|
<dt><b>Rationale:</b> Gives the user full control over class naming.</dt>
|
|
|
|
</dl>
|
|
|
|
<h4><a name="class_-spec-modifiers"></a>Class template <code>class_</code> modifier functions</h4>
|
|
|
|
<pre>
|
|
template <class F>
|
|
class_& def(char const* name, F f)
|
|
|
|
template <class Fn, class CallPolicy>
|
|
class_& def(char const* name, Fn fn, CallPolicy policy)
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b>
|
|
|
|
<code>f</code> is a non-null pointer-to-function or
|
|
pointer-to-member-function.
|
|
|
|
<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>.
|
|
|
|
If supplied, <code>policy</code> conforms to the <a
|
|
href="CallPolicy.html">CallPolicy</a> concept requirements.
|
|
</dt>
|
|
|
|
<dt><b>Effects:</b> Adds the result of <code><a
|
|
href="make_function.html#make_function-spec">make_function</a>(f)</code>
|
|
to the Boost.Python extension class being defined, with the given
|
|
<code>name</code>. If the extension class already has an attribute
|
|
named <code><i>name</i></code>, the usual <a
|
|
href="http:overloading.html">overloading procedure</a> applies.
|
|
|
|
</dt>
|
|
|
|
<dt><b>Returns:</b> <code>*this</code></dt>
|
|
</dl>
|
|
|
|
<pre>
|
|
template <class Args>
|
|
class_& def_init(Args const& argument_types)
|
|
|
|
class_& def_init()
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
|
|
<dt><b>Requires:</b> in the first form, argument_types must be an <a
|
|
href="../../../mpl/doc/Sequences.html">MPL sequence</a> of C++
|
|
argument types (<i>A1, A2,... AN</i>) such that if
|
|
<code>a1, a2</code>... <code>aN</code> are objects of type
|
|
<i>A1, A2,... AN</i> respectively, the expression
|
|
<code>T(a1, a2</code>... <code>aN</code>) is
|
|
valid. In the second form, the expression <code>T()</code> must be
|
|
valid.
|
|
</dt>
|
|
|
|
<dt><b>Effects:</b> Adds the result of <code><a
|
|
href="make_function.html#make_constructor-spec">
|
|
make_constructor</a><T,Args,HolderGenerator>()</code> to the
|
|
Boost.Python extension class being defined with the name
|
|
"__init__". If the 2nd form is used, an unspecified empty
|
|
<a href="../../../mpl/doc/Sequences.html">MPL sequence</a> type is
|
|
substituted for <code>Args</code>.
|
|
If the extension class already has an
|
|
"__init__" attribute, the usual <a
|
|
href="http:overloading.html">overloading procedure</a> applies.
|
|
|
|
<dt><b>Returns:</b> <code>*this</code></dt>
|
|
|
|
<dt><b>Rationale:</b> Allows users to easily expose a class'
|
|
constructor to Python.</dt>
|
|
</dl>
|
|
|
|
|
|
<h4><a name="class_-spec-observers"></a>Class template <code>class_</code> observer
|
|
functions</h4>
|
|
<pre>
|
|
ref object() const;
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Returns:</b> A <code>ref</code> object which holds a
|
|
reference to the Boost.Python extension class object created by the
|
|
<code>class_</code> constructor.</dt>
|
|
|
|
<dt><b>Rationale:</b> Mostly not needed by users, since <code><a
|
|
href="module.html#add-spec">module::add</a>()</code> uses this to
|
|
insert the extension class in the module.</dt>
|
|
</dl>
|
|
|
|
|
|
<h3><a name="args-spec">
|
|
</a>Class template <code>args<T1, T2,</code>...<code>TN></code></h3>
|
|
|
|
<p>Essentially an alias for <code>boost::mpl::type_list</code> which
|
|
users can use in <code>def_init</code> calls to make their code more
|
|
readable. Currently it is in the global unnammed namespace, but that
|
|
will probably change.
|
|
|
|
<h4><a name="args-spec-synopsis"></a>Class template <code>args</code> synopsis</h4>
|
|
<pre>
|
|
namespace
|
|
{
|
|
template <T1 = <i>unspecified</i>,...TN = <i>unspecified</i>>
|
|
struct args : ::boost::mpl::type_list<T1,...TN>::type
|
|
{};
|
|
}
|
|
</pre>
|
|
|
|
<h3><a name="bases-spec">
|
|
</a>Class template <code>bases<T1, T2,</code>...<code>TN></code></h3>
|
|
|
|
<p>Essentially an alias for <code>boost::mpl::type_list</code> which
|
|
users can use in <code>class_<</code>...<code>></code>
|
|
instantiations to make their code more readable. Currently it is in
|
|
the global unnammed namespace, but that will probably change.
|
|
|
|
<h4><a name="bases-spec-synopsis"></a>Class template <code>bases</code> synopsis</h4>
|
|
<pre>
|
|
namespace
|
|
{
|
|
template <T1 = <i>unspecified</i>,...TN = <i>unspecified</i>>
|
|
struct bases : ::boost::mpl::type_list<T1,...TN>::type
|
|
{};
|
|
}
|
|
</pre>
|
|
|
|
<h2><a name="examples"></a>Example(s)</h2>
|
|
|
|
<p>Given a C++ class declaration:
|
|
|
|
<pre>
|
|
class Foo : public Bar, public Baz
|
|
{
|
|
public:
|
|
Foo(int, char const*);
|
|
Foo(double);
|
|
|
|
std::string const& name() { return m_name; }
|
|
void name(char const*);
|
|
private:
|
|
...
|
|
};
|
|
</pre>
|
|
|
|
A corresponding Boost.Python extension class can be created with:
|
|
|
|
<pre>
|
|
using namespace boost::python;
|
|
ref foo =
|
|
class_<Foo,bases<Bar,Baz> >()
|
|
.def_init(args<int,char const*>())
|
|
.def_init(args<double>())
|
|
.def("get_name", &Foo::get_name, return_internal_reference<>())
|
|
.def("set_name", &Foo::set_name)
|
|
.object();
|
|
</pre>
|
|
|
|
</p>
|
|
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
05 November, 2001
|
|
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
</p>
|
|
<p><i>© Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a>
|
|
2002. All Rights Reserved.</i></p>
|
|
</body>
|
|
</html>
|