[Boost-commit] svn:boost r76421 - in trunk/libs/python/doc/tutorial/doc: . html html/python

Subject: [Boost-commit] svn:boost r76421 - in trunk/libs/python/doc/tutorial/doc: . html html/python
From: dnljms_at_[hidden]
Date: 2012-01-11 18:07:02

Author: danieljames
Date: 2012-01-11 18:07:01 EST (Wed, 11 Jan 2012)
New Revision: 76421
URL: http://svn.boost.org/trac/boost/changeset/76421

Log:
Document 'Creating `boost::python::object` from `PyObject*`'.

>From Pedro Larroy. Fixes #6393.
Text files modified: 
   trunk/libs/python/doc/tutorial/doc/html/index.html         |     3 ++-                                     
   trunk/libs/python/doc/tutorial/doc/html/python/object.html |    27 +++++++++++++++++++++++++++             
   trunk/libs/python/doc/tutorial/doc/tutorial.qbk            |    17 +++++++++++++++++                       
   3 files changed, 46 insertions(+), 1 deletions(-)

Modified: trunk/libs/python/doc/tutorial/doc/html/index.html
==============================================================================
--- trunk/libs/python/doc/tutorial/doc/html/index.html	(original)
+++ trunk/libs/python/doc/tutorial/doc/html/index.html	2012-01-11 18:07:01 EST (Wed, 11 Jan 2012)
@@ -66,6 +66,7 @@
 <dt><span class="section">Derived Object types</span></dt>
 <dt><span class="section">Extracting C++ objects</span></dt>
 <dt><span class="section">Enums</span></dt>
+<dt><span class="section">Creating boost::python::object from PyObject*</span></dt>
 </dl></dd>
 <dt><span class="section">Embedding</span></dt>
 <dd><dl><dt><span class="section">Using the interpreter</span></dt></dl></dd>
@@ -132,7 +133,7 @@
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: December 26, 2011 at 21:51:27 GMT</small></p></td>
+<td align="left"><p><small>Last revised: December 26, 2011 at 21:58:39 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

Modified: trunk/libs/python/doc/tutorial/doc/html/python/object.html
==============================================================================
--- trunk/libs/python/doc/tutorial/doc/html/python/object.html	(original)
+++ trunk/libs/python/doc/tutorial/doc/html/python/object.html	2012-01-11 18:07:01 EST (Wed, 11 Jan 2012)
@@ -30,6 +30,7 @@
 <dt><span class="section">Derived Object types</span></dt>
 <dt><span class="section">Extracting C++ objects</span></dt>
 <dt><span class="section">Enums</span></dt>
+<dt><span class="section">Creating boost::python::object from PyObject*</span></dt>
 </dl></div>
 <p>
       Python is dynamically typed, unlike C++ which is statically typed. Python variables
@@ -314,6 +315,32 @@
     <span class="special">;</span>
 </pre>
 </div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="python.creating_python_object"></a>Creating <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> from <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code>
+</h3></div></div></div>
+<p>
+        When you want a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span></code> to manage a pointer to <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code>
+        pyobj one does:
+      </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">o</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">handle</span><span class="special">&lt;&gt;(</span><span class="identifier">pyobj</span><span class="special">));</span>
+</pre>
+<p>
+        In this case, the <code class="computeroutput"><span class="identifier">o</span></code> object,
+        manages the <code class="computeroutput"><span class="identifier">pyobj</span></code>, it won&#8217;t
+        increase the reference count on construction.
+      </p>
+<p>
+        Otherwise, to use a borrowed reference:
+      </p>
+<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">object</span> <span class="identifier">o</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">handle</span><span class="special">&lt;&gt;(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">::</span><span class="identifier">borrowed</span><span class="special">(</span><span class="identifier">pyobj</span><span class="special">)));</span>
+</pre>
+<p>
+        In this case, <code class="computeroutput"><span class="identifier">Py_INCREF</span></code> is
+        called, so <code class="computeroutput"><span class="identifier">pyobj</span></code> is not destructed
+        when object o goes out of scope.
+      </p>
+</div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>

Modified: trunk/libs/python/doc/tutorial/doc/tutorial.qbk
==============================================================================
--- trunk/libs/python/doc/tutorial/doc/tutorial.qbk	(original)
+++ trunk/libs/python/doc/tutorial/doc/tutorial.qbk	2012-01-11 18:07:01 EST (Wed, 11 Jan 2012)
@@ -1302,6 +1302,23 @@
 [def PyModule_GetDict       [@http://www.python.org/doc/current/api/moduleObjects.html#l2h-594   PyModule_GetDict]]
 
 [endsect]
+
+[section:creating_python_object Creating `boost::python::object` from `PyObject*`]
+
+When you want a `boost::python::object` to manage a pointer to `PyObject*` pyobj one does:
+
+    boost::python::object o(boost::python::handle<>(pyobj));
+
+In this case, the `o` object, manages the `pyobj`, it won’t increase the reference count on construction.
+
+Otherwise, to use a borrowed reference:
+
+    boost::python::object o(boost::python::handle<>(boost::python::borrowed(pyobj)));
+
+In this case, `Py_INCREF` is called, so `pyobj` is not destructed when object o goes out of scope.
+
+[endsect] [/ creating_python_object ]
+
 [endsect] [/ Object Interface]
 
 [section Embedding]