boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-27 19:12:16 +00:00
Code Issues Projects Releases Wiki Activity

doc update

Browse Source 
[SVN r15647]
This commit is contained in:
Dave Abrahams
2002-10-02 12:00:22 +00:00
parent f8a9b922be
commit 28e5bedf49
1 changed files with 19 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files

195
doc/v2/module.html
View File

@@ -32,36 +32,14 @@
"#BOOST_PYTHON_MODULE-spec">BOOST_PYTHON_MODULE</a>
</dl>
<dt><a href="#classes">Classes</a>
<dd>
<dl class="page-index">
<dt><a href="#module-spec">Class <code>module</code></a>
<dd>
<dl class="page-index">
<dt><a href="#module-spec-synopsis">Class <code>module</code>
synopsis</a>
<dt><a href="#module-spec-ctors">Class <code>module</code>
constructor</a>
<dt><a href="#module-spec-modifiers">Class <code>module</code>
modifier functions</a>
<dt><a href="#module-spec-observers">Class <code>module</code>
observer functions</a>
</dl>
</dl>
<dt><a href="#examples">Example(s)</a>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p>This header provides the basic facilities needed to create an
extension module.
<p>This header provides the basic facilities needed to create a
Boost.Python extension module.
<h2><a name="macros"></a>Macros</h2>
@@ -75,157 +53,27 @@
"http://www.python.org/doc/2.2/ref/identifiers.html">identifier naming
rules</a>. Where you would normally write
<pre>
void init<i>name</i>()
extern &quot;C&quot; void init<i>name</i>()
{
...
}
</pre>
Boost.Python modules should be initialized with
<pre>
BOOST_PYTHON_MODULE(<i>name</i>)
{
...
}
</pre>
<h2><a name="classes"></a>Classes</h2>
This macro generates two functions in the scope where it is used:
<code>extern&nbsp;&quot;C&quot;&nbsp;void&nbsp;init<i>name</i>()</code>,
and <code>void&nbsp;init_module_<i>name</i>()</code>, whose body must
follow the macro invocation. <code>init_<i>name</i></code> passes
<code>init_module_<i>name</i></code> to <code><a
href="errors.html#handle_exception"></a>()</code> so that any C++
exceptions generated are safely processeed.
<h3><a name="module-spec">Class <code>module</code></a></h3>
<p>This class represents the Python extension module under construction. It
provides functions for adding attributes and for retrieving the underlying
Python module object.
<h4><a name="module-spec-synopsis"></a>Class <code>module</code>
synopsis</h4>
<pre>
namespace boost { namespace python
{
class module : public module_base
{
public:
module(const char* name);
// modifier functions
module&amp; setattr(const char* name, PyObject*);
module&amp; setattr(const char* name, PyTypeObject*);
module&amp; setattr(const char* name, ref const&amp;);
module&amp; add(PyTypeObject* x);
template &lt;class T, class Bases, class HolderGenerator&gt;
module&amp; add(class_&lt;T,Bases,HolderGenerator&gt; const&amp; c);
template &lt;class Fn&gt;
module&amp; def(char const* name, Fn fn);
template &lt;class Fn, class ResultHandler&gt;
module&amp; def(char const* name, Fn fn, ResultHandler handler);
// observer function
ref object() const;
};
}}
</pre>
<h4><a name="module-spec-ctors">Class <code>module</code></a>
constructor</h4>
<pre>
module(const char* name);
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> <code>name</code> is a ntbs whose value matches the
argument passed to <a href=
"#BOOST_PYTHON_MODULE-spec">BOOST_PYTHON_MODULE</a>.
<dt><b>Effects:</b> Creates a <code>module</code> object representing a
Python module named <code>name</code>.
</dl>
<h4><a name="module-spec-modifiers">Class <code>module</code></a> modifier
functions</h4>
<pre>
module&amp; setattr(const char* name, PyObject* obj);
module&amp; setattr(const char* name, PyTypeObject* obj);
module&amp; setattr(const char* name, ref const&amp; r);
</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/2.2/ref/identifiers.html">identifier
naming rules</a>. In the first two forms, <code>obj</code> is non-null.
In the third form, <code>r.get()</code> is non-null.
<dt><b>Effects:</b> Adds the given Python object to the module. If the
object is a product of <code><a href=
"make_function.html#make_function-spec">make_function</a>()</code>, the
usual <a href="overloading.html">overloading procedure</a> applies.
In the first two forms, ownership of a reference to obj is transferred
from caller to callee, even if an exception is thrown.
<dt><b>Returns:</b> <code>*this</code>
</dl>
<pre>
module&amp; add(PyTypeObject* x);
template &lt;class T, class Bases, class HolderGenerator&gt;
module&amp; add(class_&lt;T,Bases,HolderGenerator&gt; const&amp; c);
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> In the first form, <code>x</code> is non-null
<dt><b>Effects:</b> The first form adds the Python type object named by
<code>x</code> to the Python module under construction, with the name
given by the type's <code><a href=
"http://www.python.org/doc/2.2/ext/dnt-type-methods.html">tp_name</a></code>
field. The second form adds the extension class object being constructed
by <code>c</code> to the module, with the same name that was passed to
<code>c</code>'s constructor.
<dt><b>Returns:</b> <code>*this</code>
<dt><b>Rationale:</b> Provides a way to set type attributes in the module
without having to explicitly specify the name.
</dl>
<pre>
template &lt;class Fn&gt;
module&amp; def(char const* name, Fn f);
template &lt;class Fn, class ResultHandler&gt;
module&amp; def(char const* name, Fn f, ResultHandler handler);
</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/2.2/ref/identifiers.html">identifier
naming rules</a>. In the first form, the return type of
<code>f</code> is not a reference and is not a pointer other
than <code>char const*</code> or <code>PyObject*</code>. In the
second form <code>policy</code> is a model of <a
href="CallPolicy.html">CallPolicy</a>.
<dt><b>Effects:</b> Adds the result of <code><a href=
"make_function.html#make_function-spec">make_function</a>(f)</code> to
the extension module being defined, with the given <code>name</code>. If
the module already has an attribute named <code><i>name</i></code>, the
usual <a href="http:overloading.html">overloading procedure</a> applies.
<dt><b>Returns:</b> <code>*this</code>
</dl>
<h4><a name="module-spec-observers">Class <code>module</code></a> 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 Python module object created by the <code>module</code> constructor.
</dl>
<h2><a name="examples"></a>Example(s)</h2>
@@ -233,28 +81,23 @@ ref object() const;
<pre>
#include &lt;boost/python/module.hpp&gt;
char const* greet()
BOOST_PYTHON_MODULE(xxx)
{
return "hello, Boost.Python!";
}
BOOST_PYTHON_MODULE(boost_greet)
{
module("boost_greet")
.def("greet", greet);
throw &quot;something bad happened&quot;
}
</pre>
Interactive Python:
<pre>
&gt;&gt;&gt; import boost_greet
&gt;&gt;&gt; boost_greet.greet()
'hello, Boost.Python!'
&gt;&gt;&gt; import xxx
Traceback (most recent call last):
File "<stdin>", line 1, in ?
RuntimeError: Unidentifiable C++ Exception
</pre>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
14 February, 2002
2 October, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->