diff options
Diffstat (limited to 'Doc/Manual/Python.html')
| -rw-r--r-- | Doc/Manual/Python.html | 277 |
1 files changed, 188 insertions, 89 deletions
diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index dcfd7427e..eb102aa3e 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -6,7 +6,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Python"></a>35 SWIG and Python</H1> +<H1><a name="Python"></a>36 SWIG and Python</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -116,6 +116,7 @@ <li><a href="#Python_nn74">Function annotation</a> <li><a href="#Python_nn75">Buffer interface</a> <li><a href="#Python_nn76">Abstract base classes</a> +<li><a href="#Python_nn77">Byte string output conversion</a> </ul> </ul> </div> @@ -141,7 +142,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" chapter. </p> -<H2><a name="Python_nn2"></a>35.1 Overview</H2> +<H2><a name="Python_nn2"></a>36.1 Overview</H2> <p> @@ -168,10 +169,10 @@ described followed by a discussion of low-level implementation details. </p> -<H2><a name="Python_nn3"></a>35.2 Preliminaries</H2> +<H2><a name="Python_nn3"></a>36.2 Preliminaries</H2> -<H3><a name="Python_nn4"></a>35.2.1 Running SWIG</H3> +<H3><a name="Python_nn4"></a>36.2.1 Running SWIG</H3> <p> @@ -193,7 +194,7 @@ int fact(int n); </div> <p> -The <tt> #define SWIG_FILE_WITH_INIT </tt> line inserts a macro that specifies that the +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> @@ -269,7 +270,7 @@ The following sections have further practical examples and details on how you might go about compiling and using the generated files. </p> -<H3><a name="Python_nn6"></a>35.2.2 Using distutils</H3> +<H3><a name="Python_nn6"></a>36.2.2 Using distutils</H3> <p> @@ -361,7 +362,7 @@ This same approach works on all platforms if the appropriate compiler is install can even build extensions to the standard Windows Python using MingGW) </p> -<H3><a name="Python_nn7"></a>35.2.3 Hand compiling a dynamic module</H3> +<H3><a name="Python_nn7"></a>36.2.3 Hand compiling a dynamic module</H3> <p> @@ -394,7 +395,7 @@ of the module prefixed by an underscore</b>. If the name of your module is "<tt 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. +<tt>-module</tt> command line option. </p> <p> @@ -409,7 +410,7 @@ module actually consists of two files; <tt>socket.py</tt> and </p> -<H3><a name="Python_nn8"></a>35.2.4 Static linking</H3> +<H3><a name="Python_nn8"></a>36.2.4 Static linking</H3> <p> @@ -488,7 +489,7 @@ If using static linking, you might want to rely on a different approach (perhaps using distutils). </p> -<H3><a name="Python_nn9"></a>35.2.5 Using your module</H3> +<H3><a name="Python_nn9"></a>36.2.5 Using your module</H3> <p> @@ -645,7 +646,7 @@ system configuration (this requires root access and you will need to read the man pages). </p> -<H3><a name="Python_nn10"></a>35.2.6 Compilation of C++ extensions</H3> +<H3><a name="Python_nn10"></a>36.2.6 Compilation of C++ extensions</H3> <p> @@ -737,7 +738,7 @@ erratic program behavior. If working with lots of software components, you might want to investigate using a more formal standard such as COM. </p> -<H3><a name="Python_nn11"></a>35.2.7 Compiling for 64-bit platforms</H3> +<H3><a name="Python_nn11"></a>36.2.7 Compiling for 64-bit platforms</H3> <p> @@ -774,7 +775,7 @@ and -m64 allow you to choose the desired binary format for your python extension. </p> -<H3><a name="Python_nn12"></a>35.2.8 Building Python Extensions under Windows</H3> +<H3><a name="Python_nn12"></a>36.2.8 Building Python Extensions under Windows</H3> <p> @@ -782,8 +783,8 @@ 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. +are built with Visual Studio 2003), the standard <tt>python setup.py +build</tt> should just work. </p> <p> @@ -903,7 +904,7 @@ SWIG Wiki</a>. </p> -<H2><a name="Python_nn13"></a>35.3 A tour of basic C/C++ wrapping</H2> +<H2><a name="Python_nn13"></a>36.3 A tour of basic C/C++ wrapping</H2> <p> @@ -912,7 +913,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as This section briefly covers the essential aspects of this wrapping. </p> -<H3><a name="Python_nn14"></a>35.3.1 Modules</H3> +<H3><a name="Python_nn14"></a>36.3.1 Modules</H3> <p> @@ -925,7 +926,7 @@ module name, make sure you don't use the same name as a built-in Python command or standard module name. </p> -<H3><a name="Python_nn15"></a>35.3.2 Functions</H3> +<H3><a name="Python_nn15"></a>36.3.2 Functions</H3> <p> @@ -949,7 +950,7 @@ like you think it does: >>> </pre></div> -<H3><a name="Python_nn16"></a>35.3.3 Global variables</H3> +<H3><a name="Python_nn16"></a>36.3.3 Global variables</H3> <p> @@ -1087,7 +1088,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt> if there are no global variables in a module. </p> -<H3><a name="Python_nn17"></a>35.3.4 Constants and enums</H3> +<H3><a name="Python_nn17"></a>36.3.4 Constants and enums</H3> <p> @@ -1127,7 +1128,7 @@ other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful. </p> -<H3><a name="Python_nn18"></a>35.3.5 Pointers</H3> +<H3><a name="Python_nn18"></a>36.3.5 Pointers</H3> <p> @@ -1268,7 +1269,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return <tt>None</tt> if the conversion can't be performed. </p> -<H3><a name="Python_nn19"></a>35.3.6 Structures</H3> +<H3><a name="Python_nn19"></a>36.3.6 Structures</H3> <p> @@ -1457,7 +1458,7 @@ everything works just like you would expect. For example: </pre> </div> -<H3><a name="Python_nn20"></a>35.3.7 C++ classes</H3> +<H3><a name="Python_nn20"></a>36.3.7 C++ classes</H3> <p> @@ -1546,7 +1547,7 @@ they are accessed through <tt>cvar</tt> like this: </pre> </div> -<H3><a name="Python_nn21"></a>35.3.8 C++ inheritance</H3> +<H3><a name="Python_nn21"></a>36.3.8 C++ inheritance</H3> <p> @@ -1601,7 +1602,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla It is safe to use multiple inheritance with SWIG. </p> -<H3><a name="Python_nn22"></a>35.3.9 Pointers, references, values, and arrays</H3> +<H3><a name="Python_nn22"></a>36.3.9 Pointers, references, values, and arrays</H3> <p> @@ -1662,7 +1663,7 @@ treated as a returning value, and it will follow the same allocation/deallocation process. </p> -<H3><a name="Python_nn23"></a>35.3.10 C++ overloaded functions</H3> +<H3><a name="Python_nn23"></a>36.3.10 C++ overloaded functions</H3> <p> @@ -1785,7 +1786,7 @@ first declaration takes precedence. Please refer to the "SWIG and C++" chapter for more information about overloading. </p> -<H3><a name="Python_nn24"></a>35.3.11 C++ operators</H3> +<H3><a name="Python_nn24"></a>36.3.11 C++ operators</H3> <p> @@ -1874,7 +1875,7 @@ Also, be aware that certain operators don't map cleanly to Python. For instance overloaded assignment operators don't map to Python semantics and will be ignored. </p> -<H3><a name="Python_nn25"></a>35.3.12 C++ namespaces</H3> +<H3><a name="Python_nn25"></a>36.3.12 C++ namespaces</H3> <p> @@ -1941,7 +1942,7 @@ utilizes thousands of small deeply nested namespaces each with identical symbol names, well, then you get what you deserve. </p> -<H3><a name="Python_nn26"></a>35.3.13 C++ templates</H3> +<H3><a name="Python_nn26"></a>36.3.13 C++ templates</H3> <p> @@ -1995,7 +1996,7 @@ Some more complicated examples will appear later. </p> -<H3><a name="Python_nn27"></a>35.3.14 C++ Smart Pointers</H3> +<H3><a name="Python_nn27"></a>36.3.14 C++ Smart Pointers</H3> <p> @@ -2079,7 +2080,7 @@ simply use the <tt>__deref__()</tt> method. For example: </pre> </div> -<H3><a name="Python_nn27a"></a>35.3.15 C++ reference counted objects</H3> +<H3><a name="Python_nn27a"></a>36.3.15 C++ reference counted objects</H3> <p> @@ -2088,7 +2089,7 @@ Python examples of memory management using referencing counting. </p> -<H2><a name="Python_nn28"></a>35.4 Further details on the Python class interface</H2> +<H2><a name="Python_nn28"></a>36.4 Further details on the Python class interface</H2> <p> @@ -2111,7 +2112,7 @@ the <tt>-builtin</tt> option are in the <a href="#Python_builtin_types">Built-in section. </p> -<H3><a name="Python_nn29"></a>35.4.1 Proxy classes</H3> +<H3><a name="Python_nn29"></a>36.4.1 Proxy classes</H3> <p> @@ -2200,7 +2201,7 @@ you can attach new Python methods to the class and you can even inherit from it by Python built-in types until Python 2.2). </p> -<H3><a name="Python_builtin_types"></a>35.4.2 Built-in Types</H3> +<H3><a name="Python_builtin_types"></a>36.4.2 Built-in Types</H3> <p> @@ -2244,7 +2245,7 @@ please refer to the python documentation:</p> <p><a href="http://docs.python.org/extending/newtypes.html">http://docs.python.org/extending/newtypes.html</a></p> -<H4><a name="Python_builtin_limitations"></a>35.4.2.1 Limitations</H4> +<H4><a name="Python_builtin_limitations"></a>36.4.2.1 Limitations</H4> <p>Use of the <tt>-builtin</tt> option implies a couple of limitations: @@ -2412,7 +2413,7 @@ assert(issubclass(B.Derived, A.Base)) </li> </ul> -<H4><a name="Python_builtin_overloads"></a>35.4.2.2 Operator overloads -- use them!</H4> +<H4><a name="Python_builtin_overloads"></a>36.4.2.2 Operator overloads -- use them!</H4> <p>The entire justification for the <tt>-builtin</tt> option is improved @@ -2513,7 +2514,7 @@ structs. </p> -<H3><a name="Python_nn30"></a>35.4.3 Memory management</H3> +<H3><a name="Python_nn30"></a>36.4.3 Memory management</H3> <p>NOTE: Although this section refers to proxy objects, everything here also applies @@ -2708,7 +2709,7 @@ It is also possible to deal with situations like this using typemaps--an advanced topic discussed later. </p> -<H3><a name="Python_nn31"></a>35.4.4 Python 2.2 and classic classes</H3> +<H3><a name="Python_nn31"></a>36.4.4 Python 2.2 and classic classes</H3> <p> @@ -2745,7 +2746,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global function or through an instance (see the earlier section). </p> -<H2><a name="Python_directors"></a>35.5 Cross language polymorphism</H2> +<H2><a name="Python_directors"></a>36.5 Cross language polymorphism</H2> <p> @@ -2779,7 +2780,7 @@ proxy classes, director classes, and C wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Python_nn33"></a>35.5.1 Enabling directors</H3> +<H3><a name="Python_nn33"></a>36.5.1 Enabling directors</H3> <p> @@ -2869,7 +2870,7 @@ class MyFoo(mymodule.Foo): </div> -<H3><a name="Python_nn34"></a>35.5.2 Director classes</H3> +<H3><a name="Python_nn34"></a>36.5.2 Director classes</H3> @@ -2951,7 +2952,7 @@ so there is no need for the extra overhead involved with routing the calls through Python. </p> -<H3><a name="Python_nn35"></a>35.5.3 Ownership and object destruction</H3> +<H3><a name="Python_nn35"></a>36.5.3 Ownership and object destruction</H3> <p> @@ -3018,7 +3019,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard references to the Foo objects remain in Python. </p> -<H3><a name="Python_nn36"></a>35.5.4 Exception unrolling</H3> +<H3><a name="Python_nn36"></a>36.5.4 Exception unrolling</H3> <p> @@ -3077,7 +3078,7 @@ Swig::DirectorMethodException is thrown, Python will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Python_nn37"></a>35.5.5 Overhead and code bloat</H3> +<H3><a name="Python_nn37"></a>36.5.5 Overhead and code bloat</H3> <p> @@ -3111,7 +3112,7 @@ directive) for only those methods that are likely to be extended in Python. </p> -<H3><a name="Python_nn38"></a>35.5.6 Typemaps</H3> +<H3><a name="Python_nn38"></a>36.5.6 Typemaps</H3> <p> @@ -3125,7 +3126,7 @@ need to be supported. </p> -<H3><a name="Python_nn39"></a>35.5.7 Miscellaneous</H3> +<H3><a name="Python_nn39"></a>36.5.7 Miscellaneous</H3> <p> @@ -3172,7 +3173,7 @@ methods that return const references. </p> -<H2><a name="Python_nn40"></a>35.6 Common customization features</H2> +<H2><a name="Python_nn40"></a>36.6 Common customization features</H2> <p> @@ -3185,7 +3186,7 @@ This section describes some common SWIG features that are used to improve your the interface to an extension module. </p> -<H3><a name="Python_nn41"></a>35.6.1 C/C++ helper functions</H3> +<H3><a name="Python_nn41"></a>36.6.1 C/C++ helper functions</H3> <p> @@ -3266,7 +3267,7 @@ hard to implement. It is possible to clean this up using Python code, typemaps, customization features as covered in later sections. </p> -<H3><a name="Python_nn42"></a>35.6.2 Adding additional Python code</H3> +<H3><a name="Python_nn42"></a>36.6.2 Adding additional Python code</H3> <p> @@ -3367,6 +3368,18 @@ print("Loading", "Whizz", "Bang", sep=' ... ') </pre> </div> +<p>When using <tt>%pythoncode</tt> and <tt>%pythonbegin</tt> you generally +want to make sure that the block is delimited by <tt>%{</tt> and <tt>%}</tt>. +If you delimit it with <tt>{</tt> and <tt>}</tt> then any lines with a +leading <tt>#</tt> will be handled by SWIG as preprocessor directives, when +you probably meant them as Python comments. Prior to SWIG 3.0.3, invalid +preprocessor directives were silently ignored, so generally using the wrong +delimiters resulted in such comments not appearing in the generated output +(though a comment starting with a valid preprocessor directive could cause +problems, for example: <tt># error handling</tt>). SWIG 3.0.3 and later report +an error for invalid preprocessor directives, so you may have to update +existing interface files to delimit blocks of Python code correctly.</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 to do this. First, to @@ -3494,7 +3507,7 @@ The same applies for overloaded constructors. </p> -<H3><a name="Python_nn43"></a>35.6.3 Class extension with %extend</H3> +<H3><a name="Python_nn43"></a>36.6.3 Class extension with %extend</H3> <p> @@ -3583,7 +3596,7 @@ Vector(12,14,16) in any way---the extensions only show up in the Python interface. </p> -<H3><a name="Python_nn44"></a>35.6.4 Exception handling with %exception</H3> +<H3><a name="Python_nn44"></a>36.6.4 Exception handling with %exception</H3> <p> @@ -3709,7 +3722,7 @@ The language-independent <tt>exception.i</tt> library file can also be used to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter. </p> -<H2><a name="Python_nn45"></a>35.7 Tips and techniques</H2> +<H2><a name="Python_nn45"></a>36.7 Tips and techniques</H2> <p> @@ -3719,7 +3732,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques solving these problems. </p> -<H3><a name="Python_nn46"></a>35.7.1 Input and output parameters</H3> +<H3><a name="Python_nn46"></a>36.7.1 Input and output parameters</H3> <p> @@ -3932,7 +3945,7 @@ void foo(Bar *OUTPUT); may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>. </p> -<H3><a name="Python_nn47"></a>35.7.2 Simple pointers</H3> +<H3><a name="Python_nn47"></a>36.7.2 Simple pointers</H3> <p> @@ -4001,7 +4014,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t See the <a href="Library.html#Library">SWIG Library</a> chapter for further details. </p> -<H3><a name="Python_nn48"></a>35.7.3 Unbounded C Arrays</H3> +<H3><a name="Python_nn48"></a>36.7.3 Unbounded C Arrays</H3> <p> @@ -4063,7 +4076,7 @@ well suited for applications in which you need to create buffers, package binary data, etc. </p> -<H3><a name="Python_nn49"></a>35.7.4 String handling</H3> +<H3><a name="Python_nn49"></a>36.7.4 String handling</H3> <p> @@ -4132,7 +4145,7 @@ If you need to return binary data, you might use the also be used to extra binary data from arbitrary pointers. </p> -<H2><a name="Python_nn53"></a>35.8 Typemaps</H2> +<H2><a name="Python_nn53"></a>36.8 Typemaps</H2> <p> @@ -4149,7 +4162,7 @@ Typemaps are only used if you want to change some aspect of the primitive C-Python interface or if you want to elevate your guru status. </p> -<H3><a name="Python_nn54"></a>35.8.1 What is a typemap?</H3> +<H3><a name="Python_nn54"></a>36.8.1 What is a typemap?</H3> <p> @@ -4265,7 +4278,7 @@ parameter is omitted): </pre> </div> -<H3><a name="Python_nn55"></a>35.8.2 Python typemaps</H3> +<H3><a name="Python_nn55"></a>36.8.2 Python typemaps</H3> <p> @@ -4306,7 +4319,7 @@ a look at the SWIG library version 1.3.20 or so. </p> -<H3><a name="Python_nn56"></a>35.8.3 Typemap variables</H3> +<H3><a name="Python_nn56"></a>36.8.3 Typemap variables</H3> <p> @@ -4377,7 +4390,7 @@ properly assigned. The Python name of the wrapper function being created. </div> -<H3><a name="Python_nn57"></a>35.8.4 Useful Python Functions</H3> +<H3><a name="Python_nn57"></a>36.8.4 Useful Python Functions</H3> <p> @@ -4505,7 +4518,7 @@ write me </pre> </div> -<H2><a name="Python_nn58"></a>35.9 Typemap Examples</H2> +<H2><a name="Python_nn58"></a>36.9 Typemap Examples</H2> <p> @@ -4514,7 +4527,7 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in the SWIG library. </p> -<H3><a name="Python_nn59"></a>35.9.1 Converting Python list to a char ** </H3> +<H3><a name="Python_nn59"></a>36.9.1 Converting Python list to a char ** </H3> <p> @@ -4594,7 +4607,7 @@ memory allocation is used to allocate memory for the array, the the C function. </p> -<H3><a name="Python_nn60"></a>35.9.2 Expanding a Python object into multiple arguments</H3> +<H3><a name="Python_nn60"></a>36.9.2 Expanding a Python object into multiple arguments</H3> <p> @@ -4673,7 +4686,7 @@ to supply the argument count. This is automatically set by the typemap code. F </pre> </div> -<H3><a name="Python_nn61"></a>35.9.3 Using typemaps to return arguments</H3> +<H3><a name="Python_nn61"></a>36.9.3 Using typemaps to return arguments</H3> <p> @@ -4761,7 +4774,7 @@ function can now be used as follows: >>> </pre></div> -<H3><a name="Python_nn62"></a>35.9.4 Mapping Python tuples into small arrays</H3> +<H3><a name="Python_nn62"></a>36.9.4 Mapping Python tuples into small arrays</H3> <p> @@ -4810,7 +4823,7 @@ array, such an approach would not be recommended for huge arrays, but for small structures, this approach works fine. </p> -<H3><a name="Python_nn63"></a>35.9.5 Mapping sequences to C arrays</H3> +<H3><a name="Python_nn63"></a>36.9.5 Mapping sequences to C arrays</H3> <p> @@ -4899,7 +4912,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) { </pre> </div> -<H3><a name="Python_nn64"></a>35.9.6 Pointer handling</H3> +<H3><a name="Python_nn64"></a>36.9.6 Pointer handling</H3> <p> @@ -4996,7 +5009,7 @@ class object (if applicable). -<H2><a name="Python_nn65"></a>35.10 Docstring Features</H2> +<H2><a name="Python_nn65"></a>36.10 Docstring Features</H2> <p> @@ -5024,7 +5037,7 @@ of your users much simpler. </p> -<H3><a name="Python_nn66"></a>35.10.1 Module docstring</H3> +<H3><a name="Python_nn66"></a>36.10.1 Module docstring</H3> <p> @@ -5058,7 +5071,7 @@ layout of controls on a panel, etc. to be loaded from an XML file." </div> -<H3><a name="Python_nn67"></a>35.10.2 %feature("autodoc")</H3> +<H3><a name="Python_nn67"></a>36.10.2 %feature("autodoc")</H3> <p> @@ -5086,7 +5099,7 @@ four levels for autodoc controlled by the value given to the feature, <tt>%feature("autodoc", "<i>level</i>")</tt>. The four values for <i>level</i> are covered in the following sub-sections. -<H4><a name="Python_nn68"></a>35.10.2.1 %feature("autodoc", "0")</H4> +<H4><a name="Python_nn68"></a>36.10.2.1 %feature("autodoc", "0")</H4> <p> @@ -5115,7 +5128,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn69"></a>35.10.2.2 %feature("autodoc", "1")</H4> +<H4><a name="Python_nn69"></a>36.10.2.2 %feature("autodoc", "1")</H4> <p> @@ -5140,7 +5153,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_autodoc2"></a>35.10.2.3 %feature("autodoc", "2")</H4> +<H4><a name="Python_autodoc2"></a>36.10.2.3 %feature("autodoc", "2")</H4> <p> @@ -5200,7 +5213,7 @@ def function_name(*args, **kwargs): </pre> </div> -<H4><a name="Python_autodoc3"></a>35.10.2.4 %feature("autodoc", "3")</H4> +<H4><a name="Python_autodoc3"></a>36.10.2.4 %feature("autodoc", "3")</H4> <p> @@ -5225,7 +5238,7 @@ def function_name(*args, **kwargs): </div> -<H4><a name="Python_nn70"></a>35.10.2.5 %feature("autodoc", "docstring")</H4> +<H4><a name="Python_nn70"></a>36.10.2.5 %feature("autodoc", "docstring")</H4> <p> @@ -5244,7 +5257,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT); </div> -<H3><a name="Python_nn71"></a>35.10.3 %feature("docstring")</H3> +<H3><a name="Python_nn71"></a>36.10.3 %feature("docstring")</H3> <p> @@ -5276,7 +5289,7 @@ with more than one line. </pre> </div> -<H2><a name="Python_nn72"></a>35.11 Python Packages</H2> +<H2><a name="Python_nn72"></a>36.11 Python Packages</H2> <p>Python has concepts of modules and packages. Modules are separate units of @@ -5334,7 +5347,7 @@ users may need to use special features such as the <tt>package</tt> option in th <tt>%module</tt> directive or import related command line options. These are explained in the following sections.</p> -<H3><a name="Python_modulepackage"></a>35.11.1 Setting the Python package</H3> +<H3><a name="Python_modulepackage"></a>36.11.1 Setting the Python package</H3> <p> @@ -5388,7 +5401,7 @@ pkg1/pkg2/_foo.so # (shared library built from C/C++ code generated by SWI </pre> </div> -<H3><a name="Python_absrelimports"></a>35.11.2 Absolute and relative imports</H3> +<H3><a name="Python_absrelimports"></a>36.11.2 Absolute and relative imports</H3> <p>Suppose, we have the following hierarchy of files:</p> @@ -5412,7 +5425,7 @@ class M3: pass <p> We edit <tt>pkg1/mod2.py</tt> and want to import module -<tt>pkg1/pkg2/pkg3.py</tt> in order to derive from class <tt>M3</tt>. We can +<tt>pkg1/pkg2/mod3.py</tt> in order to derive from class <tt>M3</tt>. We can write appropriate Python code in several ways, for example: </p> @@ -5527,7 +5540,7 @@ uses relative imports. Second case is, when one puts import directives in <tt>__init__.py</tt> to import symbols from submodules or subpackages and the submodule depends on other submodules (discussed later).</p> -<H3><a name="Python_absimport"></a>35.11.3 Enforcing absolute import semantics</H3> +<H3><a name="Python_absimport"></a>36.11.3 Enforcing absolute import semantics</H3> <p>As you may know, there is an incompatibility in import semantics (for the @@ -5564,14 +5577,14 @@ from __future__ import absolute_import </pre> </div> -<H3><a name="Python_importfrominit"></a>35.11.4 Importing from __init__.py</H3> +<H3><a name="Python_importfrominit"></a>36.11.4 Importing from __init__.py</H3> <p>Imports in <tt>__init__.py</tt> are handy when you want to populate a package's namespace with names imported from other modules. In SWIG based projects this approach may also be used to split large pieces of code into -smaller modules, compile them in parallel and then re-assemble everything at another -level by importing submodules' contents in <tt>__init__.py</tt>, for +smaller modules, compile them in parallel and then re-assemble everything at +runtime by importing submodules' contents in <tt>__init__.py</tt>, for example.</p> <p>Unfortunately import directives in <tt>__init__.py</tt> may cause problems, @@ -5675,7 +5688,7 @@ effect (note, that the Python 2 case also needs the <tt>-relativeimport</tt> workaround).</p> -<H2><a name="Python_python3support"></a>35.12 Python 3 Support</H2> +<H2><a name="Python_python3support"></a>36.12 Python 3 Support</H2> <p> @@ -5702,7 +5715,7 @@ The following are Python 3.0 new features that are currently supported by SWIG. </p> -<H3><a name="Python_nn74"></a>35.12.1 Function annotation</H3> +<H3><a name="Python_nn74"></a>36.12.1 Function annotation</H3> <p> @@ -5735,7 +5748,7 @@ For detailed usage of function annotation, see <a href="http://www.python.org/dev/peps/pep-3107/">PEP 3107</a>. </p> -<H3><a name="Python_nn75"></a>35.12.2 Buffer interface</H3> +<H3><a name="Python_nn75"></a>36.12.2 Buffer interface</H3> <p> @@ -5887,7 +5900,7 @@ modify the buffer. </div> -<H3><a name="Python_nn76"></a>35.12.3 Abstract base classes</H3> +<H3><a name="Python_nn76"></a>36.12.3 Abstract base classes</H3> <p> @@ -5928,6 +5941,92 @@ For details of abstract base class, please see <a href="http://www.python.org/dev/peps/pep-3119/">PEP 3119</a>. </p> +<H3><a name="Python_nn77"></a>36.12.4 Byte string output conversion</H3> + + +<p> +By default, any byte string (<tt>char*</tt> or <tt>std::string</tt>) returned +from C or C++ code is decoded to text as UTF-8. This decoding uses the +<tt>surrogateescape</tt> error handler under Python 3.1 or higher -- this +error handler decodes invalid byte sequences to high surrogate characters +in the range U+DC80 to U+DCFF. + +As an example, consider the following SWIG interface, which exposes a byte +string that cannot be completely decoded as UTF-8: +</p> + +<div class="code"><pre> +%module example + +%include <std_string.i> + +%inline %{ + +const char* non_utf8_c_str(void) { + return "h\xe9llo w\xc3\xb6rld"; +} + +%} +</pre></div> + +<p> +When this method is called from Python 3, the return value is the following +text string: +</p> + +<div class="targetlang"><pre> +>>> s = example.non_utf8_c_str() +>>> s +'h\udce9llo wörld' +</pre></div> + +<p> +Since the C string contains bytes that cannot be decoded as UTF-8, those raw +bytes are represented as high surrogate characters that can be used to obtain +the original byte sequence: +</p> + +<div class="targetlang"><pre> +>>> b = s.encode('utf-8', errors='surrogateescape') +>>> b +b'h\xe9llo w\xc3\xb6rld' +</pre></div> + +<p> +One can then attempt a different encoding, if desired (or simply leave the +byte string as a raw sequence of bytes for use in binary protocols): +</p> + +<div class="targetlang"><pre> +>>> b.decode('latin-1') +'héllo wörld' +</pre></div> + +<p> +Note, however, that text strings containing surrogate characters are rejected +with the default <tt>strict</tt> codec error handler. For example: +</p> + +<div class="targetlang"><pre> +>>> with open('test', 'w') as f: +... print(s, file=f) +... +Traceback (most recent call last): + File "<stdin>", line 2, in <module> +UnicodeEncodeError: 'utf-8' codec can't encode character '\udce9' in position 1: surrogates not allowed +</pre></div> + +<p> +This requires the user to check most strings returned by SWIG bindings, but +the alternative is for a non-UTF8 byte string to be completely inaccessible +in Python 3 code. +</p> + +<p> +For more details about the <tt>surrogateescape</tt> error handler, please see +<a href="http://www.python.org/dev/peps/pep-0383/">PEP 383</a>. +</p> + </body> </html> |