2
0
mirror of https://github.com/boostorg/python.git synced 2026-01-20 16:52:15 +00:00

Documentation update

[SVN r15548]
This commit is contained in:
Dave Abrahams
2002-09-29 16:06:02 +00:00
parent 94063f7862
commit 8cd3e16e26
4 changed files with 886 additions and 558 deletions

View File

@@ -1,124 +1,152 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<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 - CallPolicies Concept</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
<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 - CallPolicies Concept</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">CallPolicies Concept</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#composition">CallPolicies Composition</a></dt>
<dt><a href="#concept-requirements">Concept Requirements</a></dt>
<dl class="page-index">
<dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt>
</dl>
</dl>
<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>
<h2><a name="introduction"></a>Introduction</h2>
<td valign="top">
<h1 align="center">Boost.Python</h1>
<p>Models of the CallPolicies concept are used to specialize the
behavior of Python callable objects generated by Boost.Python to
wrapped C++ objects like function and member function
pointers, providing three behaviors:
<ol>
<li> <code>precall</code> - Python argument tuple management before
the wrapped object is invoked
<li> <code>result_converter</code> - C++ return value handling
<li> <code>postcall</code> - Python argument tuple and result
management after the wrapped object is invoked
</ol>
<h2 align="center">CallPolicies Concept</h2>
</td>
</tr>
</table>
<hr>
<h2><a name="composition"></a>CallPolicies Composition</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
In order to allow the use of multiple models of CallPolicies in the
same callable object, Boost.Python's CallPolicies class templates
provide a chaining interface which allows them to be recursively
composed. This interface takes the form of an optional template
parameter, <code>Base</code> which defaults to <a
href="default_call_policies.html#default_call_policies-spec">
<code>default_call_policies</code></a>. By convention, the
<code>precall</code> function of the
<code>Base</code> is invoked <i>after</i> the <code>precall</code>
function supplied by the outer template, and the <code>postcall</code>
function of the <code>Base</code> is invoked <i>before</i> the
<code>postcall</code> function of the outer template. If a
<code>result_converter</code> is supplied by the outer template, it
<i>replaces</i> any <code>result_converter</code> supplied by the
<code>Base</code>. For an example, see <a
href="return_internal_reference.html#return_internal_reference-spec">
<code>return_internal_reference</code></a>.
<dt><a href="#composition">CallPolicies Composition</a></dt>
<h2><a name="concept-requirements"></a>Concept Requirements</h2>
<h3><a name="CallPolicies-concept"></a>CallPolicies Concept</h3>
<dt><a href="#concept-requirements">Concept Requirements</a></dt>
<p>In the table below, <code><b>x</b></code> denotes an object whose
type <code><b>P</b></code> is a model of CallPolicies,
<code><b>a</b></code> denotes a <code>PyObject*</code> pointing to
a Python argument tuple object, and <code><b>r</b></code> denotes a
<code>PyObject*</code> referring to a &quot;preliminary&quot; result
object.
<dd>
<dl class="page-index">
<dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt>
</dl>
</dd>
</dl>
<table summary="CallPolicies expressions" border="1" cellpadding="5">
<h2><a name="introduction"></a>Introduction</h2>
<tr>
<td><b>Expression</b></td>
<td><b>Type</b></td>
<td><b>Result/Semantics</b></td>
</tr>
<p>Models of the CallPolicies concept are used to specialize the behavior
of Python callable objects generated by Boost.Python to wrapped C++
objects like function and member function pointers, providing three
behaviors:</p>
<tr>
<td valign="top"><code>x.precall(a)</code></td>
<td>convertible to <code>bool</code>
<td>returns <code>false</code> and <code><a
href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
upon failure, <code>true</code> otherwise.
<ol>
<li><code>precall</code> - Python argument tuple management before the
wrapped object is invoked</li>
<tr>
<td valign="top"><code>P::result_converter</code></td>
<td>A model of <a href="ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.
<td>An MPL unarymetafunction object used produce the
&quot;preliminary&quot result object.
<li><code>result_converter</code> - C++ return value handling</li>
<tr>
<td valign="top"><code>x.postcall(a, r)</code></td>
<td>convertible to <code>PyObject*</code>
<td>0 <code>0</code> and <code><a
href="http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
upon failure. Must &quot;conserve references&quot; even in the
event of an exception. In other words, if <code>r</code> is not
returned, its reference count must be decremented; if another
existing object is returned, its reference count must be
incremented.
</table>
<li><code>postcall</code> - Python argument tuple and result management
after the wrapped object is invoked</li>
</ol>
Models of CallPolicies are required to be <a
href="../../../utility/CopyConstructible.html">CopyConstructible</a>.
<h2><a name="composition"></a>CallPolicies Composition</h2>
In order to allow the use of multiple models of CallPolicies in the same
callable object, Boost.Python's CallPolicies class templates provide a
chaining interface which allows them to be recursively composed. This
interface takes the form of an optional template parameter,
<code>Base</code> which defaults to <a href=
"default_call_policies.html#default_call_policies-spec"><code>default_call_policies</code></a>.
By convention, the <code>precall</code> function of the <code>Base</code>
is invoked <i>after</i> the <code>precall</code> function supplied by the
outer template, and the <code>postcall</code> function of the
<code>Base</code> is invoked <i>before</i> the <code>postcall</code>
function of the outer template. If a <code>result_converter</code> is
supplied by the outer template, it <i>replaces</i> any
<code>result_converter</code> supplied by the <code>Base</code>. For an
example, see <a href=
"return_internal_reference.html#return_internal_reference-spec"><code>return_internal_reference</code></a>.
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
19 May, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
Abrahams</a> 2002. All Rights Reserved.</i>
<h2><a name="concept-requirements"></a>Concept Requirements</h2>
<p>Permission to copy, use, modify, sell
and distribute this software is granted provided this copyright notice appears
in all copies. This software is provided "as is" without express or implied
warranty, and with no claim as to its suitability for any purpose.
</body>
<h3><a name="CallPolicies-concept"></a>CallPolicies Concept</h3>
<p>In the table below, <code><b>x</b></code> denotes an object whose type
<code><b>P</b></code> is a model of CallPolicies, <code><b>a</b></code>
denotes a <code>PyObject*</code> pointing to a Python argument tuple
object, and <code><b>r</b></code> denotes a <code>PyObject*</code>
referring to a "preliminary" result object.</p>
<table summary="CallPolicies expressions" border="1" cellpadding="5">
<tr>
<td><b>Expression</b></td>
<td><b>Type</b></td>
<td><b>Result/Semantics</b></td>
</tr>
<tr>
<td valign="top"><code>x.precall(a)</code></td>
<td>convertible to <code>bool</code></td>
<td>returns <code>false</code> and <code><a href=
"http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
upon failure, <code>true</code> otherwise.</td>
</tr>
<tr>
<td valign="top"><code>P::result_converter</code></td>
<td>A model of <a href=
"ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.</td>
<td>An MPL unary <a href=
"../../../mpl/doc/paper/html/usage.html#metafunctions.classes">Metafunction
Class</a> used produce the "preliminary" result object.</td>
</tr>
<tr>
<td valign="top"><code>x.postcall(a, r)</code></td>
<td>convertible to <code>PyObject*</code></td>
<td>0 <code>0</code> and <code><a href=
"http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>()&nbsp;!=&nbsp;0</code>
upon failure. Must "conserve references" even in the event of an
exception. In other words, if <code>r</code> is not returned, its
reference count must be decremented; if another existing object is
returned, its reference count must be incremented.</td>
</tr>
</table>
Models of CallPolicies are required to be <a href=
"../../../utility/CopyConstructible.html">CopyConstructible</a>.
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
19 May, 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
Reserved.</i></p>
<p>Permission to copy, use, modify, sell and distribute this software is
granted provided this copyright notice appears in all copies. This
software is provided "as is" without express or implied warranty, and
with no claim as to its suitability for any purpose.</p>
</body>
</html>

View File

@@ -1,74 +1,89 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<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 - &lt;call_method.hpp&gt;</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
<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 - &lt;call_method.hpp&gt;</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">Header &lt;call_method.hpp&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#functions">Functions</a></dt>
<dl class="page-index">
<dt><a href="#call_method-spec">call_method</a></dt>
</dl>
<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>
<dt><a href="#examples">Example(s)</a></dt>
<td valign="top">
<h1 align="center">Boost.Python</h1>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p>
<code>&lt;boost/python/call_method.hpp&gt;</code> defines the <a
href="#call_method-spec"><code>call_method</code></a> family of overloaded function
templates, used to invoke callable attributes of Python objects from C++.
<h2 align="center">Header &lt;call_method.hpp&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2><a name="functions"></a>Functions</h2>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#functions">Functions</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#call_method-spec">call_method</a></dt>
</dl>
</dd>
<dt><a href="#examples">Example(s)</a></dt>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p><code>&lt;boost/python/call_method.hpp&gt;</code> defines the <a href=
"#call_method-spec"><code>call_method</code></a> family of overloaded
function templates, used to invoke callable attributes of Python objects
from C++.</p>
<h2><a name="functions"></a>Functions</h2>
<pre>
<a name="call_method-spec">template &lt;class R, class A1, class A2, ... class A<i>n</i>&gt;</a>
<a name=
"call_method-spec">template &lt;class R, class A1, class A2, ... class A<i>n</i>&gt;</a>
R call_method(PyObject* self, char const* method, A1 const&amp;, A2 const&amp;, ... A<i>n</i> const&amp;)
</pre>
<dl class="function-semantics">
<dt><b>Requires:</b> <code>R</code> is a pointer type, reference
type, or a complete type with an accessible copy constructor</dt>
<dt><b>Effects:</b> Invokes <code>self.<i>method</i>(a1,&nbsp;a2,&nbsp;...a<i>n</i>)</code> in
Python, where <code>a1</code>...<code>a<i>n</i></code> are the arguments to
<code>call_method()</code>, converted to Python objects. For a
complete semantic description, see <a href="callbacks.html">this
page</a>.
<dl class="function-semantics">
<dt><b>Requires:</b> <code>R</code> is a pointer type, reference type,
or a complete type with an accessible copy constructor</dt>
<dt><b>Returns:</b> The result of the Python call, converted to the
C++ type <code>R</code>.</dt>
<dt><b>Effects:</b> Invokes
<code>self.<i>method</i>(a1,&nbsp;a2,&nbsp;...a<i>n</i>)</code> in
Python, where <code>a1</code>...<code>a<i>n</i></code> are the
arguments to <code>call_method()</code>, converted to Python objects.
For a complete semantic description, see <a href="callbacks.html">this
page</a>.</dt>
</dt>
<dt><b>Rationale:</b> <code>call_method</code> is critical to
implementing C++ virtual functions which are overridable in Python,
as shown by the example below.
</dt>
</dl>
<dt><b>Returns:</b> The result of the Python call, converted to the C++
type <code>R</code>.</dt>
<h2><a name="examples"></a>Example(s)</h2>
<dt><b>Rationale:</b> <code>call_method</code> is critical to
implementing C++ virtual functions which are overridable in Python, as
shown by the example below.</dt>
</dl>
The following C++ illustrates the use of <code>call_method</code> in
wrapping a class with a virtual function that can be overridden in
Python:
<h2><a name="examples"></a>Example(s)</h2>
The following C++ illustrates the use of <code>call_method</code> in
wrapping a class with a virtual function that can be overridden in
Python:
<h3>C++ Module Definition</h3>
<h3>C++ Module Definition</h3>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
@@ -79,13 +94,13 @@ Python:
class Base
{
public:
virtual char const* class_name() const { return &quot;Base&quot;; }
virtual char const* class_name() const { return "Base"; }
virtual ~Base();
};
bool is_base(Base* b)
{
return !std::strcmp(b-&gt;class_name(), &quot;Base&quot;);
return !std::strcmp(b-&gt;class_name(), "Base");
}
// Wrapper code begins here
@@ -97,26 +112,25 @@ class Base_callback : public Base
public:
Base_callback(PyObject* self) : m_self(self) {}
char const* class_name() const { return <b>call_method</b>(m_self, &quot;class_name&quot;); }
char const* class_name() const { return <b>call_method</b>(m_self, "class_name"); }
char const* Base_name() const { return Base::class_name(); }
private:
PyObject* m_self;
PyObject* const m_self;
};
using namespace boost::python;
BOOST_PYTHON_MODULE_INIT(my_module)
{
module("my_module")
.def(&quot;is_base&quot;, is_base)
.add(
class_&lt;Base,Base_callback, noncopyable&gt;(&quot;Base&quot;)
.def(&quot;class_name&quot;, &#24;Base_callback::Base_name);
)
;
def("is_base", is_base)
class_&lt;Base,Base_callback, noncopyable&gt;("Base")
.def("class_name", &amp;Base_callback::Base_name)
;
}
</pre>
<h3>Python Code</h3>
<h3>Python Code</h3>
<pre>
&gt;&gt;&gt; from my_module import *
&gt;&gt;&gt; class Derived(Base):
@@ -130,12 +144,15 @@ BOOST_PYTHON_MODULE_INIT(my_module)
&gt;&gt;&gt; is_base(Derived())
0
</pre>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
10 May, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a>
2002. All Rights Reserved.</i></p>
</body>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
28 Sept, 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
Reserved.</i></p>
</body>
</html>

File diff suppressed because it is too large Load Diff

View File

@@ -1,35 +1,54 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<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 - Definitions</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
<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 - Definitions</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">Definitions</h2>
</td>
</tr>
</table>
<hr>
<dl class="definitions">
<dt><b>{{term}}:</b> {{definition}}</dt>
<dt><b>{{term}}:</b> {{definition}}</dt>
</dl>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
05 November, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave Abrahams</a>
2002. All Rights Reserved.</i></p>
</body>
<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">Definitions</h2>
</td>
</tr>
</table>
<hr>
<dl class="definitions">
<dt><b><a name="arity">arity</a>:</b> The number of arguments accepted
by a function or member function. Unless otherwise specified, the
hidden "<code>this</code>" argument to member functions is not counted
when specifying arity</dt>
<dt><b><a name="ntbs">ntbs</a>:</b> Null-Terminated Byte String, or
`C'-string. C++ string literals are <strong>ntbs</strong>es. An
<strong>ntbs</strong> must never be null.</dt>
</dl>
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
28 September, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
Reserved.</i></p>
</body>
</html>