mirror of
https://github.com/boostorg/python.git
synced 2026-01-22 05:22:45 +00:00
doc updates
[SVN r15571]
This commit is contained in:
Dave Abrahams
155
doc/v2/ObjectWrapper.html
Normal file
155
doc/v2/ObjectWrapper.html
Normal file
@@ -0,0 +1,155 @@
|
||||
<!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 - ObjectWrapper 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">ObjectWrapper and TypeWrapper Concepts</h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
|
||||
<dl class="page-index">
|
||||
<dt><a href="#introduction">Introduction</a></dt>
|
||||
|
||||
<dt><a href="#concept-requirements">Concept Requirements</a></dt>
|
||||
|
||||
<dd>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#ObjectWrapper-concept">ObjectWrapper Concept</a></dt>
|
||||
|
||||
<dt><a href="#TypeWrapper-concept">TypeWrapper Concept</a></dt>
|
||||
</dl>
|
||||
</dd>
|
||||
|
||||
<dt><a href="#caveat">Caveat</a></dt>
|
||||
</dl>
|
||||
|
||||
<h2><a name="introduction"></a>Introduction</h2>
|
||||
|
||||
<p>This page defines two concepts used to describe classes which manage a
|
||||
Python objects, and which are intended to support usage with a
|
||||
Python-like syntax.</p>
|
||||
|
||||
<h2><a name="concept-requirements"></a>Concept Requirements</h2>
|
||||
|
||||
<h3><a name="ObjectWrapper-concept"></a>ObjectWrapper Concept</h3>
|
||||
Models of the ObjectWrapper concept have <a href=
|
||||
"object.html#object-spec">object</a> as a publicly-accessible base class,
|
||||
and are used to supply special construction behavior and/or additional
|
||||
convenient functionality through (often templated) member functions.
|
||||
Except when the return type <code>R</code> is itself an <a href=
|
||||
"#TypeWrapper-concept">TypeWrapper</a>, a member function invocation of
|
||||
the form
|
||||
<pre>
|
||||
x.<i>some_function</i>(<i>a<small>1</small>, a<small>2</small>,...a<small>n</small></i>)
|
||||
</pre>
|
||||
always has semantics equivalent to:
|
||||
<pre>
|
||||
<a href=
|
||||
"extract.html#extract-spec">extract</a><R>(x.attr("<i>some_function</i>")(<a
|
||||
href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>1</small></i>), <a
|
||||
href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>2</small></i>),...<a
|
||||
href="object.html#object-spec-ctors">object</a>(<i>a<small>n</small></i>)))()
|
||||
</pre>
|
||||
When the <code>R</code> is an <a href=
|
||||
"#TypeWrapper-concept">TypeWrapper</a>, the result type may be
|
||||
constructed by taking direct posession of:
|
||||
<pre>
|
||||
x.attr("<i>some_function</i>")(<a href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>1</small></i>), <a
|
||||
href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>2</small></i>),...<a
|
||||
href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>n</small></i>)).ptr()
|
||||
</pre>
|
||||
[see <a href="#caveat">caveat</a> below]
|
||||
|
||||
<h3><a name="TypeWrapper-concept"></a>TypeWrapper Concept</h3>
|
||||
TypeWrapper is a refinement of ObjectWrapper which is associated with a
|
||||
particular Python type <code>X</code>. For a given TypeWrapper
|
||||
<code>T</code>, a valid constructor expression
|
||||
<pre>
|
||||
T(<i>a<small>1</small>, a<small>2</small>,...a<small>n</small></i>)
|
||||
</pre>
|
||||
builds a new <code>T</code> object managing the result of invoking
|
||||
<code>X</code> with arguments corresponding to
|
||||
<pre>
|
||||
<a href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>1</small></i>), <a
|
||||
href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>2</small></i>),...<a
|
||||
href=
|
||||
"object.html#object-spec-ctors">object</a>(<i>a<small>n</small></i>)
|
||||
</pre>
|
||||
|
||||
When used as arguments to wrapped C++ functions, or as the template
|
||||
parameter to <code><a
|
||||
href="extract.html#extract-spec">extract</a><></code>, only
|
||||
instances of the associated Python type will be considered a match.
|
||||
|
||||
<h3><a name="caveat">Caveat</a></h3>
|
||||
The upshot of the special member function invocation rules when the
|
||||
return type is a TypeWrapper is that it is possible for the returned
|
||||
object to manage a Python object of an inappropriate type. This is not
|
||||
usually a serious problem; the worst-case result is that errors will be
|
||||
detected at runtime a little later than they might otherwise be. For an
|
||||
example of how this can occur, note that the <code><a href=
|
||||
"dict.html#dict-spec">dict</a></code> member function <code>items</code>
|
||||
returns an object of type <code><a href=
|
||||
"list.html#list-spec">list</a></code>. Now suppose the user defines this
|
||||
<code>dict</code> subclass in Python:
|
||||
<pre>
|
||||
>>> class mydict(dict):
|
||||
... def items(self):
|
||||
... return tuple(dict.items(self)) # return a tuple
|
||||
</pre>
|
||||
Since an instance of <code>mydict</code> is also an instance of
|
||||
<code>dict</code>, when used as an argument to a wrapped C++ function,
|
||||
<code><a href="dict.html#dict-spec">boost::python::dict</a></code> can
|
||||
accept objects of Python type <code>mydict</code>. Invoking
|
||||
<code>items()</code> on this object can result in an instance of <code><a
|
||||
href="list.html#list-spec">boost::python::list</a></code> which actually
|
||||
holds a Python tuple. Subsequent attempts to use list methods (e.g.
|
||||
<code>append</code>, or any other mutating operation) on this object will
|
||||
raise the same exception that would occur if you tried to do it from
|
||||
Python.
|
||||
<hr>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
||||
30 Sept, 2002 <!--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>
|
||||
|
||||
<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>
|
||||
|
||||
103
doc/v2/args.html
Normal file
103
doc/v2/args.html
Normal file
@@ -0,0 +1,103 @@
|
||||
<!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/args.hpp></title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<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 <boost/python/args.hpp></h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
|
||||
<h2>Contents</h2>
|
||||
|
||||
<dl class="page-index">
|
||||
<dt><a href="#introduction">Introduction</a></dt>
|
||||
|
||||
<dt><a href="#keyword-expression"><i>keyword-expressions</i></a></dt>
|
||||
|
||||
<dt><a href="#functions">Functions</a></dt>
|
||||
|
||||
<dd>
|
||||
<dl class="page-index">
|
||||
<dt><code><a href=
|
||||
"#args-spec">args</a>(</code>...<code>)</code></dt>
|
||||
</dl>
|
||||
</dd>
|
||||
|
||||
<dt><a href="#examples">Example(s)</a></dt>
|
||||
</dl>
|
||||
<hr>
|
||||
|
||||
<h2><a name="introduction"></a>Introduction</h2>
|
||||
|
||||
<p>Supplies a family of overloaded functions for specifying argument
|
||||
keywords for wrapped C++ functions.</p>
|
||||
|
||||
<h2><a name="keyword-expression"></a><i>keyword-expressions</i></h2>
|
||||
|
||||
<p>A <b>keyword-expression</b> results in an object which holds a
|
||||
sequence of <a href="definitions.html#ntbs">ntbs</a>es, and whose type
|
||||
encodes the number of keywords specified.</p>
|
||||
|
||||
<h2><a name="functions"></a>Functions</h2>
|
||||
|
||||
<h3><a name="args-spec"></a><code>args(</code>...<code>)</code></h3>
|
||||
<pre>
|
||||
<i>unspecified1</i> args(char const*);
|
||||
<i>unspecified2</i> args(char const*, char const*);
|
||||
.
|
||||
.
|
||||
.
|
||||
<i>unspecifiedN</i> args(char const*, char const*, ... char const*);
|
||||
</pre>
|
||||
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Requires:</b> Every argument must be a <a href=
|
||||
"definitions.html#ntbs">ntbs</a>.</dt>
|
||||
|
||||
<dt><b>Returns:</b> an object representing a <a href=
|
||||
"#keyword-expression"><i>keyword-expression</i></a> encapsulating the
|
||||
arguments passed.</dt>
|
||||
</dl>
|
||||
|
||||
<h2><a name="examples"></a>Example</h2>
|
||||
<pre>
|
||||
#include <boost/python/def.hpp>
|
||||
using namespace boost::python;
|
||||
|
||||
int f(int x, int y, int z);
|
||||
|
||||
BOOST_PYTHON_MODULE_INIT(xxx)
|
||||
{
|
||||
def("f", f, args("x", "y", "z"));
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>Revised 05 November, 2001</p>
|
||||
|
||||
<p><i>© Copyright <a href=
|
||||
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
|
||||
Reserved.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -247,7 +247,7 @@
|
||||
namespace boost { namespace python
|
||||
{
|
||||
template <class T
|
||||
<font color="#007F00"> , class Bases = bases<>
|
||||
<font color="#007F00"> , class Bases = bases<>
|
||||
, class HeldType = T
|
||||
, class NonCopyable = <i>unspecified</i>
|
||||
>
|
||||
@@ -742,23 +742,26 @@ template <class Policies>
|
||||
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>
|
||||
<blockquote>
|
||||
<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>keywords:</b> A <a href=
|
||||
"args.html#keyword-expression">keyword-expression</a> which will be
|
||||
used to name (a trailing subsequence 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>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>
|
||||
<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>
|
||||
</blockquote>
|
||||
|
||||
<h3><a name="optional-spec"></a>Class template <code>optional<T1
|
||||
=</code> <i>unspecified</i><code>, T2 =</code>
|
||||
|
||||
108
doc/v2/faq.html
108
doc/v2/faq.html
@@ -1,39 +1,75 @@
|
||||
<!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 - FAQ</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 - FAQ</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">Frequently Asked Questions (FAQs)</h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#question1">{{question}}</a></dt>
|
||||
<dt><a href="#question2">{{question}}</a></dt>
|
||||
</dl>
|
||||
<h2><a name="question1"></a>{{question}}</h2>
|
||||
<p>{{answer}}</p>
|
||||
<h2><a name="question2"></a>{{question}}</h2>
|
||||
<p>{{answer}}</p>
|
||||
<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>© 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">Frequently Asked Questions (FAQs)</h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
|
||||
<dl class="page-index">
|
||||
<dt><a href="#question1">{{question}}</a></dt>
|
||||
|
||||
<dt><a href="#question2">{{question}}</a></dt>
|
||||
</dl>
|
||||
|
||||
<h2><a name="question1"></a>Is return_internal reference efficient?</h2>
|
||||
|
||||
<blockquote>
|
||||
<b>Q:</b> <i>I have an object composed of 12 doubles. A const& to this object is
|
||||
returned by a member function of another class. From the viewpoint of
|
||||
using the returned object in Python I do not care if I get a copy or a
|
||||
reference to the returned object. In Boost.Python Version 2 I have the
|
||||
choice of using copy_const_reference or return_internal_reference. Are
|
||||
there considerations that would lead me to prefer one over the other,
|
||||
such as size of generated code or memory overhead?</i>
|
||||
|
||||
<p><b>A:</b> copy_const_reference will make an instance with storage for one of
|
||||
your objects, size = base_size + 12 * sizeof(double).
|
||||
return_internal_reference will make an instance with storage for a
|
||||
pointer to one of your objects, size = base_size + sizeof(void*).
|
||||
However, it will also create a weak reference object which goes in the
|
||||
source object's weakreflist and a special callback object to manage the
|
||||
lifetime of the internally-referenced object. My guess?
|
||||
copy_const_reference is your friend here, resulting in less overall
|
||||
memory use and less fragmentation, also probably fewer total cycles.</p>
|
||||
</blockquote>
|
||||
|
||||
<h2><a name="question2"></a>{{question}}</h2>
|
||||
|
||||
<p>{{answer}}</p>
|
||||
<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>© Copyright <a href=
|
||||
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
|
||||
Reserved.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user