You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
732 lines
52 KiB
732 lines
52 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>Using SIP — SIP 4.10.5 Reference Guide</title>
|
|
<link rel="stylesheet" href="_static/default.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '#',
|
|
VERSION: '4.10.5',
|
|
COLLAPSE_MODINDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" />
|
|
<link rel="next" title="The SIP Command Line" href="command_line.html" />
|
|
<link rel="prev" title="Installation" href="installation.html" />
|
|
</head>
|
|
<body>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
accesskey="I">index</a></li>
|
|
<li class="right" >
|
|
<a href="modindex.html" title="Global Module Index"
|
|
accesskey="M">modules</a> |</li>
|
|
<li class="right" >
|
|
<a href="command_line.html" title="The SIP Command Line"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="installation.html" title="Installation"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<div class="section" id="using-sip">
|
|
<span id="ref-using"></span><h1>Using SIP<a class="headerlink" href="#using-sip" title="Permalink to this headline">¶</a></h1>
|
|
<p>Bindings are generated by the SIP code generator from a number of specification
|
|
files, typically with a <tt class="docutils literal"><span class="pre">.sip</span></tt> extension. Specification files look very
|
|
similar to C and C++ header files, but often with additional information (in
|
|
the form of a <em>directive</em> or an <em>annotation</em>) and code so that the bindings
|
|
generated can be finely tuned.</p>
|
|
<div class="section" id="a-simple-c-example">
|
|
<span id="ref-simple-c-example"></span><h2>A Simple C++ Example<a class="headerlink" href="#a-simple-c-example" title="Permalink to this headline">¶</a></h2>
|
|
<p>We start with a simple example. Let’s say you have a (fictional) C++ library
|
|
that implements a single class called <tt class="docutils literal"><span class="pre">Word</span></tt>. The class has one constructor
|
|
that takes a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string as its single argument. The
|
|
class has one method called <tt class="docutils literal"><span class="pre">reverse()</span></tt> which takes no arguments and returns
|
|
a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string. The interface to the class is defined in
|
|
a header file called <tt class="docutils literal"><span class="pre">word.h</span></tt> which might look something like this:</p>
|
|
<div class="highlight-python"><pre>// Define the interface to the word library.
|
|
|
|
class Word {
|
|
const char *the_word;
|
|
|
|
public:
|
|
Word(const char *w);
|
|
|
|
char *reverse() const;
|
|
};</pre>
|
|
</div>
|
|
<p>The corresponding SIP specification file would then look something like this:</p>
|
|
<div class="highlight-python"><pre>// Define the SIP wrapper to the word library.
|
|
|
|
%Module word 0
|
|
|
|
class Word {
|
|
|
|
%TypeHeaderCode
|
|
#include <word.h>
|
|
%End
|
|
|
|
public:
|
|
Word(const char *w);
|
|
|
|
char *reverse() const;
|
|
};</pre>
|
|
</div>
|
|
<p>Obviously a SIP specification file looks very much like a C++ (or C) header
|
|
file, but SIP does not include a full C++ parser. Let’s look at the
|
|
differences between the two files.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>The <a class="reference external" href="directives.html#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive has been added <a class="footnote-reference" href="#id4" id="id1">[1]</a>. This is used to
|
|
name the Python module that is being created and to give it a
|
|
<em>generation</em> number. In this example these are <tt class="docutils literal"><span class="pre">word</span></tt> and <tt class="docutils literal"><span class="pre">0</span></tt>
|
|
respectively. The generation number is effectively the version number of
|
|
the module.</li>
|
|
<li>The <a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> directive has been added. The text
|
|
between this and the following <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive is included
|
|
literally in the code that SIP generates. Normally it is used, as in
|
|
this case, to <tt class="docutils literal"><span class="pre">#include</span></tt> the corresponding C++ (or C) header file <a class="footnote-reference" href="#id5" id="id2">[2]</a>.</li>
|
|
<li>The declaration of the private variable <tt class="docutils literal"><span class="pre">this_word</span></tt> has been removed.
|
|
SIP does not support access to either private or protected instance
|
|
variables.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>If we want to we can now generate the C++ code in the current directory by
|
|
running the following command:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="n">sip</span> <span class="o">-</span><span class="n">c</span> <span class="o">.</span> <span class="n">word</span><span class="o">.</span><span class="n">sip</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>However, that still leaves us with the task of compiling the generated code and
|
|
linking it against all the necessary libraries. It’s much easier to use the
|
|
<a class="reference external" href="build_system.html#ref-build-system"><em>SIP build system</em></a> to do the whole thing.</p>
|
|
<p>Using the SIP build system is simply a matter of writing a small Python script.
|
|
In this simple example we will assume that the <tt class="docutils literal"><span class="pre">word</span></tt> library we are wrapping
|
|
and it’s header file are installed in standard system locations and will be
|
|
found by the compiler and linker without having to specify any additional
|
|
flags. In a more realistic example your Python script may take command line
|
|
options, or search a set of directories to deal with different configurations
|
|
and installations.</p>
|
|
<p>This is the simplest script (conventionally called <tt class="docutils literal"><span class="pre">configure.py</span></tt>):</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>
|
|
<span class="kn">import</span> <span class="nn">sipconfig</span>
|
|
|
|
<span class="c"># The name of the SIP build file generated by SIP and used by the build</span>
|
|
<span class="c"># system.</span>
|
|
<span class="n">build_file</span> <span class="o">=</span> <span class="s">"word.sbf"</span>
|
|
|
|
<span class="c"># Get the SIP configuration information.</span>
|
|
<span class="n">config</span> <span class="o">=</span> <span class="n">sipconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">()</span>
|
|
|
|
<span class="c"># Run SIP to generate the code.</span>
|
|
<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s">" "</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">config</span><span class="o">.</span><span class="n">sip_bin</span><span class="p">,</span> <span class="s">"-c"</span><span class="p">,</span> <span class="s">"."</span><span class="p">,</span> <span class="s">"-b"</span><span class="p">,</span> <span class="n">build_file</span><span class="p">,</span> <span class="s">"word.sip"</span><span class="p">]))</span>
|
|
|
|
<span class="c"># Create the Makefile.</span>
|
|
<span class="n">makefile</span> <span class="o">=</span> <span class="n">sipconfig</span><span class="o">.</span><span class="n">SIPModuleMakefile</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">build_file</span><span class="p">)</span>
|
|
|
|
<span class="c"># Add the library we are wrapping. The name doesn't include any platform</span>
|
|
<span class="c"># specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the</span>
|
|
<span class="c"># ".dll" extension on Windows).</span>
|
|
<span class="n">makefile</span><span class="o">.</span><span class="n">extra_libs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"word"</span><span class="p">]</span>
|
|
|
|
<span class="c"># Generate the Makefile itself.</span>
|
|
<span class="n">makefile</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Hopefully this script is self-documenting. The key parts are the
|
|
<tt class="docutils literal"><span class="pre">Configuration</span></tt> and <tt class="docutils literal"><span class="pre">SIPModuleMakefile</span></tt> classes. The build system contains
|
|
other Makefile classes, for example to build programs or to call other
|
|
Makefiles in sub-directories.</p>
|
|
<p>After running the script (using the Python interpreter the extension module is
|
|
being created for) the generated C++ code and <tt class="docutils literal"><span class="pre">Makefile</span></tt> will be in the
|
|
current directory.</p>
|
|
<p>To compile and install the extension module, just run the following
|
|
commands <a class="footnote-reference" href="#id6" id="id3">[3]</a>:</p>
|
|
<div class="highlight-python"><pre>make
|
|
make install</pre>
|
|
</div>
|
|
<p>That’s all there is to it.</p>
|
|
<p>See <a class="reference external" href="distutils.html#ref-distutils"><em>Building Your Extension with distutils</em></a> for an example of how to build this example using
|
|
distutils.</p>
|
|
<table class="docutils footnote" frame="void" id="id4" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>All SIP directives start with a <tt class="docutils literal"><span class="pre">%</span></tt> as the first non-whitespace
|
|
character of a line.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="id5" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>SIP includes many code directives like this. They differ in where the
|
|
supplied code is placed by SIP in the generated code.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="id6" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>On Windows you might run <tt class="docutils literal"><span class="pre">nmake</span></tt> or <tt class="docutils literal"><span class="pre">mingw32-make</span></tt> instead.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="id7">
|
|
<h2>A Simple C Example<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h2>
|
|
<p>Let’s now look at a very similar example of wrapping a fictional C library:</p>
|
|
<div class="highlight-python"><pre>/* Define the interface to the word library. */
|
|
|
|
struct Word {
|
|
const char *the_word;
|
|
};
|
|
|
|
struct Word *create_word(const char *w);
|
|
char *reverse(struct Word *word);</pre>
|
|
</div>
|
|
<p>The corresponding SIP specification file would then look something like this:</p>
|
|
<div class="highlight-python"><pre>/* Define the SIP wrapper to the word library. */
|
|
|
|
%CModule word 0
|
|
|
|
struct Word {
|
|
|
|
%TypeHeaderCode
|
|
#include <word.h>
|
|
%End
|
|
|
|
const char *the_word;
|
|
};
|
|
|
|
struct Word *create_word(const char *w) /Factory/;
|
|
char *reverse(struct Word *word);</pre>
|
|
</div>
|
|
<p>Again, let’s look at the differences between the two files.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>The <a class="reference external" href="directives.html#directive-%CModule"><tt class="xref docutils literal"><span class="pre">%CModule</span></tt></a> directive has been added. This has the same
|
|
syntax as the <a class="reference external" href="directives.html#directive-%Module"><tt class="xref docutils literal"><span class="pre">%Module</span></tt></a> directive used in the previous example
|
|
but tells SIP that the library being wrapped is implemented in C rather
|
|
than C++.</li>
|
|
<li>The <a class="reference external" href="directives.html#directive-%TypeHeaderCode"><tt class="xref docutils literal"><span class="pre">%TypeHeaderCode</span></tt></a> directive has been added.</li>
|
|
<li>The <a class="reference external" href="annotations.html#fanno-Factory"><tt class="xref docutils literal"><span class="pre">Factory</span></tt></a> annotation has been added to the <tt class="docutils literal"><span class="pre">create_word()</span></tt>
|
|
function. This tells SIP that a newly created structure is being
|
|
returned and it is owned by Python.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>The <tt class="docutils literal"><span class="pre">configure.py</span></tt> build system script described in the previous example can
|
|
be used for this example without change.</p>
|
|
</div>
|
|
<div class="section" id="a-more-complex-c-example">
|
|
<h2>A More Complex C++ Example<a class="headerlink" href="#a-more-complex-c-example" title="Permalink to this headline">¶</a></h2>
|
|
<p>In this last example we will wrap a fictional C++ library that contains a class
|
|
that is derived from a TQt class. This will demonstrate how SIP allows a class
|
|
hierarchy to be split across multiple Python extension modules, and will
|
|
introduce SIP’s versioning system.</p>
|
|
<p>The library contains a single C++ class called <tt class="docutils literal"><span class="pre">Hello</span></tt> which is derived from
|
|
TQt’s <tt class="docutils literal"><span class="pre">TQLabel</span></tt> class. It behaves just like <tt class="docutils literal"><span class="pre">TQLabel</span></tt> except that the text
|
|
in the label is hard coded to be <tt class="docutils literal"><span class="pre">Hello</span> <span class="pre">World</span></tt>. To make the example more
|
|
interesting we’ll also say that the library only supports TQt v4.2 and later,
|
|
and also includes a function called <tt class="docutils literal"><span class="pre">setDefault()</span></tt> that is not implemented
|
|
in the Windows version of the library.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">hello.h</span></tt> header file looks something like this:</p>
|
|
<div class="highlight-python"><pre>// Define the interface to the hello library.
|
|
|
|
#include <qlabel.h>
|
|
#include <qwidget.h>
|
|
#include <qstring.h>
|
|
|
|
class Hello : public TQLabel {
|
|
// This is needed by the TQt Meta-Object Compiler.
|
|
Q_OBJECT
|
|
TQ_OBJECT
|
|
|
|
public:
|
|
Hello(TQWidget *parent = 0);
|
|
|
|
private:
|
|
// Prevent instances from being copied.
|
|
Hello(const Hello &);
|
|
Hello &operator=(const Hello &);
|
|
};
|
|
|
|
#if !defined(Q_OS_WIN)
|
|
void setDefault(const TQString &def);
|
|
#endif</pre>
|
|
</div>
|
|
<p>The corresponding SIP specification file would then look something like this:</p>
|
|
<div class="highlight-python"><pre>// Define the SIP wrapper to the hello library.
|
|
|
|
%Module hello 0
|
|
|
|
%Import TQtGui/TQtGuimod.sip
|
|
|
|
%If (TQt_4_2_0 -)
|
|
|
|
class Hello : TQLabel {
|
|
|
|
%TypeHeaderCode
|
|
#include <hello.h>
|
|
%End
|
|
|
|
public:
|
|
Hello(TQWidget *parent /TransferThis/ = 0);
|
|
|
|
private:
|
|
Hello(const Hello &);
|
|
};
|
|
|
|
%If (!WS_WIN)
|
|
void setDefault(const TQString &def);
|
|
%End
|
|
|
|
%End</pre>
|
|
</div>
|
|
<p>Again we look at the differences, but we’ll skip those that we’ve looked at in
|
|
previous examples.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>The <a class="reference external" href="directives.html#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> directive has been added to specify that we are
|
|
extending the class hierarchy defined in the file <tt class="docutils literal"><span class="pre">TQtGui/TQtGuimod.sip</span></tt>.
|
|
This file is part of PyTQt. The build system will take care of finding
|
|
the file’s exact location.</li>
|
|
<li>The <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive has been added to specify that everything
|
|
<a class="footnote-reference" href="#id11" id="id8">[4]</a> up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive only applies to TQt
|
|
v4.2 and later. <tt class="docutils literal"><span class="pre">TQt_4_2_0</span></tt> is a <em>tag</em> defined in <tt class="docutils literal"><span class="pre">TQtCoremod.sip</span></tt>
|
|
<a class="footnote-reference" href="#id12" id="id9">[5]</a> using the <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> directive. <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a>
|
|
is used to define a tag for each version of a library’s API you are
|
|
wrapping allowing you to maintain all the different versions in a single
|
|
SIP specification. The build system provides support to <tt class="docutils literal"><span class="pre">configure.py</span></tt>
|
|
scripts for working out the correct tags to use according to which
|
|
version of the library is actually installed.</li>
|
|
<li>The <tt class="docutils literal"><span class="pre">public</span></tt> keyword used in defining the super-classes has been
|
|
removed. This is not supported by SIP.</li>
|
|
<li>The <a class="reference external" href="annotations.html#aanno-TransferThis"><tt class="xref docutils literal"><span class="pre">TransferThis</span></tt></a> annotation has been added to the constructor’s
|
|
argument. It specifies that if the argument is not 0 (i.e. the <tt class="docutils literal"><span class="pre">Hello</span></tt>
|
|
instance being constructed has a parent) then ownership of the instance
|
|
is transferred from Python to C++. It is needed because TQt maintains
|
|
objects (i.e. instances derived from the <tt class="docutils literal"><span class="pre">TQObject</span></tt> class) in a
|
|
hierachy. When an object is destroyed all of its tqchildren are also
|
|
automatically destroyed. It is important, therefore, that the Python
|
|
garbage collector doesn’t also try and destroy them. This is covered in
|
|
more detail in <a class="reference internal" href="#ref-object-ownership"><em>Ownership of Objects</em></a>. SIP provides many other
|
|
annotations that can be applied to arguments, functions and classes.
|
|
Multiple annotations are separated by commas. Annotations may have
|
|
values.</li>
|
|
<li>The <tt class="docutils literal"><span class="pre">=</span></tt> operator has been removed. This operator is not supported by
|
|
SIP.</li>
|
|
<li>The <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive has been added to specify that everything
|
|
up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive does not apply to Windows.
|
|
<tt class="docutils literal"><span class="pre">WS_WIN</span></tt> is another tag defined by PyTQt, this time using the
|
|
<a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive. Tags defined by the
|
|
<a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive are mutually exclusive, i.e. only one
|
|
may be valid at a time <a class="footnote-reference" href="#id13" id="id10">[6]</a>.</li>
|
|
</ul>
|
|
</blockquote>
|
|
<p>One question you might have at this point is why bother to define the private
|
|
copy constructor when it can never be called from Python? The answer is to
|
|
prevent the automatic generation of a public copy constructor.</p>
|
|
<p>We now look at the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script. This is a little different to the
|
|
script in the previous examples for two related reasons.</p>
|
|
<p>Firstly, PyTQt includes a pure Python module called <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> that extends
|
|
the SIP build system for modules, like our example, that build on top of PyTQt.
|
|
It deals with the details of which version of TQt is being used (i.e. it
|
|
determines what the correct tags are) and where it is installed. This is
|
|
called a module’s configuration module.</p>
|
|
<p>Secondly, we generate a configuration module (called <tt class="docutils literal"><span class="pre">helloconfig</span></tt>) for our
|
|
own <tt class="docutils literal"><span class="pre">hello</span></tt> module. There is no need to do this, but if there is a chance
|
|
that somebody else might want to extend your C++ library then it would make
|
|
life easier for them.</p>
|
|
<p>Now we have two scripts. First the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>
|
|
<span class="kn">import</span> <span class="nn">sipconfig</span>
|
|
<span class="kn">from</span> <span class="nn">PyTQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span>
|
|
|
|
<span class="c"># The name of the SIP build file generated by SIP and used by the build</span>
|
|
<span class="c"># system.</span>
|
|
<span class="n">build_file</span> <span class="o">=</span> <span class="s">"hello.sbf"</span>
|
|
|
|
<span class="c"># Get the PyTQt configuration information.</span>
|
|
<span class="n">config</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">()</span>
|
|
|
|
<span class="c"># Get the extra SIP flags needed by the imported PyTQt modules. Note that</span>
|
|
<span class="c"># this normally only includes those flags (-x and -t) that relate to SIP's</span>
|
|
<span class="c"># versioning system.</span>
|
|
<span class="n">pyqt_sip_flags</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">pyqt_sip_flags</span>
|
|
|
|
<span class="c"># Run SIP to generate the code. Note that we tell SIP where to find the qt</span>
|
|
<span class="c"># module's specification files using the -I flag.</span>
|
|
<span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s">" "</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">config</span><span class="o">.</span><span class="n">sip_bin</span><span class="p">,</span> <span class="s">"-c"</span><span class="p">,</span> <span class="s">"."</span><span class="p">,</span> <span class="s">"-b"</span><span class="p">,</span> <span class="n">build_file</span><span class="p">,</span> <span class="s">"-I"</span><span class="p">,</span> <span class="n">config</span><span class="o">.</span><span class="n">pyqt_sip_dir</span><span class="p">,</span> <span class="n">pyqt_sip_flags</span><span class="p">,</span> <span class="s">"hello.sip"</span><span class="p">]))</span>
|
|
|
|
<span class="c"># We are going to install the SIP specification file for this module and</span>
|
|
<span class="c"># its configuration module.</span>
|
|
<span class="n">installs</span> <span class="o">=</span> <span class="p">[]</span>
|
|
|
|
<span class="n">installs</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">"hello.sip"</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">default_sip_dir</span><span class="p">,</span> <span class="s">"hello"</span><span class="p">)])</span>
|
|
|
|
<span class="n">installs</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">"helloconfig.py"</span><span class="p">,</span> <span class="n">config</span><span class="o">.</span><span class="n">default_mod_dir</span><span class="p">])</span>
|
|
|
|
<span class="c"># Create the Makefile. The TQtGuiModuleMakefile class provided by the</span>
|
|
<span class="c"># pyqtconfig module takes care of all the extra preprocessor, compiler and</span>
|
|
<span class="c"># linker flags needed by the TQt library.</span>
|
|
<span class="n">makefile</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">TQtGuiModuleMakefile</span><span class="p">(</span>
|
|
<span class="n">configuration</span><span class="o">=</span><span class="n">config</span><span class="p">,</span>
|
|
<span class="n">build_file</span><span class="o">=</span><span class="n">build_file</span><span class="p">,</span>
|
|
<span class="n">installs</span><span class="o">=</span><span class="n">installs</span>
|
|
<span class="p">)</span>
|
|
|
|
<span class="c"># Add the library we are wrapping. The name doesn't include any platform</span>
|
|
<span class="c"># specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the</span>
|
|
<span class="c"># ".dll" extension on Windows).</span>
|
|
<span class="n">makefile</span><span class="o">.</span><span class="n">extra_libs</span> <span class="o">=</span> <span class="p">[</span><span class="s">"hello"</span><span class="p">]</span>
|
|
|
|
<span class="c"># Generate the Makefile itself.</span>
|
|
<span class="n">makefile</span><span class="o">.</span><span class="n">generate</span><span class="p">()</span>
|
|
|
|
<span class="c"># Now we create the configuration module. This is done by merging a Python</span>
|
|
<span class="c"># dictionary (whose values are normally determined dynamically) with a</span>
|
|
<span class="c"># (static) template.</span>
|
|
<span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="c"># Publish where the SIP specifications for this module will be</span>
|
|
<span class="c"># installed.</span>
|
|
<span class="s">"hello_sip_dir"</span><span class="p">:</span> <span class="n">config</span><span class="o">.</span><span class="n">default_sip_dir</span><span class="p">,</span>
|
|
|
|
<span class="c"># Publish the set of SIP flags needed by this module. As these are the</span>
|
|
<span class="c"># same flags needed by the qt module we could leave it out, but this</span>
|
|
<span class="c"># allows us to change the flags at a later date without breaking</span>
|
|
<span class="c"># scripts that import the configuration module.</span>
|
|
<span class="s">"hello_sip_flags"</span><span class="p">:</span> <span class="n">pyqt_sip_flags</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="c"># This creates the helloconfig.py module from the helloconfig.py.in</span>
|
|
<span class="c"># template and the dictionary.</span>
|
|
<span class="n">sipconfig</span><span class="o">.</span><span class="n">create_config_module</span><span class="p">(</span><span class="s">"helloconfig.py"</span><span class="p">,</span> <span class="s">"helloconfig.py.in"</span><span class="p">,</span> <span class="n">content</span><span class="p">)</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Next we have the <tt class="docutils literal"><span class="pre">helloconfig.py.in</span></tt> template script:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyTQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span>
|
|
|
|
<span class="c"># These are installation specific values created when Hello was configured.</span>
|
|
<span class="c"># The following line will be replaced when this template is used to create</span>
|
|
<span class="c"># the final configuration module.</span>
|
|
<span class="c"># @SIP_CONFIGURATION@</span>
|
|
|
|
<span class="k">class</span> <span class="nc">Configuration</span><span class="p">(</span><span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">):</span>
|
|
<span class="sd">"""The class that represents Hello configuration values.</span>
|
|
<span class="sd"> """</span>
|
|
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sub_cfg</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
|
|
<span class="sd">"""Initialise an instance of the class.</span>
|
|
|
|
<span class="sd"> sub_cfg is the list of sub-class configurations. It should be None</span>
|
|
<span class="sd"> when called normally.</span>
|
|
<span class="sd"> """</span>
|
|
<span class="c"># This is all standard code to be copied verbatim except for the</span>
|
|
<span class="c"># name of the module containing the super-class.</span>
|
|
<span class="k">if</span> <span class="n">sub_cfg</span><span class="p">:</span>
|
|
<span class="n">cfg</span> <span class="o">=</span> <span class="n">sub_cfg</span>
|
|
<span class="k">else</span><span class="p">:</span>
|
|
<span class="n">cfg</span> <span class="o">=</span> <span class="p">[]</span>
|
|
|
|
<span class="n">cfg</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">_pkg_config</span><span class="p">)</span>
|
|
|
|
<span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cfg</span><span class="p">)</span>
|
|
|
|
<span class="k">class</span> <span class="nc">HelloModuleMakefile</span><span class="p">(</span><span class="n">pyqtconfig</span><span class="o">.</span><span class="n">TQtGuiModuleMakefile</span><span class="p">):</span>
|
|
<span class="sd">"""The Makefile class for modules that %Import hello.</span>
|
|
<span class="sd"> """</span>
|
|
<span class="k">def</span> <span class="nf">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
|
<span class="sd">"""Finalise the macros.</span>
|
|
<span class="sd"> """</span>
|
|
<span class="c"># Make sure our C++ library is linked.</span>
|
|
<span class="bp">self</span><span class="o">.</span><span class="n">extra_libs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">"hello"</span><span class="p">)</span>
|
|
|
|
<span class="c"># Let the super-class do what it needs to.</span>
|
|
<span class="n">pyqtconfig</span><span class="o">.</span><span class="n">TQtGuiModuleMakefile</span><span class="o">.</span><span class="n">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Again, we hope that the scripts are self documenting.</p>
|
|
<table class="docutils footnote" frame="void" id="id11" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id8">[4]</a></td><td>Some parts of a SIP specification aren’t subject to version control.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="id12" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id9">[5]</a></td><td>Actually in <tt class="docutils literal"><span class="pre">versions.sip</span></tt>. PyTQt uses the <a class="reference external" href="directives.html#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a>
|
|
directive to split the SIP specification for TQt across a large number of
|
|
separate <tt class="docutils literal"><span class="pre">.sip</span></tt> files.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="id13" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id10">[6]</a></td><td>Tags can also be defined by the <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive. These
|
|
tags are not mutually exclusive, i.e. any number may be valid at a time.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="ownership-of-objects">
|
|
<span id="ref-object-ownership"></span><h2>Ownership of Objects<a class="headerlink" href="#ownership-of-objects" title="Permalink to this headline">¶</a></h2>
|
|
<p>When a C++ instance is wrapped a corresponding Python object is created. The
|
|
Python object behaves as you would expect in regard to garbage collection - it
|
|
is garbage collected when its reference count reaches zero. What then happens
|
|
to the corresponding C++ instance? The obvious answer might be that the
|
|
instance’s destructor is called. However the library API may say that when the
|
|
instance is passed to a particular function, the library takes ownership of the
|
|
instance, i.e. responsibility for calling the instance’s destructor is
|
|
transferred from the SIP generated module to the library.</p>
|
|
<p>Ownership of an instance may also be associated with another instance. The
|
|
implication being that the owned instance will automatically be destroyed if
|
|
the owning instance is destroyed. SIP keeps track of these relationships to
|
|
ensure that Python’s cyclic garbage collector can detect and break any
|
|
reference cycles between the owning and owned instances. The association is
|
|
implemented as the owning instance taking a reference to the owned instance.</p>
|
|
<p>The TransferThis, Transfer and TransferBack annotations are used to specify
|
|
where, and it what direction, transfers of ownership happen. It is very
|
|
important that these are specified correctly to avoid crashes (where both
|
|
Python and C++ call the destructor) and memory leaks (where neither Python and
|
|
C++ call the destructor).</p>
|
|
<p>This applies equally to C structures where the structure is returned to the
|
|
heap using the <tt class="docutils literal"><span class="pre">free()</span></tt> function.</p>
|
|
<p>See also <a title="sipTransferTo" class="reference external" href="c_api.html#sipTransferTo"><tt class="xref docutils literal"><span class="pre">sipTransferTo()</span></tt></a>, <a title="sipTransferBack" class="reference external" href="c_api.html#sipTransferBack"><tt class="xref docutils literal"><span class="pre">sipTransferBack()</span></tt></a> and
|
|
<a title="sipTransferBreak" class="reference external" href="c_api.html#sipTransferBreak"><tt class="xref docutils literal"><span class="pre">sipTransferBreak()</span></tt></a>.</p>
|
|
</div>
|
|
<div class="section" id="types-and-meta-types">
|
|
<span id="ref-types-metatypes"></span><h2>Types and Meta-types<a class="headerlink" href="#types-and-meta-types" title="Permalink to this headline">¶</a></h2>
|
|
<p>Every Python object (with the exception of the <tt class="xref docutils literal"><span class="pre">object</span></tt> object itself)
|
|
has a meta-type and at least one super-type. By default an object’s meta-type
|
|
is the meta-type of its first super-type.</p>
|
|
<p>SIP implements two super-types, <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> and
|
|
<a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>, and a meta-type, <a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a>.</p>
|
|
<p><tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> is the super-type of <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>. The
|
|
super-type of <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> is <tt class="xref docutils literal"><span class="pre">object</span></tt>.</p>
|
|
<p><a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a> is the meta-type of both <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt>
|
|
and <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a>. The super-type of <a title="sip.wrappertype" class="reference external" href="python_api.html#sip.wrappertype"><tt class="xref docutils literal"><span class="pre">sip.wrappertype</span></tt></a> is
|
|
<tt class="xref docutils literal"><span class="pre">type</span></tt>.</p>
|
|
<p><a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a> supports the concept of object ownership described in
|
|
<a class="reference internal" href="#ref-object-ownership"><em>Ownership of Objects</em></a> and, by default, is the super-type of all the types
|
|
that SIP generates.</p>
|
|
<p><tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> does not support the concept of object ownership but
|
|
SIP generated types that are sub-classed from it have Python objects that take
|
|
less memory.</p>
|
|
<p>SIP allows a class’s meta-type and super-type to be explicitly specified using
|
|
the <a class="reference external" href="annotations.html#canno-Metatype"><tt class="xref docutils literal"><span class="pre">Metatype</span></tt></a> and <a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> class annotations.</p>
|
|
<p>SIP also allows the default meta-type and super-type to be changed for a module
|
|
using the <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> and <a class="reference external" href="directives.html#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a>
|
|
directives. Unlike the default super-type, the default meta-type is inherited
|
|
by importing modules.</p>
|
|
<p>If you want to use your own meta-type or super-type then they must be
|
|
sub-classed from one of the SIP provided types. Your types must be registered
|
|
using <a title="sipRegisterPyType" class="reference external" href="c_api.html#sipRegisterPyType"><tt class="xref docutils literal"><span class="pre">sipRegisterPyType()</span></tt></a>. This is normally done in code specified
|
|
using the <a class="reference external" href="directives.html#directive-%InitialisationCode"><tt class="xref docutils literal"><span class="pre">%InitialisationCode</span></tt></a> directive.</p>
|
|
<p>As an example, PyTQt4 uses <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> to specify a new
|
|
meta-type that handles the interaction with TQt’s own meta-type system. It also
|
|
uses <a class="reference external" href="directives.html#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a> to specify that the smaller
|
|
<tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> super-type is normally used. Finally it uses
|
|
<a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> as an annotation of the <tt class="docutils literal"><span class="pre">TQObject</span></tt> class to override the
|
|
default and use <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a> as the super-type so that the parent/child
|
|
relationships of <tt class="docutils literal"><span class="pre">TQObject</span></tt> instances are properly maintained.</p>
|
|
</div>
|
|
<div class="section" id="lazy-type-attributes">
|
|
<span id="ref-lazy-type-attributes"></span><h2>Lazy Type Attributes<a class="headerlink" href="#lazy-type-attributes" title="Permalink to this headline">¶</a></h2>
|
|
<p>Instead of populating a wrapped type’s dictionary with its attributes (or
|
|
descriptors for those attributes) SIP only creates objects for those attributes
|
|
when they are actually needed. This is done to reduce the memory footprint and
|
|
start up time when used to wrap large libraries with hundreds of classes and
|
|
tens of thousands of attributes.</p>
|
|
<p>SIP allows you to extend the handling of lazy attributes to your own attribute
|
|
types by allowing you to register an attribute getter handler (using
|
|
<a title="sipRegisterAttributeGetter" class="reference external" href="c_api.html#sipRegisterAttributeGetter"><tt class="xref docutils literal"><span class="pre">sipRegisterAttributeGetter()</span></tt></a>). This will be called just before a
|
|
type’s dictionary is accessed for the first time.</p>
|
|
</div>
|
|
<div class="section" id="support-for-python-s-buffer-interface">
|
|
<h2>Support for Python’s Buffer Interface<a class="headerlink" href="#support-for-python-s-buffer-interface" title="Permalink to this headline">¶</a></h2>
|
|
<p>SIP supports Python’s buffer interface in that whenever C/C++ requires a
|
|
<tt class="docutils literal"><span class="pre">char</span></tt> or <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> type then any Python type that supports the buffer
|
|
interface (including ordinary Python strings) can be used.</p>
|
|
<p>If a buffer is made up of a number of segments then all but the first will be
|
|
ignored.</p>
|
|
</div>
|
|
<div class="section" id="support-for-wide-characters">
|
|
<h2>Support for Wide Characters<a class="headerlink" href="#support-for-wide-characters" title="Permalink to this headline">¶</a></h2>
|
|
<p>SIP v4.6 introduced support for wide characters (i.e. the <tt class="docutils literal"><span class="pre">wchar_t</span></tt> type).
|
|
Python’s C API includes support for converting between tqunicode objects and wide
|
|
character strings and arrays. When converting from a tqunicode object to wide
|
|
characters SIP creates the string or array on the heap (using memory allocated
|
|
using <a title="sipMalloc" class="reference external" href="c_api.html#sipMalloc"><tt class="xref docutils literal"><span class="pre">sipMalloc()</span></tt></a>). This then raises the problem of how this memory
|
|
is subsequently freed.</p>
|
|
<p>The following describes how SIP handles this memory in the different situations
|
|
where this is an issue.</p>
|
|
<blockquote>
|
|
<ul class="simple">
|
|
<li>When a wide string or array is passed to a function or method then the
|
|
memory is freed (using <a title="sipFree" class="reference external" href="c_api.html#sipFree"><tt class="xref docutils literal"><span class="pre">sipFree()</span></tt></a>) after than function or method
|
|
returns.</li>
|
|
<li>When a wide string or array is returned from a virtual method then SIP
|
|
does not free the memory until the next time the method is called.</li>
|
|
<li>When an assignment is made to a wide string or array instance variable
|
|
then SIP does not first free the instance’s current string or array.</li>
|
|
</ul>
|
|
</blockquote>
|
|
</div>
|
|
<div class="section" id="the-python-global-interpreter-lock">
|
|
<span id="ref-gil"></span><h2>The Python Global Interpreter Lock<a class="headerlink" href="#the-python-global-interpreter-lock" title="Permalink to this headline">¶</a></h2>
|
|
<p>Python’s Global Interpretor Lock (GIL) must be acquired before calls can be
|
|
made to the Python API. It should also be released when a potentially
|
|
blocking call to C/C++ library is made in order to allow other Python threads
|
|
to be executed. In addition, some C/C++ libraries may implement their own
|
|
locking strategies that conflict with the GIL causing application deadlocks.
|
|
SIP provides ways of specifying when the GIL is released and acquired to
|
|
ensure that locking problems can be avoided.</p>
|
|
<p>SIP always ensures that the GIL is acquired before making calls to the Python
|
|
API. By default SIP does not release the GIL when making calls to the C/C++
|
|
library being wrapped. The <a class="reference external" href="annotations.html#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> annotation can be used to
|
|
override this behaviour when required.</p>
|
|
<p>If SIP is given the <a class="reference external" href="command_line.html#cmdoption-sip-g"><em class="xref">-g</em></a> command line option then the default
|
|
behaviour is changed and SIP releases the GIL every time is makes calls to the
|
|
C/C++ library being wrapped. The <a class="reference external" href="annotations.html#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotation can be used to
|
|
override this behaviour when required.</p>
|
|
</div>
|
|
<div class="section" id="managing-incompatible-apis">
|
|
<span id="ref-incompat-apis"></span><h2>Managing Incompatible APIs<a class="headerlink" href="#managing-incompatible-apis" title="Permalink to this headline">¶</a></h2>
|
|
<p>
|
|
<span class="versionmodified">New in version 4.9.</span></p>
|
|
<p>Sometimes it is necessary to change the way something is wrapped in a way that
|
|
introduces an incompatibility. For example a new feature of Python may
|
|
suggest that something may be wrapped in a different way to exploit that
|
|
feature.</p>
|
|
<p>SIP’s <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive could be used to provide two different
|
|
implementations. However this would mean that the choice between the two
|
|
implementations would have to be made when building the generated module
|
|
potentially causing all sorts of deployment problems. It may also require
|
|
applications to work out which implementation was available and to change
|
|
their behaviour accordingly.</p>
|
|
<p>Instead SIP provides limited support for providing multiple implementations
|
|
(of classes, mapped types and functions) that can be selected by an
|
|
application at run-time. It is then up to the application developer how they
|
|
want to manage the migration from the old API to the new, incompatible API.</p>
|
|
<p>This support is implemented in three parts.</p>
|
|
<p>Firstly the <a class="reference external" href="directives.html#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a> directive is used to define the name of an API
|
|
and its default version number. The default version number is the one used if
|
|
an application doesn’t explicitly set the version number to use.</p>
|
|
<p>Secondly the <a class="reference external" href="annotations.html#canno-API"><tt class="xref docutils literal"><span class="pre">API</span> <span class="pre">class</span></tt></a>, <a class="reference external" href="annotations.html#manno-API"><tt class="xref docutils literal"><span class="pre">mapped</span> <span class="pre">type</span></tt></a> or
|
|
<a class="reference external" href="annotations.html#fanno-API"><tt class="xref docutils literal"><span class="pre">function</span></tt></a> annotation is applied accordingly to specify the API
|
|
and range of version numbers that a particular class, mapped type or function
|
|
implementation should be enabled for.</p>
|
|
<p>Finally the application calls <a title="sip.setapi" class="reference external" href="python_api.html#sip.setapi"><tt class="xref docutils literal"><span class="pre">sip.setapi()</span></tt></a> to specify the version number
|
|
of the API that should be enabled. This call must be made before any module
|
|
that has multiple implementations is imported for the first time.</p>
|
|
<p>Note this mechanism is not intended as a way or providing equally valid
|
|
alternative APIs. For example:</p>
|
|
<div class="highlight-python"><pre>%API MyAPI 1
|
|
|
|
class Foo
|
|
{
|
|
public:
|
|
void bar();
|
|
};
|
|
|
|
class Baz : Foo
|
|
{
|
|
public:
|
|
void bar() /API=MyAPI:2-/;
|
|
};</pre>
|
|
</div>
|
|
<p>If the following Python code is executed then an exception will be raised:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="n">b</span> <span class="o">=</span> <span class="n">Baz</span><span class="p">()</span>
|
|
<span class="n">b</span><span class="o">.</span><span class="n">bar</span><span class="p">()</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This is because when version 1 of the <em>MyAPI</em> API (the default) is enabled
|
|
there is no <em>Baz.bar()</em> implementation and <em>Foo.bar()</em> will not be called
|
|
instead as might be expected.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h3><a href="index.html">Table Of Contents</a></h3>
|
|
<ul>
|
|
<li><a class="reference external" href="#">Using SIP</a><ul>
|
|
<li><a class="reference external" href="#a-simple-c-example">A Simple C++ Example</a></li>
|
|
<li><a class="reference external" href="#id7">A Simple C Example</a></li>
|
|
<li><a class="reference external" href="#a-more-complex-c-example">A More Complex C++ Example</a></li>
|
|
<li><a class="reference external" href="#ownership-of-objects">Ownership of Objects</a></li>
|
|
<li><a class="reference external" href="#types-and-meta-types">Types and Meta-types</a></li>
|
|
<li><a class="reference external" href="#lazy-type-attributes">Lazy Type Attributes</a></li>
|
|
<li><a class="reference external" href="#support-for-python-s-buffer-interface">Support for Python’s Buffer Interface</a></li>
|
|
<li><a class="reference external" href="#support-for-wide-characters">Support for Wide Characters</a></li>
|
|
<li><a class="reference external" href="#the-python-global-interpreter-lock">The Python Global Interpreter Lock</a></li>
|
|
<li><a class="reference external" href="#managing-incompatible-apis">Managing Incompatible APIs</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="installation.html"
|
|
title="previous chapter">Installation</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="command_line.html"
|
|
title="next chapter">The SIP Command Line</a></p>
|
|
<div id="searchbox" style="display: none">
|
|
<h3>Quick search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" size="18" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
<p class="searchtip" style="font-size: 90%">
|
|
Enter search terms or a module, class or function name.
|
|
</p>
|
|
</div>
|
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
>index</a></li>
|
|
<li class="right" >
|
|
<a href="modindex.html" title="Global Module Index"
|
|
>modules</a> |</li>
|
|
<li class="right" >
|
|
<a href="command_line.html" title="The SIP Command Line"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="installation.html" title="Installation"
|
|
>previous</a> |</li>
|
|
<li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© Copyright 2010 Riverbank Computing Limited.
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
|
|
</div>
|
|
</body>
|
|
</html> |