Skip to content

Commit 5809078

Browse files
author
Ralf W. Grosse-Kunstleve
committed
Patches by Nikolay Mladenov (nickm at sitius com): new pythonic signatures; docstring support for enums; fix unrelated Visual C++ 6 problem
[SVN r39191]
1 parent 04e54d6 commit 5809078

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+2525
-343
lines changed

‎build/Jamfile.v2‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ lib boost_python
4545
wrapper.cpp
4646
import.cpp
4747
exec.cpp
48+
object/function_doc_signature.cpp
4849
: # requirements
4950
<link>static:<define>BOOST_PYTHON_STATIC_LIB
5051
<define>BOOST_PYTHON_SOURCE

‎doc/news.html‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,43 @@ <h2 align="center">News/Change Log</h2>
3232
<hr>
3333

3434
<dl class="page-index">
35-
<dt>Current CVS</dt>
35+
<dt>Current SVN</dt>
36+
37+
<dd>
38+
<ul>
39+
<li>Pythonic signatures are now automatically appended to the
40+
docstrings.
41+
42+
<li>Use <a href="v2/docstring_options.html"
43+
><code>docstring_options.hpp</code></a> header
44+
control the content of docstrings.
45+
46+
<li>This new feature increases the size of the modules by about 14%.
47+
If this is not acceptable it can be turned off by defining the macro
48+
BOOST_PYTHON_NO_PY_SIGNATURES. Modules compiled with and without the macro
49+
defined are compatible.
50+
</li>
51+
<li> If BOOST_PYTHON_NO_PY_SIGNATURES is undefined, this version defines the
52+
macro BOOST_PYTHON_SUPPORTS_PY_SIGNATURES. This allows writing code that will compile
53+
with older version of Boost.Python (see <a href="v2/pytype_function.html#examples">here</a>).
54+
</li>
55+
<li>By defining BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE, and at a cost
56+
of another 14% size increase, proper pythonic type is generated for the "self"
57+
parameter of the __init__ methods.
58+
</li>
59+
60+
<li> To support this new feature changes were made to the
61+
<a href="v2/to_python_converter.html"><code>to_python_converter.hpp</code></a>,
62+
<a href="v2/default_call_policies.html"><code>default_call_policies</code></a>,
63+
<a href="v2/ResultConverter.html"><code>ResultConverter</code></a>,
64+
<a href="v2/CallPolicies.html"><code>CallPolicies</code></a> and some others.
65+
Efforts were made not to have interface breaking changes.
66+
</li>
67+
68+
</ul>
69+
</dd>
70+
71+
<dt>12 May 2007 - 1.34.0 release</dt>
3672

3773
<dd>
3874
<ul>

‎doc/v2/CallPolicies.html‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<meta name="generator" content=
99
"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
1010
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11-
<link rel="stylesheet" type="text/css" href=../../../../boost.css>
11+
<link rel="stylesheet" type="text/css" href="../../../../boost.css">
1212

1313
<title>Boost.Python - CallPolicies Concept</title>
1414
</head>
@@ -60,6 +60,7 @@ <h2><a name="introduction"></a>Introduction</h2>
6060

6161
<li><code>postcall</code> - Python argument tuple and result management
6262
after the wrapped object is invoked</li>
63+
<li><code>extract_return_type</code> - metafunction for extracting the return type from a given signature type sequence</li>
6364
</ol>
6465

6566
<h2><a name="composition"></a>CallPolicies Composition</h2>
@@ -132,7 +133,16 @@ <h3><a name="CallPolicies-concept"></a>CallPolicies Concept</h3>
132133
reference count must be decremented; if another existing object is
133134
returned, its reference count must be incremented.</td>
134135
</tr>
135-
</table>
136+
<tr>
137+
<td valign="top"><code>P::extract_return_type</code></td>
138+
139+
<td>A model of <a href=
140+
"../../../doc/refmanual/metafunction.html">Metafunction</a>.</td>
141+
142+
<td>An MPL unary <a href=
143+
"../../../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>
144+
</tr>
145+
</table>
136146
Models of CallPolicies are required to be <a href=
137147
"../../../utility/CopyConstructible.html">CopyConstructible</a>.
138148
<hr>

‎doc/v2/ResultConverter.html‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2+
13
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
24
<!-- Software License, Version 1.0. (See accompanying -->
35
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
46
<html>
57
<head>
68
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7-
<link rel="stylesheet" type="text/css" href=../../../../boost.css>
9+
<link rel="stylesheet" type="text/css" href="../../../../boost.css">
810
<title>Boost.Python - ResultConverter Concept</title>
911
</head>
1012
<body link="#0000ff" vlink="#800080">
@@ -24,10 +26,12 @@ <h2 align="center">ResultConverter Concept</h2>
2426
<dl class="page-index">
2527
<dt><a href="#introduction">Introduction</a></dt>
2628
<dt><a href="#concept-requirements">Concept Requirements</a></dt>
27-
<dl class="page-index">
28-
<dt><a href="#ResultConverter-concept">ResultConverter Concept</a></dt>
29-
<dt><a href="#ResultConverterGenerator-concept">ResultConverterGenerator Concept</a></dt>
30-
</dl>
29+
<dd>
30+
<dl class="page-index">
31+
<dt><a href="#ResultConverter-concept">ResultConverter Concept</a></dt>
32+
<dt><a href="#ResultConverterGenerator-concept">ResultConverterGenerator Concept</a></dt>
33+
</dl>
34+
</dd>
3135
</dl>
3236

3337
<h2><a name="introduction"></a>Introduction</h2>
@@ -79,6 +83,13 @@ <h3><a name="ResultConverter-concept"></a>ResultConverter Concept</h3>
7983
href="http://www.python.org/doc/current/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>
8084
should return non-zero.</td>
8185
</tr>
86+
<tr>
87+
<td valign="top"><code>c.get_pytype()</code></td>
88+
<td><code>PyTypeObject const*</code></td>
89+
<td>A pointer to a Python Type object corresponding to result of the conversion,
90+
or <code>0</code>. Used for documentation generation. If <code>0</code> is returned
91+
the generated type in the documentation will be <b>object</b> .</td>
92+
</tr>
8293
</table>
8394

8495
<h3><a name="ResultConverterGenerator-concept"></a>ResultConverterGenerator Concept</h3>

‎doc/v2/configuration.html‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,41 @@ <h2><a name="lib-defined-impl"></a>Library Defined Implementation
139139
compares <code>typeid(T).name()</code> instead of using and comparing
140140
the <code>std::type_info</code> objects directly.</td>
141141
</tr>
142+
<tr>
143+
<td valign="top"><code>BOOST_PYTHON_NO_PY_SIGNATURES</code></td>
144+
145+
<td valign="top" align="center"><i>not&nbsp;defined</i></td>
146+
147+
<td valign="top">If defined for a module no pythonic signatures are generated
148+
for the docstrings of the module functions, and no python type is associated with any
149+
of the converters registered by the module. This also reduces the binary size of the
150+
module by about 14% (gcc compiled).<br>
151+
If defined for the boost_python runtime library, the default for the
152+
<code>docstring_options.enable_py_signatures()</code> is set to <code>false</code>.
153+
</td>
154+
155+
</tr>
156+
<tr>
157+
<td valign="top"><code>BOOST_PYTHON_SUPPORTS_PY_SIGNATURES</code></td>
158+
159+
<td valign="top" align="center"><i>defined if <code>BOOST_PYTHON_NO_PY_SIGNATURES</code> is undefined</i></td>
160+
161+
<td valign="top">This macro is defined to enable a smooth transition from older Boost.Python versions
162+
which do not support pythonic signatures. For example usage see
163+
<a href="pytype_function.html#examples">here</a>.
164+
</td>
165+
166+
</tr>
167+
<tr>
168+
<td valign="top"><code>BOOST_PYTHON_PY_SIGNATURES_PROPER_INIT_SELF_TYPE</code></td>
169+
170+
<td valign="top" align="center"><i>not&nbsp;defined</i></td>
171+
172+
<td valign="top">If defined the python type of <code>__init__</code> method "self" parameters
173+
is properly generated, otherwise <code><b>object</b></code> is used. It is undefined
174+
by default because it increases the binary size of the module by about 14% (gcc compiled).</td>
175+
176+
</tr>
142177
</table>
143178
<hr>
144179

‎doc/v2/default_call_policies.html‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ <h4><a name="default_call_policies-spec-synopsis"></a>Class
8282
static PyObject* postcall(PyObject*, PyObject* result);
8383
typedef <a href=
8484
"#default_result_converter-spec">default_result_converter</a> result_converter;
85+
template &lt;class Sig&gt; struct extract_return_type : mpl::front&lt;Sig&gt;{};
8586
};
8687
}}
8788
</pre>
@@ -161,7 +162,7 @@ <h2><a name="examples"></a>Example</h2>
161162

162163
<p>Revised
163164
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
164-
13 November, 2002
165+
11 June, 2007
165166
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
166167

167168

‎doc/v2/docstring_options.html‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,8 @@ <h4><a name="docstring_options-spec-synopsis" id=
103103

104104
docstring_options(bool show_user_defined, bool show_signatures);
105105

106+
docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures);
107+
106108
~docstring_options();
107109

108110
void
@@ -117,6 +119,18 @@ <h4><a name="docstring_options-spec-synopsis" id=
117119
void
118120
enable_signatures();
119121

122+
void
123+
disable_py_signatures();
124+
125+
void
126+
enable_py_signatures();
127+
128+
void
129+
disable_cpp_signatures();
130+
131+
void
132+
enable_cpp_signatures();
133+
120134
void
121135
disable_all();
122136

@@ -139,7 +153,7 @@ <h4><a name="docstring_options-spec-ctors" id=
139153
object which controls the appearance of function and
140154
member-function docstrings defined in the code that follows. If
141155
<code>show_all</code> is <code>true</code>, both the
142-
user-defined docstrings and the automatically generated C++
156+
user-defined docstrings and the automatically generated Python and C++
143157
signatures are shown. If <code>show_all</code> is
144158
<code>false</code> the <code>__doc__</code> attributes are
145159
<code>None</code>.</dt>
@@ -154,12 +168,29 @@ <h4><a name="docstring_options-spec-ctors" id=
154168
member-function docstrings defined in the code that follows.
155169
Iff <code>show_user_defined</code> is <code>true</code>, the
156170
user-defined docstrings are shown. Iff
157-
<code>show_signatures</code> is <code>true</code>, C++
171+
<code>show_signatures</code> is <code>true</code>, Python and C++
158172
signatures are automatically added. If both
159173
<code>show_user_defined</code> and <code>show_signatures</code>
160174
are <code>false</code>, the <code>__doc__</code> attributes are
161175
<code>None</code>.</dt>
162176
</dl>
177+
<pre>
178+
docstring_options(bool show_user_defined, bool show_py_signatures, bool show_cpp_signatures);
179+
</pre>
180+
181+
<dl class="function-semantics">
182+
<dt><b>Effects:</b> Constructs a <code>docstring_options</code>
183+
object which controls the appearance of function and
184+
member-function docstrings defined in the code that follows.
185+
Iff <code>show_user_defined</code> is <code>true</code>, the
186+
user-defined docstrings are shown. Iff
187+
<code>show_py_signatures</code> is <code>true</code>, Python
188+
signatures are automatically added. Iff
189+
<code>show_cpp_signatures</code> is <code>true</code>, C++
190+
signatures are automatically added. If all parameters are
191+
<code>false</code>, the <code>__doc__</code> attributes are
192+
<code>None</code>.</dt>
193+
</dl>
163194

164195
<h4><a name="docstring_options-spec-dtors" id=
165196
"docstring_options-spec-dtors"></a>Class
@@ -186,6 +217,10 @@ <h4><a name="docstring_options-spec-modifiers" id=
186217
void enable_user_defined();
187218
void disable_signatures();
188219
void enable_signatures();
220+
void disable_py_signatures();
221+
void enable_py_signatures();
222+
void disable_cpp_signatures();
223+
void enable_cpp_signatures();
189224
void disable_all();
190225
void enable_all();
191226
</pre>
@@ -196,7 +231,7 @@ <h4><a name="docstring_options-spec-modifiers" id=
196231
<code>*_user_defined()</code> and <code>*_signatures()</code>
197232
member functions are provided for fine-grained control. The
198233
<code>*_all()</code> member functions are convenient shortcuts
199-
to manipulate both settings simultaneously.</dt>
234+
to manipulate all settings simultaneously.</dt>
200235
</dl>
201236

202237
<h2><a name="examples" id="examples"></a>Examples</h2>
@@ -219,7 +254,7 @@ <h4>Docstring options defined at compile time</h4>
219254
<pre>
220255
&gt;&gt;&gt; import demo
221256
&gt;&gt;&gt; print demo.foo.__doc__
222-
foo doc
257+
foo() -&gt; None : foo doc
223258
C++ signature:
224259
foo(void) -&gt; void
225260
</pre>If compiled with
@@ -253,21 +288,33 @@ <h4>Selective suppressions</h4>
253288
def("foo3", foo3, arg("f"), "foo3 doc");
254289
doc_options.enable_user_defined();
255290
def("foo4", foo4, arg("d"), "foo4 doc");
291+
doc_options.enable_py_signatures();
292+
def("foo5", foo4, arg("d"), "foo5 doc");
293+
doc_options.disable_py_signatures();
294+
doc_options.enable_cpp_signatures();
295+
def("foo6", foo4, arg("d"), "foo6 doc");
256296
}
257297
</pre>Python code:
258298
<pre>
259299
&gt;&gt;&gt; import demo
260300
&gt;&gt;&gt; print demo.foo1.__doc__
261-
foo1 doc
301+
foo1( (int)i) -&gt; int : foo1 doc
262302
C++ signature:
263303
foo1(int i) -&gt; int
264304
&gt;&gt;&gt; print demo.foo2.__doc__
305+
foo2( (int)l) -&gt; int :
265306
C++ signature:
266307
foo2(long l) -&gt; int
267308
&gt;&gt;&gt; print demo.foo3.__doc__
268309
None
269310
&gt;&gt;&gt; print demo.foo4.__doc__
270311
foo4 doc
312+
&gt;&gt;&gt; print demo.foo5.__doc__
313+
foo5( (float)d) -&gt; int : foo5 doc
314+
&gt;&gt;&gt; print demo.foo6.__doc__
315+
foo6 doc
316+
C++ signature:
317+
foo6(double d) -&gt; int
271318
</pre>
272319

273320
<h4>Wrapping from multiple C++ scopes</h4>

‎doc/v2/enum.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ <h4><a name="enum_-spec-synopsis"></a>Class template <code>enum_</code>
8989
template &lt;class T&gt;
9090
class enum_ : public <a href="object.html#object-spec">object</a>
9191
{
92-
enum_(char const* name);
92+
enum_(char const* name, char const* doc = 0);
9393
enum_&lt;T&gt;&amp; value(char const* name, T);
9494
enum_&lt;T&gt;&amp; export_values();
9595
};
@@ -99,7 +99,7 @@ <h4><a name="enum_-spec-synopsis"></a>Class template <code>enum_</code>
9999
<h4><a name="enum_-spec-ctors"></a>Class template <code>enum_</code>
100100
constructors</h4>
101101
<pre>
102-
enum_(char const* name);
102+
enum_(char const* name, char const* doc=0);
103103
</pre>
104104

105105
<dl class="function-semantics">
@@ -131,7 +131,7 @@ <h4><a name="enum_-spec-modifiers"></a>Class template
131131

132132
<dt><b>Effects:</b> adds an instance of the wrapped enumeration
133133
type with value <code>x</code> to the type's dictionary as the
134-
<code>name</code>d attribute</dt>.
134+
<code>name</code>d attribute.</dt>
135135

136136
<dt><b>Returns:</b> <code>*this</code></dt>
137137

@@ -146,7 +146,7 @@ <h4><a name="enum_-spec-modifiers"></a>Class template
146146
<dt><b>Effects:</b> sets attributes in the current <a
147147
href="scope.html#scope-spec"><code>scope</code></a> with the
148148
same names and values as all enumeration values exposed so far
149-
by calling <code>value()</code></dt>.
149+
by calling <code>value()</code>.</dt>
150150

151151
<dt><b>Returns:</b> <code>*this</code></dt>
152152

0 commit comments

Comments
 (0)