<spanid="ref-using"></span><h1>Using SIP<aclass="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 <ttclass="docutils literal"><spanclass="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>
<divclass="section"id="a-simple-c-example">
<spanid="ref-simple-c-example"></span><h2>A Simple C++ Example<aclass="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 <ttclass="docutils literal"><spanclass="pre">Word</span></tt>. The class has one constructor
that takes a <ttclass="docutils literal"><spanclass="pre">\0</span></tt> terminated character string as its single argument. The
class has one method called <ttclass="docutils literal"><spanclass="pre">reverse()</span></tt> which takes no arguments and returns
a <ttclass="docutils literal"><spanclass="pre">\0</span></tt> terminated character string. The interface to the class is defined in
a header file called <ttclass="docutils literal"><spanclass="pre">word.h</span></tt> which might look something like this:</p>
<divclass="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>
<divclass="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>
<ulclass="simple">
<li>The <aclass="reference external"href="directives.html#directive-%Module"><ttclass="xref docutils literal"><spanclass="pre">%Module</span></tt></a> directive has been added <aclass="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 <ttclass="docutils literal"><spanclass="pre">word</span></tt> and <ttclass="docutils literal"><spanclass="pre">0</span></tt>
respectively. The generation number is effectively the version number of
the module.</li>
<li>The <aclass="reference external"href="directives.html#directive-%TypeHeaderCode"><ttclass="xref docutils literal"><spanclass="pre">%TypeHeaderCode</span></tt></a> directive has been added. The text
between this and the following <aclass="reference external"href="directives.html#directive-%End"><ttclass="xref docutils literal"><spanclass="pre">%End</span></tt></a> directive is included
literally in the code that SIP generates. Normally it is used, as in
this case, to <ttclass="docutils literal"><spanclass="pre">#include</span></tt> the corresponding C++ (or C) header file <aclass="footnote-reference"href="#id5"id="id2">[2]</a>.</li>
<li>The declaration of the private variable <ttclass="docutils literal"><spanclass="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
<p>Hopefully this script is self-documenting. The key parts are the
<ttclass="docutils literal"><spanclass="pre">Configuration</span></tt> and <ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">Makefile</span></tt> will be in the
current directory.</p>
<p>To compile and install the extension module, just run the following
<p>See <aclass="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
<tr><tdclass="label"><aclass="fn-backref"href="#id1">[1]</a></td><td>All SIP directives start with a <ttclass="docutils literal"><spanclass="pre">%</span></tt> as the first non-whitespace
<tr><tdclass="label"><aclass="fn-backref"href="#id3">[3]</a></td><td>On Windows you might run <ttclass="docutils literal"><spanclass="pre">nmake</span></tt> or <ttclass="docutils literal"><spanclass="pre">mingw32-make</span></tt> instead.</td></tr>
</tbody>
</table>
</div>
<divclass="section"id="id7">
<h2>A Simple C Example<aclass="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>
<divclass="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>
<divclass="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>
<ulclass="simple">
<li>The <aclass="reference external"href="directives.html#directive-%CModule"><ttclass="xref docutils literal"><spanclass="pre">%CModule</span></tt></a> directive has been added. This has the same
syntax as the <aclass="reference external"href="directives.html#directive-%Module"><ttclass="xref docutils literal"><spanclass="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 <aclass="reference external"href="directives.html#directive-%TypeHeaderCode"><ttclass="xref docutils literal"><spanclass="pre">%TypeHeaderCode</span></tt></a> directive has been added.</li>
<li>The <aclass="reference external"href="annotations.html#fanno-Factory"><ttclass="xref docutils literal"><spanclass="pre">Factory</span></tt></a> annotation has been added to the <ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">configure.py</span></tt> build system script described in the previous example can
be used for this example without change.</p>
</div>
<divclass="section"id="a-more-complex-c-example">
<h2>A More Complex C++ Example<aclass="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
TQt’s <ttclass="docutils literal"><spanclass="pre">TQLabel</span></tt> class. It behaves just like <ttclass="docutils literal"><spanclass="pre">TQLabel</span></tt> except that the text
<p>Again we look at the differences, but we’ll skip those that we’ve looked at in
previous examples.</p>
<blockquote>
<ulclass="simple">
<li>The <aclass="reference external"href="directives.html#directive-%Import"><ttclass="xref docutils literal"><spanclass="pre">%Import</span></tt></a> directive has been added to specify that we are
<li>The <aclass="reference external"href="directives.html#directive-%If"><ttclass="xref docutils literal"><spanclass="pre">%If</span></tt></a> directive has been added to specify that everything
<aclass="footnote-reference"href="#id11"id="id8">[4]</a> up to the matching <aclass="reference external"href="directives.html#directive-%End"><ttclass="xref docutils literal"><spanclass="pre">%End</span></tt></a> directive only applies to TQt
v4.2 and later. <ttclass="docutils literal"><spanclass="pre">TQt_4_2_0</span></tt> is a <em>tag</em> defined in <ttclass="docutils literal"><spanclass="pre">TQtCoremod.sip</span></tt>
<aclass="footnote-reference"href="#id12"id="id9">[5]</a> using the <aclass="reference external"href="directives.html#directive-%Timeline"><ttclass="xref docutils literal"><spanclass="pre">%Timeline</span></tt></a> directive. <aclass="reference external"href="directives.html#directive-%Timeline"><ttclass="xref docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">public</span></tt> keyword used in defining the super-classes has been
removed. This is not supported by SIP.</li>
<li>The <aclass="reference external"href="annotations.html#aanno-TransferThis"><ttclass="xref docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">Hello</span></tt>
instance being constructed has a parent) then ownership of the instance
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 <aclass="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 <ttclass="docutils literal"><spanclass="pre">=</span></tt> operator has been removed. This operator is not supported by
SIP.</li>
<li>The <aclass="reference external"href="directives.html#directive-%If"><ttclass="xref docutils literal"><spanclass="pre">%If</span></tt></a> directive has been added to specify that everything
up to the matching <aclass="reference external"href="directives.html#directive-%End"><ttclass="xref docutils literal"><spanclass="pre">%End</span></tt></a> directive does not apply to Windows.
<aclass="reference external"href="directives.html#directive-%Platforms"><ttclass="xref docutils literal"><spanclass="pre">%Platforms</span></tt></a> directive. Tags defined by the
<aclass="reference external"href="directives.html#directive-%Platforms"><ttclass="xref docutils literal"><spanclass="pre">%Platforms</span></tt></a> directive are mutually exclusive, i.e. only one
may be valid at a time <aclass="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 <ttclass="docutils literal"><spanclass="pre">configure.py</span></tt> script. This is a little different to the
script in the previous examples for two related reasons.</p>
<tr><tdclass="label"><aclass="fn-backref"href="#id8">[4]</a></td><td>Some parts of a SIP specification aren’t subject to version control.</td></tr>
<tr><tdclass="label"><aclass="fn-backref"href="#id10">[6]</a></td><td>Tags can also be defined by the <aclass="reference external"href="directives.html#directive-%Feature"><ttclass="xref docutils literal"><spanclass="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>
<divclass="section"id="ownership-of-objects">
<spanid="ref-object-ownership"></span><h2>Ownership of Objects<aclass="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 <ttclass="docutils literal"><spanclass="pre">free()</span></tt> function.</p>
<p>See also <atitle="sipTransferTo"class="reference external"href="c_api.html#sipTransferTo"><ttclass="xref docutils literal"><spanclass="pre">sipTransferTo()</span></tt></a>, <atitle="sipTransferBack"class="reference external"href="c_api.html#sipTransferBack"><ttclass="xref docutils literal"><spanclass="pre">sipTransferBack()</span></tt></a> and
<spanid="ref-types-metatypes"></span><h2>Types and Meta-types<aclass="headerlink"href="#types-and-meta-types"title="Permalink to this headline">¶</a></h2>
<p>Every Python object (with the exception of the <ttclass="xref docutils literal"><spanclass="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, <ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt> and
<atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a>, and a meta-type, <atitle="sip.wrappertype"class="reference external"href="python_api.html#sip.wrappertype"><ttclass="xref docutils literal"><spanclass="pre">sip.wrappertype</span></tt></a>.</p>
<p><ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt> is the super-type of <atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a>. The
super-type of <ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt> is <ttclass="xref docutils literal"><spanclass="pre">object</span></tt>.</p>
<p><atitle="sip.wrappertype"class="reference external"href="python_api.html#sip.wrappertype"><ttclass="xref docutils literal"><spanclass="pre">sip.wrappertype</span></tt></a> is the meta-type of both <ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt>
and <atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a>. The super-type of <atitle="sip.wrappertype"class="reference external"href="python_api.html#sip.wrappertype"><ttclass="xref docutils literal"><spanclass="pre">sip.wrappertype</span></tt></a> is
<p><atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a> supports the concept of object ownership described in
<aclass="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><ttclass="xref docutils literal"><spanclass="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 <aclass="reference external"href="annotations.html#canno-Metatype"><ttclass="xref docutils literal"><spanclass="pre">Metatype</span></tt></a> and <aclass="reference external"href="annotations.html#canno-Supertype"><ttclass="xref docutils literal"><spanclass="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 <aclass="reference external"href="directives.html#directive-%DefaultMetatype"><ttclass="xref docutils literal"><spanclass="pre">%DefaultMetatype</span></tt></a> and <aclass="reference external"href="directives.html#directive-%DefaultSupertype"><ttclass="xref docutils literal"><spanclass="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 <atitle="sipRegisterPyType"class="reference external"href="c_api.html#sipRegisterPyType"><ttclass="xref docutils literal"><spanclass="pre">sipRegisterPyType()</span></tt></a>. This is normally done in code specified
using the <aclass="reference external"href="directives.html#directive-%InitialisationCode"><ttclass="xref docutils literal"><spanclass="pre">%InitialisationCode</span></tt></a> directive.</p>
<p>As an example, PyTQt4 uses <aclass="reference external"href="directives.html#directive-%DefaultMetatype"><ttclass="xref docutils literal"><spanclass="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 <aclass="reference external"href="directives.html#directive-%DefaultSupertype"><ttclass="xref docutils literal"><spanclass="pre">%DefaultSupertype</span></tt></a> to specify that the smaller
<ttclass="xref docutils literal"><spanclass="pre">sip.simplewrapper</span></tt> super-type is normally used. Finally it uses
<aclass="reference external"href="annotations.html#canno-Supertype"><ttclass="xref docutils literal"><spanclass="pre">Supertype</span></tt></a> as an annotation of the <ttclass="docutils literal"><spanclass="pre">TQObject</span></tt> class to override the
default and use <atitle="sip.wrapper"class="reference external"href="python_api.html#sip.wrapper"><ttclass="xref docutils literal"><spanclass="pre">sip.wrapper</span></tt></a> as the super-type so that the parent/child
<spanid="ref-lazy-type-attributes"></span><h2>Lazy Type Attributes<aclass="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
<atitle="sipRegisterAttributeGetter"class="reference external"href="c_api.html#sipRegisterAttributeGetter"><ttclass="xref docutils literal"><spanclass="pre">sipRegisterAttributeGetter()</span></tt></a>). This will be called just before a
type’s dictionary is accessed for the first time.</p>
<h2>Support for Python’s Buffer Interface<aclass="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
<ttclass="docutils literal"><spanclass="pre">char</span></tt> or <ttclass="docutils literal"><spanclass="pre">char</span><spanclass="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
characters SIP creates the string or array on the heap (using memory allocated
using <atitle="sipMalloc"class="reference external"href="c_api.html#sipMalloc"><ttclass="xref docutils literal"><spanclass="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>
<ulclass="simple">
<li>When a wide string or array is passed to a function or method then the
memory is freed (using <atitle="sipFree"class="reference external"href="c_api.html#sipFree"><ttclass="xref docutils literal"><spanclass="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>
<spanid="ref-gil"></span><h2>The Python Global Interpreter Lock<aclass="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 <aclass="reference external"href="annotations.html#fanno-ReleaseGIL"><ttclass="xref docutils literal"><spanclass="pre">ReleaseGIL</span></tt></a> annotation can be used to
override this behaviour when required.</p>
<p>If SIP is given the <aclass="reference external"href="command_line.html#cmdoption-sip-g"><emclass="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 <aclass="reference external"href="annotations.html#fanno-HoldGIL"><ttclass="xref docutils literal"><spanclass="pre">HoldGIL</span></tt></a> annotation can be used to
<spanid="ref-incompat-apis"></span><h2>Managing Incompatible APIs<aclass="headerlink"href="#managing-incompatible-apis"title="Permalink to this headline">¶</a></h2>
<p>
<spanclass="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 <aclass="reference external"href="directives.html#directive-%Feature"><ttclass="xref docutils literal"><spanclass="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 <aclass="reference external"href="directives.html#directive-%API"><ttclass="xref docutils literal"><spanclass="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 <aclass="reference external"href="annotations.html#canno-API"><ttclass="xref docutils literal"><spanclass="pre">API</span><spanclass="pre">class</span></tt></a>, <aclass="reference external"href="annotations.html#manno-API"><ttclass="xref docutils literal"><spanclass="pre">mapped</span><spanclass="pre">type</span></tt></a> or
<aclass="reference external"href="annotations.html#fanno-API"><ttclass="xref docutils literal"><spanclass="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 <atitle="sip.setapi"class="reference external"href="python_api.html#sip.setapi"><ttclass="xref docutils literal"><spanclass="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>
<divclass="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>
