From 90825e2392b2d70e43c7a25b8a3752299a933894 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebindings@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- python/sip/doc/sipref.html | 5281 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5281 insertions(+) create mode 100644 python/sip/doc/sipref.html (limited to 'python/sip/doc/sipref.html') diff --git a/python/sip/doc/sipref.html b/python/sip/doc/sipref.html new file mode 100644 index 00000000..850fe61f --- /dev/null +++ b/python/sip/doc/sipref.html @@ -0,0 +1,5281 @@ + + + + + + +SIP - A Tool for Generating Python Bindings for C and C++ Libraries + + + + +
+

SIP - A Tool for Generating Python Bindings for C and C++ Libraries

+

Reference Guide

+ +++ + + + + + + + +
Contact:info@riverbankcomputing.co.uk
Version:4.6
Copyright:Copyright (c) 2007 Riverbank Computing Limited
+
+

Contents

+ +
+
+

1   Introduction

+

This is the reference guide for SIP 4.6. SIP is a tool for +automatically generating Python bindings for C and +C++ libraries. SIP was originally developed in 1998 for +PyQt - the Python bindings for +the Qt GUI toolkit - but is suitable for generating bindings for any C or C++ +library.

+

This version of SIP generates bindings for Python v2.3 or later.

+

There are many other similar tools available. One of the original such tools +is SWIG and, in fact, SIP is so called because it +started out as a small SWIG. Unlike SWIG, SIP is specifically designed for +bringing together Python and C/C++ and goes to great lengths to make the +integration as tight as possible.

+

The homepage for SIP is http://www.riverbankcomputing.co.uk/sip/. Here you +will always find the latest stable version, current development snapshots, and +the latest version of this documentation.

+
+

1.1   License

+

SIP is licensed under the same terms as Python itself. SIP places no +restrictions on the license you may apply to the bindings you create.

+
+
+

1.2   Features

+

SIP, and the bindings it produces, have the following features.

+
+
    +
  • bindings are fast to load and minimise memory consumption especially when +only a small sub-set of a large library is being used
    • +
  • automatic conversion between standard Python and C/C++ data types
    • +
  • overloading of functions and methods with different argument signatures
    • +
  • access to a C++ class's protected methods
    • +
  • the ability to define a Python class that is a sub-class of a C++ class, +including abstract C++ classes
    • +
  • Python sub-classes can implement the __dtor__(self) method which +will be called from the C++ class's virtual destructor
    • +
  • support for ordinary C++ functions, class methods, static class methods, +virtual class methods and abstract class methods
    • +
  • the ability to re-implement C++ virtual and abstract methods in Python
    • +
  • support for global and class variables
    • +
  • support for global and class operators
    • +
  • support for C++ namespaces
    • +
  • support for C++ templates
    • +
  • support for C++ exceptions and wrapping them as Python exceptions
    • +
  • the ability to define mappings between C++ classes and similar Python +data types that are automatically invoked
    • +
  • the ability to automatically exploit any available run time type +information to ensure that the class of a Python instance object matches +the class of the corresponding C++ instance
    • +
  • full support of the Python global interpreter lock, including the ability +to specify that a C++ function of method may block, therefore allowing +the lock to be released and other Python threads to run
    • +
  • support for the concept of ownership of a C++ instance (i.e. what part of +the code is responsible for calling the instance's destructor) and how +the ownership may change during the execution of an application
    • +
  • the ability to generate bindings for a C++ class library that itself is +built on another C++ class library which also has had bindings generated +so that the different bindings integrate and share code properly
    • +
  • a sophisticated versioning system that allows the full lifetime of a C++ +class library, including any platform specific or optional features, to +be described in a single set of specification files
    • +
  • the ability to include documentation in the specification files which can +be extracted and subsequently processed by external tools
    • +
  • the ability to include copyright notices and licensing information in the +specification files that is automatically included in all generated +source code
    • +
  • a build system, written in Python, that you can extend to configure, +compile and install your own bindings without worrying about platform +specific issues
    • +
  • support for building your extensions using distutils
    • +
  • SIP, and the bindings it produces, runs under UNIX, Linux, Windows and +MacOS/X
    • +
+
+
+
+

1.3   SIP Components

+

SIP comprises a number of different components.

+
+
    +
  • The SIP code generator (sip or sip.exe). This processes .sip +specification files and generates C or C++ bindings. It is covered in +detail in Using SIP.
    • +
  • The SIP header file (sip.h). This contains definitions and data +structures needed by the generated C and C++ code.
    • +
  • The SIP module (sip.so or sip.pyd). This is a Python extension +module that is imported automatically by SIP generated bindings and +provides them with some common utility functions. See also Using the +SIP Module in Applications.
    • +
  • The SIP build system (sipconfig.py). This is a pure Python module +that is created when SIP is configured and encapsulates all the necessary +information about your system including relevant directory names, +compiler and linker flags, and version numbers. It also includes several +Python classes and functions which help you write configuration scripts +for your own bindings. It is covered in detail in The SIP Build +System.
    • +
  • The SIP distutils extension (sipdistutils.py). This is a distutils +extension that can be used to build your extension modules using +distutils and is an alternative to writing configuration scripts with the +SIP build system. This can be as simple as adding your .sip files to the +list of files needed to build the extension module. It is covered in +detail in Building Your Extension with distutils.
    • +
+
+
+
+

1.4   Qt Support

+

SIP has specific support for the creation of bindings based on Trolltech's Qt +toolkit.

+

The SIP code generator understands the signal/slot type safe callback mechanism +that Qt uses to connect objects together. This allows applications to define +new Python signals, and allows any Python callable object to be used as a slot.

+

SIP itself does not require Qt to be installed.

+
+
+
+

2   Potential Incompatibilities with Earlier Versions

+
+

2.1   SIP v4.4

+
+ +
+
+
+
+

3   Installing SIP

+
+

3.1   Downloading SIP

+

You can get the latest release of the SIP source code from +http://www.riverbankcomputing.co.uk/sip/download.php.

+

SIP is also included with all of the major Linux distributions. However, it +may be a version or two out of date.

+

You may also find more up to date pre-compiled binaries on +SourceForge.

+
+
+

3.2   Configuring SIP

+

After unpacking the source package (either a .tar.gz or a .zip file +depending on your platform) you should then check for any README files +that relate to your platform.

+

Next you need to configure SIP by executing the configure.py script. For +example:

+
+python configure.py
+
+

This assumes that the Python interpreter is on your path. Something like the +following may be appropriate on Windows:

+
+c:\python25\python configure.py
+
+

If you have multiple versions of Python installed then make sure you use the +interpreter for which you wish SIP to generate bindings for.

+

The full set of command line options is:

+ +++ + + + + + + + + + + + + + + + + + + + + + +
+-hDisplay a help message.
+-aExport all symbols in any SIP generated module and the SIP module +itself. This was the default behaviour of SIP prior to v4.2. +Normally only a module's inititialisation function is exported. This +option is deprecated as the ModuleMakefile class of The SIP Build +System allows this to be specified on a per module basis.
+-b dirThe SIP code generator will be installed in the directory dir.
+-d dirThe SIP module will be installed in the directory dir.
+-e dirThe SIP header file will be installed in the directory dir.
+-kThe SIP module will be built as a static library. This is useful when +building the SIP module as a Python builtin (see +Builtin Modules and Custom Interpreters).
+-nThe SIP code generator and module will be built as universal binaries +under MacOS/X.
+-p platExplicitly specify the platform/compiler to be used by the build +system, otherwise a platform specific default will be used. The +-h option will display all the supported platform/compilers and +the default.
+-uThe SIP module will be built with debugging symbols.
+-v dirBy default .sip files will be installed in the directory dir.
+

The configure.py script takes many other options that allows the build system +to be finely tuned. These are of the form name=value or name+=value. +The -h option will display each supported name, although not all are +applicable to all platforms.

+

The name=value form means that value will replace the existing value of +name.

+

The name+=value form means that value will be appended to the existing +value of name.

+

For example, the following will disable support for C++ exceptions (and so +reduce the size of module binaries) when used with GCC:

+
+python configure.py CXXFLAGS+=-fno-exceptions
+
+

A pure Python module called sipconfig.py is generated by configure.py. +This defines each name and its corresponding value. Looking at it will +give you a good idea of how the build system uses the different options. It is +covered in detail in The SIP Build System.

+
+

3.2.1   Configuring SIP Using MinGW

+

SIP, and the modules it generates, can be built with MinGW, the Windows port of +GCC. You must use the -p command line option to specify the correct +platform. For example:

+
+c:\python25\python configure.py -p win32-g++
+
+
+
+

3.2.2   Configuring SIP Using the Borland C++ Compiler

+

SIP, and the modules it generates, can be built with the free Borland C++ +compiler. You must use the -p command line option to specify the correct +platform. For example:

+
+c:\python25\python configure.py -p win32-borland
+
+

You must also make sure you have a Borland-compatible version of the Python +library. If you are using the standard Python distribution (built using the +Microsoft compiler) then you must convert the format of the Python library. +For example:

+
+coff2omf python25.lib python25_bcpp.lib
+
+
+
+
+

3.3   Building SIP

+

The next step is to build SIP by running your platform's make command. For +example:

+
+make
+
+

The final step is to install SIP by running the following command:

+
+make install
+
+

(Depending on your system you may require root or administrator privileges.)

+

This will install the various SIP components.

+
+
+
+

4   Using SIP

+

Bindings are generated by the SIP code generator from a number of specification +files, typically with a .sip extension. Specification files look very +similar to C and C++ header files, but often with additional information (in +the form of a directive or an annotation) and code so that the bindings +generated can be finely tuned.

+
+

4.1   A Simple C++ Example

+

We start with a simple example. Let's say you have a (fictional) C++ library +that implements a single class called Word. The class has one constructor +that takes a \0 terminated character string as its single argument. The +class has one method called reverse() which takes no arguments and returns +a \0 terminated character string. The interface to the class is defined in +a header file called word.h which might look something like this:

+
+// Define the interface to the word library.
+
+class Word {
+    const char *the_word;
+
+public:
+    Word(const char *w);
+
+    char *reverse() const;
+};
+
+

The corresponding SIP specification file would then look something like this:

+
+// 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;
+};
+
+

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.

+
+
    +
  • The %Module directive has been added [1]. This is used to name the +Python module that is being created and to give it a generation number. +In this example these are word and 0 respectively. The +generation number is effectively the version number of the module.
    • +
  • The %TypeHeaderCode directive has been added. The text between this +and the following %End directive is included literally in the code +that SIP generates. Normally it is used, as in this case, to +#include the corresponding C++ (or C) header file [2].
    • +
  • The declaration of the private variable this_word has been removed. +SIP does not support access to either private or protected instance +variables.
    • +
+
+

If we want to we can now generate the C++ code in the current directory by +running the following command:

+
+sip -c . word.sip
+
+

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 +SIP build system to do the whole thing.

+

Using the SIP build system is simply a matter of writing a small Python script. +In this simple example we will assume that the word 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.

+

This is the simplest script (conventionally called configure.py):

+
+import os
+import sipconfig
+
+# The name of the SIP build file generated by SIP and used by the build
+# system.
+build_file = "word.sbf"
+
+# Get the SIP configuration information.
+config = sipconfig.Configuration()
+
+# Run SIP to generate the code.
+os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "word.sip"]))
+
+# Create the Makefile.
+makefile = sipconfig.SIPModuleMakefile(config, build_file)
+
+# Add the library we are wrapping.  The name doesn't include any platform
+# specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the
+# ".dll" extension on Windows).
+makefile.extra_libs = ["word"]
+
+# Generate the Makefile itself.
+makefile.generate()
+
+

Hopefully this script is self-documenting. The key parts are the +Configuration and SIPModuleMakefile classes. The build system contains +other Makefile classes, for example to build programs or to call other +Makefiles in sub-directories.

+

After running the script (using the Python interpreter the extension module is +being created for) the generated C++ code and Makefile will be in the +current directory.

+

To compile and install the extension module, just run the following +commands [3]:

+
+make
+make install
+
+

That's all there is to it.

+

See Building Your Extension with distutils for an example of how to build +this example using distutils.

+ + + + + +
[1]All SIP directives start with a % as the first non-whitespace +character of a line.
+ + + + + +
[2]SIP includes many code directives like this. They differ in where the +supplied code is placed by SIP in the generated code.
+ + + + + +
[3]On Windows you might run nmake or mingw32-make instead.
+
+
+

4.2   A Simple C Example

+

Let's now look at a very similar example of wrapping a fictional C library:

+
+/* 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);
+
+

The corresponding SIP specification file would then look something like this:

+
+/* 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);
+
+

Again, let's look at the differences between the two files.

+
+
    +
  • The %CModule directive has been added. This has the same syntax as +the %Module directive used in the previous example but tells SIP that +the library being wrapped is implemented in C rather than C++.
    • +
  • The %TypeHeaderCode directive has been added.
    • +
  • The Factory annotation has been added to the create_word() function. +This tells SIP that a newly created structure is being returned and it is +owned by Python.
    • +
+
+

The configure.py build system script described in the previous example can +be used for this example without change.

+
+
+

4.3   A More Complex C++ Example

+

In this last example we will wrap a fictional C++ library that contains a class +that is derived from a Qt 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.

+

The library contains a single C++ class called Hello which is derived from +Qt's QLabel class. It behaves just like QLabel except that the text +in the label is hard coded to be Hello World. To make the example more +interesting we'll also say that the library only supports Qt v3.0 and later, +and also includes a function called setDefault() that is not implemented +in the Windows version of the library.

+

The hello.h header file looks something like this:

+
+// Define the interface to the hello library.
+
+#include <qlabel.h>
+#include <qwidget.h>
+#include <qstring.h>
+
+class Hello : public QLabel {
+    // This is needed by the Qt Meta-Object Compiler.
+    Q_OBJECT
+
+public:
+    Hello(QWidget *parent, const char *name = 0, WFlags f = 0);
+
+private:
+    // Prevent instances from being copied.
+    Hello(const Hello &);
+    Hello &operator=(const Hello &);
+};
+
+#if !defined(Q_OS_WIN)
+void setDefault(const QString &def);
+#endif
+
+

The corresponding SIP specification file would then look something like this:

+
+// Define the SIP wrapper to the hello library.
+
+%Module hello 0
+
+%Import qt/qtmod.sip
+
+%If (Qt_3_0_0 -)
+
+class Hello : QLabel {
+
+%TypeHeaderCode
+#include <hello.h>
+%End
+
+public:
+    Hello(QWidget *parent /TransferThis/, const char *name = 0, WFlags f = 0);
+
+private:
+    Hello(const Hello &);
+};
+
+%If (!WS_WIN)
+void setDefault(const QString &def);
+%End
+
+%End
+
+

Again we look at the differences, but we'll skip those that we've looked at in +previous examples.

+
+
    +
  • The %Import directive has been added to specify that we are extending +the class hierarchy defined in the file qt/qtmod.sip. This file is +part of PyQt. The build system will take care of finding the file's +exact location.
    • +
  • The %If directive has been added to specify that +everything [4] up to the matching %End directive only applies to Qt +v3.0 and later. Qt_3_0_0 is a tag defined in qtmod.sip [5] +using the %Timeline directive. %Timeline 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 configure.py scripts for working out +the correct tags to use according to which version of the library is +actually installed.
    • +
  • The public keyword used in defining the super-classes has been +removed. This is not supported by SIP.
    • +
  • The TransferThis annotation has been added to the first argument +of the constructor. It specifies that if the argument is not 0 (i.e. the +Hello instance being constructed has a parent) then ownership of the +instance is transferred from Python to C++. It is needed because Qt +maintains objects (i.e. instances derived from the QObject class) in +a hierachy. When an object is destroyed all of its children 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 Ownership of Objects. SIP provides many other +annotations that can be applied to arguments, functions and classes. +Multiple annotations are separated by commas. Annotations may have +values.
    • +
  • The = operator has been removed. This operator is not supported by +SIP.
    • +
  • The %If directive has been added to specify that everything up to the +matching %End directive does not apply to Windows. WS_WIN is +another tag defined by PyQt, this time using the %Platforms directive. +Tags defined by the %Platforms directive are mutually exclusive, i.e. +only one may be valid at a time [6].
    • +
+
+

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.

+

We now look at the configure.py script. This is a little different to the +script in the previous examples for two related reasons.

+

Firstly, PyQt includes a pure Python module called pyqtconfig that extends +the SIP build system for modules, like our example, that build on top of PyQt. +It deals with the details of which version of Qt 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.

+

Secondly, we generate a configuration module (called helloconfig) for our +own hello 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.

+

Now we have two scripts. First the configure.py script:

+
+import os
+import sipconfig
+import pyqtconfig
+
+# The name of the SIP build file generated by SIP and used by the build
+# system.
+build_file = "hello.sbf"
+
+# Get the PyQt configuration information.
+config = pyqtconfig.Configuration()
+
+# Get the extra SIP flags needed by the imported qt module.  Note that
+# this normally only includes those flags (-x and -t) that relate to SIP's
+# versioning system.
+qt_sip_flags = config.pyqt_qt_sip_flags
+
+# Run SIP to generate the code.  Note that we tell SIP where to find the qt
+# module's specification files using the -I flag.
+os.system(" ".join([config.sip_bin, "-c", ".", "-b", build_file, "-I", config.pyqt_sip_dir, qt_sip_flags, "hello.sip"]))
+
+# We are going to install the SIP specification file for this module and
+# its configuration module.
+installs = []
+
+installs.append(["hello.sip", os.path.join(config.default_sip_dir, "hello")])
+
+installs.append(["helloconfig.py", config.default_mod_dir])
+
+# Create the Makefile.  The QtModuleMakefile class provided by the
+# pyqtconfig module takes care of all the extra preprocessor, compiler and
+# linker flags needed by the Qt library.
+makefile = pyqtconfig.QtModuleMakefile(
+    configuration=config,
+    build_file=build_file,
+    installs=installs
+)
+
+# Add the library we are wrapping.  The name doesn't include any platform
+# specific prefixes or extensions (e.g. the "lib" prefix on UNIX, or the
+# ".dll" extension on Windows).
+makefile.extra_libs = ["hello"]
+
+# Generate the Makefile itself.
+makefile.generate()
+
+# Now we create the configuration module.  This is done by merging a Python
+# dictionary (whose values are normally determined dynamically) with a
+# (static) template.
+content = {
+    # Publish where the SIP specifications for this module will be
+    # installed.
+    "hello_sip_dir":    config.default_sip_dir,
+
+    # Publish the set of SIP flags needed by this module.  As these are the
+    # same flags needed by the qt module we could leave it out, but this
+    # allows us to change the flags at a later date without breaking
+    # scripts that import the configuration module.
+    "hello_sip_flags":  qt_sip_flags
+}
+
+# This creates the helloconfig.py module from the helloconfig.py.in
+# template and the dictionary.
+sipconfig.create_config_module("helloconfig.py", "helloconfig.py.in", content)
+
+

Next we have the helloconfig.py.in template script:

+
+import pyqtconfig
+
+# These are installation specific values created when Hello was configured.
+# The following line will be replaced when this template is used to create
+# the final configuration module.
+# @SIP_CONFIGURATION@
+
+class Configuration(pyqtconfig.Configuration):
+    """The class that represents Hello configuration values.
+    """
+    def __init__(self, sub_cfg=None):
+        """Initialise an instance of the class.
+
+        sub_cfg is the list of sub-class configurations.  It should be None
+        when called normally.
+        """
+        # This is all standard code to be copied verbatim except for the
+        # name of the module containing the super-class.
+        if sub_cfg:
+            cfg = sub_cfg
+        else:
+            cfg = []
+
+        cfg.append(_pkg_config)
+
+        pyqtconfig.Configuration.__init__(self, cfg)
+
+class HelloModuleMakefile(pyqtconfig.QtModuleMakefile):
+    """The Makefile class for modules that %Import hello.
+    """
+    def finalise(self):
+        """Finalise the macros.
+        """
+        # Make sure our C++ library is linked.
+        self.extra_libs.append("hello")
+
+        # Let the super-class do what it needs to.
+        pyqtconfig.QtModuleMakefile.finalise(self)
+
+

Again, we hope that the scripts are self documenting.

+ + + + + +
[4]Some parts of a SIP specification aren't subject to version control.
+ + + + + +
[5]Actually in versions.sip. PyQt uses the %Include directive to +split the SIP specification for Qt across a large number of separate +.sip files.
+ + + + + +
[6]Tags can also be defined by the %Feature directive. These tags are +not mutually exclusive, i.e. any number may be valid at a time.
+
+
+

4.4   Ownership of Objects

+

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.

+

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.

+

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).

+

This applies equally to C structures where the structure is returned to the +heap using the free() function.

+

See also sipTransferTo() and sipTransferBack().

+
+
+

4.5   Support for Wide Characters

+

SIP v4.6 introduced support for wide characters (i.e. the wchar_t type). +Python's C API includes support for converting between unicode objects and wide +character strings and arrays. When converting from a unicode object to wide +characters SIP creates the string or array on the heap (using memory allocated +using sipMalloc()). This then raises the problem of how this memory is +subsequently freed.

+

The following describes how SIP handles this memory in the different situations +where this is an issue.

+
+
    +
  • When a wide string or array is passed to a function or method then the +memory is freed (using sipFree()) after than function or method +returns.
    • +
  • 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.
    • +
  • 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.
    • +
+
+
+
+

4.6   The Python Global Interpreter Lock

+

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.

+

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 ReleaseGIL annotation can be used to override +this behaviour when required.

+

If SIP is given the -g 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 HoldGIL annotation can be used to override this +behaviour when required.

+
+
+
+

5   The SIP Command Line

+

The syntax of the SIP command line is:

+
+sip [options] [specification]
+
+

specification is the name of the specification file for the module. If it +is omitted then stdin is used.

+

The full set of command line options is:

+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+-hDisplay a help message.
+-VDisplay the SIP version number.
+-a fileThe name of the QScintilla API file to generate. This file contains a +description of the module API in a form that the QScintilla editor +component can use for auto-completion and call tips. (The file may +also be used by the SciTE editor but must be sorted first.) By default +the file is not generated.
+-b fileThe name of the build file to generate. This file contains the +information about the module needed by the SIP build system to generate +a platform and compiler specific Makefile for the module. By default +the file is not generated.
+-c dirThe name of the directory (which must exist) into which all of the +generated C or C++ code is placed. By default no code is generated.
+-d fileThe name of the documentation file to generate. Documentation is +included in specification files using the %Doc and %ExportedDoc +directives. By default the file is not generated.
+-eSupport for C++ exceptions is enabled. This causes all calls to C++ +code to be enclosed in try/catch blocks and C++ exceptions to +be converted to Python exceptions. By default exception support is +disabled.
+-gThe Python GIL is released before making any calls to the C/C++ library +being wrapped and reacquired afterwards. See The Python Global +Interpreter Lock and the ReleaseGIL and HoldGIL annotations.
+-I dirThe directory is added to the list of directories searched when looking +for a specification file given in an %Include or %Import +directive. This option may be given any number of times.
+-j numberThe generated code is split into the given number of files. This make +it easier to use the parallel build facility of most modern +implementations of make. By default 1 file is generated for each C +structure or C++ class.
+-rDebugging statements that trace the execution of the bindings are +automatically generated. By default the statements are not generated.
+-s suffixThe suffix to use for generated C or C++ source files. By default +.c is used for C and .cpp for C++.
+-t tagThe SIP version tag (declared using a %Timeline directive) or the +SIP platform tag (declared using the %Platforms directive) to +generate code for. This option may be given any number of times so +long as the tags do not conflict.
+-wThe display of warning messages is enabled. By default warning +messages are disabled.
+-x featureThe feature (declared using the %Feature directive) is disabled.
+-z fileThe name of a file containing more command line options.
+
+
+

6   SIP Specification Files

+

A SIP specification consists of some C/C++ type and function declarations and +some directives. The declarations may contain annotations which provide SIP +with additional information that cannot be expressed in C/C++. SIP does not +include a full C/C++ parser.

+

It is important to understand that a SIP specification describes the Python +API, i.e. the API available to the Python programmer when they import the +generated module. It does not have to accurately represent the underlying +C/C++ library. There is nothing wrong with omitting functions that make +little sense in a Python context, or adding functions implemented with +handwritten code that have no C/C++ equivalent. It is even possible (and +sometimes necessary) to specify a different super-class hierarchy for a C++ +class. All that matters is that the generated code compiles properly.

+

In most cases the Python API matches the C/C++ API. In some cases handwritten +code (see %MethodCode) is used to map from one to the other without SIP +having to know the details itself. However, there are a few cases where SIP +generates a thin wrapper around a C++ method or constructor (see Generated +Derived Classes) and needs to know the exact C++ signature. To deal with +these cases SIP allows two signatures to be specified. For example:

+
+class Klass
+{
+public:
+    // The Python signature is a tuple, but the underlying C++ signature
+    // is a 2 element array.
+    Klass(SIP_PYTUPLE) [(int *)];
+%MethodCode
+        int iarr[2];
+
+        if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1]))
+        {
+            // Note that we use the SIP generated derived class
+            // constructor.
+            Py_BEGIN_ALLOW_THREADS
+            sipCpp = new sipKlass(iarr);
+            Py_END_ALLOW_THREADS
+        }
+%End
+};
+
+
+

6.1   Syntax Definition

+

The following is a semi-formal description of the syntax of a specification +file.

+
+specification ::= {module-statement}
+
+module-statement ::= [module-directive | statement]
+
+module-directive ::= [%CModule | %Copying | %Doc |
+        %ExportedDoc | %ExportedHeaderCode | %Feature |
+        %Import | %Include | %License | %MappedType |
+        mapped-type-template | %Module | %ModuleCode |
+        %ModuleHeaderCode | %OptionalInclude | %Platforms |
+        %PreInitialisationCode | %PostInitialisationCode |
+        sip-option-list | %Timeline | %UnitCode]
+
+sip-option-list :: %SIPOptions ( option-list )
+
+option-list ::= option [, option-list]
+
+statement :: [class-statement | function | variable]
+
+class-statement :: [%If | class | class-template | enum |
+        namespace | opaque-class | operator | struct | typedef |
+        exception]
+
+class ::= class name [: super-classes] [class-annotations]
+        { {class-line} };
+
+super-classes ::= name [, super-classes]
+
+class-line ::= [class-statement | %BIGetReadBufferCode |
+        %BIGetWriteBufferCode | %BIGetSegCountCode |
+        %BIGetCharBufferCode | %ConvertToSubClassCode |
+        %ConvertToTypeCode | %GCClearCode | %GCTraverseCode |
+        %TypeCode | %TypeHeaderCode | constructor | destructor |
+        method | static-method | virtual-method | special-method |
+        operator | virtual-operator | class-variable | public: |
+        public slots: | protected: | protected slots: |
+        private: | private slots: | signals:]
+
+constructor ::= [explicit] name ( [argument-list] )
+        [exceptions] [function-annotations]
+        [c++-constructor-signature] ; [%MethodCode]
+
+c++-constructor-signature ::= [( [argument-list] )]
+
+destructor ::= [virtual] ~ name () [exceptions] [= 0]
+        [function-annotations] ; [%MethodCode]
+        [%VirtualCatcherCode]
+
+method ::= type name ( [argument-list] ) [const]
+        [exceptions] [= 0] [function-annotations] [c++-signature]
+        ; [%MethodCode]
+
+c++-signature ::= [ type ( [argument-list] )]
+
+static-method ::= static function
+
+virtual-method ::= virtual type name ( [argument-list] )
+        [const] [exceptions] [= 0] [function-annotations]
+        [c++-signature] ; [%MethodCode] [%VirtualCatcherCode]
+
+special-method ::= type special-method-name
+        ( [argument-list] ) [function-annotations] ;
+        [%MethodCode]
+
+special-method-name ::= [ __abs__ | __add__ | __and__ |
+        __call__ | __cmp__ | __contains__ | __delitem__ |
+        __div__ | __eq__ | __float__ | __ge__ |
+        __getitem__ | __gt__ | __hash__ | __iadd__ |
+        __iand__ | __idiv__ | __ilshift__ | __imod__ |
+        __imul__ | __int__ | __invert__ | __ior__ |
+        __irshift__ | __isub__ | __ixor__ | __le__ |
+        __len__ | __long__ | __lshift__ | __lt__ |
+        __mod__ | __mul__ | __ne__ | __neg__ |
+        __nonzero__ | __or__ | __pos__ | __repr__ |
+        __rshift__ | __setitem__ | __str__ | __sub__ |
+        __xor__]
+
+operator ::= operator-type
+        ( [argument-list] ) [const] [exceptions]
+        [function-annotations] ; [%MethodCode]
+
+virtual-operator ::= virtual operator-type
+        ( [argument-list] ) [const] [exceptions] [= 0]
+        [function-annotations] ; [%MethodCode]
+        [%VirtualCatcherCode]
+
+operatator-type ::= [ operator-function | operator-cast ]
+
+operator-function ::= type operator operator-name
+
+operator-cast ::= operator type
+
+operator-name ::= [+ | - | * | / | % | & |
+        | | ^ | << | >> | += | -= | *= |
+        /= | %= | &= | |= | ^= | <<= | >>= |
+        ~ | () | [] | < | <= | == | != |
+        > | >>=]
+
+class-variable ::= [static] variable
+
+class-template :: = template < type-list > class
+
+mapped-type-template :: = template < type-list >
+        %MappedType
+
+enum ::= enum [name] [enum-annotations] { {enum-line} };
+
+enum-line ::= [%If | name [enum-annotations] ,
+
+function ::= type name ( [argument-list] ) [exceptions]
+        [function-annotations] ; [%MethodCode]
+
+namespace ::= namespace name { {namespace-line} };
+
+namespace-line ::= [%TypeHeaderCode | statement]
+
+opaque-class ::= class scoped-name ;
+
+struct ::= struct name { {class-line} };
+
+typedef ::= typedef [typed-name | function-pointer] ;
+
+variable::= typed-name [variable-annotations] ; [%AccessCode]
+        [%GetCode] [%SetCode]
+
+exception ::= %Exception exception-name [exception-base] {
+        [%TypeHeaderCode] %RaiseCode };`
+
+exception-name ::= scoped-name
+
+exception-base ::= ( [exception-name | python-exception] )
+
+python-exception ::= [SIP_Exception | SIP_StopIteration |
+        SIP_StandardError | SIP_ArithmeticError |
+        SIP_LookupError | SIP_AssertionError |
+        SIP_AttributeError | SIP_EOFError |
+        SIP_FloatingPointError | SIP_EnvironmentError |
+        SIP_IOError | SIP_OSError | SIP_ImportError |
+        SIP_IndexError | SIP_KeyError | SIP_KeyboardInterrupt |
+        SIP_MemoryError | SIP_NameError | SIP_OverflowError |
+        SIP_RuntimeError | SIP_NotImplementedError |
+        SIP_SyntaxError | SIP_IndentationError | SIP_TabError |
+        SIP_ReferenceError | SIP_SystemError | SIP_SystemExit |
+        SIP_TypeError | SIP_UnboundLocalError |
+        SIP_UnicodeError | SIP_UnicodeEncodeError |
+        SIP_UnicodeDecodeError | SIP_UnicodeTranslateError |
+        SIP_ValueError | SIP_ZeroDivisionError |
+        SIP_WindowsError | SIP_VMSError]
+
+exceptions ::= throw ( [exception-list] )
+
+exception-list ::= scoped-name [, exception-list]
+
+argument-list ::= argument [, argument-list] [, ...]
+
+argument ::= [type [name] [argument-annotations]
+        [default-value] | SIP_ANYSLOT [default-value] | SIP_QOBJECT |
+        SIP_RXOBJ_CON | SIP_RXOBJ_DIS | SIP_SIGNAL [default-value] |
+        SIP_SLOT [default-value] | SIP_SLOT_CON | SIP_SLOT_DIS]
+
+default-value ::= = expression
+
+expression ::= [value | value binary-operator expression]
+
+value ::= [unary-operator] simple-value
+
+simple-value ::= [scoped-name | function-call | real-value |
+        integer-value | boolean-value | string-value |
+        character-value]
+
+typed-name::= type name
+
+function-pointer::= type (* name )( [type-list] )
+
+type-list ::= type [, type-list]
+
+function-call ::= scoped-name ( [value-list] )
+
+value-list ::= value [, value-list]
+
+real-value ::= a floating point number
+
+integer-value ::= a number
+
+boolean-value ::= [true | false]
+
+string-value ::= " {character} "
+
+character-value ::= ` character `
+
+unary-operator ::= [! | ~ | - | +]
+
+binary-operator ::= [- | + | * | / | & | |]
+
+argument-annotations ::= see Argument Annotations
+
+class-annotations ::= see Class Annotations
+
+enum-annotations ::= see Enum Annotations
+
+function-annotations ::= see Function Annotations
+
+variable-annotations ::= see Variable Annotations
+
+type ::= [const] base-type {*} [&]
+
+type-list ::= type [, type-list]
+
+base-type ::= [scoped-name | template | struct scoped-name |
+        short | unsigned short | int | unsigned |
+        unsigned int | long | unsigned long | float |
+        double | bool | char | signed char |
+        unsigned char | void | wchar_t | SIP_PYCALLABLE |
+        SIP_PYDICT | SIP_PYLIST | SIP_PYOBJECT | SIP_PYSLICE |
+        SIP_PYTUPLE | SIP_PYTYPE]
+
+scoped-name ::= name [:: scoped-name]
+
+template ::= scoped-name < type-list >
+
+name ::= _A-Za-z {_A-Za-z0-9}
+
+

Here is a short list of differences between C++ and the subset supported by +SIP that might trip you up.

+
+
    +
  • SIP does not support the use of [] in types. Use pointers instead.
    • +
  • A global operator can only be defined if its first argument is a +class or a named enum that has been wrapped in the same module.
    • +
  • Variables declared outside of a class are effectively read-only.
    • +
  • A class's list of super-classes doesn't not include any access specifier +(e.g. public).
    • +
+
+
+
+

6.2   Variable Numbers of Arguments

+

SIP supports the use of ... as the last part of a function signature. Any +remaining arguments are collected as a Python tuple.

+
+
+

6.3   Additional SIP Types

+

SIP supports a number of additional data types that can be used in Python +signatures.

+
+

6.3.1   SIP_ANYSLOT

+

This is both a const char * and a PyObject * that is used as the type +of the member instead of const char * in functions that implement the +connection or disconnection of an explicitly generated signal to a slot. +Handwritten code must be provided to interpret the conversion correctly.

+
+
+

6.3.2   SIP_PYCALLABLE

+

This is a PyObject * that is a Python callable object.

+
+
+

6.3.3   SIP_PYDICT

+

This is a PyObject * that is a Python dictionary object.

+
+
+

6.3.4   SIP_PYLIST

+

This is a PyObject * that is a Python list object.

+
+
+

6.3.5   SIP_PYOBJECT

+

This is a PyObject * of any Python type.

+
+
+

6.3.6   SIP_PYSLICE

+

This is a PyObject * that is a Python slice object.

+
+
+

6.3.7   SIP_PYTUPLE

+

This is a PyObject * that is a Python tuple object.

+
+
+

6.3.8   SIP_PYTYPE

+

This is a PyObject * that is a Python type object.

+
+
+

6.3.9   SIP_QOBJECT

+

This is a QObject * that is a C++ instance of a class derived from Qt's +QObject class.

+
+
+

6.3.10   SIP_RXOBJ_CON

+

This is a QObject * that is a C++ instance of a class derived from Qt's +QObject class. It is used as the type of the receiver instead of const +QObject * in functions that implement a connection to a slot.

+
+
+

6.3.11   SIP_RXOBJ_DIS

+

This is a QObject * that is a C++ instance of a class derived from Qt's +QObject class. It is used as the type of the receiver instead of const +QObject * in functions that implement a disconnection from a slot.

+
+
+

6.3.12   SIP_SIGNAL

+

This is a const char * that is used as the type of the signal instead of +const char * in functions that implement the connection or disconnection +of an explicitly generated signal to a slot.

+
+
+

6.3.13   SIP_SLOT

+

This is a const char * that is used as the type of the member instead of +const char * in functions that implement the connection or disconnection +of an explicitly generated signal to a slot.

+
+
+

6.3.14   SIP_SLOT_CON

+

This is a const char * that is used as the type of the member instead of +const char * in functions that implement the connection of an internally +generated signal to a slot. The type includes a comma separated list of types +that is the C++ signature of of the signal.

+

To take an example, QAccel::connectItem() connects an internally generated +signal to a slot. The signal is emitted when the keyboard accelerator is +activated and it has a single integer argument that is the ID of the +accelerator. The C++ signature is:

+
+bool connectItem(int id, const QObject *receiver, const char *member);
+
+

The corresponding SIP specification is:

+
+bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int));
+
+
+
+

6.3.15   SIP_SLOT_DIS

+

This is a const char * that is used as the type of the member instead of +const char * in functions that implement the disconnection of an +internally generated signal to a slot. The type includes a comma separated +list of types that is the C++ signature of of the signal.

+
+
+
+
+

7   SIP Directives

+

In this section we describe each of the directives that can be used in +specification files. All directives begin with % as the first +non-whitespace character in a line.

+

Some directives have arguments or contain blocks of code or documentation. In +the following descriptions these are shown in italics. Optional arguments +are enclosed in [brackets].

+

Some directives are used to specify handwritten code. Handwritten code must +not define names that start with the prefix sip.

+
+

7.1   %AccessCode

+
+%AccessCode
+    code
+%End
+
+

This directive is used immediately after the declaration of an instance of a +wrapped class or structure, or a pointer to such an instance. You use it to +provide handwritten code that overrides the default behaviour.

+

For example:

+
+class Klass;
+
+Klass *klassInstance;
+%AccessCode
+    // In this contrived example the C++ library we are wrapping defines
+    // klassInstance as Klass ** (which SIP doesn't support) so we
+    // explicitly dereference it.
+    if (klassInstance && *klassInstance)
+        return *klassInstance;
+
+    // This will get converted to None.
+    return 0;
+%End
+
+
+
+

7.2   %BIGetCharBufferCode

+
+%BIGetCharBufferCode
+    code
+%End
+
+

This directive (along with %BIGetReadBufferCode, %BIGetSegCountCode and +%BIGetWriteBufferCode) is used to specify code that implements Python's +buffer interface. See the section Buffer Object Structures for the +details.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class.
+
void **sipPtrPtr
+
This is the pointer used to return the address of the character buffer.
+
SIP_SSIZE_T sipRes
+
The handwritten code should set this to the length of the character buffer +or -1 if there was an error.
+
SIP_SSIZE_T sipSegment
+
This is the number of the segment of the character buffer.
+
PyObject *sipSelf
+
This is the Python object that wraps the the structure or class instance, +i.e. self.
+
+
+
+

7.3   %BIGetReadBufferCode

+
+%BIGetReadBufferCode
+    code
+%End
+
+

This directive (along with %BIGetCharBufferCode, %BIGetSegCountCode and +%BIGetWriteBufferCode) is used to specify code that implements Python's +buffer interface.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class.
+
void **sipPtrPtr
+
This is the pointer used to return the address of the read buffer.
+
SIP_SSIZE_T sipRes
+
The handwritten code should set this to the length of the read buffer or +-1 if there was an error.
+
SIP_SSIZE_T sipSegment
+
This is the number of the segment of the read buffer.
+
PyObject *sipSelf
+
This is the Python object that wraps the the structure or class instance, +i.e. self.
+
+
+
+

7.4   %BIGetSegCountCode

+
+%BIGetSegCountCode
+    code
+%End
+
+

This directive (along with %BIGetCharBufferCode, %BIGetReadBufferCode and +%BIGetWriteBufferCode) is used to specify code that implements Python's +buffer interface.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class.
+
SIP_SSIZE_T *sipLenPtr
+
This is the pointer used to return the total length in bytes of all +segments of the buffer.
+
SIP_SSIZE_T sipRes
+
The handwritten code should set this to the number of segments that make +up the buffer.
+
PyObject *sipSelf
+
This is the Python object that wraps the the structure or class instance, +i.e. self.
+
+
+
+

7.5   %BIGetWriteBufferCode

+
+%BIGetWriteBufferCode
+    code
+%End
+
+

This directive (along with %BIGetCharBufferCode, %BIGetReadBufferCode +and %BIGetSegCountCode is used to specify code that implements Python's +buffer interface.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class.
+
void **sipPtrPtr
+
This is the pointer used to return the address of the write buffer.
+
SIP_SSIZE_T sipRes
+
The handwritten code should set this to the length of the write buffer or +-1 if there was an error.
+
SIP_SSIZE_T sipSegment
+
This is the number of the segment of the write buffer.
+
PyObject *sipSelf
+
This is the Python object that wraps the the structure or class instance, +i.e. self.
+
+
+
+

7.6   %CModule

+
+%CModule name [version]
+
+

This directive is used to identify that the library being wrapped is a C +library and to define the name of the module and it's optional version number.

+

See the %Module directive for an explanation of the version number.

+

For example:

+
+%CModule dbus 1
+
+
+
+

7.7   %ConvertFromTypeCode

+
+%ConvertFromTypeCode
+    code
+%End
+
+

This directive is used as part of the %MappedType directive to specify the +handwritten code that converts an instance of a mapped type to a Python +object.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the instance of the mapped type to be converted. It +will never be zero as the conversion from zero to Py_None is handled +before the handwritten code is called.
+
PyObject *sipTransferObj
+
This specifies any desired ownership changes to the returned object. If it +is NULL then the ownership should be left unchanged. If it is +Py_None then ownership should be transferred to Python. Otherwise +ownership should be transferred to C/C++ and the returned object associated +with sipTransferObj. The code can choose to interpret these changes in +any way. For example, if the code is converting a C++ container of wrapped +classes to a Python list it is likely that the ownership changes should be +made to each element of the list.
+
+

The handwritten code must explicitly return a PyObject *. If there was an +error then a Python exception must be raised and NULL returned.

+

The following example converts a QList<QWidget *> instance to a Python +list of QWidget instances:

+
+%ConvertFromTypeCode
+    PyObject *l;
+
+    // Create the Python list of the correct length.
+    if ((l = PyList_New(sipCpp -> size())) == NULL)
+        return NULL;
+
+    // Go through each element in the C++ instance and convert it to a
+    // wrapped QWidget.
+    for (int i = 0; i < sipCpp -> size(); ++i)
+    {
+        QWidget *w = sipCpp -> at(i);
+        PyObject *wobj;
+
+        // Get the Python wrapper for the QWidget instance, creating a new
+        // one if necessary, and handle any ownership transfer.
+        if ((wobj = sipConvertFromInstance(w, sipClass_QWidget, sipTransferObj)) == NULL)
+        {
+            // There was an error so garbage collect the Python list.
+            Py_DECREF(l);
+            return NULL;
+        }
+
+        // Add the wrapper to the list.
+        PyList_SET_ITEM(l, i, wobj);
+    }
+
+    // Return the Python list.
+    return l;
+%End
+
+
+
+

7.8   %ConvertToSubClassCode

+
+%ConvertToSubClassCode
+    code
+%End
+
+

When SIP needs to wrap a C++ class instance it first checks to make sure it +hasn't already done so. If it has then it just returns a new reference to the +corresponding Python object. Otherwise it creates a new Python object of the +appropriate type. In C++ a function may be defined to return an instance of a +certain class, but can often return a sub-class instead.

+

This directive is used to specify handwritten code that exploits any available +real-time type information (RTTI) to see if there is a more specific Python +type that can be used when wrapping the C++ instance. The RTTI may be +provided by the compiler or by the C++ instance itself.

+

The directive is included in the specification of one of the classes that the +handwritten code handles the type conversion for. It doesn't matter which +one, but a sensible choice would be the one at the root of that class +hierarchy in the module.

+

Note that if a class hierarchy extends over a number of modules then this +directive should be used in each of those modules to handle the part of the +hierarchy defined in that module. SIP will ensure that the different pieces +of code are called in the right order to determine the most specific Python +type to use.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the C++ class instance.
+
void **sipCppRet
+
When the sub-class is derived from more than one super-class then it is +possible that the C++ address of the instance as the sub-class is +different to that of the super-class. If so, then this must be set to the +C++ address of the instance when cast (usually using static_cast) +from the super-class to the sub-class.
+
sipWrapperType *sipClass
+
The handwritten code must set this to the SIP generated Python type object +that corresponds to the class instance. (The type object for class +Klass is sipClass_Klass.) If the RTTI of the class instance isn't +recognised then sipClass must be set to NULL. The code doesn't +have to recognise the exact class, only the most specific sub-class that +it can.
+
+

The handwritten code must not explicitly return.

+

The following example shows the sub-class conversion code for QEvent based +class hierarchy in PyQt:

+
+class QEvent
+{
+%ConvertToSubClassCode
+    // QEvent sub-classes provide a unique type ID.
+    switch (sipCpp -> type())
+    {
+    case QEvent::Timer:
+        sipClass = sipClass_QTimerEvent;
+        break;
+
+    case QEvent::KeyPress:
+    case QEvent::KeyRelease:
+        sipClass = sipClass_QKeyEvent;
+        break;
+
+    // Skip the remaining event types to keep the example short.
+
+    default:
+        // We don't recognise the type.
+        sipClass = NULL;
+    }
+%End
+
+    // The rest of the class specification.
+
+};
+
+

The SIP API includes the sipMapIntToClass() and sipMapStringToClass() +functions that convert integer and string based RTTI to Python type objects +based on ordered lookup tables.

+
+
+

7.9   %ConvertToTypeCode

+
+%ConvertToTypeCode
+    code
+%End
+
+

This directive is used to specify the handwritten code that converts a Python +object to a mapped type instance and to handle any ownership transfers. It is +used as part of the %MappedType directive and as part of a class +specification. The code is also called to determine if the Python object is of +the correct type prior to conversion.

+

When used as part of a class specification it can automatically convert +additional types of Python object. For example, PyQt uses it in the +specification of the QString class to allow Python string objects and +unicode objects to be used wherever QString instances are expected.

+

The following variables are made available to the handwritten code:

+
+
int *sipIsErr
+
If this is NULL then the code is being asked to check the type of the +Python object. The check must not have any side effects. Otherwise the +code is being asked to convert the Python object and a non-zero value +should be returned through this pointer if an error occurred during the +conversion.
+
PyObject *sipPy
+
This is the Python object to be converted.
+
type **sipCppPtr
+
This is a pointer through which the address of the mapped type instance (or +zero if appropriate) is returned. Its value is undefined if sipIsErr +is NULL.
+
PyObject *sipTransferObj
+
This specifies any desired ownership changes to sipPy. If it is NULL +then the ownership should be left unchanged. If it is Py_None then +ownership should be transferred to Python. Otherwise ownership should be +transferred to C/C++ and sipPy associated with sipTransferObj. The +code can choose to interpret these changes in any way.
+
+

The handwritten code must explicitly return an int the meaning of which +depends on the value of sipIsErr.

+

If sipIsErr is NULL then a non-zero value is returned if the Python +object has a type that can be converted to the mapped type. Otherwise zero is +returned.

+

If sipIsErr is not NULL then a combination of the following flags is +returned.

+
+
    +
  • SIP_TEMPORARY is set to indicate that the returned instance is a +temporary and should be released to avoid a memory leak.
    • +
  • SIP_DERIVED_CLASS is set to indicate that the type of the +returned instance is a derived class. See Generated Derived +Classes.
    • +
+
+

The following example converts a Python list of QPoint instances to a +QList<QPoint> instance:

+
+%ConvertToTypeCode
+    // See if we are just being asked to check the type of the Python
+    // object.
+    if (!sipIsErr)
+    {
+        // Checking whether or not None has been passed instead of a list
+        // has already been done.
+        if (!PyList_Check(sipPy))
+            return 0;
+
+        // Check the type of each element.  We specify SIP_NOT_NONE to
+        // disallow None because it is a list of QPoint, not of a pointer
+        // to a QPoint, so None isn't appropriate.
+        for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+            if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i),
+                                         sipClass_QPoint, SIP_NOT_NONE))
+                return 0;
+
+        // The type is valid.
+        return 1;
+    }
+
+    // Create the instance on the heap.
+    QList<QPoint> *ql = new QList<QPoint>;
+
+    for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+    {
+        QPoint *qp;
+        int state;
+
+        // Get the address of the element's C++ instance.  Note that, in
+        // this case, we don't apply any ownership changes to the list
+        // elements, only to the list itself.
+        qp = reinterpret_cast<QPoint *>(sipConvertToInstance(
+                                                PyList_GET_ITEM(sipPy, i),
+                                                sipClass_QPoint, 0,
+                                                SIP_NOT_NONE,
+                                                &state, sipIsErr));
+
+        // Deal with any errors.
+        if (*sipIsErr)
+        {
+            sipReleaseInstance(qp, sipClass_QPoint, state);
+
+            // Tidy up.
+            delete ql;
+
+            // There is no temporary instance.
+            return 0;
+        }
+
+        ql -> append(*qp);
+
+        // A copy of the QPoint was appended to the list so we no longer
+        // need it.  It may be a temporary instance that should be
+        // destroyed, or a wrapped instance that should not be destroyed.
+        // sipReleaseInstance() will do the right thing.
+        sipReleaseInstance(qp, sipClass_QPoint, state);
+    }
+
+    // Return the instance.
+    *sipCppPtr = ql;
+
+    // The instance should be regarded as temporary (and be destroyed as
+    // soon as it has been used) unless it has been transferred from
+    // Python.  sipGetState() is a convenience function that implements
+    // this common transfer behaviour.
+    return sipGetState(sipTransferObj);
+%End
+
+

When used in a class specification the handwritten code replaces the code that +would normally be automatically generated. This means that the handwritten +code must also handle instances of the class itself and not just the additional +types that are being supported. This should be done by making calls to +sipCanConvertToInstance() to check the object type and +sipConvertToInstance() to convert the object. The SIP_NO_CONVERTORS +flag must be passed to both these functions to prevent recursive calls to the +handwritten code.

+
+
+

7.10   %Copying

+
+%Copying
+    text
+%End
+
+

This directive is used to specify some arbitrary text that will be included at +the start of all source files generated by SIP. It is normally used to +include copyright and licensing terms.

+

For example:

+
+%Copying
+Copyright (c) 2007 Riverbank Computing Limited
+%End
+
+
+
+

7.11   %Doc

+
+%Doc
+    text
+%End
+
+

This directive is used to specify some arbitrary text that will be extracted +by SIP when the -d command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them.

+

Documentation that is specified using this directive is local to the module in +which it appears. It is ignored by modules that %Import it. Use the +%ExportedDoc directive for documentation that should be included by all +modules that %Import this one.

+

For example:

+
+%Doc
+<h1>An Example</h1>
+<p>
+This fragment of documentation is HTML and is local to the module in
+which it is defined.
+</p>
+%End
+
+
+
+

7.12   %End

+

This isn't a directive in itself, but is used to terminate a number of +directives that allow a block of handwritten code or text to be specified.

+
+
+

7.13   %Exception

+
+%Exception name [(base-exception)]
+{
+    [*header-code]
+    raise-code
+};
+
+

This directive is used to define new Python exceptions, or to provide a stub +for existing Python exceptions. It allows handwritten code to be provided +that implements the translation between C++ exceptions and Python exceptions. +The arguments to throw () specifiers must either be names of classes or the +names of Python exceptions defined by this directive.

+

name is the name of the exception.

+

base-exception is the optional base exception. This may be either one of +the standard Python exceptions or one defined with a previous %Exception +directive.

+

header-code is the optional %TypeHeaderCode used to specify any external +interface to the exception being defined.

+

raise-code is the %RaiseCode used to specify the handwritten code that +converts a reference to the C++ exception to the Python exception.

+

For example:

+
+%Exception std::exception(SIP_Exception) /PyName=StdException/
+{
+%TypeHeaderCode
+#include <exception>
+%End
+%RaiseCode
+        const char *detail = sipExceptionReference.what();
+
+        SIP_BLOCK_THREADS
+        PyErr_SetString(sipException_StdException, detail);
+        SIP_UNBLOCK_THREADS
+%End
+};
+
+

In this example we map the standard C++ exception to a new Python exception. +The new exception is called StdException and is derived from the standard +Python exception Exception.

+
+
+

7.14   %ExportedDoc

+
+%ExportedDoc
+    text
+%End
+
+

This directive is used to specify some arbitrary text that will be extracted +by SIP when the -d command line option is used. The directive can be +specified any number of times and SIP will concatenate all the separate pieces +of text in the order that it sees them.

+

Documentation that is specified using this directive will also be included by +modules that %Import it.

+

For example:

+
+%ExportedDoc
+==========
+An Example
+==========
+
+This fragment of documentation is reStructuredText and will appear in the
+module in which it is defined and all modules that %Import it.
+%End
+
+
+
+

7.15   %ExportedHeaderCode

+
+%ExportedHeaderCode
+    code
+%End
+
+

This directive is used to specify handwritten code, typically the declarations +of types, that is placed in a header file that is included by all generated +code for all modules. It should not include function declarations because +Python modules should not explicitly call functions in another Python module.

+

See also %ModuleCode and %ModuleHeaderCode.

+
+
+

7.16   %Feature

+
+%Feature name
+
+

This directive is used to declare a feature. Features (along with +%Platforms and %Timeline) are used by the %If directive to control +whether or not parts of a specification are processed or ignored.

+

Features are mutually independent of each other - any combination of features +may be enabled or disable. By default all features are enabled. The SIP +-x command line option is used to disable a feature.

+

If a feature is enabled then SIP will automatically generate a corresponding C +preprocessor symbol for use by handwritten code. The symbol is the name of +the feature prefixed by SIP_FEATURE_.

+

For example:

+
+%Feature FOO_SUPPORT
+
+%If (FOO_SUPPORT)
+void foo();
+%End
+
+
+
+

7.17   %GCClearCode

+
+%GCClearCode
+    code
+%End
+
+

Python has a cyclic garbage collector which can identify and release unneeded +objects even when their reference counts are not zero. If a wrapped C +structure or C++ class keeps its own reference to a Python object then, if the +garbage collector is to do its job, it needs to provide some handwritten code +to traverse and potentially clear those embedded references.

+

See the section Supporting cyclic garbage collection in Embedding and +Extending the Python Interpreter +for the details.

+

This directive is used to specify the code that clears any embedded references. +(See %GCTraverseCode for specifying the code that traverses any embedded +references.)

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class.
+
int sipRes
+
The handwritten code should set this to the result to be returned.
+
+

The following simplified example is taken from PyQt. The QCustomEvent +class allows arbitary data to be attached to the event. In PyQt this data is +always a Python object and so should be handled by the garbage collector:

+
+%GCClearCode
+    PyObject *obj;
+
+    // Get the object.
+    obj = reinterpret_cast<PyObject *>(sipCpp -> data());
+
+    // Clear the pointer.
+    sipCpp -> setData(0);
+
+    // Clear the reference.
+    Py_XDECREF(obj);
+
+    // Report no error.
+    sipRes = 0;
+%End
+
+
+
+

7.18   %GCTraverseCode

+
+%GCTraverseCode
+    code
+%End
+
+

This directive is used to specify the code that traverses any embedded +references for Python's cyclic garbage collector. (See %GCClearCode for a +full explanation.)

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class.
+
visitproc sipVisit
+
This is the visit function provided by the garbage collector.
+
void *sipArg
+
This is the argument to the visit function provided by the garbage +collector.
+
int sipRes
+
The handwritten code should set this to the result to be returned.
+
+

The following simplified example is taken from PyQt's QCustomEvent class:

+
+%GCTraverseCode
+    PyObject *obj;
+
+    // Get the object.
+    obj = reinterpret_cast<PyObject *>(sipCpp -> data());
+
+    // Call the visit function if there was an object.
+    if (obj)
+        sipRes = sipVisit(obj, sipArg);
+    else
+        sipRes = 0;
+%End
+
+
+
+

7.19   %GetCode

+
+%GetCode
+    code
+%End
+
+

This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it to a Python object. +It is usually used to handle types that SIP cannot deal with automatically.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class. It is not made available if the +variable being wrapped is a static class variable.
+
PyObject *sipPy
+
The handwritten code must set this to the Python representation of the +class variable or structure member. If there is an error then the code +must raise an exception and set this to NULL.
+
+

For example:

+
+struct Entity
+{
+    /*
+     * In this contrived example the C library we are wrapping actually
+     * defines this as char buffer[100] which SIP cannot handle
+     * automatically.
+     */
+    char *buffer;
+%GetCode
+        sipPy = PyString_FromStringAndSize(sipCpp -> buffer, 100);
+%End
+%SetCode
+        char *ptr;
+        int length;
+
+        if (PyString_AsStringAndSize(sipPy, &ptr, &length) == -1)
+            sipErr = 1;
+        else if (length != 100)
+        {
+            /*
+             * Raise an exception because the length isn't exactly right.
+             */
+
+            PyErr_SetString(PyExc_ValueError, "an Entity.buffer must be exactly 100 bytes");
+            sipErr = 1;
+        }
+        else
+            memcpy(sipCpp -> buffer, ptr, 100);
+%End
+}
+
+
+
+

7.20   %If

+
+%If (expression)
+    specification
+%End
+
+

where

+
+expression ::= [ored-qualifiers | range]
+
+ored-qualifiers ::= [qualifier | qualifier || ored-qualifiers]
+
+qualifier ::= [!] [feature | platform]
+
+range ::= [version] - [version]
+
+

This directive is used in conjunction with features (see %Feature), +platforms (see %Platforms) and versions (see %Timeline) to control +whether or not parts of a specification are processed or not.

+

A range of versions means all versions starting with the lower bound up to +but excluding the upper bound. If the lower bound is omitted then it is +interpreted as being before the earliest version. If the upper bound is +omitted then it is interpreted as being after the latest version.

+

For example:

+
+%Feature SUPPORT_FOO
+%Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM}
+%Timeline {V1_0 V1_1 V2_0 V3_0}
+
+%If (!SUPPORT_FOO)
+    // Process this if the SUPPORT_FOO feature is disabled.
+%End
+
+%If (POSIX_PLATFORM || MACOS_PLATFORM)
+    // Process this if either the POSIX_PLATFORM or MACOS_PLATFORM
+    // platforms are enabled.
+%End
+
+%If (V1_0 - V2_0)
+    // Process this if either V1_0 or V1_1 is enabled.
+%End
+
+%If (V2_0 - )
+    // Process this if either V2_0 or V3_0 is enabled.
+%End
+
+%If ( - )
+    // Always process this.
+%End
+
+

Note that this directive is not implemented as a preprocessor. Only the +following parts of a specification are affected by it:

+
+ +
+

Also note that the only way to specify the logical and of qualifiers is to use +nested %If directives.

+
+
+

7.21   %Import

+
+%Import filename
+
+

This directive is used to import the specification of another module. This is +needed if the current module makes use of any types defined in the imported +module, e.g. as an argument to a function, or to sub-class.

+

If filename cannot be opened then SIP prepends filename with the name of +the directory containing the current specification file (i.e. the one +containing the %Import directive) and tries again. If this also fails then +SIP prepends filename with each of the directories, in turn, specified by +the -I command line option.

+

For example:

+
+%Import qt/qtmod.sip
+
+
+
+

7.22   %Include

+
+%Include filename
+
+

This directive is used to include contents of another file as part of the +specification of the current module. It is the equivalent of the C +preprocessor's #include directive and is used to structure a large module +specification into manageable pieces.

+

%Include follows the same search process as %Import when trying to open +filename.

+

For example:

+
+%Include qwidget.sip
+
+
+
+

7.23   %License

+
+%License /license-annotations/
+
+

This directive is used to specify the contents of an optional license +dictionary. The license dictionary is called __license__ and is stored in +the module dictionary. The elements of the dictionary are specified using the +Licensee, Signature, Timestamp and Type annotations. Only the Type +annotation is compulsory.

+

Note that this directive isn't an attempt to impose any licensing restrictions +on a module. It is simply a method for easily embedding licensing information +in a module so that it is accessible to Python scripts.

+

For example:

+
+%License /Type="GPL"/
+
+
+
+

7.24   %MappedType

+
+template<type-list>
+%MappedType type
+{
+    [header-code]
+    [convert-to-code]
+    [convert-from-code]
+};
+
+%MappedType type
+{
+    [header-code]
+    [convert-to-code]
+    [convert-from-code]
+};
+
+

This directive is used to define an automatic mapping between a C or C++ type +and a Python type. It can be used as part of a template, or to map a specific +type.

+

When used as part of a template type cannot itself refer to a template. Any +occurrences of any of the type names (but not any * or &) in +type-list will be replaced by the actual type names used when the template is +instantiated. Template mapped types are instantiated automatically as required +(unlike template classes which are only instantiated using typedef).

+

Any explicit mapped type will be used in preference to any template that maps +the same type, ie. a template will not be automatically instantiated if there +is an explicit mapped type.

+

header-code is the %TypeHeaderCode used to specify the library interface +to the type being mapped.

+

convert-to-code is the %ConvertToTypeCode used to specify the handwritten +code that converts a Python object to an instance of the mapped type.

+

convert-from-code is the %ConvertFromTypeCode used to specify the +handwritten code that converts an instance of the mapped type to a Python +object.

+

For example:

+
+template<Type *>
+%MappedType QList
+{
+%TypeHeaderCode
+// Include the library interface to the type being mapped.
+#include <qlist.h>
+%End
+
+%ConvertToTypeCode
+    // See if we are just being asked to check the type of the Python
+    // object.
+    if (sipIsErr == NULL)
+    {
+        // Check it is a list.
+        if (!PyList_Check(sipPy))
+            return 0;
+
+        // Now check each element of the list is of the type we expect.
+        // The template is for a pointer type so we don't disallow None.
+        for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+            if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i),
+                                         sipClass_Type, 0))
+                return 0;
+
+        return 1;
+    }
+
+    // Create the instance on the heap.
+    QList<Type *> *ql = new QList<Type *>;
+
+    for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
+    {
+        // Use the SIP API to convert the Python object to the
+        // corresponding C++ instance.  Note that we apply any ownership
+        // transfer to the list itself, not the individual elements.
+        Type *t = reinterpret_cast<Type *>(sipConvertToInstance(
+                                            PyList_GET_ITEM(sipPy, i),
+                                            sipClass_Type, 0, 0, 0,
+                                            sipIsErr));
+
+        if (*sipIsErr)
+        {
+            // Tidy up.
+            delete ql;
+
+            // There is nothing on the heap.
+            return 0;
+        }
+
+        // Add the pointer to the C++ instance.
+        ql -> append(t);
+    }
+
+    // Return the instance on the heap.
+    *sipCppPtr = ql;
+
+    // Apply the normal transfer.
+    return sipGetState(sipTransferObj);
+%End
+
+%ConvertFromTypeCode
+    PyObject *l;
+
+    // Create the Python list of the correct length.
+    if ((l = PyList_New(sipCpp -> size())) == NULL)
+        return NULL;
+
+    // Go through each element in the C++ instance and convert it to the
+    // corresponding Python object.
+    for (int i = 0; i < sipCpp -> size(); ++i)
+    {
+        Type *t = sipCpp -> at(i);
+        PyObject *tobj;
+
+        if ((tobj = sipConvertFromInstance(t, sipClass_Type, sipTransferObj)) == NULL)
+        {
+            // There was an error so garbage collect the Python list.
+            Py_DECREF(l);
+            return NULL;
+        }
+
+        PyList_SET_ITEM(l, i, tobj);
+    }
+
+    // Return the Python list.
+    return l;
+%End
+}
+
+

Using this we can use, for example, QList<QObject *> throughout the +module's specification files (and in any module that imports this one). The +generated code will automatically map this to and from a Python list of QObject +instances when appropriate.

+
+
+

7.25   %MethodCode

+
+%MethodCode
+    code
+%End
+
+

This directive is used as part of the specification of a global function, class +method, operator, constructor or destructor to specify handwritten code that +replaces the normally generated call to the function being wrapped. It is +usually used to handle argument types and results that SIP cannot deal with +automatically.

+

The specified code is embedded in-line after the function's arguments have +been successfully converted from Python objects to their C or C++ equivalents. +The specified code must not include any return statements.

+

In the context of a destructor the specified code is embedded in-line in the +Python type's deallocation function. Unlike other contexts it supplements +rather than replaces the normally generated code, so it must not include code +to return the C structure or C++ class instance to the heap. The code is only +called if ownership of the structure or class is with Python.

+

The specified code must also handle the Python Global Interpreter Lock (GIL). +If compatibility with SIP v3.x is required then the GIL must be released +immediately before the C++ call and reacquired immediately afterwards as shown +in this example fragment:

+
+Py_BEGIN_ALLOW_THREADS
+sipCpp -> foo();
+Py_END_ALLOW_THREADS
+
+

If compatibility with SIP v3.x is not required then this is optional but +should be done if the C++ function might block the current thread or take a +significant amount of time to execute. (See The Python Global Interpreter +Lock and the ReleaseGIL and HoldGIL annotations.)

+

The following variables are made available to the handwritten code:

+
+
type a0
+

There is a variable for each argument of the Python signature (excluding +any self argument) named a0, a1, etc. The type of the +variable is the same as the type defined in the specification with the +following exceptions:

+
    +
  • if the argument is only used to return a value (e.g. it is an int * +without an In annotation) then the type has one less level of +indirection (e.g. it will be an int)
    • +
  • if the argument is a structure or class (or a reference or a pointer to a +structure or class) then type will always be a pointer to the structure +or class.
    • +
+

Note that handwritten code for destructors never has any arguments.

+
+
PyObject *a0Wrapper
+
This variable is made available only if the corresponding argument wraps a +C structure or C++ class instance and the GetWrapper annotation is +specified. The variable is a pointer to the Python object that wraps the +argument.
+
type *sipCpp
+
If the directive is used in the context of a class constructor then this +must be set by the handwritten code to the constructed instance. In any +other context then this is a pointer to the C structure or C++ class +instance. Its type is a pointer to the structure or class.
+
int sipIsErr
+

The handwritten code should set this to a non-zero value, and raise an +appropriate Python exception, if an error is detected.

+

sipIsErr is not provided for destructors.

+
+
type sipRes
+

The handwritten code should set this to the result to be returned. The +type of the variable is the same as the type defined in the Python +signature in the specification with the following exception:

+
    +
  • if the argument is a structure or class (or a reference or a pointer to a +structure or class) then type will always be a pointer to the structure +or class.
    • +
+

sipRes is not provided for inplace operators (e.g. += or +__imul__) as their results are handled automatically, nor for class +constructors.

+
+
PyObject *sipSelf
+
If the directive is used in the context of a class constructor or method +then this is the Python object that wraps the the structure or class +instance, i.e. self.
+
bool sipSelfWasArg
+

This is only made available for non-abstract, virtual methods. It is set +if self was explicitly passed as the first argument of the method +rather than being bound to the method. In other words, the call was:

+
+Klass.foo(self, ...)
+
+

rather than:

+
+self.foo(...)
+
+
+
+

The following is a complete example:

+
+class Klass
+{
+public:
+    virtual int foo(SIP_PYTUPLE);
+%MethodCode
+        // The C++ API takes a 2 element array of integers but passing a
+        // two element tuple is more Pythonic.
+
+        int iarr[2];
+
+        if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1]))
+        {
+            Py_BEGIN_ALLOW_THREADS
+            sipRes = sipSelfWasArg ? sipCpp -> Klass::foo(iarr)
+                                   : sipCpp -> foo(iarr);
+            Py_END_ALLOW_THREADS
+        }
+        else
+        {
+            // PyArg_ParseTuple() will have raised the exception.
+            sipIsErr = 1;
+        }
+%End
+};
+
+

As the example is a virtual method [7], note the use of sipSelfWasArg to +determine exactly which implementation of foo() to call.

+

If a method is in the protected section of a C++ class then the call +should instead be:

+
+sipRes = sipCpp -> sipProtectVirt_foo(sipSelfWasArg, iarr);
+
+

If a method is in the protected section of a C++ class but is not virtual +then the call should instead be:

+
+sipRes = sipCpp -> sipProtect_foo(iarr);
+
+ + + + + +
[7]See %VirtualCatcherCode for a description of how SIP generated code +handles the reimplementation of C++ virtual methods in Python.
+
+
+

7.26   %Module

+
+%Module name [version]
+
+

This directive is used to identify that the library being wrapped is a C++ +library and to define the name of the module and it's optional version number.

+

The name may contain periods to specify that the module is part of a Python +package.

+

The optional version number is useful if you (or others) might create other +modules that build on this module, i.e. if another module might %Import +this module. Under the covers, a module exports an API that is used by modules +that %Import it and the API is given a version number. A module built on +that module knows the version number of the API that it is expecting. If, +when the modules are imported at run-time, the version numbers do not match +then a Python exception is raised. The dependent module must then be re-built +using the correct specification files for the base module.

+

The version number should be incremented whenever a module is changed. Some +changes don't affect the exported API, but it is good practice to change the +version number anyway.

+

For example:

+
+%Module qt 5
+
+
+
+

7.27   %ModuleCode

+
+%ModuleCode
+    code
+%End
+
+

This directive is used to specify handwritten code, typically the +implementations of utility functions, that can be called by other handwritten +code in the module.

+

For example:

+
+%ModuleCode
+// Print an object on stderr for debugging purposes.
+void dump_object(PyObject *o)
+{
+    PyObject_Print(o, stderr, 0);
+    fprintf(stderr, "\n");
+}
+%End
+
+

See also %ExportedHeaderCode and %ModuleHeaderCode.

+
+
+

7.28   %ModuleHeaderCode

+
+%ModuleHeaderCode
+    code
+%End
+
+

This directive is used to specify handwritten code, typically the declarations +of utility functions, that is placed in a header file that is included by all +generated code for the same module.

+

For example:

+
+%ModuleHeaderCode
+void dump_object(PyObject *o);
+%End
+
+

See also %ExportedHeaderCode and %ModuleCode.

+
+
+

7.29   %OptionalInclude

+
+%OptionalInclude filename
+
+

This directive is identical to the %Include directive except that SIP +silently continues processing if filename could not be opened.

+

For example:

+
+%OptionalInclude license.sip
+
+
+
+

7.30   %Platforms

+
+%Platforms {name name ...}
+
+

This directive is used to declare a set of platforms. Platforms (along with +%Feature and %Timeline) are used by the %If directive to control +whether or not parts of a specification are processed or ignored.

+

Platforms are mutually exclusive - only one platform can be enabled at a time. +By default all platforms are disabled. The SIP -t command line option is +used to enable a platform.

+

For example:

+
+%Platforms {WIN32_PLATFORM POSIX_PLATFORM MACOS_PLATFORM}
+
+%If (WIN32_PLATFORM)
+void undocumented();
+%End
+
+%If (POSIX_PLATFORM)
+void documented();
+%End
+
+
+
+

7.31   %PostInitialisationCode

+
+%PostInitialisationCode
+    code
+%End
+
+

This directive is used to specify handwritten code that is embedded in-line +at the very end of the generated module initialisation code.

+

The following variables are made available to the handwritten code:

+
+
PyObject *sipModule
+
This is the module object returned by Py_InitModule().
+
PyObject *sipModuleDict
+
This is the module's dictionary object returned by Py_ModuleGetDict().
+
+

For example:

+
+%PostInitialisationCode
+    // The code will be executed when the module is first imported and
+    // after all other initialisation has been completed.
+%End
+
+
+
+

7.32   %PreInitialisationCode

+
+%PreInitialisationCode
+    code
+%End
+
+

This directive is used to specify handwritten code that is embedded in-line +at the very start of the generated module initialisation code.

+

For example:

+
+%PreInitialisationCode
+    // The code will be executed when the module is first imported and
+    // before other initialisation has been completed.
+%End
+
+
+
+

7.33   %RaiseCode

+
+%RaiseCode
+    code
+%End
+
+

This directive is used as part of the definition of an exception using the +%Exception directive to specify handwritten code that raises a Python +exception when a C++ exception has been caught. The code is embedded in-line +as the body of a C++ catch () clause.

+

The specified code must handle the Python Global Interpreter Lock (GIL) if +necessary. The GIL must be acquired before any calls to the Python API and +released after the last call as shown in this example fragment:

+
+SIP_BLOCK_THREADS
+PyErr_SetNone(PyErr_Exception);
+SIP_UNBLOCK_THREADS
+
+

Finally, the specified code must not include any return statements.

+

The following variable is made available to the handwritten code:

+
+
type &sipExceptionRef
+
This is a reference to the caught C++ exception. The type of the +reference is the same as the type defined in the throw () specifier.
+
+

See the %Exception directive for an example.

+
+
+

7.34   %SetCode

+
+%SetCode
+    code
+%End
+
+

This directive is used after the declaration of a C++ class variable or C +structure member to specify handwritten code to convert it from a Python +object. It is usually used to handle types that SIP cannot deal with +automatically.

+

The following variables are made available to the handwritten code:

+
+
type *sipCpp
+
This is a pointer to the structure or class instance. Its type is a +pointer to the structure or class. It is not made available if the +variable being wrapped is a static class variable.
+
int sipErr
+
If the conversion failed then the handwritten code should raise a Python +exception and set this to a non-zero value. Its initial value will be +automatically set to zero.
+
PyObject *sipPy
+
This is the Python object that the handwritten code should convert.
+
+

See the %GetCode directive for an example.

+
+
+

7.35   %SIPOptions

+

This directive sets one or more options that controls different aspects of +SIP's behaviour. In this version all the available options are provided +specifically to support PyQt and so are not documented.

+
+
+

7.36   %Timeline

+
+%Timeline {name name ...}
+
+

This directive is used to declare a set of versions released over a period of +time. Versions (along with %Feature and %Platforms) are used by the +%If directive to control whether or not parts of a specification are +processed or ignored.

+

Versions are mutually exclusive - only one version can be enabled at a time. +By default all versions are disabled. The SIP -t command line option is +used to enable a version.

+

For example:

+
+%Timeline {V1_0 V1_1 V2_0 V3_0}
+
+%If (V1_0 - V2_0)
+void foo();
+%End
+
+%If (V2_0 -)
+void foo(int = 0);
+%End
+
+

%Timeline can be used any number of times in a module to allow multiple +libraries to be wrapped in the same module.

+
+
+

7.37   %TypeCode

+
+%TypeCode
+    code
+%End
+
+

This directive is used as part of the specification of a C structure or a C++ +class to specify handwritten code, typically the implementations of utility +functions, that can be called by other handwritten code in the structure or +class.

+

For example:

+
+class Klass
+{
+%TypeCode
+// Print an instance on stderr for debugging purposes.
+static void dump_klass(const Klass *k)
+{
+    fprintf(stderr,"Klass %s at %p\n", k -> name(), k);
+}
+%End
+
+    // The rest of the class specification.
+
+};
+
+

Because the scope of the code is normally within the generated file that +implements the type, any utility functions would normally be declared +static. However a naming convention should still be adopted to prevent +clashes of function names within a module in case the SIP -j command line +option is used.

+
+
+

7.38   %TypeHeaderCode

+
+%TypeHeaderCode
+    code
+%End
+
+

This directive is used to specify handwritten code that defines the interface +to a C or C++ type being wrapped, either a structure, a class, or a template. +It is used within a class definition or a %MappedType directive.

+

Normally code will be a pre-processor #include statement.

+

For example:

+
+// Wrap the Klass class.
+class Klass
+{
+%TypeHeaderCode
+#include <klass.h>
+%End
+
+    // The rest of the class specification.
+};
+
+
+
+

7.39   %UnitCode

+
+%UnitCode
+    code
+%End
+
+

This directive is used to specify handwritten code that it included at the very +start of a generated compilation unit (ie. C or C++ source file). It is +typically used to #include a C++ precompiled header file.

+
+
+

7.40   %VirtualCatcherCode

+
+%VirtualCatcherCode
+    code
+%End
+
+

For most classes there are corresponding generated derived classes that +contain reimplementations of the class's virtual methods. These methods (which +SIP calls catchers) determine if there is a corresponding Python +reimplementation and call it if so. If there is no Python reimplementation +then the method in the original class is called instead.

+

This directive is used to specify handwritten code that replaces the normally +generated call to the Python reimplementation and the handling of any returned +results. It is usually used to handle argument types and results that SIP +cannot deal with automatically.

+

This directive can also be used in the context of a class destructor to +specify handwritten code that is embedded in-line in the internal derived +class's destructor.

+

In the context of a method the Python Global Interpreter Lock (GIL) is +automatically acquired before the specified code is executed and automatically +released afterwards.

+

In the context of a destructor the specified code must handle the GIL. The +GIL must be acquired before any calls to the Python API and released after the +last call as shown in this example fragment:

+
+SIP_BLOCK_THREADS
+Py_DECREF(obj);
+SIP_UNBLOCK_THREADS
+
+

The following variables are made available to the handwritten code in the +context of a method:

+
+
type a0
+
There is a variable for each argument of the C++ signature named a0, +a1, etc. The type of the variable is the same as the type defined in +the specification.
+
int sipIsErr
+
The handwritten code should set this to a non-zero value, and raise an +appropriate Python exception, if an error is detected.
+
PyObject *sipMethod
+
This object is the Python reimplementation of the virtual C++ method. It +is normally passed to sipCallMethod().
+
type sipRes
+
The handwritten code should set this to the result to be returned. The +type of the variable is the same as the type defined in the C++ signature +in the specification.
+
+

No variables are made available in the context of a destructor.

+

For example:

+
+class Klass
+{
+public:
+    virtual int foo(SIP_PYTUPLE) [int (int *)];
+%MethodCode
+        // The C++ API takes a 2 element array of integers but passing a
+        // two element tuple is more Pythonic.
+
+        int iarr[2];
+
+        if (PyArg_ParseTuple(a0, "ii", &iarr[0], &iarr[1]))
+        {
+            Py_BEGIN_ALLOW_THREADS
+            sipRes = sipCpp -> Klass::foo(iarr);
+            Py_END_ALLOW_THREADS
+        }
+        else
+        {
+            // PyArg_ParseTuple() will have raised the exception.
+            sipIsErr = 1;
+        }
+%End
+%VirtualCatcherCode
+        // Convert the 2 element array of integers to the two element
+        // tuple.
+
+        PyObject *result;
+
+        result = sipCallMethod(&sipIsErr, sipMethod, "ii", a0[0], a0[1]);
+
+        if (result != NULL)
+        {
+            // Convert the result to the C++ type.
+            sipParseResult(&sipIsErr, sipMethod, result, "i", &sipRes);
+
+            Py_DECREF(result);
+        }
+%End
+};
+
+
+
+
+

8   SIP Annotations

+

In this section we describe each of the annotations that can be used in +specification files.

+

Annotations can either be argument annotations, class annotations, enum +annotations, exception annotations, function annotations, license annotations, +or variable annotations depending on the context in which they can be used.

+

Annotations are placed between forward slashes (/). Multiple annotations +are comma separated within the slashes.

+

Annotations have a type and, possibly, a value. The type determines the +format of the value. The name of an annotation and its value are separated by +=.

+

Annotations can have one of the following types:

+
+
boolean
+
This type of annotation has no value and is implicitly true.
+
name
+
The value is a name that is compatible with a C/C++ identifier. In some +cases the value is optional.
+
string
+
The value is a double quoted string.
+
+

The following example shows argument and function annotations:

+
+void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;
+
+

Note that the current version of SIP does not complain about unknown +annotations, or annotations used out of their correct context.

+
+

8.1   Argument Annotations

+
+

8.1.1   AllowNone

+

This boolean annotation specifies that the value of the corresponding argument +(which should be either SIP_PYCALLABLE, SIP_PYDICT, SIP_PYLIST, +SIP_PYSLICE, SIP_PYTUPLE or SIP_PYTYPE) may be None.

+
+
+

8.1.2   Array

+

This boolean annotation specifies that the corresponding argument (which +should be either char * or unsigned char *) refers to an array +rather than a '\0' terminated string. There must be a corresponding +argument with the ArraySize annotation specified. The annotation may only be +specified once in a list of arguments.

+
+
+

8.1.3   ArraySize

+

This boolean annotation specifies that the corresponding argument (which +should be either short, unsigned short, int, unsigned, +long or unsigned long) refers to the size of an array. There must be +a corresponding argument with the Array annotation specified. The annotation +may only be specified once in a list of arguments.

+
+
+

8.1.4   Constrained

+

Python will automatically convert between certain compatible types. For +example, if a floating pointer number is expected and an integer supplied, +then the integer will be converted appropriately. This can cause problems +when wrapping C or C++ functions with similar signatures. For example:

+
+// The wrapper for this function will also accept an integer argument
+// which Python will automatically convert to a floating point number.
+void foo(double);
+
+// The wrapper for this function will never get used.
+void foo(int);
+
+

This boolean annotation specifies that the corresponding argument (which +should be either bool, int, float, double or a wrapped class) +must match the type without any automatic conversions. In the context of a +wrapped class the invocation of any %ConvertToTypeCode is suppressed.

+

The following example gets around the above problem:

+
+// The wrapper for this function will only accept floating point numbers.
+void foo(double /Constrained/);
+
+// The wrapper for this function will be used for anything that Python can
+// convert to an integer, except for floating point numbers.
+void foo(int);
+
+
+
+

8.1.5   GetWrapper

+

This boolean annotation is only ever used in conjunction with handwritten code +specified with the %MethodCode directive. It causes an extra variable to +be generated for the corresponding argument (which should be a wrapped C +structure or C++ class instance) which is a pointer to the Python object that +wraps the argument.

+

See the %MethodCode directive for more detail.

+
+
+

8.1.6   In

+

This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used to pass a value to the function.

+

For pointers to wrapped C structures or C++ class instances, char * and +unsigned char * then this annotation is assumed unless the Out annotation +is specified.

+

For pointers to other types then this annotation must be explicitly specified +if required. The argument will be dereferenced to obtain the actual value.

+

Both In and Out may be specified for the same argument.

+
+
+

8.1.7   Out

+

This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used by the function to return a value as +an element of a tuple.

+

For pointers to wrapped C structures or C++ class instances, char * and +unsigned char * then this annotation must be explicitly specified if +required.

+

For pointers to other types then this annotation is assumed unless the In +annotation is specified.

+

Both In and Out may be specified for the same argument.

+
+
+

8.1.8   Transfer

+

This boolean annotation is used to specify that ownership of the corresponding +argument (which should be a wrapped C structure or C++ class instance) is +transferred from Python to C++. In addition, if the argument is of a class +method, then it is associated with the class instance with regard to the +cyclic garbage collector.

+

See Ownership of Objects for more detail.

+
+
+

8.1.9   TransferBack

+

This boolean annotation is used to specify that ownership of the corresponding +argument (which should be a wrapped C structure or C++ class instance) is +transferred back to Python from C++. In addition, any association of the +argument with regard to the cyclic garbage collector with another instance is +removed.

+

Note that this can also be used as a function annotation.

+

See Ownership of Objects for more detail.

+
+
+

8.1.10   TransferThis

+

This boolean annotation is only used in C++ constructors or methods. In the +context of a constructor or factory method it specifies that ownership of the +instance being created is transferred from Python to C++ if the corresponding +argument (which should be a wrapped C structure or C++ class instance) is not +None. In addition, the newly created instance is associated with the +argument with regard to the cyclic garbage collector.

+

In the context of a non-factory method it specifies that ownership of this +is transferred from Python to C++ if the corresponding argument is not +None. If it is None then ownership is transferred to Python.

+

The annotation may be used more that once, in which case ownership is +transferred to last instance that is not None.

+

See Ownership of Objects for more detail.

+
+
+
+

8.2   Class Annotations

+
+

8.2.1   Abstract

+

This boolean annotation is used to specify that the class has additional pure +virtual methods that have not been specified and so it cannot be instantiated +or sub-classed from Python.

+
+
+

8.2.2   DelayDtor

+

This boolean annotation is used to specify that the class's destructor should +not be called until the Python interpreter exits. It would normally only be +applied to singleton classes.

+

When the Python interpreter exits the order in which any wrapped instances are +garbage collected is unpredictable. However, the underlying C or C++ instances +may need to be destroyed in a certain order. If this annotation is specified +then when the wrapped instance is garbage collected the C or C++ instance is +not destroyed but instead added to a list of delayed instances. When the +interpreter exits then the function sipDelayedDtors is called with the +list of delayed instances. sipDelayedDtors can then choose to call (or +ignore) the destructors in any desired order.

+

The sipDelayedDtors function must be specified using the %ModuleCode +directive. It's signature is as follows:

+
+static void sipDelayedDtors(const sipDelayedDtor *dd_list);
+
+

dd_list is the linked list of delayed instances. The following fields are +defined.

+
+
const char *dd_name
+
This is the name of the class excluding any package or module name.
+
void *dd_ptr
+
This is the address of the C or C++ instance to be destroyed. It's exact +type depends on the value of dd_isderived.
+
int dd_isderived
+
This is non-zero if the type of dd_ptr is actually the generated +derived class. This allows the correct destructor to be called. See +Generated Derived Classes.
+
sipDelayedDtor *dd_next
+
This is the address of the next entry in the list or zero if this is the +last one.
+
+

Note that the above applies only to C and C++ instances that are owned by +Python.

+
+
+

8.2.3   External

+

This boolean annotation is used to specify that the class is defined in another +module. Declarations of external classes are private to the module in which +they appear.

+
+
+

8.2.4   NoDefaultCtors

+

This boolean annotation is used to suppress the automatic generation of default +constructors for the class.

+
+
+

8.2.5   PyName

+

This name annotation specifies an alternative name for the class being wrapped +which is used when it is referred to from Python. It is required when a class +name is the same as a Python keyword. It may also be used to avoid name +clashes with other objects (e.g. enums, exceptions, functions) that have the +same name in the same C++ scope.

+
+
+
+

8.3   Enum Annotations

+
+

8.3.1   PyName

+

This name annotation specifies an alternative name for the enum or enum member +being wrapped which is used when it is referred to from Python. It is required +when an enum or enum member name is the same as a Python keyword. It may also +be used to avoid name clashes with other objects (e.g. classes, exceptions, +functions) that have the same name in the same C++ scope.

+
+
+
+

8.4   Exception Annotations

+
+

8.4.1   PyName

+

This name annotation specifies an alternative name for the exception being +defined which is used when it is referred to from Python. It is required when +an exception name is the same as a Python keyword. It may also be used to +avoid name clashes with other objects (e.g. classes, enums, functions) that +have the same name.

+
+
+
+

8.5   Function Annotations

+
+

8.5.1   AutoGen

+

This optional name annotation is used with class methods to specify that the +method be automatically included in all sub-classes. The value is the name of +a feature (specified using the %Feature directive) which must be enabled +for the method to be generated.

+
+
+

8.5.2   Default

+

This boolean annotation is only used with C++ constructors. Sometimes SIP +needs to create a class instance. By default it uses a constructor with no +compulsory arguments if one is specified. (SIP will automatically generate a +constructor with no arguments if no constructors are specified.) This +annotation is used to explicitly specify which constructor to use. Zero is +passed as the value of any arguments to the constructor.

+
+
+

8.5.3   Factory

+

This boolean annotation specifies that the value returned by the function +(which should be a wrapped C structure or C++ class instance) is a newly +created instance and is owned by Python.

+

See Ownership of Objects for more detail.

+
+
+

8.5.4   HoldGIL

+

This boolean annotation specifies that the Python Global Interpreter Lock (GIL) +is not released before the call to the underlying C or C++ function. See +The Python Global Interpreter Lock and the ReleaseGIL annotation.

+
+
+

8.5.5   NewThread

+

This boolean annotation specifies that the function will create a new thread.

+
+
+

8.5.6   NoDerived

+

This boolean annotation is only used with C++ constructors. In many cases SIP +generates a derived class for each class being wrapped (see Generated Derived +Classes). This derived class contains constructors with the same C++ +signatures as the class being wrapped. Sometimes you may want to define a +Python constructor that has no corresponding C++ constructor. This annotation +is used to suppress the generation of the constructor in the derived class.

+
+
+

8.5.7   Numeric

+

This boolean annotation specifies that the operator should be interpreted as a +numeric operator rather than a sequence operator. Python uses the + +operator for adding numbers and concatanating sequences, and the * operator +for multiplying numbers and repeating sequences. SIP tries to work out which +is meant by looking at other operators that have been defined for the type. +If it finds either -, -=, /, /=, % or %= defined then +it assumes that +, +=, * and *= should be numeric operators. +Otherwise, if it finds either [], __getitem__(), __setitem__() or +__delitem__() defined then it assumes that they should be sequence +operators. This annotation is used to force SIP to treat the operator as +numeric.

+
+
+

8.5.8   PostHook

+

This name annotation is used to specify the name of a Python builtin that is +called immediately after the call to the underlying C or C++ function or any +handwritten code. The builtin is not called if an error occurred. It is +primarily used to integrate with debuggers.

+
+
+

8.5.9   PreHook

+

This name annotation is used to specify the name of a Python builtin that is +called immediately after the function's arguments have been successfully +parsed and before the call to the underlying C or C++ function or any +handwritten code. It is primarily used to integrate with debuggers.

+
+
+

8.5.10   PyName

+

This name annotation specifies an alternative name for the function being +wrapped which is used when it is referred to from Python. It is required when +a function or method name is the same as a Python keyword. It may also be used +to avoid name clashes with other objects (e.g. classes, enums, exceptions) that +have the same name in the same C++ scope.

+
+
+

8.5.11   ReleaseGIL

+

This boolean annotation specifies that the Python Global Interpreter Lock (GIL) +is released before the call to the underlying C or C++ function and reacquired +afterwards. It should be used for functions that might block or take a +significant amount of time to execute. See The Python Global Interpreter +Lock and the HoldGIL annotation.

+
+
+

8.5.12   TransferBack

+

This boolean annotation specifies that ownership of the value returned by the +function (which should be a wrapped C structure or C++ class instance) is +transferred back to Python from C++. Normally returned values (unless they are +new references to already wrapped values) are owned by C++. In addition, any +association of the returned value with regard to the cyclic garbage collector +with another instance is removed.

+

Note that this can also be used as an argument annotation.

+

See Ownership of Objects for more detail.

+
+
+
+

8.6   License Annotations

+
+

8.6.1   Licensee

+

This optional string annotation specifies the license's licensee. No +restrictions are placed on the contents of the string.

+

See the %License directive.

+
+
+

8.6.2   Signature

+

This optional string annotation specifies the license's signature. No +restrictions are placed on the contents of the string.

+

See the %License directive.

+
+
+

8.6.3   Timestamp

+

This optional string annotation specifies the license's timestamp. No +restrictions are placed on the contents of the string.

+

See the %License directive.

+
+
+

8.6.4   Type

+

This string annotation specifies the license's type. No restrictions are +placed on the contents of the string.

+

See the %License directive.

+
+
+
+

8.7   Variable Annotations

+
+

8.7.1   PyName

+

This name annotation specifies an alternative name for the variable being +wrapped which is used when it is referred to from Python. It is required when +a variable name is the same as a Python keyword. It may also be used to avoid +name clashes with other objects (e.g. classes, functions) that have the same +name in the same C++ scope.

+
+
+
+
+

9   SIP API for Handwritten Code

+

In this section we describe the API that can be used by handwritten code in +specification files.

+
+

9.1   SIP_API_MAJOR_NR

+

This is a C preprocessor symbol that defines the major number of the SIP API. +Its value is a number. There is no direct relationship between this and the +SIP version number.

+
+
+

9.2   SIP_API_MINOR_NR

+

This is a C preprocessor symbol that defines the minor number of the SIP API. +Its value is a number. There is no direct relationship between this and the +SIP version number.

+
+
+

9.3   SIP_BLOCK_THREADS

+

This is a C preprocessor macro that will make sure the Python Global +Interpreter Lock (GIL) is acquired. Python API calls must only be made when +the GIL has been acquired. There must be a corresponding +SIP_UNBLOCK_THREADS at the same lexical scope.

+
+
+

9.4   SIP_SSIZE_T

+

This is a C preprocessor macro that is defined as Py_ssize_t for Python +v2.5 and later, and as int for earlier versions of Python. It makes it +easier to write PEP 353 compliant handwritten code.

+
+
+

9.5   SIP_UNBLOCK_THREADS

+

This is a C preprocessor macro that will restore the Python Global Interpreter +Lock (GIL) to the state it was prior to the corresponding SIP_BLOCK_THREADS.

+
+
+

9.6   SIP_VERSION

+

This is a C preprocessor symbol that defines the SIP version number +represented as a 3 part hexadecimal number (e.g. v4.0.0 is represented as +0x040000).

+
+
+

9.7   SIP_VERSION_STR

+

This is a C preprocessor symbol that defines the SIP version number +represented as a string. For development snapshots it will start with +snapshot-.

+
+
+

9.8   sipBadCatcherResult()

+
+
void sipBadCatcherResult(PyObject *method)
+
This raises a Python exception when the result of a Python reimplementation +of a C++ method doesn't have the expected type. It is normally called by +handwritten code specified with the %VirtualCatcherCode directive. +method is the Python method and would normally be the supplied +sipMethod.
+
+
+
+

9.9   sipBadLengthForSlice()

+
+
void sipBadLengthForSlice(SIP_SSIZE_T seqlen, SIP_SSIZE_T slicelen)
+
This raises a Python exception when the length of a slice object is +inappropriate for a sequence-like object. It is normally called by +handwritten code specified for __setitem__() methods. seqlen is the +length of the sequence. slicelen is the length of the slice. With +versions of Python prior to v2.5 the arguments have type int.
+
+
+
+

9.10   sipBuildResult()

+
+
PyObject *sipBuildResult(int *iserr, const char *format, ...)
+

This creates a Python object based on a format string and associated +values in a similar way to the Python Py_BuildValue() function. If +there was an error then NULL is returned and a Python exception is +raised. If iserr is not NULL then the location it points to is set +to a non-zero value. format is the string of format characters.

+

If format begins and ends with parentheses then a tuple of objects is +created. If format contains more than one format character then +parentheses must be specified.

+

In the following description the first letter is the format character, the +entry in parentheses is the Python object type that the format character +will create, and the entry in brackets are the types of the C/C++ values +to be passed.

+
+
a (string) [char *, int]
+
Convert a C/C++ character array and its length to a Python string. If +the array is NULL then the length is ignored and the result is +Py_None.
+
b (boolean) [int]
+
Convert a C/C++ int to a Python boolean.
+
c (string) [char]
+
Convert a C/C++ char to a Python string.
+
d (float) [double]
+
Convert a C/C++ double to a Python floating point number.
+
e (integer) [enum]
+
Convert an anonymous C/C++ enum to a Python integer.
+
f (float) [float]
+
Convert a C/C++ float to a Python floating point number.
+
h (integer) [short]
+
Convert a C/C++ short to a Python integer.
+
i (integer) [int]
+
Convert a C/C++ int to a Python integer.
+
l (long) [long]
+
Convert a C/C++ long to a Python integer.
+
m (long) [unsigned long]
+
Convert a C/C++ unsigned long to a Python long.
+
n (long) [long long]
+
Convert a C/C++ long long to a Python long.
+
o (long) [unsigned long long]
+
Convert a C/C++ unsigned long long to a Python long.
+
s (string) [char *]
+
Convert a C/C++ '\0' terminated string to a Python string. If the +string pointer is NULL then the result is Py_None.
+
t (long) [unsigned short]
+
Convert a C/C++ unsigned short to a Python long.
+
u (long) [unsigned int]
+
Convert a C/C++ unsigned int to a Python long.
+
w (unicode) [wchar_t]
+
Convert a C/C++ wide character to a Python unicode object.
+
x (unicode) [wchar_t *]
+
Convert a C/C++ L'\0' terminated wide character string to a Python +unicode object. If the string pointer is NULL then the result is +Py_None.
+
A (unicode) [wchar_t *, int]
+
Convert a C/C++ wide character array and its length to a Python unicode +object. If the array is NULL then the length is ignored and the +result is Py_None.
+
B (wrapped instance) [type *, sipWrapperType *, PyObject *]
+
Convert a new C structure or a new C++ class instance to a Python class +instance object. Ownership of the structure or instance is determined +by the PyObject * argument. If it is NULL and the instance has +already been wrapped then the ownership is unchanged. If it is +NULL or Py_None then ownership will be with Python. Otherwise +ownership will be with C/C++ and the instance associated with the +PyObject * argument. The Python class is influenced by any +applicable %ConvertToSubClassCode code.
+
C (wrapped instance) [type *, sipWrapperType *, PyObject *]
+
Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. Ownership of the structure or instance is determined +by the PyObject * argument. If it is NULL and the instance has +already been wrapped then the ownership is unchanged. If it is +NULL and the instance is newly wrapped then ownership will be with +C/C++. If it is Py_None then ownership is transferred to Python +via a call to sipTransferBack(). Otherwise ownership is transferred +to C/C++ and the instance associated with the PyObject * argument +via a call to sipTransferTo(). The Python class is influenced by +any applicable %ConvertToSubClassCode code.
+
D (object) [type *, const sipMappedType *, PyObject *]
+
Convert a C structure or a C++ class instance wrapped as a mapped type +to a Python object. Ownership of the structure or instance is +determined by the PyObject * argument. If it is NULL then the +ownership is unchanged. If it is Py_None then ownership is +transferred to Python via a call to sipTransferBack(). Otherwise +ownership is transferred to C/C++ and the instance associated with the +PyObject * argument via a call to sipTransferTo().
+
E (wrapped enum) [enum, PyTypeObject *]
+
Convert a named C/C++ enum to an instance of the corresponding +Python named enum type.
+
M (wrapped instance) [type *, sipWrapperType *]
+
Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. If the instance has already been wrapped then the +ownership is unchanged. If the instance is newly wrapped then +ownership will be with C/C++. The Python class is influenced by any +applicable %ConvertToSubClassCode code. This is deprecated from +SIP v4.4.
+
N (wrapped instance) [type *, sipWrapperType *]
+
Convert a C structure or a C++ class instance to a Python class +instance object. This should not be used if the structure or class +instance might already have been wrapped. Ownership of the structure +or instance will be with Python. The Python class is influenced by +any applicable %ConvertToSubClassCode code. This is deprecated +from SIP v4.4.
+
O (wrapped instance) [type *, sipWrapperType *]
+
Convert a C structure or a C++ class instance to a Python class +instance object. If the structure or class instance has already been +wrapped then the result is a new reference to the existing class +instance object. Ownership of the structure or instance will be with +C/C++. This is deprecated from SIP v4.4.
+
P (wrapped instance) [type *, sipWrapperType *]
+
Convert a C structure or a C++ class instance to a Python class +instance object. This should not be used if the structure or class +instance might already have been wrapped. Ownership of the structure +or instance will be with Python. This is deprecated from SIP v4.4.
+
R (object) [PyObject *]
+
The result is value passed without any conversions. The reference +count is unaffected, i.e. a reference is taken.
+
S (object) [PyObject *]
+
The result is value passed without any conversions. The reference +count is incremented.
+
T (object) [void *, PyObject *(*)(void *cppptr)]
+
Convert a C structure or a C++ class instance to a Python object using +a convertor function. See Generated Type Convertors. This is +deprecated from SIP v4.4.
+
V (sip.voidptr) [void *]
+
Convert a C/C++ void * Python sip.voidptr object.
+
+
+
+
+
+

9.11   sipCallMethod()

+
+
PyObject *sipCallMethod(int *iserr, PyObject *method, const char *format, ...)
+

This calls a Python method passing a tuple of arguments based on a format +string and associated values in a similar way to the Python +PyObject_CallObject() function. If there was an error then NULL is +returned and a Python exception is raised. If iserr is not NULL +then the location it points to is set to a non-zero value. method is the +Python bound method to call. format is the string of format characters +(see sipBuildResult()).

+

This is normally called by handwritten code specified with the +%VirtualCatcherCode directive with method being the supplied +sipMethod.

+
+
+
+
+

9.12   sipCanConvertToInstance()

+
+
int sipCanConvertToInstance(PyObject *obj, sipWrapperType *type, int flags)
+

This returns a non-zero value if a Python object can be converted to an +instance of a C structure or C++ class. obj is the Python object. +type is the generated type corresponding to the C/C++ type being checked. +flags is any combination of the following values used to fine tune the +check.

+
+
    +
  • SIP_NOT_NONE causes the check to fail if obj is None.
    • +
  • SIP_NO_CONVERTORS suppresses the use of of any +%ConvertToTypeCode for type.
    • +
+
+
+
+
+
+

9.13   sipCanConvertToMappedType()

+
+
int sipCanConvertToMappedType(PyObject *obj, const sipMappedType *mt, int flags)
+

This returns a non-zero value if a Python object can be converted to an +instance of a C structure or C++ class which has been implemented as a +mapped type. obj is the Python object. mt is an opaque structure +returned by sipFindMappedType(). flags is any combination of the +following values used to fine tune the check.

+
+
    +
  • SIP_NOT_NONE causes the check to fail if obj is None.
    • +
+
+
+
+
+
+

9.14   sipClassName()

+
+
PyObject *sipClassName(PyObject *obj)
+
This returns the class name of a wrapped instance as a Python string. It +comes with a reference.
+
+
+
+

9.15   sipConnectRx()

+
+
PyObject *sipConnectRx(PyObject *sender, const char *signal, PyObject *receiver, const char *slot, int type)
+
This connects a signal to a signal or slot and returns Py_True if the +signal was connected or Py_False if not. If there was some other +error then a Python exception is raised and NULL is returned. sender +is the wrapped QObject derived instance that emits the signal. +signal is the typed name of the signal. receiver is the wrapped +QObject derived instance or Python callable that the signal is +connected to. slot is the typed name of the slot, or NULL if +receiver is a Python callable. type is the type of connection and is +cast from Qt::ConnectionType. It is normally only used by PyQt to +implement QObject.connect().
+
+
+
+

9.16   sipConvertFromInstance()

+
+
PyObject *sipConvertFromInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)
+
Convert a C structure or a C++ class instance to a Python class instance +object. cpp is the C/C++ instance. If the instance has already been +wrapped then the result is a new reference to the existing instance object. +type is the generated type corresponding to the C/C++ type. +transferObj controls the ownership of the returned value. If the +structure or class instance has already been wrapped then the result is a +new reference to the existing class instance object. If it is NULL and +the instance has already been wrapped then the ownership is unchanged. If +it is NULL and the instance is newly wrapped then ownership will be +with C/C++. If it is Py_None then ownership is transferred to Python +via a call to sipTransferBack(). Otherwise ownership is transferred to +C/C++ and the instance associated with transferObj via a call to +sipTransferTo(). The Python class is influenced by any applicable +%ConvertToSubClassCode code.
+
+
+
+

9.17   sipConvertFromMappedType()

+
+
PyObject *sipConvertFromMappedType(void *cpp, const sipMappedType *mt, PyObject *transferObj)
+
Convert a C structure or a C++ class instance wrapped as a mapped type to a +Python object. cpp is the C/C++ instance. mt is the opaque structure +returned by sipFindMappedType(). transferObj controls any ownership +changes to obj. If it is NULL then the ownership is unchanged. If +it is Py_None then ownership is transferred to Python via a call to +sipTransferBack(). Otherwise ownership is transferred to C/C++ and the +instance associated with the PyObject * argument via a call to +sipTransferTo().
+
+
+
+

9.18   sipConvertFromNamedEnum()

+
+
PyObject *sipConvertFromNamedEnum(int eval, PyTypeObject *type)
+
Convert a named C/C++ enum to an instance of the corresponding Python +named enum type. eval is the enumerated value to convert. type is the +generated Python type object (see Generated Named Enum Type Objects).
+
+
+
+

9.19   sipConvertFromNewInstance()

+
+
PyObject *sipConvertFromNewInstance(void *cpp, sipWrapperType *type, PyObject *transferObj)
+
Convert a new C structure or a new C++ class instance to a Python class +instance object. cpp is the C/C++ instance. type is the generated +type corresponding to the C/C++ type. transferObj controls the ownership +of the returned value. If it is NULL or Py_None then ownership +will be with Python. Otherwise ownership will be with C/C++ and the +instance associated with transferObj. The Python class is influenced by +any applicable %ConvertToSubClassCode code.
+
+
+
+

9.20   sipConvertFromSequenceIndex()

+
+
SIP_SSIZE_T sipConvertFromSequenceIndex(SIP_SSIZE_T idx, SIP_SSIZE_T len)
+
This converts a Python sequence index (i.e. where a negative value refers +to the offset from the end of the sequence) to a C/C++ array index. If the +index was out of range then a negative value is returned and a Python +exception raised. With versions of Python prior to v2.5 the result and the +arguments have type int.
+
+
+
+

9.21   sipConvertFromSliceObject()

+
+
int sipConvertFromSliceObject(PyObject *slice, SIP_SSIZE_T length, SIP_SSIZE_T *start, SIP_SSIZE_T *stop, SIP_SSIZE_T *step, SIP_SSIZE_T *slicelength)
+
This is a thin wrapper around the Python PySlice_GetIndicesEx() +function provided to make it easier to write handwritten code that is +compatible with SIP v3.x and versions of Python earlier that v2.3.
+
+
+
+

9.22   sipConvertToCpp()

+
+
void *sipConvertToCpp(PyObject *obj, sipWrapperType *type, int *iserr)
+

This function is deprecated from SIP v4.4. It is equivalent to:

+
+sipConvertToInstance(obj, type, NULL, SIP_NO_CONVERTORS, NULL, iserr);
+
+
+
+
+
+

9.23   sipConvertToInstance()

+
+
void *sipConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure or C++ class +assuming that a previous call to sipCanConvertToInstance() has been +successful. obj is the Python object. type is the generated type +corresponding to the C/C++ type returned. It may be any class in the +object's class hierarchy. transferObj controls any ownership changes to +obj. If it is NULL then the ownership is unchanged. If it is +Py_None then ownership is transferred to Python via a call to +sipTransferBack(). Otherwise ownership is transferred to C/C++ and +obj associated with transferObj via a call to sipTransferTo(). +flags is any combination of the following values used to fine tune the +check.

+
+
    +
  • SIP_NOT_NONE causes the check to fail if obj is None.
    • +
  • SIP_NO_CONVERTORS suppresses the use of of any +%ConvertToTypeCode for type.
    • +
+
+

If state is not NULL then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any %ConvertToTypeCode. The calling code must then release the value +at some point to prevent a memory leak by calling sipReleaseInstance(). +If there is an error then the location iserr points to is set to a +non-zero value. If it was initially a non-zero value then the conversion +isn't attempted in the first place. (This allows several calls to be made +that share the same error flag so that it only needs to be tested once +rather than after each call.)

+
+
+
+
+

9.24   sipConvertToMappedType()

+
+
void *sipConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)
+

This converts a Python object to an instance of a C structure or C++ +class that is implemented as a mapped type assuming that a previous call to +sipCanConvertToMappedType() has been successful. obj is the Python +object. mt is the opaque structure returned by sipFindMappedType(). +transferObj controls any ownership changes to obj. If it is NULL +then the ownership is unchanged. If it is Py_None then ownership is +transferred to Python via a call to sipTransferBack(). Otherwise +ownership is transferred to C/C++ and obj associated with transferObj +via a call to sipTransferTo(). flags is any combination of the +following values used to fine tune the check.

+
+
    +
  • SIP_NOT_NONE causes the check to fail if obj is None.
    • +
+
+

If state is not NULL then the location it points to is set to +describe the state of the returned C/C++ instance and is the value returned +by any %ConvertToTypeCode. The calling code must then release the value +at some point to prevent a memory leak by calling +sipReleaseMappedType(). If there is an error then the location iserr +points to is set to a non-zero value. If it was initially a non-zero value +then the conversion isn't attempted in the first place. (This allows +several calls to be made that share the same error flag so that it only +needs to be tested once rather than after each call.)

+
+
+
+
+

9.25   sipDisconnectRx()

+
+
PyObject *sipDisconnectRx(PyObject *sender, const char *signal, PyObject *receiver, const char *slot)
+
This disconnects a signal from a signal or slot and returns Py_True if +the signal was disconnected or Py_False if not. If there was some +other error then a Python exception is raised and NULL is returned. +sender is the wrapped QObject derived instance that emits the signal. +signal is the typed name of the signal. receiver is the wrapped +QObject derived instance or Python callable that the signal is +connected to. slot is the typed name of the slot, or NULL if +receiver is a Python callable. It is normally only used by PyQt to +implement QObject.disconnect().
+
+
+
+

9.26   sipEmitSignal()

+
+
int sipEmitSignal(PyObject *txobj, const char *signal, PyObject *args)
+
This emits a signal and returns zero if there was no error. If there was +an error then a Python exception is raised and a negative value is +returned. txobj is the wrapped QObject derived instance that emits +the signal. signal is the typed name of the signal. args is a Python +tuple of the signal arguments. It is normally only used by PyQt to +implement QObject.emit().
+
+
+
+

9.27   sipExportSymbol()

+
+
int sipExportSymbol(const char *name, void *sym)
+
Python does not allow extension modules to directly access symbols in +another extension module. This exports a symbol, referenced by a name, +that can subsequently be imported, using sipImportSymbol(), by another +module. name is the name of the symbol and sym is its value. Zero is +returned if there was no error. A negative value is returned if name is +already associated with a symbol or there was some other error.
+
+
+
+

9.28   sipFindClass()

+
+
sipWrapperType *sipFindClass(const char *type)
+
This returns a pointer to the generated type corresponding to a C/C++ type. +type is the C/C++ declaration of the type. NULL is returned if the +C/C++ type doesn't exist. The value of the pointer will not change and +may be saved in a static cache.
+
+
+
+

9.29   sipFindMappedType()

+
+
const sipMappedType *sipFindMappedType(const char *type)
+
This returns a pointer to an opaque structure describing a mapped type. +type is the C/C++ declaration of the type. NULL is returned if the +mapped type doesn't exist. The value of the pointer will not change and +may be saved in a static cache.
+
+
+
+

9.30   sipFindNamedEnum()

+
+
PyTypeObject *sipFindNamedEnum(const char *type)
+
This returns a pointer to the generated type corresponding to a named C/C++ +enum. type is the C/C++ declaration of the enum. NULL is returned +if the named C/C++ enum doesn't exist. The value of the pointer will not +change and may be saved in a static cache.
+
+
+
+

9.31   sipForceConvertToInstance()

+
+
void *sipForceConvertToInstance(PyObject *obj, sipWrapperType *type, PyObject *transferObj, int flags, int *state, int *iserr)
+
This converts a Python object to an instance of a C structure or C++ class +by calling sipCanConvertToInstance() and, if it is successfull, calling +sipConvertToInstance(). See sipConvertToInstance() for a full +description of the arguments.
+
+
+
+

9.32   sipForceConvertToMappedType()

+
+
void *sipForceConvertToMappedType(PyObject *obj, const sipMappedType *mt, PyObject *transferObj, int flags, int *state, int *iserr)
+
This converts a Python object to an instance of a C structure or C++ class +which has been implemented as a mapped type by calling +sipCanConvertToMappedType() and, if it is successfull, calling +sipConvertToMappedType(). See sipConvertToMappedType() for a full +description of the arguments.
+
+
+
+

9.33   sipFree()

+
+
void sipFree(void *mem)
+
This returns an area of memory allocated by sipMalloc() to the heap. +mem is a pointer to the area of memory.
+
+
+
+

9.34   sipGetSender()

+
+
const void *sipGetSender()
+
This returns a pointer to the last QObject instance that emitted a Qt +signal. It is normally only used by PyQt to implement +QObject.sender().
+
+
+
+

9.35   sipGetWrapper()

+
+
PyObject *sipGetWrapper(void *cppptr, sipWrapperType *type)
+
This returns a borrowed reference to the wrapped instance object for a C +structure or C++ class instance. If the structure or class instance +hasn't been wrapped then NULL is returned (and no Python exception is +raised). cppptr is the pointer to the structure or class instance. +type is the generated type corresponding to the C/C++ type.
+
+
+
+

9.36   sipImportSymbol()

+
+
void *sipImportSymbol(const char *name)
+
Python does not allow extension modules to directly access symbols in +another extension module. This imports a symbol, referenced by a name, +that has previously been exported, using sipExportSymbol(), by another +module. name is the name of the symbol. The value of the symbol is +returned if there was no error. NULL is returned if there is no such +symbol.
+
+
+
+

9.37   sipIntTypeClassMap

+

This C structure is used with sipMapIntToClass() to define a mapping +between integer based RTTI and generated type objects. The structure +elements are as follows.

+
+
int typeInt
+
The integer RTTI.
+
sipWrapperType **pyType.
+
A pointer to the corresponding Python type object.
+
+
+
+

9.38   sipIsSubClassInstance()

+
+
int sipIsSubClassInstance(PyObject *obj, sipWrapperType *type)
+

This function is deprecated from SIP v4.4. It is equivalent to:

+
+sipCanConvertToInstance(obj, type, SIP_NOT_NONE | SIP_NO_CONVERTORS);
+
+
+
+
+
+

9.39   sipLong_AsUnsignedLong()

+
+
unsigned long sipLong_AsUnsignedLong(PyObject *obj)
+
This function is a thin wrapper around PyLong_AsUnsignedLong() that works +around a bug in Python v2.3.x and earlier when converting integer objects.
+
+
+
+

9.40   sipMalloc()

+
+
void *sipMalloc(size_t nbytes)
+
This allocates an area of memory of size nytes on the heap using the +Python PyMem_Malloc() function. If there was an error then NULL is +returned and a Python exception raised. See sipFree().
+
+
+
+

9.41   sipMapIntToClass()

+
+
sipWrapperType *sipMapIntToClass(int type, const sipIntTypeClassMap *map, int maplen)
+
This is used in %ConvertToSubClassCode code as a convenient way of +converting integer based RTTI to the corresponding Python type object. +type is the RTTI. map is the table of known RTTI and the corresponding +type objects (see sipIntTypeClassMap). The entries in the table must be +sorted in ascending order of RTTI. maplen is the number of entries in +the table. The corresponding Python type object is returned, or NULL +if type wasn't in map.
+
+
+
+

9.42   sipMapStringToClass()

+
+
sipWrapperType *sipMapStringToClass(char *type, const sipStringTypeClassMap *map, int maplen)
+
This is used in %ConvertToSubClassCode code as a convenient way of +converting '\0' terminated string based RTTI to the corresponding +Python type object. type is the RTTI. map is the table of known RTTI +and the corresponding type objects (see sipStringTypeClassMap). The +entries in the table must be sorted in ascending order of RTTI. maplen +is the number of entries in the table. The corresponding Python type +object is returned, or NULL if type wasn't in map.
+
+
+
+

9.43   sipParseResult()

+
+
int sipParseResult(int *iserr, PyObject *method, PyObject *result, const char *format, ...)
+

This converts a Python object (usually returned by a method) to C/C++ based +on a format string and associated values in a similar way to the Python +PyArg_ParseTuple() function. If there was an error then a negative +value is returned and a Python exception is raised. If iserr is not +NULL then the location it points to is set to a non-zero value. +method is the Python bound method that returned the result object. +format is the string of format characters.

+

This is normally called by handwritten code specified with the +%VirtualCatcherCode directive with method being the supplied +sipMethod and result being the value returned by +sipCallMethod().

+

If format begins and ends with parentheses then result must be a Python +tuple and the rest of format is applied to the tuple contents.

+

In the following description the first letter is the format character, the +entry in parentheses is the Python object type that the format character +will convert, and the entry in brackets are the types of the C/C++ values +to be passed.

+
+
a (string) [char **, int *]
+
Convert a Python string to a C/C++ character array and its length. If +the Python object is Py_None then the array and length are NULL +and zero respectively.
+
b (integer) [bool *]
+
Convert a Python integer to a C/C++ bool.
+
c (string) [char *]
+
Convert a Python string of length 1 to a C/C++ char.
+
d (float) [double *]
+
Convert a Python floating point number to a C/C++ double.
+
e (integer) [enum *]
+
Convert a Python integer to an anonymous C/C++ enum.
+
f (float) [float *]
+
Convert a Python floating point number to a C/C++ float.
+
h (integer) [short *]
+
Convert a Python integer to a C/C++ short.
+
i (integer) [int *]
+
Convert a Python integer to a C/C++ int.
+
l (long) [long *]
+
Convert a Python long to a C/C++ long.
+
m (long) [unsigned long *]
+
Convert a Python long to a C/C++ unsigned long.
+
n (long) [long long *]
+
Convert a Python long to a C/C++ long long.
+
o (long) [unsigned long long *]
+
Convert a Python long to a C/C++ unsigned long long.
+
s (string) [char **]
+
Convert a Python string to a C/C++ '\0' terminated string. If the +Python object is Py_None then the string is NULL.
+
t (long) [unsigned short *]
+
Convert a Python long to a C/C++ unsigned short.
+
u (long) [unsigned int *]
+
Convert a Python long to a C/C++ unsigned int.
+
w (unicode) [wchar_t *]
+
Convert a Python unicode object of length 1 to a C/C++ wide character.
+
x (unicode) [wchar_t **]
+
Convert a Python unicode object to a C/C++ L'\0' terminated wide +character string. If the Python object is Py_None then the string +is NULL.
+
A (unicode) [wchar_t **, int *]
+
Convert a Python unicode object to a C/C++ wide character array and its +length. If the Python object is Py_None then the array and length +are NULL and zero respectively.
+
Cf (wrapped class) [sipWrapperType *, int *, void **]
+

Convert a Python object to a C structure or a C++ class instance and +return its state as described in sipConvertToInstance(). f is a +combination of the following flags encoded as an ASCII character by +adding 0 to the combined value:

+
+

0x01 disallows the conversion of Py_None to NULL

+

0x02 implements the Factory annotation

+
+
0x04 suppresses the return of the state of the returned C/C++
+
instance. Note that the int * used to return the state is +not passed if this flag is specified.
+
+
+
+
Df (mapped type) [const sipMappedType *, int *, void **]
+

Convert a Python object to a C structure or a C++ class instance +implemented as a mapped type and return its state as described in +sipConvertToMappedType(). f is a combination of the following +flags encoded as an ASCII character by adding 0 to the combined +value:

+
+

0x01 disallows the conversion of Py_None to NULL

+

0x02 implements the Factory annotation

+
+
0x04 suppresses the return of the state of the returned C/C++
+
instance. Note that the int * used to return the state is +not passed if this flag is specified.
+
+
+
+
E (wrapped enum) [PyTypeObject *, enum *]
+
Convert a Python named enum type to the corresponding C/C++ enum.
+
L (object) [type *(*)(PyObject *obj, int *iserr), void **]
+
Convert a Python object to a C structure or a C++ class instance using +a convertor function. See Generated Type Convertors. This is +deprecated from SIP v4.4.
+
M (object) [type *(*)(PyObject *obj, int *iserr), void **]
+
Convert a Python object to a C structure or a C++ class instance using +a convertor function. If the structure or class instance pointer is +NULL then return an error. See Generated Type Convertors. This +is deprecated from SIP v4.4.
+
N (object) [PyTypeObject *, PyObject **]
+
A Python object is checked to see if it is a certain type and then +returned without any conversions. The reference count is incremented. +The Python object may be Py_None.
+
O (object) [PyObject **]
+
A Python object is returned without any conversions. The reference +count is incremented.
+
T (object) [PyTypeObject *, PyObject **]
+
A Python object is checked to see if it is a certain type and then +returned without any conversions. The reference count is incremented. +The Python object may not be Py_None.
+
V (sip.voidptr) [void *]
+
Convert a Python sip.voidptr object to a C/C++ void *.
+
Z (object) []
+
Check that a Python object is Py_None. No value is returned.
+
+
+
+
+
+

9.44   sipReleaseInstance()

+
+
void sipReleaseInstance(void *cpp, sipWrapperType *type, int state)
+
This destroys a wrapped C/C++ instance if it was a temporary instance. It +is called after a call to either sipConvertToInstance() or +sipForceConvertToInstance(). cpp is the wrapped C/C++ instance. +type is the generated type corresponding to cpp. state describes the +state of the instance.
+
+
+
+

9.45   sipReleaseMappedType()

+
+
void sipReleaseMappedType(void *cpp, const sipMappedType *mt, int state)
+
This destroys a wrapped C/C++ mapped type if it was a temporary instance. +It is called after a call to either sipConvertToMappedType() or +sipForceConvertToMappedType(). cpp is the wrapped C/C++ instance. +mt is the opaque structure returned by sipFindMappedType(). state +describes the state of the instance.
+
+
+
+

9.46   sipStringTypeClassMap

+

This C structure is used with sipMapStringToClass() to define a mapping +between '\0' terminated string based RTTI and generated type objects. +The structure elements are as follows.

+
+
char *typeString
+
The '\0' terminated string RTTI.
+
sipWrapperType **pyType.
+
A pointer to the corresponding Python type object.
+
+
+
+

9.47   sipTransfer()

+
+
void sipTransfer(PyObject *obj, int tocpp)
+

This function is deprecated from SIP v4.3. If tocpp is non-zero then the +equivalent call is:

+
+sipTransferTo(obj, obj);
+
+

If tocpp is zero then the equivalent call is:

+
+sipTransferBack(obj);
+
+
+
+
+
+

9.48   sipTransferBack()

+
+
void sipTransferBack(PyObject *obj)
+
This transfers ownership of a Python wrapped instance to Python (see +Ownership of Objects). obj is the wrapped instance. In addition, +any association of the instance with regard to the cyclic garbage +collector with another instance is removed.
+
+
+
+

9.49   sipTransferTo()

+
+
void sipTransferTo(PyObject *obj, PyObject *owner)
+
This transfers ownership of a Python wrapped instance to C++ (see +Ownership of Objects). obj is the wrapped instance. owner is an +optional wrapped instance that obj becomes associated with with regard +to the cyclic garbage collector. If owner is NULL then no such +association is made. If owner is the same value as obj then any +reference cycles involving obj can never be detected or broken by the +cyclic garbage collector. Responsibility for calling the C++ instance's +destructor is always transfered to C++.
+
+
+
+

9.50   sipWrapper

+

This is a C structure that represents a Python wrapped instance. It is an +extension of the Python PyObject structure and so may be safely cast to +PyObject. It includes a member called user which is of type +PyObject *. This can be used for any purpose by handwritten code and will +automatically be garbage collected at the appropriate time.

+
+
+

9.51   sipWrapper_Check()

+
+
int sipWrapper_Check(PyObject *obj)
+
This returns a non-zero value if a Python object is a wrapped instance. +obj is the Python object.
+
+
+
+

9.52   sipWrapperType

+

This is a C structure that represents a SIP generated type object. It is an +extension of the Python PyTypeObject structure (which is itself an +extension of the Python PyObject structure) and so may be safely cast to +PyTypeObject (and PyObject).

+
+
+

9.53   Generated Type Convertors

+

These functions are deprecated from SIP v4.4.

+

SIP generates functions for all types being wrapped (including mapped types +defined with the %MappedType directive) that convert a Python object to the +C structure or C++ class instance. The name of this convertor is the name of +the structure or class prefixed by sipForceConvertTo_.

+
+
void *sipForceConvertTo_*class*(PyObject *obj, int *iserr)
+
obj is the Python object to convert. If obj is NULL or the +location pointed to by iserr is non-zero then the conversion is not +attempted and NULL is returned. If there was an error then the +location pointed to by iserr is set to a non-zero value, a Python +exception is raised, and NULL is returned.
+
+

SIP also generates functions for mapped types that convert a C structure or +C++ class instance to a Python object. The name of this convertor is the name +of the structure or class prefixed by sipConvertFrom_.

+
+
PyObject *sipConvertFrom_*class*(void *cppptr)
+
cppptr is a pointer to the C structure or C++ class instance to convert. +If there was an error then NULL is returned and a Python exception +raised.
+
+

The convertor functions of all imported types are available to handwritten +code.

+
+
+

9.54   Generated Type Objects

+

SIP generates a type object for each C structure or C++ class being wrapped. +These are sipWrapperType structures and are used extensively by the SIP API.

+

These objects are named with the structure or class name prefixed by +sipClass_. For example, the type object for class Klass is +sipClass_Klass.

+

The type objects of all imported classes are available to handwritten code.

+
+
+

9.55   Generated Named Enum Type Objects

+

SIP generates a type object for each named enum being wrapped. These are +PyTypeObject structures. (Anonymous enums are wrapped as Python integers.)

+

These objects are named with the fully qualified enum name (i.e. including any +enclosing scope) prefixed by sipEnum_. For example, the type object for +enum Enum defined in class Klass is sipEnum_Klass_Enum.

+

The type objects of all imported named enums are available to handwritten code.

+
+
+

9.56   Generated Derived Classes

+

For most C++ classes being wrapped SIP generates a derived class with the same +name prefixed by sip. For example, the derived class for class Klass +is sipKlass.

+

If a C++ class doesn't have any virtual or protected methods in it or any of +it's super-class hierarchy, or does not emit any Qt signals, then a derived +class is not generated.

+

Most of the time handwritten code should ignore the derived classes. The only +exception is that handwritten constructor code specified using the +%MethodCode directive should call the derived class's constructor (which +has the same C++ signature) rather then the wrapped class's constructor.

+
+
+

9.57   Generated Exception Objects

+

SIP generates a Python object for each exception defined with the %Exception_ +directive.

+

These objects are named with the fully qualified exception name (i.e. including +any enclosing scope) prefixed by sipException_. For example, the type +object for enum Except defined in class Klass is +sipException_Klass_Except.

+

The objects of all imported exceptions are available to handwritten code.

+
+
+
+

10   Using the SIP Module in Applications

+

The main purpose of the SIP module is to provide functionality common to all +SIP generated bindings. It is loaded automatically and most of the time you +will completely ignore it. However, it does expose some functionality that can +be used by applications.

+
+
cast(obj, type)
+
This does the Python equivalent of casting a C++ instance to one of its +sub or super-class types. obj is the Python object and type is the +type. A new Python object is returned that wraps the same C++ instance as +obj, but has the type type.
+
delete(obj)
+
For C++ instances this calls the C++ destructor. For C structures it +returns the structure's memory to the heap. obj is the Python object.
+
isdeleted(obj)
+
This returns True if the C++ instance or C structure has been destroyed or +returned to the heap. obj is the Python object.
+
setdeleted(obj)
+
This marks the C++ instance or C structure as having been destroyed or +returned to the heap so that future references to it raise an exception +rather than cause a program crash. Normally SIP handles such things +automatically, but there are circumstances where this isn't possible. +obj is the Python object.
+
settracemask(mask)
+

If the bindings have been created with SIP's -r command line option +then the generated code will produce debugging statements that trace the +execution of the code. (It is particularly useful when trying to +understand the operation of a C++ library's virtual function calls.)

+

Debugging statements are generated at the following points:

+
    +
  • in a C++ virtual function (mask is 0x0001)
    • +
  • in a C++ constructor (mask is 0x0002)
    • +
  • in a C++ destructor (mask is 0x0004)
    • +
  • in a Python type's __init__ method (mask is 0x0008)
    • +
  • in a Python type's __del__ method (mask is 0x0010)
    • +
  • in a Python type's ordinary method (mask is 0x0020).
    • +
+

By default the trace mask is zero and all debugging statements are +disabled.

+
+
SIP_VERSION
+
This is a Python integer object that represents the SIP version number as +a 3 part hexadecimal number (e.g. v4.0.0 is represented as 0x040000). +It was first implemented in SIP v4.2.
+
SIP_VERSION_STR
+
This is a Python string object that defines the SIP version number as +represented as a string. For development snapshots it will start with +snapshot-. It was first implemented in SIP v4.3.
+
transfer(obj, direction)
+

This function is deprecated from SIP v4.3. If direction is non-zero then +the equivalent call is:

+
+sip.transferto(obj, None)
+
+

If direction is zero then the equivalent call is:

+
+sip.transferback(obj)
+
+
+
transferback(obj)
+
This function is a wrapper around sipTransferBack().
+
transferto(obj, owner)
+
This function is a wrapper around sipTransferTo().
+
unwrapinstance(obj)
+
Return the address, as a number, of the wrapped C/C++ structure or class +instance obj.
+
voidptr
+

This is the type object for the type SIP uses to represent a C/C++ +void *. The type constructor takes a single argument that must either +be another voidptr, None, a Python CObject, or an integer. The +type has the following methods:

+
+
__int__()
+
This returns the pointer as an integer.
+
__hex__()
+
This returns the pointer as a hexadecimal string.
+
ascobject()
+
This returns the pointer as a Python CObject.
+
asstring(nbytes)
+
This returns a copy of the first nbytes of memory at the pointer as a +Python string.
+
+
+
wrapinstance(addr, type)
+
A C/C++ structure or class instance is wrapped and the Python object +created is returned. If the instance has already been wrapped then a new +reference to the existing object is returned. addr is the address of +the instance represented as a number. type is the type of the object +(e.g. qt.QWidget).
+
wrapper
+
This is the type object of the base type of all instances wrapped by SIP.
+
wrappertype
+
This is the type object of the metatype of the wrapper type.
+
+
+
+

11   The SIP Build System

+

The purpose of the build system is to make it easy for you to write +configuration scripts in Python for your own bindings. The build system takes +care of the details of particular combinations of platform and compiler. It +supports over 50 different platform/compiler combinations.

+

The build system is implemented as a pure Python module called sipconfig +that contains a number of classes and functions. Using this module you can +write bespoke configuration scripts (e.g. PyQt's configure.py) or use it +with other Python based build systems (e.g. +Distutils and +SCons).

+

An important feature of SIP is the ability to generate bindings that are built +on top of existing bindings. For example, both +PyKDE and +PyQwt are built on top of PyQt but all three +packages are maintained by different developers. To make this easier PyQt +includes its own configuration module, pyqtconfig, that contains additional +classes intended to be used by the configuration scripts of bindings built on +top of PyQt. The SIP build system includes facilities that do a lot of the +work of creating these additional configuration modules.

+
+

11.1   sipconfig Functions

+
+
create_config_module(module, template, content, macros=None)
+

This creates a configuration module (e.g. pyqtconfig) from a template +file and a string.

+

module is the name of the configuration module file to create.

+

template is the name of the template file.

+

content is a string which replaces every occurence of the pattern +@SIP_CONFIGURATION@ in the template file. The content string is +usually created from a Python dictionary using +sipconfig.create_content(). content may also be a dictionary, in +which case sipconfig.create_content() is automatically called to +convert it to a string.

+

macros is an optional dictionary of platform specific build macros. It +is only used if sipconfig.create_content() is called automatically to +convert a content dictionary to a string.

+
+
create_content(dict, macros=None)
+

This converts a Python dictionary to a string that can be parsed by the +Python interpreter and converted back to an equivalent dictionary. It is +typically used to generate the content string for +sipconfig.create_config_module().

+

dict is the Python dictionary to convert.

+

macros is the optional dictionary of platform specific build macros.

+

Returns the dictionary as a string.

+
+
create_wrapper(script, wrapper, gui=0)
+

This creates a platform dependent executable wrapper around a Python +script.

+

script is the full pathname of the script.

+

wrapper is the pathname of the wrapper to create.

+

gui is non-zero if a GUI enabled version of the interpreter should be +used on platforms that require it.

+

Returns the platform specific name of the wrapper.

+
+
error(msg)
+

This displays an error message on stderr and calls sys.exit() with +a value of 1.

+

msg is the text of the message and should not include any newline +characters.

+
+
format(msg, leftmargin=0, rightmargin=78)
+

This formats a message by inserting newline characters at appropriate +places.

+

msg is the text of the message and should not include any newline +characters.

+

leftmargin is the optional position of the left margin.

+

rightmargin is the optional position of the right margin.

+
+
inform(msg)
+

This displays an information message on stdout.

+

msg is the text of the message and should not include any newline +characters.

+
+
parse_build_macros(filename, names, overrides=None, properties=None)
+

This parses a qmake compatible file of build system macros and converts it +to a dictionary. A macro is a name/value pair. The dictionary is returned +or None if any of the overrides was invalid.

+

filename is the name of the file to parse.

+

names is a list of the macro names to extract from the file.

+

overrides is an optional list of macro names and values that modify +those found in the file. They are of the form name=value (in which case +the value replaces the value found in the file) or name+=value (in which +case the value is appended to the value found in the file).

+

properties is an optional dictionary of property name and values that +are used to resolve any expressions of the form $[name] in the file.

+
+
read_version(filename, description, numdefine=None, strdefine=None)
+

This extracts version information for a package from a file, usually a C or +C++ header file. The version information must each be specified as a +#define of a numeric (hexadecimal or decimal) value and/or a string +value.

+

filename is the name of the file to read.

+

description is a descriptive name of the package used in error +messages.

+

numdefine is the optional name of the #define of the version as a +number. If it is None then the numeric version is ignored.

+

strdefine is the optional name of the #define of the version as a +string. If it is None then the string version is ignored.

+

Returns a tuple of the numeric and string versions. sipconfig.error() +is called if either were required but could not be found.

+
+
version_to_sip_tag(version, tags, description)
+

This converts a version number to a SIP version tag. SIP uses the +%Timeline directive to define the chronology of the different versions +of the C/C++ library being wrapped. Typically it is not necessary to +define a version tag for every version of the library, but only for those +versions that affect the library's API as SIP sees it.

+

version is the numeric version number of the C/C++ library being +wrapped. If it is negative then the latest version is assumed. (This is +typically useful if a snapshot is indicated by a negative version number.)

+

tags is the dictionary of SIP version tags keyed by the corresponding +C/C++ library version number. The tag used is the one with the smallest +key (i.e. earliest version) that is greater than version.

+

description is a descriptive name of the C/C++ library used in error +messages.

+

Returns the SIP version tag. sipconfig.error() is called if the C/C++ +library version number did not correspond to a SIP version tag.

+
+
version_to_string(v)
+

This converts a 3 part version number encoded as a hexadecimal value to a +string.

+

v is the version number.

+

Returns a string.

+
+
+
+
+

11.2   sipconfig Classes

+
+
Configuration
+

This class encapsulates configuration values that can be accessed as +instance objects. A sub-class may provide a dictionary of additional +configuration values in its constructor the elements of which will have +precedence over the super-class's values.

+

The following configuration values are provided:

+
+
+
default_bin_dir
+
The name of the directory where executables should be installed by +default.
+
default_mod_dir
+
The name of the directory where SIP generated modules should be +installed by default.
+
default_sip_dir
+
The name of the base directory where the .sip files for SIP +generated modules should be installed by default. A sub-directory +with the same name as the module should be created and its .sip +files should be installed in the sub-directory. The .sip +files only need to be installed if you might want to build other +bindings based on them.
+
platform
+
The name of the platform/compiler for which the build system has +been configured for.
+
py_conf_inc_dir
+
The name of the directory containing the pyconfig.h header +file.
+
py_inc_dir
+
The name of the directory containing the Python.h header file.
+
py_lib_dir
+
The name of the directory containing the Python interpreter +library.
+
py_version
+
The Python version as a 3 part hexadecimal number (e.g. v2.3.3 is +represented as 0x020303).
+
sip_bin
+
The full pathname of the SIP executable.
+
sip_config_args
+
The command line passed to configure.py when SIP was +configured.
+
sip_inc_dir
+
The name of the directory containing the sip.h header file.
+
sip_mod_dir
+
The name of the directory containing the SIP module.
+
sip_version
+
The SIP version as a 3 part hexadecimal number (e.g. v4.0.0 is +represented as 0x040000).
+
sip_version_str
+
The SIP version as a string. For development snapshots it will +start with snapshot-.
+
universal
+
The name of the MacOS/X SDK used when creating universal binaries.
+
+
+
+
__init__(self, sub_cfg=None)
+

Initialise the instance.

+

sub_cfg is an optional list of sub-class configurations. It should +only be used by the __init__() method of a sub-class to append its +own dictionary of configuration values before passing the list to its +super-class.

+
+
build_macros(self)
+
Return the dictionary of platform specific build macros.
+
set_build_macros(self, macros)
+
Set the dictionary of platform specific build macros to be use when +generating Makefiles. Normally there is no need to change the default +macros.
+
+
+
Makefile
+

This class encapsulates a Makefile. It is intended to be sub-classed to +generate Makefiles for particular purposes. It handles all platform and +compiler specific flags, but allows them to be adjusted to suit the +requirements of a particular module or program. These are defined using a +number of macros which can be accessed as instance objects.

+

The following instance objects are provided to help in fine tuning the +generated Makefile:

+
+
+
chkdir
+
A string that will check for the existence of a directory.
+
config
+
A reference to the configuration argument that was passed to +the constructor.
+
console
+
A reference to the console argument that was passed to the +constructor.
+
copy
+
A string that will copy a file.
+
extra_cflags
+
A list of additional flags passed to the C compiler.
+
extra_cxxflags
+
A list of additional flags passed to the C++ compiler.
+
extra_defines
+
A list of additional macro names passed to the C/C++ preprocessor.
+
extra_include_dirs
+
A list of additional include directories passed to the C/C++ +preprocessor.
+
extra_lflags
+
A list of additional flags passed to the linker.
+
extra_lib_dirs
+
A list of additional library directories passed to the linker.
+
extra_libs
+
A list of additional libraries passed to the linker. The names of +the libraries must be in platform neutral form (i.e. without any +platform specific prefixes, version numbers or extensions).
+
generator
+
A string that defines the platform specific style of Makefile. The +only supported values are UNIX and something else that is not +UNIX.
+
mkdir
+
A string that will create a directory.
+
rm
+
A string that will remove a file.
+
+
+
+
__init__(self, configuration, console=0, qt=0, opengl=0, python=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, universal='')
+

Initialise the instance.

+

configuration is the current configuration and is an instance of +the Configuration class or a sub-class.

+

console is set if the target is a console (rather than GUI) target. +This only affects Windows and is ignored on other platforms.

+

qt is set if the target uses Qt. For Qt v4 a list of Qt libraries +may be specified and a simple non-zero value implies QtCore and QtGui.

+

opengl is set if the target uses OpenGL.

+

python is set if the target uses Python.h.

+

threaded is set if the target requires thread support. It is set +automatically if the target uses Qt and Qt has thread support enabled.

+

warnings is set if compiler warning messages should be enabled. +The default of None means that warnings are enabled for SIP v4.x +and disabled for SIP v3.x.

+

debug is set if debugging symbols should be generated.

+

dir is the name of the directory where build files are read from +and Makefiles are written to. The default of None means the +current directory is used.

+

makefile is the name of the generated Makefile.

+

installs is a list of extra install targets. Each element is a two +part list, the first of which is the source and the second is the +destination. If the source is another list then it is a list of source +files and the destination is a directory.

+

universal is the name of the SDK if universal binaries are to be +created under MacOS/X.

+
+
clean_build_file_objects(self, mfile, build)
+

This generates the Makefile commands that will remove any files +generated during the build of the default target.

+

mfile is the Python file object of the Makefile.

+

build is the dictionary created from parsing the build file.

+
+
finalise(self)
+
This is called just before the Makefile is generated to ensure that it +is fully configured. It must be reimplemented by a sub-class.
+
generate(self)
+
This generates the Makefile.
+
generate_macros_and_rules(self, mfile)
+

This is the default implementation of the Makefile macros and rules +generation.

+

mfile is the Python file object of the Makefile.

+
+
generate_target_clean(self, mfile)
+

This is the default implementation of the Makefile clean target +generation.

+

mfile is the Python file object of the Makefile.

+
+
generate_target_default(self, mfile)
+

This is the default implementation of the Makefile default target +generation.

+

mfile is the Python file object of the Makefile.

+
+
generate_target_install(self, mfile)
+

This is the default implementation of the Makefile install target +generation.

+

mfile is the Python file object of the Makefile.

+
+
install_file(self, mfile, src, dst, strip=0)
+

This generates the Makefile commands to install one or more files to a +directory.

+

mfile is the Python file object of the Makefile.

+

src is the name of a single file to install or a list of a number +of files to install.

+

dst is the name of the destination directory.

+

strip is set if the files should be stripped of unneeded symbols +after having been installed.

+
+
optional_list(self, name)
+

This returns an optional Makefile macro as a list.

+

name is the name of the macro.

+

Returns the macro as a list.

+
+
optional_string(self, name, default="")
+

This returns an optional Makefile macro as a string.

+

name is the name of the macro.

+

default is the optional default value of the macro.

+

Returns the macro as a string.

+
+
parse_build_file(self, filename)
+

This parses a build file (created with the -b SIP command line +option) and converts it to a dictionary. It can also validate an +existing dictionary created through other means.

+

filename is the name of the build file, or is a dictionary to be +validated. A valid dictionary will contain the name of the target to +build (excluding any platform specific extension) keyed by target; +the names of all source files keyed by sources; and, optionally, +the names of all header files keyed by headers.

+

Returns a dictionary corresponding to the parsed build file.

+
+
platform_lib(self, clib, framework=0)
+

This converts a library name to a platform specific form.

+

clib is the name of the library in cannonical form.

+

framework is set if the library is implemented as a MacOS +framework.

+

Return the platform specific name.

+
+
ready(self)
+
This is called to ensure that the Makefile is fully configured. It is +normally called automatically when needed.
+
required_string(self, name)
+

This returns a required Makefile macro as a string.

+

name is the name of the macro.

+

Returns the macro as a string. An exception is raised if the macro +does not exist or has an empty value.

+
+
+
+
ModuleMakefile(Makefile)
+

This class encapsulates a Makefile to build a generic Python extension +module.

+
+
__init__(self, configuration, build_file, install_dir=None, static=0, console=0, opengl=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, strip=1, export_all=0, universal='')
+

Initialise the instance.

+

configuration - see sipconfig.Makefile.__init__().

+

build_file is the name of the build file. Build files are +generated using the -b SIP command line option.

+

install_dir is the name of the directory where the module will be +optionally installed.

+

static is set if the module should be built as a static library +(see Builtin Modules and Custom Interpreters).

+

console - see sipconfig.Makefile.__init__().

+

qt - see sipconfig.Makefile.__init__().

+

opengl - see sipconfig.Makefile.__init__().

+

threaded - see sipconfig.Makefile.__init__().

+

warnings - see sipconfig.Makefile.__init__().

+

debug - see sipconfig.Makefile.__init__().

+

dir - see sipconfig.Makefile.__init__().

+

makefile - see sipconfig.Makefile.__init__().

+

installs - see sipconfig.Makefile.__init__().

+

strip is set if the module should be stripped of unneeded symbols +after installation. It is ignored if either debug or static is +set, or if the platform doesn't support it.

+

export_all is set if all of the module's symbols should be exported +rather than just the module's initialisation function. Exporting all +symbols increases the size of the module and slows down module load +times but may avoid problems with modules that use C++ exceptions. All +symbols are exported if either debug or static is set, or if +the platform doesn't support it.

+
+
finalise(self)
+
This is a reimplementation of sipconfig.Makefile.finalise().
+
generate_macros_and_rules(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+
generate_target_clean(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_clean().
+
generate_target_default(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_default().
+
generate_target_install(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+
module_as_lib(self, mname)
+

This returns the name of a SIP v3.x module for when it is used as a +library to be linked against. An exception will be raised if it is +used with SIP v4.x modules.

+

mname is the name of the module.

+

Returns the corresponding library name.

+
+
+
+
ParentMakefile(Makefile)
+

This class encapsulates a Makefile that sits above a number of other +Makefiles in sub-directories.

+
+
__init__(self, configuration, subdirs, dir=None, makefile="Makefile", installs=None)
+

Initialise the instance.

+

configuration - see sipconfig.Makefile.__init__().

+

subdirs is the sequence of sub-directories.

+

dir - see sipconfig.Makefile.__init__().

+

makefile - see sipconfig.Makefile.__init__().

+

installs - see sipconfig.Makefile.__init__().

+
+
generate_macros_and_rules(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+
generate_target_clean(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_clean().
+
generate_target_default(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_default().
+
generate_target_install(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+
+
+
ProgramMakefile(Makefile)
+

This class encapsulates a Makefile to build an executable program.

+
+
__init__(self, configuration, build_file=None, install_dir=None, console=0, qt=0, opengl=0, python=0, threaded=0, warnings=None, debug=0, dir=None, makefile="Makefile", installs=None, universal='')
+

Initialise the instance.

+

configuration - see sipconfig.Makefile.__init__().

+

build_file is the name of the optional build file. Build files are +generated using the -b SIP command line option.

+

install_dir is the name of the directory where the executable +program will be optionally installed.

+

console - see sipconfig.Makefile.__init__().

+

qt - see sipconfig.Makefile.__init__().

+

opengl - see sipconfig.Makefile.__init__().

+

python - see sipconfig.Makefile.__init__().

+

threaded - see sipconfig.Makefile.__init__().

+

warnings - see sipconfig.Makefile.__init__().

+

debug - see sipconfig.Makefile.__init__().

+

dir - see sipconfig.Makefile.__init__().

+

makefile - see sipconfig.Makefile.__init__().

+

installs - see sipconfig.Makefile.__init__().

+
+
build_command(self, source)
+

This creates a single command line that will create an executable +program from a single source file.

+

source is the name of the source file.

+

Returns a tuple of the name of the executable that will be created and +the command line.

+
+
finalise(self)
+
This is a reimplementation of sipconfig.Makefile.finalise().
+
generate_macros_and_rules(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+
generate_target_clean(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_clean().
+
generate_target_default(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_default().
+
generate_target_install(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+
+
+
PythonModuleMakefile(Makefile)
+

This class encapsulates a Makefile that installs a pure Python module.

+
+
__init__(self, configuration, dstdir, srcdir=None, dir=None, makefile="Makefile", installs=None)
+

Initialise the instance.

+

configuration - see sipconfig.Makefile.__init__().

+

dstdir is the name of the directory in which the module's Python +code will be installed.

+

srcdir is the name of the directory (relative to dir) +containing the module's Python code. It defaults to the same +directory.

+

dir - see sipconfig.Makefile.__init__().

+

makefile - see sipconfig.Makefile.__init__().

+

installs - see sipconfig.Makefile.__init__().

+
+
generate_macros_and_rules(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_macros_and_rules().
+
generate_target_install(self, mfile)
+
This is a reimplementation of +sipconfig.Makefile.generate_target_install().
+
+
+
SIPModuleMakefile(ModuleMakefile)
+

This class encapsulates a Makefile to build a SIP generated Python +extension module.

+
+
finalise(self)
+
This is a reimplementation of sipconfig.Makefile.finalise().
+
+
+
+
+
+
+

12   Building Your Extension with distutils

+

To build the example in A Simple C++ Example using distutils, it is +sufficient to create a standard setup.py, listing word.sip among the +files to build, and hook-up SIP into distutils:

+
+from distutils.core import setup, Extension
+import sipdistutils
+
+setup(
+  name = 'word',
+  versione = '1.0',
+  ext_modules=[
+    Extension("word", ["word.sip", "word.cpp"]),
+    ],
+
+  cmdclass = {'build_ext': sipdistutils.build_ext}
+)
+
+

As we can see, the above is a normal distutils setup script, with just a +special line which is needed so that SIP can see and process word.sip. +Then, running setup.py build will build our extension module.

+
+
+

13   Builtin Modules and Custom Interpreters

+

Sometimes you want to create a custom Python interpreter with some modules +built in to the interpreter itself rather than being dynamically loaded. To +do this the module must be created as a static library and linked with a +custom stub and the normal Python library.

+

To build the SIP module as a static library you must pass the -k command +line option to configure.py. You should then build and install SIP as +normal. (Note that, because the module is now a static library, you will not +be able to import it.)

+

To build a module you have created for your own library you must modify your +own configuration script to pass a non-zero value as the static argument +of the __init__() method of the ModuleMakefile class (or any derived +class you have created). Normally you would make this configurable using a +command line option in the same way that SIP's configure.py handles it.

+

The next stage is to create a custom stub and a Makefile. The SIP distribution +contains a directory called custom which contains example stubs and a +Python script that will create a correct Makefile. Note that, if your copy of +SIP was part of a standard Linux distribution, the custom directory may +not be installed on your system.

+

The custom directory contains the following files. They are provided as +examples - each needs to be modified according to your particular +requirements.

+
+
    +
  • mkcustom.py is a Python script that will create a Makefile which is +then used to build the custom interpreter. Comments in the file describe +how it should be modified.
    • +
  • custom.c is a stub for a custom interpreter on Linux/UNIX. It +should also be used for a custom console interpreter on Windows (i.e. +like python.exe). Comments in the file describe how it should be +modified.
    • +
  • customw.c is a stub for a custom GUI interpreter on Windows (i.e. +like pythonw.exe). Comments in the file describe how it should be +modified.
    • +
+
+

Note that this technique does not restrict how the interpreter can be used. +For example, it still allows users to write their own applications that can +import your builtin modules. If you want to prevent users from doing that, +perhaps to protect a proprietary API, then take a look at the +VendorID package.

+
+
+ + -- cgit v1.2.1