| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>SWIG and Python</title> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| <H1><a name="Python"></a>30 SWIG and Python</H1> |
| <!-- INDEX --> |
| <div class="sectiontoc"> |
| <ul> |
| <li><a href="#Python_nn2">Overview</a> |
| <li><a href="#Python_nn3">Preliminaries</a> |
| <ul> |
| <li><a href="#Python_nn4">Running SWIG</a> |
| <li><a href="#Python_nn6">Using distutils</a> |
| <li><a href="#Python_nn7">Hand compiling a dynamic module</a> |
| <li><a href="#Python_nn8">Static linking</a> |
| <li><a href="#Python_nn9">Using your module</a> |
| <li><a href="#Python_nn10">Compilation of C++ extensions</a> |
| <li><a href="#Python_nn11">Compiling for 64-bit platforms</a> |
| <li><a href="#Python_nn12">Building Python Extensions under Windows</a> |
| </ul> |
| <li><a href="#Python_nn13">A tour of basic C/C++ wrapping</a> |
| <ul> |
| <li><a href="#Python_nn14">Modules</a> |
| <li><a href="#Python_nn15">Functions</a> |
| <li><a href="#Python_nn16">Global variables</a> |
| <li><a href="#Python_nn17">Constants and enums</a> |
| <li><a href="#Python_nn18">Pointers</a> |
| <li><a href="#Python_nn19">Structures</a> |
| <li><a href="#Python_nn20">C++ classes</a> |
| <li><a href="#Python_nn21">C++ inheritance</a> |
| <li><a href="#Python_nn22">Pointers, references, values, and arrays</a> |
| <li><a href="#Python_nn23">C++ overloaded functions</a> |
| <li><a href="#Python_nn24">C++ operators</a> |
| <li><a href="#Python_nn25">C++ namespaces</a> |
| <li><a href="#Python_nn26">C++ templates</a> |
| <li><a href="#Python_nn27">C++ Smart Pointers</a> |
| <li><a href="#Python_nn27a">C++ Reference Counted Objects (ref/unref)</a> |
| </ul> |
| <li><a href="#Python_nn28">Further details on the Python class interface</a> |
| <ul> |
| <li><a href="#Python_nn29">Proxy classes</a> |
| <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> |
| <ul> |
| <li><a href="#Python_nn33">Enabling directors</a> |
| <li><a href="#Python_nn34">Director classes</a> |
| <li><a href="#Python_nn35">Ownership and object destruction</a> |
| <li><a href="#Python_nn36">Exception unrolling</a> |
| <li><a href="#Python_nn37">Overhead and code bloat</a> |
| <li><a href="#Python_nn38">Typemaps</a> |
| <li><a href="#Python_nn39">Miscellaneous</a> |
| </ul> |
| <li><a href="#Python_nn40">Common customization features</a> |
| <ul> |
| <li><a href="#Python_nn41">C/C++ helper functions</a> |
| <li><a href="#Python_nn42">Adding additional Python code</a> |
| <li><a href="#Python_nn43">Class extension with %extend</a> |
| <li><a href="#Python_nn44">Exception handling with %exception</a> |
| </ul> |
| <li><a href="#Python_nn45">Tips and techniques</a> |
| <ul> |
| <li><a href="#Python_nn46">Input and output parameters</a> |
| <li><a href="#Python_nn47">Simple pointers</a> |
| <li><a href="#Python_nn48">Unbounded C Arrays</a> |
| <li><a href="#Python_nn49">String handling</a> |
| <li><a href="#Python_nn50">Arrays</a> |
| <li><a href="#Python_nn51">String arrays</a> |
| <li><a href="#Python_nn52">STL wrappers</a> |
| </ul> |
| <li><a href="#Python_nn53">Typemaps</a> |
| <ul> |
| <li><a href="#Python_nn54">What is a typemap?</a> |
| <li><a href="#Python_nn55">Python typemaps</a> |
| <li><a href="#Python_nn56">Typemap variables</a> |
| <li><a href="#Python_nn57">Useful Python Functions</a> |
| </ul> |
| <li><a href="#Python_nn58">Typemap Examples</a> |
| <ul> |
| <li><a href="#Python_nn59">Converting Python list to a char ** </a> |
| <li><a href="#Python_nn60">Expanding a Python object into multiple arguments</a> |
| <li><a href="#Python_nn61">Using typemaps to return arguments</a> |
| <li><a href="#Python_nn62">Mapping Python tuples into small arrays</a> |
| <li><a href="#Python_nn63">Mapping sequences to C arrays</a> |
| <li><a href="#Python_nn64">Pointer handling</a> |
| </ul> |
| <li><a href="#Python_nn65">Docstring Features</a> |
| <ul> |
| <li><a href="#Python_nn66">Module docstring</a> |
| <li><a href="#Python_nn67">%feature("autodoc")</a> |
| <ul> |
| <li><a href="#Python_nn68">%feature("autodoc", "0")</a> |
| <li><a href="#Python_nn69">%feature("autodoc", "1")</a> |
| <li><a href="#Python_nn70">%feature("autodoc", "docstring")</a> |
| </ul> |
| <li><a href="#Python_nn71">%feature("docstring")</a> |
| </ul> |
| <li><a href="#Python_nn72">Python Packages</a> |
| </ul> |
| </div> |
| <!-- INDEX --> |
| |
| |
| |
| <p> |
| <b>Caution: This chapter is under repair!</b> |
| </p> |
| |
| <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. |
| </p> |
| |
| <p> |
| This chapter covers most SWIG features, but certain low-level details |
| are covered in less depth than in earlier chapters. At the |
| 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> |
| |
| |
| <p> |
| To build Python extension modules, SWIG uses a layered approach in which |
| parts of the extension module are defined in C and other parts are |
| defined in Python. The C layer contains low-level wrappers whereas Python code |
| is used to define high-level features. |
| </p> |
| |
| <p> |
| This layered approach recognizes the fact that certain aspects of |
| extension building are better accomplished in each language (instead |
| of trying to do everything in C or C++). Furthermore, by generating code in both |
| languages, you get a lot more flexibility since you can enhance the extension |
| module with support code in either language. |
| </p> |
| |
| <p> |
| In describing the Python interface, this chapter starts by covering the |
| basics of configuration, compiling, and installing Python modules. |
| Next, the Python interface to common C and C++ programming features is |
| described. Advanced customization features such as typemaps are then |
| described followed by a discussion of low-level implementation |
| details. |
| </p> |
| |
| <H2><a name="Python_nn3"></a>30.2 Preliminaries</H2> |
| |
| |
| <H3><a name="Python_nn4"></a>30.2.1 Running SWIG</H3> |
| |
| |
| <p> |
| Suppose that you defined a SWIG module such as the following: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| /* File: example.i */ |
| %module example |
| |
| %{ |
| #define SWIG_FILE_WITH_INIT |
| #include "example.h" |
| %} |
| |
| int fact(int n); |
| </pre> |
| </div> |
| |
| <p> |
| The <tt> #define SWIG_FILE_WITH_INIT </tt> line inserts a macro that specifies that the |
| resulting C file should be built as a python extension, inserting the module |
| <tt>init</tt> code. This <tt>.i</tt> file wraps the following simple C file: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| /* File: example.c */ |
| |
| #include "example.h" |
| |
| int fact(int n) { |
| if (n < 0){ /* This should probably return an error, but this is simpler */ |
| return 0; |
| } |
| if (n == 0) { |
| return 1; |
| } |
| else { |
| /* testing for overflow would be a good idea here */ |
| return n * fact(n-1); |
| } |
| } |
| |
| </pre> |
| </div> |
| |
| <p> |
| With the header file: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| /* File: example.h */ |
| |
| int fact(int n); |
| </pre> |
| </div> |
| |
| <p> |
| To build a Python module, run SWIG using the <tt>-python</tt> option: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -python example.i |
| </pre></div> |
| |
| <p> |
| If building a C++ extension, add the <tt>-c++</tt> option: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -c++ -python example.i |
| </pre></div> |
| |
| <p> |
| This creates two different files; a C/C++ source file <tt>example_wrap.c</tt> or |
| <tt>example_wrap.cxx</tt> and a Python source file <tt>example.py</tt>. The generated C |
| source file contains the low-level wrappers that need to be compiled and linked with the |
| rest of your C/C++ application to create an extension module. The Python source file |
| contains high-level support code. This is the file that you will import to use the module. |
| </p> |
| |
| <p> |
| The name of the wrapper file is derived from the name of the input file. For example, if the |
| input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. |
| To change this, you can use the <tt>-o</tt> option. The name of the Python file is derived |
| from the module name specified with <tt>%module</tt>. If the module name is <tt>example</tt>, |
| then a file <tt>example.py</tt> is created. |
| </p> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| The preferred approach to building an extension module for python is to compile it with |
| distutils, which comes with all recent versions of python |
| (<a href="http://docs.python.org/dist/dist.html">Distutils Docs</a>). |
| </p> |
| |
| <p> |
| Distutils takes care of making sure that your extension is built with all the correct |
| flags, headers, etc. for the version of Python it is run with. Distutils will compile your |
| extension into a shared object file or DLL (<tt>.so</tt> on Linux, <tt>.pyd</tt> on |
| Windows, etc). In addition, distutils can handle installing your package into |
| site-packages, if that is desired. A configuration file (conventionally called: <tt>setup.py</tt>) |
| describes the extension (and related python modules). The distutils will |
| then generate all the right compiler directives to build it for you. |
| </p> |
| |
| <p> |
| Here is a sample <tt>setup.py</tt> file for the above example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| #!/usr/bin/env python |
| |
| """ |
| setup.py file for SWIG example |
| """ |
| |
| from distutils.core import setup, Extension |
| |
| |
| example_module = Extension('_example', |
| sources=['example_wrap.c', 'example.c'], |
| ) |
| |
| setup (name = 'example', |
| version = '0.1', |
| author = "SWIG Docs", |
| description = """Simple swig example from docs""", |
| ext_modules = [example_module], |
| py_modules = ["example"], |
| ) |
| </pre> |
| </div> |
| |
| <p> |
| In this example, the line: <tt>example_module = Extension(....)</tt> creates an Extension |
| module object, defining the name as <tt>_example</tt>, and using the source code files: |
| <tt>example_wrap.c</tt>, generated by swig, and <tt>example.c</tt>, your original c |
| source. The swig (and other python extension modules) tradition is for the compiled |
| extension to have the name of the python portion, prefixed by an underscore. If the name |
| of your python module is "<tt>example.py</tt>", then the name of the corresponding object file |
| will be"<tt>_example.so</tt>" |
| </p> |
| |
| <p> |
| The <tt>setup</tt> call then sets up distutils to build your package, defining |
| some meta data, and passing in your extension module object. |
| Once this is saved as <tt>setup.py</tt>, you can build your extension with these commands: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -python example.i |
| $ python setup.py build_ext --inplace |
| </pre></div> |
| |
| <p> |
| And a .so, or .pyd or... will be created for you. It will build a version that matches the |
| python that you run the command with. Taking apart the command line: |
| </p> |
| |
| <ul> |
| <li> <tt>python</tt> -- the version of python you want to build for |
| <li> <tt>setup.py</tt> -- the name of your setup script (it can be called anything, but |
| setup.py is the tradition) |
| <li> <tt>build_ext</tt> -- telling distutils to build extensions |
| <li> <tt>--inplace</tt> -- this tells distutils to put the extension lib in the current dir. |
| Other wise, it will put it inside a build hierarchy, and you'd have to move it to use it. |
| </ul> |
| |
| <p> |
| The distutils have many other features, consult the python distutils docs for details. |
| </p> |
| |
| <p> |
| This same approach works on all platforms if the appropriate compiler is installed. (it |
| 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> |
| |
| |
| <p> |
| While the preferred approach to building an extension module is to use the distutils, some |
| people like to integrate building extensions with a larger build system, and thus may wish |
| to compile their modules without the distutils. To do this, you need to compile your |
| program using commands like this (shown for Linux): |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -python example.i |
| $ gcc -c -fPIC example.c |
| $ gcc -c -fPIC example_wrap.c -I/usr/local/include/python2.0 |
| $ gcc -shared example.o example_wrap.o -o _example.so |
| </pre></div> |
| |
| <p> |
| The exact commands for doing this vary from platform to platform. |
| However, SWIG tries to guess the right options when it is installed. Therefore, |
| you may want to start with one of the examples in the <tt>SWIG/Examples/python</tt> |
| directory. If that doesn't work, you will need to read the man-pages for |
| your compiler and linker to get the right set of options. You might also |
| check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a> for |
| additional information. |
| </p> |
| |
| <p> |
| When linking the module, <b>the name of the output file has to match the name |
| of the module prefixed by an underscore</b>. If the name of your module is "<tt>example</tt>", then the |
| name of the corresponding object file should be |
| "<tt>_example.so</tt>" or "<tt>_examplemodule.so</tt>". |
| The name of the module is specified using the <tt>%module</tt> directive or the |
| <tt> -module</tt> command line option. |
| </p> |
| |
| <p> |
| <b>Compatibility Note:</b> In SWIG-1.3.13 and earlier releases, module |
| names did not include the leading underscore. This is because modules |
| were normally created as C-only extensions without the extra Python |
| support file (instead, creating Python code was supported as an optional |
| feature). This has been changed in SWIG-1.3.14 and is consistent with |
| other Python extension modules. For example, the <tt>socket</tt> |
| module actually consists of two files; <tt>socket.py</tt> and |
| <tt>_socket.so</tt>. Many other built-in Python modules follow a similar convention. |
| </p> |
| |
| |
| <H3><a name="Python_nn8"></a>30.2.4 Static linking</H3> |
| |
| |
| <p> |
| An alternative approach to dynamic linking is to rebuild the Python |
| interpreter with your extension module added to it. In the past, |
| this approach was sometimes necessary due to limitations in dynamic loading |
| support on certain machines. However, the situation has improved greatly |
| over the last few years and you should not consider this approach |
| unless there is really no other option. |
| </p> |
| |
| <p> |
| The usual procedure for adding a new module to Python involves finding |
| the Python source, adding an entry to the <tt>Modules/Setup</tt> file, |
| and rebuilding the interpreter using the Python Makefile. However, |
| newer Python versions have changed the build process. You may need to edit |
| the 'setup.py' file in the Python distribution instead. |
| </p> |
| |
| <p> |
| In earlier versions of SWIG, the <tt>embed.i</tt> library file could be used to |
| rebuild the interpreter. For example: |
| </p> |
| |
| <div class="code"><pre> |
| %module example |
| |
| %inline %{ |
| extern int fact(int); |
| extern int mod(int, int); |
| extern double My_variable; |
| %} |
| |
| %include embed.i // Include code for a static version of Python |
| |
| </pre></div> |
| |
| <p> |
| The <tt>embed.i</tt> library file includes supporting code that |
| contains everything needed to rebuild Python. To rebuild the interpreter, |
| you simply do something like this: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -python example.i |
| $ gcc example.c example_wrap.c \ |
| -Xlinker -export-dynamic \ |
| -DHAVE_CONFIG_H -I/usr/local/include/python2.1 \ |
| -I/usr/local/lib/python2.1/config \ |
| -L/usr/local/lib/python2.1/config -lpython2.1 -lm -ldl \ |
| -o mypython |
| |
| </pre></div> |
| <p> |
| You will need to supply the same libraries that were used to build Python the first |
| time. This may include system libraries such as <tt>-lsocket</tt>, <tt>-lnsl</tt>, |
| and <tt>-lpthread</tt>. Assuming this actually works, the new version of Python |
| should be identical to the default version except that your extension module will be |
| a built-in part of the interpreter. |
| </p> |
| |
| <p> |
| <b>Comment:</b> In practice, you should probably try to avoid static |
| linking if possible. Some programmers may be inclined |
| to use static linking in the interest of getting better performance. |
| However, the performance gained by static linking tends to be rather |
| minimal in most situations (and quite frankly not worth the extra |
| hassle in the opinion of this author). |
| </p> |
| |
| <p> |
| <b>Compatibility note:</b> The <tt>embed.i</tt> library file is |
| deprecated and has not been maintained for several years. Even though it |
| appears to "work" with Python 2.1, no future support is guaranteed. |
| 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> |
| |
| |
| <p> |
| To use your module, simply use the Python <tt>import</tt> statement. If |
| all goes well, you will be able to this: |
| </p> |
| |
| <div class="targetlang"><pre> |
| $ python |
| >>> import example |
| >>> example.fact(4) |
| 24 |
| >>> |
| </pre></div> |
| |
| <p> |
| A common error received by first-time users is the following: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| File "example.py", line 2, in ? |
| import _example |
| ImportError: No module named _example |
| </pre> |
| </div> |
| |
| <p> |
| If you get this message, it means that you either forgot to compile the wrapper |
| code into an extension module or you didn't give the extension module the right |
| name. Make sure that you compiled the wrappers into a module called <tt>_example.so</tt>. And |
| don't forget the leading underscore (_). |
| </p> |
| |
| <p> |
| Another possible error is the following: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ImportError: dynamic module does not define init function (init_example) |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| This error is almost always caused when a bad name is given to the shared object file. |
| For example, if you created a file <tt>example.so</tt> instead of <tt>_example.so</tt> you would |
| get this error. Alternatively, this error could arise if the name of the module is |
| inconsistent with the module name supplied with the <tt>%module</tt> directive. |
| Double-check the interface to make sure the module name and the shared object |
| filename match. Another possible cause of this error is forgetting to link the SWIG-generated |
| wrapper code with the rest of your application when creating the extension module. |
| </p> |
| |
| <p> |
| Another common error is something similar to the following: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| Traceback (most recent call last): |
| File "example.py", line 3, in ? |
| import example |
| ImportError: ./_example.so: undefined symbol: fact |
| </pre> |
| </div> |
| |
| <p> |
| This error usually indicates that you forgot to include some object |
| files or libraries in the linking of the shared library file. Make |
| sure you compile both the SWIG wrapper file and your original program |
| into a shared library file. Make sure you pass all of the required libraries |
| to the linker. |
| </p> |
| |
| <p> |
| Sometimes unresolved symbols occur because a wrapper has been created |
| for a function that doesn't actually exist in a library. This usually |
| occurs when a header file includes a declaration for a function that |
| was never actually implemented or it was removed from a library |
| without updating the header file. To fix this, you can either edit |
| the SWIG input file to remove the offending declaration or you can use |
| the <tt>%ignore</tt> directive to ignore the declaration. |
| </p> |
| |
| <p> |
| Finally, suppose that your extension module is linked with another library like this: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| $ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib <b>-lfoo</b> \ |
| -o _example.so |
| </pre> |
| </div> |
| |
| <p> |
| If the <tt>foo</tt> library is compiled as a shared library, you might encounter the following |
| problem when you try to use your module: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ImportError: libfoo.so: cannot open shared object file: No such file or directory |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| This error is generated because the dynamic linker can't locate the |
| <tt>libfoo.so</tt> library. When shared libraries are loaded, the |
| system normally only checks a few standard locations such as |
| <tt>/usr/lib</tt> and <tt>/usr/local/lib</tt>. To fix this problem, |
| there are several things you can do. First, you can recompile your extension |
| module with extra path information. For example, on Linux you can do this: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| $ gcc -shared example.o example_wrap.o -L/home/beazley/projects/lib -lfoo \ |
| <b>-Xlinker -rpath /home/beazley/projects/lib </b> \ |
| -o _example.so |
| </pre> |
| </div> |
| |
| <p> |
| Alternatively, you can set the <tt>LD_LIBRARY_PATH</tt> environment variable to |
| include the directory with your shared libraries. |
| If setting <tt>LD_LIBRARY_PATH</tt>, be aware that setting this variable can introduce |
| a noticeable performance impact on all other applications that you run. |
| To set it only for Python, you might want to do this instead: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| $ env LD_LIBRARY_PATH=/home/beazley/projects/lib python |
| </pre> |
| </div> |
| |
| <p> |
| Finally, you can use a command such as <tt>ldconfig</tt> (Linux) or |
| <tt>crle</tt> (Solaris) to add additional search paths to the default |
| 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> |
| |
| |
| <p> |
| Compilation of C++ extensions has traditionally been a tricky problem. |
| Since the Python interpreter is written in C, you need to take steps to |
| make sure C++ is properly initialized and that modules are compiled |
| correctly. This should be a non-issue if you're using distutils, as |
| it takes care of all that for you. The following is included for |
| historical reasons, and in case you need to compile on your own. |
| </p> |
| |
| <p> |
| On most machines, C++ extension modules should be linked using the C++ |
| compiler. For example: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -c++ -python example.i |
| $ g++ -c example.cxx |
| $ g++ -c example_wrap.cxx -I/usr/local/include/python2.0 |
| $ g++ -shared example.o example_wrap.o -o _example.so |
| </pre></div> |
| |
| <p> |
| On some platforms, you could also need to generate |
| position-independent code (PIC), by using a compiler option such as -fPIC. |
| Notably, the x86_64 (Opteron and EM64T) platform requires it, and when |
| using the GNU Compiler Suite, you will need to modify the previous example |
| as follows: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -c++ -python example.i |
| $ g++ -fPIC -c example.cxx |
| $ g++ -fPIC -c example_wrap.cxx -I/usr/local/include/python2.0 |
| $ g++ -shared example.o example_wrap.o -o _example.so |
| </pre></div> |
| |
| <p> |
| In addition to this, you may need to include additional library |
| files to make it work. For example, if you are using the Sun C++ compiler on |
| Solaris, you often need to add an extra library <tt>-lCrun</tt> like this: |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -c++ -python example.i |
| $ CC -c example.cxx |
| $ CC -c example_wrap.cxx -I/usr/local/include/python2.0 |
| $ CC -G example.o example_wrap.o -L/opt/SUNWspro/lib -o _example.so -lCrun |
| </pre></div> |
| |
| <p> |
| Of course, the extra libraries to use are completely non-portable---you will |
| probably need to do some experimentation. |
| </p> |
| |
| <p> |
| Sometimes people have suggested that it is necessary to relink the |
| Python interpreter using the C++ compiler to make C++ extension modules work. |
| In the experience of this author, this has never actually appeared to be |
| necessary. Relinking the interpreter with C++ really only includes the |
| special run-time libraries described above---as long as you link your extension |
| modules with these libraries, it should not be necessary to rebuild Python. |
| </p> |
| |
| <p> |
| If you aren't entirely sure about the linking of a C++ extension, you |
| might look at an existing C++ program. On many Unix machines, the |
| <tt>ldd</tt> command will list library dependencies. This should give |
| you some clues about what you might have to include when you link your |
| extension module. For example: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| $ ldd swig |
| libstdc++-libc6.1-1.so.2 => /usr/lib/libstdc++-libc6.1-1.so.2 (0x40019000) |
| libm.so.6 => /lib/libm.so.6 (0x4005b000) |
| libc.so.6 => /lib/libc.so.6 (0x40077000) |
| /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) |
| </pre> |
| </div> |
| |
| <p> |
| As a final complication, a major weakness of C++ is that it does not |
| define any sort of standard for binary linking of libraries. This |
| means that C++ code compiled by different compilers will not link |
| together properly as libraries nor is the memory layout of classes and |
| data structures implemented in any kind of portable manner. In a |
| monolithic C++ program, this problem may be unnoticed. However, in Python, it |
| is possible for different extension modules to be compiled with |
| different C++ compilers. As long as these modules are self-contained, |
| this probably won't matter. However, if these modules start sharing data, |
| you will need to take steps to avoid segmentation faults and other |
| 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> |
| |
| |
| <p> |
| On platforms that support 64-bit applications (Solaris, Irix, etc.), |
| special care is required when building extension modules. On these |
| machines, 64-bit applications are compiled and linked using a different |
| set of compiler/linker options. In addition, it is not generally possible to mix |
| 32-bit and 64-bit code together in the same application. |
| </p> |
| |
| <p> |
| To utilize 64-bits, the Python executable will need to be recompiled |
| as a 64-bit application. In addition, all libraries, wrapper code, |
| and every other part of your application will need to be compiled for |
| 64-bits. If you plan to use other third-party extension modules, they |
| will also have to be recompiled as 64-bit extensions. |
| </p> |
| |
| <p> |
| If you are wrapping commercial software for which you have no source |
| code, you will be forced to use the same linking standard as used by |
| that software. This may prevent the use of 64-bit extensions. It may |
| also introduce problems on platforms that support more than one |
| linking standard (e.g., -o32 and -n32 on Irix). |
| </p> |
| |
| <p> On the Linux x86_64 platform (Opteron or EM64T), besides of the |
| required compiler option -fPIC discussed above, you will need to be |
| careful about the libraries you link with or the library path you |
| use. In general, a Linux distribution will have two set of libraries, |
| one for native x86_64 programs (under /usr/lib64), and another for 32 |
| bits compatibility (under /usr/lib). Also, the compiler options -m32 |
| 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> |
| |
| |
| <p> |
| Building a SWIG extension to Python under Windows is roughly similar to |
| the process used with Unix. Using the distutils, it is essentially |
| identical. If you have the same version of the MS compiler that Python |
| was built with (the python2.4 and python2.5 distributed by python.org |
| are built with Visual Studio 2003), the standard <tt> python setup.py |
| build </tt> should just work. |
| </p> |
| |
| <p> |
| As of python2.5, the distutils support building extensions with MingGW out |
| of the box. Following the instruction here: |
| <a href="http://boodebr.org/main/python/build-windows-extensions">Building |
| Python extensions for Windows with only free tools</a> should get you started. |
| </p> |
| |
| <p> |
| If you need to build it on your own, the following notes are provided: |
| </p> |
| |
| <p> |
| You will need to create a DLL that can be loaded into the interpreter. |
| This section briefly describes the use of SWIG with Microsoft Visual |
| C++. As a starting point, many of SWIG's examples include project |
| files. You might want to take a quick look at these in addition to |
| reading this section. |
| </p> |
| |
| <p> |
| In Developer Studio, SWIG should be invoked as a custom build option. |
| This is usually done as follows: |
| </p> |
| |
| <ul> |
| <li>Open up a new workspace and use the AppWizard to select a DLL |
| project. |
| |
| <li>Add both the SWIG interface file (the .i file), any supporting C |
| files, and the name of the wrapper file that will be created by SWIG |
| (ie. <tt>example_wrap.c</tt>). Note : If using C++, choose a |
| different suffix for the wrapper file such as |
| <tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't |
| exist yet--Developer Studio keeps a reference to it. |
| |
| <li>Select the SWIG interface file and go to the settings menu. Under |
| settings, select the "Custom Build" option. |
| |
| <li>Enter "SWIG" in the description field. |
| |
| <li>Enter "<tt>swig -python -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build command(s) field" |
| |
| <li>Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>" in the "Output files(s) field". |
| |
| <li>Next, select the settings for the entire project and go to |
| "C++:Preprocessor". Add the include directories for your Python |
| installation under "Additional include directories". |
| |
| <li>Define the symbol __WIN32__ under preprocessor options. |
| |
| <li>Finally, select the settings for the entire project and go to |
| "Link Options". Add the Python library file to your link libraries. |
| For example "python21.lib". Also, set the name of the output file to |
| match the name of your Python module, ie. _example.pyd - Note that _example.dll also worked with Python-2.4 and earlier. |
| |
| <li>Build your project. |
| </ul> |
| |
| <p> |
| If all went well, SWIG will be automatically invoked whenever |
| you build your project. Any changes made to the interface file will |
| result in SWIG being automatically executed to produce a new version of |
| the wrapper file. |
| </p> |
| |
| <p> |
| To run your new Python extension, simply run Python |
| and use the <tt>import</tt> command as normal. For example : |
| </p> |
| |
| <div class="targetlang"><pre> |
| $ python |
| >>> import example |
| >>> print example.fact(4) |
| 24 |
| >>> |
| </pre></div> |
| |
| <p> |
| If you get an <tt>ImportError</tt> exception when importing the module, you may |
| have forgotten to include additional library files when you built your module. |
| If you get an access violation or some kind of general protection fault |
| immediately upon import, you have a more serious problem. This |
| is often caused by linking your extension module against the wrong |
| set of Win32 debug or thread libraries. You will have to fiddle around with |
| the build options of project to try and track this down. |
| </p> |
| |
| <p> |
| Some users have reported success in building extension modules using Cygwin |
| and other compilers. However, the problem of building usable DLLs with these |
| compilers tends to be rather problematic. For the latest information, |
| you may want to consult the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl"> |
| SWIG Wiki</a>. |
| </p> |
| |
| |
| <H2><a name="Python_nn13"></a>30.3 A tour of basic C/C++ wrapping</H2> |
| |
| |
| <p> |
| By default, SWIG tries to build a very natural Python interface |
| to your C/C++ code. Functions are wrapped as functions, classes are wrapped as classes, and so forth. |
| This section briefly covers the essential aspects of this wrapping. |
| </p> |
| |
| <H3><a name="Python_nn14"></a>30.3.1 Modules</H3> |
| |
| |
| <p> |
| The SWIG <tt>%module</tt> directive specifies the name of the Python |
| module. If you specify `<tt>%module example</tt>', then everything is |
| wrapped into a Python '<tt>example</tt>' module. Underneath the covers, |
| this module consists of a Python source file <tt>example.py</tt> and a low-level |
| extension module <tt>_example.so</tt>. When choosing a |
| 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> |
| |
| |
| <p> |
| Global functions are wrapped as new Python built-in functions. For example, |
| </p> |
| |
| <div class="code"><pre> |
| %module example |
| int fact(int n); |
| </pre></div> |
| |
| <p> |
| creates a built-in function <tt>example.fact(n)</tt> that works exactly |
| like you think it does: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> import example |
| >>> print example.fact(4) |
| 24 |
| >>> |
| </pre></div> |
| |
| <H3><a name="Python_nn16"></a>30.3.3 Global variables</H3> |
| |
| |
| <p> |
| C/C++ global variables are fully supported by SWIG. However, the underlying |
| mechanism is somewhat different than you might expect due to the way that |
| Python assignment works. When you type the following in Python |
| </p> |
| |
| <div class="targetlang"><pre> |
| a = 3.4 |
| </pre></div> |
| |
| <p> |
| "a" becomes a name for an object containing the value 3.4. If you later type |
| </p> |
| |
| <div class="targetlang"><pre> |
| b = a |
| </pre></div> |
| |
| <p> |
| then "a" and "b" are both names for the object containing the value |
| 3.4. Thus, there is only one object containing 3.4 and "a" |
| and "b" are both names that refer to it. This is quite |
| different than C where a variable name refers to a memory location in which |
| a value is stored (and assignment copies data into that location). |
| Because of this, there is no direct way to map variable |
| assignment in C to variable assignment in Python. |
| </p> |
| |
| <p> |
| To provide access to C global variables, SWIG creates a special |
| object called `<tt>cvar</tt>' that is added to each SWIG generated |
| module. Global variables are then accessed as attributes of this object. |
| For example, consider this interface |
| </p> |
| |
| <div class="code"><pre> |
| // SWIG interface file with global variables |
| %module example |
| ... |
| %inline %{ |
| extern int My_variable; |
| extern double density; |
| %} |
| ... |
| </pre></div> |
| <p> |
| Now look at the Python interface: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> import example |
| >>> # Print out value of a C global variable |
| >>> print example.cvar.My_variable |
| 4 |
| >>> # Set the value of a C global variable |
| >>> example.cvar.density = 0.8442 |
| >>> # Use in a math operation |
| >>> example.cvar.density = example.cvar.density*1.10 |
| </pre></div> |
| |
| <p> |
| If you make an error in variable assignment, you will receive an |
| error message. For example: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> example.cvar.density = "Hello" |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: C variable 'density (double )' |
| >>> |
| </pre></div> |
| |
| <p> |
| If a variable is declared as <tt>const</tt>, it is wrapped as a |
| read-only variable. Attempts to modify its value will result in an |
| error. |
| </p> |
| |
| <p> |
| To make ordinary variables read-only, you can use the <tt>%immutable</tt> directive. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %{ |
| extern char *path; |
| %} |
| %immutable; |
| extern char *path; |
| %mutable; |
| </pre> |
| </div> |
| |
| <p> |
| The <tt>%immutable</tt> directive stays in effect until it is explicitly disabled or cleared using |
| <tt>%mutable</tt>. |
| See the <a href="SWIG.html#SWIG_readonly_variables">Creating read-only variables</a> section for further details. |
| </p> |
| |
| <p> |
| If you just want to make a specific variable immutable, supply a declaration name. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %{ |
| extern char *path; |
| %} |
| %immutable path; |
| ... |
| extern char *path; // Read-only (due to %immutable) |
| </pre> |
| </div> |
| |
| <p> |
| If you would like to access variables using a name other than "<tt>cvar</tt>", it can be |
| changed using the <tt>-globals</tt> option : |
| </p> |
| |
| <div class="shell"><pre> |
| $ swig -python -globals myvar example.i |
| </pre></div> |
| |
| <p> |
| Some care is in order when importing multiple SWIG modules. |
| If you use the "<tt>from <file> import *</tt>" style of |
| importing, you will get a name clash on the variable `<tt>cvar</tt>' |
| and you will only be able to access global variables from the last |
| module loaded. To prevent this, you might consider renaming |
| <tt>cvar</tt> or making it private to the module by giving it a name |
| 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> |
| |
| |
| <p> |
| C/C++ constants are installed as Python objects containing the |
| appropriate value. To create a constant, use <tt>#define</tt>, <tt>enum</tt>, or the |
| <tt>%constant</tt> directive. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| #define PI 3.14159 |
| #define VERSION "1.0" |
| |
| enum Beverage { ALE, LAGER, STOUT, PILSNER }; |
| |
| %constant int FOO = 42; |
| %constant const char *path = "/usr/local"; |
| </pre> |
| </div> |
| |
| <p> |
| For enums, make sure that the definition of the enumeration actually appears in a header |
| file or in the wrapper file somehow---if you just stick an enum in a SWIG interface without |
| also telling the C compiler about it, the wrapper code won't compile. |
| </p> |
| |
| <p> |
| Note: declarations declared as <tt>const</tt> are wrapped as read-only variables and |
| will be accessed using the <tt>cvar</tt> object described in the previous section. They |
| are not wrapped as constants. For further discussion about this, see the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter. |
| </p> |
| |
| <p> |
| Constants are not guaranteed to remain constant in Python---the name |
| of the constant could be accidentally reassigned to refer to some |
| 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> |
| |
| |
| <p> |
| C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no |
| problem working with incomplete type information. Here is a rather |
| simple interface: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| |
| FILE *fopen(const char *filename, const char *mode); |
| int fputs(const char *, FILE *); |
| int fclose(FILE *); |
| </pre> |
| </div> |
| |
| <p> |
| When wrapped, you will be able to use the functions in a natural way from Python. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| >>> f = example.fopen("junk","w") |
| >>> example.fputs("Hello World\n", f) |
| >>> example.fclose(f) |
| </pre> |
| </div> |
| |
| <p> |
| If this makes you uneasy, rest assured that there is no |
| deep magic involved. Underneath the covers, pointers to C/C++ objects are |
| simply represented as opaque values using an especial python container object: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> print f |
| <Swig Object at _08a71808_p_FILE> |
| </pre></div> |
| |
| <p> |
| This pointer value can be freely passed around to different C functions that |
| expect to receive an object of type <tt>FILE *</tt>. The only thing you can't do is |
| dereference the pointer from Python. Of course, that isn't much of a concern in this example. |
| </p> |
| |
| <p> |
| In older versions of Swig (1.3.22 or older), pointers were represented |
| using a plain string object. If you have an old package that still |
| requires that representation, or you just feel nostalgic, you can |
| always retrieve it by casting the pointer object to a string: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> print str(f) |
| _c0671108_p_FILE |
| </pre></div> |
| |
| <p> |
| Also, if you need to pass the raw pointer value to some external |
| python library, you can do it by casting the pointer object to an |
| integer: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> print int(f) |
| 135833352 |
| </pre></div> |
| |
| <p> |
| However, the inverse operation is not possible, i.e., you can't build |
| a Swig pointer object from a raw integer value. |
| </p> |
| |
| <p> |
| Note also that the '0' or NULL pointer is always represented by |
| <tt>None</tt>, no matter what type swig is addressing. In the |
| previous example, you can call: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> example.fclose(None) |
| </pre> |
| </div> |
| |
| <p> |
| and that will be equivalent to the following, but not really useful, C |
| code: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| FILE *f = NULL; |
| fclose(f); |
| </pre> |
| </div> |
| |
| <p> |
| As much as you might be inclined to modify a pointer value directly |
| from Python, don't. The hexadecimal encoding is not necessarily the |
| same as the logical memory address of the underlying object. Instead |
| it is the raw byte encoding of the pointer value. The encoding will |
| vary depending on the native byte-ordering of the platform (i.e., |
| big-endian vs. little-endian). Similarly, don't try to manually cast |
| a pointer to a new type by simply replacing the type-string. This may |
| not work like you expect, it is particularly dangerous when casting |
| C++ objects. If you need to cast a pointer or change its value, |
| consider writing some helper functions instead. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %inline %{ |
| /* C-style cast */ |
| Bar *FooToBar(Foo *f) { |
| return (Bar *) f; |
| } |
| |
| /* C++-style cast */ |
| Foo *BarToFoo(Bar *b) { |
| return dynamic_cast<Foo*>(b); |
| } |
| |
| Foo *IncrFoo(Foo *f, int i) { |
| return f+i; |
| } |
| %} |
| </pre> |
| </div> |
| |
| <p> |
| Also, if working with C++, you should always try |
| to use the new C++ style casts. For example, in the above code, the |
| 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> |
| |
| |
| <p> |
| If you wrap a C structure, it is wrapped by a Python class. This provides |
| a very natural interface. For example, |
| </p> |
| |
| <div class="code"><pre> |
| struct Vector { |
| double x,y,z; |
| }; |
| |
| </pre></div> |
| |
| <p> |
| is used as follows: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> v = example.Vector() |
| >>> v.x = 3.5 |
| >>> v.y = 7.2 |
| >>> print v.x, v.y, v.z |
| 7.8 -4.5 0.0 |
| >>> |
| </pre></div> |
| |
| <p> |
| Similar access is provided for unions and the data members of C++ classes. |
| </p> |
| |
| <p> |
| If you print out the value of <tt>v</tt> in the above example, you will see |
| something like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> print v |
| <C Vector instance at _18e31408_p_Vector> |
| </pre> |
| </div> |
| |
| <p> |
| This object is actually a Python instance that has been wrapped around a pointer to the low-level |
| C structure. This instance doesn't actually do anything--it just serves as a proxy. |
| The pointer to the C object can be found in the the <tt>.this</tt> |
| attribute. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> print v.this |
| _18e31408_p_Vector |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| Further details about the Python proxy class are covered a little later. |
| </p> |
| |
| <p> |
| <tt>const</tt> members of a structure are read-only. Data members |
| can also be forced to be read-only using the <tt>%immutable</tt> directive. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| struct Foo { |
| ... |
| %immutable; |
| int x; /* Read-only members */ |
| char *name; |
| %mutable; |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| When <tt>char *</tt> members of a structure are wrapped, the contents are assumed to be |
| dynamically allocated using <tt>malloc</tt> or <tt>new</tt> (depending on whether or not |
| SWIG is run with the -c++ option). When the structure member is set, the old contents will be |
| released and a new value created. If this is not the behavior you want, you will have to use |
| a typemap (described later). |
| </p> |
| |
| <p> |
| If a structure contains arrays, access to those arrays is managed through pointers. For |
| example, consider this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| struct Bar { |
| int x[16]; |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| If accessed in Python, you will see behavior like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> b = example.Bar() |
| >>> print b.x |
| _801861a4_p_int |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| This pointer can be passed around to functions that expect to receive |
| an <tt>int *</tt> (just like C). You can also set the value of an array member using |
| another pointer. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> c = example.Bar() |
| >>> c.x = b.x # Copy contents of b.x to c.x |
| </pre> |
| </div> |
| |
| <p> |
| For array assignment, SWIG copies the entire contents of the array starting with the data pointed |
| to by <tt>b.x</tt>. In this example, 16 integers would be copied. Like C, SWIG makes |
| no assumptions about bounds checking---if you pass a bad pointer, you may get a segmentation |
| fault or access violation. |
| </p> |
| |
| <p> |
| When a member of a structure is itself a structure, it is handled as a |
| pointer. For example, suppose you have two structures like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| struct Foo { |
| int a; |
| }; |
| |
| struct Bar { |
| Foo f; |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| Now, suppose that you access the <tt>f</tt> attribute of <tt>Bar</tt> like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> b = Bar() |
| >>> x = b.f |
| </pre> |
| </div> |
| |
| <p> |
| In this case, <tt>x</tt> is a pointer that points to the <tt>Foo</tt> that is inside <tt>b</tt>. |
| This is the same value as generated by this C code: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| Bar b; |
| Foo *x = &b->f; /* Points inside b */ |
| </pre> |
| </div> |
| |
| <p> |
| Because the pointer points inside the structure, you can modify the contents and |
| everything works just like you would expect. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> b = Bar() |
| >>> b.f.a = 3 # Modify attribute of structure member |
| >>> x = b.f |
| >>> x.a = 3 # Modifies the same structure |
| </pre> |
| </div> |
| |
| <H3><a name="Python_nn20"></a>30.3.7 C++ classes</H3> |
| |
| |
| <p> |
| C++ classes are wrapped by Python classes as well. For example, if you have this class, |
| </p> |
| |
| <div class="code"><pre> |
| class List { |
| public: |
| List(); |
| ~List(); |
| int search(char *item); |
| void insert(char *item); |
| void remove(char *item); |
| char *get(int n); |
| int length; |
| }; |
| </pre></div> |
| |
| <p> |
| you can use it in Python like this: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> l = example.List() |
| >>> l.insert("Ale") |
| >>> l.insert("Stout") |
| >>> l.insert("Lager") |
| >>> l.get(1) |
| 'Stout' |
| >>> print l.length |
| 3 |
| >>> |
| </pre></div> |
| |
| <p> |
| Class data members are accessed in the same manner as C structures. |
| </p> |
| |
| <p> |
| Static class members present a special problem for Python. Prior to Python-2.2, |
| Python classes had no support for static methods and no version of Python |
| supports static member variables in a manner that SWIG can utilize. Therefore, |
| SWIG generates wrappers that try to work around some of these issues. To illustrate, |
| suppose you have a class like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Spam { |
| public: |
| static void foo(); |
| static int bar; |
| |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| In Python, the static member can be access in three different ways: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> example.Spam_foo() # Spam::foo() |
| >>> s = example.Spam() |
| >>> s.foo() # Spam::foo() via an instance |
| >>> example.Spam.foo() # Spam::foo(). Python-2.2 only |
| </pre> |
| </div> |
| |
| <p> |
| The first two methods of access are supported in all versions of Python. The |
| last technique is only available in Python-2.2 and later versions. |
| </p> |
| |
| <p> |
| Static member variables are currently accessed as global variables. This means, |
| they are accessed through <tt>cvar</tt> like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> print example.cvar.Spam_bar |
| 7 |
| </pre> |
| </div> |
| |
| <H3><a name="Python_nn21"></a>30.3.8 C++ inheritance</H3> |
| |
| |
| <p> |
| SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have |
| classes like this |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| ... |
| }; |
| |
| class Bar : public Foo { |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| those classes are wrapped into a hierarchy of Python classes that reflect the same inheritance |
| structure. All of the usual Python utility functions work normally: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> b = Bar() |
| >>> instance(b,Foo) |
| 1 |
| >>> issubclass(Bar,Foo) |
| 1 |
| >>> issubclass(Foo,Bar) |
| 0 |
| </pre> |
| </div> |
| |
| <p> |
| Furthermore, if you have functions like this |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void spam(Foo *f); |
| </pre> |
| </div> |
| |
| <p> |
| then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any class derived from <tt>Foo</tt>. |
| </p> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| In C++, there are many different ways a function might receive |
| and manipulate objects. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void spam1(Foo *x); // Pass by pointer |
| void spam2(Foo &x); // Pass by reference |
| void spam3(const Foo &x);// Pass by const reference |
| void spam4(Foo x); // Pass by value |
| void spam5(Foo x[]); // Array of objects |
| </pre> |
| </div> |
| |
| <p> |
| In Python, there is no detailed distinction like this--specifically, |
| there are only "objects". There are no pointers, references, arrays, |
| and so forth. Because of this, SWIG unifies all of these types |
| together in the wrapper code. For instance, if you actually had the |
| above functions, it is perfectly legal to do this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = Foo() # Create a Foo |
| >>> spam1(f) # Ok. Pointer |
| >>> spam2(f) # Ok. Reference |
| >>> spam3(f) # Ok. Const reference |
| >>> spam4(f) # Ok. Value. |
| >>> spam5(f) # Ok. Array (1 element) |
| </pre> |
| </div> |
| |
| <p> |
| Similar behavior occurs for return values. For example, if you had |
| functions like this, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| Foo *spam6(); |
| Foo &spam7(); |
| Foo spam8(); |
| const Foo &spam9(); |
| </pre> |
| </div> |
| |
| <p> |
| then all three functions will return a pointer to some <tt>Foo</tt> object. |
| Since the third function (spam8) returns a value, newly allocated memory is used |
| to hold the result and a pointer is returned (Python will release this memory |
| when the return value is garbage collected). The fourth case (spam9) |
| which returns a const reference, in most of the cases will be |
| 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> |
| |
| |
| <p> |
| C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example, |
| if you have two functions like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void foo(int); |
| void foo(char *c); |
| </pre> |
| </div> |
| |
| <p> |
| You can use them in Python in a straightforward manner: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> foo(3) # foo(int) |
| >>> foo("Hello") # foo(char *c) |
| </pre> |
| </div> |
| |
| <p> |
| Similarly, if you have a class like this, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| public: |
| Foo(); |
| Foo(const Foo &); |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| you can write Python code like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = Foo() # Create a Foo |
| >>> g = Foo(f) # Copy f |
| </pre> |
| </div> |
| |
| <p> |
| Overloading support is not quite as flexible as in C++. Sometimes there are methods that SWIG |
| can't disambiguate. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void spam(int); |
| void spam(short); |
| </pre> |
| </div> |
| |
| <p> |
| or |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void foo(Bar *b); |
| void foo(Bar &b); |
| </pre> |
| </div> |
| |
| <p> |
| If declarations such as these appear, you will get a warning message like this: |
| </p> |
| |
| <div class="shell"> |
| <pre> |
| example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int) |
| at example.i:11. |
| </pre> |
| </div> |
| |
| <p> |
| To fix this, you either need to ignore or rename one of the methods. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %rename(spam_short) spam(short); |
| ... |
| void spam(int); |
| void spam(short); // Accessed as spam_short |
| </pre> |
| </div> |
| |
| <p> |
| or |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %ignore spam(short); |
| ... |
| void spam(int); |
| void spam(short); // Ignored |
| </pre> |
| </div> |
| |
| <p> |
| SWIG resolves overloaded functions and methods using a disambiguation scheme that ranks and sorts |
| declarations according to a set of type-precedence rules. The order in which declarations appear |
| in the input does not matter except in situations where ambiguity arises--in this case, the |
| first declaration takes precedence. |
| </p> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| Certain C++ overloaded operators can be handled automatically by SWIG. For example, |
| consider a class like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Complex { |
| private: |
| double rpart, ipart; |
| public: |
| Complex(double r = 0, double i = 0) : rpart(r), ipart(i) { } |
| Complex(const Complex &c) : rpart(c.rpart), ipart(c.ipart) { } |
| Complex &operator=(const Complex &c); |
| |
| Complex operator+=(const Complex &c) const; |
| Complex operator+(const Complex &c) const; |
| Complex operator-(const Complex &c) const; |
| Complex operator*(const Complex &c) const; |
| Complex operator-() const; |
| |
| double re() const { return rpart; } |
| double im() const { return ipart; } |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| When wrapped, it works like you expect: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> c = Complex(3,4) |
| >>> d = Complex(7,8) |
| >>> e = c + d |
| >>> e.re() |
| 10.0 |
| >>> e.im() |
| 12.0 |
| >>> c += d |
| >>> c.re() |
| 10.0 |
| >>> c.im() |
| 12.0 |
| |
| </pre> |
| </div> |
| |
| <p> |
| One restriction with operator overloading support is that SWIG is not |
| able to fully handle operators that aren't defined as part of the class. |
| For example, if you had code like this |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Complex { |
| ... |
| friend Complex operator+(double, const Complex &c); |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| then SWIG ignores it and issues a warning. You can still wrap the operator, |
| but you may have to encapsulate it in a special function. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %rename(Complex_add_dc) operator+(double, const Complex &); |
| </pre> |
| </div> |
| |
| <p> |
| There are ways to make this operator appear as part of the class using the <tt>%extend</tt> directive. |
| Keep reading. |
| </p> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| SWIG is aware of C++ namespaces, but namespace names do not appear in |
| the module nor do namespaces result in a module that is broken up into |
| submodules or packages. For example, if you have a file like this, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| |
| namespace foo { |
| int fact(int n); |
| struct Vector { |
| double x,y,z; |
| }; |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| it works in Python as follows: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| >>> example.fact(3) |
| 6 |
| >>> v = example.Vector() |
| >>> v.x = 3.4 |
| >>> print v.y |
| 0.0 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| If your program has more than one namespace, name conflicts (if any) can be resolved using <tt>%rename</tt> |
| For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %rename(Bar_spam) Bar::spam; |
| |
| namespace Foo { |
| int spam(); |
| } |
| |
| namespace Bar { |
| int spam(); |
| } |
| </pre> |
| </div> |
| |
| <p> |
| If you have more than one namespace and your want to keep their |
| symbols separate, consider wrapping them as separate SWIG modules. |
| For example, make the module name the same as the namespace and create |
| extension modules for each namespace separately. If your program |
| 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> |
| |
| |
| <p> |
| C++ templates don't present a huge problem for SWIG. However, in order |
| to create wrappers, you have to tell SWIG to create wrappers for a particular |
| template instantiation. To do this, you use the <tt>%template</tt> directive. |
| For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %{ |
| #include "pair.h" |
| %} |
| |
| template<class T1, class T2> |
| struct pair { |
| typedef T1 first_type; |
| typedef T2 second_type; |
| T1 first; |
| T2 second; |
| pair(); |
| pair(const T1&, const T2&); |
| ~pair(); |
| }; |
| |
| %template(pairii) pair<int,int>; |
| </pre> |
| </div> |
| |
| <p> |
| In Python: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| >>> p = example.pairii(3,4) |
| >>> p.first |
| 3 |
| >>> p.second |
| 4 |
| </pre> |
| </div> |
| |
| <p> |
| Obviously, there is more to template wrapping than shown in this example. |
| More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. |
| Some more complicated |
| examples will appear later. |
| </p> |
| |
| <H3><a name="Python_nn27"></a>30.3.14 C++ Smart Pointers</H3> |
| |
| |
| <p> |
| In certain C++ programs, it is common to use classes that have been wrapped by |
| so-called "smart pointers." Generally, this involves the use of a template class |
| that implements <tt>operator->()</tt> like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| template<class T> class SmartPtr { |
| ... |
| T *operator->(); |
| ... |
| } |
| </pre> |
| </div> |
| |
| <p> |
| Then, if you have a class like this, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| public: |
| int x; |
| int bar(); |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| A smart pointer would be used in C++ as follows: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown) |
| ... |
| p->x = 3; // Foo::x |
| int y = p->bar(); // Foo::bar |
| </pre> |
| </div> |
| |
| <p> |
| To wrap this in Python, simply tell SWIG about the <tt>SmartPtr</tt> class and the low-level |
| <tt>Foo</tt> object. Make sure you instantiate <tt>SmartPtr</tt> using <tt>%template</tt> if necessary. |
| For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| ... |
| %template(SmartPtrFoo) SmartPtr<Foo>; |
| ... |
| </pre> |
| </div> |
| |
| <p> |
| Now, in Python, everything should just "work": |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> p = example.CreateFoo() # Create a smart-pointer somehow |
| >>> p.x = 3 # Foo::x |
| >>> p.bar() # Foo::bar |
| </pre> |
| </div> |
| |
| <p> |
| If you ever need to access the underlying pointer returned by <tt>operator->()</tt> itself, |
| simply use the <tt>__deref__()</tt> method. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = p.__deref__() # Returns underlying Foo * |
| </pre> |
| </div> |
| |
| |
| <H3><a name="Python_nn27a"></a>30.3.15 C++ Reference Counted Objects (ref/unref)</H3> |
| |
| |
| <p> |
| Another usual idiom in C++ is the use of reference counted |
| objects. Consider for example: |
| |
| <div class="code"> |
| <pre> |
| class RCObj { |
| // implement the ref counting mechanism |
| int add_ref(); |
| int del_ref(); |
| int ref_count(); |
| |
| public: |
| virtual ~RCObj() = 0; |
| |
| int ref() const { |
| return add_ref(); |
| } |
| |
| int unref() const { |
| if (ref_count() == 0 || del_ref() == 0 ) { |
| delete this; |
| return 0; |
| } |
| return ref_count(); |
| } |
| }; |
| |
| |
| class A : RCObj { |
| public: |
| A(); |
| int foo(); |
| }; |
| |
| |
| class B { |
| A *_a; |
| |
| public: |
| B(A *a) : _a(a) { |
| a->ref(); |
| } |
| |
| ~B() { |
| a->unref(); |
| } |
| }; |
| |
| int main() { |
| A *a = new A(); |
| a->ref(); // 'a' is ref here |
| |
| B *b1 = new B(a); // 'a' is ref here |
| if (1 + 1 == 2) { |
| B *b2 = new B(a); // 'a' is ref here |
| delete b2; // 'a' is unref, but not deleted |
| } |
| |
| delete b1; // 'a' is unref, but not deleted |
| a->unref(); // 'a' is unref and deleted |
| } |
| </pre> |
| </div> |
| |
| <p> |
| In the example above, the 'A' class instance 'a' is a reference counted |
| object, which can't be deleted arbitrarily since it is shared between |
| the objects 'b1' and 'b2'. 'A' is derived from an Reference Counted |
| Object 'RCObj', which implements the ref/unref idiom. |
| </p> |
| |
| <p> |
| To tell SWIG that 'RCObj' and all its derived classes are reference |
| counted objects, you use the "ref" and "unref" features, or |
| <tt>%ref</tt> and <tt>%unref</tt> directives (since 1.3.28). For example: |
| </p> |
| |
| |
| <div class="code"> |
| <pre> |
| %module example |
| ... |
| |
| %feature("ref") RCObj "$this->ref();" |
| %feature("unref") RCObj "$this->unref();" |
| |
| %include "rcobj.h" |
| %include "A.h" |
| ... |
| </pre> |
| </div> |
| |
| or, using the directive form: |
| |
| |
| <div class="code"> |
| <pre> |
| %module example |
| ... |
| |
| %ref RCObj "$this->ref();" |
| %unref RCObj "$this->unref();" |
| |
| %include "rcobj.h" |
| %include "A.h" |
| ... |
| </pre> |
| </div> |
| |
| |
| |
| <p> |
| where the code passed to the "ref" and "unref" features will be |
| executed as needed whenever a new object is passed to python, or when |
| python tries to release the shadow object instance, respectively. |
| </p> |
| |
| <p> |
| In the python side, the use of a reference counted object is not |
| different than any other regular instance: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| def create_A(): |
| a = A() # SWIG ref 'a' (new object is passed to python) |
| b1 = B(a) # C++ ref 'a' |
| if 1 + 1 == 2: |
| b2 = B(a) # C++ ref 'a' |
| return a # 'b1' and 'b2' are released, C++ unref 'a' twice |
| |
| a = create_A() |
| exit # 'a' is released, SWIG unref 'a' |
| </pre> |
| </div> |
| |
| <p> |
| Note that the user doesn't explicitly need to call 'a->ref()' nor 'a->unref()' |
| (as neither 'delete a'). Instead, SWIG take cares of executing the "ref" |
| and "unref" codes as needed. If the user doesn't specify the |
| "ref/unref" features, SWIG will produce a code equivalent to define |
| them as: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %feature("ref") "" |
| %feature("unref") "delete $this;" |
| </pre> |
| </div> |
| |
| <p> |
| In other words, SWIG will not do anything special when a new object |
| is passed to python, and it will always 'delete' the object when |
| python releases the proxy instance. |
| </p> |
| |
| |
| <H2><a name="Python_nn28"></a>30.4 Further details on the Python class interface</H2> |
| |
| |
| <p> |
| In the previous section, a high-level view of Python wrapping was |
| presented. A key component of this wrapping is that structures and |
| classes are wrapped by Python proxy classes. This provides a very |
| natural Python interface and allows SWIG to support a number of |
| advanced features such as operator overloading. However, a number |
| 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> |
| |
| |
| <p> |
| In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters, |
| details of low-level structure and class wrapping are described. To summarize those chapters, if you |
| have a class like this |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| public: |
| int x; |
| int spam(int); |
| ... |
| </pre> |
| </div> |
| |
| <p> |
| then SWIG transforms it into a set of low-level procedural wrappers. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| Foo *new_Foo() { |
| return new Foo(); |
| } |
| void delete_Foo(Foo *f) { |
| delete f; |
| } |
| int Foo_x_get(Foo *f) { |
| return f->x; |
| } |
| void Foo_x_set(Foo *f, int value) { |
| f->x = value; |
| } |
| int Foo_spam(Foo *f, int arg1) { |
| return f->spam(arg1); |
| } |
| </pre> |
| </div> |
| |
| <p> |
| These wrappers can be found in the low-level extension module (e.g., <tt>_example</tt>). |
| </p> |
| |
| <p> |
| Using these wrappers, SWIG generates a high-level Python proxy class (also known as a shadow class) like this (shown |
| for Python 2.2): |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| import _example |
| |
| class Foo(object): |
| def __init__(self): |
| self.this = _example.new_Foo() |
| self.thisown = 1 |
| def __del__(self): |
| if self.thisown: |
| _example.delete_Foo(self.this) |
| def spam(self,arg1): |
| return _example.Foo_spam(self.this,arg1) |
| x = property(_example.Foo_x_get, _example.Foo_x_set) |
| </pre> |
| </div> |
| |
| <p> |
| This class merely holds a pointer to the underlying C++ object (<tt>.this</tt>) and dispatches methods and |
| member variable access to that object using the low-level accessor functions. From a user's point of |
| view, it makes the class work normally: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = example.Foo() |
| >>> f.x = 3 |
| >>> y = f.spam(5) |
| </pre> |
| </div> |
| |
| <p> |
| The fact that the class has been wrapped by a real Python class offers certain advantages. For instance, |
| you can attach new Python methods to the class and you can even inherit from it (something not supported |
| by Python built-in types until Python 2.2). |
| </p> |
| |
| <H3><a name="Python_nn30"></a>30.4.2 Memory management</H3> |
| |
| |
| <p> |
| Associated with proxy object, is an ownership flag <tt>.thisown</tt> The value of this |
| flag determines who is responsible for deleting the underlying C++ object. If set to 1, |
| the Python interpreter will destroy the C++ object when the proxy class is |
| garbage collected. If set to 0 (or if the attribute is missing), then the destruction |
| of the proxy class has no effect on the C++ object. |
| </p> |
| |
| <p> |
| When an object is created by a constructor or returned by value, Python automatically takes |
| ownership of the result. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| public: |
| Foo(); |
| Foo bar(); |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| In Python: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = Foo() |
| >>> f.thisown |
| 1 |
| >>> g = f.bar() |
| >>> g.thisown |
| 1 |
| </pre> |
| </div> |
| |
| <p> |
| On the other hand, when pointers are returned to Python, there is often no way to know where |
| they came from. Therefore, the ownership is set to zero. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| public: |
| ... |
| Foo *spam(); |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <br> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = Foo() |
| >>> s = f.spam() |
| >>> print s.thisown |
| 0 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| This behavior is especially important for classes that act as |
| containers. For example, if a method returns a pointer to an object |
| that is contained inside another object, you definitely don't want |
| Python to assume ownership and destroy it! |
| </p> |
| |
| <p> |
| A good way to indicate that ownership should be set for a returned pointer |
| is to use the <a href="Library.html#Library_nn11">%newobject directive</a>. |
| </p> |
| |
| <p> |
| Related to containers, ownership issues can arise whenever an object is assigned to a member |
| or global variable. For example, consider this interface: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| |
| struct Foo { |
| int value; |
| Foo *next; |
| }; |
| |
| Foo *head = 0; |
| </pre> |
| </div> |
| |
| <p> |
| When wrapped in Python, careful observation will reveal that ownership changes whenever an object |
| is assigned to a global variable. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = example.Foo() |
| >>> f.thisown |
| 1 |
| >>> example.cvar.head = f |
| >>> f.thisown |
| 0 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| In this case, C is now holding a reference to the object---you probably don't want Python to destroy it. |
| Similarly, this occurs for members. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> f = example.Foo() |
| >>> g = example.Foo() |
| >>> f.thisown |
| 1 |
| >>> g.thisown |
| 1 |
| >>> f.next = g |
| >>> g.thisown |
| 0 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| For the most part, memory management issues remain hidden. However, |
| there are occasionally situations where you might have to manually |
| change the ownership of an object. For instance, consider code like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Node { |
| Object *value; |
| public: |
| void set_value(Object *v) { value = v; } |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| Now, consider the following Python code: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> v = Object() # Create an object |
| >>> n = Node() # Create a node |
| >>> n.set_value(v) # Set value |
| >>> v.thisown |
| 1 |
| >>> del v |
| </pre> |
| </div> |
| |
| <p> |
| In this case, the object <tt>n</tt> is holding a reference to |
| <tt>v</tt> internally. However, SWIG has no way to know that this |
| has occurred. Therefore, Python still thinks that it has ownership of the |
| object. Should the proxy object be destroyed, then the C++ destructor |
| will be invoked and <tt>n</tt> will be holding a stale-pointer. If |
| you're lucky, you will only get a segmentation fault. |
| </p> |
| |
| <p> |
| To work around this, it is always possible to flip the ownership flag. For example, |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> v.thisown = 0 |
| </pre> |
| </div> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| SWIG makes every attempt to preserve backwards compatibility with |
| older versions of Python to the extent that it is possible. However, |
| in Python-2.2, an entirely new type of class system was introduced. |
| This new-style class system offers many enhancements including static |
| member functions, properties (managed attributes), and class methods. |
| Details about all of these changes can be found on <a |
| href="//www.python.org">www.python.org</a> and is not repeated here. |
| </p> |
| |
| <p> |
| To address differences between Python versions, SWIG currently emits |
| dual-mode proxy class wrappers. In Python-2.2 and newer releases, |
| these wrappers encapsulate C++ objects in new-style classes that take |
| advantage of new features (static methods and properties). However, |
| if these very same wrappers are imported into an older version of Python, |
| old-style classes are used instead. |
| </p> |
| |
| <p> |
| This dual-nature of the wrapper code means that you can create extension |
| modules with SWIG and those modules will work with all versions of Python |
| ranging from Python-1.4 to the very latest release. Moreover, the wrappers take |
| advantage of Python-2.2 features when available. |
| </p> |
| |
| <p> |
| For the most part, the interface presented to users is the same regardless |
| of what version of Python is used. The only incompatibility lies in the handling |
| of static member functions. In Python-2.2, they can be accessed via the |
| 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> |
| |
| |
| <p> |
| Proxy classes provide a more natural, object-oriented way to access |
| extension classes. As described above, each proxy instance has an |
| associated C++ instance, and method calls to the proxy are passed to the |
| C++ instance transparently via C wrapper functions. |
| </p> |
| |
| <p> |
| This arrangement is asymmetric in the sense that no corresponding |
| mechanism exists to pass method calls down the inheritance chain from |
| C++ to Python. In particular, if a C++ class has been extended in Python |
| (by extending the proxy class), these extensions will not be visible |
| from C++ code. Virtual method calls from C++ are thus not able access |
| the lowest implementation in the inheritance chain. |
| </p> |
| |
| <p> |
| Changes have been made to SWIG 1.3.18 to address this problem and |
| make the relationship between C++ classes and proxy classes more |
| symmetric. To achieve this goal, new classes called directors are |
| introduced at the bottom of the C++ inheritance chain. The job of the |
| directors is to route method calls correctly, either to C++ |
| implementations higher in the inheritance chain or to Python |
| implementations lower in the inheritance chain. The upshot is that C++ |
| classes can be extended in Python and from C++ these extensions look |
| exactly like native C++ classes. Neither C++ code nor Python code needs |
| to know where a particular method is implemented: the combination of |
| 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> |
| |
| |
| <p> |
| The director feature is disabled by default. To use directors you |
| must make two changes to the interface file. First, add the "directors" |
| option to the %module directive, like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module(directors="1") modulename |
| </pre> |
| </div> |
| |
| <p> |
| Without this option no director code will be generated. Second, you |
| must use the %feature("director") directive to tell SWIG which classes |
| and methods should get directors. The %feature directive can be applied |
| globally, to specific classes, and to specific methods, like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| // generate directors for all classes that have virtual methods |
| %feature("director"); |
| |
| // generate directors for all virtual methods in class Foo |
| %feature("director") Foo; |
| |
| // generate a director for just Foo::bar() |
| %feature("director") Foo::bar; |
| </pre> |
| </div> |
| |
| <p> |
| You can use the %feature("nodirector") directive to turn off |
| directors for specific classes or methods. So for example, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %feature("director") Foo; |
| %feature("nodirector") Foo::bar; |
| </pre> |
| </div> |
| |
| <p> |
| will generate directors for all virtual methods of class Foo except |
| bar(). |
| </p> |
| |
| <p> |
| Directors can also be generated implicitly through inheritance. |
| In the following, class Bar will get a director class that handles |
| the methods one() and two() (but not three()): |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %feature("director") Foo; |
| class Foo { |
| public: |
| Foo(int foo); |
| virtual void one(); |
| virtual void two(); |
| }; |
| |
| class Bar: public Foo { |
| public: |
| virtual void three(); |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| then at the python side you can define |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| import mymodule |
| |
| class MyFoo(mymodule.Foo): |
| def __init__(self, foo): |
| mymodule.Foo(self, foo) |
| |
| def one(self): |
| print "one from python" |
| </pre> |
| </div> |
| |
| |
| <H3><a name="Python_nn34"></a>30.5.2 Director classes</H3> |
| |
| |
| |
| |
| |
| <p> |
| For each class that has directors enabled, SWIG generates a new class |
| that derives from both the class in question and a special |
| <tt>Swig::Director</tt> class. These new classes, referred to as director |
| classes, can be loosely thought of as the C++ equivalent of the Python |
| proxy classes. The director classes store a pointer to their underlying |
| Python object and handle various issues related to object ownership. |
| Indeed, this is quite similar to the "this" and "thisown" members of the |
| Python proxy classes. |
| </p> |
| |
| <p> |
| For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the |
| original C++ class as the director's base class. By default, a director |
| class extends all virtual methods in the inheritance chain of its base |
| class (see the preceding section for how to modify this behavior). |
| Thus all virtual method calls, whether they originate in C++ or in |
| Python via proxy classes, eventually end up in at the implementation in |
| the director class. The job of the director methods is to route these |
| method calls to the appropriate place in the inheritance chain. By |
| "appropriate place" we mean the method that would have been called if |
| the C++ base class and its extensions in Python were seamlessly |
| integrated. That seamless integration is exactly what the director |
| classes provide, transparently skipping over all the messy extension API |
| glue that binds the two languages together. |
| </p> |
| |
| <p> |
| In reality, the "appropriate place" is one of only two possibilities: |
| C++ or Python. Once this decision is made, the rest is fairly easy. If |
| the correct implementation is in C++, then the lowest implementation of |
| the method in the C++ inheritance chain is called explicitly. If the |
| correct implementation is in Python, the Python API is used to call the |
| method of the underlying Python object (after which the usual virtual |
| method resolution in Python automatically finds the right |
| implementation). |
| </p> |
| |
| <p> |
| Now how does the director decide which language should handle the method call? |
| The basic rule is to handle the method in Python, unless there's a good |
| reason not to. The reason for this is simple: Python has the most |
| "extended" implementation of the method. This assertion is guaranteed, |
| since at a minimum the Python proxy class implements the method. If the |
| method in question has been extended by a class derived from the proxy |
| class, that extended implementation will execute exactly as it should. |
| If not, the proxy class will route the method call into a C wrapper |
| function, expecting that the method will be resolved in C++. The wrapper |
| will call the virtual method of the C++ instance, and since the director |
| extends this the call will end up right back in the director method. Now |
| comes the "good reason not to" part. If the director method were to blindly |
| call the Python method again, it would get stuck in an infinite loop. We avoid this |
| situation by adding special code to the C wrapper function that tells |
| the director method to not do this. The C wrapper function compares the |
| pointer to the Python object that called the wrapper function to the |
| pointer stored by the director. If these are the same, then the C |
| wrapper function tells the director to resolve the method by calling up |
| the C++ inheritance chain, preventing an infinite loop. |
| </p> |
| |
| <p> |
| One more point needs to be made about the relationship between director |
| classes and proxy classes. When a proxy class instance is created in |
| Python, SWIG creates an instance of the original C++ class and assigns |
| it to <tt>.this</tt>. This is exactly what happens without directors and |
| is true even if directors are enabled for the particular class in |
| question. When a class <i>derived</i> from a proxy class is created, |
| however, SWIG then creates an instance of the corresponding C++ director |
| class. The reason for this difference is that user-defined subclasses |
| may override or extend methods of the original class, so the director |
| class is needed to route calls to these methods correctly. For |
| unmodified proxy classes, all methods are ultimately implemented in C++ |
| 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> |
| |
| |
| <p> |
| Memory management issues are slightly more complicated with directors |
| than for proxy classes alone. Python instances hold a pointer to the |
| associated C++ director object, and the director in turn holds a pointer |
| back to the Python object. By default, proxy classes own their C++ |
| director object and take care of deleting it when they are garbage |
| collected. |
| </p> |
| |
| <p> |
| This relationship can be reversed by calling the special |
| <tt>__disown__()</tt> method of the proxy class. After calling this |
| method, the <tt>.thisown</tt> flag is set to zero, and the director |
| class increments the reference count of the Python object. When the |
| director class is deleted it decrements the reference count. Assuming no |
| outstanding references to the Python object remain, the Python object |
| will be destroyed at the same time. This is a good thing, since |
| directors and proxies refer to each other and so must be created and |
| destroyed together. Destroying one without destroying the other will |
| likely cause your program to segfault. |
| </p> |
| |
| <p> |
| To help ensure that no references to the Python object remain after |
| calling <tt>__disown__()</tt>, this method returns a weak reference to |
| the Python object. Weak references are only available in Python versions |
| 2.1 and higher, so for older versions you must explicitly delete all |
| references. Here is an example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| public: |
| ... |
| }; |
| class FooContainer { |
| public: |
| void addFoo(Foo *); |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <br> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> c = FooContainer() |
| >>> a = Foo().__disown()__ |
| >>> c.addFoo(a) |
| >>> b = Foo() |
| >>> b = b.__disown()__ |
| >>> c.addFoo(b) |
| >>> c.addFoo(Foo().__disown()__) |
| </pre> |
| </div> |
| |
| <p> |
| In this example, we are assuming that FooContainer will take care of |
| 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> |
| |
| |
| <p> |
| With directors routing method calls to Python, and proxies routing them |
| to C++, the handling of exceptions is an important concern. By default, the |
| directors ignore exceptions that occur during method calls that are |
| resolved in Python. To handle such exceptions correctly, it is necessary |
| to temporarily translate them into C++ exceptions. This can be done with |
| the %feature("director:except") directive. The following code should |
| suffice in most cases: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %feature("director:except") { |
| if ($error != NULL) { |
| throw Swig::DirectorMethodException(); |
| } |
| } |
| </pre> |
| </div> |
| |
| <p> |
| This code will check the Python error state after each method call from |
| a director into Python, and throw a C++ exception if an error occurred. |
| This exception can be caught in C++ to implement an error handler. |
| Currently no information about the Python error is stored in the |
| Swig::DirectorMethodException object, but this will likely change in |
| the future. |
| </p> |
| |
| <p> |
| It may be the case that a method call originates in Python, travels up |
| to C++ through a proxy class, and then back into Python via a director |
| method. If an exception occurs in Python at this point, it would be nice |
| for that exception to find its way back to the original caller. This can |
| be done by combining a normal %exception directive with the |
| <tt>director:except</tt> handler shown above. Here is an example of a |
| suitable exception handler: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %exception { |
| try { $action } |
| catch (Swig::DirectorException &e) { SWIG_fail; } |
| } |
| </pre> |
| </div> |
| |
| <p> |
| The class Swig::DirectorException used in this example is actually a |
| base class of Swig::DirectorMethodException, so it will trap this |
| exception. Because the Python error state is still set when |
| 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> |
| |
| |
| <p> |
| Enabling directors for a class will generate a new director method for |
| every virtual method in the class' inheritance chain. This alone can |
| generate a lot of code bloat for large hierarchies. Method arguments |
| that require complex conversions to and from target language types can |
| result in large director methods. For this reason it is recommended that |
| you selectively enable directors only for specific classes that are |
| likely to be extended in Python and used in C++. |
| </p> |
| |
| <p> |
| Compared to classes that do not use directors, the call routing in the |
| director methods does add some overhead. In particular, at least one |
| dynamic cast and one extra function call occurs per method call from |
| Python. Relative to the speed of Python execution this is probably |
| completely negligible. For worst case routing, a method call that |
| ultimately resolves in C++ may take one extra detour through Python in |
| order to ensure that the method does not have an extended Python |
| implementation. This could result in a noticeable overhead in some cases. |
| </p> |
| |
| <p> |
| Although directors make it natural to mix native C++ objects with Python |
| objects (as director objects) via a common base class pointer, one |
| should be aware of the obvious fact that method calls to Python objects |
| will be much slower than calls to C++ objects. This situation can be |
| optimized by selectively enabling director methods (using the %feature |
| 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> |
| |
| |
| <p> |
| Typemaps for input and output of most of the basic types from director |
| classes have been written. These are roughly the reverse of the usual |
| input and output typemaps used by the wrapper code. The typemap |
| operation names are 'directorin', 'directorout', and 'directorargout'. |
| The director code does not currently use any of the other kinds of typemaps. |
| It is not clear at this point which kinds are appropriate and |
| need to be supported. |
| </p> |
| |
| |
| <H3><a name="Python_nn39"></a>30.5.7 Miscellaneous</H3> |
| |
| |
| <p> |
| Director typemaps for STL classes are in place, and hence you should |
| be able to use std::vector, std::string, etc., as you would any other type. |
| </p> |
| |
| <p> |
| <b>Note:</b> The director typemaps for return types based in const |
| references, such as |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| … |
| virtual const int& bar(); |
| … |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| will work only for simple call scenarios. Usually the resulting code |
| is neither thread or reentrant safe. Hence, the user is advised to |
| avoid returning const references in director methods. For example, |
| the user could modify the method interface to use lvalue return |
| types, wherever possible, for example |
| </p> |
| |
| <div class="code"> |
| <pre> |
| class Foo { |
| … |
| virtual int bar(); |
| … |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| If that is not possible, the user should avoid enabling the |
| director feature for reentrant, recursive or threaded member |
| methods that return const references. |
| </p> |
| |
| |
| <H2><a name="Python_nn40"></a>30.6 Common customization features</H2> |
| |
| |
| <p> |
| The last section presented the absolute basics of C/C++ wrapping. If |
| you do nothing but feed SWIG a header file, you will get an interface |
| that mimics the behavior described. However, sometimes this isn't |
| enough to produce a nice module. Certain types of functionality might |
| be missing or the interface to certain functions might be awkward. |
| 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> |
| |
| |
| <p> |
| Sometimes when you create a module, it is missing certain bits of functionality. For |
| example, if you had a function like this |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void set_transform(Image *im, double m[4][4]); |
| </pre> |
| </div> |
| |
| <p> |
| it would be accessible from Python, but there may be no easy way to call it. |
| For example, you might get errors like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = [ |
| ... [1,0,0,0], |
| ... [0,1,0,0], |
| ... [0,0,1,0], |
| ... [0,0,0,1]] |
| >>> set_transform(im,a) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: Type error. Expected _p_a_4__double |
| </pre> |
| </div> |
| |
| <p> |
| The problem here is that there is no easy way to construct and manipulate a suitable |
| <tt>double [4][4]</tt> value to use. To fix this, you can write some extra C helper |
| functions. Just use the <tt>%inline</tt> directive. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %inline %{ |
| /* Note: double[4][4] is equivalent to a pointer to an array double (*)[4] */ |
| double (*new_mat44())[4] { |
| return (double (*)[4]) malloc(16*sizeof(double)); |
| } |
| void free_mat44(double (*x)[4]) { |
| free(x); |
| } |
| void mat44_set(double x[4][4], int i, int j, double v) { |
| x[i][j] = v; |
| } |
| double mat44_get(double x[4][4], int i, int j) { |
| return x[i][j]; |
| } |
| %} |
| </pre> |
| </div> |
| |
| <p> |
| From Python, you could then write code like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = new_mat44() |
| >>> mat44_set(a,0,0,1.0) |
| >>> mat44_set(a,1,1,1.0) |
| >>> mat44_set(a,2,2,1.0) |
| ... |
| >>> set_transform(im,a) |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| Admittedly, this is not the most elegant looking approach. However, it works and it wasn't too |
| hard to implement. It is possible to clean this up using Python code, typemaps, and other |
| customization features as covered in later sections. |
| </p> |
| |
| <H3><a name="Python_nn42"></a>30.6.2 Adding additional Python code</H3> |
| |
| |
| <p> |
| If writing support code in C isn't enough, it is also possible to write code in |
| Python. This code gets inserted in to the <tt>.py</tt> file created by SWIG. One |
| use of Python code might be to supply a high-level interface to certain functions. |
| For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void set_transform(Image *im, double x[4][4]); |
| |
| ... |
| /* Rewrite the high level interface to set_transform */ |
| %pythoncode %{ |
| def set_transform(im,x): |
| a = new_mat44() |
| for i in range(4): |
| for j in range(4): |
| mat44_set(a,i,j,x[i][j]) |
| _example.set_transform(im,a) |
| free_mat44(a) |
| %} |
| </pre> |
| </div> |
| |
| <p> |
| In this example, <tt>set_transform()</tt> provides a high-level Python interface built on top of |
| low-level helper functions. For example, this code now seems to work: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = [ |
| ... [1,0,0,0], |
| ... [0,1,0,0], |
| ... [0,0,1,0], |
| ... [0,0,0,1]] |
| >>> set_transform(im,a) |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| Admittedly, this whole scheme for wrapping the two-dimension array |
| argument is rather ad-hoc. Besides, shouldn't a Python list or a |
| Numeric Python array just work normally? We'll get to those examples |
| soon enough. For now, think of this example as an illustration of |
| what can be done without having to rely on any of the more advanced |
| customization features. |
| </p> |
| |
| <p>Sometimes you may want to replace or modify the wrapper function |
| that SWIG creates in the proxy <tt>.py</tt> file. The Python module |
| in SWIG provides some features that enable you do do this. First, to |
| entirely replace a proxy function you can use |
| <tt>%feature("shadow")</tt>. For example:</p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| |
| // Rewrite bar() python code |
| |
| %feature("shadow") Foo::bar(int) %{ |
| def bar(*args): |
| #do something before |
| $action |
| #do something after |
| %} |
| |
| class Foo { |
| public: |
| int bar(int x); |
| } |
| </pre> |
| </div> |
| |
| <p> where <tt>$action</tt> will be replaced by the call to |
| the C/C++ proper method. |
| </p> |
| |
| <p> |
| Often the proxy function created by SWIG is fine, but you simply want |
| to add code to it without touching the rest of the generated function |
| body. For these cases SWIG provides the <tt>pythonprepend</tt> and |
| <tt>pythonappend</tt> features which do exactly as their names suggest. The |
| <tt>pythonprepend</tt> feature will insert its value at the beginning of the |
| proxy function, and <tt>pythonappend</tt> will insert code at the end of the |
| proxy, just before the return statement. |
| </p> |
| |
| |
| <div class="code"> |
| <pre> |
| %module example |
| |
| // Add python code to bar() |
| |
| %feature("pythonprepend") Foo::bar(int) %{ |
| #do something before C++ call |
| %} |
| |
| %feature("pythonappend") Foo::bar(int) %{ |
| #do something after C++ call |
| %} |
| |
| |
| class Foo { |
| public: |
| int bar(int x); |
| } |
| </pre> |
| </div> |
| |
| <p> |
| Notes: Usually the <tt>pythonappend</tt> and <tt>pythonprepend</tt> |
| features are safer to use than the <tt>shadow</tt> feature. Also, from |
| SWIG version 1.3.28 you can use the directive forms |
| <tt>%pythonappend</tt> and <tt>%pythonprepend</tt> as follows:</p> |
| |
| |
| <div class="code"> |
| <pre> |
| %module example |
| |
| // Add python code to bar() |
| |
| %pythonprepend Foo::bar(int) %{ |
| #do something before C++ call |
| %} |
| |
| %pythonappend Foo::bar(int) %{ |
| #do something after C++ call |
| %} |
| |
| |
| class Foo { |
| public: |
| int bar(int x); |
| } |
| </pre> |
| </div> |
| |
| |
| |
| |
| <H3><a name="Python_nn43"></a>30.6.3 Class extension with %extend</H3> |
| |
| |
| <p> |
| One of the more interesting features of SWIG is that it can extend |
| structures and classes with new methods--at least in the Python interface. |
| Here is a simple example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %{ |
| #include "someheader.h" |
| %} |
| |
| struct Vector { |
| double x,y,z; |
| }; |
| |
| %extend Vector { |
| char *__str__() { |
| static char tmp[1024]; |
| sprintf(tmp,"Vector(%g,%g,%g)", $self->x,$self->y,$self->z); |
| return tmp; |
| } |
| Vector(double x, double y, double z) { |
| Vector *v = (Vector *) malloc(sizeof(Vector)); |
| v->x = x; |
| v->y = y; |
| v->z = z; |
| return v; |
| } |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| Now, in Python |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> v = example.Vector(2,3,4) |
| >>> print v |
| Vector(2,3,4) |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| <tt>%extend</tt> can be used for many more tasks than this. |
| For example, if you wanted to overload a Python operator, you might do this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %extend Vector { |
| Vector __add__(Vector *other) { |
| Vector v; |
| v.x = $self->x + other->x; |
| v.y = $self->y + other->y; |
| v.z = $self->z + other->z; |
| return v; |
| } |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| Use it like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> import example |
| >>> v = example.Vector(2,3,4) |
| >>> w = example.Vector(10,11,12) |
| >>> print v+w |
| Vector(12,14,16) |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| <tt>%extend</tt> works with both C and C++ code. It does not modify the underlying object |
| 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> |
| |
| |
| <p> |
| If a C or C++ function throws an error, you may want to convert that error into a Python |
| exception. To do this, you can use the <tt>%exception</tt> directive. <tt>%exception</tt> |
| simply lets you rewrite part of the generated wrapper code to include an error check. |
| </p> |
| |
| <p> |
| In C, a function often indicates an error by returning a status code (a negative number |
| or a NULL pointer perhaps). Here is a simple example of how you might handle that: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %exception malloc { |
| $action |
| if (!result) { |
| PyErr_SetString(PyExc_MemoryError,"Not enough memory"); |
| return NULL; |
| } |
| } |
| void *malloc(size_t nbytes); |
| </pre> |
| </div> |
| |
| <p> |
| In Python, |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = example.malloc(2000000000) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| MemoryError: Not enough memory |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| If a library provides some kind of general error handling framework, you can also use |
| that. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %exception { |
| $action |
| if (err_occurred()) { |
| PyErr_SetString(PyExc_RuntimeError, err_message()); |
| return NULL; |
| } |
| } |
| </pre> |
| </div> |
| |
| <p> |
| No declaration name is given to <tt>%exception</tt>, it is applied to all wrapper functions. |
| </p> |
| |
| <p> |
| C++ exceptions are also easy to handle. For example, you can write code like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %exception getitem { |
| try { |
| $action |
| } catch (std::out_of_range &e) { |
| PyErr_SetString(PyExc_IndexError, const_cast<char*>(e.what())); |
| return NULL; |
| } |
| } |
| |
| class Base { |
| public: |
| Foo *getitem(int index); // Exception handled added |
| ... |
| }; |
| </pre> |
| </div> |
| |
| <p> |
| When raising a Python exception from C, use the <tt>PyErr_SetString()</tt> |
| function as shown above. The following exception types can be used as the first argument. |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyExc_ArithmeticError |
| PyExc_AssertionError |
| PyExc_AttributeError |
| PyExc_EnvironmentError |
| PyExc_EOFError |
| PyExc_Exception |
| PyExc_FloatingPointError |
| PyExc_ImportError |
| PyExc_IndexError |
| PyExc_IOError |
| PyExc_KeyError |
| PyExc_KeyboardInterrupt |
| PyExc_LookupError |
| PyExc_MemoryError |
| PyExc_NameError |
| PyExc_NotImplementedError |
| PyExc_OSError |
| PyExc_OverflowError |
| PyExc_RuntimeError |
| PyExc_StandardError |
| PyExc_SyntaxError |
| PyExc_SystemError |
| PyExc_TypeError |
| PyExc_UnicodeError |
| PyExc_ValueError |
| PyExc_ZeroDivisionError |
| </pre> |
| </div> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| Although SWIG is largely automatic, there are certain types of wrapping problems that |
| require additional user input. Examples include dealing with output parameters, |
| strings, binary data, and arrays. This chapter discusses the common techniques for |
| solving these problems. |
| </p> |
| |
| <H3><a name="Python_nn46"></a>30.7.1 Input and output parameters</H3> |
| |
| |
| <p> |
| A common problem in some C programs is handling parameters passed as simple pointers. For |
| example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void add(int x, int y, int *result) { |
| *result = x + y; |
| } |
| </pre> |
| </div> |
| |
| <p> |
| or perhaps |
| </p> |
| |
| <div class="code"> |
| <pre> |
| int sub(int *x, int *y) { |
| return *x-*y; |
| } |
| </pre> |
| </div> |
| |
| <p> |
| The easiest way to handle these situations is to use the <tt>typemaps.i</tt> file. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %include "typemaps.i" |
| |
| void add(int, int, int *OUTPUT); |
| int sub(int *INPUT, int *INPUT); |
| </pre> |
| </div> |
| |
| <p> |
| In Python, this allows you to pass simple values. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = add(3,4) |
| >>> print a |
| 7 |
| >>> b = sub(7,4) |
| >>> print b |
| 3 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| Notice how the <tt>INPUT</tt> parameters allow integer values to be passed instead of pointers |
| and how the <tt>OUTPUT</tt> parameter creates a return result. |
| </p> |
| |
| <p> |
| If you don't want to use the names <tt>INPUT</tt> or <tt>OUTPUT</tt>, use the <tt>%apply</tt> |
| directive. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %include "typemaps.i" |
| |
| %apply int *OUTPUT { int *result }; |
| %apply int *INPUT { int *x, int *y}; |
| |
| void add(int x, int y, int *result); |
| int sub(int *x, int *y); |
| </pre> |
| </div> |
| |
| <p> |
| If a function mutates one of its parameters like this, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void negate(int *x) { |
| *x = -(*x); |
| } |
| </pre> |
| </div> |
| |
| <p> |
| you can use <tt>INOUT</tt> like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %include "typemaps.i" |
| ... |
| void negate(int *INOUT); |
| </pre> |
| </div> |
| |
| <p> |
| In Python, a mutated parameter shows up as a return value. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = negate(3) |
| >>> print a |
| -3 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| Note: Since most primitive Python objects are immutable, it is not possible to |
| perform in-place modification of a Python object passed as a parameter. |
| </p> |
| |
| <p> |
| The most common use of these special typemap rules is to handle functions that |
| return more than one value. For example, sometimes a function returns a result |
| as well as a special error code: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| /* send message, return number of bytes sent, along with success code */ |
| int send_message(char *text, int len, int *success); |
| </pre> |
| </div> |
| |
| <p> |
| To wrap such a function, simply use the <tt>OUTPUT</tt> rule above. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %include "typemaps.i" |
| %apply int *OUTPUT { int *success }; |
| ... |
| int send_message(char *text, int *success); |
| </pre> |
| </div> |
| |
| <p> |
| When used in Python, the function will return multiple values. |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| bytes, success = send_message("Hello World") |
| if not success: |
| print "Whoa!" |
| else: |
| print "Sent", bytes |
| </pre> |
| </div> |
| |
| <p> |
| Another common use of multiple return values are in query functions. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void get_dimensions(Matrix *m, int *rows, int *columns); |
| </pre> |
| </div> |
| |
| <p> |
| To wrap this, you might use the following: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %include "typemaps.i" |
| %apply int *OUTPUT { int *rows, int *columns }; |
| ... |
| void get_dimensions(Matrix *m, int *rows, *columns); |
| </pre> |
| </div> |
| |
| <p> |
| Now, in Python: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> r,c = get_dimensions(m) |
| </pre> |
| </div> |
| |
| <p> |
| Be aware that the primary purpose of the <tt>typemaps.i</tt> file is to support primitive datatypes. |
| Writing a function like this |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void foo(Bar *OUTPUT); |
| </pre> |
| </div> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| If you must work with simple pointers such as <tt>int *</tt> or <tt>double *</tt> and you don't want to use |
| <tt>typemaps.i</tt>, consider using the <tt>cpointer.i</tt> library file. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module example |
| %include "cpointer.i" |
| |
| %inline %{ |
| extern void add(int x, int y, int *result); |
| %} |
| |
| %pointer_functions(int, intp); |
| </pre> |
| </div> |
| |
| <p> |
| The <tt>%pointer_functions(type,name)</tt> macro generates five helper functions that can be used to create, |
| destroy, copy, assign, and dereference a pointer. In this case, the functions are as follows: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| int *new_intp(); |
| int *copy_intp(int *x); |
| void delete_intp(int *x); |
| void intp_assign(int *x, int value); |
| int intp_value(int *x); |
| </pre> |
| </div> |
| |
| <p> |
| In Python, you would use the functions like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> result = new_intp() |
| >>> print result |
| _108fea8_p_int |
| >>> add(3,4,result) |
| >>> print intp_value(result) |
| 7 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</tt>, the interface is more class-like. |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> result = intp() |
| >>> add(3,4,result) |
| >>> print result.value() |
| 7 |
| </pre> |
| </div> |
| |
| <p> |
| 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> |
| |
| |
| <p> |
| Sometimes a C function expects an array to be passed as a pointer. For example, |
| </p> |
| |
| <div class="code"> |
| <pre> |
| int sumitems(int *first, int nitems) { |
| int i, sum = 0; |
| for (i = 0; i < nitems; i++) { |
| sum += first[i]; |
| } |
| return sum; |
| } |
| </pre> |
| </div> |
| |
| <p> |
| To wrap this into Python, you need to pass an array pointer as the first argument. |
| A simple way to do this is to use the <tt>carrays.i</tt> library file. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %include "carrays.i" |
| %array_class(int, intArray); |
| </pre> |
| </div> |
| |
| <p> |
| The <tt>%array_class(type, name)</tt> macro creates wrappers for an unbounded array object that |
| can be passed around as a simple pointer like <tt>int *</tt> or <tt>double *</tt>. |
| For instance, you will be able to do this in Python: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> a = intArray(10000000) # Array of 10-million integers |
| >>> for i in xrange(10000): # Set some values |
| ... a[i] = i |
| >>> sumitems(a,10000) |
| 49995000 |
| >>> |
| </pre> |
| </div> |
| |
| <p> |
| The array "object" created by <tt>%array_class()</tt> does not |
| encapsulate pointers inside a special array object. In fact, there is |
| no bounds checking or safety of any kind (just like in C). Because of |
| this, the arrays created by this library are extremely low-level |
| indeed. You can't iterate over them nor can you even query their |
| length. In fact, any valid memory address can be accessed if you want |
| (negative indices, indices beyond the end of the array, etc.). |
| Needless to say, this approach is not going to suit all applications. |
| On the other hand, this low-level approach is extremely efficient and |
| 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> |
| |
| |
| <p> |
| If a C function has an argument of <tt>char *</tt>, then a Python string |
| can be passed as input. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| // C |
| void foo(char *s); |
| </pre> |
| </div> |
| |
| <div class="targetlang"> |
| <pre> |
| # Python |
| >>> foo("Hello") |
| </pre> |
| </div> |
| |
| <p> |
| When a Python string is passed as a parameter, the C function receives a pointer to the raw |
| data contained in the string. Since Python strings are immutable, it is illegal |
| for your program to change the value. In fact, doing so will probably crash the Python |
| interpreter. |
| </p> |
| |
| <p> |
| If your program modifies the input parameter or uses it to return data, consider |
| using the <tt>cstring.i</tt> library file described in the <a href="Library.html#Library">SWIG Library</a> chapter. |
| </p> |
| |
| <p> |
| When functions return a <tt>char *</tt>, it is assumed to be a NULL-terminated string. |
| Data is copied into a new Python string and returned. |
| </p> |
| |
| <p> |
| If your program needs to work with binary data, you can use a typemap |
| to expand a Python string into a pointer/length argument pair. As luck would have it, |
| just such a typemap is already defined. Just do this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %apply (char *STRING, int LENGTH) { (char *data, int size) }; |
| ... |
| int parity(char *data, int size, int initial); |
| </pre> |
| </div> |
| |
| <p> |
| Now in Python: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> parity("e\x09ffss\x00\x00\x01\nx", 0) |
| </pre> |
| </div> |
| |
| <p> |
| If you need to return binary data, you might use the |
| <tt>cstring.i</tt> library file. The <tt>cdata.i</tt> library can |
| 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_nn51"></a>30.7.6 String arrays</H3> |
| |
| |
| <H3><a name="Python_nn52"></a>30.7.7 STL wrappers</H3> |
| |
| |
| <H2><a name="Python_nn53"></a>30.8 Typemaps</H2> |
| |
| |
| <p> |
| This section describes how you can modify SWIG's default wrapping behavior |
| for various C/C++ datatypes using the <tt>%typemap</tt> directive. This |
| is an advanced topic that assumes familiarity with the Python C API as well |
| as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. |
| </p> |
| |
| <p> |
| Before proceeding, it should be stressed that typemaps are not a required |
| part of using SWIG---the default wrapping behavior is enough in most cases. |
| 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> |
| |
| |
| <p> |
| A typemap is nothing more than a code generation rule that is attached to |
| a specific C datatype. For example, to convert integers from Python to C, |
| you might define a typemap like this: |
| </p> |
| |
| <div class="code"><pre> |
| %module example |
| |
| %typemap(in) int { |
| $1 = (int) PyLong_AsLong($input); |
| printf("Received an integer : %d\n",$1); |
| } |
| %inline %{ |
| extern int fact(int n); |
| %} |
| </pre></div> |
| |
| <p> |
| Typemaps are always associated with some specific aspect of code generation. |
| In this case, the "in" method refers to the conversion of input arguments |
| to C/C++. The datatype <tt>int</tt> is the datatype to which the typemap |
| will be applied. The supplied C code is used to convert values. In this |
| code a number of special variable prefaced by a <tt>$</tt> are used. The |
| <tt>$1</tt> variable is placeholder for a local variable of type <tt>int</tt>. |
| The <tt>$input</tt> variable is the input object of type <tt>PyObject *</tt>. |
| </p> |
| |
| <p> |
| When this example is compiled into a Python module, it operates as follows: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> from example import * |
| >>> fact(6) |
| Received an integer : 6 |
| 720 |
| </pre></div> |
| |
| <p> |
| In this example, the typemap is applied to all occurrences of the <tt>int</tt> datatype. |
| You can refine this by supplying an optional parameter name. For example: |
| </p> |
| |
| <div class="code"><pre> |
| %module example |
| |
| %typemap(in) int nonnegative { |
| $1 = (int) PyLong_AsLong($input); |
| if ($1 < 0) { |
| PyErr_SetString(PyExc_ValueError,"Expected a nonnegative value."); |
| return NULL; |
| } |
| } |
| %inline %{ |
| extern int fact(int nonnegative); |
| %} |
| </pre></div> |
| |
| <p> |
| In this case, the typemap code is only attached to arguments that exactly match <tt>int nonnegative</tt>. |
| </p> |
| |
| <p> |
| The application of a typemap to specific datatypes and argument names involves |
| more than simple text-matching--typemaps are fully integrated into the |
| SWIG C++ type-system. When you define a typemap for <tt>int</tt>, that typemap |
| applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>. In addition, |
| the typemap system follows <tt>typedef</tt> declarations. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %typemap(in) int n { |
| $1 = (int) PyLong_AsLong($input); |
| printf("n = %d\n",$1); |
| } |
| %inline %{ |
| typedef int Integer; |
| extern int fact(Integer n); // Above typemap is applied |
| %} |
| </pre> |
| </div> |
| |
| <p> |
| Typemaps can also be defined for groups of consecutive arguments. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %typemap(in) (char *str, int len) { |
| $1 = PyString_AsString($input); |
| $2 = PyString_Size($input); |
| }; |
| |
| int count(char c, char *str, int len); |
| </pre> |
| </div> |
| |
| <p> |
| When a multi-argument typemap is defined, the arguments are always handled as a single |
| Python object. This allows the function to be used like this (notice how the length |
| parameter is omitted): |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> example.count('e','Hello World') |
| 1 |
| >>> |
| </pre> |
| </div> |
| |
| <H3><a name="Python_nn55"></a>30.8.2 Python typemaps</H3> |
| |
| |
| <p> |
| The previous section illustrated an "in" typemap for converting Python objects to C. |
| A variety of different typemap methods are defined by the Python module. For example, |
| to convert a C integer back into a Python object, you might define an "out" typemap |
| like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %typemap(out) int { |
| $result = PyInt_FromLong((long) $1); |
| } |
| </pre> |
| </div> |
| |
| <p> |
| A detailed list of available methods can be found in the "<a |
| href="Typemaps.html#Typemaps">Typemaps</a>" chapter. |
| </p> |
| |
| <p> |
| However, the best source of typemap information (and examples) is |
| probably the Python module itself. In fact, all of SWIG's default |
| type handling is defined by typemaps. You can view these typemaps by |
| looking at the files in the SWIG library. Just take into account that |
| in the latest versions of swig (1.3.22+), the library files are not |
| very pristine clear for the casual reader, as they used to be. The |
| extensive use of macros and other ugly techniques in the latest |
| version produce a very powerful and consistent python typemap library, |
| but at the cost of simplicity and pedagogic value. |
| </p> |
| |
| <p> |
| To learn how to write a simple or your first typemap, you better take |
| 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> |
| |
| |
| <p> |
| Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear. |
| A full list of variables can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. |
| This is a list of the most common variables: |
| </p> |
| |
| <p> |
| <tt>$1</tt> |
| </p> |
| |
| <div class="indent"> |
| A C local variable corresponding to the actual type specified in the |
| <tt>%typemap</tt> directive. For input values, this is a C local variable |
| that's supposed to hold an argument value. For output values, this is |
| the raw result that's supposed to be returned to Python. |
| </div> |
| |
| <p> |
| <tt>$input</tt> |
| </p> |
| |
| <div class="indent"> |
| A <tt>PyObject *</tt> holding a raw Python object with an argument or variable value. |
| </div> |
| |
| <p> |
| <tt>$result</tt> |
| </p> |
| |
| <div class="indent"> |
| A <tt>PyObject *</tt> that holds the result to be returned to Python. |
| </div> |
| |
| <p> |
| <tt>$1_name</tt> |
| </p> |
| |
| <div class="indent"> |
| The parameter name that was matched. |
| </div> |
| |
| <p> |
| <tt>$1_type</tt> |
| </p> |
| |
| <div class="indent"> |
| The actual C datatype matched by the typemap. |
| </div> |
| |
| <p> |
| <tt>$1_ltype</tt> |
| </p> |
| |
| <div class="indent"> |
| An assignable version of the datatype matched by the typemap (a type that can appear on the left-hand-side of |
| a C assignment operation). This type is stripped of qualifiers and may be an altered version of <tt>$1_type</tt>. |
| All arguments and local variables in wrapper functions are declared using this type so that their values can be |
| properly assigned. |
| </div> |
| |
| <p> |
| <tt>$symname</tt> |
| </p> |
| |
| <div class="indent"> |
| The Python name of the wrapper function being created. |
| </div> |
| |
| <H3><a name="Python_nn57"></a>30.8.4 Useful Python Functions</H3> |
| |
| |
| <p> |
| When you write a typemap, you usually have to work directly with Python objects. |
| The following functions may prove to be useful. |
| </p> |
| |
| <p> |
| <b>Python Integer Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyInt_FromLong(long l); |
| long PyInt_AsLong(PyObject *); |
| int PyInt_Check(PyObject *); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Python Floating Point Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyFloat_FromDouble(double); |
| double PyFloat_AsDouble(PyObject *); |
| int PyFloat_Check(PyObject *); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Python String Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyString_FromString(char *); |
| PyObject *PyString_FromStringAndSize(char *, lint len); |
| int PyString_Size(PyObject *); |
| char *PyString_AsString(PyObject *); |
| int PyString_Check(PyObject *); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Python List Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyList_New(int size); |
| int PyList_Size(PyObject *list); |
| PyObject *PyList_GetItem(PyObject *list, int i); |
| int PyList_SetItem(PyObject *list, int i, PyObject *item); |
| int PyList_Insert(PyObject *list, int i, PyObject *item); |
| int PyList_Append(PyObject *list, PyObject *item); |
| PyObject *PyList_GetSlice(PyObject *list, int i, int j); |
| int PyList_SetSlice(PyObject *list, int i, int , PyObject *list2); |
| int PyList_Sort(PyObject *list); |
| int PyList_Reverse(PyObject *list); |
| PyObject *PyList_AsTuple(PyObject *list); |
| int PyList_Check(PyObject *); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Python Tuple Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyTuple_New(int size); |
| int PyTuple_Size(PyObject *); |
| PyObject *PyTuple_GetItem(PyObject *, int i); |
| int PyTuple_SetItem(PyObject *, int i, PyObject *item); |
| PyObject *PyTuple_GetSlice(PyObject *t, int i, int j); |
| int PyTuple_Check(PyObject *); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Python Dictionary Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyDict_New(); |
| int PyDict_Check(PyObject *); |
| int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val); |
| int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val); |
| int PyDict_DelItem(PyObject *p, PyObject *key); |
| int PyDict_DelItemString(PyObject *p, char *key); |
| PyObject* PyDict_Keys(PyObject *p); |
| PyObject* PyDict_Values(PyObject *p); |
| PyObject* PyDict_GetItem(PyObject *p, PyObject *key); |
| PyObject* PyDict_GetItemString(PyObject *p, const char *key); |
| int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue); |
| Py_ssize_t PyDict_Size(PyObject *p); |
| int PyDict_Update(PyObject *a, PyObject *b); |
| int PyDict_Merge(PyObject *a, PyObject *b, int override); |
| PyObject* PyDict_Items(PyObject *p); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Python File Conversion Functions</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| PyObject *PyFile_FromFile(FILE *f); |
| FILE *PyFile_AsFile(PyObject *); |
| int PyFile_Check(PyObject *); |
| </pre> |
| </div> |
| |
| <p> |
| <b>Abstract Object Interface</b> |
| </p> |
| |
| <div class="code"> |
| <pre> |
| write me |
| </pre> |
| </div> |
| |
| <H2><a name="Python_nn58"></a>30.9 Typemap Examples</H2> |
| |
| |
| <p> |
| This section includes a few examples of typemaps. For more examples, you |
| 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> |
| |
| |
| <p> |
| A common problem in many C programs is the processing of command line |
| arguments, which are usually passed in an array of NULL terminated |
| strings. The following SWIG interface file allows a Python list |
| object to be used as a <tt>char **</tt> object. |
| </p> |
| |
| <div class="code"><pre> |
| %module argv |
| |
| // This tells SWIG to treat char ** as a special case |
| %typemap(in) char ** { |
| /* Check if is a list */ |
| if (PyList_Check($input)) { |
| int size = PyList_Size($input); |
| int i = 0; |
| $1 = (char **) malloc((size+1)*sizeof(char *)); |
| for (i = 0; i < size; i++) { |
| PyObject *o = PyList_GetItem($input,i); |
| if (PyString_Check(o)) |
| $1[i] = PyString_AsString(PyList_GetItem($input,i)); |
| else { |
| PyErr_SetString(PyExc_TypeError,"list must contain strings"); |
| free($1); |
| return NULL; |
| } |
| } |
| $1[i] = 0; |
| } else { |
| PyErr_SetString(PyExc_TypeError,"not a list"); |
| return NULL; |
| } |
| } |
| |
| // This cleans up the char ** array we malloc'd before the function call |
| %typemap(freearg) char ** { |
| free((char *) $1); |
| } |
| |
| // Now a test function |
| %inline %{ |
| int print_args(char **argv) { |
| int i = 0; |
| while (argv[i]) { |
| printf("argv[%d] = %s\n", i,argv[i]); |
| i++; |
| } |
| return i; |
| } |
| %} |
| |
| </pre></div> |
| |
| <p> |
| When this module is compiled, the wrapped C function now operates as |
| follows : |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> from argv import * |
| >>> print_args(["Dave","Mike","Mary","Jane","John"]) |
| argv[0] = Dave |
| argv[1] = Mike |
| argv[2] = Mary |
| argv[3] = Jane |
| argv[4] = John |
| 5 |
| </pre></div> |
| |
| <p> |
| In the example, two different typemaps are used. The "in" typemap is |
| used to receive an input argument and convert it to a C array. Since dynamic |
| memory allocation is used to allocate memory for the array, the |
| "freearg" typemap is used to later release this memory after the execution of |
| the C function. |
| </p> |
| |
| <H3><a name="Python_nn60"></a>30.9.2 Expanding a Python object into multiple arguments</H3> |
| |
| |
| <p> |
| Suppose that you had a collection of C functions with arguments |
| such as the following: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| int foo(int argc, char **argv); |
| </pre> |
| </div> |
| |
| <p> |
| In the previous example, a typemap was written to pass a Python list as the <tt>char **argv</tt>. This |
| allows the function to be used from Python as follows: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> foo(4, ["foo","bar","spam","1"]) |
| </pre> |
| </div> |
| |
| <p> |
| Although this works, it's a little awkward to specify the argument count. To fix this, a multi-argument |
| typemap can be defined. This is not very difficult--you only have to make slight modifications to the |
| previous example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %typemap(in) (int argc, char **argv) { |
| /* Check if is a list */ |
| if (PyList_Check($input)) { |
| int i; |
| $1 = PyList_Size($input); |
| $2 = (char **) malloc(($1+1)*sizeof(char *)); |
| for (i = 0; i < $1; i++) { |
| PyObject *o = PyList_GetItem($input,i); |
| if (PyString_Check(o)) |
| $2[i] = PyString_AsString(PyList_GetItem($input,i)); |
| else { |
| PyErr_SetString(PyExc_TypeError,"list must contain strings"); |
| free($2); |
| return NULL; |
| } |
| } |
| $2[i] = 0; |
| } else { |
| PyErr_SetString(PyExc_TypeError,"not a list"); |
| return NULL; |
| } |
| } |
| |
| %typemap(freearg) (int argc, char **argv) { |
| free((char *) $2); |
| } |
| </pre> |
| </div> |
| |
| <p> |
| When writing a multiple-argument typemap, each of the types is referenced by a variable such |
| as <tt>$1</tt> or <tt>$2</tt>. The typemap code simply fills in the appropriate values from |
| the supplied Python object. |
| </p> |
| |
| <p> |
| With the above typemap in place, you will find it no longer necessary |
| to supply the argument count. This is automatically set by the typemap code. For example: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| >>> foo(["foo","bar","spam","1"]) |
| </pre> |
| </div> |
| |
| <H3><a name="Python_nn61"></a>30.9.3 Using typemaps to return arguments</H3> |
| |
| |
| <p> |
| A common problem in some C programs is that values may be returned in |
| arguments rather than in the return value of a function. For example: |
| </p> |
| |
| <div class="code"><pre> |
| /* Returns a status value and two values in out1 and out2 */ |
| int spam(double a, double b, double *out1, double *out2) { |
| ... Do a bunch of stuff ... |
| *out1 = result1; |
| *out2 = result2; |
| return status; |
| }; |
| |
| </pre></div> |
| |
| <p> |
| A typemap can be used to handle this case as follows : |
| </p> |
| |
| <div class="code"><pre> |
| %module outarg |
| |
| // This tells SWIG to treat an double * argument with name 'OutValue' as |
| // an output value. We'll append the value to the current result which |
| // is guaranteed to be a List object by SWIG. |
| |
| %typemap(argout) double *OutValue { |
| PyObject *o, *o2, *o3; |
| o = PyFloat_FromDouble(*$1); |
| if ((!$result) || ($result == Py_None)) { |
| $result = o; |
| } else { |
| if (!PyTuple_Check($result)) { |
| PyObject *o2 = $result; |
| $result = PyTuple_New(1); |
| PyTuple_SetItem(target,0,o2); |
| } |
| o3 = PyTuple_New(1); |
| PyTuple_SetItem(o3,0,o); |
| o2 = $result; |
| $result = PySequence_Concat(o2,o3); |
| Py_DECREF(o2); |
| Py_DECREF(o3); |
| } |
| } |
| |
| int spam(double a, double b, double *OutValue, double *OutValue); |
| |
| </pre></div> |
| |
| <p> |
| The typemap works as follows. First, a check is made to see if any previous result |
| exists. If so, it is turned into a tuple and the new output value is concatenated to it. |
| Otherwise, the result is returned normally. For the sample function <tt>spam()</tt>, there |
| are three output values--meaning that the function will return a 3-tuple of the results. |
| </p> |
| |
| <p> |
| As written, the function must accept 4 arguments as input values, |
| last two being pointers to doubles. If these arguments are only used to hold output values (and have |
| no meaningful input value), an additional typemap can be written. For example: |
| </p> |
| |
| <div class="code"><pre> |
| %typemap(in,numinputs=0) double *OutValue(double temp) { |
| $1 = &temp; |
| } |
| |
| </pre></div> |
| |
| <p> |
| By specifying numinputs=0, the input value is ignored. However, since the argument still has to be set to |
| some meaningful value before calling C, it is set to point to a local variable <tt>temp</tt>. When the function |
| stores its output value, it will simply be placed in this local variable. As a result, the |
| function can now be used as follows: |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> a = spam(4,5) |
| >>> print a |
| (0, 2.45, 5.0) |
| >>> x,y,z = spam(4,5) |
| >>> |
| </pre></div> |
| |
| <H3><a name="Python_nn62"></a>30.9.4 Mapping Python tuples into small arrays</H3> |
| |
| |
| <p> |
| In some applications, it is sometimes desirable to pass small arrays |
| of numbers as arguments. For example : |
| </p> |
| |
| <div class="code"><pre> |
| extern void set_direction(double a[4]); // Set direction vector |
| </pre></div> |
| |
| <p> |
| This too, can be handled used typemaps as follows : |
| </p> |
| |
| <div class="code"><pre> |
| // Grab a 4 element array as a Python 4-tuple |
| %typemap(in) double[4](double temp[4]) { // temp[4] becomes a local variable |
| int i; |
| if (PyTuple_Check($input)) { |
| if (!PyArg_ParseTuple($input,"dddd",temp,temp+1,temp+2,temp+3)) { |
| PyErr_SetString(PyExc_TypeError,"tuple must have 4 elements"); |
| return NULL; |
| } |
| $1 = &temp[0]; |
| } else { |
| PyErr_SetString(PyExc_TypeError,"expected a tuple."); |
| return NULL; |
| } |
| } |
| |
| </pre></div> |
| |
| <p> |
| This allows our <tt>set_direction</tt> function to be called from |
| Python as follows : |
| </p> |
| |
| <div class="targetlang"><pre> |
| >>> set_direction((0.5,0.0,1.0,-0.25)) |
| </pre></div> |
| |
| <p> |
| Since our mapping copies the contents of a Python tuple into a C |
| 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> |
| |
| |
| <p> |
| Suppose that you wanted to generalize the previous example to handle C |
| arrays of different sizes. To do this, you might write a typemap as follows: |
| </p> |
| |
| <div class="code"><pre> |
| // Map a Python sequence into any sized C double array |
| %typemap(in) double[ANY](double temp[$1_dim0]) { |
| int i; |
| if (!PySequence_Check($input)) { |
| PyErr_SetString(PyExc_TypeError,"Expecting a sequence"); |
| return NULL; |
| } |
| if (PyObject_Length($input) != $1_dim0) { |
| PyErr_SetString(PyExc_ValueError,"Expecting a sequence with $1_dim0 elements"); |
| return NULL; |
| } |
| for (i =0; i < $1_dim0; i++) { |
| PyObject *o = PySequence_GetItem($input,i); |
| if (!PyFloat_Check(o)) { |
| Py_XDECREF(o); |
| PyErr_SetString(PyExc_ValueError,"Expecting a sequence of floats"); |
| return NULL; |
| } |
| temp[i] = PyFloat_AsDouble(o); |
| Py_DECREF(o); |
| } |
| $1 = &temp[0]; |
| } |
| </pre> |
| </div> |
| |
| <p> |
| In this case, the variable <tt>$1_dim0</tt> is expanded to match the |
| array dimensions actually used in the C code. This allows the typemap |
| to be applied to types such as: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| void foo(double x[10]); |
| void bar(double a[4], double b[8]); |
| </pre> |
| </div> |
| |
| <p> |
| Since the above typemap code gets inserted into every wrapper function where used, it might make sense |
| to use a helper function instead. This will greatly reduce the amount of wrapper code. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %{ |
| static int convert_darray(PyObject *input, double *ptr, int size) { |
| int i; |
| if (!PySequence_Check(input)) { |
| PyErr_SetString(PyExc_TypeError,"Expecting a sequence"); |
| return 0; |
| } |
| if (PyObject_Length(input) != size) { |
| PyErr_SetString(PyExc_ValueError,"Sequence size mismatch"); |
| return 0; |
| } |
| for (i =0; i < size; i++) { |
| PyObject *o = PySequence_GetItem(input,i); |
| if (!PyFloat_Check(o)) { |
| Py_XDECREF(o); |
| PyErr_SetString(PyExc_ValueError,"Expecting a sequence of floats"); |
| return 0; |
| } |
| ptr[i] = PyFloat_AsDouble(o); |
| Py_DECREF(o); |
| } |
| return 1; |
| } |
| %} |
| |
| %typemap(in) double [ANY](double temp[$1_dim0]) { |
| if (!convert_darray($input,temp,$1_dim0))) { |
| return NULL; |
| } |
| $1 = &temp[0]; |
| } |
| </pre> |
| </div> |
| |
| <H3><a name="Python_nn64"></a>30.9.6 Pointer handling</H3> |
| |
| |
| <p> |
| Occasionally, it might be necessary to convert pointer values that have |
| been stored using the SWIG typed-pointer representation. Since there are |
| several ways in which pointers can be represented, the following two |
| functions are used to safely perform this conversion: |
| </p> |
| |
| <p> |
| <tt> |
| int SWIG_ConvertPtr(PyObject *obj, void **ptr, swig_type_info *ty, int flags)</tt> |
| </p> |
| |
| <div class="indent"> |
| Converts a Python object <tt>obj</tt> to a C pointer. The result of the conversion is placed |
| into the pointer located at <tt>ptr</tt>. <tt>ty</tt> is a SWIG type descriptor structure. |
| <tt>flags</tt> is used to handle error checking and other aspects of conversion. It is the |
| bitwise-or of several flag values including <tt>SWIG_POINTER_EXCEPTION</tt> and |
| <tt>SWIG_POINTER_DISOWN</tt>. The first flag makes the function raise an exception on type |
| error. The second flag additionally |
| steals ownership of an object. Returns 0 on success and -1 on error. |
| </div> |
| |
| <p> |
| <tt> |
| PyObject *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int own)</tt> |
| </p> |
| |
| <div class="indent"> |
| Creates a new Python pointer object. <tt>ptr</tt> is the pointer to convert, <tt>ty</tt> is the SWIG type descriptor structure that |
| describes the type, and <tt>own</tt> is a flag that indicates whether or not Python should take ownership of the |
| pointer. |
| </div> |
| |
| <p> |
| Both of these functions require the use of a special SWIG |
| type-descriptor structure. This structure contains information about |
| the mangled name of the datatype, type-equivalence information, as |
| well as information about converting pointer values under C++ |
| inheritance. For a type of <tt>Foo *</tt>, the type descriptor structure |
| is usually accessed as follows: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| Foo *f; |
| if (SWIG_ConvertPtr($input, (void **) &f, SWIGTYPE_p_Foo, SWIG_POINTER_EXCEPTION) == -1) |
| return NULL; |
| |
| PyObject *obj; |
| obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0); |
| </pre> |
| </div> |
| |
| <p> |
| In a typemap, the type descriptor should always be accessed using the special typemap |
| variable <tt>$1_descriptor</tt>. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %typemap(in) Foo * { |
| if ((SWIG_ConvertPtr($input,(void **) &$1, $1_descriptor,SWIG_POINTER_EXCEPTION)) == -1) |
| return NULL; |
| } |
| </pre> |
| </div> |
| |
| <p> |
| If necessary, the descriptor for any type can be obtained using the <tt>$descriptor()</tt> macro in a typemap. |
| For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %typemap(in) Foo * { |
| if ((SWIG_ConvertPtr($input,(void **) &$1, $descriptor(Foo *), |
| SWIG_POINTER_EXCEPTION)) == -1) |
| return NULL; |
| } |
| </pre> |
| </div> |
| |
| <p> |
| Although the pointer handling functions are primarily intended for |
| manipulating low-level pointers, both functions are fully aware of |
| Python proxy classes. Specifically, |
| <tt>SWIG_ConvertPtr()</tt> will retrieve a pointer from any object |
| that has a <tt>this</tt> attribute. In addition, |
| <tt>SWIG_NewPointerObj()</tt> can automatically generate a proxy |
| class object (if applicable). |
| </p> |
| |
| |
| |
| <H2><a name="Python_nn65"></a>30.10 Docstring Features</H2> |
| |
| |
| <p> |
| Using docstrings in Python code is becoming more and more important |
| and more tools are coming on the scene that take advantage of them, |
| everything from full-blown documentation generators to class browsers |
| and popup call-tips in Python-aware IDEs. Given the way that SWIG |
| generates the proxy code by default, your users will normally get |
| something like <tt>"function_name(*args)"</tt> in the popup calltip of |
| their IDE which is next to useless when the real function prototype |
| might be something like this: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL); |
| </pre> |
| </div> |
| |
| <p> |
| The features described in this section make it easy for you to add |
| docstrings to your modules, functions and methods that can then be |
| used by the various tools out there to make the programming experience |
| of your users much simpler. |
| </p> |
| |
| |
| <H3><a name="Python_nn66"></a>30.10.1 Module docstring</H3> |
| |
| |
| <p> |
| Python allows a docstring at the beginning of the <tt>.py</tt> file |
| before any other statements, and it is typically used to give a |
| general description of the entire module. SWIG supports this by |
| setting an option of the <tt>%module</tt> directive. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module(docstring="This is the example module's docstring") example |
| </pre> |
| </div> |
| |
| <p> |
| When you have more than just a line or so then you can retain the easy |
| readability of the <tt>%module</tt> directive by using a macro. For |
| example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %define DOCSTRING |
| "The `XmlResource` class allows program resources defining menus, |
| layout of controls on a panel, etc. to be loaded from an XML file." |
| %enddef |
| |
| %module(docstring=DOCSTRING) xrc |
| </pre> |
| </div> |
| |
| |
| <H3><a name="Python_nn67"></a>30.10.2 %feature("autodoc")</H3> |
| |
| |
| <p> |
| As alluded to above SWIG will generate all the function and method |
| proxy wrappers with just "*args" (or "*args, **kwargs" if the -keyword |
| option is used) for a parameter list and will then sort out the |
| individual parameters in the C wrapper code. This is nice and simple |
| for the wrapper code, but makes it difficult to be programmer and tool |
| friendly as anyone looking at the <tt>.py</tt> file will not be able |
| to find out anything about the parameters that the functions accept. |
| </p> |
| |
| <p>But since SWIG does know everything about the function it is |
| possible to generate a docstring containing the parameter types, names |
| and default values. Since many of the docstring tools are adopting a |
| standard of recognizing if the first thing in the docstring is a |
| function prototype then using that instead of what they found from |
| introspection, then life is good once more. |
| |
| <p>SWIG's Python module provides support for the "autodoc" feature, |
| which when attached to a node in the parse tree will cause a docstring |
| to be generated that includes the name of the function, parameter |
| 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> |
| |
| |
| <p> |
| When the "0" option is given then the types of the parameters will |
| <em>not</em> be included in the autodoc string. For example, given |
| this function prototype: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %feature("autodoc", "0"); |
| bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL); |
| </pre> |
| </div> |
| |
| <p> |
| Then Python code like this will be generated: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| def function_name(*args, **kwargs): |
| """function_name(x, y, foo=None, bar=None) -> bool""" |
| ... |
| </pre> |
| </div> |
| |
| |
| <H4><a name="Python_nn69"></a>30.10.2.2 %feature("autodoc", "1")</H4> |
| |
| |
| <p> |
| When the "1" option is used then the parameter types <em>will</em> be |
| used in the autodoc string. In addition, an attempt is made to |
| simplify the type name such that it makes more sense to the Python |
| user. Pointer, reference and const info is removed, |
| <tt>%rename</tt>'s are evaluated, etc. (This is not always |
| successful, but works most of the time. See the next section for what |
| to do when it doesn't.) Given the example above, then turning on the |
| parameter types with the "1" option will result in Python code like |
| this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| def function_name(*args, **kwargs): |
| """function_name(int x, int y, Foo foo=None, Bar bar=None) -> bool""" |
| ... |
| </pre> |
| </div> |
| |
| |
| |
| <H4><a name="Python_nn70"></a>30.10.2.3 %feature("autodoc", "docstring")</H4> |
| |
| |
| <p> |
| Finally, there are times when the automatically generated autodoc |
| string will make no sense for a Python programmer, particularly when a |
| typemap is involved. So if you give an explicit value for the autodoc |
| feature then that string will be used in place of the automatically |
| generated string. For example: |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %feature("autodoc", "GetPosition() -> (x, y)") GetPosition; |
| void GetPosition(int* OUTPUT, int* OUTPUT); |
| </pre> |
| </div> |
| |
| |
| <H3><a name="Python_nn71"></a>30.10.3 %feature("docstring")</H3> |
| |
| |
| <p> |
| In addition to the autodoc strings described above, you can also |
| attach any arbitrary descriptive text to a node in the parse tree with |
| the "docstring" feature. When the proxy module is generated then any |
| docstring associated with classes, function or methods are output. |
| If an item already has an autodoc string then it is combined with the |
| docstring and they are output together. If the docstring is all on a |
| single line then it is output like this:: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| """This is the docstring""" |
| </pre> |
| </div> |
| |
| <p> |
| Otherwise, to aid readability it is output like this: |
| </p> |
| |
| <div class="targetlang"> |
| <pre> |
| """ |
| This is a multi-line docstring |
| with more than one line. |
| """ |
| </pre> |
| </div> |
| |
| <H2><a name="Python_nn72"></a>30.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. |
| </p> |
| |
| <div class="code"> |
| <pre> |
| %module(package="wx") xrc |
| </pre> |
| </div> |
| |
| <p> |
| This is useful when the <tt>.i</tt> file is <tt>%import</tt>ed by |
| another <tt>.i</tt> file. By default SWIG will assume that the |
| importer is able to find the importee with just the module name, but |
| if they live in separate Python packages then that won't work. |
| However if the importee specifies what its package is with the |
| <tt>%module</tt> option then the Python code generated for the |
| importer will use that package name when importing the other module |
| and also in base class declarations, etc. if the package name is |
| different than its own. |
| </p> |
| |
| |
| </body> |
| </html> |
| |
| <!-- LocalWords: polymorphism Typemaps STL typemap typemaps Docstring autodoc |
| --> |
| <!-- LocalWords: docstring SWIG's cxx py GCC linux DLL gcc fPIC Wiki Xlinker |
| --> |
| <!-- LocalWords: examplemodule DHAVE CONFIG lpython lm ldl mypython lsocket |
| --> |
| <!-- LocalWords: lnsl lpthread distutils enums namespaces |
| --> |