You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5354 lines
188 KiB
5354 lines
188 KiB
=====================================================================
|
|
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 <http://www.python.org>`__ bindings for C and
|
|
C++ libraries. SIP was originally developed in 1998 for
|
|
`PyQt <http://www.riverbankcomputing.co.uk/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 <http://www.swig.org>`__ 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 <http://sourceforge.net/project/showfiles.php?group_id=61057>`_.
|
|
|
|
|
|
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 <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 [#]_. 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 <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.
|
|
|
|
|
|
A More Complex C++ Example
|
|
--------------------------
|
|
|
|
In this last example we will wrap a fictional C++ library that contains a class
|
|
that is derived from a Qt class. This will demonstrate how SIP allows a class
|
|
hierarchy to be split across multiple Python extension modules, and will
|
|
introduce SIP's versioning system.
|
|
|
|
The library contains a single C++ class called ``Hello`` which is derived from
|
|
Qt's ``QLabel`` class. It behaves just like ``QLabel`` except that the text
|
|
in the label is hard coded to be ``Hello World``. To make the example more
|
|
interesting we'll also say that the library only supports Qt v3.0 and later,
|
|
and also includes a function called ``setDefault()`` that is not implemented
|
|
in the Windows version of the library.
|
|
|
|
The ``hello.h`` header file looks something like this::
|
|
|
|
// Define the interface to the hello library.
|
|
|
|
#include <qlabel.h>
|
|
#include <qwidget.h>
|
|
#include <qstring.h>
|
|
|
|
class Hello : public QLabel {
|
|
// This is needed by the Qt Meta-Object Compiler.
|
|
Q_OBJECT
|
|
|
|
public:
|
|
Hello(QWidget *parent, const char *name = 0, WFlags f = 0);
|
|
|
|
private:
|
|
// Prevent instances from being copied.
|
|
Hello(const Hello &);
|
|
Hello &operator=(const Hello &);
|
|
};
|
|
|
|
#if !defined(Q_OS_WIN)
|
|
void setDefault(const QString &def);
|
|
#endif
|
|
|
|
The corresponding SIP specification file would then look something like this::
|
|
|
|
// Define the SIP wrapper to the hello library.
|
|
|
|
%Module hello 0
|
|
|
|
%Import qt/qtmod.sip
|
|
|
|
%If (Qt_3_0_0 -)
|
|
|
|
class Hello : QLabel {
|
|
|
|
%TypeHeaderCode
|
|
#include <hello.h>
|
|
%End
|
|
|
|
public:
|
|
Hello(QWidget *parent /TransferThis/, const char *name = 0, WFlags f = 0);
|
|
|
|
private:
|
|
Hello(const Hello &);
|
|
};
|
|
|
|
%If (!WS_WIN)
|
|
void setDefault(const QString &def);
|
|
%End
|
|
|
|
%End
|
|
|
|
Again we look at the differences, but we'll skip those that we've looked at in
|
|
previous examples.
|
|
|
|
- The `%Import`_ directive has been added to specify that we are extending
|
|
the class hierarchy defined in the file ``qt/qtmod.sip``. This file is
|
|
part of PyQt. The build system will take care of finding the file's
|
|
exact location.
|
|
|
|
- The `%If`_ directive has been added to specify that
|
|
everything [#]_ 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
|
|
<http://www.python.org/dev/doc/devel/api/buffer-structs.html>`__ 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<QWidget *>`` instance to a Python
|
|
list of ``QWidget`` instances::
|
|
|
|
%ConvertFromTypeCode
|
|
PyObject *l;
|
|
|
|
// Create the Python list of the correct length.
|
|
if ((l = PyList_New(sipCpp -> size())) == NULL)
|
|
return NULL;
|
|
|
|
// Go through each element in the C++ instance and convert it to a
|
|
// wrapped QWidget.
|
|
for (int i = 0; i < sipCpp -> size(); ++i)
|
|
{
|
|
QWidget *w = sipCpp -> at(i);
|
|
PyObject *wobj;
|
|
|
|
// Get the Python wrapper for the QWidget instance, creating a new
|
|
// one if necessary, and handle any ownership transfer.
|
|
if ((wobj = sipConvertFromInstance(w, sipClass_QWidget, sipTransferObj)) == NULL)
|
|
{
|
|
// There was an error so garbage collect the Python list.
|
|
Py_DECREF(l);
|
|
return NULL;
|
|
}
|
|
|
|
// Add the wrapper to the list.
|
|
PyList_SET_ITEM(l, i, wobj);
|
|
}
|
|
|
|
// Return the Python list.
|
|
return l;
|
|
%End
|
|
|
|
|
|
%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<QPoint>`` instance::
|
|
|
|
%ConvertToTypeCode
|
|
// See if we are just being asked to check the type of the Python
|
|
// object.
|
|
if (!sipIsErr)
|
|
{
|
|
// Checking whether or not None has been passed instead of a list
|
|
// has already been done.
|
|
if (!PyList_Check(sipPy))
|
|
return 0;
|
|
|
|
// Check the type of each element. We specify SIP_NOT_NONE to
|
|
// disallow None because it is a list of QPoint, not of a pointer
|
|
// to a QPoint, so None isn't appropriate.
|
|
for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
|
|
if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i),
|
|
sipClass_QPoint, SIP_NOT_NONE))
|
|
return 0;
|
|
|
|
// The type is valid.
|
|
return 1;
|
|
}
|
|
|
|
// Create the instance on the heap.
|
|
QList<QPoint> *ql = new QList<QPoint>;
|
|
|
|
for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
|
|
{
|
|
QPoint *qp;
|
|
int state;
|
|
|
|
// Get the address of the element's C++ instance. Note that, in
|
|
// this case, we don't apply any ownership changes to the list
|
|
// elements, only to the list itself.
|
|
qp = reinterpret_cast<QPoint *>(sipConvertToInstance(
|
|
PyList_GET_ITEM(sipPy, i),
|
|
sipClass_QPoint, 0,
|
|
SIP_NOT_NONE,
|
|
&state, sipIsErr));
|
|
|
|
// Deal with any errors.
|
|
if (*sipIsErr)
|
|
{
|
|
sipReleaseInstance(qp, sipClass_QPoint, state);
|
|
|
|
// Tidy up.
|
|
delete ql;
|
|
|
|
// There is no temporary instance.
|
|
return 0;
|
|
}
|
|
|
|
ql -> append(*qp);
|
|
|
|
// A copy of the QPoint was appended to the list so we no longer
|
|
// need it. It may be a temporary instance that should be
|
|
// destroyed, or a wrapped instance that should not be destroyed.
|
|
// sipReleaseInstance() will do the right thing.
|
|
sipReleaseInstance(qp, sipClass_QPoint, state);
|
|
}
|
|
|
|
// Return the instance.
|
|
*sipCppPtr = ql;
|
|
|
|
// The instance should be regarded as temporary (and be destroyed as
|
|
// soon as it has been used) unless it has been transferred from
|
|
// Python. sipGetState() is a convenience function that implements
|
|
// this common transfer behaviour.
|
|
return sipGetState(sipTransferObj);
|
|
%End
|
|
|
|
When used in a class specification the handwritten code replaces the code that
|
|
would normally be automatically generated. This means that the handwritten
|
|
code must also handle instances of the class itself and not just the additional
|
|
types that are being supported. This should be done by making calls to
|
|
`sipCanConvertToInstance()`_ to check the object type and
|
|
`sipConvertToInstance()`_ to convert the object. The ``SIP_NO_CONVERTORS``
|
|
flag *must* be passed to both these functions to prevent recursive calls to the
|
|
handwritten code.
|
|
|
|
|
|
%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
|
|
<h1>An Example</h1>
|
|
<p>
|
|
This fragment of documentation is HTML and is local to the module in
|
|
which it is defined.
|
|
</p>
|
|
%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 <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``.
|
|
|
|
|
|
%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 <http://www.python.org/dev/doc/devel/ext/>`__
|
|
for the details.
|
|
|
|
This directive is used to specify the code that clears any embedded references.
|
|
(See `%GCTraverseCode`_ for specifying the code that traverses any embedded
|
|
references.)
|
|
|
|
The following variables are made available to the handwritten code:
|
|
|
|
*type* \*sipCpp
|
|
This is a pointer to the structure or class instance. Its *type* is a
|
|
pointer to the structure or class.
|
|
|
|
int sipRes
|
|
The handwritten code should set this to the result to be returned.
|
|
|
|
The following simplified example is taken from PyQt. The ``QCustomEvent``
|
|
class allows arbitary data to be attached to the event. In PyQt this data is
|
|
always a Python object and so should be handled by the garbage collector::
|
|
|
|
%GCClearCode
|
|
PyObject *obj;
|
|
|
|
// Get the object.
|
|
obj = reinterpret_cast<PyObject *>(sipCpp -> data());
|
|
|
|
// Clear the pointer.
|
|
sipCpp -> setData(0);
|
|
|
|
// Clear the reference.
|
|
Py_XDECREF(obj);
|
|
|
|
// Report no error.
|
|
sipRes = 0;
|
|
%End
|
|
|
|
|
|
%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<PyObject *>(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<Type *>
|
|
%MappedType QList
|
|
{
|
|
%TypeHeaderCode
|
|
// Include the library interface to the type being mapped.
|
|
#include <qlist.h>
|
|
%End
|
|
|
|
%ConvertToTypeCode
|
|
// See if we are just being asked to check the type of the Python
|
|
// object.
|
|
if (sipIsErr == NULL)
|
|
{
|
|
// Check it is a list.
|
|
if (!PyList_Check(sipPy))
|
|
return 0;
|
|
|
|
// Now check each element of the list is of the type we expect.
|
|
// The template is for a pointer type so we don't disallow None.
|
|
for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
|
|
if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i),
|
|
sipClass_Type, 0))
|
|
return 0;
|
|
|
|
return 1;
|
|
}
|
|
|
|
// Create the instance on the heap.
|
|
QList<Type *> *ql = new QList<Type *>;
|
|
|
|
for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
|
|
{
|
|
// Use the SIP API to convert the Python object to the
|
|
// corresponding C++ instance. Note that we apply any ownership
|
|
// transfer to the list itself, not the individual elements.
|
|
Type *t = reinterpret_cast<Type *>(sipConvertToInstance(
|
|
PyList_GET_ITEM(sipPy, i),
|
|
sipClass_Type, 0, 0, 0,
|
|
sipIsErr));
|
|
|
|
if (*sipIsErr)
|
|
{
|
|
// Tidy up.
|
|
delete ql;
|
|
|
|
// There is nothing on the heap.
|
|
return 0;
|
|
}
|
|
|
|
// Add the pointer to the C++ instance.
|
|
ql -> append(t);
|
|
}
|
|
|
|
// Return the instance on the heap.
|
|
*sipCppPtr = ql;
|
|
|
|
// Apply the normal transfer.
|
|
return sipGetState(sipTransferObj);
|
|
%End
|
|
|
|
%ConvertFromTypeCode
|
|
PyObject *l;
|
|
|
|
// Create the Python list of the correct length.
|
|
if ((l = PyList_New(sipCpp -> size())) == NULL)
|
|
return NULL;
|
|
|
|
// Go through each element in the C++ instance and convert it to the
|
|
// corresponding Python object.
|
|
for (int i = 0; i < sipCpp -> size(); ++i)
|
|
{
|
|
Type *t = sipCpp -> at(i);
|
|
PyObject *tobj;
|
|
|
|
if ((tobj = sipConvertFromInstance(t, sipClass_Type, sipTransferObj)) == NULL)
|
|
{
|
|
// There was an error so garbage collect the Python list.
|
|
Py_DECREF(l);
|
|
return NULL;
|
|
}
|
|
|
|
PyList_SET_ITEM(l, i, tobj);
|
|
}
|
|
|
|
// Return the Python list.
|
|
return l;
|
|
%End
|
|
}
|
|
|
|
Using this we can use, for example, ``QList<QObject *>`` throughout the
|
|
module's specification files (and in any module that imports this one). The
|
|
generated code will automatically map this to and from a Python list of QObject
|
|
instances when appropriate.
|
|
|
|
|
|
%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 <klass.h>
|
|
%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 <http://www.python.org/sigs/distutils-sig/distutils.html>`_ and
|
|
`SCons <http://www.scons.org>`_).
|
|
|
|
An important feature of SIP is the ability to generate bindings that are built
|
|
on top of existing bindings. For example, both
|
|
`PyKDE <http://www.riverbankcomputing.co.uk/pykde/>`_ and
|
|
`PyQwt <http://pyqwt.sourceforge.net/>`_ 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 <http://www.riverbankcomputing.co.uk/vendorid/>`__ package.
|