boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-27 07:02:15 +00:00
Code Issues Projects Releases Wiki Activity
Files
1102fec2a022032923803b4a8ad692562de48410
python/doc/tutorial/doc/creating_packages.html
Bruno da Silva de Oliveira bc92a7d155 - added new "General Techniques" section 
[SVN r20927]
2003-11-23 21:24:54 +00:00

211 lines
13 KiB
HTML
Raw Blame History

<html>
<head>
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
<title>Creating Packages</title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
<link rel="prev" href="general_techniques.html">
<link rel="next" href="extending_wrapped_objects_in_python.html">
</head>
<body>
<table width="100%" height="48" border="0" cellspacing="2">
<tr>
<td><img src="theme/c%2B%2Bboost.gif">
</td>
<td width="85%">
<font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Creating Packages</b></font>
</td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="general_techniques.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><a href="extending_wrapped_objects_in_python.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>
A Python package is a collection of modules that provide to the user a certain
functionality. If you're not familiar on how to create packages, a good
introduction to them is provided in the
<a href="http://www.python.org/doc/current/tut/node8.html">
Python Tutorial</a>.</p>
<p>
But we are wrapping C++ code, using Boost.Python. How can we provide a nice
package interface to our users? To better explain some concepts, let's work
with an example.</p>
<p>
We have a C++ library that works with sounds: reading and writing various
formats, applying filters to the sound data, etc. It is named (conveniently)
<tt>sounds</tt>. Our library already has a neat C++ namespace hierarchy, like so: </p>
<code><pre>
<span class=identifier>sounds</span><span class=special>::</span><span class=identifier>core
</span><span class=identifier>sounds</span><span class=special>::</span><span class=identifier>io
</span><span class=identifier>sounds</span><span class=special>::</span><span class=identifier>filters
</span></pre></code>
<p>
We would like to present this same hierarchy to the Python user, allowing him
to write code like this:</p>
<code><pre>
<span class=identifier>import </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters
</span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters</span><span class=special>.</span><span class=identifier>echo</span><span class=special>(...) </span>##<span class=identifier>echo </span><span class=identifier>is </span><span class=identifier>a </span><span class=identifier>C</span><span class=special>++ </span><span class=identifier>function
</span></pre></code>
<p>
The first step is to write the wrapping code. We have to export each module
separately with Boost.Python, like this:</p>
<code><pre>
<span class=comment>/* file core.cpp */
</span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>core</span><span class=special>)
{
/* </span><span class=keyword>export </span><span class=identifier>everything </span><span class=identifier>in </span><span class=identifier>the </span><span class=identifier>sounds</span><span class=special>::</span><span class=identifier>core </span><span class=keyword>namespace </span><span class=special>*/
...
}
/* </span><span class=identifier>file </span><span class=identifier>io</span><span class=special>.</span><span class=identifier>cpp </span><span class=special>*/
</span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>io</span><span class=special>)
{
/* </span><span class=keyword>export </span><span class=identifier>everything </span><span class=identifier>in </span><span class=identifier>the </span><span class=identifier>sounds</span><span class=special>::</span><span class=identifier>io </span><span class=keyword>namespace </span><span class=special>*/
...
}
/* </span><span class=identifier>file </span><span class=identifier>filters</span><span class=special>.</span><span class=identifier>cpp </span><span class=special>*/
</span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>filters</span><span class=special>)
{
/* </span><span class=keyword>export </span><span class=identifier>everything </span><span class=identifier>in </span><span class=identifier>the </span><span class=identifier>sounds</span><span class=special>::</span><span class=identifier>filters </span><span class=keyword>namespace </span><span class=special>*/
...
}
</span></pre></code>
<p>
Compiling these files will generate the following Python extensions:
<tt>core.pyd</tt>, <tt>io.pyd</tt> and <tt>filters.pyd</tt>.</p>
<table width="80%" border="0" align="center">
<tr>
<td class="note_box">
<img src="theme/note.gif"></img> The extension <tt>.pyd</tt> is used for python extension modules, which
are just shared libraries. Using the default for your system, like <tt>.so</tt> for
Unix and <tt>.dll</tt> for Windows, works just as well. </td>
</tr>
</table>
<p>
Now, we create this directory structure for our Python package:</p>
<code><pre>
sounds/
__init__.py
core.pyd
filters.pyd
io.pyd
</pre></code><p>
The file <tt>__init__.py</tt> is what tells Python that the directory <tt>sounds/</tt> is
actually a Python package. It can be a empty file, but can also perform some
magic, that will be shown later. </p>
<p>
Now our package is ready. All the user has to do is put <tt>sounds</tt> into his
<a href="http://www.python.org/doc/current/tut/node8.html#SECTION008110000000000000000">
PYTHONPATH</a> and fire up the interpreter:</p>
<code><pre>
<span class=special>&gt;&gt;&gt; </span><span class=identifier>import </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>io
</span><span class=special>&gt;&gt;&gt; </span><span class=identifier>import </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters
</span><span class=special>&gt;&gt;&gt; </span><span class=identifier>sound </span><span class=special>= </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>io</span><span class=special>.</span><span class=identifier>open</span><span class=special>(</span><span class=literal>'file.mp3'</span><span class=special>)
&gt;&gt;&gt; </span><span class=identifier>new_sound </span><span class=special>= </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters</span><span class=special>.</span><span class=identifier>echo</span><span class=special>(</span><span class=identifier>sound</span><span class=special>, </span><span class=number>1.0</span><span class=special>)
</span></pre></code>
<p>
Nice heh? </p>
<p>
This is the simplest way to create hierarchies of packages, but it is not very
flexible. What if we want to add a <i>pure</i> Python function to the filters
package, for instance, one that applies 3 filters in a sound object at once?
Sure, you can do this in C++ and export it, but why not do so in Python? You
don't have to recompile the extension modules, plus it will be easier to write
it.</p>
<p>
If we want this flexibility, we will have to complicate our package hierarchy a
little. First, we will have to change the name of the extension modules:</p>
<code><pre>
<span class=comment>/* file core.cpp */
</span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>_core</span><span class=special>)
{
...
/* </span><span class=keyword>export </span><span class=identifier>everything </span><span class=identifier>in </span><span class=identifier>the </span><span class=identifier>sounds</span><span class=special>::</span><span class=identifier>core </span><span class=keyword>namespace </span><span class=special>*/
}
</span></pre></code>
<p>
Note that we added an underscore to the module name. The filename will have to
be changed to <tt>_core.pyd</tt> as well, and we do the same to the other extension modules.
Now, we change our package hierarchy like so:</p>
<code><pre>
sounds/
__init__.py
core/
__init__.py
_core.pyd
filters/
__init__.py
_filters.pyd
io/
__init__.py
_io.pyd
</pre></code><p>
Note that we created a directory for each extension module, and added a
__init__.py to each one. But if we leave it that way, the user will have to
access the functions in the core module with this syntax: </p>
<code><pre>
<span class=special>&gt;&gt;&gt; </span><span class=identifier>import </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>core</span><span class=special>.</span><span class=identifier>_core
</span><span class=special>&gt;&gt;&gt; </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>core</span><span class=special>.</span><span class=identifier>_core</span><span class=special>.</span><span class=identifier>foo</span><span class=special>(...)
</span></pre></code>
<p>
which is not what we want. But here enters the <tt>__init__.py</tt> magic: everything
that is brought to the <tt>__init__.py</tt> namespace can be accessed directly by the
user. So, all we have to do is bring the entire namespace from <tt>_core.pyd</tt>
to <tt>core/__init__.py</tt>. So add this line of code to <tt>sounds/core/__init__.py</tt>:</p>
<code><pre>
<span class=identifier>from </span><span class=identifier>_core </span><span class=identifier>import </span><span class=special>*
</span></pre></code>
<p>
We do the same for the other packages. Now the user accesses the functions and
classes in the extension modules like before:</p>
<code><pre>
<span class=special>&gt;&gt;&gt; </span><span class=identifier>import </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters
</span><span class=special>&gt;&gt;&gt; </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters</span><span class=special>.</span><span class=identifier>echo</span><span class=special>(...)
</span></pre></code>
<p>
with the additional benefit that we can easily add pure Python functions to
any module, in a way that the user can't tell the difference between a C++
function and a Python function. Let's add a <i>pure</i> Python function,
<tt>echo_noise</tt>, to the <tt>filters</tt> package. This function applies both the
<tt>echo</tt> and <tt>noise</tt> filters in sequence in the given <tt>sound</tt> object. We
create a file named <tt>sounds/filters/echo_noise.py</tt> and code our function:</p>
<code><pre>
<span class=identifier>import </span><span class=identifier>_filters
</span><span class=identifier>def </span><span class=identifier>echo_noise</span><span class=special>(</span><span class=identifier>sound</span><span class=special>):
</span><span class=identifier>s </span><span class=special>= </span><span class=identifier>_filters</span><span class=special>.</span><span class=identifier>echo</span><span class=special>(</span><span class=identifier>sound</span><span class=special>)
</span><span class=identifier>s </span><span class=special>= </span><span class=identifier>_filters</span><span class=special>.</span><span class=identifier>noise</span><span class=special>(</span><span class=identifier>sound</span><span class=special>)
</span><span class=keyword>return </span><span class=identifier>s
</span></pre></code>
<p>
Next, we add this line to <tt>sounds/filters/__init__.py</tt>:</p>
<code><pre>
<span class=identifier>from </span><span class=identifier>echo_noise </span><span class=identifier>import </span><span class=identifier>echo_noise
</span></pre></code>
<p>
And that's it. The user now accesses this function like any other function
from the <tt>filters</tt> package:</p>
<code><pre>
<span class=special>&gt;&gt;&gt; </span><span class=identifier>import </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters
</span><span class=special>&gt;&gt;&gt; </span><span class=identifier>sounds</span><span class=special>.</span><span class=identifier>filters</span><span class=special>.</span><span class=identifier>echo_noise</span><span class=special>(...)
</span></pre></code>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="general_techniques.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><a href="extending_wrapped_objects_in_python.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright &copy; 2002-2003 David Abrahams<br>Copyright &copy; 2002-2003 Joel de Guzman<br><br>
<font size="2">Permission to copy, use, modify, sell and distribute this document
is granted provided this copyright notice appears in all copies. This document
is provided &quot;as is&quot; without express or implied warranty, and with
no claim as to its suitability for any purpose. </font> </p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink