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

Merged the Python 3.0 support branch. The merging progress is not so smooth, so hope this commit won't make anything broken.

Browse source 
This is the (incomplemete) log produced by svnmerge.py:

Merged revisions 10405-10409,10420-10422,10426,10438,10445,10451,10454-10465,10467,10473-10475,10485,10488-10489,10493-10495,10497,10509-10510,10513-10514,10517,10520,10525,10528-10529,10533-10535,10554-10557,10570,10573,10593,10614,10666-10669,10673,10678,10687,10690,10704-10706,10731,10744,10750-10752,10755,10759,10770,10775-10776,10813,10819 via svnmerge from 
https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-bhy



git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@10834 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Haoyu Bai 2008-09-11 17:18:07 +00:00
commit 3d8ddfc442
75 changed files with 1603 additions and 246 deletions
Download patch file Download diff file Expand all files Collapse all files

253
Doc/Manual/Python.html
View file

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