1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Function documentation</title> 5<link rel="stylesheet" href="../../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> 8<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation"> 9<link rel="prev" href="boost_python_raw_function_hpp.html" title="boost/python/raw_function.hpp"> 10<link rel="next" href="models_of_callpolicies.html" title="Models of CallPolicies"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> 14<hr> 15<div class="spirit-nav"> 16<a accesskey="p" href="boost_python_raw_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_callpolicies.html"><img src="../../images/next.png" alt="Next"></a> 17</div> 18<div class="section"> 19<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 20<a name="function_invocation_and_creation.function_documentation"></a><a class="link" href="function_documentation.html" title="Function documentation">Function 21 documentation</a> 22</h2></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat">boost/python/function_doc_signature.hpp</a></span></dt> 25<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp">boost/python/pytype_function.hpp</a></span></dt> 26</dl></div> 27<div class="section"> 28<div class="titlepage"><div><div><h3 class="title"> 29<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat" title="boost/python/function_doc_signature.hpp">boost/python/function_doc_signature.hpp</a> 30</h3></div></div></div> 31<div class="toc"><dl class="toc"> 32<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction">Introduction</a></span></dt> 33<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen">Class 34 <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code></a></span></dt> 35<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example">Example</a></span></dt> 36</dl></div> 37<div class="section"> 38<div class="titlepage"><div><div><h4 class="title"> 39<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.introduction" title="Introduction">Introduction</a> 40</h4></div></div></div> 41<p> 42 Boost.Python supports docstrings with automatic appending of Pythonic 43 and C++ signatures. This feature is implemented by class <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code>. The 44 class uses all of the overloads, supplied arg names and default values, 45 as well as the user-defined docstrings, to generate documentation for 46 a given function. 47 </p> 48</div> 49<div class="section"> 50<div class="titlepage"><div><div><h4 class="title"> 51<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.class_function_doc_signature_gen" title="Class function_doc_signature_generator">Class 52 <code class="computeroutput"><span class="identifier">function_doc_signature_generator</span></code></a> 53</h4></div></div></div> 54<p> 55 The class has only one public function which returns a list of strings 56 documenting the overloads of a function. 57 </p> 58<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">objects</span> <span class="special">{</span> 59 60 <span class="keyword">class</span> <span class="identifier">function_doc_signature_generator</span> 61 <span class="special">{</span> 62 <span class="keyword">public</span><span class="special">:</span> 63 <span class="keyword">static</span> <span class="identifier">list</span> <span class="identifier">function_doc_signatures</span><span class="special">(</span><span class="identifier">function</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">f</span><span class="special">);</span> 64 <span class="special">};</span> 65 66<span class="special">}}}</span> 67</pre> 68</div> 69<div class="section"> 70<div class="titlepage"><div><div><h4 class="title"> 71<a name="function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_function_doc_signat.example" title="Example">Example</a> 72</h4></div></div></div> 73<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 74<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 75<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">args</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 76<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 77<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 78<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">overloads</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 79<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">raw_function</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 80 81<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> 82 83<span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span> 84<span class="special">{</span> 85 <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> 86<span class="special">}</span> 87 88<span class="identifier">BOOST_PYTHON_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">f_overloads</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> 89 90 91<span class="keyword">struct</span> <span class="identifier">X</span> 92<span class="special">{</span> 93 <span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">double</span> <span class="identifier">y</span> <span class="special">=</span> <span class="number">4.25</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">z</span> <span class="special">=</span> <span class="string">"wow"</span><span class="special">)</span> 94 <span class="special">{</span> 95 <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">y</span><span class="special">,</span> <span class="identifier">z</span><span class="special">);</span> 96 <span class="special">}</span> 97<span class="special">};</span> 98 99<span class="identifier">BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</span><span class="special">(</span><span class="identifier">X_f_overloads</span><span class="special">,</span> <span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> 100 101<span class="identifier">tuple</span> <span class="identifier">raw_func</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kw</span><span class="special">)</span> 102<span class="special">{</span> 103 <span class="keyword">return</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">kw</span><span class="special">);</span> 104<span class="special">}</span> 105 106<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">args_ext</span><span class="special">)</span> 107<span class="special">{</span> 108 <span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="special">(</span><span class="identifier">arg</span><span class="special">(</span><span class="string">"x"</span><span class="special">)=</span><span class="number">1</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"y"</span><span class="special">)=</span><span class="number">4.25</span><span class="special">,</span> <span class="identifier">arg</span><span class="special">(</span><span class="string">"z"</span><span class="special">)=</span><span class="string">"wow"</span><span class="special">)</span> 109 <span class="special">,</span> <span class="string">"This is f's docstring"</span> 110 <span class="special">);</span> 111 112 <span class="identifier">def</span><span class="special">(</span><span class="string">"raw"</span><span class="special">,</span> <span class="identifier">raw_function</span><span class="special">(</span><span class="identifier">raw_func</span><span class="special">));</span> 113 114 <span class="identifier">def</span><span class="special">(</span><span class="string">"f1"</span><span class="special">,</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">f_overloads</span><span class="special">(</span><span class="string">"f1's docstring"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">,</span> <span class="string">"z"</span><span class="special">)));</span> 115 116 117 <span class="identifier">class_</span><span class="special"><</span><span class="identifier">X</span><span class="special">>(</span><span class="string">"X"</span><span class="special">,</span> <span class="string">"This is X's docstring"</span><span class="special">,</span> <span class="identifier">init</span><span class="special"><>(</span><span class="identifier">args</span><span class="special">(</span><span class="string">"self"</span><span class="special">)))</span> 118 <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"f"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">X</span><span class="special">::</span><span class="identifier">f</span> 119 <span class="special">,</span> <span class="string">"This is X.f's docstring"</span> 120 <span class="special">,</span> <span class="identifier">args</span><span class="special">(</span><span class="string">"self"</span><span class="special">,</span><span class="string">"x"</span><span class="special">,</span> <span class="string">"y"</span><span class="special">,</span> <span class="string">"z"</span><span class="special">))</span> 121 122 <span class="special">;</span> 123 124<span class="special">}</span> 125</pre> 126<p> 127 Python code: 128 </p> 129<pre class="programlisting"><span class="special">>>></span> <span class="keyword">import</span> <span class="identifier">args_ext</span> 130<span class="special">>>></span> <span class="identifier">help</span><span class="special">(</span><span class="identifier">args_ext</span><span class="special">)</span> 131<span class="identifier">Help</span> <span class="identifier">on</span> <span class="identifier">module</span> <span class="identifier">args_ext</span><span class="special">:</span> 132 133<span class="identifier">NAME</span> 134 <span class="identifier">args_ext</span> 135 136<span class="identifier">FILE</span> 137 <span class="identifier">args_ext</span><span class="special">.</span><span class="identifier">pyd</span> 138 139<span class="identifier">CLASSES</span> 140 <span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span><span class="special">.</span><span class="identifier">instance</span><span class="special">(</span><span class="identifier">__builtin__</span><span class="special">.</span><span class="identifier">object</span><span class="special">)</span> 141 <span class="identifier">X</span> 142 143 <span class="keyword">class</span> <span class="identifier">X</span><span class="special">(</span><span class="identifier">Boost</span><span class="special">.</span><span class="identifier">Python</span><span class="special">.</span><span class="identifier">instance</span><span class="special">)</span> 144 <span class="special">|</span> <span class="identifier">This</span> <span class="keyword">is</span> <span class="identifier">X</span><span class="string">'s docstring 145 | 146 | Method resolution order: 147 | X 148 | Boost.Python.instance 149 | __builtin__.object 150 | 151 | Methods defined here: 152 | 153 | __init__(...) 154 | __init__( (object)self) -> None : 155 | C++ signature: 156 | void __init__(struct _object *) 157 | 158 | f(...) 159 | f( (X)self, (int)x, (float)y, (str)z) -> tuple : This is X.f'</span><span class="identifier">s</span> <span class="identifier">docstring</span> 160 <span class="special">|</span> <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> 161 <span class="special">|</span> <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">struct</span> <span class="identifier">X</span> <span class="special">{</span><span class="identifier">lvalue</span><span class="special">},</span><span class="identifier">int</span><span class="special">,</span><span class="identifier">double</span><span class="special">,</span><span class="identifier">char</span> <span class="identifier">const</span> <span class="special">*)</span> 162 <span class="special">|</span> 163 <span class="special">|</span> <span class="special">.................</span> 164 <span class="special">|</span> 165<span class="identifier">FUNCTIONS</span> 166 <span class="identifier">f</span><span class="special">(...)</span> 167 <span class="identifier">f</span><span class="special">([</span> <span class="special">(</span><span class="identifier">int</span><span class="special">)</span><span class="identifier">x</span><span class="special">=</span><span class="number">1</span> <span class="special">[,</span> <span class="special">(</span><span class="identifier">float</span><span class="special">)</span><span class="identifier">y</span><span class="special">=</span><span class="number">4.25</span> <span class="special">[,</span> <span class="special">(</span><span class="identifier">str</span><span class="special">)</span><span class="identifier">z</span><span class="special">=</span><span class="string">'wow'</span><span class="special">]]])</span> <span class="special">-></span> <span class="identifier">tuple</span> <span class="special">:</span> <span class="identifier">This</span> <span class="keyword">is</span> <span class="identifier">f</span><span class="string">'s docstring 168 C++ signature: 169 class boost::python::tuple f([ int=1 [,double=4.25 [,char const *='</span><span class="identifier">wow</span><span class="string">']]]) 170 171 f1(...) 172 f1([ (int)x [, (float)y [, (str)z]]]) -> tuple : f1'</span><span class="identifier">s</span> <span class="identifier">docstring</span> 173 <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> 174 <span class="keyword">class</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">tuple</span> <span class="identifier">f1</span><span class="special">([</span> <span class="identifier">int</span> <span class="special">[,</span><span class="identifier">double</span> <span class="special">[,</span><span class="identifier">char</span> <span class="identifier">const</span> <span class="special">*]]])</span> 175 176 <span class="identifier">raw</span><span class="special">(...)</span> 177 <span class="identifier">object</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kwds</span><span class="special">)</span> <span class="special">:</span> 178 <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> 179 <span class="identifier">object</span> <span class="identifier">raw</span><span class="special">(</span><span class="identifier">tuple</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">dict</span> <span class="identifier">kwds</span><span class="special">)</span> 180</pre> 181</div> 182</div> 183<div class="section"> 184<div class="titlepage"><div><div><h3 class="title"> 185<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp" title="boost/python/pytype_function.hpp">boost/python/pytype_function.hpp</a> 186</h3></div></div></div> 187<div class="toc"><dl class="toc"> 188<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction">Introduction</a></span></dt> 189<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype">Class 190 <code class="computeroutput"><span class="identifier">wrap_pytype</span></code></a></span></dt> 191<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype">Class 192 <code class="computeroutput"><span class="identifier">registered_pytype</span></code></a></span></dt> 193<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type">Class 194 <code class="computeroutput"><span class="identifier">expected_from_python_type</span></code></a></span></dt> 195<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type">Class 196 <code class="computeroutput"><span class="identifier">to_python_target_type</span></code></a></span></dt> 197<dt><span class="section"><a href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example">Example</a></span></dt> 198</dl></div> 199<div class="section"> 200<div class="titlepage"><div><div><h4 class="title"> 201<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.introduction" title="Introduction">Introduction</a> 202</h4></div></div></div> 203<p> 204 To support Pythonic signatures the converters should supply a <code class="computeroutput"><span class="identifier">get_pytype</span></code> function returning a pointer 205 to the associated <code class="computeroutput"><span class="identifier">PyTypeObject</span></code>. 206 See for example <a class="link" href="../concepts/resultconverter.html" title="ResultConverter"><code class="computeroutput"><span class="identifier">ResultConverter</span></code></a> or <a class="link" href="../to_from_python_type_conversion/boost_python_to_python_converter.html#to_from_python_type_conversion.boost_python_to_python_converter.class_template_to_python_convert.class_template_to_python_convert" title="Class template to_python_converter constructor"><code class="computeroutput"><span class="identifier">to_python_converter</span></code></a>. The classes 207 in this header file are meant to be used when implmenting <code class="computeroutput"><span class="identifier">get_pytype</span></code>. There are also <code class="computeroutput"><span class="identifier">_direct</span></code> versions of the templates of 208 <code class="computeroutput"><span class="keyword">class</span> <span class="identifier">T</span></code> 209 which should be used with undecorated type parameter, expected to be 210 in the conversion registry when the module loads. 211 </p> 212</div> 213<div class="section"> 214<div class="titlepage"><div><div><h4 class="title"> 215<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_wrap_pytype" title="Class wrap_pytype">Class 216 <code class="computeroutput"><span class="identifier">wrap_pytype</span></code></a> 217</h4></div></div></div> 218<p> 219 This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code> 220 member returning the template parameter. 221 </p> 222<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> 223 224 <span class="keyword">template</span> <span class="special"><</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">pytype</span> <span class="special">></span> 225 <span class="keyword">class</span> <span class="identifier">wrap_pytype</span> 226 <span class="special">{</span> 227 <span class="keyword">public</span><span class="special">:</span> 228 <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">(){</span><span class="keyword">return</span> <span class="identifier">pytype</span><span class="special">;</span> <span class="special">}</span> 229 <span class="special">};</span> 230 231<span class="special">}}}</span> 232</pre> 233</div> 234<div class="section"> 235<div class="titlepage"><div><div><h4 class="title"> 236<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_registered_pytype" title="Class registered_pytype">Class 237 <code class="computeroutput"><span class="identifier">registered_pytype</span></code></a> 238</h4></div></div></div> 239<p> 240 This template should be used with template parameters which are (possibly 241 decorated) types exported to python using <a class="link" href="../high_level_components.html#high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel" title="Class template class_<T, Bases, HeldType, NonCopyable>"><code class="computeroutput"><span class="identifier">class_</span></code></a>. The generated a static 242 <code class="computeroutput"><span class="identifier">get_pytype</span></code> member returns 243 the corresponding python type. 244 </p> 245<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> 246 247 <span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> 248 <span class="keyword">class</span> <span class="identifier">registered_pytype</span> 249 <span class="special">{</span> 250 <span class="keyword">public</span><span class="special">:</span> 251 <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span> 252 <span class="special">};</span> 253 254<span class="special">}}}</span> 255</pre> 256</div> 257<div class="section"> 258<div class="titlepage"><div><div><h4 class="title"> 259<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_expected_from_python_type" title="Class expected_from_python_type">Class 260 <code class="computeroutput"><span class="identifier">expected_from_python_type</span></code></a> 261</h4></div></div></div> 262<p> 263 This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code> 264 member which inspects the registered <code class="computeroutput"><span class="identifier">from_python</span></code> 265 converters for the type <code class="computeroutput"><span class="identifier">T</span></code> 266 and returns a matching python type. 267 </p> 268<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> 269 270 <span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> 271 <span class="keyword">class</span> <span class="identifier">expected_from_python_type</span> 272 <span class="special">{</span> 273 <span class="keyword">public</span><span class="special">:</span> 274 <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span> 275 <span class="special">};</span> 276 277<span class="special">}}}</span> 278</pre> 279</div> 280<div class="section"> 281<div class="titlepage"><div><div><h4 class="title"> 282<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.class_to_python_target_type" title="Class to_python_target_type">Class 283 <code class="computeroutput"><span class="identifier">to_python_target_type</span></code></a> 284</h4></div></div></div> 285<p> 286 This template generates a static <code class="computeroutput"><span class="identifier">get_pytype</span></code> 287 member returning the python type to which <code class="computeroutput"><span class="identifier">T</span></code> 288 can be converted. 289 </p> 290<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">converter</span><span class="special">{</span> 291 292 <span class="keyword">template</span> <span class="special"><</span> <span class="keyword">class</span> <span class="identifier">T</span> <span class="special">></span> 293 <span class="keyword">class</span> <span class="identifier">to_python_target_type</span> 294 <span class="special">{</span> 295 <span class="keyword">public</span><span class="special">:</span> 296 <span class="keyword">static</span> <span class="identifier">PyTypeObject</span> <span class="keyword">const</span> <span class="special">*</span><span class="identifier">get_pytype</span><span class="special">();</span> 297 <span class="special">};</span> 298 299<span class="special">}}}</span> 300</pre> 301</div> 302<div class="section"> 303<div class="titlepage"><div><div><h4 class="title"> 304<a name="function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example"></a><a class="link" href="function_documentation.html#function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example" title="Example">Example</a> 305</h4></div></div></div> 306<p> 307 This example presumes that someone has implemented the standard noddy 308 example module from the Python documentation, and placed the corresponding 309 declarations in "noddy.h". Because <code class="computeroutput"><span class="identifier">noddy_NoddyObject</span></code> 310 is the ultimate trivial extension type, the example is a bit contrived: 311 it wraps a function for which all information is contained in the type 312 of its return value. 313 </p> 314<p> 315 C++ module definition: 316 </p> 317<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 318<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 319<span class="preprocessor">#include</span> <span class="string">"noddy.h"</span> 320 321<span class="keyword">struct</span> <span class="identifier">tag</span> <span class="special">{};</span> 322<span class="identifier">tag</span> <span class="identifier">make_tag</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">tag</span><span class="special">();</span> <span class="special">}</span> 323 324<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> 325 326<span class="keyword">struct</span> <span class="identifier">tag_to_noddy</span> 327<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//unnecessary overhead if py signatures are not supported</span> 328<span class="special">:</span> <span class="identifier">wrap_pytype</span><span class="special"><&</span><span class="identifier">noddy_NoddyType</span><span class="special">></span> <span class="comment">//inherits get_pytype from wrap_pytype</span> 329<span class="preprocessor">#endif</span> 330<span class="special">{</span> 331 <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="identifier">tag</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">)</span> 332 <span class="special">{</span> 333 <span class="keyword">return</span> <span class="identifier">PyObject_New</span><span class="special">(</span><span class="identifier">noddy_NoddyObject</span><span class="special">,</span> <span class="special">&</span><span class="identifier">noddy_NoddyType</span><span class="special">);</span> 334 <span class="special">}</span> 335<span class="special">};</span> 336 337<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">to_python_converter</span><span class="special">)</span> 338<span class="special">{</span> 339 <span class="identifier">def</span><span class="special">(</span><span class="string">"make_tag"</span><span class="special">,</span> <span class="identifier">make_tag</span><span class="special">);</span> 340 <span class="identifier">to_python_converter</span><span class="special"><</span><span class="identifier">tag</span><span class="special">,</span> <span class="identifier">tag_to_noddy</span> 341<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span> 342 <span class="special">,</span> <span class="keyword">true</span> 343<span class="preprocessor">#endif</span> 344 <span class="special">>();</span> <span class="comment">//"true" because tag_to_noddy has member get_pytype</span> 345<span class="special">}</span> 346</pre> 347<p> 348 The following example registers to and from python converters using the 349 templates expected_from_python_type and to_pyhton_target_type. 350 </p> 351<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 352<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">def</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 353<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">extract</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 354<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">to_python_converter</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 355<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 356 357<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span> 358 359<span class="keyword">struct</span> <span class="identifier">A</span> 360<span class="special">{</span> 361<span class="special">};</span> 362 363<span class="keyword">struct</span> <span class="identifier">B</span> 364<span class="special">{</span> 365 <span class="identifier">A</span> <span class="identifier">a</span><span class="special">;</span> 366 <span class="identifier">B</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&</span> <span class="identifier">a_</span><span class="special">):</span><span class="identifier">a</span><span class="special">(</span><span class="identifier">a_</span><span class="special">){}</span> 367<span class="special">};</span> 368 369<span class="comment">// Converter from A to python int</span> 370<span class="keyword">struct</span> <span class="identifier">BToPython</span> 371<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//unnecessary overhead if py signatures are not supported</span> 372 <span class="special">:</span> <span class="identifier">converter</span><span class="special">::</span><span class="identifier">to_python_target_type</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> <span class="comment">//inherits get_pytype</span> 373<span class="preprocessor">#endif</span> 374<span class="special">{</span> 375 <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&</span> <span class="identifier">b</span><span class="special">)</span> 376 <span class="special">{</span> 377 <span class="keyword">return</span> <span class="identifier">incref</span><span class="special">(</span><span class="identifier">object</span><span class="special">(</span><span class="identifier">b</span><span class="special">.</span><span class="identifier">a</span><span class="special">).</span><span class="identifier">ptr</span><span class="special">());</span> 378 <span class="special">}</span> 379<span class="special">};</span> 380 381<span class="comment">// Conversion from python int to A</span> 382<span class="keyword">struct</span> <span class="identifier">BFromPython</span> 383<span class="special">{</span> 384 <span class="identifier">BFromPython</span><span class="special">()</span> 385 <span class="special">{</span> 386 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">registry</span><span class="special">::</span><span class="identifier">push_back</span> 387 <span class="special">(</span> <span class="special">&</span><span class="identifier">convertible</span> 388 <span class="special">,</span> <span class="special">&</span><span class="identifier">construct</span> 389 <span class="special">,</span> <span class="identifier">type_id</span><span class="special"><</span> <span class="identifier">B</span> <span class="special">>()</span> 390<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span> 391 <span class="special">,</span> <span class="special">&</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">expected_from_python_type</span><span class="special"><</span><span class="identifier">A</span><span class="special">>::</span><span class="identifier">get_pytype</span><span class="comment">//convertible to A can be converted to B</span> 392<span class="preprocessor">#endif</span> 393 <span class="special">);</span> 394 <span class="special">}</span> 395 396 <span class="keyword">static</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">convertible</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">)</span> 397 <span class="special">{</span> 398 <span class="identifier">extract</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&></span> <span class="identifier">ex</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span> 399 <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">ex</span><span class="special">.</span><span class="identifier">check</span><span class="special">())</span> <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 400 <span class="keyword">return</span> <span class="identifier">obj_ptr</span><span class="special">;</span> 401 <span class="special">}</span> 402 403 <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">construct</span><span class="special">(</span> 404 <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">obj_ptr</span><span class="special">,</span> 405 <span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_stage1_data</span><span class="special">*</span> <span class="identifier">data</span><span class="special">)</span> 406 <span class="special">{</span> 407 <span class="keyword">void</span><span class="special">*</span> <span class="identifier">storage</span> <span class="special">=</span> <span class="special">(</span> 408 <span class="special">(</span><span class="identifier">converter</span><span class="special">::</span><span class="identifier">rvalue_from_python_storage</span><span class="special"><</span> <span class="identifier">B</span> <span class="special">>*)</span><span class="identifier">data</span><span class="special">)-></span> <span class="identifier">storage</span><span class="special">.</span><span class="identifier">bytes</span><span class="special">;</span> 409 410 <span class="identifier">extract</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&></span> <span class="identifier">ex</span><span class="special">(</span><span class="identifier">obj_ptr</span><span class="special">);</span> 411 <span class="keyword">new</span> <span class="special">(</span><span class="identifier">storage</span><span class="special">)</span> <span class="identifier">B</span><span class="special">(</span><span class="identifier">ex</span><span class="special">());</span> 412 <span class="identifier">data</span><span class="special">-></span><span class="identifier">convertible</span> <span class="special">=</span> <span class="identifier">storage</span><span class="special">;</span> 413 <span class="special">}</span> 414<span class="special">};</span> 415 416 417<span class="identifier">B</span> <span class="identifier">func</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span> <span class="special">;</span> <span class="special">}</span> 418 419<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">pytype_function_ext</span><span class="special">)</span> 420<span class="special">{</span> 421 <span class="identifier">to_python_converter</span><span class="special"><</span> <span class="identifier">B</span> <span class="special">,</span> <span class="identifier">BToPython</span> 422<span class="preprocessor">#if</span> <span class="identifier">defined</span> <span class="identifier">BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</span> <span class="comment">//invalid if py signatures are not supported</span> 423 <span class="special">,</span><span class="keyword">true</span> 424<span class="preprocessor">#endif</span> 425 <span class="special">>();</span> <span class="comment">//has get_pytype</span> 426 <span class="identifier">BFromPython</span><span class="special">();</span> 427 428 <span class="identifier">class_</span><span class="special"><</span><span class="identifier">A</span><span class="special">>(</span><span class="string">"A"</span><span class="special">)</span> <span class="special">;</span> 429 430 <span class="identifier">def</span><span class="special">(</span><span class="string">"func"</span><span class="special">,</span> <span class="special">&</span><span class="identifier">func</span><span class="special">);</span> 431 432<span class="special">}</span> 433 434 435 436<span class="special">>>></span> <span class="identifier">from</span> <span class="identifier">pytype_function_ext</span> <span class="identifier">import</span> <span class="special">*</span> 437<span class="special">>>></span> <span class="identifier">print</span> <span class="identifier">func</span><span class="special">.</span><span class="identifier">__doc__</span> 438<span class="identifier">func</span><span class="special">(</span> <span class="special">(</span><span class="identifier">A</span><span class="special">)</span><span class="identifier">arg1</span><span class="special">)</span> <span class="special">-></span> <span class="identifier">A</span> <span class="special">:</span> 439 <span class="identifier">C</span><span class="special">++</span> <span class="identifier">signature</span><span class="special">:</span> 440 <span class="keyword">struct</span> <span class="identifier">B</span> <span class="identifier">func</span><span class="special">(</span><span class="keyword">struct</span> <span class="identifier">B</span><span class="special">)</span> 441</pre> 442</div> 443</div> 444</div> 445<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 446<td align="left"></td> 447<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 448 Distributed under the Boost Software License, Version 1.0. (See accompanying 449 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> 450 </p> 451</div></td> 452</tr></table> 453<hr> 454<div class="spirit-nav"> 455<a accesskey="p" href="boost_python_raw_function_hpp.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_callpolicies.html"><img src="../../images/next.png" alt="Next"></a> 456</div> 457</body> 458</html> 459
