jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merged with recent changes from trunk.

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-maciekd@11187 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Maciej Drwal 2009-04-11 16:46:47 +00:00
commit 8c74fa0f46
703 changed files with 21126 additions and 9266 deletions
Download patch file Download diff file Expand all files Collapse all files

410
Doc/Manual/Python.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Python"></a>30 SWIG and Python</H1>
<H1><a name="Python"></a>31 SWIG and Python</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -46,7 +46,7 @@
<li><a href="#Python_nn30">Memory management</a>
<li><a href="#Python_nn31">Python 2.2 and classic classes</a>
</ul>
<li><a href="#directors">Cross language polymorphism</a>
<li><a href="#Python_directors">Cross language polymorphism</a>
<ul>
<li><a href="#Python_nn33">Enabling directors</a>
<li><a href="#Python_nn34">Director classes</a>
@ -101,6 +101,12 @@
<li><a href="#Python_nn71">%feature("docstring")</a>
</ul>
<li><a href="#Python_nn72">Python Packages</a>
<li><a href="#Python_python3support">Python 3 Support</a>
<ul>
<li><a href="#Python_nn74">Function annotation</a>
<li><a href="#Python_nn75">Buffer interface</a>
<li><a href="#Python_nn76">Abstract base classes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -113,9 +119,9 @@
<p>
This chapter describes SWIG's support of Python. SWIG is compatible
with most recent Python versions including Python 2.2 as well as older
versions dating back to Python 1.5.2. For the best results, consider using Python
2.0 or newer.
with most recent Python versions including Python 3.0 and Python 2.6,
as well as older versions dating back to Python 2.0. For the best results,
consider using Python 2.3 or newer.
</p>
<p>
@ -125,7 +131,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG
Basics</a>" chapter.
</p>
<H2><a name="Python_nn2"></a>30.1 Overview</H2>
<H2><a name="Python_nn2"></a>31.1 Overview</H2>
<p>
@ -152,10 +158,10 @@ described followed by a discussion of low-level implementation
details.
</p>
<H2><a name="Python_nn3"></a>30.2 Preliminaries</H2>
<H2><a name="Python_nn3"></a>31.2 Preliminaries</H2>
<H3><a name="Python_nn4"></a>30.2.1 Running SWIG</H3>
<H3><a name="Python_nn4"></a>31.2.1 Running SWIG</H3>
<p>
@ -253,7 +259,7 @@ The following sections have further practical examples and details on
how you might go about compiling and using the generated files.
</p>
<H3><a name="Python_nn6"></a>30.2.2 Using distutils</H3>
<H3><a name="Python_nn6"></a>31.2.2 Using distutils</H3>
<p>
@ -345,7 +351,7 @@ This same approach works on all platforms if the appropriate compiler is install
can even build extensions to the standard Windows Python using MingGW)
</p>
<H3><a name="Python_nn7"></a>30.2.3 Hand compiling a dynamic module</H3>
<H3><a name="Python_nn7"></a>31.2.3 Hand compiling a dynamic module</H3>
<p>
@ -393,7 +399,7 @@ module actually consists of two files; <tt>socket.py</tt> and
</p>
<H3><a name="Python_nn8"></a>30.2.4 Static linking</H3>
<H3><a name="Python_nn8"></a>31.2.4 Static linking</H3>
<p>
@ -472,7 +478,7 @@ If using static linking, you might want to rely on a different approach
(perhaps using distutils).
</p>
<H3><a name="Python_nn9"></a>30.2.5 Using your module</H3>
<H3><a name="Python_nn9"></a>31.2.5 Using your module</H3>
<p>
@ -629,7 +635,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Python_nn10"></a>30.2.6 Compilation of C++ extensions</H3>
<H3><a name="Python_nn10"></a>31.2.6 Compilation of C++ extensions</H3>
<p>
@ -728,7 +734,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Python_nn11"></a>30.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Python_nn11"></a>31.2.7 Compiling for 64-bit platforms</H3>
<p>
@ -765,7 +771,7 @@ and -m64 allow you to choose the desired binary format for your python
extension.
</p>
<H3><a name="Python_nn12"></a>30.2.8 Building Python Extensions under Windows</H3>
<H3><a name="Python_nn12"></a>31.2.8 Building Python Extensions under Windows</H3>
<p>
@ -874,7 +880,7 @@ SWIG Wiki</a>.
</p>
<H2><a name="Python_nn13"></a>30.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Python_nn13"></a>31.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -883,7 +889,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as
This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Python_nn14"></a>30.3.1 Modules</H3>
<H3><a name="Python_nn14"></a>31.3.1 Modules</H3>
<p>
@ -896,7 +902,7 @@ module name, make sure you don't use the same name as a built-in
Python command or standard module name.
</p>
<H3><a name="Python_nn15"></a>30.3.2 Functions</H3>
<H3><a name="Python_nn15"></a>31.3.2 Functions</H3>
<p>
@ -920,7 +926,7 @@ like you think it does:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn16"></a>30.3.3 Global variables</H3>
<H3><a name="Python_nn16"></a>31.3.3 Global variables</H3>
<p>
@ -1058,7 +1064,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt>
if there are no global variables in a module.
</p>
<H3><a name="Python_nn17"></a>30.3.4 Constants and enums</H3>
<H3><a name="Python_nn17"></a>31.3.4 Constants and enums</H3>
<p>
@ -1098,7 +1104,7 @@ other object. Unfortunately, there is no easy way for SWIG to
generate code that prevents this. You will just have to be careful.
</p>
<H3><a name="Python_nn18"></a>30.3.5 Pointers</H3>
<H3><a name="Python_nn18"></a>31.3.5 Pointers</H3>
<p>
@ -1239,7 +1245,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Python_nn19"></a>30.3.6 Structures</H3>
<H3><a name="Python_nn19"></a>31.3.6 Structures</H3>
<p>
@ -1428,7 +1434,7 @@ everything works just like you would expect. For example:
</pre>
</div>
<H3><a name="Python_nn20"></a>30.3.7 C++ classes</H3>
<H3><a name="Python_nn20"></a>31.3.7 C++ classes</H3>
<p>
@ -1517,7 +1523,7 @@ they are accessed through <tt>cvar</tt> like this:
</pre>
</div>
<H3><a name="Python_nn21"></a>30.3.8 C++ inheritance</H3>
<H3><a name="Python_nn21"></a>31.3.8 C++ inheritance</H3>
<p>
@ -1572,7 +1578,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Python_nn22"></a>30.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Python_nn22"></a>31.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -1633,7 +1639,7 @@ treated as a returning value, and it will follow the same
allocation/deallocation process.
</p>
<H3><a name="Python_nn23"></a>30.3.10 C++ overloaded functions</H3>
<H3><a name="Python_nn23"></a>31.3.10 C++ overloaded functions</H3>
<p>
@ -1756,7 +1762,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Python_nn24"></a>30.3.11 C++ operators</H3>
<H3><a name="Python_nn24"></a>31.3.11 C++ operators</H3>
<p>
@ -1845,7 +1851,7 @@ Also, be aware that certain operators don't map cleanly to Python. For instance
overloaded assignment operators don't map to Python semantics and will be ignored.
</p>
<H3><a name="Python_nn25"></a>30.3.12 C++ namespaces</H3>
<H3><a name="Python_nn25"></a>31.3.12 C++ namespaces</H3>
<p>
@ -1912,7 +1918,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Python_nn26"></a>30.3.13 C++ templates</H3>
<H3><a name="Python_nn26"></a>31.3.13 C++ templates</H3>
<p>
@ -1966,7 +1972,7 @@ Some more complicated
examples will appear later.
</p>
<H3><a name="Python_nn27"></a>30.3.14 C++ Smart Pointers</H3>
<H3><a name="Python_nn27"></a>31.3.14 C++ Smart Pointers</H3>
<p>
@ -2051,7 +2057,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</div>
<H3><a name="Python_nn27a"></a>30.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<H3><a name="Python_nn27a"></a>31.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<p>
@ -2213,7 +2219,7 @@ python releases the proxy instance.
</p>
<H2><a name="Python_nn28"></a>30.4 Further details on the Python class interface</H2>
<H2><a name="Python_nn28"></a>31.4 Further details on the Python class interface</H2>
<p>
@ -2226,7 +2232,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Python_nn29"></a>30.4.1 Proxy classes</H3>
<H3><a name="Python_nn29"></a>31.4.1 Proxy classes</H3>
<p>
@ -2315,7 +2321,7 @@ you can attach new Python methods to the class and you can even inherit from it
by Python built-in types until Python 2.2).
</p>
<H3><a name="Python_nn30"></a>30.4.2 Memory management</H3>
<H3><a name="Python_nn30"></a>31.4.2 Memory management</H3>
<p>
@ -2507,7 +2513,7 @@ It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
</p>
<H3><a name="Python_nn31"></a>30.4.3 Python 2.2 and classic classes</H3>
<H3><a name="Python_nn31"></a>31.4.3 Python 2.2 and classic classes</H3>
<p>
@ -2544,7 +2550,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global
function or through an instance (see the earlier section).
</p>
<H2><a name="directors"></a>30.5 Cross language polymorphism</H2>
<H2><a name="Python_directors"></a>31.5 Cross language polymorphism</H2>
<p>
@ -2578,7 +2584,7 @@ proxy classes, director classes, and C wrapper functions takes care of
all the cross-language method routing transparently.
</p>
<H3><a name="Python_nn33"></a>30.5.1 Enabling directors</H3>
<H3><a name="Python_nn33"></a>31.5.1 Enabling directors</H3>
<p>
@ -2671,7 +2677,7 @@ class MyFoo(mymodule.Foo):
</div>
<H3><a name="Python_nn34"></a>30.5.2 Director classes</H3>
<H3><a name="Python_nn34"></a>31.5.2 Director classes</H3>
@ -2753,7 +2759,7 @@ so there is no need for the extra overhead involved with routing the
calls through Python.
</p>
<H3><a name="Python_nn35"></a>30.5.3 Ownership and object destruction</H3>
<H3><a name="Python_nn35"></a>31.5.3 Ownership and object destruction</H3>
<p>
@ -2820,7 +2826,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard
references to the Foo objects remain in Python.
</p>
<H3><a name="Python_nn36"></a>30.5.4 Exception unrolling</H3>
<H3><a name="Python_nn36"></a>31.5.4 Exception unrolling</H3>
<p>
@ -2879,7 +2885,7 @@ Swig::DirectorMethodException is thrown, Python will register the
exception as soon as the C wrapper function returns.
</p>
<H3><a name="Python_nn37"></a>30.5.5 Overhead and code bloat</H3>
<H3><a name="Python_nn37"></a>31.5.5 Overhead and code bloat</H3>
<p>
@ -2913,7 +2919,7 @@ directive) for only those methods that are likely to be extended in
Python.
</p>
<H3><a name="Python_nn38"></a>30.5.6 Typemaps</H3>
<H3><a name="Python_nn38"></a>31.5.6 Typemaps</H3>
<p>
@ -2927,7 +2933,7 @@ need to be supported.
</p>
<H3><a name="Python_nn39"></a>30.5.7 Miscellaneous</H3>
<H3><a name="Python_nn39"></a>31.5.7 Miscellaneous</H3>
<p>
@ -2974,7 +2980,7 @@ methods that return const references.
</p>
<H2><a name="Python_nn40"></a>30.6 Common customization features</H2>
<H2><a name="Python_nn40"></a>31.6 Common customization features</H2>
<p>
@ -2987,7 +2993,7 @@ This section describes some common SWIG features that are used to
improve your the interface to an extension module.
</p>
<H3><a name="Python_nn41"></a>30.6.1 C/C++ helper functions</H3>
<H3><a name="Python_nn41"></a>31.6.1 C/C++ helper functions</H3>
<p>
@ -3068,7 +3074,7 @@ hard to implement. It is possible to clean this up using Python code, typemaps,
customization features as covered in later sections.
</p>
<H3><a name="Python_nn42"></a>30.6.2 Adding additional Python code</H3>
<H3><a name="Python_nn42"></a>31.6.2 Adding additional Python code</H3>
<p>
@ -3217,7 +3223,7 @@ public:
<H3><a name="Python_nn43"></a>30.6.3 Class extension with %extend</H3>
<H3><a name="Python_nn43"></a>31.6.3 Class extension with %extend</H3>
<p>
@ -3306,7 +3312,7 @@ Vector(12,14,16)
in any way---the extensions only show up in the Python interface.
</p>
<H3><a name="Python_nn44"></a>30.6.4 Exception handling with %exception</H3>
<H3><a name="Python_nn44"></a>31.6.4 Exception handling with %exception</H3>
<p>
@ -3432,7 +3438,7 @@ The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter.
</p>
<H2><a name="Python_nn45"></a>30.7 Tips and techniques</H2>
<H2><a name="Python_nn45"></a>31.7 Tips and techniques</H2>
<p>
@ -3442,7 +3448,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques
solving these problems.
</p>
<H3><a name="Python_nn46"></a>30.7.1 Input and output parameters</H3>
<H3><a name="Python_nn46"></a>31.7.1 Input and output parameters</H3>
<p>
@ -3655,7 +3661,7 @@ void foo(Bar *OUTPUT);
may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>
<H3><a name="Python_nn47"></a>30.7.2 Simple pointers</H3>
<H3><a name="Python_nn47"></a>31.7.2 Simple pointers</H3>
<p>
@ -3724,7 +3730,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
<H3><a name="Python_nn48"></a>30.7.3 Unbounded C Arrays</H3>
<H3><a name="Python_nn48"></a>31.7.3 Unbounded C Arrays</H3>
<p>
@ -3786,7 +3792,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Python_nn49"></a>30.7.4 String handling</H3>
<H3><a name="Python_nn49"></a>31.7.4 String handling</H3>
<p>
@ -3855,16 +3861,16 @@ If you need to return binary data, you might use the
also be used to extra binary data from arbitrary pointers.
</p>
<H3><a name="Python_nn50"></a>30.7.5 Arrays</H3>
<H3><a name="Python_nn50"></a>31.7.5 Arrays</H3>
<H3><a name="Python_nn51"></a>30.7.6 String arrays</H3>
<H3><a name="Python_nn51"></a>31.7.6 String arrays</H3>
<H3><a name="Python_nn52"></a>30.7.7 STL wrappers</H3>
<H3><a name="Python_nn52"></a>31.7.7 STL wrappers</H3>
<H2><a name="Python_nn53"></a>30.8 Typemaps</H2>
<H2><a name="Python_nn53"></a>31.8 Typemaps</H2>
<p>
@ -3881,7 +3887,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Python interface or if you want to elevate your guru status.
</p>
<H3><a name="Python_nn54"></a>30.8.1 What is a typemap?</H3>
<H3><a name="Python_nn54"></a>31.8.1 What is a typemap?</H3>
<p>
@ -3997,7 +4003,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Python_nn55"></a>30.8.2 Python typemaps</H3>
<H3><a name="Python_nn55"></a>31.8.2 Python typemaps</H3>
<p>
@ -4038,7 +4044,7 @@ a look at the SWIG library version 1.3.20 or so.
</p>
<H3><a name="Python_nn56"></a>30.8.3 Typemap variables</H3>
<H3><a name="Python_nn56"></a>31.8.3 Typemap variables</H3>
<p>
@ -4109,7 +4115,7 @@ properly assigned.
The Python name of the wrapper function being created.
</div>
<H3><a name="Python_nn57"></a>30.8.4 Useful Python Functions</H3>
<H3><a name="Python_nn57"></a>31.8.4 Useful Python Functions</H3>
<p>
@ -4237,7 +4243,7 @@ write me
</pre>
</div>
<H2><a name="Python_nn58"></a>30.9 Typemap Examples</H2>
<H2><a name="Python_nn58"></a>31.9 Typemap Examples</H2>
<p>
@ -4246,7 +4252,7 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Python_nn59"></a>30.9.1 Converting Python list to a char ** </H3>
<H3><a name="Python_nn59"></a>31.9.1 Converting Python list to a char ** </H3>
<p>
@ -4326,7 +4332,7 @@ memory allocation is used to allocate memory for the array, the
the C function.
</p>
<H3><a name="Python_nn60"></a>30.9.2 Expanding a Python object into multiple arguments</H3>
<H3><a name="Python_nn60"></a>31.9.2 Expanding a Python object into multiple arguments</H3>
<p>
@ -4405,7 +4411,7 @@ to supply the argument count. This is automatically set by the typemap code. F
</pre>
</div>
<H3><a name="Python_nn61"></a>30.9.3 Using typemaps to return arguments</H3>
<H3><a name="Python_nn61"></a>31.9.3 Using typemaps to return arguments</H3>
<p>
@ -4494,7 +4500,7 @@ function can now be used as follows:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn62"></a>30.9.4 Mapping Python tuples into small arrays</H3>
<H3><a name="Python_nn62"></a>31.9.4 Mapping Python tuples into small arrays</H3>
<p>
@ -4543,7 +4549,7 @@ array, such an approach would not be recommended for huge arrays, but
for small structures, this approach works fine.
</p>
<H3><a name="Python_nn63"></a>30.9.5 Mapping sequences to C arrays</H3>
<H3><a name="Python_nn63"></a>31.9.5 Mapping sequences to C arrays</H3>
<p>
@ -4632,7 +4638,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) {
</pre>
</div>
<H3><a name="Python_nn64"></a>30.9.6 Pointer handling</H3>
<H3><a name="Python_nn64"></a>31.9.6 Pointer handling</H3>
<p>
@ -4729,7 +4735,7 @@ class object (if applicable).
<H2><a name="Python_nn65"></a>30.10 Docstring Features</H2>
<H2><a name="Python_nn65"></a>31.10 Docstring Features</H2>
<p>
@ -4757,7 +4763,7 @@ of your users much simpler.
</p>
<H3><a name="Python_nn66"></a>30.10.1 Module docstring</H3>
<H3><a name="Python_nn66"></a>31.10.1 Module docstring</H3>
<p>
@ -4791,7 +4797,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
</div>
<H3><a name="Python_nn67"></a>30.10.2 %feature("autodoc")</H3>
<H3><a name="Python_nn67"></a>31.10.2 %feature("autodoc")</H3>
<p>
@ -4818,7 +4824,7 @@ names, default values if any, and return type if any. There are also
three options for autodoc controlled by the value given to the
feature, described below.
<H4><a name="Python_nn68"></a>30.10.2.1 %feature("autodoc", "0")</H4>
<H4><a name="Python_nn68"></a>31.10.2.1 %feature("autodoc", "0")</H4>
<p>
@ -4847,7 +4853,7 @@ def function_name(*args, **kwargs):
</div>
<H4><a name="Python_nn69"></a>30.10.2.2 %feature("autodoc", "1")</H4>
<H4><a name="Python_nn69"></a>31.10.2.2 %feature("autodoc", "1")</H4>
<p>
@ -4872,7 +4878,7 @@ def function_name(*args, **kwargs):
<H4><a name="Python_nn70"></a>30.10.2.3 %feature("autodoc", "docstring")</H4>
<H4><a name="Python_nn70"></a>31.10.2.3 %feature("autodoc", "docstring")</H4>
<p>
@ -4891,7 +4897,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT);
</div>
<H3><a name="Python_nn71"></a>30.10.3 %feature("docstring")</H3>
<H3><a name="Python_nn71"></a>31.10.3 %feature("docstring")</H3>
<p>
@ -4923,13 +4929,13 @@ with more than one line.
</pre>
</div>
<H2><a name="Python_nn72"></a>30.11 Python Packages</H2>
<H2><a name="Python_nn72"></a>31.11 Python Packages</H2>
<p>
Using the <tt>package</tt> option of the <tt>%module</tt> directive
allows you to specify what Python package that the module will be
living in when installed.
living in when installed.
</p>
<div class="code">
@ -4950,6 +4956,256 @@ and also in base class declarations, etc. if the package name is
different than its own.
</p>
<H2><a name="Python_python3support"></a>31.12 Python 3 Support</H2>
<p>
SWIG is able to support Python 3.0. The wrapper code generated by
SWIG can be compiled with both Python 2.x or 3.0. Further more, by
passing the <tt>-py3</tt> command line option to SWIG, wrapper code
with some Python 3 specific features can be generated (see below
subsections for details of these features). The <tt>-py3</tt> option also
disables some incompatible features for Python 3, such as
<tt>-classic</tt>.
<p>
There is a list of known-to-be-broken features in Python 3:
</p>
<ul>
<li>No more support for FILE* typemaps, because PyFile_AsFile has been dropped
in Python 3.</li>
<li>The <tt>-apply</tt> command line option is removed and generating
code using apply() is no longer supported.</li>
</ul>
<p>
The following are Python 3.0 new features that are currently supported by
SWIG.
</p>
<H3><a name="Python_nn74"></a>31.12.1 Function annotation</H3>
<p>
The <tt>-py3</tt> option will enable function annotation support. When used
SWIG is able to generate proxy method definitions like this:
</p>
<div class="code"><pre>
def foo(self, bar : "int" = 0) -&gt; "void" : ...
</pre></div>
<p>
Also, even if without passing SWIG the <tt>-py3</tt> option, the parameter list
still could be generated:
</p>
<div class="code"><pre>
def foo(self, bar = 0): ...
</pre></div>
<p>
But for overloaded function or method, the parameter list would fallback to
<tt>*args</tt> or <tt>self, *args</tt>, and <tt>**kwargs</tt> may be append
depend on whether you enabled the keyword argument. This fallback is due to
all overloaded functions share the same function in SWIG generated proxy class.
</p>
<p>
For detailed usage of function annotation, see PEP 3107.
</p>
<H3><a name="Python_nn75"></a>31.12.2 Buffer interface</H3>
<p>
Buffer protocols were revised in Python 3. SWIG also gains a series of
new typemaps to support buffer interfaces. These typemap macros are
defined in <tt>pybuffer.i</tt>, which must be included in order to use them.
By using these typemaps, your wrapped function will be able to
accept any Python object that exposes a suitable buffer interface.
</p>
<p>
For example, the <tt>get_path()</tt> function puts the path string
into the memory pointed to by its argument:
</p>
<div class="code"><pre>
void get_path(char *s);
</pre></div>
<p>
Then you can write a typemap like this: (the following example is
applied to both Python 3.0 and 2.6, since the <tt>bytearray</tt> type
is backported to 2.6.
</p>
<div class="code"><pre>
%include &lt;pybuffer.i&gt;
%pybuffer_mutable_string(char *str);
void get_path(char *s);
</pre></div>
<p>
And then on the Python side the wrapped <tt>get_path</tt> could be used in this
way:
</p>
<div class="targetlang"><pre>
&gt;&gt;&gt; p = bytearray(10)
&gt;&gt;&gt; get_path(p)
&gt;&gt;&gt; print(p)
bytearray(b'/Foo/Bar/\x00')
</pre></div>
<p>
The macros defined in <tt>pybuffer.i</tt> are similar to those in
<tt>cstring.i</tt>:
</p>
<p>
<b>%pybuffer_mutable_binary(parm, size_parm)</b>
</p>
<div class="indent">
<p>
The macro can be used to generate a typemap which maps a buffer of an
object to a pointer provided by <tt>parm</tt> and a size argument
provided by <tt>size_parm</tt>. For example:
</p>
<div class="code"><pre>
%pybuffer_mutable_binary(char *str, size_t size);
...
int snprintf(char *str, size_t size, const char *format, ...);
</pre></div>
<p>
In Python:
</p>
<div class="targetlang"><pre>
&gt;&gt;&gt; buf = bytearray(6)
&gt;&gt;&gt; snprintf(buf, "Hello world!")
&gt;&gt;&gt; print(buf)
bytearray(b'Hello\x00')
&gt;&gt;&gt;
</pre></div>
</div>
<p>
<b>%pybuffer_mutable_string(parm)</b>
</p>
<div class="indent">
<p>
This typemap macro requires the buffer to be a zero terminated string,
and maps the pointer of the buffer to <tt>parm</tt>. For example:
</p>
<div class="code"><pre>
%pybuffer_mutable_string(char *str);
...
size_t make_upper(char *str);
</pre></div>
<p>
In Python:
</p>
<div class="targetlang"><pre>
&gt;&gt;&gt; buf = bytearray(b'foo\x00')
&gt;&gt;&gt; make_upper(buf)
&gt;&gt;&gt; print(buf)
bytearray(b'FOO\x00')
&gt;&gt;&gt;
</pre></div>
<p>
Both <tt>%pybuffer_mutable_binary</tt> and <tt>%pybuffer_mutable_string</tt>
require the provided buffer to be mutable, eg. they can accept a
<tt>bytearray</tt> type but can't accept an immutable <tt>byte</tt>
type.
</p>
</div>
<p>
<b>%pybuffer_binary(parm, size_parm)</b>
</p>
<div class="indent">
<p>
This macro maps an object's buffer to a pointer <tt>parm</tt> and a
size <tt>size_parm</tt>. It is similar to
<tt>%pybuffer_mutable_binary</tt>, except the
<tt>%pybuffer_binary</tt> an accept both mutable and immutable
buffers. As a result, the wrapped function should not modify the buffer.
</p>
</div>
<p>
<b>%pybuffer_string(parm)</b>
</p>
<div class="indent">
<p>
This macro maps an object's buffer as a string pointer <tt>parm</tt>.
It is similar to <tt>%pybuffer_mutable_string</tt> but the buffer
could be both mutable and immutable. And your function should not
modify the buffer.
</p>
</div>
<H3><a name="Python_nn76"></a>31.12.3 Abstract base classes</H3>
<p>
By including <tt>pyabc.i</tt> and using the <tt>-py3</tt> command
line option when calling SWIG, the proxy classes of the STL containers
will automatically gain an appropriate abstract base class. For
example, the following SWIG interface:
</p>
<div class="code"><pre>
%include &lt;pyabc.i&gt;
%include &lt;std_map.i&gt;
%include &lt;std_list.i&gt;
namespace std {
%template(Mapii) map&lt;int, int&gt;;
%template(IntList) list&lt;int&gt;;
}
</pre></div>
<p>
will generate a Python proxy class <tt>Mapii</tt> inheriting from
<tt>collections.MutableMap</tt> and a proxy class <tt>IntList</tt>
inheriting from <tt>collections.MutableSequence</tt>.
</p>
<p>
<tt>pyabc.i</tt> also provides a macro <tt>%pythonabc</tt> that could be
used to define an abstract base class for your own C++ class:
</p>
<div class="code"><pre>
%pythonabc(MySet, collections.MutableSet);
</pre></div>
<p>
For details of abstract base class, please see PEP 3119.
</p>
</body>
</html>