This chapter describes SWIG's support of Python. SWIG is compatible -with most recent Python versions including Python 2.2 as well as older -versions dating back to Python 1.5.2. For the best results, consider using Python -2.0 or newer. +with most recent Python versions including Python 3.0 and Python 2.6, +as well as older versions dating back to Python 2.0. For the best results, +consider using Python 2.3 or newer.
@@ -2544,7 +2550,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global function or through an instance (see the earlier section).
-@@ -4929,7 +4935,7 @@ with more than one line.
Using the package option of the %module directive allows you to specify what Python package that the module will be -living in when installed. +living in when installed.
+SWIG is able to support Python 3.0. The wrapper code generated by +SWIG can be compiled with both Python 2.x or 3.0. Further more, by +passing the -py3 command line option to SWIG, wrapper code +with some Python 3 specific features can be generated (see below +subsections for details of these features). The -py3 option also +disables some incompatible features for Python 3, such as +-classic. + +
+There is a list of known-to-be-broken features in Python 3: +
++The following are Python 3.0 new features that are currently supported by +SWIG. +
+ ++The -py3 option will enable function annotation support. When used +SWIG is able to generate proxy method definitions like +this: +
+ ++ def foo(self, bar : "int" = 0) -> "void" : ... +
+For details of usage of function annotation, see PEP 3107. +
+ ++Buffer protocols were revised in Python 3. SWIG also gains a series of +new typemaps to support buffer interfaces. These typemap macros are +defined in pybuffer.i, which must be included in order to use them. +By using these typemaps, your wrapped function will be able to +accept any Python object that exposes a suitable buffer interface. +
+ ++For example, the get_path() function puts the path string +into the memory pointed to by its argument: +
+ ++void get_path(char *s); +
+Then you can write a typemap like this: (the following example is +applied to both Python 3.0 and 2.6, since the bytearray type +is backported to 2.6. +
+ + ++%include <pybuffer.i> +%pybuffer_mutable_string(char *str); +void get_path(char *s); +
+And then on the Python side the wrapped get_path could be used in this +way: +
+ ++>>> p = bytearray(10) +>>> get_path(p) +>>> print(p) +bytearray(b'/Foo/Bar/\x00') +
+The macros defined in pybuffer.i are similar to those in +cstring.i: +
+ ++%pybuffer_mutable_binary(parm, size_parm) +
+ ++The macro can be used to generate a typemap which maps a buffer of an +object to a pointer provided by parm and a size argument +provided by size_parm. For example: +
+ ++%pybuffer_mutable_binary(char *str, size_t size); +... +int snprintf(char *str, size_t size, const char *format, ...); +
+In Python: +
+ ++>>> buf = bytearray(6) +>>> snprintf(buf, "Hello world!") +>>> print(buf) +bytearray(b'Hello\x00') +>>> +
+%pybuffer_mutable_string(parm) +
+ ++This typemap macro requires the buffer to be a zero terminated string, +and maps the pointer of the buffer to parm. For example: +
+ ++%pybuffer_mutable_string(char *str); +... +size_t make_upper(char *str); +
+In Python: +
+ ++>>> buf = bytearray(b'foo\x00') +>>> make_upper(buf) +>>> print(buf) +bytearray(b'FOO\x00') +>>> +
+Both %pybuffer_mutable_binary and %pybuffer_mutable_string +require the provided buffer to be mutable, eg. they can accept a +bytearray type but can't accept an immutable byte +type. +
+ ++%pybuffer_binary(parm, size_parm) +
+ ++This macro maps an object's buffer to a pointer parm and a +size size_parm. It is similar to +%pybuffer_mutable_binary, except the +%pybuffer_binary an accept both mutable and immutable +buffers. As a result, the wrapped function should not modify the buffer. +
+ ++%pybuffer_string(parm) +
+ ++This macro maps an object's buffer as a string pointer parm. +It is similar to %pybuffer_mutable_string but the buffer +could be both mutable and immutable. And your function should not +modify the buffer. +
+ ++By including pyabc.i and using the -py3 command +line option when calling SWIG, the proxy classes of the STL containers +will automatically gain an appropriate abstract base class. For +example, the following SWIG interface: +
+ +
+%include <pyabc.i>
+%include <std_map.i>
+%include <std_list.i>
+
+namespace std {
+ %template(Mapii) map<int, int>;
+ %template(IntList) list<int>;
+}
++will generate a Python proxy class Mapii inheriting from +collections.MutableMap and a proxy class IntList +inheriting from collections.MutableSequence. +
+ ++pyabc.i also provides a macro %pythonabc that could be +used to define an abstract base class for your own C++ class: +
+ ++%pythonabc(MySet, collections.MutableSet); +
+For details of abstract base class, please see PEP 3119. +