From 875ae8e38bc3663e5057ca910e7ebe4b2994edb9 Mon Sep 17 00:00:00 2001 From: tpearson Date: Tue, 14 Sep 2010 19:47:20 +0000 Subject: Updated python directory git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebindings@1175349 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- python/sip/doc/default.css | 229 -- python/sip/doc/sipref.html | 5281 ------------------------------------------- python/sip/doc/sipref.txt | 5353 -------------------------------------------- 3 files changed, 10863 deletions(-) delete mode 100644 python/sip/doc/default.css delete mode 100644 python/sip/doc/sipref.html delete mode 100644 python/sip/doc/sipref.txt (limited to 'python/sip/doc') diff --git a/python/sip/doc/default.css b/python/sip/doc/default.css deleted file mode 100644 index 5e077213..00000000 --- a/python/sip/doc/default.css +++ /dev/null @@ -1,229 +0,0 @@ -/* -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. - -Default cascading style sheet for the HTML output of Docutils. -*/ - -.first { - margin-top: 0 } - -.last { - margin-bottom: 0 } - -a.toc-backref { - text-decoration: none ; - color: black } - -dt { - font-weight: bold } - -dd { - margin-bottom: 1.5em } - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning, div.admonition { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title, -div.admonition p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.dedication { - margin: 2em 5em ; - text-align: center ; - font-style: italic } - -div.dedication p.topic-title { - font-weight: bold ; - font-style: normal } - -div.figure { - margin-left: 2em } - -div.footer, div.header { - font-size: smaller } - -div.sidebar { - margin-left: 1em ; - border: medium outset ; - padding: 0em 1em ; - background-color: #ffffee ; - width: 40% ; - float: right ; - clear: right } - -div.sidebar p.rubric { - font-family: sans-serif ; - font-size: medium } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -h1.title { - text-align: center } - -h2.subtitle { - text-align: center } - -hr { - width: 75% } - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.attribution { - text-align: right ; - margin-left: 50% } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.rubric { - font-weight: bold ; - font-size: larger ; - color: maroon ; - text-align: center } - -p.sidebar-title { - font-family: sans-serif ; - font-weight: bold ; - font-size: larger } - -p.sidebar-subtitle { - font-family: sans-serif ; - font-weight: bold } - -p.topic-title { - font-weight: bold } - -pre.address { - margin-bottom: 0 ; - margin-top: 0 ; - font-family: serif ; - font-size: 100% } - -pre.line-block { - font-family: serif ; - font-size: 100% } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em ; - background-color: #eeeeee } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option { - white-space: nowrap } - -span.option-argument { - font-style: italic } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -table.citation { - border-left: solid thin gray ; - padding-left: 0.5ex } - -table.docinfo { - margin: 2em 4em } - -table.footnote { - border-left: solid thin black ; - padding-left: 0.5ex } - -td, th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -th.docinfo-name, th.field-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - font-size: 100% } - -/* -tt { - background-color: #eeeeee } -*/ - -ul.auto-toc { - list-style-type: none } diff --git a/python/sip/doc/sipref.html b/python/sip/doc/sipref.html deleted file mode 100644 index 71fcbdb4..00000000 --- a/python/sip/doc/sipref.html +++ /dev/null @@ -1,5281 +0,0 @@ - - - - - - -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 TQLabel class. It behaves just like TQLabel 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 <tqlabel.h>
-#include <tqwidget.h>
-#include <tqstring.h>
-
-class Hello : public TQLabel {
-    // This is needed by the Qt Meta-Object Compiler.
-    Q_OBJECT
-
-public:
-    Hello(TQWidget *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 TQString &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 : TQLabel {
-
-%TypeHeaderCode
-#include <hello.h>
-%End
-
-public:
-    Hello(TQWidget *parent /TransferThis/, const char *name = 0, WFlags f = 0);
-
-private:
-    Hello(const Hello &);
-};
-
-%If (!WS_WIN)
-void setDefault(const TQString &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 TQObject 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 TQObject * that is a C++ instance of a class derived from Qt's -TQObject class.

-
-
-

6.3.10   SIP_RXOBJ_CON

-

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

-
-
-

6.3.11   SIP_RXOBJ_DIS

-

This is a TQObject * that is a C++ instance of a class derived from Qt's -TQObject class. It is used as the type of the receiver instead of const -TQObject * 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, TQAccel::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 TQObject *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<TQWidget *> instance to a Python -list of TQWidget 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 TQWidget.
-    for (int i = 0; i < sipCpp -> size(); ++i)
-    {
-        TQWidget *w = sipCpp -> at(i);
-        PyObject *wobj;
-
-        // Get the Python wrapper for the TQWidget 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 TQEvent based -class hierarchy in PyQt:

-
-class QEvent
-{
-%ConvertToSubClassCode
-    // TQEvent sub-classes provide a unique type ID.
-    switch (sipCpp -> type())
-    {
-    case TQEvent::Timer:
-        sipClass = sipClass_QTimerEvent;
-        break;
-
-    case TQEvent::KeyPress:
-    case TQEvent::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 TQString class to allow Python string objects and -unicode objects to be used wherever TQString 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 TQPoint instances to a -QList<TQPoint> 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 TQPoint, not of a pointer
-        // to a TQPoint, 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<TQPoint> *ql = new QList<TQPoint>;
-
-    for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
-    {
-        TQPoint *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<TQPoint *>(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 TQPoint 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 TQCustomEvent -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 TQCustomEvent 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 <tqlist.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<TQObject *> 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(TQWidget * /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 TQObject derived instance that emits the signal. -signal is the typed name of the signal. receiver is the wrapped -TQObject 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 TQObject.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 TQObject derived instance that emits the signal. -signal is the typed name of the signal. receiver is the wrapped -TQObject 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 TQObject.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 TQObject 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 TQObject.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 TQObject instance that emitted a Qt -signal. It is normally only used by PyQt to implement -TQObject.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.TQWidget).
-
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.

-
-
- - diff --git a/python/sip/doc/sipref.txt b/python/sip/doc/sipref.txt deleted file mode 100644 index 4e14f79e..00000000 --- a/python/sip/doc/sipref.txt +++ /dev/null @@ -1,5353 +0,0 @@ -===================================================================== - 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:: -.. section-numbering:: - - -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. - - -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. - - -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 - - -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`_. - - -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. - - -Potential Incompatibilities with Earlier Versions -================================================= - -SIP v4.4 --------- - - - The ``SIP_BUILD`` C preprocessor symbol has been removed. - - - `sipConvertToCpp()`_, `sipIsSubClassInstance()`_ and the old `Generated - Type Convertors`_ have been deprecated. The functions - `sipCanConvertToInstance()`_, `sipConvertToInstance()`_, - `sipForceConvertToInstance()`_, `sipConvertFromInstance()`_, - `sipConvertFromNewInstance()`_, `sipCanConvertToMappedType()`_, - `sipConvertToMappedType()`_, `sipForceConvertToMappedType()`_ and - `sipConvertFromMappedType()`_ should be used instead. Handwritten - `%ConvertFromTypeCode`_ and `%ConvertToTypeCode`_ now has the - responsibility for using these to implement the ``Transfer`` and - ``TransferBack`` annotations. - - -Installing SIP -============== - -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 `_. - - -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: - --h Display a help message. --a Export 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 dir The SIP code generator will be installed in the directory ``dir``. --d dir The SIP module will be installed in the directory ``dir``. --e dir The SIP header file will be installed in the directory ``dir``. --k The 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`_). --n The SIP code generator and module will be built as universal binaries - under MacOS/X. --p plat Explicitly 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. --u The SIP module will be built with debugging symbols. --v dir By 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`_. - - -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++ - - -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 - - -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. - - -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. - - -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 - %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 [#]_. 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 [#]_. - - - 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 [#]_:: - - 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. - -.. [#] All SIP directives start with a ``%`` as the first non-whitespace - character of a line. -.. [#] SIP includes many code directives like this. They differ in where the - supplied code is placed by SIP in the generated code. -.. [#] On Windows you might run ``nmake`` or ``mingw32-make`` instead. - - -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 - %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. - - -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 - #include - #include - - 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 - %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 [#]_ 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`` [#]_ - 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 [#]_. - -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. - -.. [#] Some parts of a SIP specification aren't subject to version control. -.. [#] Actually in ``versions.sip``. PyQt uses the `%Include`_ directive to - split the SIP specification for Qt across a large number of separate - ``.sip`` files. -.. [#] 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. - - -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()`_. - - -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. - - -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. - - -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: - --h Display a help message. --V Display the SIP version number. --a file - The 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 file - The 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 dir The 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 file - The 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. --e Support 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. --g The 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 dir The 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 number - The 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. --r Debugging statements that trace the execution of the bindings are - automatically generated. By default the statements are not generated. --s suffix - The suffix to use for generated C or C++ source files. By default - ``.c`` is used for C and ``.cpp`` for C++. --t tag The 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. --w The display of warning messages is enabled. By default warning - messages are disabled. --x feature - The feature (declared using the `%Feature`_ directive) is disabled. --z file - The name of a file containing more command line options. - - -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 - }; - - -Syntax Definition ------------------ - -The following is a semi-formal description of the syntax of a specification -file. - -.. parsed-literal:: - - *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``). - - -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. - - -Additional SIP Types --------------------- - -SIP supports a number of additional data types that can be used in Python -signatures. - - -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. - - -SIP_PYCALLABLE -************** - -This is a ``PyObject *`` that is a Python callable object. - - -SIP_PYDICT -********** - -This is a ``PyObject *`` that is a Python dictionary object. - - -SIP_PYLIST -********** - -This is a ``PyObject *`` that is a Python list object. - - -SIP_PYOBJECT -************ - -This is a ``PyObject *`` of any Python type. - - -SIP_PYSLICE -*********** - -This is a ``PyObject *`` that is a Python slice object. - - -SIP_PYTUPLE -*********** - -This is a ``PyObject *`` that is a Python tuple object. - - -SIP_PYTYPE -********** - -This is a ``PyObject *`` that is a Python type object. - - -SIP_QOBJECT -*********** - -This is a ``QObject *`` that is a C++ instance of a class derived from Qt's -``QObject`` class. - - -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. - - -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. - - -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. - - -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. - - -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)); - - -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. - - -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``. - - -%AccessCode ------------ - -.. parsed-literal:: - - %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 - - -%BIGetCharBufferCode --------------------- - -.. parsed-literal:: - - %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``. - - -%BIGetReadBufferCode --------------------- - -.. parsed-literal:: - - %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``. - - -%BIGetSegCountCode ------------------- - -.. parsed-literal:: - - %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``. - - -%BIGetWriteBufferCode ---------------------- - -.. parsed-literal:: - - %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``. - - -%CModule --------- - -.. parsed-literal:: - - %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 - - -%ConvertFromTypeCode --------------------- - -.. parsed-literal:: - - %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`` 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 - - -%ConvertToSubClassCode ----------------------- - -.. parsed-literal:: - - %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. - - -%ConvertToTypeCode ------------------- - -.. parsed-literal:: - - %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`` 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 *ql = new QList; - - 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(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. - - -%Copying --------- - -.. parsed-literal:: - - %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 - - -%Doc ----- - -.. parsed-literal:: - - %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 -

An Example

-

- This fragment of documentation is HTML and is local to the module in - which it is defined. -

- %End - - -%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. - - -%Exception ----------- - -.. parsed-literal:: - - %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 - %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``. - - -%ExportedDoc ------------- - -.. parsed-literal:: - - %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 - - -%ExportedHeaderCode -------------------- - -.. parsed-literal:: - - %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`_. - - -%Feature --------- - -.. parsed-literal:: - - %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 - - -%GCClearCode ------------- - -.. parsed-literal:: - - %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(sipCpp -> data()); - - // Clear the pointer. - sipCpp -> setData(0); - - // Clear the reference. - Py_XDECREF(obj); - - // Report no error. - sipRes = 0; - %End - - -%GCTraverseCode ---------------- - -.. parsed-literal:: - - %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(sipCpp -> data()); - - // Call the visit function if there was an object. - if (obj) - sipRes = sipVisit(obj, sipArg); - else - sipRes = 0; - %End - - -%GetCode --------- - -.. parsed-literal:: - - %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 - } - - -%If ---- - -.. parsed-literal:: - - %If (*expression*) - *specification* - %End - -where - -.. parsed-literal:: - - *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: - - - ``class`` - - `%ConvertFromTypeCode`_ - - `%ConvertToSubClassCode`_ - - `%ConvertToTypeCode`_ - - ``enum`` - - `%ExportedHeaderCode`_ - - functions - - `%GCClearCode`_ - - `%GCTraverseCode`_ - - `%If`_ - - `%MappedType`_ - - `%MethodCode`_ - - `%ModuleCode`_ - - `%ModuleHeaderCode`_ - - ``namespace`` - - `%PostInitialisationCode`_ - - `%PreInitialisationCode`_ - - ``struct`` - - ``typedef`` - - `%TypeCode`_ - - `%TypeHeaderCode`_ - - `%UnitCode`_ - - variables - - `%VirtualCatcherCode`_ - -Also note that the only way to specify the logical and of qualifiers is to use -nested `%If`_ directives. - - -%Import -------- - -.. parsed-literal:: - - %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 - - -%Include --------- - -.. parsed-literal:: - - %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 - - -%License --------- - -.. parsed-literal:: - - %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"/ - - -%MappedType ------------ - -.. parsed-literal:: - - 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 - %MappedType QList - { - %TypeHeaderCode - // Include the library interface to the type being mapped. - #include - %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 *ql = new QList; - - 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(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`` 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. - - -%MethodCode ------------ - -.. parsed-literal:: - - %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 [#]_, 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); - -.. [#] See `%VirtualCatcherCode`_ for a description of how SIP generated code - handles the reimplementation of C++ virtual methods in Python. - - -%Module -------- - -.. parsed-literal:: - - %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 - - -%ModuleCode ------------ - -.. parsed-literal:: - - %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`_. - - -%ModuleHeaderCode ------------------ - -.. parsed-literal:: - - %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`_. - - -%OptionalInclude ----------------- - -.. parsed-literal:: - - %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 - - -%Platforms ----------- - -.. parsed-literal:: - - %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 - - -%PostInitialisationCode ------------------------ - -.. parsed-literal:: - - %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 - - -%PreInitialisationCode ----------------------- - -.. parsed-literal:: - - %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 - - -%RaiseCode ----------- - -.. parsed-literal:: - - %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. - - -%SetCode --------- - -.. parsed-literal:: - - %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. - - -%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. - - -%Timeline ---------- - -.. parsed-literal:: - - %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. - - -%TypeCode ---------- - -.. parsed-literal:: - - %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. - - -%TypeHeaderCode ---------------- - -.. parsed-literal:: - - %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 - %End - - // The rest of the class specification. - }; - - -%UnitCode ---------- - -.. parsed-literal:: - - %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. - - -%VirtualCatcherCode -------------------- - -.. parsed-literal:: - - %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 - }; - - -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. - - -Argument Annotations --------------------- - -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``. - - -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. - - -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. - - -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); - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -Class Annotations ------------------ - -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. - - -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. - - -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. - - -NoDefaultCtors -************** - -This boolean annotation is used to suppress the automatic generation of default -constructors for the class. - - -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. - - -Enum Annotations ----------------- - -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. - - -Exception Annotations ---------------------- - -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. - - -Function Annotations --------------------- - -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. - - -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. - - -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. - - -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. - - -NewThread -********* - -This boolean annotation specifies that the function will create a new thread. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -License Annotations -------------------- - -Licensee -******** - -This optional string annotation specifies the license's licensee. No -restrictions are placed on the contents of the string. - -See the `%License`_ directive. - - -Signature -********* - -This optional string annotation specifies the license's signature. No -restrictions are placed on the contents of the string. - -See the `%License`_ directive. - - -Timestamp -********* - -This optional string annotation specifies the license's timestamp. No -restrictions are placed on the contents of the string. - -See the `%License`_ directive. - - -Type -**** - -This string annotation specifies the license's type. No restrictions are -placed on the contents of the string. - -See the `%License`_ directive. - - -Variable Annotations --------------------- - -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. - - -SIP API for Handwritten Code -============================ - -In this section we describe the API that can be used by handwritten code in -specification files. - - -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. - - -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. - - -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. - - -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. - - -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`_. - - -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``). - - -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-``. - - -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``. - - -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``. - - -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. - - -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``. - - -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*. - - -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``. - - -sipClassName() --------------- - -PyObject \*sipClassName(PyObject \*obj) - This returns the class name of a wrapped instance as a Python string. It - comes with a reference. - - -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()``. - - -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. - - -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()`_. - - -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`_). - - -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. - - -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``. - - -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. - - -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); - - -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.) - - -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.) - - -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()``. - - -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()``. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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()``. - - -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. - - -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. - - -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. - - -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); - - -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. - - -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()`_. - - -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*. - - -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*. - - -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. - - -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. - - -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. - - -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. - - -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); - - -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. - - -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++. - - -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. - - -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. - - -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``). - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -``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. - - -``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()``. - - -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. - - -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.3