diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2013-06-25 22:59:01 +0000 |
|---|---|---|
| committer | <> | 2013-09-27 11:49:28 +0000 |
| commit | 8c4528713d907ee2cfd3bfcbbad272c749867f84 (patch) | |
| tree | c09e2ce80f47b90c85cc720f5139089ad9c8cfff /libs/python/doc/v2 | |
| download | boost-tarball-baserock/morph.tar.gz | |
Imported from /home/lorry/working-area/delta_boost-tarball/boost_1_54_0.tar.bz2.boost_1_54_0baserock/morph
Diffstat (limited to 'libs/python/doc/v2')
83 files changed, 20310 insertions, 0 deletions
diff --git a/libs/python/doc/v2/Apr2002.html b/libs/python/doc/v2/Apr2002.html new file mode 100644 index 000000000..62350defa --- /dev/null +++ b/libs/python/doc/v2/Apr2002.html @@ -0,0 +1,166 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - April 2002 Progress Report</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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">April 2002 Progress Report</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="index"> + <dt><a href="#accomplishments">Accomplishments</a></dt> + <dl class="index"> + <dt><a href="#arity">Arbitrary Arity Support</a></dt> + <dt><a href="#callbacks">New Callback Interface</a></dt> + <dt><a href="#policies">Call Policies for Construtors</a></dt> + <dt><a href="#bugs">Real Users, Real Bugs</a></dt> + <dt><a href="#insights">New Insights</a></dt> + <dt><a href="#v1">Boost.Python V1 Maintenance</a></dt> + </dl> + + <dt><a href="#missing">What's Missing</a></dt> + +</dl> + +<h2><a name="accomplishments">Accomplishments</a></h2> + +April was a short month as far as Boost.Python was concerned, since +the spring ISO C++ Committee Meeting (and associated vacation) +occupied me for the 2nd half of the month. However, a suprising amount +of work got done... + +<h3><a name="arity">Arbitrary Arity Support</a></h3> + +I began using the <a +href="../../../preprocessor/doc/index.html">Boost.Preprocessor</a> +metaprogramming library to generate support for functions and member +functions of arbitrary arity, which was, to say the least, quite an +adventure. The feedback cycle resulting from my foray into +Boost.Preprocessor resulted in several improvements to the library, +most notably in its documentation. + +<p> + +Boost.Python now supports calls of up to 17 arguments on most +compilers. Because most EDG-based compilers have dismal preprocessor +performance, I had to "manually" expand the metaprograms for +arities from zero to fifteen arguments, and EDG-based compilers with +<code>__EDG_VERSION__ <= 245</code> only support 15 +arguments by default. If some crazy program finds a need for more than +the default arity support, users can increase the base support by +setting the <code>BOOST_PYTHON_MAX_ARITY</code> preprocessor symbol. + +<h3><a name="callbacks">New Callback Interface</a></h3> + +I mentioned in <a href="Mar2002.html">last month's report</a> that I +wasn't pleased with the interface for the interface for calling into +Python, so now it has been redesigned. The new interface is outlined +in <a +href="http://mail.python.org/pipermail/c++-sig/2002-April/000953.html">this +message</a> (though the GCC 2.95.3 bugs have been fixed). + +<h3><a name="policies">Call Policies for Constructors</a></h3> + +On April 2nd, I <a +href="http://mail.python.org/pipermail/c++-sig/2002-April/000916.html">announced</a> +support for the use of call policies with constructors. + +<h3><a name="bugs">Real Users, Real Bugs</a></h3> + +At least two people outside of Kull began actually using Boost.Python +v2 in earnest this month. Peter Bienstman and Pearu Pearson both +provided valuable real-world bug reports that helped me to improve the +library's robustness. + +<h3><a name="insights">New Insights</a></h3> + +<a +href="http://mail.python.org/pipermail/c++-sig/2002-May/001010.html" +>Answering some of Pearu's questions</a> about explicitly converting +objects between Python and C++ actually led me to a new understanding +of the role of the current conversion facilities. In Boost.Python v1, +all conversions between Python and C++ were handled by a single family +of functions, called <code>to_python()</code> and +<code>from_python()</code>. Since the primary role of Boost.Python is +to wrap C++ functions in Python, I used these names for the first kind +of converters I needed: those that extract C++ objects to be used as +function arguments and which C++ function return values to +Python. The better-considered approach in Boost.Python v2 uses a +completely different mechanism for conversions used when calling +Python from C++, as in wrapped virtual function implementations. I +usually think of this as a "callback", as in "calling +back into Python", and I named the converters used in callbacks +accordingly: <code>to_python_callback</code> and +<code>from_python_callback</code>. However, as it turns out, the +behavior of the "callback" converters is the appropriate one +for users who want to explicitly extract a C++ value from a Python +object, or create a Python object from a C++ value. The upshot is that +it probably makes sense to change the name of the existing <code>to_python</code> and +<code>from_python</code> so those names are available for the +user-friendly explicit converters. + +<p> +<a +href="http://mail.python.org/pipermail/c++-sig/2002-May/001013.html">Another +of Pearu's questions</a> pushes momentum further in the direction of a +more-sophisticated overloading mechanism than the current +simple-minded "first match" approach, as I suggested <a +href="Mar2002.html#implicit_conversions">last month</a>. + +<h3><a name="v1">Boost.Python V1 Maintenance</a></h3> + +As much as I'm looking forward to retiring Boost.Python v1, a +significant amount of effort has been being spent dealing with support +problems; the saying that code rots when left alone is true, and +Boost.Python is no exception. Eventually it became obvious to me that +we were going to have to invest some effort in keeping V1 healthy +while working on V2. Ralf and I have expanded support for various +compilers and stabilized the V1 codebase considerably. We discarded +the obsolete Visual Studio projects which were causing so much +confusion. Still to do before the next Boost release: +<ol> +<li>Update the build/test documentation with detailed instructions for +configuring various toolsets. +<li>Provide some links to Boost.Python v2 to let people know what's +coming. +</ol> + + +<h2><a name="missing">What's Missing</a></h2> + +Last month I announced that I would implement the following which are +not yet complete: +<ol> +<li>Document all implemented features +<li>Implement conversions for <code>char</code> types. This is +implemented but not tested, so we have to assume it doesn't work. +</ol> + +These are my first priority for this month (especially the +documentation). + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> diff --git a/libs/python/doc/v2/CallPolicies.html b/libs/python/doc/v2/CallPolicies.html new file mode 100644 index 000000000..06384a23d --- /dev/null +++ b/libs/python/doc/v2/CallPolicies.html @@ -0,0 +1,165 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - 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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></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> + + <dd> + <dl class="page-index"> + <dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt> + </dl> + </dd> + </dl> + + <h2><a name="introduction"></a>Introduction</h2> + + <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> + + <ol> + <li><code>precall</code> - Python argument tuple management before the + wrapped object is invoked</li> + + <li><code>result_converter</code> - C++ return value handling</li> + + <li><code>postcall</code> - Python argument tuple and result management + after the wrapped object is invoked</li> + <li><code>extract_return_type</code> - metafunction for extracting the return type from a given signature type sequence</li> + </ol> + + <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>. + + + <h2><a name="concept-requirements"></a>Concept Requirements</h2> + + <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>() != 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/refmanual/metafunction-class.html">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>() != 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> + <tr> + <td valign="top"><code>P::extract_return_type</code></td> + + <td>A model of <a href= + "../../../mpl/doc/refmanual/metafunction.html">Metafunction</a>.</td> + + <td>An MPL unary <a href= + "../../../mpl/doc/refmanual/metafunction.html">Metafunction</a> used extract the return type from a given signature. By default it is derived from mpl::front.</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 --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</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> + diff --git a/libs/python/doc/v2/Dereferenceable.html b/libs/python/doc/v2/Dereferenceable.html new file mode 100644 index 000000000..f7c53fd23 --- /dev/null +++ b/libs/python/doc/v2/Dereferenceable.html @@ -0,0 +1,74 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Dereferenceable 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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Dereferenceable Concept</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> + <dl class="page-index"> + <dt><a href="#Dereferenceable-concept">Dereferenceable Concept</a></dt> + </dl> +</dl> + +<h2><a name="introduction"></a>Introduction</h2> + +<p>Instances of a Dereferenceable type can be used like a pointer to access an lvalue. + +<h2><a name="concept-requirements"></a>Concept Requirements</h2> +<h3><a name="Dereferenceable-concept"></a>Dereferenceable Concept</h3> + +<p>In the table below, <code><b>T</b></code> is a model of +Dereferenceable, and <code><b>x</b></code> denotes an object of +type <code>T</code>. In addition, all pointers are Dereferenceable. + +<table summary="Dereferenceable expressions" border="1" cellpadding="5"> + + <tr> + <td><b>Expression</b></td> + <td><b>Result</b></td> + <td><b>Operational Semantics</b></td> + </tr> + + <tr> + <td><code>get_pointer(x)</code></td> + <td>convertible to <code><a href="pointee.html#pointee-spec">pointee</a><T>::type*</code> + <td><code>&*x</code>, or a null pointer + </tr> +<tr> + +</table> + +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 18 December, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002-2003. </i> + +<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> +</html> diff --git a/libs/python/doc/v2/Extractor.html b/libs/python/doc/v2/Extractor.html new file mode 100644 index 000000000..441ca38b3 --- /dev/null +++ b/libs/python/doc/v2/Extractor.html @@ -0,0 +1,96 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Extractor 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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Extractor Concept</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> + <dl class="page-index"> + <dt><a href="#Extractor-concept">Extractor Concept</a></dt> + </dl> + <dt><a href="#notes">Notes</a></dt> +</dl> + +<h2><a name="introduction"></a>Introduction</h2> + +<p>An Extractor is a class which Boost.Python can use to extract C++ +objects from Python objects, and is typically used by facilities that +define <code>from_python</code> conversions for +"traditional" Python extension types. + +<h2><a name="concept-requirements"></a>Concept Requirements</h2> +<h3><a name="Extractor-concept"></a>Extractor Concept</h3> + +<p>In the table below, <code><b>X</b></code> denotes a model of +Extractor and <code><b>a</b></code> denotes an instance of a Python +object type. + +<table summary="Extractor expressions" border="1" cellpadding="5"> + + <tr> + <td><b>Expression</b></td> + <td><b>Type</b></td> + <td><b>Semantics</b></td> + </tr> + + <tr> + <td valign="top"><code>X::execute(a)</code></td> + <td>non-void + <td>Returns the C++ object being extracted. The + <code>execute</code> function must not be overloaded. + </tr> + + <tr> + <td valign="top"><code>&a.ob_type</code> + <td><code><a + href="http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>**</code> + <td>Points to the <code>ob_type</code> field of an object which is + layout-compatible with <code>PyObject</code> + </tr> + + </tr> + +</table> + +<h2><a name="notes"></a>Notes</h2> + +Informally, an Extractor's <code>execute</code> member must be a +non-overloaded static function whose single argument is a Python +object type. Acceptable Python object types include those publicly (and +unambiguously) derived from <code>PyObject</code>, and POD types which +are layout-compatible with PyObject. + +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> + +<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> +</html> diff --git a/libs/python/doc/v2/HolderGenerator.html b/libs/python/doc/v2/HolderGenerator.html new file mode 100644 index 000000000..58b4265af --- /dev/null +++ b/libs/python/doc/v2/HolderGenerator.html @@ -0,0 +1,74 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Holder 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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">HolderGenerator Concept</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> + <dl class="page-index"> + <dt><a href="#HolderGenerator-concept">HolderGenerator Concept</a></dt> + </dl> +</dl> + +<h2><a name="introduction"></a>Introduction</h2> + +<p>A HolderGenerator is a unary metafunction class which returns types +suitable for holding instances of its argument in a wrapped C++ class +instance. + +<h2><a name="concept-requirements"></a>Concept Requirements</h2> +<h3><a name="HolderGenerator-concept"></a>HolderGenerator Concept</h3> + +<p>In the table below, <code><b>G</b></code> denotes an type which +models HolderGenerator, and <code><b>X</b></code> denotes a class +type. + +<table summary="Holder expressions" border="1" cellpadding="5"> + + <tr> + <td><b>Expression</b></td> + <td><b>Requirements</b></td> + </tr> + + <tr> + <td valign="top"><code>G::apply<X>::type</code></td> + <td>A concrete subclass of <a + href="instance_holder.html#instance_holder-spec">instance_holder</a> + which can hold objects of type <code>X</code>. + </tr> +</table> + +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> + +<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> +</html> diff --git a/libs/python/doc/v2/Jun2002.html b/libs/python/doc/v2/Jun2002.html new file mode 100644 index 000000000..db1fc25c6 --- /dev/null +++ b/libs/python/doc/v2/Jun2002.html @@ -0,0 +1,229 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - June 2002 Progress Report</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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">June 2002 Progress Report</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="index"> + <dt><a href="#intro">Introduction</a></dt> + <dt><a href="#handle"><code>handle<T></code></a></dt> + <dt><a href="#object"><code>object</code></a></dt> + <dl class="index"> + <dt><a href="#operators"><code>object</code> operators</a></dt> + <dt><a href="#conversions"><code>object</code> conversions</a></dt> + </dl> + <dt><a href="#list"><code>list</code></a></dt> + <dt><a href="#numerics"><code>Numerics</code></a></dt> + <dt><a href="#community">Community</a></dt> + <dt><a href="#next">What's Next</a></dt> +</dl> + +<h2><a name="intro">Introduction</a></h2> + +July was mostly focused on allowing expressive manipulation of +individual Python objects, or what Ralf Grosse-Kunstleve calls +"Writing Python in C++". The work began with this <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">posting</a>, +which outlines the issues and intention. + +<h2><a name="handle"><code>handle<T></code></a></h2> + +The most basic element needed was a replacement for the +<code>reference<></code> class template and the +<code>ref</code> typedef from Boost.Python v1, a simple smart +pointer to a Python object. The old v1 typedef +"<code>ref</code>" (for +<code>reference<PyObject></code>) had to be retired because I +thought it would be too confusing given the importance of <code><a +href="../../../bind/ref.html">boost::ref</a>()</code> to this +library. I began a <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001311.html">discussion</a>of +possible names, and it was eventually <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001337.html">decided</a> +to rename <code>reference</code> to <code>handle</code> and supply a +default argument so that <code>ref</code> could be spelled +<code>handle<></code> without an additional typedef. There +were also some interface changes to make it safer and more-efficient +to interface with the raw +<code>PyObject*</code>s forced on us by Python's 'C' API. A +discussion of those protocols can be found <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001401.html">here</a>. + +<h2><a name="handle"><code>object</code></a></h2> + +It is intended that users will seldom need or want to work with +<code>handle<></code>; its major distinguishing features are +that it gives direct access to the underlying object representation +through <code>operator*</code> and <code>operator-></code>, and +that can be <code>NULL</code>, both sources of danger. Instead the +library provides a class called <code>object</code>, which +encapsulates a valid Python object and provides a similar interface to +Python's. + +<h3><a name="operators"><code>object</code> operators</a></h3> + +The first challenge was to provide support for object manipulations +using a Python-like syntax, mostly in the form of operator overloads: + +<table border="1"> +<tr><th>Python <th>C++ + +<tr> + <td><code>y = x.foo</code> <td><code>y = x.attr("foo"); +<tr> + <td><code>x.foo = 1</code> <td><code>x.attr("foo") = 1; + +<tr> + <td><code>y = x[z]</code> <td><code>y = x[z]; +<tr> + <td><code>x[z] = 1</code> <td><code>x[z] = 1; + +<tr> + <td><code>y = x[3:-1]</code> <td><code>y = x.slice(3,-1); + +<tr> + <td><code>y = x[3:]</code> <td><code>y = x.slice(3,_); + +<tr> + <td><code>y = x[:-2]</code> <td><code>y = x.slice(_,-2); + +<tr> + <td><code>z = x(1, y)</code> <td><code>z = x(1, y); +<tr> + <td><code>z = x.f(1, y)</code> <td><code>z = x.attr("f")(1, y); + +<tr> + <td><code>not x</code> <td><code>!x + +<tr> + <td><code>x and y</code> <td><code>x and y +</table> + +I'm still a unsatisfied with the interface for attribute access. There +original proposal used a syntax like this one: +<pre> +y = x._("foo"); +x._("foo") = 1; +</pre> + +which was only marginally better than what we've got. Niki Spahiev +then <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001447.html">pointed +out</a> a potential conflict with the macro which GNU Gettext <a +href="http://www.gnu.org/manual/gettext/html_mono/gettext.html#SEC6">suggests</a> +people define. This unfortunate state of affairs forced us into using +<code>attr</code> instead. I'd still like to find a better interface, +but the lack of overloadable C++ operators which aren't already used +in Python is an obstacle. The comma operator is still a possibility, +but it has the wrong precedence: +<pre> +y = x,"foo" // error +x,"foo" = 1; // error + +y = (x,"foo"); // ok +(x,"foo") = 1; // ok +</pre> + +Well, I guess we could consider adding that to the interface without +removing <code>attr()</code>, to see how it plays out... + +<h3><a name="operators"><code>object</code> conversions</a></h3> + +The <code>object</code> class also provided an opportunity to replace +Boost.Python v1's <code>to_python()</code> as a user-level +interface. Instead, <code>object</code> has a templated constructor +which can be used to convert any C++ object to Python using the same +underlying mechanisms used for the arguments to <code><a +href="call.html">call</a><></code>. + +<p>Incidentally, the implementation of operator and conversion support +for object uncovered an inordinate number of compiler bugs in our +targeted platforms. It was a lot more "interesting" than it +should have been. + +<h2><a name="list"><code>list</code></a></h2> + +With <code>object</code> implemented, it was time to begin replacing +the ad-hoc implementations of <code>list</code>, <code>string</code>, +and <code>dictionary</code> supplied by Boost.Python v1 with something +more robust. I started with <code>list</code> as an example. Because +<code>object</code> already provides all of the requisite operators, +publicly deriving <code>list</code> from object seemed like a good +choice. The remaining issues were what do do about the one-argument +list constructor (which in Python attempts to convert its argument to +a list), and how to deal converting with <code>list</code> arguments +to wrapped functions. Some of the issues are laid out in <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001551.html">this +thread</a>. Ultimately, it was decided that <code>list(x)</code> +should do the same thing in C++ as in Python (conversion), while +<code>list</code> arguments should only match Python +<code>list</code>s (and <code>list</code> subclasses). The +implementation worked well, and provided a <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001586.html">roadmap</a> +for the protocol to be used for implementation of the other built-in +types. + +<h2><a name="numerics">Numerics</a></h2> + +Support for C++ <code>long long</code> and <code>unsigned long +long</code> +(and <code>__int64</code> on MSVC) to/from python conversions was +added this month. We also improved handling of numeric overflows when +converting, e.g., a Python int to a type with a more limited range of +representation. + +<h2><a name="community">Community</a></h2> + +<ul> +<li>Ralf W. Grosse-Kunstleve and Nick Sauter have implemented +<a href="http://cci.lbl.gov/boost/">multiplatform nightly +build-and-test</a> runs for Boost.Python V2 at LBL. + +<li>Dave Hawkes has made significant progress on generating the +Python <a +href="http://mail.python.org/pipermail/c++-sig/2002-June/001503.html">built-in +function and API wrappers</a> + +<li>Achim Domma has agreed to take up the job of implementing the +<code>str</code>, <code>dict</code>, and <code>tuple</code> classes. +</ul> + +Deep thanks to all the Boost.Python contributors! This project +wouldn't be possible without your participation. + + <h2><a name="next">What's Next</a></h2> + +As I write this we are already well into the month of July, so I +suggest you consult the <a +href="http://mail.python.org/pipermail/c++-sig/2002-July/">Mailing +List Archive</a> if you want to know what's been happening. Otherwise +you'll just have to wait till next month (hopefully the beginning). + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> diff --git a/libs/python/doc/v2/Mar2002.html b/libs/python/doc/v2/Mar2002.html new file mode 100644 index 000000000..97444d229 --- /dev/null +++ b/libs/python/doc/v2/Mar2002.html @@ -0,0 +1,237 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - March 2002 Progress Report</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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">March 2002 Progress Report</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="index"> + <dt><a href="#accomplishments">Accomplishments</a></dt> + <dl class="index"> + <dt><a href="#calling_python">Calling Python from C++</a></dt> + <dt><a href="#virtual_functions">Virtual Functions</a></dt> + <dt><a href="#abstract_classes">Abstract Classes</a></dt> + <dt><a href="#implicit_conversions">C++ Implicit Conversions</a></dt> + <dt><a href="#data_members">C++ Data Members</a></dt> + <dt><a href="#miscellaneous">Miscellaneous</a></dt> + </dl> + + <dt><a href="#future">The Near future</a></dt> + + <dt><a href="#notes">Notes</a></dt> + +</dl> + +<h2><a name="accomplishments">Accomplishments</a></h2> + +March was mostly devoted to the reimplementation of features from +Boost.Python v1, and some new features. Re-examination of the features +from Boost.Python v1 allowed me to make significant improvements. + +<h3><a name="calling_python">Calling Python from C++</a></h3> + +The ability to call Python from C++ is crucial for virtual function +support. Implementing this feature well for V2 proved to be more +interesting than I expected. You can review most of the relevant +design decisions +<a href="callbacks.txt">here</a>. + +<p> +One point which <i>isn't</i> emphasized in that document is that there +are subtle differences in the way <code>from_python</code> conversions +work when used for C++ function arguments and Python function return +values. In particular, while <code>T const&</code> arguments may +invoke rvalue converters, a reference-to-const return value requires +an lvalue converter, since a temporary conversion result would leave +the returned reference dangling. + +<p>I'm not particularly pleased with the current callback interface, +since it usually results in constructs like: +<pre> +<u>return returning</u><X&>::call(f, obj); +</pre> +However, I think the following may be possible and I plan to investigate: +<pre> +return apply<X&>(f, obj); +</pre> +I'm open to suggestion for better names (and syntaxes)! + +<h3><a name="virtual_functions">Virtual Functions</a></h3> + +Once Python callbacks were implemented, it was just a short step to +implementing virtual functions. Python extension class exposing a C++ +class whose virtual functions are overridable in Python must actually +hold a C++ instance of a class <i>derived</i> from the one exposed to +Python. Needing some way for users to specify that class, I added an +optional template argument to <code>value_holder_generator</code> and +<code>pointer_holder_generator<></code> to specify the class +actually held. This move began to put pressure on the +<code>class_<></code> interface, since the need for the user to +produce complicated instantations of +<code>class_<></code> was increased: + +<pre> +class<Foo, bases<>, value_holder_generator<Foo_callback> >("Foo") +.def("hello", &Foo::hello) +... +</pre> + +<h3><a name="abstract_classes">Abstract Classes</a></h3> + +Normally when a C++ class is exposed to Python, the library registers +a conversion function which allows users to wrap functions returning +values of that type. Naturally, these return values are temporaries, +so the conversion function must make a copy in some +dynamically-allocated storage (a "holder") which is managed +by the corresponding Python object. + +<p>Unfortunately, in the case of abstract classes (and other types +without a publicly-accessible copy constructor), instantiating this +conversion function causes a compilation error. In order to support +non-copyable classes, there had to be some way to prevent the library +from trying to instantiate the conversion function. The only practical +approach I could think of was to add an additional template parameter +to the <code>class_<></code> interface. When the number of +template parameters with useful defaults begins to grow, it is often +hard to choose an order which allows users to take advantage of the +defaults. + +<p> + +This was the straw that broke the +<code>class_<></code> interface's back and caused the redesign +whose outcome is detailed <a +href="http://mail.python.org/pipermail/c++-sig/2002-March/000892.html">here</a>. +The approach allows the user to supply the optional parameters in an +arbitrary order. It was inspired by the use of <a +href="../../../utility/iterator_adaptors.htm#named_tempalte_parameters">named +template parameters</a> in the <a +href="../../../utility/iterator_adaptors.htm">Boost Iterator Adaptor +Library</a>, though in this case it is possible to deduce the meaning +of the template parameters entirely from their type properties, +resulting in a simpler interface. Although the move from a +policy-based design to what resembles a configuration DSL usually +implies a loss of flexibility, in this case I think any costs are far +outweighed by the advantages. + +<p>Note: working around the limitations of the various compilers I'm +supporting was non-trivial, and resulted in a few messy implementation +details. It might be a good idea to switch to a more-straightforward +approach once Metrowerks CodeWarrior Pro8 is released. + +<h3><a name="implicit_conversions">C++ Implicit Conversions</a></h3> + +Support for C++ implicit conversion involves creating +<code>from_python</code> converters for a type <code>U</code> which in +turn use <code>from_python</code> converters registered for a type +<code>T</code> where there exists a implicit conversion from +<code>T</code> to <code>U</code>. The current implementation is +subject to two inefficiencies: +<ol> + +<li>Because an rvalue <code>from_python</code> converter produces two +pieces of data (a function and a <code>void*</code>) from its +<code>convertible()</code> function, we end up calling the function +for <code>T</code> twice: once when the converter is looked up in the +registry, and again when the conversion is actually performed. + +<li>A vector is used to mark the "visited" converters, preventing +infinite recursion as <code>T</code> to +<code>U</code> and <code>U</code> to <code>T</code> converters +continually search through one-another. + +</ol> + +I consider the former to be a minor issue. The second may or may not +prove to be computationally significant, but I believe that +architecturally, it points toward a need for more sophisticated +overload resolution. It may be that we want CLOS-style multimethod +dispatching along with C++ style rules that prevent more than one +implicit conversion per argument. + +<h3><a name="data_members">C++ Data Members</a></h3> + +To supply the ability to directly access data members, I was able to +hijack the new Python <a +href="http://www.python.org/2.2/descrintro.html#property">property</a> +type. I had hoped that I would also be able to re-use the work of <a +href="make_function.html">make_function</a> to create callable python +objects from C++ functions which access a data member of a given +class. C++ facilities for specifying data member pointer non-type +template arguments require the user to explicitly specify the type of +the data member and this under-utilized feature is also not +well-implemented on all compilers, so passing the member pointer as a +runtime value is the only practical approach. The upshot is that any +such entity would actually have to be a function <i>object</i>, and I +haven't implemented automatic wrapping of C++ callable function +objects yet, so there is less re-use in the implementation than I'd +like. I hope to implement callable object wrapping and refactor this +code one day. I also hope to implement static data member support, +for which Python's property will not be an appropriate descriptor. + +<h3><a name="miscellaneous">Miscellaneous</a></h3> +<ul> +<li>Moved <code>args<></code> and <code>bases<></code> from unnamed namespace to <code>boost::python</code> in their own header files. +<li>Convert <code>NULL</code> pointers returned from wrapped C++ functions to <code>None</code>. +<li>Improved some compile-time error checks. +<li>Eliminated <code>boost/python/detail/eval.hpp</code> in favor of +more-general <code>boost/mpl/apply.hpp</code>. +<li>General code cleanup and refactoring. +<li>Works with Microsoft Visual C++ 7.0 +<li>Warning suppression for many compilers +<li>Elegant interface design for exporting <code>enum</code> types. +</ul> +<hr> + +<h2><a name="future">The Near Future</a></h2> + +Before April 15th I plan to +<ol> +<li>Document all implemented features +<li>Implement a <code>CallPolicy</code> interface for constructors of wrapped +classes +<li>Implement conversions for <code>char</code> types. +<li>Implement automated code generation for all headers containing +families of overloaded functions to handle arbitrary arity. +</ol> + +I also hope to implement a mechanism for generating conversions +between arbitrary Python sequences and C++ containers, if time permits +(and others haven't already done it)! + +<h2><a name="notes">Notes</a></h2> + +The older version of KCC used by Kull is generating lots of warnings +about a construct I use to instantiate static members of various class +templates. I'm thinking of moving to an idiom which uses a function +template to suppress it, but worry about bloating the size of debug +builds. Since KCC users may be moving to GCC, I'm not sure that it's +worth doing anything about it. + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> diff --git a/libs/python/doc/v2/May2002.html b/libs/python/doc/v2/May2002.html new file mode 100644 index 000000000..5e5b6aaa4 --- /dev/null +++ b/libs/python/doc/v2/May2002.html @@ -0,0 +1,311 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - May 2002 Progress Report</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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">May 2002 Progress Report</h2> + </td> + </tr> +</table> +<hr> +<h2>Contents</h2> +<dl class="index"> + <dt><a href="#intro">Introduction</a></dt> + <dt><a href="#features">New Features</a></dt> + <dl> + <dt><a href="#aix_shared">Shared Library Support for AIX</a><dd> + <dt><a href="#class_enhancements">Class Enhancements</a><dd> + <dl> + <dt><a href="#operators">Operators</a><dd> + <dt><a href="#iterators">Iterators</a><dd> + <dt><a href="#properties">Properties</a><dd> + <dt><a href="#setattr">setattr</a><dd> + <dt><a href="#module">__module__ Attribute</a><dd> + </dl> + <dt><a href="#back_reference">back_reference</a><dd> + </dl> + + <dt><a href="#documentation">Documentation</a></dt> + <dt><a href="#misc">Miscellaneous</a></dt> + <dl class="index"> + <dt><a href="#converters">Converters</a></dt> + <dt><a href="#checkins">Checkins Mailing List</a></dt> + <dt><a href="#shared">Shared Libraries</a></dt> + </dl> + + <dt><a href="#next">What's Next</a></dt> +</dl> + +<h2><a name="intro">Introduction</a></h2> + +Aside from library development, work on Boost.Python in May was +focused on reducing the support burden. In recent weeks, responding to +requests for support, espcially surrounding building the library, had +begun to impede progress on development. There was a major push to +release a stable 1.28.0 of Boost, including documentation of <a +href="../../../../tools/build/v1/build_system.htm">Boost.Build</a> and specific +<a href="../building.html">instructions</a> for building Boost.Python +v1. The documentation for Boost.Python v2 was also updated as +described <a href="#documentation">here</a>. + +<h2><a name="features">New Features</a></h2> + + <h3><a name="aix_shared">Shared Library Support for AIX</a></h3> + + The Kull group required the ability to build and test Boost.Python + extensions on AIX, a platform with "creatively designed" + shared library semantics. Making this work was a multi-pronged + effort, involving changes to Boost.Build and some great research by + Martin Casado which uncovered the key mechanism required to allow + shared libraries to use functions from the Python executable. The + current solution used in Boost.Build relies on a <a + href="../../../../tools/build/v1/gen_aix_import_file.py">Python + Script</a> as part of the build process. This is not a problem for + Boost.Python, as Python will be available. However, the commands + issued by the script are so simple that a 100%-pure-Boost.Jam + solution is surely possible. Linking on AIX is sufficiently + interesting to have skewed the Boost.Python development schedule a + bit. + + <h3><a name="class_enhancements">Class Enhancements</a></h3> + + <h4><a name="operators">Operators</a></h4> + +Support for exposing C++ operators and functions as the corresponding +Python special methods was added. Thinking that the Boost.Python +v1 interface was a little too esoteric (especially the use of +<code>left_operand<...>/right_operand<...></code> for +asymmetric operands), I introduced a simple form of <a +href="http://osl.iu.edu/~tveldhui/papers/Expression-Templates/exprtmpl.html">expression +templates</a> which allow users to simply write the expressions that +should be wrapped, as in this <a href="operators.html#examples">example</a>. + + <h4><a name="iterators">Iterators</a></h4> + +Python iterator support as required by the Kull project resulted in a +highly flexible interface allowing: + +<dl> + +<dt>Direct exposure of a class' <code>begin()</code> and +<code>end()</code> functions: + +<pre> + ... + .def("__iter__", iterator<list_int>()) +</pre> +<dd> + +<dt>Creation of iterators from member functions... +<pre> + ... + .def("__iter__" + , range(&my_class::x_begin, &my_class::x_end)) + ) +</pre> +<dd> + +<dt>...and member data: +<pre> + ... + .def("__iter__" + , range(&std::pair<char*,char*>::first, &std::pair<char*,char*>::second)) + ) +</pre> +<dd> + +<dt>The ability to specify <a +href="CallPolicies.html">CallPolicies</a>, e.g. to prevent copying of +heavyweight values: + +<pre> + ... + .def("__iter__", + , range<return_value_policy<copy_non_const_reference> >( + &my_sequence<heavy>::begin + , &my_sequence<heavy>::end)) +</pre> +<dd> + +</dl> + + <h4><a name="properties">Properties</a></h4> + +The Kull iteration interfaces also required the ability to iterate +over a sequence specified by an instance's attribute: +<pre> +>>> f = field() +>>> for e in f.elements: +... print e, +</pre> + +This forced the exposure of the <a + href="http://www.python.org/2.2/descrintro.html#property"><code>property</code></a> + interface used internally to implement the data member exposure + facility described in <a + href="Mar2002.html#data_members">March</a>. Properties are an + incredibly useful idiom, so it's good to be able to provide them + at little new development cost. + + <h4><a name="setattr">setattr</a></h4> + +<code>class_<></code> acquired a <code>setattr</code> member +function which allows users to easily add new Python objects as class +attributes. + + <h4><a name="module">__module__ Attribute</a></h4> + +Ralf Grosse-Kunstleve has been working on pickling support for v2. To +make it work correctly, he had to make sure that a class' +<code>__module__</code> attribute was set correctly. + +<h3><a name="back_reference"><code>back_reference</code></a></h3> + +The new <code>back_reference<T></code> template can be used as a +function parameter when the user needs access to both a <code>T</code> +argument and to the Python object which manages it. The function will +only match in the overload resolution process if it would match the +same function signature with <code>T</code> substituted for +<code>back_reference<T></code>. This feature is not yet +documented. + +<h2><a name="documentation">Documentation</a></h2> + +In a major effort to prepare Boost.Python v2 to replace v1, many pages +of new reference documentation were added: + +<blockquote> + +<dl> + <dt><a href="CallPolicies.html">CallPolicies.html</a><dd> + <dt><a href="Dereferenceable.html">Dereferenceable.html</a><dd> + <dt><a href="Extractor.html">Extractor.html</a><dd> + <dt><a href="HolderGenerator.html">HolderGenerator.html</a><dd> + <dt><a href="ResultConverter.html">ResultConverter.html</a><dd> + <dt><a href="call_method.html">call_method.html</a><dd> + <dt><a href="callbacks.html">callbacks.html</a><dd> + <dt><a href="data_members.html">data_members.html</a><dd> + <dt><a href="has_back_reference.html">has_back_reference.html</a><dd> + <dt><a href="implicit.html">implicit.html</a><dd> + <dt><a href="instance_holder.html">instance_holder.html</a><dd> + <dt><a href="operators.html">operators.html</a><dd> + <dt><a href="ptr.html">ptr.html</a><dd> + <dt><a href="type_id.html">type_id.html</a><dd> + <dt><a href="with_custodian_and_ward.html">with_custodian_and_ward.html</a><dd> +</dl> + +</blockquote> +Major updates were made to the following pages: + + +<blockquote> +<dl> + <dt><a href="call.html">call.html</a><dd> <dt>updated<dd> + <dt><a href="class.html">class.html</a><dd> + <dt><a href="reference.html">reference.html</a><dd> +</dl> +</blockquote> + + As usual, careful documentation forces one to consider the + interface again, and there were many interface changes + associated with this effort, including the elevation of the + following components from implementation detail to + first-class library citizen: + +<blockquote> +<dl> + <dt>type_id.hpp<dd> + <dt>pointee.hpp<dd> + <dt>lvalue_from_pytype.hpp<dd></dl> +</dl> +</blockquote> + +<h2><a name="misc">Miscellaneous</a></h2> + + <h3><a name="converters">Converters</a></h3> + +It appears that the world of C++ <==> Python conversion rules is +an endlessly-rich area of exploration. Completing the conversions for +<code>char</code> and <code>char const*</code> types, as described at +the end of <a href="Apr2002.html#missing">April's report</a>, +uncovered some interesting new shades to the problem. It turns out to +be worth distinguishing mutable and immutable lvalue conversions, +because despite the fact that Python doesn't understand +<code>const</code>, it does understand immutability (c.f. Python +strings, which expose an immutable <code>char</code> pointer). It is +also worth recognizing types which represent lvalue <i>sequences</i>, +to prevent Python <code>"foobar"</code> from being silently +truncated to C++ <code>'f'</code>. More details on this insight can be +found in the mailing list <a +href="http://mail.python.org/pipermail/c++-sig/2002-May/001023.html"> +archive</a>. I don't plan to do anything about this immediately, but I +do think it's the right direction to go in the long run. + + <h3><a name="checkins">Checkins Mailing List</a></h3> + +In order to better coordinate changes made by multiple developers, I +enabled <a +href="http://sourceforge.net/docman/display_doc.php?docid=772&group_id=1">syncmail</a> +for the Boost.Python CVS trees, and established an associated <a +href="http://lists.sourceforge.net/lists/listinfo/boost-python-cvs">mailing +list</a>. Subscribe to this list to receive notices of each new +checkin. + + <h3><a name="shared">Shared Libraries</a></h3> + +Beyond the vagaries of dynamic linking on AIX, I have been +participating in a more-general discussion of dynamic linking for +C++. Needless to say, C++ dynamic linking is of critical importance to +Boost.Python: all extension modules are normally built as shared +libraries, and Boost.Python extension modules share a common library +as well. + +In fact, there are at least two separate conversations. One +in the C++ standard extensions mailing list concerns what can be +standardized for C++ and shared libraries; the other, mostly on the <a +href="http://gcc.gnu.org/ml/gcc/">gcc</a> mailing list, concerns the +behavior of GCC on Posix/ELF platforms. + +Some of the GCC threads are here: + +<blockquote> +<a +href="http://gcc.gnu.org/ml/gcc/2002-05/msg02002.html">http://gcc.gnu.org/ml/gcc/2002-05/msg02002.html</a><br> +<a +href="http://gcc.gnu.org/ml/gcc/2002-05/msg02945.html">http://gcc.gnu.org/ml/gcc/2002-05/msg02945.html</a><br> +<a href="http://gcc.gnu.org/ml/gcc/2002-05/msg01758.html">http://gcc.gnu.org/ml/gcc/2002-05/msg01758.html</a> +</blockquote> + + <h2><a name="next">What's Next</a></h2> + +Development is focused on what's needed to be able to retire +Boost.Python v1. At the moment, that means deciding the user-friendly +interfaces for to_/from_python conversion, and formally exposing the +Python object smart pointers and object wrapper classes. Quite a few +questions have also been showing up recently about how to embed Python +with Boost.Python, and how to link with it statically; the solutions +to these issues will probably have to be formalized before long. + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> diff --git a/libs/python/doc/v2/ObjectWrapper.html b/libs/python/doc/v2/ObjectWrapper.html new file mode 100644 index 000000000..7962e69fa --- /dev/null +++ b/libs/python/doc/v2/ObjectWrapper.html @@ -0,0 +1,153 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></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 --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/ResultConverter.html b/libs/python/doc/v2/ResultConverter.html new file mode 100644 index 000000000..be53a9b97 --- /dev/null +++ b/libs/python/doc/v2/ResultConverter.html @@ -0,0 +1,124 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - ResultConverter 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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">ResultConverter Concept</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="#ResultConverter-concept">ResultConverter Concept</a></dt> + <dt><a href="#ResultConverterGenerator-concept">ResultConverterGenerator Concept</a></dt> + </dl> + </dd> +</dl> + +<h2><a name="introduction"></a>Introduction</h2> + +<p>A ResultConverter for a type <code>T</code> is a type whose +instances can be used to convert C++ return values of type +<code>T</code> <code>to_python</code>. A ResultConverterGenerator is +an MPL unary metafunction class which, given the return type of a C++ +function, returns a ResultConverter for that type. ResultConverters in +Boost.Python generally inspect library's registry of converters to +find a suitable converter, but converters which don't use the registry +are also possible. + +<h2><a name="concept-requirements"></a>Concept Requirements</h2> +<h3><a name="ResultConverter-concept"></a>ResultConverter Concept</h3> + +<p>In the table below, <code><b>C</b></code> denotes a ResultConverter +type for a type <b><code>R</code></b> , <code><b>c</b></code> denotes +an object of type <code><b>C</b></code> , and <code><b>r</b></code> +denotes an object of type <code><b>R</b></code>. + +<table summary="ResultConverter expressions" border="1" cellpadding="5"> + + <tr> + <td><b>Expression</b></td> + <td><b>Type</b></td> + <td><b>Semantics</b></td> + </tr> + + <tr> + <td valign="top"><code>C c;</code></td> + <td> + <td>Constructs a <code>C</code> object. + </tr> + + <tr> + <td valign="top"><code>c.convertible()</code></td> + <td>convertible to <code>bool</code></td> + <td><code>false</code> iff no conversion from any <code>R</code> value + to a Python object is possible.</td> + </tr> + + <tr> + <td valign="top"><code>c(r)</code></td> + <td>convertible to <code>PyObject*</code></td> + <td>A pointer to a Python object corresponding to <code>r</code>, + or <code>0</code> iff <code>r</code> could not be converted + <code>to_python</code>, in which case <a + href="http://www.python.org/doc/current/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a> + should return non-zero.</td> + </tr> + <tr> + <td valign="top"><code>c.get_pytype()</code></td> + <td><code>PyTypeObject const*</code></td> + <td>A pointer to a Python Type object corresponding to result of the conversion, + or <code>0</code>. Used for documentation generation. If <code>0</code> is returned + the generated type in the documentation will be <b>object</b> .</td> + </tr> +</table> + +<h3><a name="ResultConverterGenerator-concept"></a>ResultConverterGenerator Concept</h3> +<p>In the table below, <code><b>G</b></code> denotes a +ResultConverterGenerator type and <code><b>R</b></code> denotes a possible +C++ function return type. + +<table summary="ResultConverterGenerator expressions" border="1" cellpadding="5"> + <tr> + <td><b>Expression</b></td> + <td><b>Requirements</b></td> + </tr> + <tr> + <td valign="top"><code>G::apply<R>::type</code></td> + <td>A ResultConverter type for <code>R</code>.</td> +</table> + +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 09 May, 2002 <!--Luann's birthday! --> + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> + +<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> +</html> diff --git a/libs/python/doc/v2/acknowledgments.html b/libs/python/doc/v2/acknowledgments.html new file mode 100644 index 000000000..28f1b1dbd --- /dev/null +++ b/libs/python/doc/v2/acknowledgments.html @@ -0,0 +1,135 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Acknowledgments</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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Acknowledgments</h2> + </td> + </tr> + </table> + <hr> + + <p><a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> is + the architect, designer, and implementor of <b>Boost.Python</b>.</p> + + <p><a href="mailto:brett.calcott@paradise.net.nz">Brett Calcott</a> + contributed and maintains the Visual Studio project files and + documentation.</p> + + <p><a href="mailto:Gottfried.Ganssauge-at-haufe.de">Gottfried + Ganßauge</a> supplied support for opaque pointer conversions, + complete with documentation and a regression test (and I didn't + even have to ask him for those)! + + <p>Joel de Guzman implemented the <a href="overloads.html">default + argument support</a> and wrote the excellent <a href= + "../tutorial/index.html">tutorial documentation</a>.</p> + + <p><a href="http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. + Grosse-Kunstleve</a> implemented the <a href="pickle.html">pickle + support</a>, and has enthusiastically supported the library since its + birth, contributing to design decisions and providing invaluable + real-world insight into user requirements. Ralf has written some <a href= + "faq.html#question2">extensions</a> for converting C++ containers that I + hope will be incorporated into the library soon. He also implemented the + cross-module support in the first version of Boost.Python. More + importantly, Ralf makes sure nobody forgets the near-perfect synergy of + C++ and Python for solving the problems of large-scale software + construction.</p> + + <p><a href="http://www.boost.org/people/aleksey_gurtovoy.htm">Aleksey Gurtovoy</a> + wrote an incredible C++ <a href="http://www.mywikinet.com/mpl">Template + Metaprogramming Library</a> which allows Boost.Python to perform much of + its compile-time magic. In addition, Aleksey very generously contributed + his time and deep knowledge of the quirks of various buggy compilers to + help us get around problems at crucial moments.</p> + + <p><a href="http://www.boost.org/people/paul_mensonides.htm">Paul Mensonides</a>, + building on the work <a href="http://www.boost.org/people/vesa_karvonen.htm">Vesa + Karvonen</a>, wrote a similarly amazing <a href= + "../../../preprocessor/doc/index.html">Preprocessor Metaprogramming + Library</a>, and generously contributed the time and expertise to get it + working in the Boost.Python library, rewriting much of Boost.Python to + use the new preproccessor metaprogramming constructs and helping us to + work around buggy and slow C++ preprocessors.</p> + + <p><a href="mailto:nicodemus-at-globalite.com.br">Bruno da Silva de + Oliveira</a> contributed the ingenious <a + href="../../pyste/index.html">Pyste</a> ("Pie-Steh") + code generator. + + <p><a href="mailto:nickm@sitius.com">Nikolay Mladenov</a> contributed + <code>staticmethod</code> support.</p> + + <p>Martin Casado solved some sticky problems which allow us to build the + Boost.Python shared library for AIX's crazy dynamic linking model.</p> + + <p><a href="mailto:achim@procoders.net">Achim Domma</a> contributed some + of the <a href="reference.html#object_wrappers">Object Wrappers</a> and + HTML templates for this documentation. Dave Hawkes contributed + inspiration for the use of the <code><a href= + "scope.html#scope-spec">scope</a></code> class to simplify module + definition syntax. Pearu Pearson wrote some of the test cases that are in + the current test suite.</p> + + <p>The development of this version of Boost.Python was funded in part by + the <a href="http://www.llnl.gov/">Lawrence Livermore National + Laboratories</a> and by the <a href="http://cci.lbl.gov/">Computational + Crystallography Initiative</a> at Lawrence Berkeley National + Laboratories.</p> + + <p><a href="http://kogs-www.informatik.uni-hamburg.de/~koethe/">Ullrich + Koethe</a> had independently developed a similar system. When he + discovered Boost.Python v1, he generously contributed countless hours of + coding and much insight into improving it. He is responsible for an early + version of the support for function overloading and wrote the support for + reflecting C++ inheritance relationships. He has helped to improve + error-reporting from both Python and C++ (we hope to do as well in v2 + again soon), and has designed the original support for exposing numeric + operators, including a way to avoid explicit coercion by means of + overloading.</p> + + <p>The members of the boost mailing list and the Python community + supplied invaluable early feedback. In particular, Ron Clarke, Mark + Evans, Anton Gluck, Chuck Ingold, Prabhu Ramachandran, and Barry Scott + took the brave step of trying to use Boost.Python while it was still in + early stages of development.</p> + + <p>The first version of Boost.Python would not have been possible without + the support of Dragon Systems, which supported its development and + release as a Boost library.</p> + <hr> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 26 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/args.html b/libs/python/doc/v2/args.html new file mode 100644 index 000000000..e04720b7e --- /dev/null +++ b/libs/python/doc/v2/args.html @@ -0,0 +1,199 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></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="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#arg-spec">class <code>arg</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#arg-synopsis">class <code>arg</code> + synopsis</a></dt> + + <dt><a href="#arg-ctor">class <code>arg</code> + constructor</a></dt> + + <dt><a href="#arg-operator">class <code>arg</code> template + <code>operator =</code></a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#keyword-expression-operators"><i>Keyword-expression</i> + operator <code>,</code></a></dt> + + <dt><a href="#functions">Functions (deprecated)</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. The <b>keyword-expression</b> + may contain default values for some or all of the keywords it holds</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="arg-spec"></a><code>class arg;</code></h3> + + <p>The objects of class arg are keyword-expressions holding one keyword ( + size one )</p> + + <h4><a name="arg-synopsis"></a>Class <code>arg</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct arg + { + template <class T> + arg &operator = (T const &value); + explicit arg (char const *name){elements[0].name = name;} + }; + +}} +</pre> + + <h4><a name="arg-ctor"></a>Class <code>arg</code> constructor</h4> +<pre> +arg(char const* name); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> The argument must be a <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> Constructs an <code>arg</code> object holding a + keyword with name <code>name</code>.</dt> + </dl> + + <h4><a name="arg-operator"></a>Class <code>arg</code> operator =</h4> +<pre> +template <class T> arg &operator = (T const &value); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> The argument must convertible to python.</dt> + + <dt><b>Effects:</b> Assigns default value for the keyword.</dt> + + <dt><b>Returns:</b> Reference to <code>this</code>.</dt> + </dl> + + <h2><a name="keyword-expression-operators"><i>Keyword-expression</i> + operator <code>,</code></a></h2> +<pre> + <i>keyword-expression</i> operator , (<i>keyword-expression</i>, const arg &kw) const + <i>keyword-expression</i> operator , (<i>keyword-expression</i>, const char *name) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> The argument <code>name</code> must be a <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> Extends the <i>keyword-expression</i> argument with + one more keyword.</dt> + + <dt><b>Returns:</b> The extended <i>keyword-expression</i>.</dt> + </dl> + + <h2><font color="#7F7F7F"><a name="functions"></a>Functions + (deprecated)</font></h2> + + <h3><a name="args-spec"></a><code><font color= + "#7F7F7F">args</font>(</code>...<code>)</code></h3> +<pre> +<font color="#7F7F7F"> <i>unspecified1</i> args(char const*); + <i>unspecified2</i> args(char const*, char const*); + . + . + . + <i>unspecifiedN</i> args(char const*, char const*, ... char const*); +</font> +</pre> + + <dl class="function-semantics"> + <dt><font color="#7F7F7F"><b>Requires:</b> Every argument must be a <a + href="definitions.html#ntbs">ntbs</a>.</font></dt> + + <dt><font color="#7F7F7F"><b>Returns:</b> an object representing a <a + href="#keyword-expression"><i>keyword-expression</i></a> encapsulating + the arguments passed.</font></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> +<pre> +#include <boost/python/def.hpp> +using namespace boost::python; + +int f(double x, double y, double z=0.0, double w=1.0); + +BOOST_PYTHON_MODULE(xxx) +{ + def("f", f + , ( arg("x"), "y", arg("z")=0.0, arg("w")=1.0 ) + ); +} +</pre> + + <p>Revised 01 August, 2003</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002-2003.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/call.html b/libs/python/doc/v2/call.html new file mode 100644 index 000000000..adba2b5fe --- /dev/null +++ b/libs/python/doc/v2/call.html @@ -0,0 +1,85 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - <call.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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Header <call.hpp></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-spec">call</a></dt> + </dl> + + <dt><a href="#examples">Example(s)</a></dt> + +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p> + <code><boost/python/call.hpp></code> defines the <a + href="#call-spec"><code>call</code></a> family of overloaded function + templates, used to invoke Python callable objects from C++. + +<h2><a name="functions"></a>Functions</h2> +<pre> +<a name="call-spec">template <class R, class A1, class A2, ... class A<i>n</i>></a> +R call(PyObject* callable, A1 const&, A2 const&, ... A<i>n</i> const&) +</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>callable(a1, a2, ...a<i>n</i>)</code> in + Python, where <code>a1</code>...<code>a<i>n</i></code> are the arguments to + <code>call()</code>, converted to Python objects. + <dt><b>Returns:</b> The result of the Python call, converted to the C++ type <code>R</code>.</dt> + +</dt> + <dt><b>Rationale:</b> For a complete semantic description and + rationale, see <a href="callbacks.html">this page</a>. +</dt> +</dl> + +<h2><a name="examples"></a>Example(s)</h2> + +The following C++ function applies a Python callable object to its two +arguments and returns the result. If a Python exception is raised or +the result can't be converted to a <code>double</code>, an exception +is thrown. + +<pre> +double apply2(PyObject* func, double x, double y) +{ + return boost::python::call<double>(func, x, y); +} +</pre> + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 9 May, 2002 <!-- Luann's birthday! --> + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> diff --git a/libs/python/doc/v2/call_method.html b/libs/python/doc/v2/call_method.html new file mode 100644 index 000000000..e54ffb26a --- /dev/null +++ b/libs/python/doc/v2/call_method.html @@ -0,0 +1,161 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - <call_method.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <call_method.hpp></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> + + <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><boost/python/call_method.hpp></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 <class R, class A1, class A2, ... class A<i>n</i>></a> +R call_method(PyObject* self, char const* method, A1 const&, A2 const&, ... A<i>n</i> const&) +</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, a2, ...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><b>Returns:</b> The result of the Python call, converted to the C++ + type <code>R</code>.</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> + + <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> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/utility.hpp> +#include <cstring> + +// class to be wrapped +class Base +{ + public: + virtual char const* class_name() const { return "Base"; } + virtual ~Base(); +}; + +bool is_base(Base* b) +{ + return !std::strcmp(b->class_name(), "Base"); +} + +// Wrapper code begins here +using namespace boost::python; + +// Callback class +class Base_callback : public Base +{ + public: + Base_callback(PyObject* self) : m_self(self) {} + + char const* class_name() const { return <b>call_method</b><char const*>(m_self, "class_name"); } + char const* Base_name() const { return Base::class_name(); } + private: + PyObject* const m_self; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + def("is_base", is_base); + + class_<Base,Base_callback, noncopyable>("Base") + .def("class_name", &Base_callback::Base_name) + ; + +} +</pre> + + <h3>Python Code</h3> +<pre> +>>> from my_module import * +>>> class Derived(Base): +... def __init__(self): +... Base.__init__(self) +... def class_name(self): +... return self.__class__.__name__ +... +>>> is_base(Base()) # calls the class_name() method from C++ +1 +>>> is_base(Derived()) +0 +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/callbacks.html b/libs/python/doc/v2/callbacks.html new file mode 100644 index 000000000..4e91befad --- /dev/null +++ b/libs/python/doc/v2/callbacks.html @@ -0,0 +1,254 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Calling Python Functions and Methods</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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Calling Python Functions and Methods</h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href="#argument_handling">Argument Handling</a></dt> + + <dt><a href="#result_handling">Result Handling</a></dt> + + <dt><a href="#result_handling">Rationale</a></dt> + </dl> + <hr> + + <h2><a name="introduction">Introduction</a></h2> + The simplest way to call a Python function from C++, given an <code><a + href="object.html#object-spec">object</a></code> instance <code>f</code> + holding the function, is simply to invoke its function call operator. +<pre> +f("tea", 4, 2) // In Python: f('tea', 4, 2) +</pre> + And of course, a method of an <code><a href= + "object.html#object-spec">object</a></code> instance <code>x</code> can + be invoked by using the function-call operator of the corresponding + attribute: +<pre> +x.attr("tea")(4, 2); // In Python: x.tea(4, 2) +</pre> + + <p>If you don't have an <code>object</code> instance, Boost.Python + provides two families of function templates, <code><a href= + "call.html#call-spec">call</a></code> and <code><a href= + "call_method.html#call_method-spec">call_method</a></code>, for invoking + Python functions and methods respectively on <code>PyObject*</code>s. The + interface for calling a Python function object (or any Python callable + object) looks like:</p> +<pre> +call<ResultType>(callable_object, a1, a2... a<i>N</i>); +</pre> + Calling a method of a Python object is similarly easy: +<pre> +call_method<ResultType>(self_object, "<i>method-name</i>", a1, a2... a<i>N</i>); +</pre> + This comparitively low-level interface is the one you'll use when + implementing C++ virtual functions that can be overridden in Python. + + <h2><a name="argument_handling">Argument Handling</a></h2> + + <p>Arguments are converted to Python according to their type. By default, + the arguments <code>a1</code>...<code>a<i>N</i></code> are copied into + new Python objects, but this behavior can be overridden by the use of + <code><a href="ptr.html#ptr-spec">ptr()</a></code> and <a href= + "../../../bind/ref.html">ref()</a>:</p> +<pre> +class X : boost::noncopyable +{ + ... +}; + +void apply(PyObject* callable, X& x) +{ + // Invoke callable, passing a Python object which holds a reference to x + boost::python::call<void>(callable, boost::ref(x)); +} +</pre> + In the table below, <code><b>x</b></code> denotes the actual argument + object and <code><b>cv</b></code> denotes an optional + <i>cv-qualification</i>: "<code>const</code>", "<code>volatile</code>", + or "<code>const volatile</code>". + + <table border="1" summary="class_ template parameters"> + <tr> + <th>Argument Type</th> + + <th>Behavior</th> + </tr> + + <tr> + <td><code>T cv&</code><br> + <code>T cv</code></td> + + <td>The Python argument is created by the same means used for the + return value of a wrapped C++ function returning <code>T</code>. When + <code>T</code> is a class type, that normally means <code>*x</code> + is copy-constructed into the new Python object.</td> + </tr> + + <tr> + <td><code>T*</code></td> + + <td>If <code>x == 0</code>, the Python argument will be + <code><a href= + "http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>. + Otherwise, the Python argument is created by the same means used for + the return value of a wrapped C++ function returning <code>T</code>. + When <code>T</code> is a class type, that normally means + <code>*x</code> is copy-constructed into the new Python object.</td> + </tr> + + <tr> + <td><code><a href= + "../../../bind/ref.html">boost::reference_wrapper</a><T></code></td> + + <td>The Python argument contains a pointer to, rather than a copy of, + <code>x.get()</code>. Note: failure to ensure that no Python code + holds a reference to the resulting object beyond the lifetime of + <code>*x.get()</code> <b>may result in a crash!</b></td> + </tr> + + <tr> + <td><code><a href= + "ptr.html#pointer_wrapper-spec">pointer_wrapper</a><T></code></td> + + <td>If <code>x.get() == 0</code>, the Python argument will + be <code><a href= + "http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>. + Otherwise, the Python argument contains a pointer to, rather than a + copy of, <code>*x.get()</code>. Note: failure to ensure that no + Python code holds a reference to the resulting object beyond the + lifetime of <code>*x.get()</code> <b>may result in a crash!</b></td> + </tr> + </table> + + <h2><a name="result_handling">Result Handling</a></h2> + In general, <code>call<ResultType>()</code> and + <code>call_method<ResultType>()</code> return + <code>ResultType</code> by exploiting all lvalue and rvalue + <code>from_python</code> converters registered for ResultType and + returning a copy of the result. However, when <code>ResultType</code> is + a pointer or reference type, Boost.Python searches only for lvalue + converters. To prevent dangling pointers and references, an exception + will be thrown if the Python result object has only a single reference + count. + + <h2><a name="rationale">Rationale</a></h2> + In general, to get Python arguments corresponding to + <code>a1</code>...<code>a<i>N</i></code>, a new Python object must be + created for each one; should the C++ object be copied into that Python + object, or should the Python object simply hold a reference/pointer to + the C++ object? In general, the latter approach is unsafe, since the + called function may store a reference to the Python object somewhere. If + the Python object is used after the C++ object is destroyed, we'll crash + Python. + + <p>In keeping with the philosophy that users on the Python side shouldn't + have to worry about crashing the interpreter, the default behavior is to + copy the C++ object, and to allow a non-copying behavior only if the user + writes <code><a href="../../../bind/ref.html">boost::ref</a>(a1)</code> + instead of a1 directly. At least this way, the user doesn't get dangerous + behavior "by accident". It's also worth noting that the non-copying + ("by-reference") behavior is in general only available for class types, + and will fail at runtime with a Python exception if used otherwise[<a + href="#1">1</a>].</p> + + <p>However, pointer types present a problem: one approach is to refuse to + compile if any aN has pointer type: after all, a user can always pass + <code>*aN</code> to pass "by-value" or <code>ref(*aN)</code> to indicate + a pass-by-reference behavior. However, this creates a problem for the + expected null pointer to <code>None</code> conversion: it's illegal to + dereference a null pointer value.</p> + + <p>The compromise I've settled on is this:</p> + + <ol> + <li>The default behavior is pass-by-value. If you pass a non-null + pointer, the pointee is copied into a new Python object; otherwise the + corresponding Python argument will be None.</li> + + <li>if you want by-reference behavior, use <code>ptr(aN)</code> if + <code>aN</code> is a pointer and <code>ref(aN)</code> otherwise. If a + null pointer is passed to <code>ptr(aN)</code>, the corresponding + Python argument will be <code>None</code>.</li> + </ol> + + <p>As for results, we have a similar problem: if <code>ResultType</code> + is allowed to be a pointer or reference type, the lifetime of the object + it refers to is probably being managed by a Python object. When that + Python object is destroyed, our pointer dangles. The problem is + particularly bad when the <code>ResultType</code> is char const* - the + corresponding Python String object is typically uniquely-referenced, + meaning that the pointer dangles as soon as <code>call<char + const*>(...)</code> returns.</p> + + <p>The old Boost.Python v1 deals with this issue by refusing to compile + any uses of <code>call<char const*>()</code>, but this goes both + too far and not far enough. It goes too far because there are cases where + the owning Python string object survives beyond the call (just for + instance, when it's the name of a Python class), and it goes not far + enough because we might just as well have the same problem with a + returned pointer or reference of any other type.</p> + + <p>In Boost.Python v2 this is dealt with by:</p> + + <ol> + <li>lifting the compile-time restriction on const char* callback + returns</li> + + <li>detecting the case when the reference count on the result Python + object is 1 and throwing an exception inside of + <code>call<U>(...)</code> when <code>U</code> is a pointer or + reference type.</li> + </ol> + This should be acceptably safe because users have to explicitly specify a + pointer/reference for <code>U</code> in <code>call<U></code>, and + they will be protected against dangles at runtime, at least long enough + to get out of the <code>call<U>(...)</code> invocation. + <hr> + <a name="1">[1]</a> It would be possible to make it fail at compile-time + for non-class types such as int and char, but I'm not sure it's a good + idea to impose this restriction yet. + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/callbacks.txt b/libs/python/doc/v2/callbacks.txt new file mode 100644 index 000000000..2795680fd --- /dev/null +++ b/libs/python/doc/v2/callbacks.txt @@ -0,0 +1,92 @@ +.. Copyright David Abrahams 2006. Distributed under the Boost +.. Software License, Version 1.0. (See accompanying +.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + +Here's the plan: + +I aim to provide an interface similar to that of Boost.Python v1's +callback<>::call(...) for dealing with callbacks. The interface will +look like: + + returning<ResultType>::call("method_name", self_object, a1, a2...); + +or + + returning<ResultType>::call(callable_object, a1, a2...); + +ARGUMENT HANDLING + +There is an issue concerning how to make Python objects from the +arguments a1...aN. A new Python object must be created; should the C++ +object be copied into that Python object, or should the Python object +simply hold a reference/pointer to the C++ object? In general, the +latter approach is unsafe, since the called function may store a +reference to the Python object somewhere. If the Python object is used +after the C++ object is destroyed, we'll crash Python. + +I plan to make the copying behavior the default, and to allow a +non-copying behavior if the user writes boost::ref(a1) instead of a1 +directly. At least this way, the user doesn't get dangerous behavior "by +accident". It's also worth noting that the non-copying ("by-reference") +behavior is in general only available for class types, and will fail at +runtime with a Python exception if used otherwise** + +However, pointer types present a problem: My first thought is to refuse +to compile if any aN has pointer type: after all, a user can always pass +*aN to pass "by-value" or ref(*aN) to indicate a pass-by-reference +behavior. However, this creates a problem for the expected NULL pointer +=> None conversion: it's illegal to dereference a null pointer value. + +We could use another construct, say "ptr(aN)", to deal with null +pointers, but then what does it mean? We know what it does when aN is +NULL, but it might either have by-value or by-reference behavior when aN +is non-null. + +The compromise I've settled on is this: + +1. The default behavior is pass-by-value. If you pass a non-null + pointer, the pointee is copied into a new Python object; otherwise + the corresponding Python argument will be None. + +2. if you want by-reference behavior, use ptr(aN) if aN is a pointer + and ref(aN) otherwise. If a null pointer is passed to ptr(aN), the + corresponding Python argument will be None. + +RESULT HANDLING + +As for results, we have a similar problem: if ResultType is allowed to +be a pointer or reference type, the lifetime of the object it refers to +is probably being managed by a Python object. When that Python object is +destroyed, our pointer dangles. The problem is particularly bad when the +ResultType is char const* - the corresponding Python String object is +typically uniquely-referenced, meaning that the pointer dangles as soon +as returning<char const*>::call() returns. + +Boost.Python v1 deals with this issue by refusing to compile any uses of +callback<char const*>::call(), but IMO this goes both too far and not +far enough. It goes too far because there are cases where the owning +String object survives beyond the call (just for instance when it's the +name of a Python class), and it goes not far enough because we might +just as well have the same problem with any returned pointer or +reference. + +I propose to address this in Boost.Python v2 by + + 1. lifting the compile-time restriction on const + char* callback returns + + 2. detecting the case when the reference count on the + result Python object is 1 and throwing an exception + inside of returning<U>::call() when U is a pointer or + reference type. + +I think this is acceptably safe because users have to explicitly specify +a pointer/reference for U in returning<U>, and they will be protected +against dangles at runtime, at least long enough to get out of the +returning<U>::call() invocation. + +-Dave + +**It would be possible to make it fail at compile-time for non-class +types such as int and char, but I'm not sure it's a good idea to impose +this restriction yet. diff --git a/libs/python/doc/v2/class.html b/libs/python/doc/v2/class.html new file mode 100644 index 000000000..edfc60970 --- /dev/null +++ b/libs/python/doc/v2/class.html @@ -0,0 +1,790 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> +<head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st September 2004), see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-latin-1-dos"> + <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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></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> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + <hr> + + <h2><a name="introduction" id="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" id="classes"></a>Classes</h2> + + <h3><a name="class_-spec" id="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-spec">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 that is actually embedded in a Python object + wrapping a <code>T</code> instance when <code>T</code>'s constructor is + called or when a <code>T</code> or <code>T*</code> is converted to + Python without the use of <a href= + "http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling"> + <code>ptr</code></a>, <a href= + "http://www.boost.org/libs/python/doc/v2/callbacks.html#argument_handling"> + <code>ref</code></a>, or <a href="CallPolicies.html">Call Policies</a> + such as <code><a href= + "return_internal_reference.html">return_internal_reference</a></code>. + 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_noncopyable">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" id="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#examples">this example</a>. This argument is not + included in the <em><a href= + "init.html#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" id="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&); + + // declaring method as static + class_& staticmethod(char const* name); + + // 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); + + // exposing static data members + template <class D> + class_& def_readonly(char const* name, D const& d); + template <class D> + class_& def_readwrite(char const* name, D& d); + + // property creation + template <class Get> + void add_property(char const* name, Get const& fget, char const* doc=0); + template <class Get, class Set> + void add_property( + char const* name, Get const& fget, Set const& fset, char const* doc=0); + + template <class Get> + void add_static_property(char const* name, Get const& fget); + template <class Get, class Set> + void add_static_property(char const* name, Get const& fget, Set const& fset); + + // pickle support + template <typename PickleSuite> + self& def_pickle(PickleSuite const&); + self& enable_pickling(); + }; +}} +</pre> + + <h4><a name="class_-spec-ctors" id="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 an <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.html#init-expressions">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" id="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.html#init-expressions">init-expression</a> compatible with + <code>T</code>.</dt> + + <dt><b>Effects:</b> For each <a href="init.html#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 <a href="init.html#init-expressions">valid prefix</a> 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 an <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= + "overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>, + only the second form is allowed and fn must be a pointer to function + or pointer to member function whose <a href="definitions.html#arity"> + arity</a> is the same as A1's <a href= + "overloads.html#overload-dispatch-expression"><em>maximum + arity</em></a>. + + <dl> + <dt><b>Effects:</b> For each prefix <em>P</em> of + <code>Fn</code>'s sequence of argument types, beginning with the + one whose length is <code>A1</code>'s <a href= + "overloads.html#overload-dispatch-expression"><em>minimum + arity</em></a>, adds a + <code><em>name</em>(</code>...<code>)</code> method 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. If an earlier overload + supplied a docstring, two newline characters and the new + docstring are appended to it.</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> +class_& staticmethod(char const* name); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <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>, and corresponds to a method whose overloads have all + been defined.</dt> + + <dt><b>Effects:</b> Replaces the existing named attribute <i>x</i> with + the result of invoking <code>staticmethod(</code><i>x</i><code>)</code> + in Python. Specifies that the corresponding method is static and + therefore no object instance will be passed to it. This is equivalent to + the Python statement:</dt> + + <dd> + <pre> +setattr(self, name, staticmethod(getattr(self, name))) +</pre> + </dd> + + <dt><b>Note:</b> Attempting to invoke <code>def(name,...)</code> after + invoking <code>staticmethod(name)</code> will <a href= + "definitions.html#raise">raise</a> a RuntimeError.</dt> + + <dt><b>Returns:</b> <code>*this</code></dt> + </dl><br> + <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 an <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> + + <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, char const* doc=0); +template <class Get, class Set> +void add_property( + char const* name, Get const& fget, Set const& fset, char const* doc=0); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <a href= + "definitions.html#ntbs">ntbs</a> which conform 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/2.2.2/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) with an (optional) docstring <code>doc</code> 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 Get> +void add_static_property(char const* name, Get const& fget); +template <class Get, class Set> +void add_static_property(char const* name, Get const& fget, Set const& fset); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <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> + + <dt><b>Effects:</b> Creates a Boost.Python.StaticProperty object, 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 + under construction with the given attribute <code>name</code>. + StaticProperty is a special subclass of Python's <a href= + "http://www.python.org/2.2.2/descrintro.html#property"><code>property</code></a> + class which can be called without an initial <code>self</code> + argument.</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 static attribute access syntax.</dt> + </dl><br> + <pre> +template <class D> +class_& def_readonly(char const* name, D T::*pm, char const* doc=0); +template <class D> +class_& def_readonly(char const* name, D const& d); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <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>. <code>doc</code> is also an ntbs.</dt> + + <dt><b>Effects:</b></dt> + + <dd> + <pre> +this->add_property(name, <a href= +"data_members.html#make_getter-spec">make_getter</a>(pm), doc); +</pre>and + <pre> +this->add_static_property(name, <a href= +"data_members.html#make_getter-spec">make_getter</a>(d)); +</pre>respectively.<br> + <br> + </dd> + + <dt><b>Returns:</b> <code>*this</code></dt> + + <dt><b>Rationale:</b> Allows users to easily expose a class' data member + or free variable 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, char const* doc=0); +template <class D> +class_& def_readwrite(char const* name, D& d); +</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), doc); +</pre>and + <pre> +this->add_static_property(name, <a href= +"data_members.html#make_getter-spec">make_getter</a>(d), <a href= +"data_members.html#make_setter-spec">make_setter</a>(d)); +</pre>respectively.<br> + <br> + </dd> + + <dt><b>Returns:</b> <code>*this</code></dt> + + <dt><b>Rationale:</b> Allows users to easily expose a class' data or free + variable member such that it can be inspected and set from Python with a + natural syntax.</dt> + </dl> + <pre> +template <typename PickleSuite> +class_& def_pickle(PickleSuite const&); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> PickleSuite must be publically derived from <a href= + "pickle.html"><code>pickle_suite</code></a>.</dt> + + <dt><b>Effects:</b> Defines a legal combination of the special attributes + and methods: <code>__getinitargs__</code>, <code>__getstate__</code>, + <code>__setstate__</code>, <code>__getstate_manages_dict__</code>, + <code>__safe_for_unpickling__</code>, <code>__reduce__</code></dt> + + <dt><b>Returns:</b> <code>*this</code></dt> + + <dt><b>Rationale:</b> Provides an <a href="pickle.html">easy to use + high-level interface</a> for establishing complete pickle support for the + wrapped class. The user is protected by compile-time consistency + checks.</dt> + </dl><br> + <pre> +class_& enable_pickling(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Defines the <code>__reduce__</code> method and the + <code>__safe_for_unpickling__</code> attribute.</dt> + + <dt><b>Returns:</b> <code>*this</code></dt> + + <dt><b>Rationale:</b> Light-weight alternative to + <code>def_pickle()</code>. Enables implementation of <a href= + "pickle.html">pickle support</a> from Python.</dt> + </dl><br> + + <h3><a name="bases-spec" id="bases-spec"></a>Class template + <code>bases<T1, T2,</code>...<code>TN></code></h3> + + <p>An <a href="../../../mpl/doc/refmanual/forward-sequence.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" id="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" id="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" id="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 --> + 1 November, 2005 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002.</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/configuration.html b/libs/python/doc/v2/configuration.html new file mode 100644 index 000000000..1be862ed6 --- /dev/null +++ b/libs/python/doc/v2/configuration.html @@ -0,0 +1,217 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Configuration</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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Configuration</h2> + </td> + </tr> + </table> + <hr> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href="#app-defined">Application Defined Macros</a></dt> + + <dt><a href="#lib-defined-impl">Library Defined Implementation + Macros</a></dt> + </dl> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><b>Boost.Python</b> uses several configuration macros in <a href= + "http://www.boost.org/libs/config/config.htm"><boost/config.hpp></a>, + as well as configuration macros meant to be supplied by the application. + These macros are documented here.</p> + + <h2><a name="app-defined"></a>Application Defined Macros</h2> + + <p>These are the macros that may be defined by an application using + <b>Boost.Python</b>. Note that if you extend a strict interpretation of + the C++ standard to cover dynamic libraries, using different values of + these macros when compiling different libraries (including extension + modules and the <b>Boost.Python</b> library itself) is a violation of the + <a href="definitions.html#ODR">ODR</a>. However, we know of no C++ + implementations on which this particular violation is detectable or + causes any problems.</p> + + <table summary="application defined macros" width="100%" cellpadding= + "10"> + <tr> + <th align="left"><b>Macro</b></th> + + <th><b>Default</b></th> + + <th align="left"><b>Meaning</b></th> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_MAX_ARITY</code></td> + + <td valign="top" align="center">15</td> + + <td valign="top">The maximum <a href= + "definitions.html#arity">arity</a> of any function, member function, + or constructor to be wrapped, invocation of a <b>Boost.Python</b> + function wich is specified as taking arguments + <code>x1, x2,</code>...<code>X</code><i>n</i>. This includes, in + particular, callback mechanisms such as <code><a href= + "object.html#object-spec">object</a>::operator()(</code>...<code>)</code> + or <code><a href= + "call_method.html#call_method-spec">call_method</a><R>(</code>... + <code>)</code>.</td> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_MAX_BASES</code></td> + + <td valign="top" align="center">10</td> + + <td valign="top">The maximum number of template arguments to the + <code><a href= + "class.html#bases-spec">bases</a><</code>...<code>></code> + class template, which is used to specify the bases of a wrapped C++ + class..</td> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_STATIC_MODULE</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined, prevents your module initialization + function from being treated as an exported symbol on platforms which + support that distinction in-code</td> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_ENABLE_CDECL</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined, allows functions using the <code>__cdecl + </code> calling convention to be wrapped.</td> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_ENABLE_STDCALL</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined, allows functions using the <code>__stdcall + </code> calling convention to be wrapped.</td> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_ENABLE_FASTCALL</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined, allows functions using the <code>__fastcall + </code> calling convention to be wrapped.</td> + </tr> + </table> + + <h2><a name="lib-defined-impl"></a>Library Defined Implementation + Macros</h2> + + <p>These macros are defined by <b>Boost.Python</b> and are implementation + details of interest only to implementors and those porting to new + platforms.</p> + + <table summary="library defined implementation macros" width="100%" + cellpadding="10"> + <tr> + <th align="left"><b>Macro</b></th> + + <th><b>Default</b></th> + + <th align="left"><b>Meaning</b></th> + </tr> + + <tr> + <td valign="top"><code>BOOST_PYTHON_TYPE_ID_NAME</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined, this indicates that the type_info + comparison across shared library boundaries does not work on this + platform. In other words, if shared-lib-1 passes + <code>typeid(T)</code> to a function in shared-lib-2 which compares + it to <code>typeid(T)</code>, that comparison may return + <code>false</code>. If this macro is #defined, Boost.Python uses and + compares <code>typeid(T).name()</code> instead of using and comparing + the <code>std::type_info</code> objects directly.</td> + </tr> + <tr> + <td valign="top"><code>BOOST_PYTHON_NO_PY_SIGNATURES</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined for a module no pythonic signatures are generated + for the docstrings of the module functions, and no python type is associated with any + of the converters registered by the module. This also reduces the binary size of the + module by about 14% (gcc compiled).<br> + If defined for the boost_python runtime library, the default for the + <code>docstring_options.enable_py_signatures()</code> is set to <code>false</code>. + </td> + + </tr> + <tr> + <td valign="top"><code>BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</code></td> + + <td valign="top" align="center"><i>defined if <code>BOOST_PYTHON_NO_PY_SIGNATURES</code> is undefined</i></td> + + <td valign="top">This macro is defined to enable a smooth transition from older Boost.Python versions + which do not support pythonic signatures. For example usage see + <a href="pytype_function.html#examples">here</a>. + </td> + + </tr> + <tr> + <td valign="top"><code>BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE</code></td> + + <td valign="top" align="center"><i>not defined</i></td> + + <td valign="top">If defined the python type of <code>__init__</code> method "self" parameters + is properly generated, otherwise <code><b>object</b></code> is used. It is undefined + by default because it increases the binary size of the module by about 14% (gcc compiled).</td> + + </tr> + </table> + <hr> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 7 January, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/copy_const_reference.html b/libs/python/doc/v2/copy_const_reference.html new file mode 100644 index 000000000..97c2a282c --- /dev/null +++ b/libs/python/doc/v2/copy_const_reference.html @@ -0,0 +1,149 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/copy_const_reference.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/copy_const_reference.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#copy_const_reference-spec">Class + <code>copy_const_reference</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#copy_const_reference-spec-synopsis">Class + <code>copy_const_reference</code> synopsis</a></dt> + + <dt><a href="#copy_const_reference-spec-metafunctions">Class + <code>copy_const_reference</code> metafunctions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="copy_const_reference-spec"></a>Class + <code>copy_const_reference</code></h3> + + <p><code>copy_const_reference</code> is a model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> + which can be used to wrap C++ functions returning a reference-to-const + type such that the referenced value is copied into a new Python + object.</p> + + <h4><a name="copy_const_reference-spec-synopsis"></a>Class + <code>copy_const_reference</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct copy_const_reference + { + template <class T> struct apply; + }; +}} +</pre> + + <h4><a name="copy_const_reference-spec-metafunctions"></a>Class + <code>copy_const_reference</code> metafunctions</h4> +<pre> +template <class T> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Requires:</b> <code>T</code> is <code>U const&</code> for + some <code>U</code>.</dt> + + <dt><b>Returns:</b> <code>typedef <a href= + "to_python_value.html#to_python_value-spec">to_python_value</a><T> + type;</code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ Module Definition</h3> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/copy_const_reference.hpp> +#include <boost/python/return_value_policy.hpp> + +// classes to wrap +struct Bar { int x; } + +struct Foo { + Foo(int x) : { b.x = x; } + Bar const& get_bar() const { return b; } + private: + Bar b; +}; + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + class_<Bar>("Bar"); + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_value_policy<copy_const_reference>()) + ; +} +</pre> + + <h3>Python Code</h3> +<pre> +>>> from my_module import * +>>> f = Foo(3) # create a Foo object +>>> b = f.get_bar() # make a copy of the internal Bar object +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/copy_non_const_reference.html b/libs/python/doc/v2/copy_non_const_reference.html new file mode 100644 index 000000000..987efad83 --- /dev/null +++ b/libs/python/doc/v2/copy_non_const_reference.html @@ -0,0 +1,149 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/copy_non_const_reference.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/copy_non_const_reference.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#copy_non_const_reference-spec">Class + <code>copy_non_const_reference</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#copy_non_const_reference-spec-synopsis">Class + <code>copy_non_const_reference</code> synopsis</a></dt> + + <dt><a href= + "#copy_non_const_reference-spec-metafunctions">Class + <code>copy_non_const_reference</code> metafunctions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="copy_non_const_reference-spec"></a>Class + <code>copy_non_const_reference</code></h3> + + <p><code>copy_non_const_reference</code> is a model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> + which can be used to wrap C++ functions returning a + reference-to-non-const type such that the referenced value is copied into + a new Python object.</p> + + <h4><a name="copy_non_const_reference-spec-synopsis"></a>Class + <code>copy_non_const_reference</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct copy_non_const_reference + { + template <class T> struct apply; + }; +}} +</pre> + + <h4><a name="copy_non_const_reference-spec-metafunctions"></a>Class + <code>copy_non_const_reference</code> metafunctions</h4> +<pre> +template <class T> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Requires:</b> <code>T</code> is <code>U&</code> for some + non-const <code>U</code>.</dt> + + <dt><b>Returns:</b> <code>typedef <a href= + "to_python_value.html#to_python_value-spec">to_python_value</a><T> + type;</code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <p>C++ code:</p> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/copy_non_const_reference.hpp> +#include <boost/python/return_value_policy.hpp> + +// classes to wrap +struct Bar { int x; } + +struct Foo { + Foo(int x) : { b.x = x; } + Bar& get_bar() { return b; } + private: + Bar b; +}; + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + class_<Bar>("Bar"); + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_value_policy<copy_non_const_reference>()) + ; +} +</pre> + Python Code: +<pre> +>>> from my_module import * +>>> f = Foo(3) # create a Foo object +>>> b = f.get_bar() # make a copy of the internal Bar object +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/data_members.html b/libs/python/doc/v2/data_members.html new file mode 100644 index 000000000..36f818d3d --- /dev/null +++ b/libs/python/doc/v2/data_members.html @@ -0,0 +1,229 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 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/data_members.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/data_members.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#make_getter-spec">make_getter</a></dt> + + <dt><a href="#make_setter-spec">make_setter</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><a href="#make_getter-spec">make_getter</a>()</code> and + <code><a href="#make_setter-spec">make_setter</a>()</code> are the + functions used internally by <code>class_<>::<a href= + "class.html#class_-spec-modifiers">def_readonly</a></code> and + <code>class_<>::<a href= + "class.html#class_-spec-modifiers">def_readwrite</a></code> to produce + Python callable objects which wrap C++ data members.</p> + + <h2><a name="functions"></a>Functions</h2> +<pre> +<a name="make_getter-spec">template <class C, class D></a> +<a href="object.html#object-spec">object</a> make_getter(D C::*pm); + +template <class C, class D, class Policies> +<a href= +"object.html#object-spec">object</a> make_getter(D C::*pm, Policies const& policies); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= + "CallPolicies.html">CallPolicies</a>.</dt> + + <dt><b>Effects:</b> Creates a Python callable object which accepts a + single argument that can be converted <code>from_python</code> to + <code>C*</code>, and returns the corresponding member <code>D</code> + member of the <code>C</code> object, converted <code>to_python</code>. + If <code>policies</code> is supplied, it will be applied to the + function as described <a href="CallPolicies.html">here</a>. Otherwise, + the library attempts to determine whether <code>D</code> is a + user-defined class type, and if so uses <code><a href= + "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a><></code></dt> + + <dt>for <code>Policies</code>. Note that this test may inappropriately + choose <code>return_internal_reference<></code> in some cases + when <code>D</code> is a smart pointer type. This is a known + defect.</dt> + + <dt><b>Returns:</b> An instance of <a href= + "object.html#object-spec">object</a> which holds the new Python + callable object.</dt> + </dl> +<pre> +template <class D> +<a href="object.html#object-spec">object</a> make_getter(D const& d); +template <class D, class Policies> +<a href= +"object.html#object-spec">object</a> make_getter(D const& d, Policies const& policies); + +template <class D> +<a href="object.html#object-spec">object</a> make_getter(D const* p); +template <class D, class Policies> +<a href= +"object.html#object-spec">object</a> make_getter(D const* p, Policies const& policies); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= + "CallPolicies.html">CallPolicies</a>.</dt> + + <dt><b>Effects:</b> Creates a Python callable object which accepts no + arguments and returns <code>d</code> or <code>*p</code>, converted + <code>to_python</code> on demand. If <code>policies</code> is supplied, + it will be applied to the function as described <a href= + "CallPolicies.html">here</a>. Otherwise, the library attempts to + determine whether <code>D</code> is a user-defined class type, and if + so uses <code><a href= + "reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a></code></dt> + + <dt>for <code>Policies</code>.</dt> + + <dt><b>Returns:</b> An instance of <a href= + "object.html#object-spec">object</a> which holds the new Python + callable object.</dt> + </dl> +<pre> +<a name="make_setter-spec">template <class C, class D></a> +<a href="object.html#object-spec">object</a> make_setter(D C::*pm); + +template <class C, class D, class Policies> +<a href= +"object.html#object-spec">object</a> make_setter(D C::*pm, Policies const& policies); +</pre> + + <dl class="function*-semantics"> + <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= + "CallPolicies.html">CallPolicies</a>.</dt> + + <dt><b>Effects:</b> Creates a Python callable object which, when called + from Python, expects two arguments which can be converted + <code>from_python</code> to <code>C*</code> and + <code>D const&</code>, respectively, and sets the + corresponding <code>D</code> member of the <code>C</code> object. If + <code>policies</code> is supplied, it will be applied to the function + as described <a href="CallPolicies.html">here</a>.</dt> + + <dt><b>Returns:</b> An instance of <a href= + "object.html#object-spec">object</a> which holds the new Python + callable object.</dt> + </dl> +<pre> +template <class D> +<a href="object.html#object-spec">object</a> make_setter(D& d); +template <class D, class Policies> +<a href= +"object.html#object-spec">object</a> make_setter(D& d, Policies const& policies); + +template <class D> +<a href="object.html#object-spec">object</a> make_setter(D* p); +template <class D, class Policies> +<a href= +"object.html#object-spec">object</a> make_setter(D* p, Policies const& policies); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>Policies</code> is a model of <a href= + "CallPolicies.html">CallPolicies</a>.</dt> + + <dt><b>Effects:</b> Creates a Python callable object which accepts one + argument, which is converted from Python to <code>D const&</code> + and written into <code>d</code> or <code>*p</code>, respectively. If + <code>policies</code> is supplied, it will be applied to the function + as described <a href="CallPolicies.html">here</a>.</dt> + + <dt><b>Returns:</b> An instance of <a href= + "object.html#object-spec">object</a> which holds the new Python + callable object.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <p>The code below uses make_getter and make_setter to expose a data + member as functions:</p> +<pre> +#include <boost/python/data_members.hpp> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> + +struct X +{ + X(int x) : y(x) {} + int y; +}; + +using namespace boost::python; + +BOOST_PYTHON_MODULE_INIT(data_members_example) +{ + class_<X>("X", init<int>()) + .def("get", make_getter(&X::y)) + .def("set", make_setter(&X::y)) + ; +} +</pre> + It can be used this way in Python: +<pre> +>>> from data_members_example import * +>>> x = X(1) +>>> x.get() +1 +>>> x.set(2) +>>> x.get() +2 +</pre> + + <p> + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 5 August, 2003 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/def.html b/libs/python/doc/v2/def.html new file mode 100644 index 000000000..3c71fd363 --- /dev/null +++ b/libs/python/doc/v2/def.html @@ -0,0 +1,191 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 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/def.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/def.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#def-spec">def</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><a href="#def-spec">def</a>()</code> is the function which can + be used to expose C++ functions and callable objects as Python functions + in the current <code><a href="scope.html">scope</a></code>.</p> + + <h2><a name="functions"></a>Functions</h2> + <a name="def-spec"></a>def +<pre> +template <class F> +void def(char const* name, F f); + +template <class Fn, class A1> +void def(char const* name, Fn fn, A1 const&); + +template <class Fn, class A1, class A2> +void def(char const* name, Fn fn, A1 const&, A2 const&); + +template <class Fn, class A1, class A2, class A3> +void def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <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>Fn</code> is [derived from] <code><a href= + "object.html#object-spec">object</a></code>, it will be added to + the current scope as a single overload. 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> + + <li> + If <code>a1</code> is the result of an <a href= + "overloads.html#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>, + only the second form is allowed and fn must be a pointer to + function or pointer to member function whose <a href= + "definitions.html#arity">arity</a> is the same as A1's <a href= + "overloads.html#overload-dispatch-expression"><em>maximum + arity</em></a>. + + <dl> + <dt><b>Effects:</b> For each prefix <em>P</em> of + <code>Fn</code>'s sequence of argument types, beginning with + the one whose length is <code>A1</code>'s <a href= + "overloads.html#overload-dispatch-expression"><em>minimum + arity</em></a>, adds a + <code><em>name</em>(</code>...<code>)</code> function overload + to the <a href="scope.html">current scope</a>. 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, fn must be a non-null function or member function + pointer, and a single function overload built around fn is added to + the <a href="scope.html">current scope</a>. If any of + <code>a1</code>-<code>a3</code> are supplied, they may be selected + in any order from the table below.</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> + </dd> + </dl> + + <h2><a name="examples"></a>Example</h2> +<pre> +#include <boost/python/def.hpp> +#include <boost/python/module.hpp> +#include <boost/python/args.hpp> + +using namespace boost::python; + +char const* foo(int x, int y) { return "foo"; } + +BOOST_PYTHON_MODULE(def_test) +{ + def("foo", foo, args("x", "y"), "foo's docstring"); +} +</pre> + + <p> + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 7 March, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/def_visitor.html b/libs/python/doc/v2/def_visitor.html new file mode 100644 index 000000000..08fa0c514 --- /dev/null +++ b/libs/python/doc/v2/def_visitor.html @@ -0,0 +1,137 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="Microsoft FrontPage 5.0"> + <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/def_visitor.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html"><font size="7">Boost.Python</font></a></h1> + + <h2 align="center">Header <boost/python/def_visitor.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + +<dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + <dt><a href="#classes">Classes</a> + <dd> + <dl class="page-index"> + <dt><a href="#def_visitor-spec">Class <code>def_visitor</code></a> + <dd> <a href="#def_visitor-synopsis">Class <code>def_visitor</code> + synopsis</a></dd> + <dd> <a href="#def_visitor-requirements">Class <code>def_visitor</code> + requirements</a></dd> + </dl> + <dt><a href="#examples">Example</a> +</dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + +<p><code><boost/python/def_visitor.hpp></code> provides a generic visitation + interface through which the <a href="class.html">class_</a> <b>def</b> member + functionality can be extended non-intrusively to avoid cluttering the <a href="class.html">class_</a> + interface. It declares the <code>def_visitor<T> </code>class template, + which is parameterized on the derived type <tt>DerivedVisitor</tt>, which provides + the actual <b>def</b> functionality through its <b>visit</b> member functions. +<h2><a name="classes"></a>Classes</h2> + + <h3><a name="def_visitor-spec"></a>Class template <code>def_visitor<DerivedVisitor></code></h3> + + +<p>The class def_visitor is a base class paramaterized by its derived class. The + def_visitor class is a protocol class. Its derived class, DerivedVisitor, is + expected to have a member function visit. The def_visitor class is never instantiated + directly. Instead, an instance of its subclass, DerivedVisitor, is passed + on as an argument to the <a href="class.html">class_</a> def member function. +<h4> +<a name="def_visitor-synopsis" id="def_visitor-synopsis"></a>Class <code>def_visitor </code>synopsis</h4> +<pre>namespace boost { namespace python { + + template <class DerivedVisitor> + class def_visitor {}; +}</pre> +<h3><a name="def_visitor-requirements"></a><code>def_visitor </code>requirements</h3> + + +<p>The <span class="pre">client supplied class </span><span class="pre"></span><tt class="literal"><span class="pre">DerivedVisitor</span></tt> + template parameter is expected to: +<ul> + <li>be privately derived from def_visitor</li> + <li>grant friend access to class def_visitor_access</li> + <li>define either or both visit member functions listed in the table below:</li> +</ul> + + +<table border class="table"> + <tr> + <td width="181" nowrap><b>Expression</b></td> + <td width="85"><b>Return Type</b></td> + <td width="330"><b>Requirements</b></td> + <td width="259"><b>Effects</b></td> + </tr> + <tr> + <td nowrap>visitor.visit(cls)</td> + <td>void</td> + <td>cls is an instance of a <a href="class.html">class_</a> being wrapped + to Python. visitor is a def_visitor derived class.</td> + <td>A call to cls.def(visitor) forwards to this member function.</td> + </tr> + <tr> + <td nowrap>visitor.visit(cls, name, options)</td> + <td>void</td> + <td>cls is a class_ instance, name is a C string. visitor is a def_visitor + derived class. options is a context specific optional argument.</td> + <td>A call to cls.def(name, visitor) or cls.def(name, visitor, options) forwards + to this member function. </td> + </tr> +</table> + + <h2><a name="examples"></a>Example</h2> + + +<pre>class X {/*...*/};<br> +class my_def_visitor : boost::python::def_visitor<my_def_visitor> +{ + friend class def_visitor_access; + + template <class classT> + void visit(classT& c) const + { + c + .def("foo", &my_def_visitor::foo) + .def("bar", &my_def_visitor::bar) + ; + } + + static void foo(X& self); + static void bar(X& self); +}; + +BOOST_PYTHON_MODULE(my_ext) +{ + class_<X>("X") + .def(my_def_visitor()) + ; +} +</pre> + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->27 August, 2003<!--webbot bot="Timestamp" endspan i-checksum="34484" --> + </p> + + + <p><i>© Copyright Joel de Guzman 2003. </i> Distributed under the Boost + Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) diff --git a/libs/python/doc/v2/default_call_policies.html b/libs/python/doc/v2/default_call_policies.html new file mode 100644 index 000000000..30d0a50de --- /dev/null +++ b/libs/python/doc/v2/default_call_policies.html @@ -0,0 +1,173 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, 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/default_call_policies.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/default_call_policies.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a> + + <dd> + <dl class="page-index"> + <dt><a href="#default_call_policies-spec">Class + <code>default_call_policies</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#default_call_policies-spec-synopsis">Class + <code>default_call_policies</code> synopsis</a> + + <dt><a href="#default_call_policies-spec-statics">Class + <code>default_call_policies</code> static functions</a> + </dl> + + <dt><a href="#default_result_converter-spec">Class + <code>default_result_converter</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#default_result_converter-spec-synopsis">Class + <code>default_result_converter</code> synopsis</a> + + <dt><a href="#default_result_converter-spec-metafunctions">Class + <code>default_result_converter</code> metafunctions</a> + </dl> + </dl> + + <dt><a href="#examples">Example</a> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="default_call_policies-spec"></a>Class + <code>default_call_policies</code></h3> + + <p><code>default_call_policies</code> is a model of <a href= + "CallPolicies.html">CallPolicies</a> with no <code>precall</code> or + <code>postcall</code> behavior and a <code>result_converter</code> which + handles by-value returns. Wrapped C++ functions and member functions use + <code>default_call_policies</code> unless otherwise specified. You may find + it convenient to derive new models of <a href= + "CallPolicies.html">CallPolicies</a> from + <code>default_call_policies</code>. + + <h4><a name="default_call_policies-spec-synopsis"></a>Class + <code>default_call_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct default_call_policies + { + static bool precall(PyObject*); + static PyObject* postcall(PyObject*, PyObject* result); + typedef <a href= +"#default_result_converter-spec">default_result_converter</a> result_converter; + template <class Sig> struct extract_return_type : mpl::front<Sig>{}; + }; +}} +</pre> + + <h4><a name="default_call_policies-spec-statics"></a>Class + <code>default_call_policies</code> static functions</h4> +<pre> +bool precall(PyObject*); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>true</code> + + <dt><b>Throws:</b> nothing + </dl> +<pre> +PyObject* postcall(PyObject*, PyObject* result); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>result</code> + + <dt><b>Throws:</b> nothing + </dl> + + <h3><a name="default_result_converter-spec"></a>Class + <code>default_result_converter</code></h3> + + <p><code>default_result_converter</code> is a model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be + used to wrap C++ functions returning non-pointer types, <code>char + const*</code>, and <code>PyObject*</code>, by-value. + + <h4><a name="default_result_converter-spec-synopsis"></a>Class + <code>default_result_converter</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct default_result_converter + { + template <class T> struct apply; + }; +}} +</pre> + + <h4><a name="default_result_converter-spec-metafunctions"></a>Class + <code>default_result_converter</code> metafunctions</h4> +<pre> +template <class T> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Requires:</b> <code>T</code> is not a reference type. If + <code>T</code> is a pointer type, <code>T</code> is <code>const + char*</code> or <code>PyObject*</code>. + + <dt><b>Returns:</b> <code>typedef <a href= + "to_python_value.html#to_python_value-spec">to_python_value</a><T + const&> type;</code> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <p>This example comes from the Boost.Python implementation itself. Because + the <a href= + "return_value_policy.html#return_value_policy-spec">return_value_policy</a> + class template does not implement <code>precall</code> or + <code>postcall</code> behavior, its default base class is + <code>default_call_policies</code>: +<pre> +template <class Handler, class Base = default_call_policies> +struct return_value_policy : Base +{ + typedef Handler result_converter; +}; +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 11 June, 2007 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002.</i> Distributed under the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt)</p> + diff --git a/libs/python/doc/v2/definitions.html b/libs/python/doc/v2/definitions.html new file mode 100644 index 000000000..cfec181c7 --- /dev/null +++ b/libs/python/doc/v2/definitions.html @@ -0,0 +1,102 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - 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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></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> + + <dd><br> + </dd> + + <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> + + <dd><br> + </dd> + + <dt><b><a name="raise">raise</a>:</b> Exceptions in Python are + "raised", not "thrown", as they are in C++. When this documentation + says that some Python exception is "raised" in the context of C++ code, + it means that the corresponding Python exception is set via the <a + href= + "http://www.python.org/doc/current/api/exceptionHandling.html">Python/'C' + API</a>, and <code><a href= + "errors.html#throw_error_already_set-spec">throw_error_already_set</a>()</code> + is called.</dt> + + <dd><br> + </dd> + + <dt><b><a name="POD">POD</a>:</b> A technical term from the C++ + standard. Short for "Plain Ol'Data": A POD-struct is an aggregate class + that has no non-static data members of type pointer to member, + non-POD-struct, non-POD-union (or array of such types) or reference, + and has no user-defined copy assign- ment operator and no user-defined + destructor. Similarly, a POD-union is an aggregate union that has no + non-static data members of type pointer to member, non-POD-struct, + non-POD-union (or array of such types) or reference, and has no + user-defined copy assignment operator and no user-defined destructor. A + POD class is a class that is either a POD-struct or a POD-union. An + aggregate is an array or a class (clause 9) with no user-declared + constructors (12.1), no private or protected non-static data members + (clause 11), no base classes (clause 10), and no virtual functions + (10.3).</dt> + + <dd><br> + </dd> + + <dt><b><a name="ODR">ODR</a>:</b> The "One Definition + Rule", which says that any entity in a C++ program must have the same definition in all translation units (object files) which make up a program. + </dt> + + <dd><br> + </dd> + + + </dl> + <hr> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/dict.html b/libs/python/doc/v2/dict.html new file mode 100644 index 000000000..82ea13653 --- /dev/null +++ b/libs/python/doc/v2/dict.html @@ -0,0 +1,152 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/dict.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/dict.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="#dict-spec">Class <code>dict</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#dict-spec-synopsis">Class <code>dict</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>Exposes a <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python + <a href= + "http://www.python.org/dev/doc/devel/lib/typesmapping.html">dict</a> + type.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="dict-spec"></a>Class <code>dict</code></h3> + + <p>Exposes the <a href= + "http://www.python.org/dev/doc/devel/lib/typesmapping.html">mapping + protocol</a> of Python's built-in <code>dict</code> type. The semantics + of the constructors and member functions defined below can be fully + understood by reading the <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept + definition. Since <code>dict</code> is publicly derived from <code><a + href="object.html#object-spec">object</a></code>, the public object + interface applies to <code>dict</code> instances as well.</p> + + <h4><a name="dict-spec-synopsis"></a>Class <code>dict</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class dict : public object + { + dict(); + + template< class T > + dict(T const & data); + + // modifiers + void clear(); + dict copy(); + + template <class T1, class T2> + tuple popitem(); + + template <class T> + object setdefault(T const &k); + + template <class T1, class T2> + object setdefault(T1 const & k, T2 const & d); + + void update(object_cref E); + + template< class T > + void update(T const & E); + + // observers + list values() const; + + object get(object_cref k) const; + + template<class T> + object get(T const & k) const; + + object get(object_cref k, object_cref d) const; + object get(T1 const & k, T2 const & d) const; + + bool has_key(object_cref k) const; + + template< class T > + bool has_key(T const & k) const; + + list items() const; + object iteritems() const; + object iterkeys() const; + object itervalues() const; + list keys() const; + }; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> +<pre> +using namespace boost::python; +dict swap_object_dict(object target, dict d) +{ + dict result = extract<dict>(target.attr("__dict__")); + target.attr("__dict__") = d; + return result; +} +</pre> + + <p>Revised 30 September, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/docstring_options.html b/libs/python/doc/v2/docstring_options.html new file mode 100644 index 000000000..a2a0cc645 --- /dev/null +++ b/libs/python/doc/v2/docstring_options.html @@ -0,0 +1,386 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> +<head> + <meta name="generator" content= + "HTML Tidy for Linux/x86 (vers 1st September 2004), see www.w3.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - + <boost/python/docstring_options.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="../../../../boost.png" border= + "0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href= + "../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/docstring_options.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="#docstring_options-spec">Class + <code>docstring_options</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#docstring_options-spec-synopsis">Class + <code>docstring_options</code> synopsis</a></dt> + + <dt><a href="#docstring_options-spec-ctors">Class + <code>docstring_options</code> constructors</a></dt> + + <dt><a href="#docstring_options-spec-dtors">Class + <code>docstring_options</code> destructors</a></dt> + + <dt><a href="#docstring_options-spec-modifiers">Class + <code>docstring_options</code> modifiers</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction" id= + "introduction"></a>Introduction</h2> + + <p>Boost.Python supports user-defined docstrings with automatic + appending of C++ signatures. These features are enabled by + default. The <code>class docstring_options</code> is available to + selectively suppress the user-defined docstrings, signatures, or + both.</p> + + <h2><a name="classes" id="classes"></a>Classes</h2> + + <h3><a name="docstring_options-spec" id= + "docstring_options-spec"></a>Class + <code>docstring_options</code></h3> + + <p>Controls the appearance of docstrings of wrapped functions and + member functions for the life-time of the instance. The instances + are noncopyable to eliminate the possibility of surprising side + effects.</p> + + <h4><a name="docstring_options-spec-synopsis" id= + "docstring_options-spec-synopsis"></a>Class + <code>docstring_options</code> synopsis</h4> + <pre> +namespace boost { namespace python { + + class docstring_options : boost::noncopyable + { + public: + docstring_options(bool show_all=true); + + docstring_options(bool show_user_defined, bool show_signatures); + + docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); + + ~docstring_options(); + + void + disable_user_defined(); + + void + enable_user_defined(); + + void + disable_signatures(); + + void + enable_signatures(); + + void + disable_py_signatures(); + + void + enable_py_signatures(); + + void + disable_cpp_signatures(); + + void + enable_cpp_signatures(); + + void + disable_all(); + + void + enable_all(); + }; + +}} +</pre> + + <h4><a name="docstring_options-spec-ctors" id= + "docstring_options-spec-ctors"></a>Class + <code>docstring_options</code> constructors</h4> + <pre> +docstring_options(bool show_all=true); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Constructs a <code>docstring_options</code> + object which controls the appearance of function and + member-function docstrings defined in the code that follows. If + <code>show_all</code> is <code>true</code>, both the + user-defined docstrings and the automatically generated Python and C++ + signatures are shown. If <code>show_all</code> is + <code>false</code> the <code>__doc__</code> attributes are + <code>None</code>.</dt> + </dl> + <pre> +docstring_options(bool show_user_defined, bool show_signatures); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Constructs a <code>docstring_options</code> + object which controls the appearance of function and + member-function docstrings defined in the code that follows. + Iff <code>show_user_defined</code> is <code>true</code>, the + user-defined docstrings are shown. Iff + <code>show_signatures</code> is <code>true</code>, Python and C++ + signatures are automatically added. If both + <code>show_user_defined</code> and <code>show_signatures</code> + are <code>false</code>, the <code>__doc__</code> attributes are + <code>None</code>.</dt> + </dl> + <pre> +docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Constructs a <code>docstring_options</code> + object which controls the appearance of function and + member-function docstrings defined in the code that follows. + Iff <code>show_user_defined</code> is <code>true</code>, the + user-defined docstrings are shown. Iff + <code>show_py_signatures</code> is <code>true</code>, Python + signatures are automatically added. Iff + <code>show_cpp_signatures</code> is <code>true</code>, C++ + signatures are automatically added. If all parameters are + <code>false</code>, the <code>__doc__</code> attributes are + <code>None</code>.</dt> + </dl> + + <h4><a name="docstring_options-spec-dtors" id= + "docstring_options-spec-dtors"></a>Class + <code>docstring_options</code> destructors</h4> + <pre> +~docstring_options(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Restores the previous state of the + docstring options. In particular, if + <code>docstring_options</code> instances are in nested C++ + scopes the settings effective in the enclosing scope are + restored. If the last <code>docstring_options</code> instance + goes out of scope the default "all on" settings are + restored.</dt> + </dl> + + <h4><a name="docstring_options-spec-modifiers" id= + "docstring_options-spec-modifiers"></a>Class + <code>docstring_options</code> modifier functions</h4> + <pre> +void disable_user_defined(); +void enable_user_defined(); +void disable_signatures(); +void enable_signatures(); +void disable_py_signatures(); +void enable_py_signatures(); +void disable_cpp_signatures(); +void enable_cpp_signatures(); +void disable_all(); +void enable_all(); +</pre> + + <dl class="function-semantics"> + <dt>These member functions dynamically change the appearance of + docstrings in the code that follows. The + <code>*_user_defined()</code> and <code>*_signatures()</code> + member functions are provided for fine-grained control. The + <code>*_all()</code> member functions are convenient shortcuts + to manipulate all settings simultaneously.</dt> + </dl> + + <h2><a name="examples" id="examples"></a>Examples</h2> + + <h4>Docstring options defined at compile time</h4> + <pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/docstring_options.hpp> + +void foo() {} + +BOOST_PYTHON_MODULE(demo) +{ + using namespace boost::python; + docstring_options doc_options(DEMO_DOCSTRING_SHOW_ALL); + def("foo", foo, "foo doc"); +} +</pre>If compiled with <code>-DDEMO_DOCSTRING_SHOW_ALL=true</code>: + <pre> +>>> import demo +>>> print demo.foo.__doc__ +foo() -> None : foo doc +C++ signature: + foo(void) -> void +</pre>If compiled with +<code>-DDEMO_DOCSTRING_SHOW_ALL=false</code>: + <pre> +>>> import demo +>>> print demo.foo.__doc__ +None +</pre> + + <h4>Selective suppressions</h4> + <pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/args.hpp> +#include <boost/python/docstring_options.hpp> + +int foo1(int i) { return i; } +int foo2(long l) { return static_cast<int>(l); } +int foo3(float f) { return static_cast<int>(f); } +int foo4(double d) { return static_cast<int>(d); } + +BOOST_PYTHON_MODULE(demo) +{ + using namespace boost::python; + docstring_options doc_options; + def("foo1", foo1, arg("i"), "foo1 doc"); + doc_options.disable_user_defined(); + def("foo2", foo2, arg("l"), "foo2 doc"); + doc_options.disable_signatures(); + def("foo3", foo3, arg("f"), "foo3 doc"); + doc_options.enable_user_defined(); + def("foo4", foo4, arg("d"), "foo4 doc"); + doc_options.enable_py_signatures(); + def("foo5", foo4, arg("d"), "foo5 doc"); + doc_options.disable_py_signatures(); + doc_options.enable_cpp_signatures(); + def("foo6", foo4, arg("d"), "foo6 doc"); +} +</pre>Python code: + <pre> +>>> import demo +>>> print demo.foo1.__doc__ +foo1( (int)i) -> int : foo1 doc +C++ signature: + foo1(int i) -> int +>>> print demo.foo2.__doc__ +foo2( (int)l) -> int : +C++ signature: + foo2(long l) -> int +>>> print demo.foo3.__doc__ +None +>>> print demo.foo4.__doc__ +foo4 doc +>>> print demo.foo5.__doc__ +foo5( (float)d) -> int : foo5 doc +>>> print demo.foo6.__doc__ +foo6 doc +C++ signature: + foo6(double d) -> int +</pre> + + <h4>Wrapping from multiple C++ scopes</h4> + <pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/args.hpp> +#include <boost/python/docstring_options.hpp> + +int foo1(int i) { return i; } +int foo2(long l) { return static_cast<int>(l); } + +int bar1(int i) { return i; } +int bar2(long l) { return static_cast<int>(l); } + +namespace { + + void wrap_foos() + { + using namespace boost::python; + // no docstring_options here + // -> settings from outer C++ scope are in effect + def("foo1", foo1, arg("i"), "foo1 doc"); + def("foo2", foo2, arg("l"), "foo2 doc"); + } + + void wrap_bars() + { + using namespace boost::python; + bool show_user_defined = true; + bool show_signatures = false; + docstring_options doc_options(show_user_defined, show_signatures); + def("bar1", bar1, arg("i"), "bar1 doc"); + def("bar2", bar2, arg("l"), "bar2 doc"); + } +} + +BOOST_PYTHON_MODULE(demo) +{ + boost::python::docstring_options doc_options(false); + wrap_foos(); + wrap_bars(); +} +</pre>Python code: + <pre> +>>> import demo +>>> print demo.foo1.__doc__ +None +>>> print demo.foo2.__doc__ +None +>>> print demo.bar1.__doc__ +bar1 doc +>>> print demo.bar2.__doc__ +bar2 doc +</pre> + + <h4>See also: <code>boost/libs/python/test/docstring.cpp</code> + and <code>docstring.py</code></h4> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 16 January, 2006 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. + Grosse-Kunstleve</a> 2006.</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/enum.html b/libs/python/doc/v2/enum.html new file mode 100644 index 000000000..c5ec2b921 --- /dev/null +++ b/libs/python/doc/v2/enum.html @@ -0,0 +1,234 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/enum.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/enum.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="#enum_-spec">Class template + <code>enum_</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#enum_-spec-synopsis">Class template <code>enum_</code> + synopsis</a></dt> + + <dt><a href="#enum_-spec-ctors">Class template <code>enum_</code> + constructors</a></dt> + + <dt><a href="#enum_-spec-modifiers">Class template <code>enum_</code> + modifier functions</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/enum.hpp></code> defines the + interface through which users expose their C++ enumeration types + to Python. It declares the + <code>enum_</code> class template, which is parameterized on the + enumeration type being exposed. </p> + + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="enum_-spec"></a>Class template + <code>enum_<T></code></h3> + + <p>Creates a Python class derived from Python's <code>int</code> + type which is associated with the C++ type passed as its first + parameter. + + <h4><a name="enum_-spec-synopsis"></a>Class template <code>enum_</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> + class enum_ : public <a href="object.html#object-spec">object</a> + { + enum_(char const* name, char const* doc = 0); + enum_<T>& value(char const* name, T); + enum_<T>& export_values(); + }; +}} +</pre> + + <h4><a name="enum_-spec-ctors"></a>Class template <code>enum_</code> + constructors</h4> +<pre> +enum_(char const* name, char const* doc=0); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <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><b>Effects:</b> Constructs an <code>enum_</code> object + holding a Python extension type derived from <code>int</code> + which is 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 type.</dt> + </dl> + + <h4><a name="enum_-spec-modifiers"></a>Class template + <code>enum_</code> modifier functions</h4> +<pre> +inline enum_<T>& value(char const* name, T x); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is an <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><b>Effects:</b> adds an instance of the wrapped enumeration + type with value <code>x</code> to the type's dictionary as the + <code>name</code>d attribute.</dt> + + <dt><b>Returns:</b> <code>*this</code></dt> + + </dl> + +<pre> +inline enum_<T>& export_values(); +</pre> + + <dl class="function-semantics"> + + <dt><b>Effects:</b> sets attributes in the current <a + href="scope.html#scope-spec"><code>scope</code></a> with the + same names and values as all enumeration values exposed so far + by calling <code>value()</code>.</dt> + + <dt><b>Returns:</b> <code>*this</code></dt> + + </dl> + + <h2><a name="examples"></a>Example(s)</h2> + + <p>C++ module definition +<pre> +#include <boost/python/enum.hpp> +#include <boost/python/def.hpp> +#include <boost/python/module.hpp> + +using namespace boost::python; + +enum color { red = 1, green = 2, blue = 4 }; + +color identity_(color x) { return x; } + +BOOST_PYTHON_MODULE(enums) +{ + enum_<color>("color") + .value("red", red) + .value("green", green) + .export_values() + .value("blue", blue) + ; + + def("identity", identity_); +} +</pre> + <p>Interactive Python: +<pre> +>>> from enums import * + +>>> identity(red) +enums.color.red + +>>> identity(color.red) +enums.color.red + +>>> identity(green) +enums.color.green + +>>> identity(color.green) +enums.color.green + +>>> identity(blue) +Traceback (most recent call last): + File "<stdin>", line 1, in ? +NameError: name blue' is not defined + +>>> identity(color.blue) +enums.color.blue + +>>> identity(color(1)) +enums.color.red + +>>> identity(color(2)) +enums.color.green + +>>> identity(color(3)) +enums.color(3) + +>>> identity(color(4)) +enums.color.blue + +>>> identity(1) +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: bad argument type for built-in operation +</pre> + <hr> + + Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 December, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/errors.html b/libs/python/doc/v2/errors.html new file mode 100644 index 000000000..69a3cf570 --- /dev/null +++ b/libs/python/doc/v2/errors.html @@ -0,0 +1,289 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/errors.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/errors.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="#error_already_set-spec">Class + <code>error_already_set</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#error_already_set-spec-synopsis">Class + <code>error_already_set</code> synopsis</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#handle_exception-spec">handle_exception</a></dt> + + <dt><a href="#expect_non_null-spec">expect_non_null</a></dt> + + <dt><a href= + "#throw_error_already_set-spec">throw_error_already_set</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/errors.hpp></code> provides types and + functions for managing and translating between Python and C++ exceptions. + This is relatively low-level functionality that is mostly used internally + by Boost.Python. Users should seldom need it.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="error_already_set-spec"></a>Class + <code>error_already_set</code></h3> + + <p><code>error_already_set</code> is an exception type which can be + thrown to indicate that a Python error has occurred. If thrown, the + precondition is that <a href= + "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred()</a> + returns a value convertible to <code>true</code>. Portable code shouldn't + throw this exception type directly, but should instead use <code><a href= + "#throw_error_already_set-spec">throw_error_already_set</a>()</code>, + below.</p> + + <h4><a name="error_already_set-spec-synopsis"></a>Class error_already_set + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class error_already_set {}; +}} +</pre> + + <h2><a name="functions"></a>Functions</h2> +<pre> +<a name= +"handle_exception-spec">template <class T> bool handle_exception</a>(T f) throw(); + +void handle_exception() throw(); +</pre> + + <dl class="handle_exception-semantics"> + <dt><b>Requires:</b> The first form requires that the expression + <code><a href= + "../../../../doc/html/functionN.html">function0</a><void>(f)</code> + is valid. The second form requires that a C++ exception is currently + being handled (see section 15.1 in the C++ standard).</dt> + + <dt><b>Effects:</b> The first form calls <code>f()</code> inside a + <code>try</code> block which first attempts to use all registered <a + href="exception_translator.html">exception translators</a>. If none of + those translates the exception, the <code>catch</code> clauses then set + an appropriate Python exception for the C++ exception caught, returning + <code>true</code> if an exception was thrown, <code>false</code> + otherwise. The second form passes a function which rethrows the + exception currently being handled to the first form.</dt> + + <dt><b>Postconditions:</b> No exception is being handled</dt> + + <dt><b>Throws:</b> nothing</dt> + + <dt><b>Rationale:</b> At inter-language boundaries it is important to + ensure that no C++ exceptions escape, since the calling language + usually doesn't have the equipment necessary to properly unwind the + stack. Use <code>handle_exception</code> to manage exception + translation whenever your C++ code is called directly from the Python + API. This is done for you automatically by the usual function wrapping + facilities: <code><a href= + "make_function.html#make_function-spec">make_function</a>()</code>, + <code><a href= + "make_function.html#make_constructor-spec">make_constructor</a>()</code>, + <code><a href="def.html#class_-spec-modifiers">def</a>()</code> and <code><a href= + "class.html#def-spec">class_::def</a>()</code>. The second form can be + more convenient to use (see the <a href="#examples">example</a> below), + but various compilers have problems when exceptions are rethrown from + within an enclosing <code>try</code> block.</dt> + </dl> +<pre> +<a name= +"expect_non_null-spec">template <class T> T* expect_non_null(T* x);</a> +</pre> + + <dl class="expect_non_null-semantics"> + <dt><b>Returns:</b> <code>x</code></dt> + + <dt><b>Throws:</b> <code><a href= + "#error_already_set-spec">error_already_set</a>()</code> iff <code>x == + 0</code>.</dt> + + <dt><b>Rationale:</b> Simplifies error-handling when calling functions + in the <a href="http://www.python.org/doc/2.2/api/api.html">Python/C + API</a> which return 0 on error.</dt> + </dl> +<pre> +<a name="throw_error_already_set-spec">void throw_error_already_set();</a> +</pre> + + <dl class="throw_error_already_set-semantics"> + <dt><b>Effects:</b> <code>throw <a href= + "#error_already_set-spec">error_already_set</a>();</code></dt> + </dl> + + <dl> + <dt><b>Rationale:</b> Many platforms and compilers are not able to + consistently catch exceptions thrown across shared library boundaries. + Using this function from the Boost.Python library ensures that the + appropriate <code>catch</code> block in <code><a href= + "#handle_exception-spec">handle_exception</a>()</code> can catch the + exception.</dt> + </dl> + + <h2><a name="examples"></a>Examples</h2> +<pre> +#include <string> +#include <boost/python/errors.hpp> +#include <boost/python/object.hpp> +#include <boost/python/handle.hpp> + +// Returns a std::string which has the same value as obj's "__name__" +// attribute. +std::string get_name(boost::python::object obj) +{ + // throws if there's no __name__ attribute + PyObject* p = boost::python::expect_non_null( + PyObject_GetAttrString(obj.ptr(), "__name__")); + + char const* s = PyString_AsString(p); + if (s != 0) + Py_DECREF(p); + + // throws if it's not a Python string + std::string result( + boost::python::expect_non_null( + PyString_AsString(p))); + + Py_DECREF(p); // Done with p + + return result; +} + +// +// Demonstrate form 1 of handle_exception +// + +// Place into result a Python Int object whose value is 1 if a and b have +// identical "__name__" attributes, 0 otherwise. +void same_name_impl(PyObject*& result, boost::python::object a, boost::python::object b) +{ + result = PyInt_FromLong( + get_name(a) == get_name(a2)); +} + +object borrowed_object(PyObject* p) +{ + return boost::python::object( + boost::python::handle<>( + boost::python::borrowed(a1))); +} + +// This is an example Python 'C' API interface function +extern "C" PyObject* +same_name(PyObject* args, PyObject* keywords) +{ + PyObject* a1; + PyObject* a2; + PyObject* result = 0; + + if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2)) + return 0; + + // Use boost::bind to make an object compatible with + // boost::Function0<void> + if (boost::python::handle_exception( + boost::bind<void>(same_name_impl, boost::ref(result), borrowed_object(a1), borrowed_object(a2)))) + { + // an exception was thrown; the Python error was set by + // handle_exception() + return 0; + } + + return result; +} + +// +// Demonstrate form 2 of handle_exception. Not well-supported by all +// compilers. +// +extern "C" PyObject* +same_name2(PyObject* args, PyObject* keywords) +{ + PyObject* a1; + PyObject* a2; + PyObject* result = 0; + + if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2)) + return 0; + + try { + return PyInt_FromLong( + get_name(borrowed_object(a1)) == get_name(borrowed_object(a2))); + } + catch(...) + { + // If an exception was thrown, translate it to Python + boost::python::handle_exception(); + return 0; + } +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/exception_translator.html b/libs/python/doc/v2/exception_translator.html new file mode 100644 index 000000000..4cc7bb91b --- /dev/null +++ b/libs/python/doc/v2/exception_translator.html @@ -0,0 +1,150 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/exception_translator.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/exception_translator.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href= + "#register_exception_translator-spec">register_exception_translator</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>As described <a href="errors.html#handle_exception-spec">here</a>, it + is important to make sure that exceptions thrown by C++ code do not pass + into the Python interpreter core. By default, Boost.Python translates all + C++ exceptions thrown by wrapped functions and module init functions into + Python, but the default translators are extremely limited: most C++ + exceptions will appear in Python as a <a href= + "http://www.python.org/doc/current/lib/module-exceptions.html">RuntimeError</a> + exception whose representation is + <code>'Unidentifiable C++ Exception'</code>. To produce better + error messages, users can register additional exception translators as + described below.</p> + + <h2><a name="functions"></a>Functions</h2> + +<h3><code><a name="register_exception_translator-spec">register_exception_translator</a></code></h3> + +<pre> +<a name="register_exception_translator-spec">template<class ExceptionType, class Translate></a> +void register_exception_translator(Translate translate); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b></dt> + + <dd> + <code>Translate</code> is <a href= + "../../../utility/CopyConstructible.html">Copyconstructible</a>, and + the following code must be well-formed: +<pre> +void f(ExceptionType x) { translate(x); } +</pre> + The expression <code>translate(x)</code> must either throw a C++ + exception, or a subsequent call to <code><a href= + "http://www.python.org/doc/current/api/exceptionHandling.html">PyErr_Occurred</a>()</code> + must return 1. + </dd> + + <p> + + <dt><b>Effects:</b> Adds a copy of <code>translate</code> to the sequence of + exception translators tried when Boost.Python catches an exception that + is about to pass into Python's core interpreter. The new translator + will get "first shot" at translating all exceptions matching the catch + clause shown above. Any subsequently-registered translators will be + allowed to translate the exception earlier. A translator which cannot + translate a given C++ exception can re-throw it, and it will be handled + by a translator which was registered earlier (or by the default + translator).</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/exception_translator.hpp> +#include <exception> + +struct my_exception : std::exception +{ + char const* what() throw() { return "One of my exceptions"; } +}; + +void translate(my_exception const& e) +{ + // Use the Python 'C' API to set up an exception object + PyErr_SetString(PyExc_RuntimeError, e.what()); +} + +void something_which_throws() +{ + ... + throw my_exception(); + ... +} + +BOOST_PYTHON_MODULE(exception_translator_ext) +{ + using namespace boost::python; + register_exception_translator<my_exception>(&translate); + + def("something_which_throws", something_which_throws); +} +</pre> + <br> + <br> + + <hr> + + <p>Revised 03 October, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/exec.html b/libs/python/doc/v2/exec.html new file mode 100644 index 000000000..83d2c9b89 --- /dev/null +++ b/libs/python/doc/v2/exec.html @@ -0,0 +1,163 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/exec.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/exec.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#eval-spec"><code>eval</code></a></dt> + <dt><a href="#exec-spec"><code>exec</code></a></dt> + <dt><a href="#exec_file-spec"><code>exec_file</code></a></dt> + </dl> + </dd> + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Exposes a mechanism for embedding the python interpreter into C++ code.</p> + + <h2><a name="functions"></a>Functions</h2> + + <h3><a name="eval-spec"></a><code>eval</code></h3> + <pre> +object eval(str expression, + object globals = object(), + object locals = object()); + </pre> + <dl class="function-semantics"> + <dt><b>Effects:</b> + Evaluate Python expression from <code>expression</code> in the context + specified by the dictionaries <code>globals</code> and <code>locals</code>. + </dt> + <dt><b>Returns:</b> + An instance of <a href="object.html#object-spec">object</a> + which holds the value of the expression. + </dt> + </dl> + + <h3><a name="exec-spec"></a><code>exec</code></h3> + <pre> +object exec(str code, + object globals = object(), + object locals = object()); + </pre> + <dl class="function-semantics"> + <dt><b>Effects:</b> + Execute Python source code from <code>code</code> in the context + specified by the dictionaries <code>globals</code> and <code>locals</code>. + </dt> + <dt><b>Returns:</b> + An instance of <a href="object.html#object-spec">object</a> + which holds the result of executing the code. + </dt> + </dl> + + <h3><a name="exec_file-spec"></a><code>exec_file</code></h3> + <pre> +object exec_file(str filename, + object globals = object(), + object locals = object()); + </pre> + <dl class="function-semantics"> + <dt><b>Effects:</b> + Execute Python source code from the file named by <code>filename</code> + in the context specified by the dictionaries <code>globals</code> and + <code>locals</code>. + </dt> + <dt><b>Returns:</b> + An instance of <a href="object.html#object-spec">object</a> + which holds the result of executing the code. + </dt> + </dl> + + <h2><a name="examples"></a>Examples</h2> + + <para>The following example demonstrates the use of <function>import</function> + and <function>exec</function> to define a function in python, and later call + it from within C++.</para> + +<pre> +#include <iostream> +#include <string> + +using namespace boost::python; + +void greet() +{ + // Retrieve the main module. + object main = import("__main__"); + + // Retrieve the main module's namespace + object global(main.attr("__dict__")); + + // Define greet function in Python. + object result = exec( + "def greet(): \n" + " return 'Hello from Python!' \n", + global, global); + + // Create a reference to it. + object greet = global["greet"]; + + // Call it. + std::string message = extract<std::string>(greet()); + std::cout << message << std::endl; +} +</pre> + + <para>Instead of embedding the python script into a string, + we could also store it in an a file...</para> + +<pre> +def greet(): + return 'Hello from Python!' +</pre> + <para>... and execute that instead.</para> +<pre> + // ... + // Load the greet function from a file. + object result = exec_file(script, global, global); + // ... +} +</pre> + <p>Revised 01 November, 2005</p> + + <p><i>© Copyright Stefan Seefeld 2005.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/extract.html b/libs/python/doc/v2/extract.html new file mode 100644 index 000000000..3c6b77f2f --- /dev/null +++ b/libs/python/doc/v2/extract.html @@ -0,0 +1,232 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/extract.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/extract.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="#extract-spec">Class <code>extract</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#extract-spec-synopsis">Class <code>extract</code> + synopsis</a></dt> + + <dt><a href="#extract-spec-ctors">Class <code>extract</code> + constructors and destructor</a></dt> + + <dt><a href="#extract-spec-observers">Class + <code>extract</code> observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Exposes a mechanism for extracting C++ object values from + generalized Python objects. Note that + <code>extract<</code>...<code>></code> can also be used to + "downcast" an <a + href="object.html#object-spec">object</a> to some specific <a + href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>. Because + invoking a mutable python type with an argument of the same type + (e.g. <code>list([1,2])</code> typically makes a <em>copy</em> of + the argument object, this may be the only way to access the <a + href="ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a>'s + interface on the original object. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="extract-spec"></a>Class template <code>extract</code></h3> + + <p><code>extract<T></code> can be used to extract a value of + an arbitrary C++ type from an instance of <code><a + href="object.html#object-spec">object</a></code>. Two usages are supported: +<ol> +<li><b><code>extract<T>(o)</code></b> is a temporary object +which is implicitly convertible to <code>T</code> (explicit conversion +is also available through the object's function-call +operator). However, if no conversion is available which can convert +<code>o</code> to an object of type <code>T</code>, a Python +<code>TypeError</code> exception will be <a +href="definitions.html#raise">raised</a>. + +<li><b><code>extract<T> x(o);</code></b> constructs an extractor +whose <code>check()</code> member function can be used to ask whether +a conversion is available without causing an exception to be thrown. +</ol> + + <h4><a name="extract-spec-synopsis"></a>Class template <code>extract</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> + struct extract + { + typedef <i>unspecified</i> result_type; + + extract(PyObject*); + extract(object const&); + + result_type operator()() const; + operator result_type() const; + + bool check() const; + }; +}} +</pre> + + <h4><a name="extract-spec-ctors"></a>Class <code>extract</code> + constructors and destructor</h4> +<pre> +extract(PyObject* p); +extract(object const&); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> The first form requires that <code>p</code> is non-null.</dt> + + <dt><b>Effects:</b>Stores a pointer to the Python object managed + by its constructor argument. In particular, the reference + count of the object is not incremented. The onus is on the user + to be sure it is not destroyed before the extractor's conversion + function is called.</dt> + </dl> + + <h4><a name="extract-spec-observers"></a>Class <code>extract</code> + observer functions</h4> +<pre> +result_type operator()() const; +operator result_type() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Converts the stored pointer to + <code>result_type</code>, which is either <code>T</code> or + <code>T const&</code>. + </dt> + + <dt><b>Returns:</b> An object of <code>result_type</code> + corresponding to the one referenced by the stored pointer.</dt> + + <dt><b>Throws:</b> <code><a + href="errors.html#error_already_set-spec">error_already_set</a></code> + and sets a <code>TypeError</code> if no such conversion is + available. May also emit other unspecified exceptions thrown by + the converter which is actually used.</dt> + </dl> + +<pre> +bool check() const; +</pre> + + <dl class="function-semantics"> + + <dt><b>Postconditions:</b> None. In particular, note that a + return value of <code>true</code> does not preclude an exception + being thrown from <code>operator result_type()</code> or + <code>operator()()</code>.</dt> + + <dt><b>Returns:</b> <code>false</code> <i>only</i> if no conversion from the + stored pointer to <code>T</code> is available.</dt> + + </dl> + + + <h2><a name="examples"></a>Examples</h2> + +<pre> +#include <cstdio> +using namespace boost::python; +int Print(str s) +{ + // extract a C string from the Python string object + char const* c_str = extract<char const*>(s); + + // Print it using printf + std::printf("%s\n", c_str); + + // Get the Python string's length and convert it to an int + return extract<int>(s.attr("__len__")()) +} +</pre> + +The following example shows how extract can be used along with +<code><a +href="class.html#class_-spec">class_</a><</code>...<code>></code> +to create and access an instance of a wrapped C++ class. + +<pre> +struct X +{ + X(int x) : v(x) {} + int value() { return v; } + private: + int v; +}; + +BOOST_PYTHON_MODULE(extract_ext) +{ + object x_class( + class_<X>("X", init<int>()) + .def("value", &X::value)) + ; + + // Instantiate an X object through the Python interface. + // Its lifetime is now managed by x_obj. + object x_obj = x_class(3); + + // Get a reference to the C++ object out of the Python object + X& x = extract<X&>(x_obj); + assert(x.value() == 3); +} +</pre> + <p>Revised 15 November, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/faq.html b/libs/python/doc/v2/faq.html new file mode 100644 index 000000000..75283d77c --- /dev/null +++ b/libs/python/doc/v2/faq.html @@ -0,0 +1,861 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 2002), see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + <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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Frequently Asked Questions (FAQs)</h2> + </td> + </tr> + </table> + <hr> + + <dl class="page-index"> + + <dt><a href="#funcptr">How can I wrap a function which takes a + function pointer as an argument?</a><dd> + + <dt><a href="#dangling">I'm getting the "attempt to return dangling + reference" error. What am I doing wrong?</a></dt> + + <dt><a href="#question1">Is return_internal_reference + efficient?</a></dt> + + <dt><a href="#question2">How can I wrap functions which take C++ + containers as arguments?</a></dt> + + <dt><a href="#c1204">fatal error C1204:Compiler limit:internal + structure overflow</a></dt> + + <dt><a href="#debugging">How do I debug my Python extensions?</a></dt> + + <dt><a href="#imul">Why doesn't my <code>*=</code> operator + work?</a></dt> + + <dt><a href="#macosx">Does Boost.Python work with Mac OS X?</a></dt> + + <dt><a href="#xref">How can I find the existing PyObject that holds a + C++ object?</a></dt> + + <dt><a href="#ownership">How can I wrap a function which needs to take + ownership of a raw pointer?</a></dt> + + <dt><a href="#slow_compilation">Compilation takes too much time and eats too much memory! + What can I do to make it faster?</a></dt> + + <dt><a href="#packages">How do I create sub-packages using Boost.Python?</a></dt> + + <dt><a href="#msvcthrowbug" + >error C2064: term does not evaluate to a function taking 2 arguments</a> + </dt> + + <dt><a href="#custom_string" + >How can I automatically convert my custom string type to + and from a Python string?</a></dt> + + <dt><a href="#topythonconversionfailed">Why is my automatic to-python conversion not being + found?</a></dt> + + <dt><a href="#threadsupport">Is Boost.Python thread-aware/compatible with multiple interpreters?</a></dt> + </dl> + <hr> + + <h2><a name="funcptr">How can I wrap a function which takes a + function pointer as an argument?</a></h2> + + If what you're trying to do is something like this: +<pre> +typedef boost::function<void (string s) > funcptr; + +void foo(funcptr fp) +{ + fp("hello,world!"); +} + +BOOST_PYTHON_MODULE(test) +{ + def("foo",foo) ; +} +</pre> + +And then: + +<pre> +>>> def hello(s): +... print s +... +>>> foo(hello) +hello, world! +</pre> + + The short answer is: "you can't". This is not a + Boost.Python limitation so much as a limitation of C++. The + problem is that a Python function is actually data, and the only + way of associating data with a C++ function pointer is to store it + in a static variable of the function. The problem with that is + that you can only associate one piece of data with every C++ + function, and we have no way of compiling a new C++ function + on-the-fly for every Python function you decide to pass + to <code>foo</code>. In other words, this could work if the C++ + function is always going to invoke the <em>same</em> Python + function, but you probably don't want that. + + <p>If you have the luxury of changing the C++ code you're + wrapping, pass it an <code>object</code> instead and call that; + the overloaded function call operator will invoke the Python + function you pass it behind the <code>object</code>. + + <p>For more perspective on the issue, see <a + href="http://aspn.activestate.com/ASPN/Mail/Message/1554837">this + posting</a>. + + <hr> + + <h2><a name="dangling">I'm getting the "attempt to return dangling + reference" error. What am I doing wrong?</a></h2> + That exception is protecting you from causing a nasty crash. It usually + happens in response to some code like this: +<pre> +period const& get_floating_frequency() const +{ + return boost::python::call_method<period const&>( + m_self,"get_floating_frequency"); +} +</pre> + And you get: +<pre> +ReferenceError: Attempt to return dangling reference to object of type: +class period +</pre> + + <p>In this case, the Python method invoked by <code>call_method</code> + constructs a new Python object. You're trying to return a reference to a + C++ object (an instance of <code>class period</code>) contained within + and owned by that Python object. Because the called method handed back a + brand new object, the only reference to it is held for the duration of + <code>get_floating_frequency()</code> above. When the function returns, + the Python object will be destroyed, destroying the instance of + <code>class period</code>, and leaving the returned reference dangling. + That's already undefined behavior, and if you try to do anything with + that reference you're likely to cause a crash. Boost.Python detects this + situation at runtime and helpfully throws an exception instead of letting + you do that.<br> + </p> + <hr> + + <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> + <hr> + + <h2><a name="question2"></a>How can I wrap functions which take C++ + containers as arguments?</h2> + + <p>Ralf W. Grosse-Kunstleve provides these notes:</p> + + <ol> + <li> + Using the regular <code>class_<></code> wrapper: +<pre> +class_<std::vector<double> >("std_vector_double") + .def(...) + ... + ; +</pre> + This can be moved to a template so that several types (double, int, + long, etc.) can be wrapped with the same code. This technique is used + in the file + + <blockquote> + scitbx/include/scitbx/array_family/boost_python/flex_wrapper.h + </blockquote> + in the "scitbx" package. The file could easily be modified for + wrapping std::vector<> instantiations. + + <p>This type of C++/Python binding is most suitable for containers + that may contain a large number of elements (>10000).</p> + </li> + + <li> + Using custom rvalue converters. Boost.Python "rvalue converters" + match function signatures such as: +<pre> +void foo(std::vector<double> const& array); // pass by const-reference +void foo(std::vector<double> array); // pass by value +</pre> + Some custom rvalue converters are implemented in the file + + <blockquote> + scitbx/include/scitbx/boost_python/container_conversions.h + </blockquote> + This code can be used to convert from C++ container types such as + std::vector<> or std::list<> to Python tuples and vice + versa. A few simple examples can be found in the file + + <blockquote> + scitbx/array_family/boost_python/regression_test_module.cpp + </blockquote> + Automatic C++ container <-> Python tuple conversions are most + suitable for containers of moderate size. These converters generate + significantly less object code compared to alternative 1 above. + </li> + </ol> + A disadvantage of using alternative 2 is that operators such as + arithmetic +,-,*,/,% are not available. It would be useful to have custom + rvalue converters that convert to a "math_array" type instead of tuples. + This is currently not implemented but is possible within the framework of + Boost.Python V2 as it will be released in the next couple of weeks. [ed.: + this was posted on 2002/03/10] + + <p>It would also be useful to also have "custom lvalue converters" such + as std::vector<> <-> Python list. These converters would + support the modification of the Python list from C++. For example:</p> + + <p>C++:</p> +<pre> +void foo(std::vector<double>& array) +{ + for(std::size_t i=0;i<array.size();i++) { + array[i] *= 2; + } +} +</pre> + Python: +<pre> +>>> l = [1, 2, 3] +>>> foo(l) +>>> print l +[2, 4, 6] +</pre> + Custom lvalue converters require changes to the Boost.Python core library + and are currently not available. + + <p>P.S.:</p> + + <p>The "scitbx" files referenced above are available via anonymous + CVS:</p> +<pre> +cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx login +cvs -d:pserver:anonymous@cvs.cctbx.sourceforge.net:/cvsroot/cctbx co scitbx +</pre> + <hr> + + <h2><a name="c1204"></a>fatal error C1204:Compiler limit:internal + structure overflow</h2> + + <blockquote> + <b>Q:</b> <i>I get this error message when compiling a large source + file. What can I do?</i> + + <p><b>A:</b> You have two choices:</p> + + <ol> + <li>Upgrade your compiler (preferred)</li> + + <li> + Break your source file up into multiple translation units. + + <p><code><b>my_module.cpp</b></code>:</p> +<pre> +... +void more_of_my_module(); +BOOST_PYTHON_MODULE(my_module) +{ + def("foo", foo); + def("bar", bar); + ... + more_of_my_module(); +} +</pre> + <code><b>more_of_my_module.cpp</b></code>: +<pre> +void more_of_my_module() +{ + def("baz", baz); + ... +} +</pre> + If you find that a <code><a href= + "class.html#class_-spec">class_</a><...></code> declaration + can't fit in a single source file without triggering the error, you + can always pass a reference to the <code>class_</code> object to a + function in another source file, and call some of its member + functions (e.g. <code>.def(...)</code>) in the auxilliary source + file: + + <p><code><b>more_of_my_class.cpp</b></code>:</p> +<pre> +void more_of_my_class(class<my_class>& x) +{ + x + .def("baz", baz) + .add_property("xx", &my_class::get_xx, &my_class::set_xx) + ; + + ... +} +</pre> + </li> + </ol> + </blockquote> + <hr> + + <h2><a name="debugging"></a>How do I debug my Python extensions?</h2> + + <p>Greg Burley gives the following answer for Unix GCC users:</p> + + <blockquote> + Once you have created a boost python extension for your c++ library or + class, you may need to debug the code. Afterall this is one of the + reasons for wrapping the library in python. An expected side-effect or + benefit of using BPL is that debugging should be isolated to the c++ + library that is under test, given that python code is minimal and + boost::python either works or it doesn't. (ie. While errors can occur + when the wrapping method is invalid, most errors are caught by the + compiler ;-). + + <p>The basic steps required to initiate a gdb session to debug a c++ + library via python are shown here. Note, however that you should start + the gdb session in the directory that contains your BPL my_ext.so + module.</p> +<pre> +(gdb) target exec python +(gdb) run + >>> from my_ext import * + >>> [C-c] +(gdb) break MyClass::MyBuggyFunction +(gdb) cont + >>> pyobj = MyClass() + >>> pyobj.MyBuggyFunction() +Breakpoint 1, MyClass::MyBuggyFunction ... +Current language: auto; currently c++ +(gdb) do debugging stuff +</pre> + </blockquote> + + <p>Greg's approach works even better using Emacs' "<code>gdb</code>" + command, since it will show you each line of source as you step through + it.</p> + + <p>On <b>Windows</b>, my favorite debugging solution is the debugger that + comes with Microsoft Visual C++ 7. This debugger seems to work with code + generated by all versions of Microsoft and Metrowerks toolsets; it's rock + solid and "just works" without requiring any special tricks from the + user.</p> + + <p>Raoul Gough has provided the following for gdb on Windows:</p> + + <blockquote> + + <p>gdb support for Windows DLLs has improved lately, so it is + now possible to debug Python extensions using a few + tricks. Firstly, you will need an up-to-date gdb with support + for minimal symbol extraction from a DLL. Any gdb from version 6 + onwards, or Cygwin gdb-20030214-1 and onwards should do. A + suitable release will have a section in the gdb.info file under + Configuration – Native – Cygwin Native – + Non-debug DLL symbols. Refer to that info section for more + details of the procedures outlined here.</p> + + <p>Secondly, it seems necessary to set a breakpoint in the + Python interpreter, rather than using ^C to break execution. A + good place to set this breakpoint is PyOS_Readline, which will + stop execution immediately before reading each interactive + Python command. You have to let Python start once under the + debugger, so that it loads its own DLL, before you can set the + breakpoint:</p> + +<p> +<pre> +$ gdb python +GNU gdb 2003-09-02-cvs (cygwin-special) +[...] + +(gdb) run +Starting program: /cygdrive/c/Python22/python.exe +Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32 +Type "help", "copyright", "credits" or "license" for more information. +>>> ^Z + + +Program exited normally. +(gdb) break *&PyOS_Readline +Breakpoint 1 at 0x1e04eff0 +(gdb) run +Starting program: /cygdrive/c/Python22/python.exe +Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit (Intel)] on win32 +Type "help", "copyright", "credits" or "license" for more information. + +Breakpoint 1, 0x1e04eff0 in python22!PyOS_Readline () + from /cygdrive/c/WINNT/system32/python22.dll +(gdb) cont +Continuing. +>>> from my_ext import * + +Breakpoint 1, 0x1e04eff0 in python22!PyOS_Readline () + from /cygdrive/c/WINNT/system32/python22.dll +(gdb) # my_ext now loaded (with any debugging symbols it contains) +</pre> + </blockquote> + + <h3>Debugging extensions through Boost.Build</h3> + If you are launching your extension module tests with <a href= + "../../../../tools/build/v1/build_system.htm">Boost.Build</a> using the + <code>boost-python-runtest</code> rule, you can ask it to launch your + debugger for you by adding "--debugger=<i>debugger</i>" to your bjam + command-line: +<pre> +bjam -sTOOLS=vc7.1 "--debugger=devenv /debugexe" test +bjam -sTOOLS=gcc -sPYTHON_LAUNCH=gdb test +</pre> + It can also be extremely useful to add the <code>-d+2</code> option when + you run your test, because Boost.Build will then show you the exact + commands it uses to invoke it. This will invariably involve setting up + PYTHONPATH and other important environment variables such as + LD_LIBRARY_PATH which may be needed by your debugger in order to get + things to work right. + <hr> + + <h2><a name="imul"></a>Why doesn't my <code>*=</code> operator work?</h2> + + <blockquote> + <b>Q:</b> <i>I have exported my class to python, with many overloaded + operators. it works fine for me except the</i> <code>*=</code> + <i>operator. It always tells me "can't multiply sequence with non int + type". If I use</i> <code>p1.__imul__(p2)</code> <i>instead of</i> + <code>p1 *= p2</code><i>, it successfully executes my code. What's + wrong with me?</i> + + <p><b>A:</b> There's nothing wrong with you. This is a bug in Python + 2.2. You can see the same effect in Pure Python (you can learn a lot + about what's happening in Boost.Python by playing with new-style + classes in Pure Python).</p> +<pre> +>>> class X(object): +... def __imul__(self, x): +... print 'imul' +... +>>> x = X() +>>> x *= 1 +</pre> + To cure this problem, all you need to do is upgrade your Python to + version 2.2.1 or later. + </blockquote> + <hr> + + <h2><a name="macosx"></a>Does Boost.Python work with Mac OS X?</h2> + + It is known to work under 10.2.8 and 10.3 using + Apple's gcc 3.3 compiler: + <pre>gcc (GCC) 3.3 20030304 (Apple Computer, Inc. build 1493)</pre> + Under 10.2.8 get the August 2003 gcc update (free at + <a href="http://connect.apple.com/">http://connect.apple.com/</a>). + Under 10.3 get the Xcode Tools v1.0 (also free). + <p> + Python 2.3 is required. The Python that ships with 10.3 is + fine. Under 10.2.8 use these commands to install Python + as a framework: + <pre>./configure --enable-framework +make +make frameworkinstall</pre> + The last command requires root privileges because the target + directory is + <tt>/Library/Frameworks/Python.framework/Versions/2.3</tt>. + However, the installation does not interfere with the Python + version that ships with 10.2.8. + <p> + It is also crucial to increase the <tt>stacksize</tt> before + starting compilations, e.g.: + <pre>limit stacksize 8192k</pre> + If the <tt>stacksize</tt> is too small the build might crash with + internal compiler errors. + <p> + Sometimes Apple's compiler exhibits a bug by printing an error + like the following while compiling a + <tt>boost::python::class_<your_type></tt> + template instantiation: + <pre>.../inheritance.hpp:44: error: cannot + dynamic_cast `p' (of type `struct cctbx::boost_python::<unnamed>::add_pair* + ') to type `void*' (source type is not polymorphic)</pre> + + We do not know a general workaround, but if the definition of + <tt>your_type</tt> can be modified the following was found + to work in all cases encountered so far:<pre>struct your_type +{ + // before defining any member data +#if defined(__MACH__) && defined(__APPLE_CC__) && __APPLE_CC__ == 1493 + bool dummy_; +#endif + // now your member data, e.g. + double x; + int j; + // etc. +};</pre> + + <hr> + <h2><a name="xref">How can I find the existing PyObject that holds a C++ + object?</a></h2> + + <blockquote> + "I am wrapping a function that always returns a pointer to an + already-held C++ object." + </blockquote> + One way to do that is to hijack the mechanisms used for wrapping a class + with virtual functions. If you make a wrapper class with an initial + PyObject* constructor argument and store that PyObject* as "self", you + can get back to it by casting down to that wrapper type in a thin wrapper + function. For example: +<pre> +class X { X(int); virtual ~X(); ... }; +X* f(); // known to return Xs that are managed by Python objects + + +// wrapping code + +struct X_wrap : X +{ + X_wrap(PyObject* self, int v) : self(self), X(v) {} + PyObject* self; +}; + +handle<> f_wrap() +{ + X_wrap* xw = dynamic_cast<X_wrap*>(f()); + assert(xw != 0); + return handle<>(borrowed(xw->self)); +} + +... + +def("f", f_wrap()); +class_<X,X_wrap,boost::noncopyable>("X", init<int>()) + ... + ; +</pre> + Of course, if X has no virtual functions you'll have to use + <code>static_cast</code> instead of <code>dynamic_cast</code> with no + runtime check that it's valid. This approach also only works if the + <code>X</code> object was constructed from Python, because + <code>X</code>s constructed from C++ are of course never + <code>X_wrap</code> objects. + + <p>Another approach to this requires you to change your C++ code a bit; + if that's an option for you it might be a better way to go. work we've + been meaning to get to anyway. When a <code>shared_ptr<X></code> is + converted from Python, the shared_ptr actually manages a reference to the + containing Python object. When a shared_ptr<X> is converted back to + Python, the library checks to see if it's one of those "Python object + managers" and if so just returns the original Python object. So you could + just write <code>object(p)</code> to get the Python object back. To + exploit this you'd have to be able to change the C++ code you're wrapping + so that it deals with shared_ptr instead of raw pointers.</p> + + <p>There are other approaches too. The functions that receive the Python + object that you eventually want to return could be wrapped with a thin + wrapper that records the correspondence between the object address and + its containing Python object, and you could have your f_wrap function + look in that mapping to get the Python object out.</p> + + <hr> + + <h2><a name="ownership">How can I wrap a function which needs to take + ownership of a raw pointer?</a></h2> + + <blockquote> + <i>Part of an API that I'm wrapping goes something like this:</i> +<pre> +struct A {}; struct B { void add( A* ); } +where B::add() takes ownership of the pointer passed to it. +</pre> + + <p><i>However:</i></p> +<pre> +a = mod.A() +b = mod.B() +b.add( a ) +del a +del b +# python interpreter crashes +# later due to memory corruption. +</pre> + + <p><i>Even binding the lifetime of a</i> to b via + with_custodian_and_ward doesn't prevent the python object a from + ultimately trying to delete the object it's pointing to. Is there a way + to accomplish a 'transfer-of-ownership' of a wrapped C++ object?</p> + + <p><i>--Bruce Lowery</i></p> + </blockquote> + Yes: Make sure the C++ object is held by auto_ptr: +<pre> +class_<A, std::auto_ptr<A> >("A") + ... + ; +</pre> + Then make a thin wrapper function which takes an auto_ptr parameter: +<pre> +void b_insert(B& b, std::auto_ptr<A> a) +{ + b.insert(a.get()); + a.release(); +} +</pre> + Wrap that as B.add. Note that pointers returned via <code><a href= + "manage_new_object.html#manage_new_object-spec">manage_new_object</a></code> + will also be held by <code>auto_ptr</code>, so this transfer-of-ownership + will also work correctly. + + <hr> + <h2><a name="slow_compilation">Compilation takes too much time and eats too + much memory! What can I do to make it faster?</a></h2> + <p> + Please refer to the <a href="../tutorial/doc/html/python/techniques.html#python.reducing_compiling_time" + >Reducing Compiling Time</a> section in the tutorial. + </p> + + <hr> + <h2><a name="packages">How do I create sub-packages using Boost.Python?</a></h2> + <p> + Please refer to the <a href="../tutorial/doc/html/python/techniques.html#python.creating_packages" + >Creating Packages</a> section in the tutorial. + </p> + + <hr> + <h2><a name="msvcthrowbug"></a>error C2064: term does + not evaluate to a function taking 2 arguments</h2> + <font size="-1"><i>Niall Douglas provides these notes:</i></font><p> + If you see Microsoft Visual C++ 7.1 (MS Visual Studio .NET 2003) issue + an error message like the following it is most likely due to a bug + in the compiler: + <pre>boost\boost\python\detail\invoke.hpp(76): +error C2064: term does not evaluate to a function taking 2 arguments"</pre> + This message is triggered by code like the following: +<pre>#include <boost/python.hpp> + +using namespace boost::python; + +class FXThread +{ +public: + bool setAutoDelete(bool doso) throw(); +}; + +void Export_FXThread() +{ + class_< FXThread >("FXThread") + .def("setAutoDelete", &FXThread::setAutoDelete) + ; +} + </pre> + The bug is related to the <code>throw()</code> modifier. + As a workaround cast off the modifier. E.g.: +<pre> + .def("setAutoDelete", (bool (FXThread::*)(bool)) &FXThread::setAutoDelete)</pre> + <p>(The bug has been reported to Microsoft.)</p> + + <hr> + <h2><a name="custom_string"></a>How can I automatically + convert my custom string type to and from a Python string?</h2> + <font size="-1"><i>Ralf W. Grosse-Kunstleve provides these + notes:</i></font><p> + Below is a small, self-contained demo extension module that shows + how to do this. Here is the corresponding trivial test: + <pre>import custom_string +assert custom_string.hello() == "Hello world." +assert custom_string.size("california") == 10</pre> + + If you look at the code you will find: + + <ul> + <li>A custom <tt>to_python</tt> converter (easy): + <tt>custom_string_to_python_str</tt> + + <li>A custom lvalue converter (needs more code): + <tt>custom_string_from_python_str</tt> + </ul> + + The custom converters are registered in the global Boost.Python + registry near the top of the module initialization function. Once + flow control has passed through the registration code the automatic + conversions from and to Python strings will work in any module + imported in the same process. + +<pre>#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/to_python_converter.hpp> + +namespace sandbox { namespace { + + class custom_string + { + public: + custom_string() {} + custom_string(std::string const& value) : value_(value) {} + std::string const& value() const { return value_; } + private: + std::string value_; + }; + + struct custom_string_to_python_str + { + static PyObject* convert(custom_string const& s) + { + return boost::python::incref(boost::python::object(s.value()).ptr()); + } + }; + + struct custom_string_from_python_str + { + custom_string_from_python_str() + { + boost::python::converter::registry::push_back( + &convertible, + &construct, + boost::python::type_id<custom_string>()); + } + + static void* convertible(PyObject* obj_ptr) + { + if (!PyString_Check(obj_ptr)) return 0; + return obj_ptr; + } + + static void construct( + PyObject* obj_ptr, + boost::python::converter::rvalue_from_python_stage1_data* data) + { + const char* value = PyString_AsString(obj_ptr); + if (value == 0) boost::python::throw_error_already_set(); + void* storage = ( + (boost::python::converter::rvalue_from_python_storage<custom_string>*) + data)->storage.bytes; + new (storage) custom_string(value); + data->convertible = storage; + } + }; + + custom_string hello() { return custom_string("Hello world."); } + + std::size_t size(custom_string const& s) { return s.value().size(); } + + void init_module() + { + using namespace boost::python; + + boost::python::to_python_converter< + custom_string, + custom_string_to_python_str>(); + + custom_string_from_python_str(); + + def("hello", hello); + def("size", size); + } + +}} // namespace sandbox::<anonymous> + +BOOST_PYTHON_MODULE(custom_string) +{ + sandbox::init_module(); +}</pre> + + <hr> + <h2><a name="topythonconversionfailed"></a + >Why is my automatic to-python conversion not being found?</h2> + <font size="-1"><i>Niall Douglas provides these notes:</i></font><p> + If you define custom converters similar to the ones + shown above the <tt>def_readonly()</tt> and <tt>def_readwrite()</tt> + member functions provided by <tt>boost::python::class_</tt> for + direct access to your member data will not work as expected. + This is because <tt>def_readonly("bar", &foo::bar)</tt> is + equivalent to: + +<pre>.add_property("bar", make_getter(&foo::bar, return_internal_reference()))</pre> + + Similarly, <tt>def_readwrite("bar", &foo::bar)</tt> is + equivalent to: + +<pre>.add_property("bar", make_getter(&foo::bar, return_internal_reference()), + make_setter(&foo::bar, return_internal_reference())</pre> + + In order to define return value policies compatible with the + custom conversions replace <tt>def_readonly()</tt> and + <tt>def_readwrite()</tt> by <tt>add_property()</tt>. E.g.: + +<pre>.add_property("bar", make_getter(&foo::bar, return_value_policy<return_by_value>()), + make_setter(&foo::bar, return_value_policy<return_by_value>()))</pre> + + <hr> + <h2><a name="threadsupport"></a + >Is Boost.Python thread-aware/compatible with multiple interpreters?</h2> + <font size="-1"><i>Niall Douglas provides these notes:</i></font><p> + The quick answer to this is: no.</p> + <p> + The longer answer is that it can be patched to be so, but it's + complex. You will need to add custom lock/unlock wrapping of every + time your code enters Boost.Python (particularly every virtual + function override) plus heavily modify + <tt>boost/python/detail/invoke.hpp</tt> with custom unlock/lock + wrapping of every time Boost.Python enters your code. You must + furthermore take care to <i>not</i> unlock/lock when Boost.Python + is invoking iterator changes via <tt>invoke.hpp</tt>.</p> + <p> + There is a patched <tt>invoke.hpp</tt> posted on the C++-SIG + mailing list archives and you can find a real implementation of all + the machinery necessary to fully implement this in the TnFOX + project at <a href="http://sourceforge.net/projects/tnfox/"> this + SourceForge project location</a>.</p> + + <hr> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 12 March, 2006 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002-2006.</i></p> + </body> +</html> diff --git a/libs/python/doc/v2/feb2002.html b/libs/python/doc/v2/feb2002.html new file mode 100644 index 000000000..5f15aeace --- /dev/null +++ b/libs/python/doc/v2/feb2002.html @@ -0,0 +1,367 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta http-equiv="Content-Type" content= + "text/html; charset=iso-8859-1"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - February 2002 Progress Report</title> +<style type="text/css"> + :link { color: #0000ff } + :visited { color: #800080 } + p.c3 {font-style: italic} + h2.c2 {text-align: center} + h1.c1 {text-align: center} +</style> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">February 2002 Progress Report</h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="index"> + <dt><a href="#Python10">Python10 Conference Report</a> + + <dt><a href="#progress">Boost.Python v2 Progress</a> + + <dd> + <dl class="index"> + <dt><a href="#documentation">Documentation</a> + + <dt><a href="#conversion">Overhaul of + <code>to_python</code>/<code>from_python</code> + conversion mechanism</a> + + <dt><a href="#miscellaneous">Miscellaneous</a> + </dl> + </dl> + + <h2><a name="Python10">Python10 Conference Report</a></h2> + I spent the first week of February at the Python10 conference + in Alexandria, VA. I'm including this experience report + for two reasons: firstly, it documents where my time was + used. Secondly, a public presence for Boost.Python and + interaction between the Python and C++ communities is + important to the future of Boost.Python, which in turn is + important to the Kull Project. + + <p>Andy Koenig, of all people, was the keynote speaker of + this year's opening plenary session. He presented his + "impressions of a polyglot outsider", which + studiously avoided any mention of C++ until the end of his + talk, when he was asked about standardization. I was + surprised to learn that the C++ community at large wanted a + few more years before beginning but when ANSI accepted + HP's request for a standard, the process was forced to + start: it was a matter of participating or having + standardization proceed without one's input. Andy managed + to highlight very effectively the balance of strengths in + Python, one of the most important being its support for + extension via libraries. In many ways that makes Python a + good analogue for C++ in the interpreted world + + <p>There were several kind mentions of the Boost.Python + library from people who found it indispensable. I was + particularly happy that Karl MacMillan, Michael Droettboom, + and Ichiro Fujinaga from Johns Hopkins is using it to do OCR + on a vast library of music notation, since in a previous life + I was an author of music notation software. These guys are + also drawing on Ullrich Koethe's VIGRA library for image + manipulation (Ullrich has been a major contributor to + Boost.Python). They also have a system for writing the + Boost.Python wrapper code in C++ comments, which allows them + to keep all of the code in one place. I've asked them to + send me some information on that. + + <p>The development of Swig has been gaining momentum again + (the basic description at + www.boost.org/libs/python/doc/comparisons.html still + applies). The talk given about it by David Beazly was very + well-attended, and they appear to have quite a few users. + Swig's strengths (coverage of many langauages) and + weaknesses (incomplete C++ language support) haven't + changed, although the C++ support seems to have improved + considerably - they now claim to have a complete model of the + C++ type system. It seems to be mostly geared at wrapping + what Walter Landry calls "C-Tran": C++ code which + traffics in built-in types with little use of abstraction. + I'm not knocking that, either: I'm sure a lot of that + code exists, so it's a valuable service. One feature Swig + has which I'd like to steal is the ability to unwrap a + single Python argument into multiple C++ arguments, for + example, by converting a Python string into a pointer and + length. When his talk was over, David approached me about a + possible joint workshop on language binding, which sounds + like a fun idea to me. + + <p>I spent some considerable time talking with Steven Knight, + the leader of the Scons build tool effort. We had a lot to + share with one another, and I gained a much better + appreciation for many of the Scons design decisions. Scons + seems to be concentrating on being the ultimate build system + substrate, and Steve seemed to think that we were on the + right track with our high-level design. We both hope that the + Boost.Build V2 high-level architecture can eventually be + ported to run on top of Scons. + + <p>They also have a highly-refined and successful development + procedure which I'd like to emulate for Boost.Build V2. + Among many other things they do, their source-control system + automatically ensures that when you check in a new test, it + is automatically run on the currently checked-in state of the + code, and is expected to fail -- a relatively obvious good + idea which I've never heard before. + + <p>Guido Van Rossum's "State of the Python + Union" address was full of questions for the community + about what should be done next, but the one idea Guido seemed + to stress was that core language stability and continuing + library development would be a good idea (sound familiar?) I + mentioned the Boost model as a counterpoint to the idea of + something like CPAN (the massive Perl library archives), and + it seemed to generate some significant interest. I've + offered to work with anyone from the Python community who + wants to set up something like Boost. + + <p>There was some discussion of "string + interpolation" (variable substitution in strings), and + Guido mentioned that he had some thoughts about the + strengths/weaknesses of Python's formatting interface. It + might be useful for those working on formatting for boost to + contact him and find out what he has to say. + + <p>Ka-Ping Yee demoed a Mailman discussion thread weaver. + This tool weaves the various messages in a discussion thread + into a single document so you can follow the entire + conversation. Since we're looking very seriously at + moving Boost to Mailman, this could be a really useful thing + for us to have. If we do this, we'll move the yahoogroups + discussions into the mailman archive so old discussions can + be easily accessed in the same fashion. + + <p>And, just because it's cool, though perhaps not + relevant: http://homepages.ulb.ac.be/~arigo/psyco/ is a + promising effort to accelerate the execution of Python code + to speeds approaching those of compiled languages. It + reminded me a lot of Todd Veldhuizen's research into + moving parts of C++ template compilation to runtime, only + coming from the opposite end of things. + + <h2><a name="progress">Boost.Python v2 Progress</a></h2> + Here's what actually got accomplished. + + <h3><a name="documentation">Documentation</a></h3> + + <p>My first priority upon returning from Python10 was to get + some documentation in place. After wasting an unfortunate + amount of time looking at automatic documentation tools which + don't quite work, I settled down to use Bill Kempf's + HTML templates designed to be a boost standard. While they + are working well, it is highly labor-intensive. + + <p>I decided to begin with the high-level reference material, + as opposed to tutorial, narrative, or nitty-gritty details of + the framework. It seemed more important to have a precise + description of the way the commonly-used components work than + to have examples in HTML (since we already have some test + modules), and since the low-level details are much + less-frequently needed by users it made sense for me to + simply respond to support requests for the time being. + + <p>After completing approximately 60% of the high-level docs + (currently checked in to libs/python/doc/v2), I found myself + ready to start documenting the mechanisms for creating + to-/from-python converters. This caused a dilemma: I had + realized during the previous week that a much simpler, + more-efficient, and easier-to-use implementation was + possible, but I hadn't planned on implementing it right + away, since what was already in place worked adequately. I + had also received my first query on the C++-sig about how to + write such a converter + + <p>Given the labor-intensive nature of documentation writing, + I decided it would be a bad idea to document the conversion + mechanism if I was just going to rewrite it. Often the best + impetus for simplifying a design is the realization that + understandably documenting its current state would be too + difficult, and this was no exception. + + <h3><a name="conversion">Overhaul of + <code>to_python</code>/<code>from_python</code> conversion + mechanism</a></h3> + + <p>There were two basic realizations involved here: + + <ol> + <li><code>to_python</code> conversion could be a one-step + process, once an appropriate conversion function is found. + This allows elimination of the separate indirect + convertibility check + + <li>There are basically two categories of from_python + conversions: those which lvalues stored within or held by + the Python object (essentially extractions), like what + happens when an instance of a C++ class exposed with class_ + is used as the target of a wrapped member function), and + those in which a new rvalue gets created, as when a Python + Float is converted to a C++ + <code>complex<double></code> or a Python tuple is + converted to a C++ <code>std::vector<></code>. From + the client side, there are two corresponding categories of + conversion: those which demand an lvalue conversion and + those which can accept an lvalue or an rvalue conversion. + </ol> + The latter realization allowed the following collapse, which + considerably simplified things: + + <blockquote> + <table border="1" summary="Conversion protocol"> + <tr> + <th>Target Type + + <th>Eligible Converters + + <tr> + <td><code>T</code> + + <td rowspan="5"><code>T</code> rvalue or lvalue + + <tr> + <td><code>T const</code> + + <tr> + <td><code>T volatile</code> + + <tr> + <td><code>T const volatile</code> + + <tr> + <td><code>T const&</code> + + <tr> + <td><code>T const*</code> + + <td rowspan="9"><code>T</code> lvalue + + <tr> + <td><code>T volatile*</code> + + <tr> + <td><code>T const volatile*</code> + + <tr> + <td><code>T&</code> + + <tr> + <td><code>T volatile&</code> + + <tr> + <td><code>T const volatile&</code> + + <tr> + <td><code>T* const&</code> + + <tr> + <td><code>T const* const&</code> + + <tr> + <td><code>T volatile*const&</code> + + <tr> + <td><code>T const volatile*const&</code> + </table> + </blockquote> + This job included the following additional enhancements: + + <ul> + <li>Elimination of virtual functions, which cause object + code bloat + + <li>Registration of a single converter function for all + lvalue conversions, two for all rvalue conversions + + <li>Killed lots of unneeded code + + <li>Increased opacity of registry interface + + <li>Eliminated all need for decorated runtime type + identifiers + + <li>Updated test modules to reflect new interface + + <li>Eliminated the need for users to worry about converter + lifetime issues Additional Builtin Conversion Enhancements + + <li>Support for complex<float>, + complex<double>, and complex<long double> + conversions + + <li>Support for bool conversions + + <li>NULL pointers representable by None in Python + + <li>Support for conversion of Python classic classes to + numeric types + </ul> + + <h3><a name="miscellaneous">Miscellaneous</a></h3> + These don't fit easily under a large heading: + + <ul> + <li>Support CallPolicies for class member functions + + <li>from_python_data.hpp: revamped type alignment + metaprogram so that it's fast enough for KCC + + <li>classfwd.hpp header forward-declares class_<T> + + <li>indirect_traits.hpp: + + <li>added is_pointer_to_reference + + <li>fixed bugs + + <li>Reduced recompilation dependencies + + <li>msvc_typeinfo works around broken MS/Intel typeid() + implementation + + <li>Many fixes and improvements to the type_traits library + in order to work around compiler bugs and suppress warnings + + <li>Eliminated the need for explicit acquisition of + converter registrations + + <li>Expanded constructor support to 6 arguments + + <li>Implemented generalized pointer lifetime support + + <li>Updated code generation for returning.hpp + + <li>Tracked down and fixed cycle GC bugs + + <li>Added comprehensive unit tests for destroy_reference, + pointer_type_id, select_from_python, complex<T>, + bool, and classic class instance conversions + </ul> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p class="c3">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. Distributed + under the Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> + diff --git a/libs/python/doc/v2/function_doc_signature.html b/libs/python/doc/v2/function_doc_signature.html new file mode 100644 index 000000000..e439a77ac --- /dev/null +++ b/libs/python/doc/v2/function_doc_signature.html @@ -0,0 +1,216 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright Nikolay Mladenov 2007. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> +<head> + <meta http-equiv="Content-Type" content= + "text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - + <boost/python/doobject/function_doc_signature.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="../../../../boost.png" border= + "0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href= + "../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/object/function_doc_signature.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="#function_doc_signature_generator-spec">Class + <code>function_doc_signature_generator</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#function_doc_signature_generator-spec-synopsis">Class + <code>function_doc_signature_generator</code> synopsis</a></dt> + + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction" id= + "introduction"></a>Introduction</h2> + + <p>Boost.Python supports docstrings with automatic + appending of Pythonic and C++ signatures. This feature is implemented + by <code>class function_doc_signature_generator</code> + The class uses all of the overloads, supplied arg names and default values, as well as + the user-defined docstrings, to generate documentation for a given function.</p> + + <h2><a name="classes" id="classes"></a>Classes</h2> + + <h3><a name="function_doc_signature_generator-spec" id= + "function_doc_signature_generator-spec"></a>Class + <code>function_doc_signature_generator</code></h3> + + <p> + The class has only one public function which returns a list of strings documenting the + overloads of a function. + </p> + + <h4><a name="function_doc_signature_generator-spec-synopsis" id= + "function_doc_signature_generator-spec-synopsis"></a>Class + <code>function_doc_signature_generator</code> synopsis</h4> + <pre> +namespace boost { namespace python { namespace objects { + + class function_doc_signature_generator + { + public: + static list function_doc_signatures(function const *f); + }; + +}}} +</pre> + + + <h2><a name="examples" id="examples"></a>Examples</h2> + + <h4>Docstrings generated with <code>function_doc_signature_generator</code></h4> + <pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/args.hpp> +#include <boost/python/tuple.hpp> +#include <boost/python/class.hpp> +#include <boost/python/overloads.hpp> +#include <boost/python/raw_function.hpp> + +using namespace boost::python; + +tuple f(int x = 1, double y = 4.25, char const* z = "wow") +{ + return make_tuple(x, y, z); +} + +BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3) + + +struct X +{ + tuple f(int x = 1, double y = 4.25, char const* z = "wow") + { + return make_tuple(x, y, z); + } +}; + +BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 0, 3) + +tuple raw_func(tuple args, dict kw) +{ + return make_tuple(args, kw); +} + +BOOST_PYTHON_MODULE(args_ext) +{ + def("f", f, (arg("x")=1, arg("y")=4.25, arg("z")="wow") + , "This is f's docstring" + ); + + def("raw", raw_function(raw_func)); + + def("f1", f, f_overloads("f1's docstring", args("x", "y", "z"))); + + + class_<X>("X", "This is X's docstring", init<>(args("self"))) + .def("f", &X::f + , "This is X.f's docstring" + , args("self","x", "y", "z")) + + ; + +} + +</pre> +Python code: + <pre> +>>> import args_ext +>>> help(args_ext) +Help on module args_ext: + +NAME + args_ext + +FILE + args_ext.pyd + +CLASSES + Boost.Python.instance(__builtin__.object) + X + + class X(Boost.Python.instance) + | This is X's docstring + | + | Method resolution order: + | X + | Boost.Python.instance + | __builtin__.object + | + | Methods defined here: + | + | __init__(...) + | __init__( (object)self) -> None : + | C++ signature: + | void __init__(struct _object *) + | + | f(...) + | f( (X)self, (int)x, (float)y, (str)z) -> tuple : This is X.f's docstring + | C++ signature: + | class boost::python::tuple f(struct X {lvalue},int,double,char const *) + | + | ................. + | +FUNCTIONS + f(...) + f([ (int)x=1 [, (float)y=4.25 [, (str)z='wow']]]) -> tuple : This is f's docstring + C++ signature: + class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='wow']]]) + + f1(...) + f1([ (int)x [, (float)y [, (str)z]]]) -> tuple : f1's docstring + C++ signature: + class boost::python::tuple f1([ int [,double [,char const *]]]) + + raw(...) + object raw(tuple args, dict kwds) : + C++ signature: + object raw(tuple args, dict kwds) + + +</pre> + + <p><i>© Copyright <a href="mailto:nickm at sitius dot com">Nikolay Mladenov</a> 2007.</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/handle.html b/libs/python/doc/v2/handle.html new file mode 100644 index 000000000..b20d94a1f --- /dev/null +++ b/libs/python/doc/v2/handle.html @@ -0,0 +1,336 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/handle.hpp></title> + + <style type="text/css"> + p.c4 {font-style: italic} + span.c3 {color: #ff0000} + h2.c2 {text-align: center} + h1.c1 {text-align: center} + </style> + </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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Header <boost/python/handle.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="#handle-spec">Class template + <code>handle</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#handle-spec-synopsis">Class <code>handle</code> + synopsis</a></dt> + + <dt><a href="#handle-spec-ctors">Class <code>handle</code> + constructors and destructor</a></dt> + + <dt><a href="#handle-spec-modifiers">Class <code>handle</code> + modifier functions</a></dt> + + <dt><a href="#handle-spec-observers">Class <code>handle</code> + observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#borrowed-spec"><code>borrowed</code></a></dt> + + <dt><a href="#allow_null-spec"><code>allow_null</code></a></dt> + </dl> + </dd> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/handle.hpp></code> provides + <code>class template handle</code>, a smart pointer for + managing reference-counted Python objects.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="handle-spec"></a>Class template <code>handle</code></h3> + + <p><code>handle</code> is a smart pointer to a Python object type; it + holds a pointer of type <code>T*</code>, where T is its template + parameter. <code>T</code> must be either a type derived from + <code>PyObject</code> or a <a href="definitions.html#POD">POD</a> type + whose initial <code>sizeof(PyObject)</code> bytes are layout-compatible + with <code>PyObject</code>. Use <code>handle<></code> at the + boundary between the Python/'C' API and high-level code; prefer <code><a + href="object.html#object-spec">object</a></code> for a generalized + interface to Python objects.</p> + + <p><a name="upcast"></a>In this document, the term "upcast" refers to an + operation which converts a pointer <code>Y*</code> to a base class + pointer <code>T*</code> via <code>static_cast<T*></code> if + <code>Y</code> is derived from <code>T</code>, or via C-style cast + <code>(T*)</code> if it is not. However, in the latter case the "upcast" + is ill-formed if the initial <code>sizeof(PyObject)</code> bytes of + <code>Y</code> are not layout-compatible with <code>PyObject</code>.</p> + + <h4><a name="handle-spec-synopsis"></a>Class template handle + synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> + class handle + { + typedef <i>unspecified-member-function-pointer</i> bool_type; + + public: // types + typedef T element_type; + + public: // member functions + ~handle(); + + template <class Y> + explicit handle(detail::borrowed<null_ok<Y> >* p); + + template <class Y> + explicit handle(null_ok<detail::borrowed<Y> >* p); + + template <class Y> + explicit handle(detail::borrowed<Y>* p); + + template <class Y> + explicit handle(null_ok<Y>* p); + + template <class Y> + explicit handle(Y* p); + + handle(); + + handle& operator=(handle const& r); + + template<typename Y> + handle& operator=(handle<Y> const & r); // never throws + + + template <typename Y> + handle(handle<Y> const& r); + + handle(handle const& r); + + T* operator-> () const; + T& operator* () const; + T* get() const; + void reset(); + T* release(); + + operator bool_type() const; // never throws + private: + T* m_p; + }; + + template <class T> struct null_ok; + namespace detail { template <class T> struct borrowed; } +}} +</pre> + + <h4><a name="handle-spec-ctors">Class <code>handle</code> constructors + and destructor</a></h4> +<pre> +virtual ~handle(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Py_XDECREF(</code><i>upcast</i><code><PyObject*>(m_p))</code></dt> + </dl> +<pre> +template <class Y> +explicit handle(detail::borrowed<null_ok<Y> >* p); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(p)); + m_p = </code><i>upcast</i><code><T*>(p);</code></dt> + </dl> +<pre> +template <class Y> +explicit handle(null_ok<detail::borrowed<Y> >* p); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(p)); + m_p = </code><i>upcast</i><code><T*>(p);</code></dt> + </dl> +<pre> +template <class Y> +explicit handle(detail::borrowed<Y>* p); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(p)); + m_p = </code><i>upcast</i><code><T*>(<a href= + "errors.html#expect_non_null-spec">expect_non_null</a>(p));</code></dt> + </dl> +<pre> +template <class Y> +explicit handle(null_ok<Y>* p); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>m_p = </code><i>upcast</i><code><T*>(p);</code></dt> + </dl> +<pre> +template <class Y> +explicit handle(Y* p); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>m_p = </code><i>upcast</i><code><T*>(<a href= + "errors.html#expect_non_null-spec">expect_non_null</a>(p));</code></dt> + </dl> +<pre> +handle(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> <code>m_p = 0;</code></dt> + </dl> +<pre> +template <typename Y> +handle(handle<Y> const& r); +handle(handle const& r); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>m_p = r.m_p; Py_XINCREF(</code><i>upcast</i><code><PyObject*>(m_p));</code></dt> + </dl> + + <h4><a name="handle-spec-modifiers">Class <code>handle</code> + modifiers</a></h4> +<pre> +handle& operator=(handle const& r); +template<typename Y> +handle& operator=(handle<Y> const & r); // never throws +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Py_XINCREF(</code><i>upcast</i><code><PyObject*>(r.m_p)); Py_XDECREF(</code><i> + upcast</i><code><PyObject*>(m_p)); m_p = r.m_p;</code></dt> + </dl> +<pre> +T* release(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> <code>T* x = m_p; m_p = 0;return + x;</code></dt> + </dl> +<pre> +void reset(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>*this = handle<T>();</code></dt> + </dl> + + <h4><a name="handle-spec-observers">Class <code>handle</code> + observers</a></h4> +<pre> +T* operator-> () const; +T* get() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>m_p;</code></dt> + </dl> +<pre> +T& operator* () const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>*m_p;</code></dt> + </dl> +<pre> +operator bool_type() const; // never throws +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> 0 if <code>m_p == 0</code>, a pointer + convertible to <code>true</code> otherwise.</dt> + </dl> + + <h2><a name="functions"></a>Functions</h2> + + <h3><a name="borrowed-spec"></a><code>borrowed</code></h3> +<pre> +template <class T> +detail::borrowed<T>* borrowed(T* p) +{ + return (detail::borrowed<T>*)p; +} +</pre> + + <h3><a name="allow_null-spec"></a><code>allow_null</code></h3> +<pre> +template <class T> +null_ok<T>* allow_null(T* p) +{ + return (null_ok<T>*)p; +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p class="c4">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 +.</p> + </body> +</html> + diff --git a/libs/python/doc/v2/has_back_reference.html b/libs/python/doc/v2/has_back_reference.html new file mode 100644 index 000000000..29b81506c --- /dev/null +++ b/libs/python/doc/v2/has_back_reference.html @@ -0,0 +1,225 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/has_back_reference.hpp></title> + + <style type="text/css"> + p.c3 {font-style: italic} + h2.c2 {text-align: center} + h1.c1 {text-align: center} + </style> + </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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Header + <boost/python/has_back_reference.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="#has_back_reference-spec">Class template + <code>has_back_reference</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#has_back_reference-spec-synopsis">Class template + <code>has_back_reference</code> synopsis</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + </dd> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/has_back_reference.hpp></code> defines the + predicate metafunction <code>has_back_reference<></code>, which can + be specialized by the user to indicate that a wrapped class instance + holds a <code>PyObject*</code> corresponding to a Python object.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="has_back_reference-spec"></a>Class template + <code>has_back_reference</code></h3> + + <p>A unary metafunction whose <code>value</code> is true iff its argument + is a <code>pointer_wrapper<></code>.</p> + + <h4><a name="has_back_reference-spec-synopsis"></a>Class template + <code>has_back_reference</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template<class WrappedClass> class has_back_reference + { + typedef mpl::false_ type; + }; +}} +</pre> + <p>A "<a href="../../../mpl/doc/refmanual/metafunction.html"> + metafunction</a>" that is inspected by Boost.Python to determine how + wrapped classes can be constructed.</p> + + <dl class="traits-semantics"> + <dt><code>type::value</code> is an integral constant convertible to bool + of unspecified type.</dt> + + <dt>Specializations may substitute a <code>true</code>-valued integral constant wrapper for + <code>type</code> iff for each invocation of + <code>class_<WrappedClass>::def(init<</code> + <i>type-sequence...</i><code>>())</code> and the implicitly wrapped + copy constructor (unless it is <a href="class.html#class_-spec"> + noncopyable</a>), there exists a corresponding constructor + <code>WrappedClass::WrappedClass(PyObject*, </code> + <i>type-sequence...</i><code>)</code>. If such a specialization exists, + the <code>WrappedClass</code> constructors will be called with a "back + reference" pointer to the corresponding Python object whenever they are + invoked from Python. The easiest way to provide this nested <code> +type +</code> + is to + derive the specialization from <code>mpl::true_</code>. + </dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/class.hpp> +#include <boost/python/module.hpp> +#include <boost/python/has_back_reference.hpp> +#include <boost/python/handle.hpp> +#include <boost/shared_ptr.hpp> + +using namespace boost::python; +using boost::shared_ptr; + +struct X +{ + X(PyObject* self) : m_self(self), m_x(0) {} + X(PyObject* self, int x) : m_self(self), m_x(x) {} + X(PyObject* self, X const& other) : m_self(self), m_x(other.m_x) {} + + handle<> self() { return handle<>(borrowed(m_self)); } + int get() { return m_x; } + void set(int x) { m_x = x; } + + PyObject* m_self; + int m_x; +}; + +// specialize has_back_reference for X +namespace boost { namespace python +{ + template <> + struct has_back_reference<X> + : mpl::true_ + {}; +}} + +struct Y +{ + Y() : m_x(0) {} + Y(int x) : m_x(x) {} + int get() { return m_x; } + void set(int x) { m_x = x; } + + int m_x; +}; + +shared_ptr<Y> +Y_self(shared_ptr<Y> self) { return self; } + +BOOST_PYTHON_MODULE(back_references) +{ + class_<X>("X") + .def(init<int>()) + .def("self", &X::self) + .def("get", &X::get) + .def("set", &X::set) + ; + + class_<Y, shared_ptr<Y> >("Y") + .def(init<int>()) + .def("get", &Y::get) + .def("set", &Y::set) + .def("self", Y_self) + ; +} +</pre> + The following Python session illustrates that <code>x.self()</code> + returns the same Python object on which it is invoked, while + <code>y.self()</code> must create a new Python object which refers to the + same Y instance. + + <h3>Python code</h3> +<pre> +>>> from back_references import * +>>> x = X(1) +>>> x2 = x.self() +>>> x2 is x +<b>1</b> +>>> (x.get(), x2.get()) +(1, 1) +>>> x.set(10) +>>> (x.get(), x2.get()) +(10, 10) +>>> +>>> +>>> y = Y(2) +>>> y2 = y.self() +>>> y2 is y +<b>0</b> +>>> (y.get(), y2.get()) +(2, 2) +>>> y.set(20) +>>> (y.get(), y2.get()) +(20, 20) +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 18 July, 2004 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p class="c3">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 +.</p> + </body> +</html> + diff --git a/libs/python/doc/v2/implicit.html b/libs/python/doc/v2/implicit.html new file mode 100644 index 000000000..e9d5cac58 --- /dev/null +++ b/libs/python/doc/v2/implicit.html @@ -0,0 +1,163 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/implicit.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/implicit.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#implicitly_convertible-spec">Function Template + <code>implicitly_convertible</code></a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + <code>implicitly_convertible</code> allows Boost.Python to implicitly + take advantage of a C++ implicit or explicit conversion when matching + Python objects to C++ argument types. + + <h2><a name="functions"></a>Functions</h2> + + <h3><a name="implicitly_convertible-spec"></a>Function template + <code>implicitly_convertible</code></h3> +<pre> +template <class Source, class Target> +void implicitly_convertible(); +</pre> + + <table border="1" summary="implicitly_convertible template parameters"> + <caption> + <b><code>implicitly_convertible</code> template parameters</b><br> + </caption> + + <tr> + <th>Parameter</th> + + <th>Description</th> + </tr> + + <tr> + <td><code>Source</code></td> + + <td>The source type of the implicit conversion</td> + </tr> + + <tr> + <td><code>Target</code></td> + + <td>The target type of the implicit conversion</td> + </tr> + </table> + + <dl class="function-semantics"> + <dt><b>Requires:</b> The declaration <code>Target t(s);</code>, where + <code>s</code> is of type <code>Source</code>, is valid.</dt> + + <dt><b>Effects:</b> registers an rvalue <code>from_python</code> + converter to <code>Target</code> which can succeed for any + <code>PyObject* p</code> iff there exists any registered converter + which can produce <code>Source</code> rvalues</dt> + + <dt><b>Rationale:</b> C++ users expect to be able to take advantage of + the same sort of interoperability in Python as they do in C++.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/class.hpp> +#include <boost/python/implicit.hpp> +#include <boost/python/module.hpp> + +using namespace boost::python; + +struct X +{ + X(int x) : v(x) {} + operator int() const { return v; } + int v; +}; + +int x_value(X const& x) +{ + return x.v; +} + +X make_x(int n) { return X(n); } + +BOOST_PYTHON_MODULE(implicit_ext) +{ + def("x_value", x_value); + def("make_x", make_x); + + class_<X>("X", + init<int>()) + ; + + implicitly_convertible<X,int>(); + implicitly_convertible<int,X>(); +} +</pre> + + <h3>Python code</h3> +<pre> +>>> from implicit_ext import * +>>> x_value(X(42)) +42 +>>> x_value(42) +42 +>>> x = make_x(X(42)) +>>> x_value(x) +42 +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/import.html b/libs/python/doc/v2/import.html new file mode 100644 index 000000000..15c1c68c5 --- /dev/null +++ b/libs/python/doc/v2/import.html @@ -0,0 +1,90 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/import.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/import.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#import-spec"><code>import</code></a></dt> + </dl> + </dd> + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Exposes a mechanism for importing python modules.</p> + + <h2><a name="functions"></a>Functions</h2> + + <h3><a name="import-spec"></a><code>import</code></h3> + <pre> +object import(str name); + </pre> + <dl class="function-semantics"> + <dt><b>Effects:</b> Imports the module named by <code>name</code>.</dt> + <dt><b>Returns:</b> An instance of <a href="object.html#object-spec">object</a> + which holds a reference to the imported module.</dt> + </dl> + + <h2><a name="examples"></a>Examples</h2> + + <para>The following example demonstrates the use of <function>import</function> + to access a function in python, and later call it from within C++.</para> + +<pre> +#include <iostream> +#include <string> + +using namespace boost::python; + +void print_python_version() +{ + // Load the sys module. + object sys = import("sys"); + + // Extract the python version. + std::string version = extract<std::string>(sys.attr("version")); + std::cout << version << std::endl; +} +</pre> + <p>Revised 01 November, 2005</p> + + <p><i>© Copyright Stefan Seefeld 2005.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/index.html b/libs/python/doc/v2/index.html new file mode 100644 index 000000000..92593d06e --- /dev/null +++ b/libs/python/doc/v2/index.html @@ -0,0 +1,20 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org"> + <meta http-equiv="refresh" content="0; URL=../index.html"> + + <title></title> + </head> + + <body> + Loading index page; if nothing happens, please go to <a href= + "../index.html">../index.html</a>. + </body> +</html> + diff --git a/libs/python/doc/v2/indexing.html b/libs/python/doc/v2/indexing.html new file mode 100644 index 000000000..72c999c41 --- /dev/null +++ b/libs/python/doc/v2/indexing.html @@ -0,0 +1,695 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Windows (vers 1st February 2003), see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + <title> + Indexing Support + </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="../../../../boost.png" border= + "0"></a> + </h3> + </td> + <td valign="top"> + <h1 align="center"> + <a href="../index.html">Boost.Python</a> + </h1> + + <h2> Headers <boost/python/indexing/indexing_suite.hpp><br> + <boost/python/indexing/vector_indexing_suite.hpp></h2> + </td> + </tr> + </table> + <hr> + <h2> + Contents + </h2> + <dl class="page-index"> + <dt> + <a href="#introduction">Introduction</a> + </dt> + <dt> + <a href="#interface">Interface</a> + </dt> + <dd> + <dl class="page-index"> + <dt> + <a href="#indexing_suite">indexing_suite</a> + </dt> + <dt> + <a href="#indexing_suite_subclasses">indexing_suite + sub-classes</a> + </dt> + <dd> + <dl class="page-index"> + <dt> + <a href="#vector_indexing_suite">vector_indexing_suite</a> + </dt> + </dl> + </dd> + </dl> + </dd> + </dl> + <dl> + <dt> + <a href="#indexing_suite_class">indexing_suite class</a> + </dt> + <dt> + <a href="#vector_indexing_suite_class">vector_indexing_suite + class<br> + </a><a href="#map_indexing_suite_class">map_indexing_suite class</a> </dt> + </dl> + <hr> + <h2> + <a name="introduction" id="introduction"></a>Introduction + </h2> + <p> + Indexing is a Boost Python facility for easy exportation of indexable + C++ containers to Python. Indexable containers are containers that + allow random access through the operator[] (e.g. std::vector). + </p> + <p> + While Boost Python has all the facilities needed to expose indexable + C++ containers such as the ubiquitous std::vector to Python, the + procedure is not as straightforward as we'd like it to be. Python + containers do not map easily to C++ containers. Emulating Python + containers in C++ (see Python Reference Manual, <a href= + "http://www.python.org/doc/current/ref/sequence-types.html">Emulating + container types</a>) using Boost Python is non trivial. There are a lot + of issues to consider before we can map a C++ container to Python. + These involve implementing wrapper functions for the methods + <strong>__len__</strong>, <strong>__getitem__</strong>, + <strong>__setitem__</strong>, <strong>__delitem__,</strong> + <strong>__iter__</strong> and <strong>__contains</strong>. + </p> + <p> + The goals: + </p> + <ul> + <li> + <div> + Make indexable C++ containers behave exactly as one would expect a + Python container to behave. + </div> + </li> + <li> + Provide default reference semantics for container element indexing + (<tt>__getitem__</tt>) such that <tt>c[i]</tt> can be mutable. + Require: + <div> + <pre> + val = c[i] + c[i].m() + val == c[i] + </pre> + </div>where <tt>m</tt> is a non-const (mutating) member function + (method). + </li> + <li> + Return safe references from <tt>__getitem__</tt> such that subsequent + adds and deletes to and from the container will not result in + dangling references (will not crash Python). + </li> + <li> + Support slice indexes. + </li> + <li> + Accept Python container arguments (e.g. lists, tuples) wherever + appropriate. + </li> + <li> + Allow for extensibility through re-definable policy classes. + </li> + <li> + Provide predefined support for the most common STL and STL like + indexable containers. + </li> + </ul> + <hr> + +<h2> <a name="interface"></a>The Boost.Python Indexing Interface</h2> +<h3> <a name="indexing_suite"></a>indexing_suite [ Header <boost/python/indexing/indexing_suite.hpp> + ]</h3> + <p> + The <tt>indexing_suite</tt> class is the base class for the + management of C++ containers intended to be integrated to Python. The + objective is make a C++ container look and feel and behave exactly as + we'd expect a Python container. The class automatically wraps these + special Python methods (taken from the Python reference: <a href= + "http://www.python.org/doc/current/ref/sequence-types.html">Emulating + container types</a>): + </p> + <dl> + <dd> + <dl> + <dt> + <b><a name="l2h-126"><tt class= + "method">__len__</tt></a></b>(<var>self</var>) + </dt> + <dd> + Called to implement the built-in function <tt class= + "function">len()</tt><a name="l2h-134"> </a> Should return + the length of the object, an integer <code>>=</code> 0. Also, + an object that doesn't define a <tt class= + "method">__nonzero__()</tt> method and whose <tt class= + "method">__len__()</tt> method returns zero is considered to be + false in a Boolean context. <a name="l2h-128"> </a> + </dd> + </dl> + <dl> + <dt> + <b><a name="l2h-129"><tt class= + "method">__getitem__</tt></a></b>(<var>self, key</var>) + </dt> + <dd> + Called to implement evaluation of + <code><var>self</var>[<var>key</var>]</code>. For sequence types, + the accepted keys should be integers and slice + objects.<a name="l2h-135"> </a> Note that the special + interpretation of negative indexes (if the class wishes to + emulate a sequence type) is up to the <tt class= + "method">__getitem__()</tt> method. If <var>key</var> is of + an inappropriate type, <tt class="exception">TypeError</tt> + may be raised; if of a value outside the set of indexes for + the sequence (after any special interpretation of negative + values), <tt class="exception">IndexError</tt> should be + raised. <span class="note"><b class="label">Note:</b> + <tt class="keyword">for</tt> loops expect that an <tt class= + "exception">IndexError</tt> will be raised for illegal + indexes to allow proper detection of the end of the + sequence.</span> + </dd> + </dl> + <dl> + <dt> + <b><a name="l2h-130"><tt class= + "method">__setitem__</tt></a></b>(<var>self, key, value</var>) + </dt> + <dd> + Called to implement assignment to + <code><var>self</var>[<var>key</var>]</code>. Same note as for + <tt class="method">__getitem__()</tt>. This should only be + implemented for mappings if the objects support changes to the + values for keys, or if new keys can be added, or for sequences if + elements can be replaced. The same exceptions should be raised + for improper <var>key</var> values as for the <tt class= + "method">__getitem__()</tt> method. + </dd> + </dl> + <dl> + <dt> + <b><a name="l2h-131"><tt class= + "method">__delitem__</tt></a></b>(<var>self, key</var>) + </dt> + <dd> + Called to implement deletion of + <code><var>self</var>[<var>key</var>]</code>. Same note as for + <tt class="method">__getitem__()</tt>. This should only be + implemented for mappings if the objects support removal of keys, + or for sequences if elements can be removed from the sequence. + The same exceptions should be raised for improper <var>key</var> + values as for the <tt class="method">__getitem__()</tt> method. + </dd> + </dl> + <dl> + <dt> + <b><a name="l2h-132"><tt class= + "method">__iter__</tt></a></b>(<var>self</var>) + </dt> + <dd> + This method is called when an iterator is required for a + container. This method should return a new iterator object that + can iterate over all the objects in the container. For mappings, + it should iterate over the keys of the container, and should also + be made available as the method <tt class= + "method">iterkeys()</tt>. + <p> + Iterator objects also need to implement this method; they are + required to return themselves. For more information on iterator + objects, see ``<a class="ulink" href= + "http://www.python.org/doc/current/lib/typeiter.html">Iterator + Types</a>'' in the <em class="citetitle"><a href= + "http://www.python.org/doc/current/lib/lib.html" title= + "Python Library Reference">Python Library Reference</a></em>. + </p> + </dd> + </dl> + <dl> + <dt> + <b><a name="l2h-133"><tt class= + "method">__contains__</tt></a></b>(<var>self, item</var>) + </dt> + <dd> + Called to implement membership test operators. Should return true + if <var>item</var> is in <var>self</var>, false otherwise. For + mapping objects, this should consider the keys of the mapping + rather than the values or the key-item pairs. + </dd> + </dl> + </dd> + </dl> + +<h3> <a name="indexing_suite_subclasses"></a>indexing_suite sub-classes</h3> + <p> + The <tt>indexing_suite</tt> is not meant to be used as is. A couple of + policy functions must be supplied by subclasses of + <tt>indexing_suite</tt>. However, a set of <tt>indexing_suite</tt> + subclasses for the standard indexable STL containers will be provided, + In most cases, we can simply use the available predefined suites. In + some cases, we can refine the predefined suites to suit our needs. + </p> + +<h3> <a name="vector_indexing_suite"></a>vector_indexing_suite [ Header <boost/python/indexing/vector_indexing_suite.hpp> + ] </h3> +<p> + The <tt>vector_indexing_suite</tt> class is a predefined + <tt>indexing_suite</tt> derived class designed to wrap + <tt>std::vector</tt> (and <tt>std::vector</tt> like [i.e. a class with + std::vector interface]) classes. It provides all the policies required by the + <tt>indexing_suite</tt>. + </p> + <p> + Example usage: + </p> + <pre> + class X {...}; + ... + + class_<std::vector<X> >("XVec") + .def(vector_indexing_suite<std::vector<X> >()) + ; +</pre> + <p> + <tt>XVec</tt> is now a full-fledged Python container (see the + <a href="../../test/vector_indexing_suite.cpp">example in full</a>, + along with its <a href="../../test/vector_indexing_suite.py">python + test</a>). +</p> + <h3><a name="map_indexing_suite" id="map_indexing_suite"></a>map_indexing_suite [ Header <boost/python/indexing/map_indexing_suite.hpp> ] </h3> + <p> The <tt>map_indexing_suite</tt> class is a predefined <tt>indexing_suite</tt> derived class designed to wrap <tt>std::map</tt> (and <tt>std::map</tt> like [i.e. a class with std::map interface]) classes. It provides all the policies required by the <tt>indexing_suite</tt>. </p> + <p> Example usage: </p> + <pre> + class X {...}; + ... + + class_<std::map<X> >("XMap") + .def(map_indexing_suite<std::map<X> >()) + ; +</pre> + <p> By default indexed elements are returned by proxy. This can be disabled by supplying <tt>true</tt> in the NoProxy template parameter. <tt>XMap</tt> is now a full-fledged Python container (see the <a href="../../test/map_indexing_suite.cpp">example in full</a>, along with its <a href="../../test/map_indexing_suite.py">python test</a>).</p> + <hr> + <h2> + <a name="indexing_suite_class"></a>indexing_suite class </h2> + <h2> <tt>indexing_suite<<br> + </tt><tt>class Container<br> + , class DerivedPolicies<font color="#007F00"><br> + </font></tt> <tt>, + bool NoProxy<br> + , + bool NoSlice<br> + </tt><tt>, class Data<br> + , class Index<br> + </tt><tt>, class Key</tt></h2> + <table width="100%" border="1"> + <tr> + <td> + <strong>Template Parameter</strong><br> + </td> + <td> + <strong>Requirements</strong> + </td> + <td> + <strong>Semantics</strong> + </td> + <td> + <strong>Default</strong> + </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>Container</tt></font> + </td> + <td> + A class type + </td> + <td> + The container type to be wrapped to Python. + </td> + <td> + + </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>DerivedPolicies</tt></font> + </td> + <td> + A subclass of indexing_suite + </td> + <td> + Derived classes provide the policy hooks. See <a href= + "#DerivedPolicies">DerivedPolicies</a> below. + </td> + <td> + + </td> + </tr> + <tr> + <td> <font color="#007F00"><tt>NoProxy</tt></font> </td> + <td> A boolean </td> + <td> By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying <strong>true</strong> in the <tt>NoProxy</tt> template parameter. </td> + <td> false </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>NoSlice</tt></font> + </td> + <td> + A boolean + </td> + <td> + Do not allow slicing. </td> + <td> + false + </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>Data</tt></font> + </td> + <td> + + </td> + <td> + The container's data type. + </td> + <td> + <tt>Container::value_type</tt> + </td> + </tr> + <tr> + <td> <font color="#007F00"><tt>Index</tt></font> </td> + <td> </td> + <td> The container's index type. </td> + <td> <tt>Container::size_type</tt> </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>Key</tt></font> + </td> + <td> + + </td> + <td> + The container's key type. + </td> + <td> + <tt>Container::value_type</tt> + </td> + </tr> + </table> + <pre> + template <<br> class Container + , class DerivedPolicies + , bool NoProxy = false<br> , bool NoSlice = false + , class Data = typename Container::value_type + , class Index = typename Container::size_type + , class Key = typename Container::value_type + ><br> class indexing_suite + : unspecified + { + public: + + indexing_suite(); // default constructor + } + </pre> + <h2> + <tt><a name="DerivedPolicies"></a>DerivedPolicies</tt> + </h2> + <dl> + <dd> + Derived classes provide the hooks needed by + the <tt>indexing_suite:</tt> + </dd> + </dl> + <pre> data_type& + get_item(Container& container, index_type i); + + static object + get_slice(Container& container, index_type from, index_type to); + + static void + set_item(Container& container, index_type i, data_type const& v); + + static void + set_slice( + Container& container, index_type from, + index_type to, data_type const& v + ); + + template <class Iter> + static void<br> set_slice(Container& container, index_type from, + index_type to, Iter first, Iter last + ); + + static void + delete_item(Container& container, index_type i); + + static void + delete_slice(Container& container, index_type from, index_type to); + + static size_t + size(Container& container); + + template <class T> + static bool + contains(Container& container, T const& val); + + static index_type + convert_index(Container& container, PyObject* i); + + static index_type + adjust_index(index_type current, index_type from, + index_type to, size_type len + ); +</pre> + <blockquote> + <p> + Most of these policies are self explanatory. <tt>However, + <strong>convert_index</strong></tt> and + <tt><strong>adjust_index</strong></tt> deserve some explanation. + </p> + <p> + <strong><tt>convert_index</tt></strong> converts a Python index into + a C++ index that the container can handle. For instance, negative + indexes in Python, by convention, start counting from the right(e.g. + <tt>C[-1]</tt> indexes the rightmost element in <tt>C</tt>). + <strong><tt>convert_index</tt></strong> should handle the necessary + conversion for the C++ container (e.g. convert <tt>-1</tt> to + <tt>C.size()-1</tt>). <tt><strong>convert_index</strong></tt> should + also be able to convert the type of the index (A dynamic Python type) + to the actual type that the C++ container expects. + </p> + <p> + When a container expands or contracts, held indexes to its elements + must be adjusted to follow the movement of data. For instance, if we + erase 3 elements, starting from index 0 from a 5 element vector, what + used to be at index 4 will now be at index 1: + </p> + <pre> + [a][b][c][d][e] ---> [d][e] + ^ ^ + 4 1 +</pre> + <p> + <strong><tt>adjust_index</tt></strong> takes care of the adjustment. + Given a current index, the function should return the adjusted index + when data in the container at index <tt>from</tt>..<tt>to</tt> is + replaced by <tt>len</tt> elements. + </p> + </blockquote> + <div> + <hr> + <h2> + <a name="vector_indexing_suite_class"></a>vector_indexing_suite class + </h2> + <h3> + Class template <tt><br> + vector_indexing_suite<<br> + class <font color="#007F00">Container</font><br> + , bool <font color="#007F00">NoProxy</font><br> + , class <font color="#007F00">DerivedPolicies</font>></tt> + </h3> + <table width="100%" border="1"> + <tr> + <td> + <strong>Template Parameter</strong><br> + </td> + <td> + <strong>Requirements</strong> + </td> + <td> + <strong>Semantics</strong> + </td> + <td> + <strong>Default</strong> + </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>Container</tt></font> + </td> + <td> + A class type + </td> + <td> + The container type to be wrapped to Python. + </td> + <td> + + </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>NoProxy</tt></font> + </td> + <td> + A boolean + </td> + <td> + By default indexed elements have Python reference semantics and + are returned by proxy. This can be disabled by supplying + <strong>true</strong> in the <tt>NoProxy</tt> template parameter. + </td> + <td> + false + </td> + </tr> + <tr> + <td> + <font color="#007F00"><tt>DerivedPolicies</tt></font> + </td> + <td> + A subclass of indexing_suite + </td> + <td> + The <tt>vector_indexing_suite</tt> may still be derived to + further tweak any of the predefined policies. Static polymorphism + through CRTP (James Coplien. "Curiously Recurring Template + Pattern". C++ Report, Feb. 1995) enables the base + <tt>indexing_suite</tt> class to call policy function of the most + derived class + </td> + <td> + + </td> + </tr> + </table> + <pre> + template <<br> class Container,<br> bool NoProxy = false,<br> class DerivedPolicies = unspecified_default<br> class vector_indexing_suite : unspecified_base<br> {<br> public:<br><br> typedef typename Container::value_type data_type;<br> typedef typename Container::value_type key_type;<br> typedef typename Container::size_type index_type;<br> typedef typename Container::size_type size_type;<br> typedef typename Container::difference_type difference_type;<br> <br> data_type&<br> get_item(Container& container, index_type i); + + static object + get_slice(Container& container, index_type from, index_type to); + + static void<br> set_item(Container& container, index_type i, data_type const& v); + + static void + set_slice(Container& container, index_type from, + index_type to, data_type const& v); + + template <class Iter><br> static void<br> set_slice(Container& container, index_type from,<br> index_type to, Iter first, Iter last); + + static void + delete_item(Container& container, index_type i); + + static void + delete_slice(Container& container, index_type from, index_type to);<br> + static size_t + size(Container& container); + + static bool + contains(Container& container, key_type const& key); + + static index_type + convert_index(Container& container, PyObject* i); + + static index_type + adjust_index(index_type current, index_type from, + index_type to, size_type len); + }; + +</pre> + <h2><a name="vector_indexing_suite_class"></a>map_indexing_suite class </h2> + <h3> Class template <tt><br> + map_indexing_suite<<br> + class <font color="#007F00">Container</font><br> + , bool <font color="#007F00">NoProxy</font><br> + , class <font color="#007F00">DerivedPolicies</font>></tt> </h3> + <table width="100%" border="1"> + <tr> + <td> <strong>Template Parameter</strong><br> + </td> + <td> <strong>Requirements</strong> </td> + <td> <strong>Semantics</strong> </td> + <td> <strong>Default</strong> </td> + </tr> + <tr> + <td> <font color="#007F00"><tt>Container</tt></font> </td> + <td> A class type </td> + <td> The container type to be wrapped to Python. </td> + <td> </td> + </tr> + <tr> + <td> <font color="#007F00"><tt>NoProxy</tt></font> </td> + <td> A boolean </td> + <td> By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying <strong>true</strong> in the <tt>NoProxy</tt> template parameter. </td> + <td> false </td> + </tr> + <tr> + <td> <font color="#007F00"><tt>DerivedPolicies</tt></font> </td> + <td> A subclass of indexing_suite </td> + <td> The <tt>vector_indexing_suite</tt> may still be derived to further tweak any of the predefined policies. Static polymorphism through CRTP (James Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995) enables the base <tt>indexing_suite</tt> class to call policy function of the most derived class </td> + <td> </td> + </tr> + </table> + <pre> + template <<br> class Container,<br> bool NoProxy = false,<br> class DerivedPolicies = unspecified_default<br> class map_indexing_suite : unspecified_base<br> {<br> public:<br><br> typedef typename Container::value_type value_type;<br> typedef typename Container::value_type::second_type data_type;<br> typedef typename Container::key_type key_type;<br> typedef typename Container::key_type index_type;<br> typedef typename Container::size_type size_type;<br> typedef typename Container::difference_type difference_type;<br><br> static data_type&<br> get_item(Container& container, index_type i); + + static void<br> set_item(Container& container, index_type i, data_type const& v); + + static void + delete_item(Container& container, index_type i);<br> + static size_t + size(Container& container); + + static bool + contains(Container& container, key_type const& key); + + static bool<br> compare_index(Container& container, index_type a, index_type b); +<br> static index_type + convert_index(Container& container, PyObject* i); + }; + +</pre> + <hr> + © Copyright Joel de Guzman 2003. Permission to copy, use, modify, + sell and distribute this document is granted provided this copyright + notice appears in all copies. This document is provided "as is" without + express or implied warranty, and with no claim as to its suitability + for any purpose. + </div> + </body> +</html> diff --git a/libs/python/doc/v2/init.html b/libs/python/doc/v2/init.html new file mode 100644 index 000000000..2aacaad9f --- /dev/null +++ b/libs/python/doc/v2/init.html @@ -0,0 +1,251 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/init.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Headers <boost/python/init.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href= + "#init-expressions"><em>init-expressions</em></a></dt> + + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <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> + + </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> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/init.hpp></code> defines the interface for + exposing C++ constructors to Python as extension class + <code>__init__</code> functions.</p> + + <h2><a name="init-expressions"><em>init-expressions</em></a></h2> + An <em>init-expression</em> is used to describe a family of + <code>__init__</code> methods to be generated for an extension class, and + the result has the following properties: + + <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 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>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> + + <h2><a name="classes"></a>Classes</h2> + + <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/refmanual/forward-sequence.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>call + policies</em> are replaced by a reference to + <code>policies</code>.</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/refmanual/forward-sequence.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> + + <h2><a name="examples"></a>Example(s)</h2> + + <p>Given the C++ declarations:</p> +<pre> +class Y; +class X +{ + public: + X(int x, Y* y) : m_y(y) {} + X(double); + private: + Y* m_y; +}; +</pre> + A corresponding Boost.Python extension class can be created with: +<pre> +using namespace boost::python; + +class_<X>("X", "This is X's docstring.", + init<int,char const*>(args("x","y"), "X.__init__'s docstring")[ + with_custodian_and_ward<1,3>()] + ) + .def(init<double>()) + ; +</pre> + <hr> + Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/instance_holder.html b/libs/python/doc/v2/instance_holder.html new file mode 100644 index 000000000..87571d1da --- /dev/null +++ b/libs/python/doc/v2/instance_holder.html @@ -0,0 +1,219 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content="HTML Tidy, 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/instance_holder.hpp></title> + </head> + +<style type="text/css"> + p.c4 {font-style: italic} + span.c3 {color: #ff0000} + h2.c2 {text-align: center} + h1.c1 {text-align: center} +</style> + + <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="../../../../boost.png" border= + "0"></a></h3> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Header <boost/python/instance_holder.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + + <dt><a href="#classes">Classes</a> + + <dd> + <dl class="page-index"> + <dt><a href="#instance_holder-spec">Class + <code>instance_holder</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#instance_holder-spec-synopsis">Class + <code>instance_holder</code> synopsis</a> + + <dt><a href="#instance_holder-spec-ctors">Class + <code>instance_holder</code> destructor</a> + + <dt><a href="#instance_holder-spec-modifiers">Class + <code>instance_holder</code> modifier functions</a> + + <dt><a href="#instance_holder-spec-observers">Class + <code>instance_holder</code> observer functions</a> + </dl> + </dl> + + <dt><a href="#examples">Example</a> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/instance_holder.hpp></code> provides + <code>class instance_holder</code>, the base class for types + which hold C++ instances of wrapped classes. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="instance_holder-spec"></a>Class <code>instance_holder</code></h3> + + <p><code>instance_holder</code> is an abstract base class whose + concrete derived classes hold C++ class instances within their + Python object wrappers. To allow multiple inheritance in Python + from C++ class wrappers, each such Python object contains a chain + of <code>instance_holder</code>s. When an <code>__init__</code> + function for a wrapped C++ class is invoked, a new + <code>instance_holder</code> instance is created and installed in + the Python object using its <code><a + href="#instance_holder-spec-modifiers">install</a></code>() + function. Each concrete class derived from + <code>instance_holder</code> must provide a <code><a + href="#instance_holder-spec-observers">holds</a>()</code> + implementation which allows Boost.Python to query it for the + type(s) it is holding. In order to support the held type's wrapped + constructor(s), the class must also provide constructors that can + accept an initial <code>PyObject*</code> argument referring to the + owning Python object, and which forward the rest of their + arguments to the constructor of the held type. The initial + argument is needed to enable virtual function overriding in + Python, and may be ignored, depending on the specific + <code>instance_holder</code> subclass. + + <h4><a name="instance_holder-spec-synopsis"></a>Class instance_holder + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class instance_holder : <a href="../../../utility/utility.htm#Class_noncopyable">noncopyable</a> + { + public: + // destructor + virtual ~instance_holder(); + + // instance_holder modifiers + void install(PyObject* inst) throw(); + + // instance_holder observers + virtual void* holds(type_info) = 0; + }; +}} +</pre> + + <h4><a name="instance_holder-spec-ctors">Class <code>instance_holder</code> + destructor</a></h4> +<pre> +virtual ~instance_holder(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> destroys the object + </dl> + + <h4><a name="instance_holder-spec-modifiers">Class + <code>instance_holder</code> modifiers</a></h4> +<pre> +void install(PyObject* inst) throw(); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>inst</code> is a Python instance of a + wrapped C++ class type, or is a type derived from a wrapped C++ + class type. + <dt><b>Effects:</b> installs the new instance at the head of the + Python object's chain of held instances. + <dt><b>Throws:</b> nothing + </dl> + + <h4><a name="instance_holder-spec-observers">Class <code>instance_holder</code> + observers</a></h4> +<pre> +virtual void* holds(type_info x) = 0; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> A pointer to an object of the type described + by <code>x</code> if <code>*this</code> contains such an object, + 0 otherwise. + </dl> + + <h2><a name="examples"></a>Example</h2> + +The following is a simplified version of the instance holder template +used by Boost.Python to wrap classes held by smart pointers: +<pre> +template <class SmartPtr, class Value> +struct pointer_holder : instance_holder +{ + // construct from the SmartPtr type + pointer_holder(SmartPtr p) + :m_p(p) + + // Forwarding constructors for the held type + pointer_holder(PyObject*) + :m_p(new Value()) + { + } + + template<class A0> + pointer_holder(PyObject*,A0 a0) + :m_p(new Value(a0)) + { + } + + template<class A0,class A1> + pointer_holder(PyObject*,A0 a0,A1 a1) + :m_p(new Value(a0,a1)) + { + } + ... + + private: // required holder implementation + void* holds(type_info dst_t) + { + // holds an instance of the SmartPtr type... + if (dst_t == python::type_id<SmartPtr>()) + return &this->m_p; + + // ...and an instance of the SmartPtr's element_type, if the + // pointer is non-null + return python::type_id<Value>() == dst_t ? &*this->m_p : 0; + } + + private: // data members + SmartPtr m_p; +}; +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p class="c4">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. + + </body> +</html> diff --git a/libs/python/doc/v2/iterator.html b/libs/python/doc/v2/iterator.html new file mode 100644 index 000000000..3557ffb9a --- /dev/null +++ b/libs/python/doc/v2/iterator.html @@ -0,0 +1,398 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/iterator.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/iterator.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="#iterator-spec">Class template + <code>iterator</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#iterator-spec-synopsis">Class + <code>iterator</code> synopsis</a></dt> + + <dt><a href="#iterator-spec-constructors">Class template + <code>iterator</code> constructor</a></dt> + </dl> + </dd> + </dl> + + <dl class="page-index"> + <dt><a href="#iterators-spec">Class template + <code>iterators</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#iterators-spec-synopsis">Class + <code>iterators</code> synopsis</a></dt> + + <dt><a href="#iterators-spec-types">Class template + <code>iterators</code> nested types</a></dt> + + <dt><a href="#iterators-spec-statics">Class template + <code>iterators</code> static functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#range-spec">range</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/iterator.hpp></code> provides types and + functions for creating <a href= + "http://www.python.org/doc/current/lib/typeiter.html">Python + iterators</a> from <a href= + "http://www.sgi.com/tech/stl/Container.html">C++ Containers</a> and <a + href="http://www.sgi.com/tech/stl/Iterators.html">Iterators</a>. Note + that if your <code>class_</code> supports random-access iterators, + implementing <code><a href= + "http://www.python.org/doc/current/ref/sequence-types.html#l2h-128">__getitem__</a></code> + (also known as the Sequence Protocol) may serve you better than using + this facility: Python will automatically create an iterator type for you + (see <a href= + "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-35">iter()</a>), + and each access can be range-checked, leaving no possiblity of accessing + through an invalidated C++ iterator.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3> + + <p>Instances of <code>iterator<C,P></code> hold a reference to a + callable Python object which, when invoked from Python, expects a single + argument <code>c</code> convertible to <code>C</code> and creates a + Python iterator that traverses [<code>c.begin()</code>, + <code>c.end()</code>). The optional <a href= + "CallPolicies.html">CallPolicies</a> <code>P</code> can be used to + control how elements are returned during iteration.</p> + + <p>In the table below, <code><b>c</b></code> is an instance of + <code>Container</code>.</p> + + <table border="1" summary="iterator template parameters"> + <tr> + <th>Template Parameter</th> + + <th>Requirements</th> + + <th>Semantics</th> + + <th>Default</th> + </tr> + + <tr> + <td><code>Container</code></td> + + <td>[c.begin(),c.end()) is a valid <a href= + "http://www.sgi.com/tech/stl/Iterators.html">Iterator range</a>.</td> + + <td>The result will convert its argument to <code>c</code> and call + <code>c.begin()</code> and <code>c.end()</code> to acquire iterators. + To invoke <code>Container</code>'s <code>const</code> + <code>begin()</code> and <code>end()</code> functions, make it + <code>const</code>.</td> + </tr> + + <tr> + <td><code>NextPolicies</code></td> + + <td>A default-constructible model of <a href= + "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</td> + + <td>Applied to the resulting iterators' <code>next()</code> + method.</td> + + <td>An unspecified model of <a href= + "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which + always makes a copy of the result of deferencing the underlying C++ + iterator</td> + </tr> + </table> + + <h4><a name="iterator-spec-synopsis"></a>Class Template iterator + synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class Container + , class NextPolicies = <i>unspecified</i>> + struct iterator : <a href="object.html#object-spec">object</a> + { + iterator(); + }; +}} +</pre> + + <h4><a name="iterator-spec-constructors"></a>Class Template iterator + constructor</h4> +<pre> +iterator() +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b></dt> + + <dd> + Initializes its base class with the result of: +<pre> +range<NextPolicies>(&iterators<Container>::begin, &iterators<Container>::end) +</pre> + </dd> + + <dt><b>Postconditions:</b> <code>this->get()</code> points to a + Python callable object which creates a Python iterator as described + above.</dt> + + <dt><b>Rationale:</b> Provides an easy way to create iterators for the + common case where a C++ class being wrapped provides + <code>begin()</code> and <code>end()</code>.</dt> + </dl> + <!-- --> + + <h3><a name="iterators-spec"></a>Class Template + <code>iterators</code></h3> + + <p>A utility class template which provides a way to reliably call its + argument's <code>begin()</code> and <code>end()</code> member functions. + Note that there is no portable way to take the address of a member + function of a C++ standard library container, so + <code>iterators<></code> can be particularly helpful when wrapping + them.</p> + + <p>In the table below, <code><b>x</b></code> is an instance of + <code>C</code>.</p> + + <table border="1" summary="iterator template parameters"> + <tr> + <th>Required Valid Expression</th> + + <th>Type</th> + </tr> + + <tr> + <td><code>x.begin()</code></td> + + <td>Convertible to <code>C::const_iterator</code> if <code>C</code> + is a <code>const</code> type; convertible to <code>C::iterator</code> + otherwise.</td> + </tr> + + <tr> + <td><code>x.end()</code></td> + + <td>Convertible to <code>C::const_iterator</code> if <code>C</code> + is a <code>const</code> type; convertible to <code>C::iterator</code> + otherwise.</td> + </tr> + </table> + + <h4><a name="iterators-spec-synopsis"></a>Class Template iterators + synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class C> + struct iterators + { + typedef typename C::[const_]iterator iterator; + static iterator begin(C& x); + static iterator end(C& x); + }; +}} + +</pre> + + <h4><a name="iterators-spec-types"></a>Class Template iterators nested + types</h4> + If C is a <code>const</code> type, +<pre> +typedef typename C::const_iterator iterator; +</pre> + Otherwise: +<pre> +typedef typename C::iterator iterator; +</pre> + + <h4><a name="iterators-spec-statics"></a>Class Template iterators static + functions</h4> +<pre> +static iterator begin(C&); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>x.begin()</code></dt> + </dl> +<pre> +static iterator end(C&); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>x.end()</code></dt> + </dl> + <!-- --> + + <h2><a name="functions"></a>Functions</h2> +<pre> +<a name= +"range-spec">template</a> <class NextPolicies, class Target, class Accessor1, class Accessor2> +<a href= +"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); + +template <class NextPolicies, class Accessor1, class Accessor2> +<a href= +"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); + +template <class Accessor1, class Accessor2> +<a href= +"object.html#object-spec">object</a> range(Accessor1 start, Accessor2 finish); +</pre> + + <dl class="range-semantics"> + <dt><b>Requires:</b> <code>NextPolicies</code> is a + default-constructible model of <a href= + "CallPolicies.html#CallPolicies-concept">CallPolicies</a>.</dt> + + <dt><b>Effects:</b></dt> + + <dd> + <dl> + <dt>The first form creates a Python callable object which, when + invoked, converts its argument to a <code>Target</code> object + <code>x</code>, and creates a Python iterator which traverses + [<code><a href= + "../../../bind/bind.html">bind</a>(start,_1)(x)</code>, <code><a + href="../../../bind/bind.html">bind</a>(finish,_1)(x)</code>), + applying <code>NextPolicies</code> to the iterator's + <code>next()</code> function.</dt> + + <dt>The second form is identical to the first, except that + <code>Target</code> is deduced from <code>Accessor1</code> as + follows:</dt> + + <dd> + <ol> + <li>If <code>Accessor1</code> is a function type, + <code>Target</code> is the type of its first argument.</li> + + <li>If <code>Accessor1</code> is a data member pointer of the + form <code>R (T::*)</code>, <code>Target</code> is + identical to <code>T</code>.</li> + + <li>If <code>Accessor1</code> is a member function pointer of + the form + <code>R (T::*)(</code><i>arguments...</i><code>)</code> + <i>cv-opt</i>, where <i>cv-opt</i> is an optional + <code>cv-qualifier</code>, <code>Target</code> is identical to + <code>T</code>.</li> + </ol> + </dd> + + <dt>The third form is identical to the second, except that + <code>NextPolicies</code> is an unspecified model of <a href= + "CallPolicies.html#CallPolicies-concept">CallPolicies</a> which + always makes a copy of the result of deferencing the underlying C++ + iterator</dt> + </dl> + </dd> + + <dt><b>Rationale:</b> The use of <code><a href= + "../../../bind/bind.html">boost::bind</a>()</code> allows C++ iterators + to be accessed through functions, member functions or data member + pointers. Customization of <code>NextPolicies</code> (e.g. using + <code><a href= + "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code>) + is useful when it is expensive to copy sequence elements of a wrapped + class type. Customization of <code>Target</code> is useful when + <code>Accessor1</code> is a function object, or when a base class of + the intended target type would otherwise be deduced.</dt> + </dl> + + <h2><a name="examples"></a>Examples</h2> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> + +#include <vector> + +using namespace boost::python; +BOOST_PYTHON_MODULE(demo) +{ + class_<std::vector<double> >("dvec") + .def("__iter__", iterator<std::vector<double> >()) + ; +} +</pre> + A more comprehensive example can be found in: + + <dl> + <dt><code><a href= + "../../test/iterator.cpp">libs/python/test/iterator.cpp</a></code></dt> + + <dt><code><a href= + "../../test/input_iterator.cpp">libs/python/test/input_iterator.cpp</a></code></dt> + + <dt><code><a href= + "../../test/iterator.py">libs/python/test/input_iterator.py</a></code></dt> + + </dl> +<hr> + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/list.html b/libs/python/doc/v2/list.html new file mode 100644 index 000000000..e347ae461 --- /dev/null +++ b/libs/python/doc/v2/list.html @@ -0,0 +1,142 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/list.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/list.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="#list-spec">Class <code>list</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#list-spec-synopsis">Class <code>list</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>Exposes a <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python + <a href= + "http://www.python.org/doc/current/lib/typesseq-mutable.html">list</a> + type.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="list-spec"></a>Class <code>list</code></h3> + + <p>Exposes the <a href= + "http://www.python.org/doc/current/lib/typesseq-mutable.html">mapping + protocol</a> of Python's built-in <code>list</code> type. The semantics + of the constructors and member functions defined below can be fully + understood by reading the <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept + definition. Since <code>list</code> is publicly derived from <code><a + href="object.html#object-spec">object</a></code>, the public object + interface applies to <code>list</code> instances as well.</p> + + <h4><a name="list-spec-synopsis"></a>Class <code>list</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class list : public object + { + public: + list(); // new list + + template <class T> + explicit list(T const& sequence); + + template <class T> + void append(T const& x); + + template <class T> + long count(T const& value) const; + + template <class T> + void extend(T const& x); + + template <class T> + long index(T const& x) const; + + template <class T> + void insert(object const& index, T const& x); // insert object before index + + object pop(); // remove and return item at index (default last) + object pop(long index); + object pop(object const& index); + + template <class T> + void remove(T const& value); + + void reverse(); // reverse *IN PLACE* + + void sort(); // sort *IN PLACE*; if given, cmpfunc(x, y) -> -1, 0, 1 + + template <class T> + void sort(T const& value); + }; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> +<pre> +using namespace boost::python; + +// Return the number of zeroes in the list +long zeroes(list l) +{ + return l.count(0); +} +</pre> + + <p>Revised 1 October, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/long.html b/libs/python/doc/v2/long.html new file mode 100644 index 000000000..08ceb3bd5 --- /dev/null +++ b/libs/python/doc/v2/long.html @@ -0,0 +1,119 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/long.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/long.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="#long_-spec">Class <code>long_</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#long_-spec-synopsis">Class <code>long_</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>Exposes a <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python + <a href= + "http://www.python.org/doc/current/lib/typesnumeric.html">long</a> + integer type.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="long_-spec"></a>Class <code>long_</code></h3> + + <p>Exposes the <a href= + "http://www.python.org/doc/current/lib/typesnumeric.html">numeric type + protocol</a> of Python's built-in <code>long</code> type. The semantics + of the constructors and member functions defined below can be fully + understood by reading the <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept + definition. Since <code>long_</code> is publicly derived from <code><a + href="object.html#object-spec">object</a></code>, the public object + interface applies to <code>long_</code> instances as well.</p> + + <h4><a name="long_-spec-synopsis"></a>Class <code>long_</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class long_ : public object + { + public: + long_(); // new long_ + + template <class T> + explicit long_(T const& rhs); + + template <class T, class U> + long_(T const& rhs, U const& base); + }; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> +<pre> +namespace python = boost::python; + +// compute a factorial without overflowing +python::long_ fact(long n) +{ + if (n == 0) + return python::long_(1); + else + return n * fact(n - 1); +} +</pre> + + <p>Revised 1 October, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/lvalue_from_pytype.html b/libs/python/doc/v2/lvalue_from_pytype.html new file mode 100644 index 000000000..d27c57d0c --- /dev/null +++ b/libs/python/doc/v2/lvalue_from_pytype.html @@ -0,0 +1,301 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/lvalue_from_python.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/lvalue_from_pytype.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="#lvalue_from_pytype-spec">Class Template + <code>lvalue_from_pytype</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#lvalue_from_pytype-spec-synopsis">Class Template + <code>lvalue_from_pytype</code> synopsis</a></dt> + + <dt><a href="#lvalue_from_pytype-spec-ctors">Class Template + <code>lvalue_from_pytype</code> constructor</a></dt> + </dl> + </dd> + </dl> + + <dl class="page-index"> + <dt><a href="#extract_identity-spec">Class Template + <code>extract_identity</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#extract_identity-spec-synopsis">Class Template + <code>extract_identity</code> synopsis</a></dt> + + <dt><a href="#extract_identity-spec-statics">Class Template + <code>extract_identity</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#extract_member-spec">Class Template + <code>extract_member</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#extract_member-spec-synopsis">Class Template + <code>extract_member</code> synopsis</a></dt> + + <dt><a href="#extract_member-spec-statics">Class Template + <code>extract_member</code> static functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + <code><boost/python/lvalue_from_pytype.hpp></code> supplies a + facility for extracting C++ objects from within Python instances of a + given type. This is typically useful for dealing with "traditional" + Python extension types. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="lvalue_from_pytype-spec"></a>Class template + <code>lvalue_from_pytype</code></h3> + + <p>Class template <code>lvalue_from_pytype</code> will register + from_python converters which, given an object of the given Python type, + can extract references and pointers to a particular C++ type. Its + template arguments are:</p> + + <table border="1" summary="lvalue_from_pytype template parameters"> + <caption> + <b><code>lvalue_from_pytype</code> Requirements</b><br> + In the table below, <b><code>x</code></b> denotes an object of type + <code>PythonObject&</code> + </caption> + + <tr> + <th>Parameter</th> + + <th>Requirements</th> + + <th>Semantics</th> + </tr> + + <tr> + <td><code>Extractor</code></td> + + <td>a model of <a href= + "Extractor.html#Extractor-concept">Extractor</a> whose execute + function returns a reference type.</td> + + <td>Extracts the lvalue from the Python object once its type has been + confirmed</td> + </tr> + + <tr> + <td><code>python_type</code></td> + + <td>A compile-time constant <code><a href= + "http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>*</code></td> + + <td>The Python type of instances convertible by this converter. + Python subtypes are also convertible.</td> + </tr> + </table> + + <h4><a name="lvalue_from_pytype-spec-synopsis"></a>Class template + <code>lvalue_from_pytype</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class Extractor, PyTypeObject const* python_type> + struct lvalue_from_pytype + { + lvalue_from_pytype(); + }; +}} +</pre> + + <h4><a name="lvalue_from_pytype-spec-ctors"></a>Class template + <code>lvalue_from_pytype</code> constructor</h4> +<pre> +lvalue_from_pytype(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Registers converters which can convert Python + objects of the given type to lvalues of the type returned by + <code>Extractor::execute</code>.</dt> + </dl> + + <h3><a name="extract_identity-spec"></a>Class template + <code>extract_identity</code></h3> + + <p><code>extract_identity</code> is a model of <a href= + "Extractor.html#Extractor-concept">Extractor</a> which can be used in the + common case where the C++ type to be extracted is the same as the Python + object type.</p> + + <h4><a name="extract_identity-spec-synopsis"></a>Class template + <code>extract_identity</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class InstanceType> + struct extract_identity + { + static InstanceType& execute(InstanceType& c); + }; +}} +</pre> + + <h4><a name="extract_identity-spec-statics"></a>Class template + <code>extract_identity</code> static functions</h4> +<pre> +InstanceType& execute(InstanceType& c); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>c</code></dt> + </dl> + + <h3><a name="extract_member-spec"></a>Class template + <code>extract_member</code></h3> + + <p><code>extract_member</code> is a model of <a href= + "Extractor.html#Extractor-concept">Extractor</a> which can be used in the + common case in the common case where the C++ type to be extracted is a + member of the Python object.</p> + + <h4><a name="extract_member-spec-synopsis"></a>Class template + <code>extract_member</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class InstanceType, class MemberType, MemberType (InstanceType::*member)> + struct extract_member + { + static MemberType& execute(InstanceType& c); + }; +}} +</pre> + + <h4><a name="extract_member-spec-statics"></a>Class template + <code>extract_member</code> static functions</h4> +<pre> +static MemberType& execute(InstanceType& c); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>c.*member</code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + This example presumes that someone has implemented the standard <a href= + "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example + module</a> from the Python documentation, and we want to build a module + which manipulates <code>Noddy</code>s. Since + <code>noddy_NoddyObject</code> is so simple that it carries no + interesting information, the example is a bit contrived: it assumes you + want to keep track of one particular object for some reason. This module + would have to be dynamically linked to the module which defines + <code>noddy_NoddyType</code>. + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/handle.hpp> +#include <boost/python/borrowed.hpp> +#include <boost/python/lvalue_from_pytype.hpp> + +// definition lifted from the Python docs +typedef struct { + PyObject_HEAD +} noddy_NoddyObject; + +using namespace boost::python; +static handle<noddy_NoddyObject> cache; + +bool is_cached(noddy_NoddyObject* x) +{ + return x == cache.get(); +} + +void set_cache(noddy_NoddyObject* x) +{ + cache = handle<noddy_NoddyObject>(borrowed(x)); +} + +BOOST_PYTHON_MODULE(noddy_cache) +{ + def("is_cached", is_cached); + def("set_cache", set_cache); + + // register Noddy lvalue converter + lvalue_from_pytype<extract_identity<noddy_NoddyObject>,&noddy_NoddyType>(); +} +</pre> + + <h3>Python code</h3> +<pre> +>>> import noddy +>>> n = noddy.new_noddy() +>>> import noddy_cache +>>> noddy_cache.is_cached(n) +0 +>>> noddy_cache.set_cache(n) +>>> noddy_cache.is_cached(n) +1 +>>> noddy_cache.is_cached(noddy.new_noddy()) +0 +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 20 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/make_function.html b/libs/python/doc/v2/make_function.html new file mode 100644 index 000000000..d5a6cdb06 --- /dev/null +++ b/libs/python/doc/v2/make_function.html @@ -0,0 +1,207 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/make_function.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/make_function.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#make_function-spec">make_function</a></dt> + + <dt><a href="#make_constructor-spec">make_constructor</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><a href="#make_function-spec">make_function</a>()</code> and + <code><a href="#make_constructor-spec">make_constructor</a>()</code> are + the functions used internally by <code><a href= + "def.html#def-spec">def</a>()</code> and <code>class_<>::<a href= + "class.html#class_-spec-modifiers">def</a>()</code> to produce Python + callable objects which wrap C++ functions and member functions.</p> + + <h2><a name="functions"></a>Functions</h2> +<pre> +<a name="make_function-spec">template <class F></a> +<a href="object.html#object-spec">object</a> make_function(F f) + +template <class F, class Policies> +<a href= +"object.html#object-spec">object</a> make_function(F f, Policies const& policies) + +template <class F, class Policies, class KeywordsOrSignature> +<a href= +"object.html#object-spec">object</a> make_function(F f, Policies const& policies, KeywordsOrSignature const& ks) + +template <class F, class Policies, class Keywords, class Signature> +<a href= +"object.html#object-spec">object</a> make_function(F f, Policies const& policies, Keywords const& kw, Signature const& sig) +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>F</code> is a function pointer or member + function pointer type. If <code>policies</code> are supplied, it must + be a model of <a href="CallPolicies.html">CallPolicies</a>. If + <code>kewords</code> are supplied, it must be 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>f</code>.</dt> + + <dt><b>Effects:</b> Creates a Python callable object which, when called + from Python, converts its arguments to C++ and calls <code>f</code>. If + <code>F</code> is a pointer-to-member-function type, the target + object of the function call (<code>*this</code>) will be taken + from the first Python argument, and subsequent Python arguments + will be used as the arguments + to <code>f</code>. <ul> +<li> If <code>policies</code> are supplied, it + will be applied to the function as described <a href= + "CallPolicies.html">here</a>. +<li>If <code>keywords</code> are + supplied, the keywords will be applied in order to the final + arguments of the resulting function. +<li>If <code>Signature</code> + is supplied, it should be an instance of an <a + href="../../../mpl/doc/refmanual/front-extensible-sequence.html">MPL front-extensible + sequence</a> representing the function's return type followed by + its argument types. Pass a <code>Signature</code> when wrapping + function object types whose signatures can't be deduced, or when + you wish to override the types which will be passed to the + wrapped function. +</ul></dt> + + <dt><b>Returns:</b> An instance of <a href= + "object.html#object-spec">object</a> which holds the new Python + callable object.</dt> + + <dt><b>Caveats:</b> An argument of pointer type may + be <code>0</code> if <code>None</code> is passed from Python. + An argument type which is a constant reference may refer to a + temporary which was created from the Python object for just the + duration of the call to the wrapped function, for example + a <code>std::vector</code> conjured up by the conversion process + from a Python list. Use a non-<code>const</code> reference + argument when a persistent lvalue is required. + </dl> + +<pre> +<a name="make_constructor-spec">template <class F></a> +<a href="object.html#object-spec">object</a> make_constructor(F f) + +template <class F, class Policies> +<a href= +"object.html#object-spec">object</a> make_constructor(F f, Policies const& policies) + +template <class F, class Policies, class KeywordsOrSignature> +<a href= +"object.html#object-spec">object</a> make_constructor(F f, Policies const& policies, KeywordsOrSignature const& ks) + +template <class F, class Policies, class Keywords, class Signature> +<a href= +"object.html#object-spec">object</a> make_constructor(F f, Policies const& policies, Keywords const& kw, Signature const& sig) +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>F</code> is a + function pointer type. If <code>policies</code> are supplied, it must + be a model of <a href="CallPolicies.html">CallPolicies</a>. If + <code>kewords</code> are supplied, it must be 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>f</code>.</dt> + + <dt><b>Effects:</b> Creates a Python callable object which, when called + from Python, converts its arguments to C++ and calls <code>f</code>.</dt> + + <dt><b>Returns:</b> An instance of <a href= + "object.html#object-spec">object</a> which holds the new Python + callable object.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <p>C++ function exposed below returns a callable object wrapping one of + two functions.</p> +<pre> +#include <boost/python/make_function.hpp> +#include <boost/python/module.hpp> + +char const* foo() { return "foo"; } +char const* bar() { return "bar"; } + +using namespace boost::python; +object choose_function(bool selector) +{ + if (selector) + return boost::python::make_function(foo); + else + return boost::python::make_function(bar); +} + +BOOST_PYTHON_MODULE(make_function_test) +{ + def("choose_function", choose_function); +} +</pre> + It can be used this way in Python: +<pre> +>>> from make_function_test import * +>>> f = choose_function(1) +>>> g = choose_function(0) +>>> f() +'foo' +>>> g() +'bar' +</pre> + + <p> + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/manage_new_object.html b/libs/python/doc/v2/manage_new_object.html new file mode 100644 index 000000000..57efb4137 --- /dev/null +++ b/libs/python/doc/v2/manage_new_object.html @@ -0,0 +1,145 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/manage_new_object.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/manage_new_object.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#manage_new_object-spec">Class + <code>manage_new_object</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#manage_new_object-spec-synopsis">Class + <code>manage_new_object</code> synopsis</a></dt> + + <dt><a href="#manage_new_object-spec-metafunctions">Class + <code>manage_new_object</code> metafunctions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="manage_new_object-spec"></a>Class + <code>manage_new_object</code></h3> + + <p><code>manage_new_object</code> is a model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> + which can be used to wrap C++ functions which return a pointer to an + object allocated with a <i>new-expression</i>, and expect the caller to + take responsibility for deleting that object.</p> + + <h4><a name="manage_new_object-spec-synopsis"></a>Class + <code>manage_new_object</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct manage_new_object + { + template <class T> struct apply; + }; +}} +</pre> + + <h4><a name="manage_new_object-spec-metafunctions"></a>Class + <code>manage_new_object</code> metafunctions</h4> +<pre> +template <class T> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Requires:</b> <code>T</code> is <code>U*</code> for some + <code>U</code>.</dt> + + <dt><b>Returns:</b> <code>typedef <a href= + "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a><T> + type;</code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <p>In C++:</p> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/manage_new_object.hpp> +#include <boost/python/return_value_policy.hpp> + + +struct Foo { + Foo(int x) : x(x){} + int get_x() { return x; } + int x; +}; + +Foo* make_foo(int x) { return new Foo(x); } + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + def("make_foo", make_foo, return_value_policy<manage_new_object>()) + class_<Foo>("Foo") + .def("get_x", &Foo::get_x) + ; +} +</pre> + In Python: +<pre> +>>> from my_module import * +>>> f = make_foo(3) # create a Foo object +>>> f.get_x() +3 +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/module.html b/libs/python/doc/v2/module.html new file mode 100644 index 000000000..353523cb6 --- /dev/null +++ b/libs/python/doc/v2/module.html @@ -0,0 +1,110 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, 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/module.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/module.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + + <dt><a href="#macros">Macros</a> + + <dd> + <dl class="page-index"> + <dt><a href= + "#BOOST_PYTHON_MODULE-spec">BOOST_PYTHON_MODULE</a> + </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 a + Boost.Python extension module. + + <h2><a name="macros"></a>Macros</h2> + + <p><a name= + "BOOST_PYTHON_MODULE-spec"><code>BOOST_PYTHON_MODULE(name)</code></a> + is used to declare Python <a href= + "http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000"> + module initialization functions</a>. The <code>name</code> argument must + exactly match the name of the module to be initialized, and must conform to + Python's <a href= + "http://www.python.org/doc/2.2/ref/identifiers.html">identifier naming + rules</a>. Where you would normally write +<pre> +extern "C" void init<i>name</i>() +{ + ... +} +</pre> + Boost.Python modules should be initialized with +<pre> +BOOST_PYTHON_MODULE(<i>name</i>) +{ + ... +} +</pre> + +This macro generates two functions in the scope where it is used: +<code>extern "C" void init<i>name</i>()</code>, +and <code>void 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-spec">handle_exception</a>()</code> so +that any C++ exceptions generated are safely processeed. During the +body of <code>init_<i>name</i></code>, the current <code><a +href="scope.html#scope-spec">scope</a></code> refers to the module +being initialized. + + <h2><a name="examples"></a>Example(s)</h2> + + <p>C++ module definition: +<pre> +#include <boost/python/module.hpp> + +BOOST_PYTHON_MODULE(xxx) +{ + throw "something bad happened" +} +</pre> + +Interactive Python: +<pre> +>>> 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 --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> Distributed + under the Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> + diff --git a/libs/python/doc/v2/numeric.html b/libs/python/doc/v2/numeric.html new file mode 100644 index 000000000..eaa390af4 --- /dev/null +++ b/libs/python/doc/v2/numeric.html @@ -0,0 +1,276 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> + +<html> +<head> + <meta name="generator" content= + "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - <boost/python/numeric.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/numeric.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="#array-spec">Class <code>array</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#array-spec-synopsis">Class <code>array</code> + synopsis</a></dt> + + <dt><a href="#array-spec-observers">Class <code>array</code> + observer functions</a></dt> + + <dt><a href="#array-spec-statics">Class <code>array</code> static + functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + <hr> + + <h2><a name="introduction" id="introduction"></a>Introduction</h2> + + <p>Exposes a <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python + <a href= + "http://www.python.org/dev/doc/devel/lib/typesmapping.html">array</a> + type.</p> + + <h2><a name="classes" id="classes"></a>Classes</h2> + + <h3><a name="array-spec" id="array-spec"></a>Class <code>array</code></h3> + + <p>Provides access to the array types of <a href= + "http://www.pfdubois.com/numpy/">Numerical Python</a>'s <a href= + "http://www.pfdubois.com/numpy/#Numeric">Numeric</a> and <a href= + "http://stsdas.stsci.edu/numarray/index.html">NumArray</a> modules. With + the exception of the functions documented <a href= + "#array-spec-observers">below</a>, the semantics of the constructors and + member functions defined below can be fully understood by reading the + <a href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept + definition. Since <code>array</code> is publicly derived from + <code><a href="object.html#object-spec">object</a></code>, the public + object interface applies to <code>array</code> instances as well.</p> + + <p><a name="default_search" id="default_search"></a>The default behavior is + to use <code>numarray.NDArray</code> as the associated Python type if the + <code>numarray</code> module is installed in the default location. + Otherwise it falls back to use <code>Numeric.ArrayType</code>. If neither + extension module is installed, overloads of wrapped C++ functions with + <code>numeric::array</code> parameters will never be matched, and other + attempted uses of <code>numeric::array</code> will <a href= + "definitions.html#raise">raise</a> an appropriate Python exception. The + associated Python type can be set manually using the <code><a href= + "#array-spec-statics">set_module_and_type</a>(...)</code> static + function.</p> + + <h4><a name="array-spec-synopsis" id="array-spec-synopsis"></a>Class + <code>array</code> synopsis</h4> + <pre> +namespace boost { namespace python { namespace numeric +{ + class array : public object + { + public: + object astype(); + template <class Type> + object astype(Type const& type_); + + template <class Type> + array new_(Type const& type_) const; + + template <class Sequence> + void resize(Sequence const& x); + void resize(long x1); + void resize(long x1, long x2); + ... + void resize(long x1, long x2,...long x<i>n</i>); + + template <class Sequence> + void setshape(Sequence const& x); + void setshape(long x1); + void setshape(long x1, long x2); + ... + void setshape(long x1, long x2,...long x<i>n</i>); + + template <class Indices, class Values> + void put(Indices const& indices, Values const& values); + + template <class Sequence> + object take(Sequence const& sequence, long axis = 0); + + template <class File> + void tofile(File const& f) const; + + object factory(); + template <class Sequence> + object factory(Sequence const&); + template <class Sequence, class Typecode> + object factory(Sequence const&, Typecode const&, bool copy = true, bool savespace = false); + template <class Sequence, class Typecode, class Type> + object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&); + template <class Sequence, class Typecode, class Type, class Shape> + object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&, Shape const&); + + template <class T1> + explicit array(T1 const& x1); + template <class T1, class T2> + explicit array(T1 const& x1, T2 const& x2); + ... + template <class T1, class T2,...class T<i>n</i>> + explicit array(T1 const& x1, T2 const& x2,...T<i>n</i> const& xn); + + static void set_module_and_type(); + static void set_module_and_type(char const* package_path = 0, char const* type_name = 0); + static void get_module_name(); + + object argmax(long axis=-1); + + object argmin(long axis=-1); + + object argsort(long axis=-1); + + void byteswap(); + + object copy() const; + + object diagonal(long offset = 0, long axis1 = 0, long axis2 = 1) const; + + void info() const; + + bool is_c_array() const; + bool isbyteswapped() const; + void sort(); + object trace(long offset = 0, long axis1 = 0, long axis2 = 1) const; + object type() const; + char typecode() const; + + object getflat() const; + long getrank() const; + object getshape() const; + bool isaligned() const; + bool iscontiguous() const; + long itemsize() const; + long nelements() const; + object nonzero() const; + + void ravel(); + + object repeat(object const& repeats, long axis=0); + + void setflat(object const& flat); + + void swapaxes(long axis1, long axis2); + + str tostring() const; + + void transpose(object const& axes = object()); + + object view() const; + }; +}}} +</pre> + + <h4><a name="array-spec-observers" id="array-spec-observers"></a>Class + <code>array</code> observer functions</h4> + <pre> +object factory(); +template <class Sequence> +object factory(Sequence const&); +template <class Sequence, class Typecode> +object factory(Sequence const&, Typecode const&, bool copy = true, bool savespace = false); +template <class Sequence, class Typecode, class Type> +object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&); +template <class Sequence, class Typecode, class Type, class Shape> +object factory(Sequence const&, Typecode const&, bool copy, bool savespace, Type const&, Shape const&); +</pre>These functions map to the underlying array type's <code>array()</code> +function family. They are not called "<code>array</code>" because of the C++ +limitation that you can't define a member function with the same name as its +enclosing class. + <pre> +template <class Type> +array new_(Type const&) const; +</pre>This function maps to the underlying array type's <code>new()</code> +function. It is not called "<code>new</code>" because that is a keyword in +C++. + + <h4><a name="array-spec-statics" id="array-spec-statics"></a>Class + <code>array</code> static functions</h4> + <pre> +static void set_module_and_type(char const* package_path, char const* type_name); +static void set_module_and_type(); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>package_path</code> and + <code>type_name</code>, if supplied, is an <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> The first form sets the package path of the module + that supplies the type named by <code>type_name</code> to + <code>package_path</code>. The second form restores the <a href= + "#default_search">default search behavior</a>. The associated Python type + will be searched for only the first time it is needed, and thereafter the + first time it is needed after an invocation of + <code>set_module_and_type</code>.</dt> + </dl> + <pre> +static std::string get_module_name() +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Returns the name of the module containing the class + that will be held by new <code>numeric::array</code> instances.</dt> + </dl> + + <h2><a name="examples" id="examples"></a>Example</h2> + <pre> +#include <boost/python/numeric.hpp> +#include <boost/python/tuple.hpp> + +// sets the first element in a 2d numeric array +void set_first_element(numeric::array& y, double value) +{ + y[make_tuple(0,0)] = value; +} +</pre> + + <p>Revised 07 October, 2006</p> + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002-2006.</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/object.html b/libs/python/doc/v2/object.html new file mode 100644 index 000000000..8df8ef5f8 --- /dev/null +++ b/libs/python/doc/v2/object.html @@ -0,0 +1,1121 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/object.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/object.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href="#types">Types</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#slice_nil-spec">slice_nil</a></dt> + </dl> + </dd> + + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#const_attribute_policies-spec">Class + <code>const_attribute_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#const_attribute_policies-spec-synopsis">Class + <code>const_attribute_policies</code> synopsis</a></dt> + + <dt><a href="#const_attribute_policies-spec-statics">Class + <code>const_attribute_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#attribute_policies-spec">Class + <code>attribute_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#attribute_policies-spec-synopsis">Class + <code>attribute_policies</code> synopsis</a></dt> + + <dt><a href="#attribute_policies-spec-statics">Class + <code>attribute_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#const_objattribute_policies-spec">Class + <code>const_objattribute_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#const_objattribute_policies-spec-synopsis">Class + <code>const_objattribute_policies</code> synopsis</a></dt> + + <dt><a href="#const_objattribute_policies-spec-statics">Class + <code>const_objattribute_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#objattribute_policies-spec">Class + <code>objattribute_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#objattribute_policies-spec-synopsis">Class + <code>objattribute_policies</code> synopsis</a></dt> + + <dt><a href="#objattribute_policies-spec-statics">Class + <code>objattribute_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#const_item_policies-spec">Class + <code>const_item_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#const_item_policies-spec-synopsis">Class + <code>const_item_policies</code> synopsis</a></dt> + + <dt><a href="#const_item_policies-spec-statics">Class + <code>const_item_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#item_policies-spec">Class + <code>item_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#item_policies-spec-synopsis">Class + <code>item_policies</code> synopsis</a></dt> + + <dt><a href="#item_policies-spec-statics">Class + <code>item_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#const_slice_policies-spec">Class + <code>const_slice_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#const_slice_policies-spec-synopsis">Class + <code>const_slice_policies</code> synopsis</a></dt> + + <dt><a href="#const_slice_policies-spec-statics">Class + <code>const_slice_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#slice_policies-spec">Class + <code>slice_policies</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#slice_policies-spec-synopsis">Class + <code>slice_policies</code> synopsis</a></dt> + + <dt><a href="#slice_policies-spec-statics">Class + <code>slice_policies</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#object_operators-spec">Class + <code>object_operators</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#object_operators-spec-synopsis">Class + <code>object_operators</code> synopsis</a></dt> + + <dt><a href="#object_operators-spec-observers">Class + <code>object_operators</code> observer functions</a></dt> + </dl> + </dd> + + <dt><a href="#object-spec">Class <code>object</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#object-spec-synopsis">Class <code>object</code> + synopsis</a></dt> + + <dt><a href="#object-spec-ctors">Class <code>object</code> + constructors and destructor</a></dt> + + <dt><a href="#object-spec-modifiers">Class template + <code>object</code> modifier functions</a></dt> + + <dt><a href="#object-spec-observers">Class template + <code>object</code> observer functions</a></dt> + </dl> + </dd> + + <dt><a href="#proxy-spec">Class template + <code>proxy</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#proxy-spec-synopsis">Class template + <code>proxy</code> synopsis</a></dt> + + <dt><a href="#proxy-spec-modifiers">Class template + <code>proxy</code> modifier functions</a></dt> + + <dt><a href="#proxy-spec-observers">Class template + <code>proxy</code> observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#del-spec">del</a></dt> + + <dt><a href="#comparisons-spec">comparisons</a></dt> + + <dt><a href="#binary-spec">binary operations</a></dt> + + <dt><a href="#assignment-spec">assignment operations</a></dt> + + </dl> + + <dl class="page-index"> + <dt><a href="#object_operators-spec">operators</a></dt> + </dl> + + <dl class="page-index"> + <dt><a href="#len-spec">len()</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Exposes the generic Python object wrapper class <code>object</code>, + and related classes. In order to avoid some potenential problems with + argument-dependent lookup and the generalized operators defined on + <code>object</code>, all these facilities are defined in + <code>namespace boost::python::api</code>, and <code>object</code> + is imported into <code>namespace boost::python</code> with a + <i>using-declaration</i>.</p> + + <h2><a name="types"></a>Types</h2> + + <p><a name="slice_nil-spec"></a></p> +<pre> +class slice_nil; +static const _ = slice_nil(); +</pre> + A type that can be used to get the effect of leaving out an index in a + Python slice expression: +<pre> +>>> x[:-1] +>>> x[::-1] +</pre> + C++ equivalent: +<pre> +x.slice(_,-1) +x[slice(_,_,-1)] +</pre> + + <h2><a name="classes"></a>Classes</h2> + <!-- begin --> + + <h3><a name="const_attribute_policies-spec"></a>Class + <code>const_attribute_policies</code></h3> + + <p>The policies which are used for proxies representing an attribute + access to a <code>const object</code>.</p> + + <h4><a name="const_attribute_policies-spec-synopsis"></a>Class + <code>const_attribute_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct const_attribute_policies + { + typedef char const* key_type; + static object get(object const& target, char const* key); + }; +}}} +</pre> + + <h4><a name="const_attribute_policies-spec-statics"></a>Class + <code>const_attribute_policies</code> static functions</h4> +<pre> +static object get(object const& target, char const* key); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>key</code> is an <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> accesses the attribute of <code>target</code> named + by <code>key</code>.</dt> + + <dt><b>Returns:</b> An <code>object</code> managing the result of the + attribute access.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + + <h3><a name="attribute_policies-spec"></a>Class + <code>attribute_policies</code></h3> + + <p>The policies which are used for proxies representing an attribute + access to a mutable <code>object</code>.</p> + + <h4><a name="attribute_policies-spec-synopsis"></a>Class + <code>attribute_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct attribute_policies : const_attribute_policies + { + static object const& set(object const& target, char const* key, object const& value); + static void del(object const&target, char const* key); + }; +}}} +</pre> + + <h4><a name="attribute_policies-spec-statics"></a>Class + <code>attribute_policies</code> static functions</h4> +<pre> +static object const& set(object const& target, char const* key, object const& value); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>key</code> is an <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> sets the attribute of <code>target</code> named by + <code>key</code> to <code>value</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> +<pre> +static void del(object const&target, char const* key); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>key</code> is an <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> deletes the attribute of <code>target</code> named + by <code>key</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + <!-- end --> + <!-- begin --> + + <h3><a name="const_objattribute_policies-spec"></a>Class + <code>const_objattribute_policies</code></h3> + + <p>The policies which are used for proxies representing an attribute + access to a <code>const object</code> when the attribute name is + given as a <code>const object</code>.</p> + + <h4><a name="const_objattribute_policies-spec-synopsis"></a>Class + <code>const_objattribute_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct const_objattribute_policies + { + typedef object const& key_type; + static object get(object const& target, object const& key); + }; +}}} +</pre> + + <h4><a name="const_objattribute_policies-spec-statics"></a>Class + <code>const_objattribute_policies</code> static functions</h4> +<pre> +static object get(object const& target, object const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>key</code> is an <code>object</code> + holding a string.</dt> + + <dt><b>Effects:</b> accesses the attribute of <code>target</code> named + by <code>key</code>.</dt> + + <dt><b>Returns:</b> An <code>object</code> managing the result of the + attribute access.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + + <h3><a name="objattribute_policies-spec"></a>Class + <code>objattribute_policies</code></h3> + + <p>The policies which are used for proxies representing an attribute + access to a mutable <code>object</code> when the attribute name is + given as a <code>const object</code>.</p> + + <h4><a name="objattribute_policies-spec-synopsis"></a>Class + <code>objattribute_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct objattribute_policies : const_objattribute_policies + { + static object const& set(object const& target, object const& key, object const& value); + static void del(object const&target, object const& key); + }; +}}} +</pre> + + <h4><a name="objattribute_policies-spec-statics"></a>Class + <code>objattribute_policies</code> static functions</h4> +<pre> +static object const& set(object const& target, object const& key, object const& value); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>key</code> is an <code>object</code> + holding a string.</dt> + + <dt><b>Effects:</b> sets the attribute of <code>target</code> named by + <code>key</code> to <code>value</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> +<pre> +static void del(object const&target, object const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>key</code> is an <code>object</code> + holding a string.</dt> + + <dt><b>Effects:</b> deletes the attribute of <code>target</code> named + by <code>key</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + <!-- end --> + <!-- begin --> + + <h3><a name="const_item_policies-spec"></a>Class + <code>const_item_policies</code></h3> + + <p>The policies which are used for proxies representing an item access + (via the Python bracket operators <code>[]</code>) to a + <code>const object</code>.</p> + + <h4><a name="const_item_policies-spec-synopsis"></a>Class + <code>const_item_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct const_item_policies + { + typedef object key_type; + static object get(object const& target, object const& key); + }; +}}} +</pre> + + <h4><a name="const_item_policies-spec-statics"></a>Class + <code>const_item_policies</code> static functions</h4> +<pre> +static object get(object const& target, object const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> accesses the item of <code>target</code> specified + by <code>key</code>.</dt> + + <dt><b>Returns:</b> An <code>object</code> managing the result of the + item access.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + + <h3><a name="item_policies-spec"></a>Class + <code>item_policies</code></h3> + + <p>The policies which are used for proxies representing an item access + (via the Python bracket operators <code>[]</code>) to a mutable + <code>object</code>.</p> + + <h4><a name="item_policies-spec-synopsis"></a>Class + <code>item_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct item_policies : const_item_policies + { + static object const& set(object const& target, object const& key, object const& value); + static void del(object const& target, object const& key); + }; +}}} +</pre> + + <h4><a name="item_policies-spec-statics"></a>Class + <code>item_policies</code> static functions</h4> +<pre> +static object const& set(object const& target, object const& key, object const& value); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> sets the item of <code>target</code> specified by + <code>key</code> to <code>value</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> +<pre> +static void del(object const& target, object const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> deletes the item of <code>target</code> specified + by <code>key</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + <!-- end --> + <!-- begin --> + + <h3><a name="const_slice_policies-spec"></a>Class + <code>const_slice_policies</code></h3> + + <p>The policies which are used for proxies representing an slice access + (via the Python slice notation + <code>[</code><i>x</i><code>:</code><i>y</i><code>]</code>) to a + <code>const object</code>.</p> + + <h4><a name="const_slice_policies-spec-synopsis"></a>Class + <code>const_slice_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct const_slice_policies + { + typedef std::pair<handle<>, handle<> > key_type; + static object get(object const& target, key_type const& key); + }; +}}} +</pre> + + <h4><a name="const_slice_policies-spec-statics"></a>Class + <code>const_slice_policies</code> static functions</h4> +<pre> +static object get(object const& target, key_type const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> accesses the slice of <code>target</code> specified + by <code>key</code>.</dt> + + <dt><b>Returns:</b> An <code>object</code> managing the result of the + slice access.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + + <h3><a name="slice_policies-spec"></a>Class + <code>slice_policies</code></h3> + + <p>The policies which are used for proxies representing an slice access + to a mutable <code>object</code>.</p> + + <h4><a name="slice_policies-spec-synopsis"></a>Class + <code>slice_policies</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + struct slice_policies : const_slice_policies + { + static object const& set(object const& target, key_type const& key, object const& value); + static void del(object const& target, key_type const& key); + }; +}}} +</pre> + + <h4><a name="slice_policies-spec-statics"></a>Class + <code>slice_policies</code> static functions</h4> +<pre> +static object const& set(object const& target, key_type const& key, object const& value); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> sets the slice of <code>target</code> specified by + <code>key</code> to <code>value</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> +<pre> +static void del(object const& target, key_type const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> deletes the slice of <code>target</code> specified + by <code>key</code>.</dt> + + <dt><b>Throws:</b> <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> if a + Python exception is raised.</dt> + </dl> + <!-- end --> + + <h3><a name="object_operators-spec"></a>Class template + <code>object_operators<U></code></h3> + + <p>This is the base class of <code>object</code> and its + <code>proxy</code> template used to supply common interface: member + functions, and operators which must be defined within the class body. Its + template parameter <code>U</code> is expected to be a class derived from + <code>object_operators<U></code>. In practice users should never + use this class directly, but it is documented here because it supplies + important interface to <code>object</code> and its proxies.</p> + + <h4><a name="object_operators-spec-synopsis"></a>Class template + <code>object_operators</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + template <class U> + class object_operators + { + public: + // function call + // + object operator()() const; + + template <class A0> + object operator()(A0 const&) const; + template <class A0, class A1> + object operator()(A0 const&, A1 const&) const; + ... + template <class A0, class A1,...class An> + object operator()(A0 const&, A1 const&,...An const&) const; + + detail::args_proxy operator* () const; + object operator()(detail::args_proxy const &args) const; + object operator()(detail::args_proxy const &args, + detail::kwds_proxy const &kwds) const; + + // truth value testing + // + typedef unspecified bool_type; + operator bool_type() const; + + // Attribute access + // + proxy<const_object_attribute> attr(char const*) const; + proxy<object_attribute> attr(char const*); + proxy<const_object_objattribute> attr(object const&) const; + proxy<object_objattribute> attr(object const&); + + // item access + // + template <class T> + proxy<const_object_item> operator[](T const& key) const; + + template <class T> + proxy<object_item> operator[](T const& key); + + // slicing + // + template <class T, class V> + proxy<const_object_slice> slice(T const& start, V const& end) const + + template <class T, class V> + proxy<object_slice> slice(T const& start, V const& end); + }; +}}} +</pre> + + <h4><a name="object_operators-spec-observers"></a>Class template + <code>object_operators</code> observer functions</h4> +<pre> +object operator()() const; +template <class A0> +object operator()(A0 const&) const; +template <class A0, class A1> +object operator()(A0 const&, A1 const&) const; +... +template <class A0, class A1,...class An> +object operator()(A0 const& a1, A1 const& a2,...An const& aN) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + call<object>(object(*static_cast<U*>(this)).ptr(), a1, + a2,...aN)</dt> + </dl> + +<pre> +object operator()(detail::args_proxy const &args) const; +</pre> +<dl class="function-semantics"> + <dt><b>Effects:</b> + call object with arguments given by the tuple <varname>args</varname></dt> +</dl> +<pre> +object operator()(detail::args_proxy const &args, + detail::kwds_proxy const &kwds) const; +</pre> +<dl class="function-semantics"> + <dt><b>Effects:</b> + call object with arguments given by the tuple <varname>args</varname>, and named + arguments given by the dictionary <varname>kwds</varname></dt> +</dl> + + +<pre> +operator bool_type() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Tests truth value of <code>*this</code>.</dt> + + <dt><b>Returns:</b> + call<object>(object(*static_cast<U*>(this)).ptr(), a1, + a2,...aN)</dt> + </dl> +<pre> +proxy<const_object_attribute> attr(char const* name) const; +proxy<object_attribute> attr(char const* name); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> name is an <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Effects:</b> accesses the named attribute of + <code>*this</code>.</dt> + + <dt><b>Returns:</b> a proxy object which binds + <code>object(*static_cast<U*>(this))</code> as its target, and + <code>name</code> as its key.</dt> + </dl> +<pre> +proxy<const_object_objattribute> attr(const object& name) const; +proxy<object_objattribute> attr(const object& name); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> name is a <code>object</code> holding a string.</dt> + + <dt><b>Effects:</b> accesses the named attribute of + <code>*this</code>.</dt> + + <dt><b>Returns:</b> a proxy object which binds + <code>object(*static_cast<U*>(this))</code> as its target, and + <code>name</code> as its key.</dt> + </dl> +<pre> +template <class T> +proxy<const_object_item> operator[](T const& key) const; +template <class T> +proxy<object_item> operator[](T const& key); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> accesses the item of <code>*this</code> indicated + by <code>key</code>.</dt> + + <dt><b>Returns:</b> a proxy object which binds + <code>object(*static_cast<U*>(this))</code> as its target, and + <code>object(key)</code> as its key.</dt> + </dl> +<pre> +template <class T, class V> +proxy<const_object_slice> slice(T const& start; start, V const& finish) const +template <class T, class V> +proxy<object_slice> slice(T const& start; start, V const& finish); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> accesses the slice of <code>*this</code> indicated + by <code>std::make_pair(object(start), object(finish))</code>.</dt> + + <dt><b>Returns:</b> a proxy object which binds + <code>object(*static_cast<U*>(this))</code> as its target, and + <code>std::make_pair(object(start), object(finish))</code> as its + key.</dt> + </dl> + <!-- --> + + <h3><a name="object-spec"></a>Class <code>object</code></h3> + + <p>The intention is that <code>object</code> acts as much like a + Python variable as possible. Thus expressions you'd expect to work + in Python should generally work in the same way from C++. Most of + <code>object</code>'s interface is provided by its base class + <code><a + href="#object_operators-spec">object_operators</a><object></code>, + and the <a href="#functions">free functions</a> defined in this + header. +</p> + + <h4><a name="object-spec-synopsis"></a>Class <code>object</code> + synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + class object : public object_operators<object> + { + public: + object(); + + object(object const&); + + template <class T> + explicit object(T const& x); + + ~object(); + + object& operator=(object const&); + + PyObject* ptr() const; + + bool is_none() const; + }; +}}} +</pre> + + <h4><a name="object-spec-ctors"></a>Class <code>object</code> + constructors and destructor</h4> +<pre> +object(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Constructs an object managing a reference to the + Python <code>None</code> object.</dt> + + <dt><b>Throws:</b> nothing.</dt> + </dl> +<pre> +template <class T> +explicit object(T const& x); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> converts <code>x</code> to python and manages a + reference to it.</dt> + + <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python + <code>TypeError</code> exception if no such conversion is + possible.</dt> + </dl> +<pre> +~object(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> decrements the reference count of the + internally-held object.</dt> + </dl> + + <h4><a name="object-spec-modifiers"></a>Class <code>object</code> + modifiers</h4> +<pre> +object& operator=(object const& rhs); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> increments the reference count of the object held + by <code>rhs</code> and decrements the reference count of the object + held by <code>*this</code>.</dt> + </dl> + + <h4><a name="object-spec-observers"></a>Class <code>object</code> + observers</h4> +<pre> +PyObject* ptr() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> a pointer to the internally-held Python + object.</dt> + </dl> + +<pre> +bool is_none() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> result of (ptr() == Py_None)</dt> + </dl> + <!-- --> + + <h3><a name="proxy-spec"></a>Class template <code>proxy</code></h3> + + <p>This template is instantiated with various Policies described in this + document in order to implement attribute, item, and slice access for + <code>object</code>. It stores an object of type + <code>Policies::key_type</code>.</p> + + <h4><a name="proxy-spec-synopsis"></a>Class template <code>proxy</code> + synopsis</h4> +<pre> +namespace boost { namespace python { namespace api +{ + template <class Policies> + class proxy : public object_operators<proxy<Policies> > + { + public: + operator object() const; + + proxy const& operator=(proxy const&) const; + template <class T> + inline proxy const& operator=(T const& rhs) const; + + void del() const; + + template <class R> + proxy operator+=(R const& rhs); + template <class R> + proxy operator-=(R const& rhs); + template <class R> + proxy operator*=(R const& rhs); + template <class R> + proxy operator/=(R const& rhs); + template <class R> + proxy operator%=(R const& rhs); + template <class R> + proxy operator<<=(R const& rhs); + template <class R> + proxy operator>>=(R const& rhs); + template <class R> + proxy operator&=(R const& rhs); + template <class R> + proxy operator|=(R const& rhs); + }; +}}} +</pre> + + <h4><a name="proxy-spec-observers"></a>Class template <code>proxy</code> + observer functions</h4> +<pre> +operator object() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> applies + <code>Policies::get(</code><i>target</i><code>,</code> <i>key</i> + <code>)</code> with the proxy's target and key objects.</dt> + </dl> + + <h4><a name="proxy-spec-modifiers"></a>Class template <code>proxy</code> + modifier functions</h4> +<pre> +proxy const& operator=(proxy const& rhs) const; +template <class T> +inline proxy const& operator=(T const& rhs) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Policies::set(</code><i>target</i><code>,</code> <i>key</i> + <code>, object(rhs))</code> with the proxy's target and key + objects.</dt> + </dl> +<pre> +template <class R> +proxy operator+=(R const& rhs); +template <class R> +proxy operator-=(R const& rhs); +template <class R> +proxy operator*=(R const& rhs); +template <class R> +proxy operator/=(R const& rhs); +template <class R> +proxy operator%=(R const& rhs); +template <class R> +proxy operator<<=(R const& rhs); +template <class R> +proxy operator>>=(R const& rhs); +template <class R> +proxy operator&=(R const& rhs); +template <class R> +proxy operator|=(R const& rhs); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> for a given operator@=, + <code>object(*this) @= rhs;</code></dt> + <dt><b>Returns:</b> <code>*this</code></dt> + </dl> +<pre> +void del() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>Policies::del(</code><i>target</i><code>,</code> <i>key</i> + <code>)</code> with the proxy's target and key objects.</dt> + </dl> + <!-- --> + + <h2><a name="functions"></a>Functions</h2> +<pre> +<a name="del-spec"></a>template <class T> +void del(proxy<T> const& x); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> x.del()</dt> + </dl> +<pre> +<a name="comparisons-spec"></a> +template<class L,class R> object operator>(L const&l,R const&r); +template<class L,class R> object operator>=(L const&l,R const&r); +template<class L,class R> object operator<(L const&l,R const&r); +template<class L,class R> object operator<=(L const&l,R const&r); +template<class L,class R> object operator==(L const&l,R const&r); +template<class L,class R> object operator!=(L const&l,R const&r); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> returns the result of applying the operator to + <code>object(l)</code> and <code>object(r)</code>, respectively, in + Python.</dt> + </dl> +<pre> +<a name="binary-spec"></a> +template<class L,class R> object operator+(L const&l,R const&r); +template<class L,class R> object operator-(L const&l,R const&r); +template<class L,class R> object operator*(L const&l,R const&r); +template<class L,class R> object operator/(L const&l,R const&r); +template<class L,class R> object operator%(L const&l,R const&r); +template<class L,class R> object operator<<(L const&l,R const&r); +template<class L,class R> object operator>>(L const&l,R const&r); +template<class L,class R> object operator&(L const&l,R const&r); +template<class L,class R> object operator^(L const&l,R const&r); +template<class L,class R> object operator|(L const&l,R const&r); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> returns the result of applying the operator to + <code>object(l)</code> and <code>object(r)</code>, respectively, in + Python.</dt> + </dl> +<pre> +<a name="assignment-spec"></a> +template<class R> object& operator+=(object&l,R const&r); +template<class R> object& operator-=(object&l,R const&r); +template<class R> object& operator*=(object&l,R const&r); +template<class R> object& operator/=(object&l,R const&r); +template<class R> object& operator%=(object&l,R const&r); +template<class R> object& operator<<=(object&l,R const&r) +template<class R> object& operator>>=(object&l,R const&r); +template<class R> object& operator&=(object&l,R const&r); +template<class R> object& operator^=(object&l,R const&r); +template<class R> object& operator|=(object&l,R const&r); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> assigns to l the result of applying the + corresponding Python inplace operator to <code>l</code> and + <code>object(r)</code>, respectively.</dt> + + <dt><b>Returns:</b> <code>l</code>.</dt> + </dl> + +<pre> +inline long len(object const& obj); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> PyObject_Length(obj.ptr()) </dt> + <dt><b>Returns:</b> len() of object.</dt> + </dl> + +<h2><a name="examples"></a>Example</h2> + Python code: +<pre> +def sum_items(seq): + result = 0 + for x in seq: + result += x + return result +</pre> + C++ version: +<pre> +object sum_items(object seq) +{ + object result = object(0); + for (int i = 0; i < len(seq); ++i) + result += seq[i]; + return result; +} +</pre> + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 15 March, 2010 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2008.</i></p> + </body> +</html> diff --git a/libs/python/doc/v2/opaque.html b/libs/python/doc/v2/opaque.html new file mode 100644 index 000000000..fed1d446f --- /dev/null +++ b/libs/python/doc/v2/opaque.html @@ -0,0 +1,138 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright 2003..2006 Haufe Mediengruppe. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> + +<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/opaque_pointer_converter.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/opaque_pointer_converter.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#opaque-spec">Class template + <code>opaque<Pointee></code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#opaque-spec-synopsis">Class template + <code>opaque</code> synopsis</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#macros">Macros</a></dt> + <dd> + <dl class="page-index"> + <dt><a href="#BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec">Macro + <code>BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</code></a></dt> + </dl> + </dd> + + <dt><a href="#see-also">See Also</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="opaque-spec"></a>Class template + <code>opaque<P></code></h3> + + <p><code>opaque<></code> registers itself as a converter from + Python objects to pointers to undefined types and vice versa.</p> + + <h4><a name="opaque-spec-synopsis"></a>Class template + <code>opaque</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template<class Pointee> + struct opaque + { + opaque(); + }; +}} +</pre> + + <h4><a name="opaque-spec-constructor"></a>Class template + <code>opaque</code> constructor</h4> +<pre> +opaque(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <ul> + <li>Registers the instance as a + <a href="lvalue_from_pytype.html#lvalue_from_pytype-spec"> <code>lvalue_from_pytype</code></a> + converter from Python objects into opaque pointers.</p> + <p>The Python Objects created are named after the type pointed to + by the opaque pointer being wrapped.</p></li> + <li>Registers the instance as a + <a href="to_python_converter.html#to_python_converter-spec"> <code>to_python_converter</code></a> + from opaque pointers to Python objects.</p></li> + </ul> + <p>If there is already an instance registered by another module, this + instance doesn't try to register again in order to avoid warnings + about multiple registrations.</p> + + <h4>Note</h4> + <p>Normally only a single instance of this class is created for every + Pointee.</p> + </dt> + </dl> + + <h2><a name="macros"></a>Macros</h2> + + <h3><a name="BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec"></a> + Macro BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(Pointee)</h3> + <p>This macro must be used to define specializations of the + <a href="type_id.html#type_id-spec">type_id</a> function + which can't be instantiated for incomplete types.</p> + <h4>Note</h4> + <p>The macro must be invoked in every translation unit which uses the + opaque converter.</p> + + <h2><a name="see-also"></a>See Also</h2> + <p> + <a href="return_opaque_pointer.html">return_opaque_pointer</a> + </p> + + <p>Revised + 10 September, 2006 + </p> + + <p><i>© Copyright 2003..2006 Haufe Mediengruppe. All Rights + Reserved.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/operators.html b/libs/python/doc/v2/operators.html new file mode 100644 index 000000000..69740243f --- /dev/null +++ b/libs/python/doc/v2/operators.html @@ -0,0 +1,921 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/operators.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/operators.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="#self_t-spec">Class + <code>self_ns::self_t</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#self_t-spec-synopsis">Class <code>self_t</code> + synopsis</a></dt> + + <dt><a href="#self_t-spec-inplace">Class <code>self_t</code> + inplace operators</a></dt> + + <dt><a href="#self_t-spec-comparisons">Class + <code>self_t</code> comparison functions</a></dt> + + <dt><a href="#self_t-spec-ops">Class <code>self_t</code> + non-member operations</a></dt> + + <dt><a href="#self_t-spec-value-unary-ops">Class + <code>self_t</code> unary operations</a></dt> + + <dt><a href="#self_t-spec-value-ops">Class + <code>self_t</code> value operations</a></dt> + </dl> + </dd> + + <dt><a href="#other-spec">Class template + <code>other</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#other-spec-synopsis">Class <code>other</code> + synopsis</a></dt> + </dl> + </dd> + + <dt><a href="#operator_-spec">Class template + <code>operator_</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#operator_-spec-synopsis">Class + <code>operator_</code> synopsis</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#objects">Objects</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#self-spec">self</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/operators.hpp></code> provides types and + functions for automatically generating Python <a href= + "http://www.python.org/doc/ref/specialnames.html">special methods</a> + from the corresponding C++ constructs. Most of these constructs are + operator expressions, hence the name. To use the facility, substitute the + <code><a href="#self-spec">self</a></code> object for an object of the + class type being wrapped in the expression to be exposed, and pass the + result to <a href= + "class.html#class_-spec-modifiers">class_<>::def()</a>. Much of + what is exposed in this header should be considered part of the + implementation, so is not documented in detail here.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="self_t-spec"></a>Class <code>self_ns::self_t</code></h3> + + <p><code>self_ns::self_t</code> is the actual type of the <a href= + "#self-spec"><code>self</code></a> object. The library isolates + <code>self_t</code> in its own namespace, <code>self_ns</code>, in order + to prevent the generalized operator templates which operate on it from + being found by argument-dependent lookup in other contexts. This should + be considered an implementation detail, since users should never have to + mention <code>self_t</code> directly.</p> + + <h4><a name="self_t-spec-synopsis"></a>Class <code>self_ns::self_t</code> + synopsis</h4> +<pre> +namespace boost { namespace python { namespace self_ns { +{ + <i>unspecified-type-declaration</i> self_t; + + // inplace operators + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator+=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator-=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator*=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator/=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator%=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator>>=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator<<=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator&=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator^=(self_t, T); + template <class T> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator|=(self_t, T); + + // comparisons + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator==(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator!=(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator<(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator>(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator<=(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator>=(L const&, R const&); + + // non-member operations + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator+(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator-(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator*(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator/(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator%(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator>>(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator<<(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator&(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator^(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator|(L const&, R const&); + template <class L, class R> <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> pow(L const&, R const&); + + // unary operations + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator-(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator+(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator~(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> operator!(self_t); + + // value operations + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> int_(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> long_(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> float_(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> complex_(self_t); + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> str(self_t); + + <a href= +"#operator_-spec">operator_</a><<i>unspecified</i>> repr(self_t); + +}}}; +</pre> + The tables below describe the methods generated when the results of the + expressions described are passed as arguments to <a href= + "class.html#class_-spec-modifiers">class_<>::def()</a>. + <code><b>x</b></code> is an object of the class type being wrapped. + + <h4><a name="self_t-spec-inplace"></a>Class <code>self_t</code> inplace + operators</h4> + In the table below, If <code><b>r</b></code> is an object of type + <code><a href="#other-spec">other</a><T></code>, + <code><b>y</b></code> is an object of type <code>T</code>; otherwise, + <code><b>y</b></code> is an object of the same type as + <code><b>r</b></code>. + + <table border="1" summary="self_t inplace operators"> + <tr> + <th>C++ Expression</th> + + <th>Python Method Name</th> + + <th>C++ Implementation</th> + </tr> + + <tr> + <td><code>self += r</code></td> + + <td><code>__iadd__</code></td> + + <td><code>x += y</code></td> + </tr> + + <tr> + <td><code>self -= r</code></td> + + <td><code>__isub__</code></td> + + <td><code>x -= y</code></td> + </tr> + + <tr> + <td><code>self *= r</code></td> + + <td><code>__imul__</code></td> + + <td><code>x *= y</code></td> + </tr> + + <tr> + <td><code>self /= r</code></td> + + <td><code>__idiv__</code></td> + + <td><code>x /= y</code></td> + </tr> + + <tr> + <td><code>self %= r</code></td> + + <td><code>__imod__</code></td> + + <td><code>x %= y</code></td> + </tr> + + <tr> + <td><code>self >>= r</code></td> + + <td><code>__irshift__</code></td> + + <td><code>x >>= y</code></td> + </tr> + + <tr> + <td><code>self <<= r</code></td> + + <td><code>__ilshift__</code></td> + + <td><code>x <<= y</code></td> + </tr> + + <tr> + <td><code>self &= r</code></td> + + <td><code>__iand__</code></td> + + <td><code>x &= y</code></td> + </tr> + + <tr> + <td><code>self ^= r</code></td> + + <td><code>__ixor__</code></td> + + <td><code>x ^= y</code></td> + </tr> + + <tr> + <td><code>self |= r</code></td> + + <td><code>__ior__</code></td> + + <td><code>x |= y</code></td> + </tr> + </table> + + <h4><a name="self_t-spec-comparisons"></a>Class <code>self_t</code> + comparison functions</h4> + In the tables below, if <code><b>r</b></code> is of type <code><a href= + "#self_t-spec">self_t</a></code>, <code><b>y</b></code> is an object of + the same type as <code>x</code>; <br> + if <code><b>l</b></code> or <code><b>r</b></code> is an object of type + <code><a href="#other-spec">other</a><T></code>, + <code><b>y</b></code> is an object of type <code>T</code>; <br> + otherwise, <code><b>y</b></code> is an object of the same type as + <code><b>l</b></code> or <code><b>r</b></code>.<br> + <code><b>l</b></code> is never of type <code><a href= + "#self_t-spec">self_t</a></code>. + + <p>The column of <b>Python Expressions</b> illustrates the expressions + that will be supported in Python for objects convertible to the types of + <code>x</code> and <code>y</code>. The secondary operation arises due to + Python's <a href= + "http://www.python.org/doc/ref/customization.html#l2h-89">reflection + rules</a> for rich comparison operators, and are only used when the + corresponding operation is not defined as a method of the <code>y</code> + object.</p> + + <table border="1" summary="self_t comparison functions"> + <tr> + <th>C++ Expression</th> + + <th>Python Method Name</th> + + <th>C++ Implementation</th> + + <th>Python Expressions<br> + (primary, secondary)</th> + </tr> + + <tr> + <td><code>self == r</code></td> + + <td><code>__eq__</code></td> + + <td><code>x == y</code></td> + + <td><code>x == y, y == x</code></td> + </tr> + + <tr> + <td><code>l == self</code></td> + + <td><code>__eq__</code></td> + + <td><code>y == x</code></td> + + <td><code>y == x, x == y</code></td> + </tr> + + <tr> + <td><code>self != r</code></td> + + <td><code>__ne__</code></td> + + <td><code>x != y</code></td> + + <td><code>x != y, y != x</code></td> + </tr> + + <tr> + <td><code>l != self</code></td> + + <td><code>__ne__</code></td> + + <td><code>y != x</code></td> + + <td><code>y != x, x != y</code></td> + </tr> + + <tr> + <td><code>self < r</code></td> + + <td><code>__lt__</code></td> + + <td><code>x < y</code></td> + + <td><code>x < y, y > x</code></td> + </tr> + + <tr> + <td><code>l < self</code></td> + + <td><code>__gt__</code></td> + + <td><code>y < x</code></td> + + <td><code>y > x, x < y</code></td> + </tr> + + <tr> + <td><code>self > r</code></td> + + <td><code>__gt__</code></td> + + <td><code>x > y</code></td> + + <td><code>x > y, y < x</code></td> + </tr> + + <tr> + <td><code>l > self</code></td> + + <td><code>__lt__</code></td> + + <td><code>y > x</code></td> + + <td><code>y < x, x > y</code></td> + </tr> + + <tr> + <td><code>self <= r</code></td> + + <td><code>__le__</code></td> + + <td><code>x <= y</code></td> + + <td><code>x <= y, y >= x</code></td> + </tr> + + <tr> + <td><code>l <= self</code></td> + + <td><code>__ge__</code></td> + + <td><code>y <= x</code></td> + + <td><code>y >= x, x <= y</code></td> + </tr> + + <tr> + <td><code>self >= r</code></td> + + <td><code>__ge__</code></td> + + <td><code>x >= y</code></td> + + <td><code>x >= y, y <= x</code></td> + </tr> + + <tr> + <td><code>l >= self</code></td> + + <td><code>__le__</code></td> + + <td><code>y >= x</code></td> + + <td><code>y <= x, x >= y</code></td> + </tr> + </table> + + <h4><a name="self_t-spec-ops"></a>Class <code>self_t</code> non-member + operations</h4> + The operations whose names begin with "<code>__r</code>" below will only + be called if the left-hand operand does not already support the given + operation, as described <a href= + "http://www.python.org/doc/current/ref/numeric-types.html#l2h-152">here</a>. + + + <table border="1" summary="self_t non-member operations"> + <tr> + <th>C++ Expression</th> + + <th>Python Method Name</th> + + <th>C++ Implementation</th> + </tr> + + <tr> + <td><code>self + r</code></td> + + <td><code>__add__</code></td> + + <td><code>x + y</code></td> + </tr> + + <tr> + <td><code>l + self</code></td> + + <td><code>__radd__</code></td> + + <td><code>y + x</code></td> + </tr> + + <tr> + <td><code>self - r</code></td> + + <td><code>__sub__</code></td> + + <td><code>x - y</code></td> + </tr> + + <tr> + <td><code>l - self</code></td> + + <td><code>__rsub__</code></td> + + <td><code>y - x</code></td> + </tr> + + <tr> + <td><code>self * r</code></td> + + <td><code>__mul__</code></td> + + <td><code>x * y</code></td> + </tr> + + <tr> + <td><code>l * self</code></td> + + <td><code>__rmul__</code></td> + + <td><code>y * x</code></td> + </tr> + + <tr> + <td><code>self / r</code></td> + + <td><code>__div__</code></td> + + <td><code>x / y</code></td> + </tr> + + <tr> + <td><code>l / self</code></td> + + <td><code>__rdiv__</code></td> + + <td><code>y / x</code></td> + </tr> + + <tr> + <td><code>self % r</code></td> + + <td><code>__mod__</code></td> + + <td><code>x % y</code></td> + </tr> + + <tr> + <td><code>l % self</code></td> + + <td><code>__rmod__</code></td> + + <td><code>y % x</code></td> + </tr> + + <tr> + <td><code>self >> r</code></td> + + <td><code>__rshift__</code></td> + + <td><code>x >> y</code></td> + </tr> + + <tr> + <td><code>l >> self</code></td> + + <td><code>__rrshift__</code></td> + + <td><code>y >> x</code></td> + </tr> + + <tr> + <td><code>self << r</code></td> + + <td><code>__lshift__</code></td> + + <td><code>x << y</code></td> + </tr> + + <tr> + <td><code>l << self</code></td> + + <td><code>__rlshift__</code></td> + + <td><code>y << x</code></td> + </tr> + + <tr> + <td><code>self & r</code></td> + + <td><code>__and__</code></td> + + <td><code>x & y</code></td> + </tr> + + <tr> + <td><code>l & self</code></td> + + <td><code>__rand__</code></td> + + <td><code>y & x</code></td> + </tr> + + <tr> + <td><code>self ^ r</code></td> + + <td><code>__xor__</code></td> + + <td><code>x ^ y</code></td> + </tr> + + <tr> + <td><code>l ^ self</code></td> + + <td><code>__rxor__</code></td> + + <td><code>y ^ x</code></td> + </tr> + + <tr> + <td><code>self | r</code></td> + + <td><code>__or__</code></td> + + <td><code>x | y</code></td> + </tr> + + <tr> + <td><code>l | self</code></td> + + <td><code>__ror__</code></td> + + <td><code>y | x</code></td> + </tr> + + <tr> + <td><code>pow(self, r)</code></td> + + <td><code>__pow__</code></td> + + <td><code>pow(x, y)</code></td> + </tr> + + <tr> + <td><code>pow(l, self)</code></td> + + <td><code>__rpow__</code></td> + + <td><code>pow(y, x)</code></td> + </tr> + </table> + + <h4><a name="self_t-spec-value-unary-ops"></a>Class <code>self_t</code> unary + operations</h4> + + <table border="1" summary="self_t unary operations"> + <tr> + <th>C++ Expression</th> + + <th>Python Method Name</th> + + <th>C++ Implementation</th> + </tr> + + <tr> + <td><code>-self</code></td> + + <td><code>__neg__</code></td> + + <td><code>-x</code></td> + </tr> + + <tr> + <td><code>+self</code></td> + + <td><code>__pos__</code></td> + + <td><code>+x</code></td> + </tr> + + <tr> + <td><code>~self</code></td> + + <td><code>__invert__</code></td> + + <td><code>~x</code></td> + </tr> + + <tr> + <td><code>not self</code><br><i>or</i><br><code>!self</code></td> + + <td><code>__nonzero__</code></td> + + <td><code>!!x</code></td> + </tr> + </table> + + <h4><a name="self_t-spec-value-ops"></a>Class <code>self_t</code> value + operations</h4> + + <table border="1" summary="self_t value operations"> + <tr> + <th>C++ Expression</th> + + <th>Python Method Name</th> + + <th>C++ Implementation</th> + </tr> + + <tr> + <td><code>int_(self)</code></td> + + <td><code>__int__</code></td> + + <td><code>long(x)</code></td> + </tr> + + <tr> + <td><code>long_</code></td> + + <td><code>__long__</code></td> + + <td><code>PyLong_FromLong(x)</code></td> + </tr> + + <tr> + <td><code>float_</code></td> + + <td><code>__float__</code></td> + + <td><code>double(x)</code></td> + </tr> + + <tr> + <td><code>complex_</code></td> + + <td><code>__complex__</code></td> + + <td><code>std::complex<double>(x)</code></td> + </tr> + + <tr> + <td><code>str</code></td> + + <td><code>__str__</code></td> + + <td><code><a href= + "../../../conversion/lexical_cast.htm#lexical_cast">lexical_cast</a><std::string>(x)</code></td> + </tr> + + <tr> + <td><code>repr</code></td> + + <td><code>__repr__</code></td> + + <td><code><a href= + "../../../conversion/lexical_cast.htm#lexical_cast">lexical_cast</a><std::string>(x)</code></td> + </tr> + </table> + + <h3><a name="other-spec"></a>Class Template <code>other</code></h3> + + <p>Instances of <code>other<T></code> can be used in operator + expressions with <a href="#self-spec">self</a>; the result is equivalent + to the same expression with a <code>T</code> object in place of + <code>other<T></code>. Use <code>other<T></code> to prevent + construction of a <code>T</code> object in case it is heavyweight, when + no constructor is available, or simply for clarity.</p> + + <h4><a name="other-spec-synopsis"></a>Class Template other synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> + struct other + { + }; +}} +</pre> + <!-- --> + + <h3><a name="operator_-spec"></a>Class Template + <code>detail::operator_</code></h3> + + <p>Instantiations of <code>detail::operator_<></code> are used as + the return type of operator expressions involving <code><a href= + "#self-spec">self</a></code>. This should be considered an implementation + detail and is only documented here as a way of showing how the result of + <code>self</code>-expressions match calls to <a href= + "class.html#class_-spec-modifiers">class_<>::def()</a>.</p> + + <h4><a name="operator_-spec-synopsis"></a>Class Template + <code>detail::operator_</code> synopsis</h4> +<pre> +namespace boost { namespace python { namespace detail +{ + template <<i>unspecified</i>> + struct operator_ + { + }; +}}} +</pre> + + <h2><a name="objects"></a>Objects</h2> + + <p><a name="self-spec"><code>self</code></a></p> +<pre> +namespace boost { namespace python +{ + using self_ns::self; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/operators.hpp> +#include <boost/operators.hpp> + +struct number + : boost::<a href= +"../../../utility/operators.htm#grpd_oprs">integer_arithmetic</a><number> +{ + explicit number(long x_) : x(x_) {} + operator long() const { return x; } + + template <class T> + number& operator+=(T const& rhs) + { x += rhs; return *this; } + + template <class T> + number& operator-=(T const& rhs) + { x -= rhs; return *this; } + + template <class T> + number& operator*=(T const& rhs) + { x *= rhs; return *this; } + + template <class T> + number& operator/=(T const& rhs) + { x /= rhs; return *this; } + + template <class T> + number& operator%=(T const& rhs) + { x %= rhs; return *this; } + + long x; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(demo) +{ + class_<number>("number", init<long>()) + // interoperate with self + .def(self += self) + .def(self + self) + .def(self -= self) + .def(self - self) + .def(self *= self) + .def(self * self) + .def(self /= self) + .def(self / self) + .def(self %= self) + .def(self % self) + + // Convert to Python int + .def(int_(self)) + + // interoperate with long + .def(self += long()) + .def(self + long()) + .def(long() + self) + .def(self -= long()) + .def(self - long()) + .def(long() - self) + .def(self *= long()) + .def(self * long()) + .def(long() * self) + .def(self /= long()) + .def(self / long()) + .def(long() / self) + .def(self %= long()) + .def(self % long()) + .def(long() % self) + ; +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 5 October, 2004 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/overloads.html b/libs/python/doc/v2/overloads.html new file mode 100644 index 000000000..783e8e5db --- /dev/null +++ b/libs/python/doc/v2/overloads.html @@ -0,0 +1,229 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/overloads.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/overloads.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href= + "#overload-dispatch-expression"><i>overload-dispatch-expressions</i></a></dt> + + <dt><a href= "#OverloadDispatcher-concept">OverloadDispatcher</a> concept</dt> + + <dt><a href="#macros">Macros</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href= + "#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS</a></dt> + + <dt><a href= + "#BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Defines facilities for generating families of overloaded Python + functions and extension class methods from C++ functions and + member functions with default arguments, or from similar families + of C++ overloads</p> + + <h2><a name= + "overload-dispatch-expression"></a><i>overload-dispatch-expressions</i></h2> + + <p> + An <em>overload-dispatch-expression</em> is used to describe a + family of overloaded methods to be generated for an extension + class. It has the following properties: + + <blockquote> + <dl class="properties"> + <dt><b>docstring:</b> An <a href="definitions.html#ntbs">ntbs</a> + whose value will bound to the methods' <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 subsequence of) the arguments + to the generated methods.</dt> + + <dt><b>call policies:</b> An instance of some type which models <a href= + "CallPolicies.html">CallPolicies</a>.</dt> + + <dt><b>minimum <a href="definitions.html#arity">arity</a></b> + The minimum number of arguments to be accepted by a generated + method overload.</dt> + + <dt><b>maximum <a href="definitions.html#arity">arity</a></b> + The maximum number of arguments to be accepted by a generated + method overload.</dt> + </dl> + </blockquote> + + <h2><a name="OverloadDispatcher-concept"></a>OverloadDispatcher Concept</h2> + + An OverloadDispatcher <code>X</code> is a class which has a + <em>minimum arity</em> and a <em>maximum arity</em>, and for which + the following following are valid <a + href="#overload-dispatch-expression"><em>overload-dispatch-expression</em></a>s, + with the same minimum and maximum arity as the OverloadDispatcher. + +<pre> +X() +X(docstring) +X(docstring, keywords) +X(keywords, docstring) +X()[policies] +X(docstring)[policies] +X(docstring, keywords)[policies] +X(keywords, docstring)[policies] +</pre> + +<ul> +<li>If <code>policies</code> are supplied, it must be an instance of a +type which models <a +href="CallPolicies.html#CallPolicies-concept">CallPolicies</a>, and +will be used as the result's call policies. Otherwise the result's +call policies will be an instance of <a +href="default_call_policies.html#default_call_policies-spec">default_call_policies</a>. + +<li>If <code>docstring</code> is supplied it must be an <a +href="definitions.html#ntbs">ntbs</a>, and will be used as the result's docstring. Otherwise the result has an empty docstring. + +<li>If <code>keywords</code> is supplied it must be the result of a <a + href= "args.html#keyword-expression">keyword-expression</a> + whose length is no greater than <code>X</code>'s maximum + arity, and will be used as the result's keywords. Otherwise + the result's keywords will be empty. +</ul> + + + + + <h2><a name="macros"></a>Macros</h2> + + <h3><a name= + "BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS(name, func_id, min_args, max_args)</a></h3> + Expands to the definition of an OverloadDispatcher called + <code>name</code> in the current scope which can be used to + generate the following function invocation: +<pre> +func_id(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>); +</pre> + + for all <code>min_args</code> <= <i>i</i> <= <code>max_args</code>. + + <h3><a name= + "BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name, member_name, min_args, max_args)</a></h3> + + Expands to the definition of an OverloadDispatcher called + <code>name</code> in the current scope which can be used to + generate the following function invocation: +<pre> +x.member_name(a<small><i>1</i></small>, a<small><i>2</i></small>,...a<small><i>i</i></small>); +</pre> + + for all <code>min_args</code> <= <i>i</i> <= + <code>max_args</code>, where <code>x</code> is a reference to an + object of class type. + + <h2><a name="examples"></a>Example(s)</h2> + +<pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/args.hpp> +#include <boost/python/tuple.hpp> +#include <boost/python/class.hpp> +#include <boost/python/overloads.hpp> +#include <boost/python/return_internal_reference.hpp> + +using namespace boost::python; + +tuple f(int x = 1, double y = 4.25, char const* z = "wow") +{ + return make_tuple(x, y, z); +} + +BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3) + +struct Y {}; +struct X +{ + Y& f(int x, double y = 4.25, char const* z = "wow") + { + return inner; + } + Y inner; +}; + +BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(f_member_overloads, f, 1, 3) + +BOOST_PYTHON_MODULE(args_ext) +{ + def("f", f, + f_overloads( + args("x", "y", "z"), "This is f's docstring" + )); + + + class_<Y>("Y") + ; + + class_<X>("X", "This is X's docstring") + .def("f1", &X::f, + f_member_overloads( + args("x", "y", "z"), "f's docstring" + )[return_internal_reference<>()] + ) + ; +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 15 April, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/pickle.html b/libs/python/doc/v2/pickle.html new file mode 100644 index 000000000..22e198d63 --- /dev/null +++ b/libs/python/doc/v2/pickle.html @@ -0,0 +1,280 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> + <title>Boost.Python Pickle Support</title> +</head> + +<body> + <div> + <img src="../../../../boost.png" alt="boost.png (6897 bytes)" align= + "center" width="277" height="86" /> + <hr /> + + <h1>Boost.Python Pickle Support</h1>Pickle is a Python module for object + serialization, also known as persistence, marshalling, or flattening. + + <p>It is often necessary to save and restore the contents of an object to + a file. One approach to this problem is to write a pair of functions that + read and write data from a file in a special format. A powerful + alternative approach is to use Python's pickle module. Exploiting + Python's ability for introspection, the pickle module recursively + converts nearly arbitrary Python objects into a stream of bytes that can + be written to a file.</p> + + <p>The Boost Python Library supports the pickle module through the + interface as described in detail in the <a href= + "http://www.python.org/doc/current/lib/module-pickle.html">Python Library + Reference for pickle.</a> This interface involves the special methods + <tt>__getinitargs__</tt>, <tt>__getstate__</tt> and <tt>__setstate__</tt> + as described in the following. Note that Boost.Python is also fully + compatible with Python's cPickle module.</p> + <hr /> + + <h2>The Boost.Python Pickle Interface</h2>At the user level, the + Boost.Python pickle interface involves three special methods: + + <dl> + <dt><strong><tt>__getinitargs__</tt></strong></dt> + + <dd> + When an instance of a Boost.Python extension class is pickled, the + pickler tests if the instance has a <tt>__getinitargs__</tt> method. + This method must return a Python tuple (it is most convenient to use + a boost::python::tuple). When the instance is restored by the + unpickler, the contents of this tuple are used as the arguments for + the class constructor. + + <p>If <tt>__getinitargs__</tt> is not defined, <tt>pickle.load</tt> + will call the constructor (<tt>__init__</tt>) without arguments; + i.e., the object must be default-constructible.</p> + </dd> + + <dt><strong><tt>__getstate__</tt></strong></dt> + + <dd>When an instance of a Boost.Python extension class is pickled, the + pickler tests if the instance has a <tt>__getstate__</tt> method. This + method should return a Python object representing the state of the + instance.</dd> + + <dt><strong><tt>__setstate__</tt></strong></dt> + + <dd>When an instance of a Boost.Python extension class is restored by + the unpickler (<tt>pickle.load</tt>), it is first constructed using the + result of <tt>__getinitargs__</tt> as arguments (see above). + Subsequently the unpickler tests if the new instance has a + <tt>__setstate__</tt> method. If so, this method is called with the + result of <tt>__getstate__</tt> (a Python object) as the argument.</dd> + </dl>The three special methods described above may be <tt>.def()</tt>'ed + individually by the user. However, Boost.Python provides an easy to use + high-level interface via the + <strong><tt>boost::python::pickle_suite</tt></strong> class that also + enforces consistency: <tt>__getstate__</tt> and <tt>__setstate__</tt> + must be defined as pairs. Use of this interface is demonstrated by the + following examples. + <hr /> + + <h2>Examples</h2>There are three files in <tt>boost/libs/python/test</tt> + that show how to provide pickle support. + <hr /> + + <h3><a href="../../test/pickle1.cpp"><tt>pickle1.cpp</tt></a></h3>The C++ + class in this example can be fully restored by passing the appropriate + argument to the constructor. Therefore it is sufficient to define the + pickle interface method <tt>__getinitargs__</tt>. This is done in the + following way: + + <ul> + <li>1. Definition of the C++ pickle function: + <pre> + struct world_pickle_suite : boost::python::pickle_suite + { + static + boost::python::tuple + getinitargs(world const& w) + { + return boost::python::make_tuple(w.get_country()); + } + }; +</pre> + </li> + + <li>2. Establishing the Python binding: + <pre> + class_<world>("world", args<const std::string&>()) + // ... + .def_pickle(world_pickle_suite()) + // ... +</pre> + </li> + </ul> + <hr /> + + <h3><a href="../../test/pickle2.cpp"><tt>pickle2.cpp</tt></a></h3>The C++ + class in this example contains member data that cannot be restored by any + of the constructors. Therefore it is necessary to provide the + <tt>__getstate__</tt>/<tt>__setstate__</tt> pair of pickle interface + methods: + + <ul> + <li>1. Definition of the C++ pickle functions: + <pre> + struct world_pickle_suite : boost::python::pickle_suite + { + static + boost::python::tuple + getinitargs(const world& w) + { + // ... + } + + static + boost::python::tuple + getstate(const world& w) + { + // ... + } + + static + void + setstate(world& w, boost::python::tuple state) + { + // ... + } + }; +</pre> + </li> + + <li>2. Establishing the Python bindings for the entire suite: + <pre> + class_<world>("world", args<const std::string&>()) + // ... + .def_pickle(world_pickle_suite()) + // ... +</pre> + </li> + </ul> + + <p>For simplicity, the <tt>__dict__</tt> is not included in the result of + <tt>__getstate__</tt>. This is not generally recommended, but a valid + approach if it is anticipated that the object's <tt>__dict__</tt> will + always be empty. Note that the safety guard described below will catch + the cases where this assumption is violated.</p> + <hr /> + + <h3><a href="../../test/pickle3.cpp"><tt>pickle3.cpp</tt></a></h3>This + example is similar to <a href= + "../../test/pickle2.cpp"><tt>pickle2.cpp</tt></a>. However, the object's + <tt>__dict__</tt> is included in the result of <tt>__getstate__</tt>. + This requires a little more code but is unavoidable if the object's + <tt>__dict__</tt> is not always empty. + <hr /> + + <h2>Pitfall and Safety Guard</h2>The pickle protocol described above has + an important pitfall that the end user of a Boost.Python extension module + might not be aware of: + + <p><strong><tt>__getstate__</tt> is defined and the instance's + <tt>__dict__</tt> is not empty.</strong></p> + + <p>The author of a Boost.Python extension class might provide a + <tt>__getstate__</tt> method without considering the possibilities + that:</p> + + <ul> + <li>his class is used in Python as a base class. Most likely the + <tt>__dict__</tt> of instances of the derived class needs to be pickled + in order to restore the instances correctly.</li> + + <li>the user adds items to the instance's <tt>__dict__</tt> directly. + Again, the <tt>__dict__</tt> of the instance then needs to be + pickled.</li> + </ul> + + <p>To alert the user to this highly unobvious problem, a safety guard is + provided. If <tt>__getstate__</tt> is defined and the instance's + <tt>__dict__</tt> is not empty, Boost.Python tests if the class has an + attribute <tt>__getstate_manages_dict__</tt>. An exception is raised if + this attribute is not defined:</p> + <pre> + RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set) +</pre>To resolve this problem, it should first be established that the <tt> + __getstate__</tt> and <tt>__setstate__</tt> methods manage the + instances's <tt>__dict__</tt> correctly. Note that this can be done + either at the C++ or the Python level. Finally, the safety guard should + intentionally be overridden. E.g. in C++ (from <a href= + "../../test/pickle3.cpp"><tt>pickle3.cpp</tt></a>): + <pre> + struct world_pickle_suite : boost::python::pickle_suite + { + // ... + + static bool getstate_manages_dict() { return true; } + }; +</pre>Alternatively in Python: + <pre> + import your_bpl_module + class your_class(your_bpl_module.your_class): + __getstate_manages_dict__ = 1 + def __getstate__(self): + # your code here + def __setstate__(self, state): + # your code here +</pre> + <hr /> + + <h2>Practical Advice</h2> + + <ul> + <li>In Boost.Python extension modules with many extension classes, + providing complete pickle support for all classes would be a + significant overhead. In general complete pickle support should only be + implemented for extension classes that will eventually be pickled.</li> + + <li>Avoid using <tt>__getstate__</tt> if the instance can also be + reconstructed by way of <tt>__getinitargs__</tt>. This automatically + avoids the pitfall described above.</li> + + <li>If <tt>__getstate__</tt> is required, include the instance's + <tt>__dict__</tt> in the Python object that is returned.</li> + </ul> + <hr /> + + <h2>Light-weight alternative: pickle support implemented in Python</h2> + + <h3><a href="../../test/pickle4.cpp"><tt>pickle4.cpp</tt></a></h3>The + <tt>pickle4.cpp</tt> example demonstrates an alternative technique for + implementing pickle support. First we direct Boost.Python via the + <tt>class_::enable_pickling()</tt> member function to define only the + basic attributes required for pickling: + <pre> + class_<world>("world", args<const std::string&>()) + // ... + .enable_pickling() + // ... +</pre>This enables the standard Python pickle interface as described in the +Python documentation. By "injecting" a <tt>__getinitargs__</tt> method into +the definition of the wrapped class we make all instances pickleable: + <pre> + # import the wrapped world class + from pickle4_ext import world + + # definition of __getinitargs__ + def world_getinitargs(self): + return (self.get_country(),) + + # now inject __getinitargs__ (Python is a dynamic language!) + world.__getinitargs__ = world_getinitargs +</pre>See also the <a href= +"../tutorial/doc/html/python/techniques.html#python.extending_wrapped_objects_in_python"> + tutorial section</a> on injecting additional methods from Python. + <hr /> + © Copyright Ralf W. Grosse-Kunstleve 2001-2004. Distributed under the + Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + + <p>Updated: Feb 2004.</p> + </div> +</body> +</html> diff --git a/libs/python/doc/v2/platforms.html b/libs/python/doc/v2/platforms.html new file mode 100644 index 000000000..ac984b43f --- /dev/null +++ b/libs/python/doc/v2/platforms.html @@ -0,0 +1,135 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Known Working Platforms and Compilers</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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Known Working Platforms and Compilers</h2> + </td> + </tr> + </table> + <hr> + Please see + our <a + href="http://boost.sourceforge.net/regression-logs">regression + logs</a> for up-to-date information. Note that logs not marked + otherwise reflect the CVS state, not the condition of the release. + + <p> + Earlier versions of <b>Boost.Python</b> have been successfully + tested on the following platforms and compilers. + + <dl class="page-index"> + <dt>Unix Platforms:</dt> + + <dd> + <dl> + <dt>with Python <a href="http://www.python.org/2.2">2.2</a> and <a + href="http://www.python.org/2.2.2">2.2.2b1</a>:</dt> + + <dd> + <dl> + <dt><a href="http://gcc.gnu.org">GCC</a> 2.95.3, 2.96, 3.0.4, + 3.1, and 3.2 on <a href="http://www.redhat.com">RedHat Linux 7.3</a> + for Intel x86</dt> + + <dt>Tru64 CXX 6.5.1 on OSF v. 5.1 for Dec/Compaq + Alpha</dt> + + <dt> + MIPSPro 7.3.1.2m on <a href= + "http://www.sgi.com/software/irix6.5/">IRIX 6.5</a> for SGI + mips</dt> + + <dt><a href="http://gcc.gnu.org">GCC 3.1</a> on SunOS 5.8</dt> + </dl> + </dd> + + <dt>with Python <a href= + "http://www.python.org/2.2.1">2.2.1</a></dt> + + <dd> + <dl> + <dt>KCC 3.4d on OSF v. 5.1 for Dec/Compaq Alpha</dt> + + <dt>KCC 3.4d</a> on AIX</dt> + </dl> + </dd> + </dl> + <br> + </dd> + + <dt>Microsoft Windows XP Professional with Python <a href= + "http://www.python.org/2.2">2.2</a>, <a href= + "http://www.python.org/2.2.1">2.2.1</a>, and <a href= + "http://www.python.org/2.2.2">2.2.2b1</a>:</dt> + + <dd> + <dl> + <dt><a href= + "http://msdn.microsoft.com/visualc/default.asp">Microsoft Visual + C++</a> 6, 7, and 7.1 beta</dt> + + <dt><a href= + "http://msdn.microsoft.com/visualc/default.asp">Microsoft Visual + C++ 6</a> with <a href="http://www.stlport.org">STLPort + 4.5.3</a></dt> + + <dt><a href= + "http://www.metrowerks.com/MW/Develop/Desktop/Windows/Professional/Default.htm"> + Metrowerks CodeWarrior</a> 7.2, 8.0, 8.2 and 8.3 beta</dt> + + <dt><a href= + "http://www.intel.com/software/products/compilers/c60/">Intel + C++</a> 5.0, 6.0, and 7.0 beta</dt> + + <dt><a href= + "http://www.intel.com/software/products/compilers/c60/">Intel C++ + 5.0</a> with <a href="http://www.stlport.org">STLPort + 4.5.3</a></dt> + + <dt><a href="http://www.cygwin.com">Cygwin</a> <a href= + "http://gcc.gnu.org">GCC</a> 3.0.4 and 3.2</dt> + + <dt><a href="http://www.mingw.org">MinGW-1.1</a> (<a href= + "http://gcc.gnu.org">GCC 2.95.3-5</a>)</dt> + + <dt><a href="http://www.mingw.org">MinGW-2.0</a> (<a href= + "http://gcc.gnu.org">GCC 3.2</a>)</dt> + </dl> + </dd> + </dl> + <hr> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/pointee.html b/libs/python/doc/v2/pointee.html new file mode 100644 index 000000000..2dcec8c36 --- /dev/null +++ b/libs/python/doc/v2/pointee.html @@ -0,0 +1,119 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, 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/pointee.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/pointee.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + + <dt><a href="#classes">Classes</a> + + <dd> + <dl class="page-index"> + <dt><a href="#pointee-spec">Class Template<code>pointee</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#pointee-spec-synopsis">Class Template + <code>pointee</code> synopsis</a> + </dl> + </dl> + + <dt><a href="#examples">Example</a> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/pointee.hpp></code> introduces a + traits <a + href="../../../mpl/doc/refmanual/metafunction.html">metafunction</a> + template <code>pointee<T></code> that can be used to extract the "pointed-to" type from the type of a pointer or smart pointer. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="pointee-spec"></a>Class Template <code>pointee<class T></code></h3> + + <p><code>pointee<T></code> is used by the <code><a + href="class.html#class_-spec">class_</a><...></code> + template to deduce the type being held when a pointer or smart + pointer type is used as its <code>HeldType</code> argument. + + <h4><a name="pointee-spec-synopsis"></a>Class Template + <code>pointee</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> struct pointee + { + typedef T::element_type type; + }; + + // specialization for pointers + template <T> struct pointee<T*> + { + typedef T type; + }; +} +</pre> + + + <h2><a name="examples"></a>Example</h2> + +Given a 3rd-party smart pointer type +<code>smart_pointer<T></code>, one might partially specialize +<code>pointee<smart_pointer<T> ></code> so that it can be +used as the <code>HeldType</code> for a class wrapper: + +<pre> +#include <boost/python/pointee.hpp> +#include <boost/python/class.hpp> +#include <third_party_lib.hpp> + +namespace boost { namespace python +{ + template <class T> struct pointee<smart_pointer<T> > + { + typedef T type; + }; +}} + +BOOST_PYTHON_MODULE(pointee_demo) +{ + class_<third_party_class, smart_pointer<third_party_class> >("third_party_class") + .def(...) + ... + ; +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> Distributed + under the Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> + + diff --git a/libs/python/doc/v2/progress_reports.html b/libs/python/doc/v2/progress_reports.html new file mode 100644 index 000000000..5a8b015a2 --- /dev/null +++ b/libs/python/doc/v2/progress_reports.html @@ -0,0 +1,47 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - Progress Reports</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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Progress Reports</h2> + </td> + </tr> +</table> +<hr> + +Monthly progress reports are required as part of Boost Consulting's +contract with LLNL for Boost.Python development. These reports contain +a useful record of the project history, including the rationale for +design decisions and links to relevant discussions. + +<dl class="page-index"> + <dt><a href="feb2002.html">February 2002</a></dt> + <dt><a href="Mar2002.html">March 2002</a></dt> + <dt><a href="Apr2002.html">April 2002</a></dt> + <dt><a href="May2002.html">May 2002</a></dt> + <dt><a href="Jun2002.html">June 2002</a></dt> +</dl> +<hr> +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> diff --git a/libs/python/doc/v2/ptr.html b/libs/python/doc/v2/ptr.html new file mode 100644 index 000000000..4aca53915 --- /dev/null +++ b/libs/python/doc/v2/ptr.html @@ -0,0 +1,265 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, 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/ptr.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/ptr.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + + <dt><a href="#functions">Functions</a> + <dd> + <dl class="page-index"> + <dt><a href="#ptr-spec">ptr</a> + </dl> + + <dt><a href="#classes">Classes</a> + <dd> + <dl class="page-index"> + <dt><a href="#pointer_wrapper-spec">Class template <code>pointer_wrapper</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#pointer_wrapper-spec-synopsis">Class template <code>pointer_wrapper</code> synopsis</a> + + <dt><a href="#pointer_wrapper-spec-types">Class + <code>pointer_wrapper</code> types</a> + + <dt><a href="#pointer_wrapper-spec-ctors">Class + <code>pointer_wrapper</code> constructors and destructor</a> + + <dt><a href="#pointer_wrapper-spec-observers">Class + <code>pointer_wrapper</code> observer functions</a> + + </dl> + </dl> + + <dt><a href="#metafunctions">Metafunctions</a> + <dd> + <dl class="page-index"> + <dt><a href="#is_pointer_wrapper-spec">Class template <code>is_pointer_wrapper</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#is_pointer_wrapper-spec-synopsis">Class template <code>is_pointer_wrapper</code> synopsis</a> + </dl> + + + <dt><a href="#unwrap_pointer-spec">Class template <code>unwrap_pointer</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#unwrap_pointer-spec-synopsis">Class template <code>unwrap_pointer</code> synopsis</a> + </dl> + + </dl> + + + <dt><a href="#examples">Example(s)</a> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/ptr.hpp></code> defines the + <code>ptr()</code> function template, which allows users to + specify how to convert C++ pointer values to python in the context + of implementing overridable virtual functions, invoking Python + callable objects, or explicitly converting C++ objects to + Python. Normally, when passing pointers to Python callbacks, the + pointee is copied to ensure that the Python object + never holds a dangling reference. To specify that the new Python + object should merely contain a copy of a pointer <code>p</code>, + the user can pass <code><a href="#ptr-spec">ptr</a>(p)</code> instead of passing + <code>p</code> directly. This interface is meant to mirror the use + of <a href="../../../bind/ref.html"><code>boost::ref()</code></a>, + which can be similarly used to prevent copying of referents. + + <p><code>ptr(p)</code> returns an instance of <code><a + href="#pointer_wrapper-spec">pointer_wrapper<></a></code>, which + can be detected using the <code><a + href="#is_pointer_wrapper-spec">is_pointer_wrapper<></a></code> + metafunction; <code><a + href="#unwrap_pointer-spec">unwrap_pointer<></a></code> is a + metafunction which extracts the original pointer type from a + <code>pointer_wrapper<></code>. These classes can be thought + of as implementation details. + + <h2><a name="functions"></a>Functions</h2> +<pre> + +<a name="ptr-spec">template <class T></a> +pointer_wrapper<T> ptr(T x); +</pre> + + <dl class="ptr-semantics"> + <dt><b>Requires:</b> <code>T</code> is a pointer type. + + <dt><b>Returns:</b> <code><a href="#pointer_wrapper-spec">pointer_wrapper</a><T>(x)</code> + + <dt><b>Throws:</b> nothing. + </dl> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="pointer_wrapper-spec"></a>Class template <code>pointer_wrapper</code></h3> + + <p>A "type envelope" which is returned by <a + href="#ptr-spec">ptr()</a>, used to indicate reference semantics + for pointers passed to Python callbacks. + + <h4><a name="pointer_wrapper-spec-synopsis"></a>Class + <code>pointer_wrapper</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template<class Ptr> class pointer_wrapper + { + public: + typedef Ptr type; + + explicit pointer_wrapper(Ptr x); + operator Ptr() const; + Ptr get() const; + }; +}} +</pre> + + <h4><a name="pointer_wrapper-spec-types"></a>Class template <code>pointer_wrapper</code> types</h4> +<pre> +typedef Ptr type; +</pre> +The type of the pointer being wrapped. + + <h4><a name="pointer_wrapper-spec-ctors"></a>Class template <code>pointer_wrapper</code> constructors and + destructor</h4> +<pre> +explicit pointer_wrapper(Ptr x); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>Ptr</code> is a pointer type. + + <dt><b>Effects:</b> Stores <code>x</code> in a the <code>pointer_wrapper<></code>. + <dt><b>Throws:</b> nothing. + </dl> + + <h4><a name="pointer_wrapper-spec-observers"></a>Class template <code>pointer_wrapper</code> observer + functions</h4> +<pre> +operator Ptr() const; +Ptr get() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> a copy of the stored pointer. + <dt><b>Rationale:</b> <code>pointer_wrapper</code> is intended + to be a stand-in for the actual pointer type, but sometimes it's + better to have an explicit way to retrieve the pointer. + </dl> + + <h2><a name="metafunctions"></a>Metafunctions</h2> + + <h3><a name="is_pointer_wrapper-spec"></a>Class template <code>is_pointer_wrapper</code></h3> + + <p>A unary metafunction whose <code>value</code> is true iff its + argument is a <code>pointer_wrapper<></code>. + + <h4><a name="is_pointer_wrapper-spec-synopsis"></a>Class template <code>is_pointer_wrapper</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template<class T> class is_pointer_wrapper + { + static <i>unspecified</i> value = ...; + }; +}} +</pre> + + + <dl class="metafunction-semantics"> + <dt><b>Returns:</b> <code>true</code> iff <code>T</code> is a + specialization of +<code>pointer_wrapper<></code>. +<dt><code>value</code> is an integral constant convertible to bool of +unspecified type + + </dl> + +<h3><a name="unwrap_pointer-spec"></a>Class template <code>unwrap_pointer</code></h3> + +A unary metafunction which extracts the wrapped pointer type from a +specialization of <code>pointer_wrapper<></code>. + + <h4><a name="unwrap_pointer-spec-synopsis"></a>Class template <code>unwrap_pointer</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template<class T> class unwrap_pointer + { + typedef <i>unspecified</i> type; + }; +}} +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Returns:</b> <code>T::type</code> if <code>T</code> is a + specialization of +<code>pointer_wrapper<></code>, <code>T</code> otherwise + </dl> + + + <h2><a name="examples"></a>Example(s)</h2> + +This example illustrates the use of <code>ptr()</code> to prevent an +object from being copied: +<pre> +#include <boost/python/call.hpp> +#include <boost/python/ptr.hpp> + +class expensive_to_copy +{ + ... +}; + +void pass_as_arg(expensive_to_copy* x, PyObject* f) +{ + // call the Python function f, passing a Python object built around + // which refers to *x by-pointer. + // + // *** Note: ensuring that *x outlives the argument to f() is *** + // *** up to the user! Failure to do so could result in a crash! *** + + boost::python::call<void>(f, ptr(x)); +} +... +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> Distributed + under the Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> + diff --git a/libs/python/doc/v2/python.html b/libs/python/doc/v2/python.html new file mode 100644 index 000000000..9c4e27ec6 --- /dev/null +++ b/libs/python/doc/v2/python.html @@ -0,0 +1,110 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>This is a convenience header which #includes all of the public + interface headers that are part of the Boost.Python library</p> +<pre> +# include <args.hpp> +# include <args_fwd.hpp> +# include <back_reference.hpp> +# include <bases.hpp> +# include <borrowed.hpp> +# include <call.hpp> +# include <call_method.hpp> +# include <class.hpp> +# include <copy_const_reference.hpp> +# include <copy_non_const_reference.hpp> +# include <data_members.hpp> +# include <def.hpp> +# include <default_call_policies.hpp> +# include <dict.hpp> +# include <enum.hpp> +# include <errors.hpp> +# include <exception_translator.hpp> +# include <extract.hpp> +# include <handle.hpp> +# include <has_back_reference.hpp> +# include <implicit.hpp> +# include <init.hpp> +# include <instance_holder.hpp> +# include <iterator.hpp> +# include <list.hpp> +# include <long.hpp> +# include <lvalue_from_pytype.hpp> +# include <make_function.hpp> +# include <manage_new_object.hpp> +# include <module.hpp> +# include <numeric.hpp> +# include <object.hpp> +# include <object_protocol.hpp> +# include <object_protocol_core.hpp> +# include <operators.hpp> +# include <other.hpp> +# include <overloads.hpp> +# include <pointee.hpp> +# include <ptr.hpp> +# include <reference_existing_object.hpp> +# include <return_internal_reference.hpp> +# include <return_value_policy.hpp> +# include <scope.hpp> +# include <self.hpp> +# include <slice_nil.hpp> +# include <str.hpp> +# include <to_python_converter.hpp> +# include <to_python_indirect.hpp> +# include <to_python_value.hpp> +# include <tuple.hpp> +# include <type_id.hpp> +# include <with_custodian_and_ward.hpp> +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/pytype_function.html b/libs/python/doc/v2/pytype_function.html new file mode 100644 index 000000000..fcc2a7f92 --- /dev/null +++ b/libs/python/doc/v2/pytype_function.html @@ -0,0 +1,370 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright Nikolay Mladenov 2007. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> +<head> + <meta http-equiv="Content-Type" content= + "text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - + <boost/python/doobject/pytype_function.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="../../../../boost.png" border= + "0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href= + "../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/converter/pytype_function.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="#wrap_pytype-spec">Class + <code>wrap_pytype</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#wrap_pytype-spec-synopsis">Class + <code>wrap_pytype</code> synopsis</a></dt> + + </dl> + </dd> + </dl> + </dd> + + <dd> + <dl class="page-index"> + <dt><a href="#registered_pytype-spec">Class + <code>registered_pytype</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#registered_pytype-spec-synopsis">Class + <code>registered_pytype</code> synopsis</a></dt> + + </dl> + </dd> + </dl> + </dd> + + <dd> + <dl class="page-index"> + <dt><a href="#expected_from_python_type-spec">Class + <code>expected_from_python_type</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#expected_from_python_type-spec-synopsis">Class + <code>expected_from_python_type</code> synopsis</a></dt> + + </dl> + </dd> + </dl> + </dd> + + <dd> + <dl class="page-index"> + <dt><a href="#to_python_target_type-spec">Class + <code>to_python_target_type</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#to_python_target_type-spec-synopsis">Class + <code>to_python_target_type</code> synopsis</a></dt> + + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction" id= + "introduction"></a>Introduction</h2> + + <p>To support Pythonic signatures the converters should supply a <code>get_pytype</code> function + returning a pointer to the associated <code>PyTypeObject</code>. See for example + <a href="ResultConverter.html#ResultConverter-concept">ResultConverter</a> or + <a href="to_python_converter.html#to_python_converter-spec">to_python_converter</a>. + The classes in this header file are meant to be used when implmenting <code>get_pytype</code>. + There are also <code>_direct</code> versions of the templates of <code>class T</code> which + should be used with undecorated type parameter, expected to be in the conversion registry when the module loads. + </p> + + <h2><a name="classes" id="classes"></a>Classes</h2> + + <h3><a name="wrap_pytype-spec" id= + "wrap_pytype-spec"></a>Class + <code>wrap_pytype</code></h3> + + <p> + This template generates a static <code>get_pytype</code> member returning the template parameter. + </p> + + <h4><a name="wrap_pytype-spec-synopsis" id= + "wrap_pytype-spec-synopsis"></a>Class + <code>wrap_pytype</code> synopsis</h4> + <pre> +namespace boost { namespace python { namespace converter{ + + template < PyTypeObject const *pytype > + class wrap_pytype + { + public: + static PyTypeObject const *get_pytype(){return pytype; } + }; + +}}} +</pre> + + + <h3><a name="registered_pytype-spec" id= + "registered_pytype-spec"></a>Class + <code>registered_pytype</code></h3> + + <p> + This template should be used with template parameters which are (possibly decorated) + types exported to python using <a href="class.html"><code>class_</code></a>. + The generated a static <code>get_pytype</code> member + returns the corresponding python type. + </p> + + <h4><a name="registered_pytype-spec-synopsis" id= + "registered_pytype-spec-synopsis"></a>Class + <code>registered_pytype</code> synopsis</h4> + <pre> +namespace boost { namespace python { namespace converter{ + + template < class T > + class registered_pytype + { + public: + static PyTypeObject const *get_pytype(); + }; + +}}} +</pre> + + + <h3><a name="expected_from_python_type-spec" id= + "expected_from_python_type-spec"></a>Class + <code>expected_from_python_type</code></h3> + + <p> + This template generates a static <code>get_pytype</code> member which inspects the registered + <code>from_python</code> converters for the type <code>T</code> and returns a matching python type. + </p> + + <h4><a name="expected_from_python_type-spec-synopsis" id= + "expected_from_python_type-spec-synopsis"></a>Class + <code>expected_from_python_type</code> synopsis</h4> + <pre> +namespace boost { namespace python { namespace converter{ + + template < class T > + class expected_from_python_type + { + public: + static PyTypeObject const *get_pytype(); + }; + +}}} +</pre> + + + <h3><a name="to_python_target_type-spec" id= + "to_python_target_type-spec"></a>Class + <code>to_python_target_type</code></h3> + + <p> + This template generates a static <code>get_pytype</code> member returning the + python type to which T can be converted. + </p> + + <h4><a name="to_python_target_type-spec-synopsis" id= + "to_python_target_type-spec-synopsis"></a>Class + <code>to_python_target_type</code> synopsis</h4> + <pre> +namespace boost { namespace python { namespace converter{ + + template < class T > + class to_python_target_type + { + public: + static PyTypeObject const *get_pytype(); + }; + +}}} +</pre> + + + <h2><a name="examples" id="examples"></a>Examples</h2> + + This example presumes that someone has implemented the standard <a href= + "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example + module</a> from the Python documentation, and placed the corresponding + declarations in <code>"noddy.h"</code>. Because + <code>noddy_NoddyObject</code> is the ultimate trivial extension type, + the example is a bit contrived: it wraps a function for which all + information is contained in the <i>type</i> of its return value. + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/reference.hpp> +#include <boost/python/module.hpp> +#include "noddy.h" + +struct tag {}; +tag make_tag() { return tag(); } + +using namespace boost::python; + +struct tag_to_noddy +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //unnecessary overhead if py signatures are not supported +: wrap_pytype<&noddy_NoddyType> //inherits get_pytype from wrap_pytype +#endif +{ + static PyObject* convert(tag const& x) + { + return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); + } +}; + +BOOST_PYTHON_MODULE(to_python_converter) +{ + def("make_tag", make_tag); + to_python_converter<tag, tag_to_noddy +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported + , true +#endif + >(); //"true" because tag_to_noddy has member get_pytype +} +</pre> + + +<p>The following example registers to and from python converters using the templates +<code>expected_from_python_type</code> and <code>to_pyhton_target_type</code>. +</p> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/def.hpp> +#include <boost/python/extract.hpp> +#include <boost/python/to_python_converter.hpp> +#include <boost/python/class.hpp> + +using namespace boost::python; + +struct A +{ +}; + +struct B +{ + A a; + B(const A& a_):a(a_){} +}; + +// Converter from A to python int +struct BToPython +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //unnecessary overhead if py signatures are not supported + : converter::to_python_target_type<A> //inherits get_pytype +#endif +{ + static PyObject* convert(const B& b) + { + return incref(object(b.a).ptr()); + } +}; + +// Conversion from python int to A +struct BFromPython +{ + BFromPython() + { + boost::python::converter::registry::push_back + ( &convertible + , &construct + , type_id< B >() +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported + , &converter::expected_from_python_type<A>::get_pytype//convertible to A can be converted to B +#endif + ); + } + + static void* convertible(PyObject* obj_ptr) + { + extract<const A&> ex(obj_ptr); + if (!ex.check()) return 0; + return obj_ptr; + } + + static void construct( + PyObject* obj_ptr, + converter::rvalue_from_python_stage1_data* data) + { + void* storage = ( + (converter::rvalue_from_python_storage< B >*)data)-> storage.bytes; + + extract<const A&> ex(obj_ptr); + new (storage) B(ex()); + data->convertible = storage; + } +}; + + +B func(const B& b) { return b ; } + +BOOST_PYTHON_MODULE(pytype_function_ext) +{ + to_python_converter< B , BToPython +#if defined BOOST_PYTHON_SUPPORTS_PY_SIGNATURES //invalid if py signatures are not supported + ,true +#endif + >(); //has get_pytype + BFromPython(); + + class_<A>("A") ; + + def("func", &func); + +} + + + +>>> from pytype_function_ext import * +>>> print func.__doc__ +func( (A)arg1) -> A : + C++ signature: + struct B func(struct B) +</pre> + + + <p><i>© Copyright <a href="mailto:nickm at sitius dot com">Nikolay Mladenov</a> 2007.</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/raw_function.html b/libs/python/doc/v2/raw_function.html new file mode 100644 index 000000000..0ad4c37c2 --- /dev/null +++ b/libs/python/doc/v2/raw_function.html @@ -0,0 +1,118 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 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/raw_function.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/raw_function.hpp></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> + + <dd> + <dl class="page-index"> + <dt><a href="#raw_function-spec">raw_function</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><a href="#raw_function-spec">raw_function</a>(...)</code> + is used to convert a function taking a <a + href="tuple.html#tuple-spec">tuple</a> and a <a + href="dict.html#dict-spec">dict</a> into a Python callable object + which accepts a variable number of arguments and arbitrary keyword + arguments. + + <h2><a name="functions"></a>Functions</h2> + <a name="raw_function-spec"></a>raw_function +<pre> +template <class F> +object raw_function(F f, std::size_t min_args = 0); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>f(tuple(), dict())</code> is + well-formed.</dt> + + <dt><b>Returns:</b> a <a href= + "http://www.python.org/doc/current/lib/built-in-funcs.html#l2h-6">callable</a> object which requires at least <code>min_args</code> arguments. When called, the actual non-keyword arguments will be passed in a <a + href="tuple.html#tuple-spec">tuple</a> as the first argument to <code>f</code>, and the keyword arguments will be passed in a <a + href="dict.html#dict-spec">dict</a> as the second argument to <code>f</code>. + + </dd> + </dl> + + <h2><a name="examples"></a>Example</h2> +C++: +<pre> +#include <boost/python/def.hpp> +#include <boost/python/tuple.hpp> +#include <boost/python/dict.hpp> +#include <boost/python/module.hpp> +#include <boost/python/raw_function.hpp> + +using namespace boost::python; + +tuple raw(tuple args, dict kw) +{ + return make_tuple(args, kw); +} + +BOOST_PYTHON_MODULE(raw_test) +{ + def("raw", raw_function(raw)); +} +</pre> + +Python: +<pre> +>>> from raw_test import * + +>>> raw(3, 4, foo = 'bar', baz = 42) +((3, 4), {'foo': 'bar', 'baz': 42}) +</pre> + <p> + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 7 March, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/reference.html b/libs/python/doc/v2/reference.html new file mode 100644 index 000000000..5ebdad105 --- /dev/null +++ b/libs/python/doc/v2/reference.html @@ -0,0 +1,1192 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 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 - Reference</title> + + <style type="text/css"> + p.c3 {font-style: italic} + h2.c2 {text-align: center} + h1.c1 {text-align: center} + </style> + </head> + + <body> + <table border="0" cellpadding="7" cellspacing="0" width="100%" summary= + "reference"> + <tr> + <td valign="top" width="300"> + <h3><a href="http://www.boost.org"><img height="86" width="277" + alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Reference</h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="Reference"> + <dt><a href="#concepts">Concepts</a></dt> + + <dt><a href="#high_level">High Level Components</a></dt> + + <dt><a href="#object_wrappers">Object Wrappers</a></dt> + + <dt><a href="#invocation">Function Invocation and Creation</a></dt> + + <dd> + <dl class="index"> + <dt><a href="#models_of_call_policies">Models of + CallPolicies</a></dt> + + <dt><a href="#models_of_result_converter">Models of + ResultConverter</a></dt> + + <dt><a href="#result_converter_generators">Models of + ResultConverterGenerator</a></dt> + </dl> + </dd> + + <dt><a href="#type_conversion">To/From Python Type Conversion</a></dt> + + <dt><a href="#embedding">Embedding</a></dt> + + <dt><a href="#utility">Utility and Infrastructure</a></dt> + + <dt><a href="#topics">Topics</a></dt> + </dl> + <hr> + <!-- xxxxx --> + + <h2><a name="concepts">Concepts</a></h2> + + <dl class="index"> + <dt><a href= + "CallPolicies.html#CallPolicies-concept">CallPolicies</a></dt> + + <dt><a href= + "Dereferenceable.html#Dereferenceable-concept">Dereferenceable</a></dt> + + <dt><a href="Extractor.html#Extractor-concept">Extractor</a></dt> + + <dt><a href= + "HolderGenerator.html#HolderGenerator-concept">HolderGenerator</a></dt> + + <dt><a href= + "ResultConverter.html#ResultConverter-concept">ResultConverter</a></dt> + + <dt><a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a></dt> + + <dt><a href= + "ObjectWrapper.html#ObjectWrapper-concept">ObjectWrapper</a></dt> + + <dt><a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a></dt> + </dl> + + <h2><a name="high_level">High Level Components</a></h2> + + <dl> + <dt><a href="class.html">class.hpp/class_fwd.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="class.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="class.html#class_-spec">class_</a></dt> + + <dt><a href="class.html#bases-spec">bases</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="def.html">def.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="def.html#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="def.html#def-spec">def</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="def_visitor.html">def_visitor.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="def_visitor.html#classes">Classes</a></dt> + </dl> + </dd> + + <dt><a href="docstring_options.html">docstring_options.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="docstring_options.html#classes">Classes</a></dt> + </dl> + </dd> + + <dt><a href="enum.html">enum.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="enum.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="enum.html#enum_-spec">enum_</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="errors.html">errors.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="errors.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "errors.html#error_already_set-spec">error_already_set</a></dt> + </dl> + </dd> + + <dt><a href="errors.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "errors.html#handle_exception-spec">handle_exception</a></dt> + + <dt><a href= + "errors.html#expect_non_null-spec">expect_non_null</a></dt> + + <dt><a href= + "errors.html#throw_error_already_set-spec">throw_error_already_set</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "exception_translator.html">exception_translator.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "exception_translator.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "exception_translator.html#register_exception_translator-spec">register_exception_translator</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="init.html">init.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="init.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="init.html#init-spec">init</a></dt> + + <dt><a href="init.html#optional-spec">optional</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="iterator.html">iterator.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="iterator.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="iterator.html#iterator-spec">iterator</a></dt> + + <dt><a href="iterator.html#iterators-spec">iterators</a></dt> + </dl> + </dd> + + <dt><a href="iterator.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="iterator.html#range-spec">range</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="module.html">module.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="module.html#macros">Macros</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "module.html#BOOST_PYTHON_MODULE-spec">BOOST_PYTHON_MODULE</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="operators.html">operators.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="operators.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="operators.html#self_t-spec">self_t</a></dt> + + <dt><a href="operators.html#other-spec">other</a></dt> + + <dt><a href="operators.html#operator_-spec">operator_</a></dt> + </dl> + </dd> + + <dt><a href="operators.html#objects">Objects</a></dt> + + <dd> + <dl class="index"> + <dt><a href="operators.html#self-spec">self</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="scope.html">scope.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="scope.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="scope.html#scope-spec">scope</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="stl_iterator.html">stl_iterator.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="stl_iterator.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="stl_iterator.html#stl_input_iterator-spec">stl_input_iterator</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="wrapper.html">wrapper.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="wrapper.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="wrapper.html#override-spec">override</a></dt> + + <dt><a href="wrapper.html#wrapper-spec">wrapper</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a name="object_wrappers">Object Wrappers</a></h2> + + <dl class="index"> + <dt><a href="dict.html">dict.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="dict.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="dict.html#dict-spec">dict</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="list.html">list.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="list.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="list.html#list-spec">list</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="long.html">long.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="long.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="long.html#long_-spec">long_</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="numeric.html">numeric.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="numeric.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="numeric.html#array-spec">numeric::array</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="object.html">object.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="object.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="object.html#object-spec">object</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="str.html">str.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="str.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="str.html#str-spec">str</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="tuple.html">tuple.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="tuple.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="tuple.html#tuple-spec">tuple</a></dt> + </dl> + </dd> + + <dt><a href="tuple.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="tuple.html#make_tuple-spec">make_tuple</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="slice.html">slice.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="slice.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="slice.html#slice-spec">slice</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a name="invocation">Function Invocation and Creation</a></h2> + + <dl class="index"> + <dt><a href="args.html">args.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="args.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="args.html#args-spec">args</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="call.html">call.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="call.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="call.html#call-spec">call</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="call_method.html">call_method.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="call_method.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "call_method.html#call_method-spec">call_method</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="data_members.html">data_members.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="data_members.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "data_members.html#make_getter-spec">make_getter</a></dt> + + <dt><a href= + "data_members.html#make_setter-spec">make_setter</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="make_function.html">make_function.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="make_function.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "make_function.html#make_function-spec">make_function</a></dt> + + <dt><a href= + "make_function.html#make_constructor-spec">make_constructor</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="overloads.html">overloads.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="overloads.html#macros">macros</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_FUNCTION_OVERLOADS</a></dt> + + <dt><a href= + "overloads.html#BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS-spec">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="ptr.html">ptr.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="ptr.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="ptr.html#ptr-spec">ptr</a></dt> + </dl> + </dd> + + <dt><a href="ptr.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "ptr.html#pointer_wrapper-spec">pointer_wrapper</a></dt> + </dl> + </dd> + + <dt><a href="ptr.html#metafunctions">MetaFunctions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "ptr.html#is_pointer_wrapper-spec">is_pointer_wrapper</a></dt> + + <dt><a href= + "ptr.html#unwrap_pointer-spec">unwrap_pointer</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="raw_function.html">raw_function.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="raw_function.html#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href= + "raw_function.html#raw_function-spec">raw_function</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dd> + <a name="function_documentation"></a> + + <h3>Function documentation</h3> + + <dl class="index"> + <dt><a href= + "function_doc_signature.html">function_doc_signature.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "function_doc_signature.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "function_doc_signature.html#function_doc_signature_generator-spec">function_doc_signature_generator</a></dt> + + </dl> + </dd> + </dl> + </dd> + </dl> + <dl class="index"> + <dt><a href= + "pytype_function.html">pytype_function.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "pytype_function.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "pytype_function.html#wrap_pytype-spec">wrap_pytype</a></dt> + + </dl> + <dl class="index"> + <dt><a href= + "pytype_function.html#expected_from_python_type-spec">expected_from_python_type</a></dt> + + </dl> + <dl class="index"> + <dt><a href= + "pytype_function.html#to_python_target_type-spec">to_python_target_type</a></dt> + + </dl> + <dl class="index"> + <dt><a href= + "pytype_function.html#registered_pytype-spec">registered_pytype</a></dt> + + </dl> + </dd> + </dl> + </dd> + </dl> + </dd> + + <dd> + <a name="models_of_call_policies"></a> + + <h3>Models of CallPolicies</h3> + + <dl class="index"> + <dt><a href= + "default_call_policies.html">default_call_policies.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "default_call_policies.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "default_call_policies.html#default_call_policies-spec">default_call_policies</a></dt> + + <dt><a href= + "default_call_policies.html#default_result_converter-spec">default_result_converter</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="return_arg.html">return_arg.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="return_arg.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_arg.html#return_arg-spec">return_arg</a></dt> + + <dt><a href= + "return_arg.html#return_self-spec">return_self</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "return_internal_reference.html">return_internal_reference.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_internal_reference.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_internal_reference.html#return_internal_reference-spec"> + return_internal_reference</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "return_value_policy.html">return_value_policy.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="return_value_policy.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_value_policy.html#return_value_policy-spec">return_value_policy</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "with_custodian_and_ward.html">with_custodian_and_ward.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "with_custodian_and_ward.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "with_custodian_and_ward.html#with_custodian_and_ward-spec"> + with_custodian_and_ward</a></dt> + + <dt><a href= + "with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec"> + with_custodian_and_ward_postcall</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + <a name="models_of_result_converter"></a> + + <h3>Models of ResultConverter</h3> + + <dl class="index"> + <dt><a href= + "to_python_indirect.html">to_python_indirect.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="to_python_indirect.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="to_python_value.html">to_python_value.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="to_python_value.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "to_python_value.html#to_python_value-spec">to_python_value</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + <a name="result_converter_generators"></a> + + <h3>Models of ResultConverterGenerator</h3> + + <dl class="index"> + <dt><a href= + "copy_const_reference.html">copy_const_reference.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "copy_const_reference.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "copy_const_reference.html#copy_const_reference-spec">copy_const_reference</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "copy_non_const_reference.html">copy_non_const_reference.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "copy_non_const_reference.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "copy_non_const_reference.html#copy_non_const_reference-spec"> + copy_non_const_reference</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="manage_new_object.html">manage_new_object.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="manage_new_object.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "manage_new_object.html#manage_new_object-spec">manage_new_object</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "reference_existing_object.html">reference_existing_object.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "reference_existing_object.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "reference_existing_object.html#reference_existing_object-spec"> + reference_existing_object</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="return_by_value.html">return_by_value.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="return_by_value.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_by_value.html#return_by_value-spec">return_by_value</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "return_opaque_pointer.html">return_opaque_pointer.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_opaque_pointer.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "return_opaque_pointer.html#return_opaque_pointer-spec">return_opaque_pointer</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a name="type_conversion">To/From Python Type Conversion</a></h2> + + <dl class="index"> + <dt><a href="extract.html">extract.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="extract.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="extract.html#extract-spec">extract</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="implicit.html">implicit.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="implicit.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "implicit.html#implicitly_convertible-spec">implicitly_convertible</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="lvalue_from_pytype.html">lvalue_from_pytype.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="lvalue_from_pytype.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "lvalue_from_pytype.html#lvalue_from_pytype-spec">lvalue_from_pytype</a></dt> + + <dt><a href= + "lvalue_from_pytype.html#extract_identity-spec">extract_identity</a></dt> + + <dt><a href= + "lvalue_from_pytype.html#extract_member-spec">extract_member</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "opaque.html">opaque_pointer_converter.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "opaque.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "opaque.html#opaque-spec">opaque</a></dt> + </dl> + </dd> + + <dt><a href="opaque.html#macros">Macros</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "opaque.html#BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec"> + BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="to_python_converter.html">to_python_converter.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="to_python_converter.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "to_python_converter.html#to_python_converter-spec">to_python_converter</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href= + "register_ptr_to_python.html">register_ptr_to_python.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "register_ptr_to_python.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "register_ptr_to_python.html#register_ptr_to_python-spec">register_ptr_to_python</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a name="embedding">Embedding</a></h2> + + <dl class="index"> + <dt><a href="exec.html">exec.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="exec.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="exec.html#eval-spec">eval</a></dt> + <dt><a href="exec.html#exec-spec">exec</a></dt> + <dt><a href="exec.html#exec_file-spec">exec_file</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="import.html">import.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="import.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="import.html#import-spec">import</a></dt> + </dl> + </dd> + </dl> + </dd> + </dl> + + <h2><a name="utility">Utility and Infrastructure</a></h2> + + <dl> + <dt><a href="has_back_reference.html">has_back_reference.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="has_back_reference.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "has_back_reference.html#has_back_reference-spec">has_back_reference</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="instance_holder.html">instance_holder.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="instance_holder.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href= + "instance_holder.html#instance_holder-spec">instance_holder</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="pointee.html">pointee.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="pointee.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt>class template <a href= + "pointee.html#pointee-spec">pointee</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="python.html"><boost/python.hpp></a></dt> + + <dt><a href="handle.html">handle.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="handle.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="handle.html#handle-spec">handle</a></dt> + </dl> + </dd> + + <dt><a href="handle.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="handle.html#borrowed-spec">borrowed</a></dt> + + <dt><a href="handle.html#allow_null-spec">allow_null</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="type_id.html">type_id.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="type_id.html#functions">Functions</a></dt> + + <dd> + <dl class="index"> + <dt><a href="type_id.html#type_id-spec">type_id</a></dt> + </dl> + </dd> + + <dt><a href="type_id.html#classes">Classes</a></dt> + + <dd> + <dl class="index"> + <dt><a href="type_id.html#type_info-spec">type_info</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="ssize_t.html">ssize_t.hpp</a></dt> + + <dd> + <dl class="index"> + <dt><a href="ssize_t.html#typedefs">Typedefs</a></dt> + + <dt><a href="ssize_t.html#constants">Constants</a></dt> + </dl> + </dd> + </dl> + + <h2><a name="topics">Topics</a></h2> + + <dl> + <dt><a href="callbacks.html">Calling Python Functions and + Methods</a></dt> + + <dt><a href="pickle.html">Pickle Support</a><br> + <a href="indexing.html">Indexing Support</a></dt> + </dl> + <hr> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 31 October, 2004 +<!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p class="c3">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 +.</p> + </body> +</html> + diff --git a/libs/python/doc/v2/reference_existing_object.html b/libs/python/doc/v2/reference_existing_object.html new file mode 100644 index 000000000..12e228f50 --- /dev/null +++ b/libs/python/doc/v2/reference_existing_object.html @@ -0,0 +1,180 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/reference_existing_object.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/reference_existing_object.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#reference_existing_object-spec">Class + <code>reference_existing_object</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#reference_existing_object-spec-synopsis">Class + <code>reference_existing_object</code> synopsis</a></dt> + + <dt><a href= + "#reference_existing_object-spec-metafunctions">Class + <code>reference_existing_object</code> metafunctions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="reference_existing_object-spec"></a>Class + <code>reference_existing_object</code></h3> + + <p><code>reference_existing_object</code> is a model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> + which can be used to wrap C++ functions which return a reference or + pointer to a C++ object. When the wrapped function is called, the value + referenced by its return value is not copied. A new Python object is + created which contains a pointer to the referent, and no attempt is made + to ensure that the lifetime of the referent is at least as long as that + of the corresponding Python object. Thus, it can be <font color= + "#ff0000"><b>highly dangerous</b></font> to use + <code>reference_existing_object</code> without additional lifetime + management from such models of <a href= + "CallPolicies.html">CallPolicies</a> as <a href= + "with_custodian_and_ward.html#with_custodian_and_ward-spec">with_custodian_and_ward</a>. + This class is used in the implementation of <a href= + "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a>.</p> + + <h4><a name="reference_existing_object-spec-synopsis"></a>Class + <code>reference_existing_object</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct reference_existing_object + { + template <class T> struct apply; + }; +}} +</pre> + + <h4><a name="reference_existing_object-spec-metafunctions"></a>Class + <code>reference_existing_object</code> metafunctions</h4> +<pre> +template <class T> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Requires:</b> <code>T</code> is <code>U&</code> or + <code>U*</code>for some <code>U</code>.</dt> + + <dt><b>Returns:</b> <code>typedef <a href= + "to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a><T,V> + type</code>, where <code>V</code> is a class whose + static <code>execute</code> function constructs an instance + holder containing an <i>unowned</i> + <code>U*</code> pointing to the referent of the wrapped function's + return value.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <p>In C++:</p> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/reference_existing_object.hpp> +#include <boost/python/return_value_policy.hpp> +#include <utility> + +// classes to wrap +struct Singleton +{ + Singleton() : x(0) {} + + int exchange(int n) // set x and return the old value + { + std::swap(n, x); + return n; + } + + int x; +}; + +Singleton& get_it() +{ + static Singleton just_one; + return just_one; +} + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(singleton) +{ + def("get_it", get_it, + return_value_policy<reference_existing_object>()); + + class_<Singleton>("Singleton") + .def("exchange", &Singleton::exchange) + ; +} +</pre> + In Python: +<pre> +>>> import singleton +>>> s1 = singleton.get_it() +>>> s2 = singleton.get_it() +>>> id(s1) == id(s2) # s1 and s2 are not the same object +0 +>>> s1.exchange(42) # but they reference the same C++ Singleton +0 +>>> s2.exchange(99) +42 +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/register_ptr_to_python.html b/libs/python/doc/v2/register_ptr_to_python.html new file mode 100644 index 000000000..5f660e18f --- /dev/null +++ b/libs/python/doc/v2/register_ptr_to_python.html @@ -0,0 +1,162 @@ +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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 - <register_ptr_to_python.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="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Header <register_ptr_to_python.hpp></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="#register_ptr_to_python-spec">register_ptr_to_python</a></dt> + </dl> + + <dt><a href="#examples">Example(s)</a></dt> + +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p> + <code><boost/python/register_ptr_to_python.hpp></code> + supplies <code>register_ptr_to_python</code>, a function template + which registers a conversion for smart pointers to Python. The + resulting Python object holds a copy of the converted smart pointer, + but behaves as though it were a wrapped copy of the pointee. If + the pointee type has virtual functions and the class representing + its dynamic (most-derived) type has been wrapped, the Python object + will be an instance of the wrapper for the most-derived type. More than + one smart pointer type for a pointee's class can be registered. +</p> +<p> + Note that in order to convert a Python <code>X</code> object to a + <code>smart_ptr<X>&</code> (non-const reference), the embedded C++ + object must be held by <code>smart_ptr<X></code>, and that when wrapped + objects are created by calling the constructor from Python, how they are held + is determined by the <code>HeldType</code> parameter to + <code>class_<...></code> instances. +</p> + +<h2><a name="functions"></a>Functions</h2> +<pre> +<a name="register_ptr_to_python-spec">template <class P> +void register_ptr_to_python() +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> <code>P</code> is <a href="Dereferenceable.html#Dereferenceable-concept">Dereferenceable</a>. + </dt> + <dt><b>Effects:</b> Allows conversions to-python of <code>P</code> + instances. + </dt> +</dl> + +<h2><a name="examples"></a>Example(s)</h2> + +<h3>C++ Wrapper Code</h3> + +Here is an example of a module that contains a class <code>A</code> with +virtual functions and some functions that work with +<code>boost::shared_ptr<A></code>. + +<pre> +struct A +{ + virtual int f() { return 0; } +}; + +shared_ptr<A> New() { return shared_ptr<A>( new A() ); } + +int Ok( const shared_ptr<A>& a ) { return a->f(); } + +int Fail( shared_ptr<A>& a ) { return a->f(); } + +struct A_Wrapper: A +{ + A_Wrapper(PyObject* self_): self(self_) {} + int f() { return call_method<int>(self, "f"); } + int default_f() { return A::f(); } + PyObject* self; +}; + +BOOST_PYTHON_MODULE(register_ptr) +{ + class_<A, A_Wrapper>("A") + .def("f", &A::f, &A_Wrapper::default_f) + ; + + def("New", &New); + def("Ok", &Call); + def("Fail", &Fail); + + register_ptr_to_python< shared_ptr<A> >(); +} +</pre> + +<h3>Python Code</h3> + +<pre> +>>> from register_ptr import * +>>> a = A() +>>> Ok(a) # ok, passed as shared_ptr<A> +0 +>>> Fail(a) # passed as shared_ptr<A>&, and was created in Python! +Traceback (most recent call last): + File "<stdin>", line 1, in ? +TypeError: bad argument type for built-in operation +>>> +>>> na = New() # now "na" is actually a shared_ptr<A> +>>> Ok(a) +0 +>>> Fail(a) +0 +>>> +</pre> + +If <code>shared_ptr<A></code> is registered as follows: + +<pre> + class_<A, A_Wrapper, shared_ptr<A> >("A") + .def("f", &A::f, &A_Wrapper::default_f) + ; +</pre> + +There will be an error when trying to convert <code>shared_ptr<A></code> to +<code>shared_ptr<A_Wrapper></code>: + +<pre> +>>> a = New() +Traceback (most recent call last): +File "<stdin>", line 1, in ? +TypeError: No to_python (by-value) converter found for C++ type: class boost::shared_ptr<struct A> +>>> +</pre> + +<p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 24 Jun, 2003 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> +</p> +<p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> + 2002. </i></p> +</body> +</html> + + diff --git a/libs/python/doc/v2/return_arg.html b/libs/python/doc/v2/return_arg.html new file mode 100644 index 000000000..44cd58c24 --- /dev/null +++ b/libs/python/doc/v2/return_arg.html @@ -0,0 +1,224 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st April 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/return_arg.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/return_arg.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="#return_arg-spec">Class Template + <code>return_arg</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_arg-spec-synopsis">Class Template + <code>return_arg</code> synopsis</a></dt> + + <dt><a href="#return_arg-spec-statics">Class + <code>return_arg</code> static functions</a></dt> + </dl> + </dd> + + <dt><a href="#return_self-spec">Class Template + <code>return_self</code></a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + <code>return_arg</code> and <code>return_self</code> instantiations are + models of <a href="CallPolicies.html">CallPolicies</a> which return the + specified argument parameter (usually <code>*this</code>) of a wrapped + (member) function. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="return_arg-spec"></a>Class template + <code>return_arg</code></h3> + + <table border="1" summary="return_arg template parameters"> + <caption> + <b><code>return_arg</code> template parameters</b> + </caption> + + <tr> + <th>Parameter</th> + + <th>Requirements</th> + + <th>Description</th> + + <th>Default</th> + </tr> + + <tr> + <td><code>arg_pos</code></td> + + <td>A positive compile-time constant of type + <code>std::size_t</code>.</td> + + <td>the position of the argument to be returned.</td> + + <td>1</td> + </tr> + + <tr> + <td><code>Base</code></td> + + <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> + + <td>Used for policy composition. Any <code>result_converter</code> it + supplies will be overridden by <code>return_arg</code>, but its + <code>precall</code> and <code>postcall</code> policies are composed + as described here <a href= + "CallPolicies.html#composition">CallPolicies</a>.</td> + + <td><code><a href= + "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code></td> + </tr> + </table> + + <h4><a name="return_arg-spec-synopsis"></a>Class template + <code>return_arg</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <size_t arg_pos=1, class Base = default_call_policies> + struct return_arg : Base + { + static PyObject* postcall(PyObject*, PyObject* result); + struct result_converter{ template <class T> struct apply; }; + template <class Sig> struct extract_return_type : mpl::at_c<Sig, arg_pos>{}; + + }; +}} +</pre> + + <h4><a name="return_arg-spec-statics"></a>Class <code>return_arg</code> + static functions</h4> +<pre> +PyObject* postcall(PyObject* args, PyObject* result); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code><a href= + "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) + != 0</code> and <code>PyTuple_Size(args) != 0</code></dt> + + <dt><b>Returns:</b> <code>PyTuple_GetItem(args,arg_pos-1)</code></dt> + </dl> + + <h3><a name="return_self-spec"></a>Class template + <code>return_self</code></h3> + + <h4>Class template <code>return_self</code> synopsis:</h4> +<pre> +namespace boost { namespace python +{ + template <class Base = default_call_policies> + struct return_self + : return_arg<1,Base> + {}; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/return_arg.hpp> + +struct Widget +{ + Widget() :sensitive_(true){} + bool get_sensitive() const { return sensitive_; } + void set_sensitive(bool s) { this->sensitive_ = s; } + private: + bool sensitive_; +}; + +struct Label : Widget +{ + Label() {} + + std::string get_label() const { return label_; } + void set_label(const std::string &l){ label_ = l; } + + private: + std::string label_; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(return_self_ext) +{ + class_<widget>("Widget") + .def("sensitive", &Widget::get_sensitive) + .def("sensitive", &Widget::set_sensitive, return_self<>()) + ; + + class_<Label, bases<Widget> >("Label") + .def("label", &Label::get_label) + .def("label", &Label::set_label, return_self<>()) + ; +} + + +</pre> + + <h3>Python code</h3> +<pre> +>>> from return_self_ext import * +>>> l1 = Label().label("foo").sensitive(false) +>>> l2 = Label().sensitive(false).label("foo") +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 19 July, 2003 <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> and Nikolay + Mladenov 2003. </i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/return_by_value.html b/libs/python/doc/v2/return_by_value.html new file mode 100644 index 000000000..12ca3c43f --- /dev/null +++ b/libs/python/doc/v2/return_by_value.html @@ -0,0 +1,149 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/return_by_value.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/return_by_value.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_by_value-spec">Class + <code>return_by_value</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_by_value-spec-synopsis">Class + <code>return_by_value</code> synopsis</a></dt> + + <dt><a href="#return_by_value-spec-metafunctions">Class + <code>return_by_value</code> metafunctions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="return_by_value-spec"></a>Class + <code>return_by_value</code></h3> + + <p><code>return_by_value</code> is a model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> + which can be used to wrap C++ functions returning any reference or value + type such that the return value is copied into a new Python object.</p> + + <h4><a name="return_by_value-spec-synopsis"></a>Class + <code>return_by_value</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct return_by_value + { + template <class T> struct apply; + }; +}} +</pre> + + <h4><a name="return_by_value-spec-metafunctions"></a>Class + <code>return_by_value</code> metafunctions</h4> +<pre> +template <class T> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Returns:</b> <code>typedef <a href= + "to_python_value.html#to_python_value-spec">to_python_value</a><T> + type;</code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ Module Definition</h3> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/return_by_value.hpp> +#include <boost/python/return_value_policy.hpp> + +// classes to wrap +struct Bar { }; + +Bar global_bar; + +// functions to wrap: +Bar b1(); +Bar& b2(); +Bar const& b3(); + +// Wrapper code +using namespace boost::python; +template <class R> +void def_void_function(char const* name, R (*f)()) +{ + def(name, f, return_value_policy<return_by_value>()); +} + +BOOST_PYTHON_MODULE(my_module) +{ + class_<Bar>("Bar"); + def_void_function("b1", b1); + def_void_function("b2", b2); + def_void_function("b3", b3); +} +</pre> + + <h3>Python Code</h3> +<pre> +>>> from my_module import * +>>> b = b1() # each of these calls +>>> b = b2() # creates a brand +>>> b = b3() # new Bar object +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/return_internal_reference.html b/libs/python/doc/v2/return_internal_reference.html new file mode 100644 index 000000000..87c33f855 --- /dev/null +++ b/libs/python/doc/v2/return_internal_reference.html @@ -0,0 +1,230 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/return_internal_reference.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/return_internal_reference.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="#return_internal_reference-spec">Class Template + <code>return_internal_reference</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_internal_reference-spec-synopsis">Class + Template <code>return_internal_reference</code> + synopsis</a></dt> + + <dt><a href="#return_internal_reference-spec-statics">Class + <code>return_internal_reference</code> static + functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + <code>return_internal_reference</code> instantiations are models of <a + href="CallPolicies.html">CallPolicies</a> which allow pointers and + references to objects held internally by a free or member function + argument or from the target of a member function to be returned safely + without making a copy of the referent. The default for its first template + argument handles the common case where the containing object is the + target (<code>*this</code>) of a wrapped member function. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="return_internal_reference-spec"></a>Class template + <code>return_internal_reference</code></h3> + + <table border="1" summary= + "return_internal_reference template parameters"> + <caption> + <b><code>return_internal_reference</code> template parameters</b> + </caption> + + <tr> + <th>Parameter</th> + + <th>Requirements</th> + + <th>Description</th> + + <th>Default</th> + </tr> + + <tr> + <td><code>owner_arg</code></td> + + <td>A positive compile-time constant of type + <code>std::size_t</code>.</td> + + <td>The index of the parameter which contains the object to which the + reference or pointer is being returned. If used to wrap a member + function, parameter 1 is the target object (<code>*this</code>). Note + that if the target Python object type doesn't support weak + references, a Python <code>TypeError</code> exception will be raised + when the function being wrapped is called.</td> + + <td>1</td> + </tr> + + <tr> + <td><code>Base</code></td> + + <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> + + <td>Used for policy composition. Any <code>result_converter</code> it + supplies will be overridden by + <code>return_internal_reference</code>, but its <code>precall</code> + and <code>postcall</code> policies are composed as described here <a + href="CallPolicies.html#composition">CallPolicies</a>.</td> + + <td><code><a href= + "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code></td> + </tr> + </table> + + <h4><a name="return_internal_reference-spec-synopsis"></a>Class template + <code>return_internal_reference</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <std::size_t owner_arg = 1, class Base = default_call_policies> + struct return_internal_reference : Base + { + static PyObject* postcall(PyObject*, PyObject* result); + typedef <a href= +"reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter; + }; +}} +</pre> + + <h4><a name="return_internal_reference-spec-statics"></a>Class + <code>return_internal_reference</code> static functions</h4> +<pre> +PyObject* postcall(PyObject* args, PyObject* result); +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code><a href= + "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) + != 0</code></dt> + + <dt><b>Returns:</b> <code><a href= + "with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec-statics"> + with_custodian_and_ward_postcall::postcall(args, + result)</a></code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/return_internal_reference.hpp> + +class Bar +{ + public: + Bar(int x) : x(x) {} + int get_x() const { return x; } + void set_x(int x) { this->x = x; } + private: + int x; +}; + +class Foo +{ + public: + Foo(int x) : b(x) {} + + // Returns an internal reference + Bar const& get_bar() const { return b; } + + private: + Bar b; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE(internal_refs) +{ + class_<Bar>("Bar", init<int>()) + .def("get_x", &Bar::get_x) + .def("set_x", &Bar::set_x) + ; + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_internal_reference<>()) + ; +} +</pre> + + <h3>Python code</h3> +<pre> +>>> from internal_refs import * +>>> f = Foo(3) +>>> b1 = f.get_bar() +>>> b2 = f.get_bar() +>>> b1.get_x() +3 +>>> b2.get_x() +3 +>>> b1.set_x(42) +>>> b2.get_x() +42 +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/return_opaque_pointer.html b/libs/python/doc/v2/return_opaque_pointer.html new file mode 100644 index 000000000..52d8396e8 --- /dev/null +++ b/libs/python/doc/v2/return_opaque_pointer.html @@ -0,0 +1,192 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/return_opaque_pointer.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/return_opaque_pointer.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_opaque_pointer-spec">Class + <code>return_opaque_pointer</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_opaque_pointer-spec-synopsis">Class + <code>return_opaque_pointer</code> synopsis</a></dt> + + <dt><a href="#return_opaque_pointer-spec-metafunctions">Class + <code>return_opaque_pointer</code> metafunctions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + + <dt><a href="#see-also">See Also</a></dt> + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="return_opaque_pointer-spec"></a>Class + <code>return_opaque_pointer</code></h3> + + <p><code>return_opaque_pointer</code> is a model of + <a href="ResultConverter.html#ResultConverterGenerator-concept"> + ResultConverterGenerator</a> + which can be used to wrap C++ functions returning pointers to + undefined types such that the return value is copied into a + new Python object.</p> + <p>In addition to specifying the <code>return_opaque_pointer</code> + policy the <a href="opaque.html#BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID-spec"> + <code>BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID</code></a> macro must be + used to define specializations for the + <a href="type_id.html#type_id-spec">type_id</a> function + on the type pointed to by returned pointer.</p> + + <h4><a name="return_opaque_pointer-spec-synopsis"></a>Class + <code>return_opaque_pointer</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + struct return_opaque_pointer + { + template <class R> struct apply; + }; +}} +</pre> + + <h4><a name="return_opaque_pointer-spec-metafunctions"></a>Class + <code>return_opaque_pointer</code> metafunctions</h4> +<pre> +template <class R> struct apply +</pre> + + <dl class="metafunction-semantics"> + <dt><b>Returns:</b> <code>typedef + detail::opaque_conversion_holder<R> + type;</code></dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ Module Definition</h3> +<pre> +# include <boost/python/return_opaque_pointer.hpp> +# include <boost/python/def.hpp> +# include <boost/python/module.hpp> +# include <boost/python/return_value_policy.hpp> + +typedef struct opaque_ *opaque; + +opaque the_op = ((opaque) 0x47110815); + +opaque get () { return the_op; } +void use (opaque op) { + if (op != the_op) + throw std::runtime_error (std::string ("failed")); +} + +void failuse (opaque op) { + if (op == the_op) + throw std::runtime_error (std::string ("success")); +} + +BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(opaque_) + +namespace bpl = boost::python; + +BOOST_PYTHON_MODULE(opaque_ext) +{ + bpl::def ( + "get", &::get, bpl::return_value_policy<bpl::return_opaque_pointer>()); + bpl::def ("use", &::use); + bpl::def ("failuse", &::failuse); +} +</pre> + + <h3>Python Code</h3> +<pre> +""" +>>> from opaque_ext import * +>>> # +>>> # Check for correct conversion +>>> use(get()) +>>> failuse(get()) +Traceback (most recent call last): + ... +RuntimeError: success +>>> # +>>> # Check that there is no conversion from integers ... +>>> use(0) +Traceback (most recent call last): + ... +TypeError: bad argument type for built-in operation +>>> # +>>> # ... and from strings to opaque objects +>>> use("") +Traceback (most recent call last): + ... +TypeError: bad argument type for built-in operation +""" +def run(args = None): + import sys + import doctest + + if args is not None: + sys.argv = args + return doctest.testmod(sys.modules.get(__name__)) + +if __name__ == '__main__': + print "running..." + import sys + sys.exit(run()[0]) +</pre> + + <h2><a name="see-also"></a>See Also</h2> + <p> + <a href="opaque.html"> + opaque</a> + </p> + + <p>Revised + 28 January, 2003 + </p> + + <p><i>© Copyright 2003 Haufe Mediengruppe. All Rights + Reserved.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/return_value_policy.html b/libs/python/doc/v2/return_value_policy.html new file mode 100644 index 000000000..b02d4bc39 --- /dev/null +++ b/libs/python/doc/v2/return_value_policy.html @@ -0,0 +1,167 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/return_value_policy.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/return_value_policy.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="#return_value_policy-spec">Class Template + <code>return_value_policy</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#return_value_policy-spec-synopsis">Class Template + <code>return_value_policy</code> synopsis</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + <code>return_value_policy</code> instantiations are simply models of <a + href="CallPolicies.html">CallPolicies</a> which are composed of a <a + href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> + and optional <code>Base</code> <a href= + "CallPolicies.html">CallPolicies</a>. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="return_value_policy-spec"></a>Class template + <code>return_value_policy</code></h3> + + <table border="1" summary="return_value_policy template parameters"> + <caption> + <b><code>return_value_policy</code> template parameters</b> + </caption> + + <tr> + <th>Parameter</th> + + <th>Requirements</th> + + <th>Default</th> + </tr> + + <tr> + <td><a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a></td> + + <td>A model of <a href= + "ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.</td> + </tr> + + <tr> + <td><code>Base</code></td> + + <td>A model of <a href="CallPolicies.html">CallPolicies</a></td> + + <td><code><a href= + "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code></td> + </tr> + </table> + + <h4><a name="return_value_policy-spec-synopsis"></a>Class template + <code>return_value_policy</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class ResultConverterGenerator, class Base = default_call_policies> + struct return_value_policy : Base + { + typedef ResultConverterGenerator result_converter; + }; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> + + <h3>C++ Module Definition</h3> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/copy_const_reference.hpp> +#include <boost/python/return_value_policy.hpp> + +// classes to wrap +struct Bar { int x; } + +struct Foo { + Foo(int x) : { b.x = x; } + Bar const& get_bar() const { return b; } + private: + Bar b; +}; + +// Wrapper code +using namespace boost::python; +BOOST_PYTHON_MODULE(my_module) +{ + class_<Bar>("Bar"); + + class_<Foo>("Foo", init<int>()) + .def("get_bar", &Foo::get_bar + , return_value_policy<copy_const_reference>()) + ; +} +</pre> + + <h3>Python Code</h3> +<pre> +>>> from my_module import * +>>> f = Foo(3) # create a Foo object +>>> b = f.get_bar() # make a copy of the internal Bar object +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/scope.html b/libs/python/doc/v2/scope.html new file mode 100644 index 000000000..54ef67e3e --- /dev/null +++ b/libs/python/doc/v2/scope.html @@ -0,0 +1,173 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/scope.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/scope.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="#scope-spec">Class <code>scope</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#scope-spec-synopsis">Class <code>scope</code> + synopsis</a></dt> + + <dt><a href="#scope-spec-ctors">Class <code>scope</code> + constructors and destructor</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Defines facilities for querying and controlling the Python scope + (namespace) which will contain new wrapped classes and functions.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="scope-spec"></a>Class <code>scope</code></h3> + + <p>The <code>scope</code> class has an associated global Python + object which controls the Python namespace in which new extension + classes and wrapped functions will be defined as + attributes. Default-constructing a new <code>scope</code> object + binds it to the associated global Python object. Constructing a + <code>scope</code> object with an argument changes the associated + global Python object to the one held by the argument, until the + lifetime of the <code>scope</code> object ends, at which time the + associated global Python object reverts to what it was before the + <code>scope</code> object was constructed.</p> + + <h4><a name="scope-spec-synopsis"></a>Class <code>scope</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class scope : public <a href= +"object.html#object-spec">object</a> + { + public: + scope(scope const&); + scope(object const&); + scope(); + ~scope() + private: + void operator=(scope const&); + }; +}} +</pre> + + <h4><a name="scope-spec-ctors"></a>Class <code>scope</code> constructors + and destructor</h4> +<pre> +explicit scope(scope const& x); +explicit scope(object const& x); +</pre> + Stores a reference to the current associated scope object, and sets the + associated scope object to the one referred to by <code>x.ptr()</code>. + The <code>object</code> base class is initialized with <code>x</code>. +<pre> +scope(); +</pre> + Stores a reference to the current associated scope object. The + <code>object</code> base class is initialized with the current associated + scope object. Outside any module initialization function, the current + associated Python object is <code>None</code>. +<pre> +~scope() +</pre> + Sets the current associated Python object to the stored object. + + <h2><a name="examples"></a>Example</h2> + The following example shows how scope setting can be used to define + nested classes. + + <p>C++ Module definition:</p> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/scope.hpp> +using namespace boost::python; + +struct X +{ + void f() {} + + struct Y { int g() { return 42; } }; +}; + +BOOST_PYTHON_MODULE(nested) +{ + // add some constants to the current (module) scope + scope().attr("yes") = 1; + scope().attr("no") = 0; + + // Change the current scope + scope outer + = class_<X>("X") + .def("f", &X::f) + ; + + // Define a class Y in the current scope, X + class_<X::Y>("Y") + .def("g", &X::Y::g) + ; +} +</pre> + Interactive Python: +<pre> +>>> import nested +>>> nested.yes +1 +>>> y = nested.X.Y() +>>> y.g() +42 +</pre> + + <p>Revised 09 October, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/slice.html b/libs/python/doc/v2/slice.html new file mode 100644 index 000000000..fb6b47c7e --- /dev/null +++ b/libs/python/doc/v2/slice.html @@ -0,0 +1,246 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/slice.hpp></title> +</head> +<body> +<table border="0" cellpadding="7" cellspacing="0" width="100%" + summary="header"> + <tbody> + <tr> + <td valign="top" width="300"> + <h3><a href="../../../../index.htm"><img height="86" width="277" + alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3> + </td> + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + <h2 align="center">Header <boost/python/slice.hpp></h2> + </td> + </tr> + </tbody> +</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="#slice-spec">Class <code>slice</code></a></dt> + <dd> + <dl class="page-index"> + <dt><a href="#slice-spec-synopsis">Class <code>slice</code> +synopsis</a></dt> + <dt><a href="#slice-spec-ctors">Class <code>slice</code> +constructors</a></dt> + <dt><a href="#slice-spec-observers">Class <code>slice</code> +observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + <dt><a href="#examples">Example(s)</a></dt> +</dl> +<hr> +<h2><a name="introduction"></a>Introduction</h2> +<p>Exposes a <a href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> +for the Python <a + href="http://www.python.org/doc/2.3.3/api/slice-objects.html">slice</a> +type.</p> +<h2><a name="classes"></a>Classes</h2> +<h3><a name="slice-spec"></a>Class <code>slice</code></h3> +<p>Exposes the extended slicing protocol by wrapping the built-in slice +type. The semantics of the constructors and member functions defined +below can be fully understood by reading the <a + href="ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept +definition. Since <code>slice</code> is publicly derived from <code><a + href="object.html#object-spec">object</a></code>, the public object +interface applies to <code>slice</code> instances as well.<br> +</p> +<h4><a name="slice-spec-synopsis"></a>Class <code>slice</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + class slice : public object + { + public: + slice(); // create an empty slice, equivalent to [::] + + template <typename Int1, typename Int2> + slice(Int1 start, Int2 stop); + + template <typename Int1, typename Int2, typename Int3> + slice(Int1 start, Int2 stop, Int3 step); + + // Access the parameters this slice was created with. + object start(); + object stop(); + object step(); + + // The return type of slice::get_indices() + template <typename RandomAccessIterator> + struct range + { + RandomAccessIterator start; + RandomAccessIterator stop; + int step; + }; + + template <typename RandomAccessIterator> + range<RandomAccessIterator> + get_indices( + RandomAccessIterator const& begin, + RandomAccessIterator const& end); + }; +}} +</pre> +<h4><a name="slice-spec-ctors"></a>Class <code>slice</code> +constructors<br> +</h4> +<pre>slice();<br></pre> +<dl class="function-semantics"> + <dt><b>Effects:</b> constructs a <code>slice</code> with default stop, start, and +step values. Equivalent to the slice object created as part of the Python +expression <code>base[::].</code></dt> + <dt><b>Throws:</b> nothing.</dt> +</dl> +<pre> +template <typename Int1, typename Int2> +slice(Int1 start, Int2 stop); +</pre> +<dl class="function-semantics"> + <dt><b>Requires:</b> <code>start</code>, <code>stop</code>, and <code>step</code> + are of type <code><a href="object.html#slice_nil-spec">slice_nil</a></code> + or convertible to type <code>object</code>.</dt> + <dt><b>Effects:</b> constructs a new slice with default step value +and the provided start and stop values. Equivalent to the slice +object +created by the built-in Python function <code><a + href="http://www.python.org/doc/current/lib/built-in-funcs.html#12h-62">slice(start,stop)</a></code>, +or as part of the Python expression <code>base[start:stop]</code>.</dt> + <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python <code>TypeError</code> +exception if no conversion is possible from the arguments to type <code>object</code>.</dt> +</dl> +<pre> +template <typename Int1, typename Int2, typename Int3> +slice(Int1 start, Int2 stop, Int3 step); +</pre> + <dt><b>Requires:</b> <code>start</code>, <code>stop</code>, and <code>step</code> are <code>slice_nil</code> or convertible to type <code>object</code>.</dt> + <dt><b>Effects:</b> constructs a new slice with start stop and step +values. Equivalent to the slice object created +by the built-in Python function <code><a + href="http://www.python.org/doc/current/lib/built-in-funcs.html">slice(start,stop,step)</a></code>, +or as part of the Python expression <code>base[start:stop:step]</code>.</dt> + <dt><b>Throws:</b> <code>error_already_set</code> and sets a Python <code>TypeError</code> +exception if no conversion is possible from the arguments to type +object.</dt> +<h4><a name="slice-spec-observers"></a>Class <code>slice</code> +observer functions<br> +</h4> +<pre> +object slice::start() const; +object slice::stop() const; +object slice::step() const; +</pre> +<dl class="function-semantics"> + <dt><b>Effects:</b> None.</dt> + <dt><b>Throws:</b> nothing.</dt> + <dt><b>Returns:</b>the parameter that +the slice was created with. If the parameter was omitted or +slice_nil was used when the slice was created, than that parameter will +be a reference to PyNone and compare equal to a default-constructed +object. In principal, any object may be used when creating a +slice object, but in practice they are usually integers.</dt> +</dl> +<br> +<pre> +template <typename RandomAccessIterator> +slice::range<RandomAccessIterator> +slice::get_indices( + RandomAccessIterator const& begin, + RandomAccessIterator const& end) const; +</pre> +<dl class="function-semantics"> + <dt><b>Arguments:</b> A pair of STL-conforming Random Access +Iterators that form a half-open range.</dt> + <dt><b>Effects:</b> Create a RandomAccessIterator pair that defines a +fully-closed range within the [begin,end) range of its arguments. +This function translates this slice's indices while accounting for the +effects of any PyNone or negative indices, and non-singular step sizes.</dt> + <dt><b>Returns:</b> a slice::range +that has been initialized with a non-zero value of step and a pair of +RandomAccessIterators that point within the range of this functions +arguments and define a closed interval.</dt> + <dt><b>Throws:</b> <a href="definitions.html#raise">Raises</a> a Python <code>TypeError</code> exception if any of this slice's arguments +are neither references to <code>PyNone</code> nor convertible to <code>int</code>. Throws +<code>std::invalid_argument</code> if the resulting range would be empty. You +should always wrap calls to <code>slice::get_indices()</code> +within <code>try { ...; } catch (std::invalid_argument) {}</code> to +handle this case and take appropriate action.</dt> + <dt><b>Rationale</b>: closed-interval: If +an open interval were used, then for step +size other than 1, the required state for the end iterator would point +beyond the one-past-the-end position or before the beginning of the +specified range.<br> +exceptions on empty slice: It is impossible to define a closed interval +over an empty range, so some other form of error checking would have to +be used to prevent undefined behavior. In the case where the +exception is not caught, it will simply be translated to Python by the +default exception handling mechanisms. </dt> +</dl> +<h2><a name="examples"></a><b>Examples</b></h2> +<pre> +using namespace boost::python; + +// Perform an extended slice of a Python list. +// Warning: extended slicing was not supported for built-in types prior +// to Python 2.3 +list odd_elements(list l) +{ + return l[slice(_,_,2)]; +} + +// Perform a multidimensional extended slice of a Numeric.array +numeric::array even_columns(numeric::array arr) +{ + // select every other column, starting with the second, of a 2-D array. + // Equivalent to "return arr[:, 1::2]" in Python. + return arr[make_tuple( slice(), slice(1,_,2))]; +} + +// Perform a summation over a slice of a std::vector. +double partial_sum(std::vector<double> const& Foo, const slice index) +{ + slice::range<std::vector<double>::const_iterator> bounds; + try { + bounds = index.get_indices<>(Foo.begin(), Foo.end()); + } + catch (std::invalid_argument) { + return 0.0; + } + double sum = 0.0; + while (bounds.start != bounds.stop) { + sum += *bounds.start; + std::advance( bounds.start, bounds.step); + } + sum += *bounds.start; + return sum; +} +</pre> +<p>Revised 07 Febuary, 2004</p> +<p><i>© Copyright <a + href="mailto:jbrandmeyer@users.sourceforge.net">Jonathan Brandmeyer</a>, +2004. Modification, copying and redistribution of this document +is permitted under the terms and conditions of the Boost Software +License, version 1.0.<br> +</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/ssize_t.html b/libs/python/doc/v2/ssize_t.html new file mode 100644 index 000000000..cb4398bb5 --- /dev/null +++ b/libs/python/doc/v2/ssize_t.html @@ -0,0 +1,96 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- Copyright Ralf W. Grosse-Kunstleve 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> + +<html> +<head> + <meta name="generator" content= + "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - <boost/python/ssize_t.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="../../../../boost.png" border= + "0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href= + "../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/ssize_t.hpp></h2> + </td> + </tr> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a></dt> + + <dt><a href="#typdefs">Typedef</a></dt> + + <dt><a href="#macros">Constants</a></dt> + </dl> + <hr> + + <h2><a name="introduction" id= + "introduction"></a>Introduction</h2> + + <p>Python 2.5 introduces a new <tt>Py_ssize_t</tt> typedef and + two related macros (<a href= + "http://www.python.org/dev/peps/pep-0353/">PEP 353</a>). The + <tt><boost/python/ssize_t.hpp></tt> header imports these + definitions into the <tt>boost::python</tt> namespace as + <tt>ssize_t</tt>, <tt>ssize_t_max</tt>, and <tt>ssize_t_min</tt>. + Appropriate definitions are provided for backward compatibility + with previous Python versions.</p> + + <h2><a name="typedefs" id="typedefs"></a>Typedefs</h2>Imports + <tt>Py_ssize_t</tt> into the <tt>boost::python</tt> namespace if + available, or provides an appropriate typedef for backward + compatibility: + <pre> +#if PY_VERSION_HEX >= 0x02050000 +typedef Py_ssize_t ssize_t; +#else +typedef int ssize_t; +#endif +</pre> + + <h2><a name="constants" id="constants"></a>Constants</h2>Imports + <tt>PY_SSIZE_T_MAX</tt> and <tt>PY_SSIZE_T_MIN</tt> as constants + into the <tt>boost::python</tt> namespace if available, or + provides appropriate constants for backward compatibility: + <pre> +#if PY_VERSION_HEX >= 0x02050000 +ssize_t const ssize_t_max = PY_SSIZE_T_MAX; +ssize_t const ssize_t_min = PY_SSIZE_T_MIN; +#else +ssize_t const ssize_t_max = INT_MAX; +ssize_t const ssize_t_min = INT_MIN; +#endif +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 25 September, 2006 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --></p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/ralf_w_grosse_kunstleve.htm">Ralf W. + Grosse-Kunstleve</a> 2006.</i></p> +</body> +</html> diff --git a/libs/python/doc/v2/stl_iterator.html b/libs/python/doc/v2/stl_iterator.html new file mode 100644 index 000000000..ef197b0f8 --- /dev/null +++ b/libs/python/doc/v2/stl_iterator.html @@ -0,0 +1,273 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + + <title>Boost.Python - <boost/python/stl_iterator.hpp></title> + <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"> + </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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/stl_iterator.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="#stl_input_iterator-spec">Class template + <code>stl_input_iterator</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#stl_input_iterator-spec-synopsis">Class + <code>stl_input_iterator</code> synopsis</a></dt> + + <dt><a href="#stl_input_iterator-spec-constructors">Class template + <code>stl_input_iterator</code> constructors</a></dt> + + <dt><a href="#stl_input_iterator-spec-modifiers">Class template + <code>stl_input_iterator</code> modifiers</a></dt> + + <dt><a href="#stl_input_iterator-spec-observers">Class template + <code>stl_input_iterator</code> observers</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Examples</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/stl_iterator.hpp></code> provides types + for creating <a href="http://www.sgi.com/tech/stl/Iterators.html">C++ + Iterators</a> from <a href="http://www.python.org/doc/current/lib/typeiter.html"> + Python iterables</a>.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="stl_input_iterator-spec"></a>Class Template + <code>stl_input_iterator</code></h3> + + <p>Instances of <code>stl_input_iterator<T></code> hold a Python + iterator and adapt it for use with STL algorithms. + <code>stl_input_iterator<T></code> satisfies the requirements for + an <a href="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>. + </p> + + <table border="1" summary="stl_input_iterator template parameters"> + <tr> + <th>Template Parameter</th> + + <th>Requirements</th> + + <th>Semantics</th> + + <th>Default</th> + </tr> + + <tr> + <td><code>ValueType</code></td> + + <td><code>ValueType</code> must be CopyConstructible.</td> + + <td>Dereferencing an instance of <code>stl_input_iterator<ValueType></code> + will return an rvalue of type <code>ValueType</code>.</td> + + <td><i>None</i></td> + </tr> + </table> + + <h4><a name="stl_input_iterator-spec-synopsis"></a>Class Template stl_input_iterator + synopsis</h4> + +<pre> +namespace boost { namespace python +{ + template <class ValueType> + struct stl_input_iterator + { + typedef std::ptrdiff_t difference_type; + typedef ValueType value_type; + typedef ValueType* pointer; + typedef ValueType reference; + typedef std::input_iterator_tag iterator_category; + + stl_input_iterator(); + stl_input_iterator(<a href="object.html#object-spec">object</a> const& ob); + + stl_input_iterator& operator++(); + stl_input_iterator operator++(int); + + ValueType operator*() const; + + friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs); + friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs); + private: + <a href="object.html#object-spec">object</a> it; // For exposition only + <a href="object.html#object-spec">object</a> ob; // For exposition only + }; +}} +</pre> + + <h4> + <a name="stl_input_iterator-spec-constructors"></a>Class Template <code>stl_input_iterator</code> + constructors + </h4> + +<pre> +stl_input_iterator() +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + Creates a past-the-end input iterator, useful for signifying the end of a sequence. + </dt> + <dt><b>Postconditions:</b> <code>this</code> is past-the-end.</dt> + <dt><b>Throws:</b> Nothing.</dt> + </dl> + +<pre> +stl_input_iterator(object const& ob) +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + Calls <code>ob.attr("__iter__")()</code> and stores the resulting Python iterator + object in <code>this->it</code>. Then, calls <code>this->it.attr("next")()</code> and + stores the result in <code>this->ob</code>. If the sequence is exhausted, sets + <code>this->ob</code> to <code>object()</code>. + </dt> + + <dt><b>Postconditions:</b> <code>this</code> is a dereferenceable or past-the-end.</dt> + </dl> + + <h4> + <a name="stl_input_iterator-spec-modifiers"></a>Class Template <code>stl_input_iterator</code> + modifiers + </h4> + +<pre> +stl_input_iterator& operator++() +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + Calls <code>this->it.attr("next")()</code> and stores the result in + <code>this->ob</code>. If the sequence is exhausted, sets <code>this->ob</code> + to <code>object()</code>. + </dt> + + <dt><b>Postconditions:</b> <code>this</code> is a dereferenceable or past-the-end.</dt> + + <dt><b>Returns:</b> <code>*this</code>.</dt> + </dl> + +<pre> +stl_input_iterator operator++(int) +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + <code>stl_input_iterator tmp = *this; ++*this; return tmp;</code> + </dt> + + <dt><b>Postconditions:</b> <code>this</code> is a dereferenceable or past-the-end.</dt> + </dl> + + <h4><a name="stl_input_iterator-spec-observers"></a>Class Template<code>stl_input_iterator</code> + observers</h4> + +<pre> +ValueType operator*() const +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + Returns the current element in the sequence. + </dt> + <dt><b>Returns:</b> + <code>extract<ValueType>(this->ob);</code> + </dt> + </dl> + +<pre> +friend bool operator==(stl_input_iterator const& lhs, stl_input_iterator const& rhs) +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + Returns true if both iterators are dereferenceable or if both iterators are past-the-end, + false otherwise. + </dt> + <dt><b>Returns:</b> + <code>(lhs.ob == object()) == (rhs.ob == object())</code> + </dt> + </dl> + +<pre> +friend bool operator!=(stl_input_iterator const& lhs, stl_input_iterator const& rhs) +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> + Returns false if both iterators are dereferenceable or if both iterators are past-the-end, + true otherwise. + </dt> + <dt><b>Returns:</b> + <code>!(lhs == rhs)</code> + </dt> + </dl> + + <h2><a name="examples"></a>Examples</h2> +<pre> +#include <boost/python/object.hpp> +#include <boost/python/stl_iterator.hpp> + +#include <list> + +using namespace boost::python; +std::list<int> sequence_to_int_list(object const& ob) +{ + stl_input_iterator<int> begin(ob), end; + return std::list<int>(begin, end); +} +</pre> + +<hr> + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->30 +October, 2005 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright Eric Niebler 2005.</i></p> + </body> +</html>
\ No newline at end of file diff --git a/libs/python/doc/v2/str.html b/libs/python/doc/v2/str.html new file mode 100644 index 000000000..11810d841 --- /dev/null +++ b/libs/python/doc/v2/str.html @@ -0,0 +1,237 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/str.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/str.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="#str-spec">Class <code>str</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#str-spec-synopsis">Class <code>str</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>Exposes a <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python + <a href= + "http://www.python.org/dev/doc/devel/lib/string-methods.html">str</a> + type.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="str-spec"></a>Class <code>str</code></h3> + + <p>Exposes the <a href= + "http://www.python.org/dev/doc/devel/lib/string-methods.html">string + methods</a> of Python's built-in <code>str</code> type. The + semantics of the constructors and member functions defined below, + except for the two-argument constructors which construct str + objects from a range of characters, can be fully understood by + reading the <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept + definition. Since <code>str</code> is publicly derived from + <code><a href="object.html#object-spec">object</a></code>, the + public object interface applies to <code>str</code> instances as + well.</p> + + <h4><a name="str-spec-synopsis"></a>Class <code>str</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class str : public object + { + public: + str(); // new str + + str(char const* s); // new str + + str(char const* start, char const* finish); // new str + str(char const* start, std::size_t length); // new str + + template <class T> + explicit str(T const& other); + + str capitalize() const; + + template <class T> + str center(T const& width) const; + + template<class T> + long count(T const& sub) const; + template<class T1, class T2> + long count(T1 const& sub,T2 const& start) const; + template<class T1, class T2, class T3> + long count(T1 const& sub,T2 const& start, T3 const& end) const; + + object decode() const; + template<class T> + object decode(T const& encoding) const; + template<class T1, class T2> + object decode(T1 const& encoding, T2 const& errors) const; + + object encode() const; + template <class T> + object encode(T const& encoding) const; + template <class T1, class T2> + object encode(T1 const& encoding, T2 const& errors) const; + + template <class T> + bool endswith(T const& suffix) const; + template <class T1, class T2> + bool endswith(T1 const& suffix, T2 const& start) const; + template <class T1, class T2, class T3> + bool endswith(T1 const& suffix, T2 const& start, T3 const& end) const; + + str expandtabs() const; + template <class T> + str expandtabs(T const& tabsize) const; + + template <class T> + long find(T const& sub) const; + template <class T1, class T2> + long find(T1 const& sub, T2 const& start) const; + template <class T1, class T2, class T3> + long find(T1 const& sub, T2 const& start, T3 const& end) const; + + template <class T> + long index(T const& sub) const; + template <class T1, class T2> + long index(T1 const& sub, T2 const& start) const; + template <class T1, class T2, class T3> + long index(T1 const& sub, T2 const& start, T3 const& end) const; + + bool isalnum() const; + bool isalpha() const; + bool isdigit() const; + bool islower() const; + bool isspace() const; + bool istitle() const; + bool isupper() const; + + template <class T> + str join(T const& sequence) const; + + template <class T> + str ljust(T const& width) const; + + str lower() const; + str lstrip() const; + + template <class T1, class T2> + str replace(T1 const& old, T2 const& new_) const; + template <class T1, class T2, class T3> + str replace(T1 const& old, T2 const& new_, T3 const& maxsplit) const; + + template <class T> + long rfind(T const& sub) const; + template <class T1, class T2> + long rfind(T1 const& sub, T2 const& start) const; + template <class T1, class T2, class T3> + long rfind(T1 const& sub, T2 const& start, T3 const& end) const; + + template <class T> + long rindex(T const& sub) const; + template <class T1, class T2> + long rindex(T1 const& sub, T2 const& start) const; + template <class T1, class T2, class T3> + long rindex(T1 const& sub, T2 const& start, T3 const& end) const; + + template <class T> + str rjust(T const& width) const; + + str rstrip() const; + + list split() const; + template <class T> + list split(T const& sep) const; + template <class T1, class T2> + list split(T1 const& sep, T2 const& maxsplit) const; + + list splitlines() const; + template <class T> + list splitlines(T const& keepends) const; + + template <class T> + bool startswith(T const& prefix) const; + template <class T1, class T2> + bool startswidth(T1 const& prefix, T2 const& start) const; + template <class T1, class T2, class T3> + bool startswidth(T1 const& prefix, T2 const& start, T3 const& end) const; + + str strip() const; + str swapcase() const; + str title() const; + + template <class T> + str translate(T const& table) const; + template <class T1, class T2> + str translate(T1 const& table, T2 const& deletechars) const; + + str upper() const; + }; +}} +</pre> + + <h2><a name="examples"></a>Example</h2> +<pre> +using namespace boost::python; +str remove_angle_brackets(str x) +{ + return x.strip('<').strip('>'); +} +</pre> + + <p>Revised 3 October, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/to_python_converter.html b/libs/python/doc/v2/to_python_converter.html new file mode 100644 index 000000000..81b61d252 --- /dev/null +++ b/libs/python/doc/v2/to_python_converter.html @@ -0,0 +1,227 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/to_python_converter.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/to_python_converter.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="#to_python_converter-spec">Class Template + <code>to_python_converter</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#to_python_converter-spec-synopsis">Class Template + <code>to_python_converter</code> synopsis</a></dt> + + <dt><a href="#to_python_converter-spec-ctors">Class Template + <code>to_python_converter</code> constructor</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + <code>to_python_converter</code> registers a conversion from objects of a + given C++ type into a Python object. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="to_python_converter-spec"></a>Class template + <code>to_python_converter</code></h3> + <code>to_python_converter</code> adds a wrapper around a static member + function of its second template parameter, handling low-level details + such as insertion into the converter registry. + + <table border="1" summary="to_python_converter template parameters"> + <caption> + <b><code>to_python_converter</code> template parameters</b><br> + In the table below, <b><code>x</code></b> denotes an object of type + <code>T</code> + </caption> + + <tr> + <th>Parameter</th> + + <th>Requirements</th> + + <th>Description</th> + </tr> + + <tr> + <td><code>T</code></td> + + <td> + </td> + + <td>The C++ type of the source object in the conversion</td> + </tr> + + <tr> + <td><code>Conversion</code></td> + + <td> + <code>PyObject* p = Conversion::convert(x)</code>,<br> + if <code>p == 0</code>, <code><a href= + "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code>.</td> + + <td>A class type whose static member function <code>convert</code> + does the real work of the conversion.</td> + </tr> + <tr> + <td><code>bool has_get_pytype = false</code></td> + + <td> + <code>PyTypeObject const * p = Conversion::get_pytype() </code>.</td> + + <td><b>Optional member</b> - if <code>Conversion</code> has <code>get_pytype</code> member supply + <code>true</code> for this parameters. + If present <code>get_pytype</code> is used to document the return type + of functions using this conversion. The <code>get_pytype</code> may be implemented + using the classes and functions + from <a href="pytype_function.html"><code>pytype_function.hpp</code></a> + <b>NOTE :</b> For backward compatibility this parameter may be passed after + checking if <code>BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</code> is defined (see + <a href="pytype_function.html#examples">here</a>). + </td> + </tr> + </table> + + <h4><a name="to_python_converter-spec-synopsis"></a>Class template + <code>to_python_converter</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T, class Conversion, bool convertion_has_get_pytype_member=false> + struct to_python_converter + { + to_python_converter(); + }; +}} +</pre> + + <h4><a name="to_python_converter-spec-ctors"></a>Class template + <code>to_python_converter</code> constructor</h4> +<pre> +to_python_converter(); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Registers a to_python converter which uses + <code>Conversion::convert()</code> to do its work.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + This example presumes that someone has implemented the standard <a href= + "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example + module</a> from the Python documentation, and placed the corresponding + declarations in <code>"noddy.h"</code>. Because + <code>noddy_NoddyObject</code> is the ultimate trivial extension type, + the example is a bit contrived: it wraps a function for which all + information is contained in the <i>type</i> of its return value. + + <h3>C++ module definition</h3> +<pre> +#include <boost/python/reference.hpp> +#include <boost/python/module.hpp> +#include "noddy.h" + +struct tag {}; +tag make_tag() { return tag(); } + +using namespace boost::python; + +struct tag_to_noddy +{ + static PyObject* convert(tag const& x) + { + return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); + } + static PyTypeObject const* get_pytype() + { + return &noddy_NoddyType; + } +}; + +BOOST_PYTHON_MODULE(to_python_converter) +{ + def("make_tag", make_tag); + to_python_converter<tag, tag_to_noddy, true>(); //"true" because tag_to_noddy has member get_pytype +} +</pre> + + <h3>Python code</h3> +<pre> +>>> import to_python_converter +>>> def always_none(): +... return None +... +>>> def choose_function(x): +... if (x % 2 != 0): +... return to_python_converter.make_tag +... else: +... return always_none +... +>>> a = [ choose_function(x) for x in range(5) ] +>>> b = [ f() for f in a ] +>>> type(b[0]) +<type 'NoneType'> +>>> type(b[1]) +<type 'Noddy'> +>>> type(b[2]) +<type 'NoneType'> +>>> type(b[3]) +<type 'Noddy'> +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 11 June, 2007 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/to_python_indirect.html b/libs/python/doc/v2/to_python_indirect.html new file mode 100644 index 000000000..17e0a826c --- /dev/null +++ b/libs/python/doc/v2/to_python_indirect.html @@ -0,0 +1,196 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, 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/to_python_indirect.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/to_python_indirect.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#introduction">Introduction</a> + + + <dt><a href="#classes">Classes</a> + + <dd> + <dl class="page-index"> + <dt><a href="#to_python_indirect-spec">Class Template <code>to_python_indirect</code></a> + + <dd> + <dl class="page-index"> + + <dt><a href="#to_python_indirect-spec-synopsis">Class Template + <code>to_python_indirect</code> synopsis</a> + + <dt><a href="#to_python_indirect-spec-observers">Class Template + <code>to_python_indirect</code> observer functions</a> + + <dt><a href="#to_python_indirect-spec-statics">Class Template + <code>to_python_indirect</code> static functions</a> + </dl> + </dl> + + <dt><a href="#examples">Example</a> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <code><boost/python/to_python_indirect.hpp></code> supplies + a way to construct new Python objects that hold wrapped C++ class + instances via a pointer or smart pointer. + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="to_python_indirect-spec"></a>Class template <code>to_python_indirect</code></h3> + <p>Class template <code>to_python_indirect</code> converts objects +of its first argument type to python as extension class instances, using the ownership policy provided by its 2nd argument. + + <p> + + + <table border="1" summary="to_python_indirect template parameters"> + <caption> + <b><code>to_python_indirect</code> Requirements</b><br> + + In the table below, <b><code>x</code></b> denotes an object of + type <code>T</code>, <b><code>h</code></b> denotes an + object of type + <code>boost::python::objects::instance_holder*</code>, and + <b><code>p</code></b> denotes an object of type + <code>U*</code>. + + </caption> + <tr> + <th>Parameter + + <th>Requirements + + <th>Description + + <tr> + <td><code>T</code> + + <td>Either <code>U</code> <i>cv</i><code>&</code> + (where <i>cv</i> is any optional cv-qualification) or a <a + href="Dereferenceable.html">Dereferenceable</a> type such that + <code>*x</code> is convertible to <code>U const&</code>, where + <code>U</code> is a class type. + + <td>A type deferencing a C++ class exposed to Python using + class template <code><a + href="class.html#class_-spec">class_</a></code>. + + <tr> + <td><code>MakeHolder</code> + + <td>h = MakeHolder::execute(p); + + <td>A class whose static <code>execute()</code> creates an + <code>instance_holder</code>. + + </table> + + Instantiations of <code>to_python_indirect</code> are models of <a + href="ResultConverter.html#ResultConverter-concept">ResultConverter</a>. + + + <h4><a name="to_python_indirect-spec-synopsis"></a>Class template <code>to_python_indirect</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T, class MakeHolder> + struct to_python_indirect + { + static bool convertible(); + PyObject* operator()(T ptr_or_reference) const; + private: + static PyTypeObject* type(); + }; +}} +</pre> + + <h4><a name="to_python_indirect-spec-observers"></a>Class template <code>to_python_indirect</code> observers</h4> +<pre> +PyObject* operator()(T x) const; +</pre> + + <dl class="function-semantics"> + + <dt><b>Requires:</b> <code>x</code> refers to an object (if it + is a pointer type, it is non-null). <code>convertible() == + true</code>. + + <dt><b>Effects:</b> Creates an appropriately-typed Boost.Python + extension class instance, uses <code>MakeHolder</code> to create + an <code>instance_holder</code> from <code>x</code>, installs + the <code>instance_holder</code> in the new extension class + instance, and returns a pointer to it. + + </dl> + + + <h4><a name="to_python_indirect-spec-statics"></a>Class template <code>to_python_indirect</code> statics</h4> +<pre> +bool convertible(); +</pre> + + <dt><b>Effects:</b> Returns <code>true</code> iff any module has + registered a Python type corresponding to <code>U</code>. + + <h2><a name="examples"></a>Example</h2> + +This example replicates the functionality of <a +href="reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a>, +but without some of the compile-time error checking. + + +<pre> + +struct make_reference_holder +{ + typedef boost::python::objects::instance_holder* result_type; + template <class T> + static result_type execute(T* p) + { + return new boost::python::objects::pointer_holder<T*, T>(p); + } +}; + +struct reference_existing_object +{ + // metafunction returning the <a href="ResultConverter.html#ResultConverter-concept">ResultConverter</a> + template <class T> + struct apply + { + typedef boost::python::to_python_indirect<T,make_reference_holder> type; + }; +}; +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> Distributed + under the Boost Software License, Version 1.0. (See accompanying file + LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</p> + diff --git a/libs/python/doc/v2/to_python_value.html b/libs/python/doc/v2/to_python_value.html new file mode 100644 index 000000000..3ba0044d1 --- /dev/null +++ b/libs/python/doc/v2/to_python_value.html @@ -0,0 +1,103 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, 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/to_python_value.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header + <boost/python/to_python_value.hpp></h2> + </table> + <hr> + + <h2>Contents</h2> + + <dl class="page-index"> + <dt><a href="#classes">Classes</a> + + <dd> + <dl class="page-index"> + <dt><a href="#to_python_value-spec">Class + <code>to_python_value</code></a> + + <dd> + <dl class="page-index"> + <dt><a href="#to_python_value-spec-synopsis">Class template + <code>to_python_value</code> synopsis</a> + + <dt><a href="#to_python_value-spec-observers">Class template + <code>to_python_value</code> observer functions</a> + </dl> + </dl> + + </dl> + <hr> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="to_python_value-spec"></a>Class template + <code>to_python_value</code></h3> + + <p><code>to_python_value</code> is a model of <a href= + "ResultConverter.html#ResultConverter-concept">ResultConverter</a> + which copies its argument into a new Python object. + + <h4><a name="to_python_value-spec-synopsis"></a>Class + <code>to_python_value</code> synopsis</h4> +<pre> +namespace boost { namespace python +{ + template <class T> + struct to_python_value + { + typedef typename <a href="../../../type_traits/index.html#transformations">add_reference</a>< + typename <a href="../../../type_traits/index.html#transformations">add_const</a><T>::type + >::type argument_type; + + static bool convertible(); + PyObject* operator()(argument_type) const; + }; +}} +</pre> + + <h4><a name="to_python_value-spec-observers"></a>Class + <code>to_python_value</code> observers</h4> +<pre> +static bool convertible(); +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>true</code> iff a converter has been registered which can convert <code>T</code> to python by-value. + </dl> + +<pre> +PyObject* operator()(argument_type x) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>convertible() == true</code> + <dt><b>Effects:</b> converts <code>x</code> to python + <dt><b>Returns:</b> the resulting Python object iff a converter for <code>T</code> has been registered, <code>0</code> otherwise. + </dl> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> Distributed under the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt)</p> + diff --git a/libs/python/doc/v2/tuple.html b/libs/python/doc/v2/tuple.html new file mode 100644 index 000000000..e90244f3e --- /dev/null +++ b/libs/python/doc/v2/tuple.html @@ -0,0 +1,139 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<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/tuple.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="../../../../boost.png" border="0"></a></h3> + </td> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <boost/python/tuple.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="#tuple-spec">Class <code>tuple</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#tuple-spec-synopsis">Class <code>tuple</code> + synopsis</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#make_tuple-spec"><code>make_tuple</code></a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>Exposes a <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> for the Python + <a href= + "http://www.python.org/doc/current/tut/node7.html#SECTION007300000000000000000"> + tuple</a> type.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="tuple-spec"></a>Class <code>tuple</code></h3> + + <p>Exposes the interface of Python's built-in <code>tuple</code> type. + The semantics of the constructors and member functions defined below can + be fully understood by reading the <a href= + "ObjectWrapper.html#TypeWrapper-concept">TypeWrapper</a> concept + definition. Since <code>tuple</code> is publicly derived from <code><a + href="object.html#object-spec">object</a></code>, the public object + interface applies to <code>tuple</code> instances as well.</p> + + <h4><a name="tuple-spec-synopsis"></a>Class <code>tuple</code> + synopsis</h4> +<pre> +namespace boost { namespace python +{ + class tuple : public object + { + // tuple() -> an empty tuple + tuple(); + + // tuple(sequence) -> tuple initialized from sequence's items + template <class T> + explicit tuple(T const& sequence) + }; +}} +</pre> + + <h2><a name="functions"></a>Functions</h2> + + <h3><a name="make_tuple-spec"></a><code>make_tuple</code></h3> +<pre> +namespace boost { namespace python +{ + tuple make_tuple(); + + template <class A0> + tuple make_tuple(A0 const& a0); + + template <class A0, class A1> + tuple make_tuple(A0 const& a0, A1 const& a1); + ... + template <class A0, class A1,...class A<i>n</i>> + tuple make_tuple(A0 const& a0, A1 const& a1,...A<i>n</i> const& a<i>n</i>); +}} +</pre> + Constructs a new tuple object composed of <code>object(a0), + object(a0),...object(a<i>n</i>)</code>. + + <h2><a name="examples"></a>Example</h2> +<pre> +using namespace boost::python; +tuple head_and_tail(object sequence) +{ + return make_tuple(sequence[0],sequence[-1]); +} +</pre> + + <p>Revised 03 October, 2002</p> + + <p><i>© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p> + </body> +</html> + diff --git a/libs/python/doc/v2/type_id.html b/libs/python/doc/v2/type_id.html new file mode 100644 index 000000000..570846741 --- /dev/null +++ b/libs/python/doc/v2/type_id.html @@ -0,0 +1,224 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + + <meta name="generator" content="HTML Tidy, 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/type_id.hpp></title> + + <style type="text/css"> + p.c4 {font-style: italic} + span.c3 {color: #ff0000} + h2.c2 {text-align: center} + h1.c1 {text-align: center} +</style> + + <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="../../../../boost.png" border= + "0"></a></h3> + + <td valign="top"> + <h1 class="c1"><a href="../index.html">Boost.Python</a></h1> + + <h2 class="c2">Header <boost/python/type_id.hpp></h2> + </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="#type_info-spec">Class <code>type_info</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#type_info-spec-synopsis">Class + <code>type_info</code> synopsis</a></dt> + + <dt><a href="#type_infospec-ctors">Class <code>type_info</code> + constructor</a></dt> + + <dt><a href="#type_infospec-comparisons">Class + <code>type_info</code> comparison functions</a></dt> + + <dt><a href="#type_infospec-observers">Class + <code>type_info</code> observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#functions">Functions</a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#type_id-spec">type_id</a></dt> + </dl> + </dd> + + <dt><a href="#examples">Example</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p><code><boost/python/type_id.hpp></code> provides types and + functions for runtime type identification like those of of + <code><typeinfo></code>. It exists mostly to work around certain + compiler bugs and platform-dependent interactions with shared + libraries.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="type_info-spec"></a>Class <code>type_info</code></h3> + + <p><code>type_info</code> instances identify a type. As + <code>std::type_info</code> is specified to (but unlike its + implementation in some compilers), <code>boost::python::type_info</code> + never represents top-level references or cv-qualification (see section + 5.2.8 in the C++ standard). Unlike <code>std::type_info</code>, + <code>boost::python::type_info</code> instances are copyable, and + comparisons always work reliably across shared library boundaries.</p> + + <h4><a name="type_info-spec-synopsis"></a>Class type_info synopsis</h4> +<pre> +namespace boost { namespace python +{ + class type_info : <a href= +"../../../utility/operators.htm#totally_ordered1">totally_ordered</a><type_info> + { + public: + // constructor + type_info(std::type_info const& = typeid(void)); + + // comparisons + bool operator<(type_info const& rhs) const; + bool operator==(type_info const& rhs) const; + + // observers + char const* name() const; + }; +}} +</pre> + + <h4><a name="type_infospec-ctors">Class <code>type_info</code> + constructor</a></h4> +<pre> +type_info(std::type_info const& = typeid(void)); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> constructs a <code>type_info</code> object which + identifies the same type as its argument.</dt> + + <dt><b>Rationale:</b> Since it is occasionally necessary to make an + array of <code>type_info</code> objects a benign default argument is + supplied. <span class="c3"><b>Note:</b></span> this constructor does + <i>not</i> correct for non-conformance of compiler + <code>typeid()</code> implementations. See <code><a href= + "#type_id-spec">type_id</a></code>, below.</dt> + </dl> + + <h4><a name="type_infospec-comparisons">Class <code>type_info</code> + comparisons</a></h4> +<pre> +bool operator<(type_info const& rhs) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> yields a total order over <code>type_info</code> + objects.</dt> + </dl> +<pre> +bool operator==(type_info const& rhs) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>true</code> iff the two values describe the + same type.</dt> + </dl> + + <dl class="function-semantics"> + <dt><b>Note:</b> The use of <code><a href= + "../../../utility/operators.htm#totally_ordered1">totally_ordered</a><type_info></code> + as a private base class supplies operators <code><=</code>, + <code>>=</code>, <code>></code>, and <code>!=</code></dt> + </dl> + + <h4><a name="type_infospec-observers">Class <code>type_info</code> + observers</a></h4> +<pre> +char const* name() const; +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> The result of calling <code>name()</code> on the + argument used to construct the object.</dt> + </dl> + + <h2><a name="functions"></a>Functions</h2> +<pre> +std::ostream& operator<<(std::ostream&s, type_info const&x); +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> Writes a description of the type described by to + <code>x</code> into <code>s</code>.</dt> + + <dt><b>Rationale:</b> Not every C++ implementation provides a truly + human-readable <code>type_info::name()</code> string, but for some we + may be able to decode the string and produce a reasonable + representation.</dt> + </dl> +<pre> +<a name="type_id-spec">template <class T> type_info type_id</a>() +</pre> + + <dl class="function-semantics"> + <dt><b>Returns:</b> <code>type_info(typeid(T))</code></dt> + + <dt><b>Note:</b> On some non-conforming C++ implementations, the code + is not actually as simple as described above; the semantics are + adjusted to work <i>as-if</i> the C++ implementation were + conforming.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> + The following example, though silly, illustrates how the + <code>type_id</code> facility might be used +<pre> +#include <boost/python/type_id.hpp> + +// Returns true iff the user passes an int argument +template <class T> +bool is_int(T x) +{ + using boost::python::type_id; + return type_id<T>() == type_id<int>(); +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + + <p class="c4">© Copyright <a href= + "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002. Distributed under the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt)< + + </body> +</html> + diff --git a/libs/python/doc/v2/with_custodian_and_ward.html b/libs/python/doc/v2/with_custodian_and_ward.html new file mode 100644 index 000000000..b8e2a498d --- /dev/null +++ b/libs/python/doc/v2/with_custodian_and_ward.html @@ -0,0 +1,370 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- Copyright David Abrahams 2006. Distributed under the Boost --> +<!-- Software License, Version 1.0. (See accompanying --> +<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) --> +<html> + <head> + <meta name="generator" content= + "HTML Tidy for Cygwin (vers 1st February 2003), see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + <title> + Boost.Python - <boost/python/with_custodian_and_ward.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="../../../../boost.png" border="0"> + </a> + </h3> + </td> + <td valign="top"> + <h1 align="center"> + <a href="../index.html">Boost.Python</a> + </h1> + <h2 align="center"> + Header <boost/python/with_custodian_and_ward.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="#with_custodian_and_ward-spec">Class Template + <code>with_custodian_and_ward</code></a> + </dt> + <dd> + <dl class="page-index"> + <dt> + <a href="#with_custodian_and_ward-spec-synopsis">Class + Template <code>with_custodian_and_ward</code> synopsis</a> + </dt> + <dt> + <a href="#with_custodian_and_ward-spec-statics">Class + <code>with_custodian_and_ward</code> static functions</a> + </dt> + </dl> + </dd> + <dt> + <a href="#with_custodian_and_ward_postcall-spec">Class Template + <code>with_custodian_and_ward_postcall</code></a> + </dt> + <dd> + <dl class="page-index"> + <dt> + <a href= + "#with_custodian_and_ward_postcall-spec-synopsis">Class + Template <code>with_custodian_and_ward_postcall</code> + synopsis</a> + </dt> + <dt> + <a href= + "#with_custodian_and_ward_postcall-spec-statics">Class + <code>with_custodian_and_ward_postcall</code> static + functions</a> + </dt> + </dl> + </dd> + </dl> + </dd> + <dt> + <a href="#examples">Example</a> + </dt> + </dl> + <hr> + <h2> + <a name="introduction">Introduction</a> + </h2>This header provides facilities for establishing a lifetime + dependency between two of a function's Python argument or result objects. + The <i>ward</i> object will not be destroyed until after the custodian as + long as the <i>custodian</i> object supports <a href= + "http://www.python.org/doc/current/lib/module-weakref.html">weak + references</a> (Boost.Python extension classes all support weak + references). If the <i>custodian</i> object does not support weak + references and is not <code>None</code>, an appropriate exception will be + thrown. The two class templates <code>with_custodian_and_ward</code> and + <code>with_custodian_and_ward_postcall</code> differ in the point at + which they take effect. + <p> + In order to reduce the chance of inadvertently creating dangling + pointers, the default is to do lifetime binding <i>before</i> the + underlying C++ object is invoked. However, before invocation the result + object is not available, so + <code>with_custodian_and_ward_postcall</code> is provided to bind + lifetimes after invocation. Also, if a C++ exception is thrown after + <code>with_custodian_and_ward<>::precall</code> but before the + underlying C++ object actually stores a pointer, the lifetime of the + custodian and ward objects will be artificially bound together, so one + might choose <code>with_custodian_and_ward_postcall</code> instead, + depending on the semantics of the function being wrapped. + </p> + <p> + Please note that this is <i>not</i> the appropriate tool to use when + wrapping functions which <b>transfer ownership</b> of a raw pointer + across the function-call boundary. Please see the <a href= + "faq.html#ownership">FAQ</a> if you want to do that. + </p> + <h2> + <a name="classes"></a>Classes + </h2> + <h3> + <a name="with_custodian_and_ward-spec"></a>Class template + <code>with_custodian_and_ward</code> + </h3> + <table border="1" summary="with_custodian_and_ward template parameters"> + <caption> + <b><code>with_custodian_and_ward</code> template parameters</b> + </caption> + <tr> + <th> + Parameter + </th> + <th> + Requirements + </th> + <th> + Description + </th> + <th> + Default + </th> + </tr> + <tr> + <td> + <code>custodian</code> + </td> + <td> + A positive compile-time constant of type <code>std::size_t</code>. + </td> + <td> + The 1-based index of the parameter which is the dependency in the + lifetime relationship to be established. If used to wrap a member + function, parameter 1 is the target object (<code>*this</code>). + Note that if the target Python object type doesn't support weak + references, a Python <code>TypeError</code> exception will be + raised when the C++ object being wrapped is called. + </td> + </tr> + <tr> + <td> + <code>ward</code> + </td> + <td> + A positive compile-time constant of type <code>std::size_t</code>. + </td> + <td> + The 1-based index of the parameter which is the dependent in the + lifetime relationship to be established. If used to wrap a member + function, parameter 1 is the target object (<code>*this</code>). + </td> + </tr> + <tr> + <td> + <code>Base</code> + </td> + <td> + A model of <a href="CallPolicies.html">CallPolicies</a> + </td> + <td> + Used for <a href="CallPolicies.html#composition">policy + composition</a>. + </td> + <td> + <code><a href= + "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code> + </td> + </tr> + </table> + <h4> + <a name="with_custodian_and_ward-spec-synopsis"></a>Class template + <code>with_custodian_and_ward</code> synopsis + </h4> + <pre> +namespace boost { namespace python +{ + template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> + struct with_custodian_and_ward : Base + { + static bool precall(PyObject* args); + }; +}} +</pre> + <h4> + <a name="with_custodian_and_ward-spec-statics"></a>Class + <code>with_custodian_and_ward</code> static functions + </h4> + <pre> +bool precall(PyObject* args); +</pre> + <dl class="function-semantics"> + <dt> + <b>Requires:</b> <code><a href= + "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) + != 0</code> + </dt> + <dt> + <b>Effects:</b> Makes the lifetime of the argument indicated by + <code>ward</code> dependent on the lifetime of the argument indicated + by <code>custodian</code>. + </dt> + <dt> + <b>Returns:</b> <code>false</code> and <code><a href= + "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code> + upon failure, <code>true</code> otherwise. + </dt> + </dl><!-- xxxxxx --> + <h3> + <a name="with_custodian_and_ward_postcall-spec"></a>Class template + <code>with_custodian_and_ward_postcall</code> + </h3> + <table border="1" summary= + "with_custodian_and_ward_postcall template parameters"> + <caption> + <b><code>with_custodian_and_ward_postcall</code> template + parameters</b> + </caption> + <tr> + <th> + Parameter + </th> + <th> + Requirements + </th> + <th> + Description + </th> + <th> + Default + </th> + </tr> + <tr> + <td> + <code>custodian</code> + </td> + <td> + A compile-time constant of type <code>std::size_t</code>. + </td> + <td> + The index of the parameter which is the dependency in the lifetime + relationship to be established. Zero indicates the result object; 1 + indicates the first argument. If used to wrap a member function, + parameter 1 is the target object (<code>*this</code>). Note that if + the target Python object type doesn't support weak references, a + Python <code>TypeError</code> exception will be raised when the C++ + object being wrapped is called. + </td> + </tr> + <tr> + <td> + <code>ward</code> + </td> + <td> + A compile-time constant of type <code>std::size_t</code>. + </td> + <td> + The index of the parameter which is the dependent in the lifetime + relationship to be established. Zero indicates the result object; 1 + indicates the first argument. If used to wrap a member function, + parameter 1 is the target object (<code>*this</code>). + </td> + </tr> + <tr> + <td> + <code>Base</code> + </td> + <td> + A model of <a href="CallPolicies.html">CallPolicies</a> + </td> + <td> + Used for <a href="CallPolicies.html#composition">policy + composition</a>. + </td> + <td> + <code><a href= + "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code> + </td> + </tr> + </table> + <h4> + <a name="with_custodian_and_ward_postcall-spec-synopsis"></a>Class + template <code>with_custodian_and_ward_postcall</code> synopsis + </h4> + <pre> +namespace boost { namespace python +{ + template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> + struct with_custodian_and_ward_postcall : Base + { + static PyObject* postcall(PyObject* args, PyObject* result); + }; +}} +</pre> + <h4> + <a name="with_custodian_and_ward_postcall-spec-statics"></a>Class + <code>with_custodian_and_ward_postcall</code> static functions + </h4> + <pre> +PyObject* postcall(PyObject* args, PyObject* result); +</pre> + <dl class="function-semantics"> + <dt> + <b>Requires:</b> <code><a href= + "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) + != 0</code>, <code>result != 0</code>. + </dt> + <dt> + <b>Effects:</b> Makes the lifetime of the object indicated by + <code>ward</code> dependent on the lifetime of the object indicated + by <code>custodian</code>. + </dt> + <dt> + <b>Returns:</b> <code>0</code> and <code><a href= + "http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code> + upon failure, <code>true</code> otherwise. + </dt> + </dl> + <h2> + <a name="examples"></a>Example + </h2>The following example shows how + <code>with_custodian_and_ward_postcall</code> is used by the library to + implement <code><a href= + "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code> + + <pre> +template <std::size_t owner_arg = 1, class Base = default_call_policies> +struct return_internal_reference + : with_custodian_and_ward_postcall<0, owner_arg, Base> +{ + typedef <a href= +"reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter; +}; +</pre> + <p> + Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 13 November, 2002 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + </p> + <p> + <i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2002. </i> + </p> + </body> +</html> diff --git a/libs/python/doc/v2/wrapper.html b/libs/python/doc/v2/wrapper.html new file mode 100644 index 000000000..06239754a --- /dev/null +++ b/libs/python/doc/v2/wrapper.html @@ -0,0 +1,238 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> + <link rel="stylesheet" type="text/css" href="../boost.css"> + + <title>Boost.Python - <wrapper.hpp></title> + + <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="../../../../boost.png" border="0"></a></h3> + + <td valign="top"> + <h1 align="center"><a href="../index.html">Boost.Python</a></h1> + + <h2 align="center">Header <wrapper.hpp></h2> + </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="#override-spec">Class template + <code>override</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#override-spec-synopsis">Class + <code>override</code> synopsis</a></dt> + + <dt><a href="#override-spec-observers">Class + <code>override</code> observer functions</a></dt> + </dl> + </dd> + + <dt><a href="#wrapper-spec">Class template + <code>wrapper</code></a></dt> + + <dd> + <dl class="page-index"> + <dt><a href="#wrapper-spec-synopsis">Class <code>wrapper</code> + synopsis</a></dt> + + <dt><a href="#wrapper-spec-observers">Class + <code>wrapper</code> observer functions</a></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><a href="#examples">Example(s)</a></dt> + </dl> + <hr> + + <h2><a name="introduction"></a>Introduction</h2> + + <p>To wrap a class <code>T</code> such that its virtual functions can be + "overridden in Python"—so that the corresponding method of a Python + derived class will be called when the virtual function is invoked from + C++—you must create a C++ wrapper class derived from ``T`` that + overrides those virtual functions so that they call into Python. This + header contains classes that can be used to make that job easier.</p> + + <h2><a name="classes"></a>Classes</h2> + + <h3><a name="override-spec"></a>Class <code>override</code></h3> + + <p>Encapsulates a Python override of a C++ virtual function. An + <code>override</code> object either holds a callable Python object or + <code>None</code>.</p> + + <h4><a name="override-spec-synopsis"></a>Class <code>override</code> + synopsis</h4> +<pre> +namespace boost +{ + class override : object + { + public: + <i>unspecified</i> operator() const; + template <class A0> + <i>unspecified</i> operator(A0) const; + template <class A0, class A1> + <i>unspecified</i> operator(A0, A1) const; + ... + template <class A0, class A1, ...class A<i>n</i>> + <i>unspecified</i> operator(A0, A1, ...A<i>n</i>) const; + }; +}; +</pre> + + <h4><a name="override-spec-observers"></a>Class <code>override</code> + observer functions</h4> +<pre> +<i>unspecified</i> operator() const; +template <class A0> +<i>unspecified</i> operator(A0) const; +template <class A0, class A1> +<i>unspecified</i> operator(A0, A1) const; +... +template <class A0, class A1, ...class A<i>n</i>> +<i>unspecified</i> operator(A0, A1, ...A<i>n</i>) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Effects:</b> If <code>*this</code> holds a callable Python + object, it is invoked with the specified arguments in the manner + specified <a href="callbacks.html">here</a>. Otherwise, throws <code><a + href="errors.html#error_already_set-spec">error_already_set</a></code> + .</dt> + + <dt><b>Returns:</b> An object of unspecified type that holds the Python + result of the invocation and, when converted to a C++ type + <code>R</code>, attempts to convert that result object to + <code>R</code>. If that conversion fails, throws <code><a href= + "errors.html#error_already_set-spec">error_already_set</a></code> + .</dt> + </dl> + + <h3><a name="wrapper-spec"></a>Class template <code>wrapper</code></h3> + + <p>Deriving your wrapper class from both ``T`` <i>and</i> + ``wrapper<T> makes writing that derived class easier.</p> + + <h4><a name="wrapper-spec-synopsis"></a>Class template + <code>wrapper</code> synopsis</h4> +<pre> +namespace boost +{ + class wrapper + { + protected: + override get_override(char const* name) const; + }; +}; +</pre> + + <h4><a name="wrapper-spec-observers"></a>Class <code>wrapper</code> + observer functions</h4> +<pre> +override get_override(char const* name) const; +</pre> + + <dl class="function-semantics"> + <dt><b>Requires:</b> <code>name</code> is a <a href= + "definitions.html#ntbs">ntbs</a>.</dt> + + <dt><b>Returns:</b> If <code>*this</code> is the C++ base class + subobject of a Python derived class instance that overrides the named + function, returns an <code>override</code> object that delegates to the + Python override. Otherwise, returns an <code>override</code> object + that holds <code>None</code>.</dt> + </dl> + + <h2><a name="examples"></a>Example</h2> +<pre> +#include <boost/python/module.hpp> +#include <boost/python/class.hpp> +#include <boost/python/wrapper.hpp> +#include <boost/python/call.hpp> + +using namespace boost::python; + +// Class with one pure virtual function +struct P +{ + virtual ~P(){} + virtual char const* f() = 0; + char const* g() { return "P::g()"; } +}; + +struct PCallback : P, wrapper<P> +{ + char const* f() + { +#if BOOST_WORKAROUND(BOOST_MSVC, <= 1300) // Workaround for vc6/vc7 + return call<char const*>(this->get_override("f").ptr()); +#else + return this->get_override("f")(); +#endif + } +}; + +// Class with one non-pure virtual function +struct A +{ + virtual ~A(){} + virtual char const* f() { return "A::f()"; } +}; + +struct ACallback : A, wrapper<A> +{ + char const* f() + { + if (override f = this->get_override("f")) +#if BOOST_WORKAROUND(BOOST_MSVC, <= 1300) // Workaround for vc6/vc7 + return call<char const*>(f.ptr()); +#else + return f(); +#endif + + return A::f(); + } + + char const* default_f() { return this->A::f(); } +}; + +BOOST_PYTHON_MODULE_INIT(polymorphism) +{ + class_<PCallback,boost::noncopyable>("P") + .def("f", pure_virtual(&P::f)) + ; + + class_<ACallback,boost::noncopyable>("A") + .def("f", &A::f, &ACallback::default_f) + ; +} +</pre> + + <p>Revised + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + 31 October, 2004 + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + + + <p><i>© Copyright <a href="http://www.boost.org/people/dave_abrahams.htm">Dave + Abrahams</a> 2004</i> Distributed under the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt)</p> + |