Initial import of SIP4 for Qt3

1 files changed, 2109 insertions, 0 deletions

diff --git a/doc/html/_sources/directives.txt b/doc/html/_sources/directives.txt
new file mode 100644
index 0000000..7e3a2e0
--- /dev/null
+++ b/doc/html/_sources/directives.txt
@@ -0,0 +1,2109 @@
+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``.
+
+
+.. directive:: %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
+
+
+.. directive:: %API
+
+.. versionadded:: 4.9
+
+.. parsed-literal::
+
+    %API *name* *version*
+
+This directive is used to define an API and set its default version number.  A
+version number must be greater than or equal to 1.
+
+See :ref:`ref-incompat-apis` for more detail.
+
+For example::
+
+    %API PyQt4 1
+
+
+.. directive:: %BIGetBufferCode
+
+.. parsed-literal::
+
+    %BIGetBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIReleaseBufferCode`) is used to
+specify code that implements the buffer interface of Python v3.  If Python v2
+is being used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+Py_buffer \*sipBuffer
+    This is a pointer to the Python buffer structure that the handwritten code
+    must populate.
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+int sipFlags
+    These are the flags that specify what elements of the ``sipBuffer``
+    structure must be populated.
+
+int sipRes
+    The handwritten code should set this to 0 if there was no error or -1 if
+    there was an error.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetCharBufferCode
+
+.. parsed-literal::
+
+    %BIGetCharBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetReadBufferCode`,
+:directive:`%BIGetSegCountCode` and :directive:`%BIGetWriteBufferCode`) is used
+to specify code that implements the buffer interface of Python v2.  If Python
+v3 is being used then this is ignored.
+
+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.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the length of the character buffer
+    or -1 if there was an error.
+
+:cmacro:`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 structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetReadBufferCode
+
+.. parsed-literal::
+
+    %BIGetReadBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetCharBufferCode`,
+:directive:`%BIGetSegCountCode` and :directive:`%BIGetWriteBufferCode`) is used
+to specify code that implements the buffer interface of Python v2.  If
+Python v3 is being used then this is ignored.
+
+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.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the length of the read buffer or
+    -1 if there was an error.
+
+:cmacro:`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 structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetSegCountCode
+
+.. parsed-literal::
+
+    %BIGetSegCountCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetCharBufferCode`,
+:directive:`%BIGetReadBufferCode` and :directive:`%BIGetWriteBufferCode`) is
+used to specify code that implements the buffer interface of Python v2.  If
+Python v3 is being used then this is ignored.
+
+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.
+
+:cmacro:`SIP_SSIZE_T` \*sipLenPtr
+    This is the pointer used to return the total length in bytes of all
+    segments of the buffer.
+
+:cmacro:`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 structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIGetWriteBufferCode
+
+.. parsed-literal::
+
+    %BIGetWriteBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetCharBufferCode`,
+:directive:`%BIGetReadBufferCode` and :directive:`%BIGetSegCountCode` is used
+to specify code that implements the buffer interface of Python v2.  If Python
+v3 is being used then this is ignored.
+
+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.
+
+:cmacro:`SIP_SSIZE_T` sipRes
+    The handwritten code should set this to the length of the write buffer or
+    -1 if there was an error.
+
+:cmacro:`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 structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %BIReleaseBufferCode
+
+.. parsed-literal::
+
+    %BIReleaseBufferCode
+        *code*
+    %End
+
+This directive (along with :directive:`%BIGetBufferCode`) is used to specify
+code that implements the buffer interface of Python v3.  If Python v2 is being
+used then this is ignored.
+
+The following variables are made available to the handwritten code:
+
+Py_buffer \*sipBuffer
+    This is a pointer to the Python buffer structure.
+
+*type* \*sipCpp
+    This is a pointer to the structure or class instance.  Its *type* is a
+    pointer to the structure or class.
+
+PyObject \*sipSelf
+    This is the Python object that wraps the structure or class instance, i.e.
+    ``self``.
+
+
+.. directive:: %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 :directive:`%Module` directive for an explanation of the version
+number.
+
+For example::
+
+    %CModule dbus 1
+
+
+.. directive:: %CompositeModule
+
+.. parsed-literal::
+
+    %CompositeModule *name*
+
+A composite module is one that merges a number of related SIP generated
+modules.  For example, a module that merges the modules ``a_mod``, ``b_mod``
+and ``c_mod`` is equivalent to the following pure Python module::
+
+    from a_mod import *
+    from b_mod import *
+    from c_mod import *
+
+Clearly the individual modules should not define module-level objects with the
+same name.
+
+This directive is used to specify the name of a composite module.  Any
+subsequent :directive:`%CModule` or :directive:`%Module` directive is
+interpreted as defining a component module.
+
+For example::
+
+    %CompositeModule PyQt4.Qt
+    %Include QtCore/QtCoremod.sip
+    %Include QtGui/QtGuimod.sip
+
+The main purpose of a composite module is as a programmer convenience as they
+don't have to remember which which individual module an object is defined in.
+
+
+.. directive:: %ConsolidatedModule
+
+.. parsed-literal::
+
+    %ConsolidatedModule *name*
+
+A consolidated module is one that consolidates the wrapper code of a number of
+SIP generated modules (refered to as component modules in this context).
+
+This directive is used to specify the name of a consolidated module.  Any
+subsequent :directive:`%CModule` or :directive:`%Module` directive is
+interpreted as defining a component module.
+
+For example::
+
+    %ConsolidatedModule PyQt4._qt
+    %Include QtCore/QtCoremod.sip
+    %Include QtGui/QtGuimod.sip
+
+A consolidated module is not intended to be explicitly imported by an
+application.  Instead it is imported by its component modules when they
+themselves are imported.
+
+Normally the wrapper code is contained in the component module and is linked
+against the corresponding C or C++ library.  The advantage of a consolidated
+module is that it allows all of the wrapped C or C++ libraries to be linked
+against a single module.  If the linking is done statically then deployment of
+generated modules can be greatly simplified.
+
+It follows that a component module can be built in one of two ways, as a
+normal standalone module, or as a component of a consolidated module.  When
+building as a component the ``-p`` command line option should be used to
+specify the name of the consolidated module.
+
+
+.. directive:: %ConvertFromTypeCode
+
+.. parsed-literal::
+
+    %ConvertFromTypeCode
+        *code*
+    %End
+
+This directive is used as part of the :directive:`%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 = sipConvertFromType(w, sipType_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
+
+
+.. directive:: %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.
+
+const sipTypeDef \*sipType
+    The handwritten code must set this to the SIP generated type structure
+    that corresponds to the class instance.  (The type structure for class
+    ``Klass`` is ``sipType_Klass``.)  If the RTTI of the class instance isn't
+    recognised then ``sipType`` must be set to ``NULL``.  The code doesn't
+    have to recognise the exact class, only the most specific sub-class that
+    it can.
+
+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.
+
+    This is deprecated from SIP v4.8.  Instead you should use ``sipType``.
+
+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:
+            sipType = sipType_QTimerEvent;
+            break;
+
+        case QEvent::KeyPress:
+        case QEvent::KeyRelease:
+            sipType = sipType_QKeyEvent;
+            break;
+
+        // Skip the remaining event types to keep the example short.
+
+        default:
+            // We don't recognise the type.
+            sipType = NULL;
+        }
+    %End
+
+        // The rest of the class specification.
+
+    };
+
+
+.. directive:: %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 :directive:`%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.
+
+        - :cmacro:`SIP_TEMPORARY` is set to indicate that the returned instance
+          is a temporary and should be released to avoid a memory leak.
+
+        - :cmacro:`SIP_DERIVED_CLASS` is set to indicate that the type of the
+          returned instance is a derived class.  See
+          :ref:`ref-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 (!sipCanConvertToType(PyList_GET_ITEM(sipPy, i),
+                                         sipType_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 *>(sipConvertToType(
+                                                    PyList_GET_ITEM(sipPy, i),
+                                                    sipType_QPoint, 0,
+                                                    SIP_NOT_NONE,
+                                                    &state, sipIsErr));
+
+            // Deal with any errors.
+            if (*sipIsErr)
+            {
+                sipReleaseType(qp, sipType_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.
+            // sipReleaseType() will do the right thing.
+            sipReleaseType(qp, sipType_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
+:cfunc:`sipCanConvertToType()` to check the object type and
+:cfunc:`sipConvertToType()` to convert the object.  The
+:cmacro:`SIP_NO_CONVERTORS` flag *must* be passed to both these functions to
+prevent recursive calls to the handwritten code.
+
+
+.. directive:: %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) 2009 Riverbank Computing Limited
+    %End
+
+
+.. directive:: %DefaultEncoding
+
+.. parsed-literal::
+
+    %DefaultEncoding *string*
+
+This directive is used to specify the default encoding used for ``char``,
+``const char``, ``char *`` or ``const char *`` values.  The encoding can be
+either ``"ASCII"``, ``"Latin-1"``, ``"UTF-8"`` or ``"None"``.  An encoding of
+``"None"`` means that the value is unencoded.  The default can be overridden
+for a particular value using the :aanno:`Encoding` annotation.  If the
+directive is not specified then ``"None"`` is used.
+
+For example::
+
+    %DefaultEncoding "Latin-1"
+
+
+.. directive:: %DefaultMetatype
+
+.. parsed-literal::
+
+    %DefaultMetatype *dotted-name*
+
+This directive is used to specify the Python type that should be used as the
+meta-type for any C/C++ data type defined in the same module, and by importing
+modules, that doesn't have an explicit meta-type.
+
+If this is not specified then ``sip.wrappertype`` is used.
+
+You can also use the :canno:`Metatype` class annotation to specify the
+meta-type used by a particular C/C++ type.
+
+See the section :ref:`ref-types-metatypes` for more details.
+
+For example::
+
+    %DefaultMetatype PyQt4.QtCore.pyqtWrapperType
+
+
+.. directive:: %DefaultSupertype
+
+.. parsed-literal::
+
+    %DefaultSupertype *dotted-name*
+
+This directive is used to specify the Python type that should be used as the
+super-type for any C/C++ data type defined in the same module that doesn't have
+an explicit super-type.
+
+If this is not specified then ``sip.wrapper`` is used.
+
+You can also use the :canno:`Supertype` class annotation to specify the
+super-type used by a particular C/C++ type.
+
+See the section :ref:`ref-types-metatypes` for more details.
+
+For example::
+
+    %DefaultSupertype sip.simplewrapper
+
+
+.. directive:: %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 :directive:`%Import` it.  Use
+the :directive:`%ExportedDoc` directive for documentation that should be
+included by all modules that :directive:`%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
+
+
+.. directive:: %Docstring
+
+.. parsed-literal::
+
+    %Docstring
+        *text*
+    %End
+
+.. versionadded:: 4.10
+
+This directive is used to specify explicit docstrings for classes, functions
+and methods.
+
+The docstring of a class is made up of the docstring specified for the class
+itself, with the docstrings specified for each contructor appended.
+
+The docstring of a function or method is made up of the concatenated docstrings
+specified for each of the overloads.
+
+Specifying an explicit docstring will prevent SIP from generating an automatic
+docstring that describes the Python signature of a function or method overload.
+This means that SIP will generate less informative exceptions (i.e. without a
+full signature) when it fails to match a set of arguments to any function or
+method overload.
+
+For example::
+
+    class Klass
+    {
+    %Docstring
+    This will be at the start of the class's docstring.
+    %End
+
+    public:
+        Klass();
+    %Docstring
+    This will be appended to the class's docstring.
+    %End
+    };
+
+
+.. directive:: %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.
+
+
+.. directive:: %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
+:directive:`%Exception` directive.
+
+*header-code* is the optional :directive:`%TypeHeaderCode` used to specify any
+external interface to the exception being defined.
+
+*raise-code* is the :directive:`%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 = sipExceptionRef.what();
+
+            SIP_BLOCK_THREADS
+            PyErr_SetString(sipException_std_exception, 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``.
+
+An exception may be annotated with :xanno:`Default` to specify that it should
+be caught by default if there is no ``throw`` clause.
+
+
+.. directive:: %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 :directive:`%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
+
+
+.. directive:: %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 :directive:`%ModuleCode` and :directive:`%ModuleHeaderCode`.
+
+
+.. directive:: %Feature
+
+.. parsed-literal::
+
+    %Feature *name*
+
+This directive is used to declare a feature.  Features (along with
+:directive:`%Platforms` and :directive:`%Timeline`) are used by the
+:directive:`%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
+
+
+.. directive:: %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 :directive:`%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
+
+
+.. directive:: %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
+:directive:`%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
+
+
+.. directive:: %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``.
+
+PyObject \*sipPyType
+    If the variable being wrapped is a static class variable then this is the
+    Python type object of the class from which the variable was referenced
+    (*not* the class in which it is defined).  It may be safely cast to a
+    PyTypeObject \* or a sipWrapperType \*.
+
+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
+    }
+
+
+.. directive:: %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
+:directive:`%Feature`), platforms (see :directive:`%Platforms`) and versions
+(see :directive:`%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:
+
+    - :directive:`%API`
+    - ``class``
+    - :directive:`%ConvertFromTypeCode`
+    - :directive:`%ConvertToSubClassCode`
+    - :directive:`%ConvertToTypeCode`
+    - ``enum``
+    - :directive:`%DefaultEncoding`
+    - :directive:`%DefaultMetatype`
+    - :directive:`%DefaultSupertype`
+    - :directive:`%ExportedHeaderCode`
+    - functions
+    - :directive:`%GCClearCode`
+    - :directive:`%GCTraverseCode`
+    - :directive:`%If`
+    - :directive:`%InitialisationCode`
+    - :directive:`%MappedType`
+    - :directive:`%MethodCode`
+    - :directive:`%ModuleCode`
+    - :directive:`%ModuleHeaderCode`
+    - ``namespace``
+    - :directive:`%PostInitialisationCode`
+    - :directive:`%PreInitialisationCode`
+    - ``struct``
+    - ``typedef``
+    - :directive:`%TypeCode`
+    - :directive:`%TypeHeaderCode`
+    - :directive:`%UnitCode`
+    - variables
+    - :directive:`%VirtualCatcherCode`
+
+Also note that the only way to specify the logical and of qualifiers is to use
+nested :directive:`%If` directives.
+
+
+.. directive:: %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 :directive:`%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
+
+
+.. directive:: %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.
+
+:directive:`%Include` follows the same search process as :directive:`%Import`
+when trying to open *filename*.
+
+For example::
+
+    %Include qwidget.sip
+
+
+.. directive:: %InitialisationCode
+
+.. parsed-literal::
+
+    %InitialisationCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code that is embedded in-line
+in the generated module initialisation code after the SIP module has been
+imported but before the module itself has been initialised.
+
+It is typically used to call :cfunc:`sipRegisterPyType()`.
+
+For example::
+
+    %InitialisationCode
+        // The code will be executed when the module is first imported, after
+        // the SIP module has been imported, but before other module-specific
+        // initialisation has been completed.
+    %End
+
+
+.. directive:: %License
+
+.. parsed-literal::
+
+    %License /*license-annotations*/
+
+This directive is used to specify the contents of an optional license
+dictionary.  The license dictionary is called :data:`__license__` and is stored
+in the module dictionary.  The elements of the dictionary are specified using
+the :lanno:`Licensee`, :lanno:`Signature`, :lanno:`Timestamp` and :lanno:`Type`
+annotations.  Only the :lanno:`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"/
+
+
+.. directive:: %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 :directive:`%TypeHeaderCode` used to specify the library
+interface to the type being mapped.
+
+*convert-to-code* is the :directive:`%ConvertToTypeCode` used to specify the
+handwritten code that converts a Python object to an instance of the mapped
+type.
+
+*convert-from-code* is the :directive:`%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 (!sipCanConvertToType(PyList_GET_ITEM(sipPy, i),
+                                         sipType_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 *>(sipConvertToType(
+                                                PyList_GET_ITEM(sipPy, i),
+                                                sipType_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 = sipConvertFromType(t, sipType_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.
+
+
+.. directive:: %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.
+
+Normally 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.  In this case the specified code must not include any ``return``
+statements.
+
+However if the :fanno:`NoArgParser` annotation has been used then the specified
+code is also responsible for parsing the arguments.  No other code is generated
+by SIP and the specified code must include a ``return`` statement.
+
+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 :ref:`ref-gil` and the
+:fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations.)
+
+If the :fanno:`NoArgParser` annotation has not been used then 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 :aanno:`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 :aanno:`GetWrapper` annotation
+    is specified for the corresponding argument.  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.  If it is
+    set to ``0`` and no Python exception is raised then SIP will continue to
+    try other Python signatures.
+    
+    If the directive is used in the context of a method (but not the standard
+    binary operator methods, e.g. :meth:`__add__`) or a destructor then this is
+    a pointer to the C structure or C++ class instance.
+    
+    Its *type* is a pointer to the structure or class.
+    
+    Standard binary operator methods follow the same convention as global
+    functions and instead define two arguments called ``a0`` and ``a1``.
+
+sipErrorState sipError
+    The handwritten code should set this to either ``sipErrorContinue`` or
+    ``sipErrorFail``, and raise an appropriate Python exception, if an error
+    is detected.  Its initial value will be ``sipErrorNone``.
+
+    When ``sipErrorContinue`` is used, SIP will remember the exception as the
+    reason why the particular overloaded callable could not be invoked.  It
+    will then continue to try the next overloaded callable.  It is typically
+    used by code that needs to do additional type checking of the callable's
+    arguments.
+
+    When ``sipErrorFail1`` is used, SIP will report the exception immediately
+    and will not attempt to invoke other overloaded callables.
+
+    ``sipError`` is not provided for destructors.
+
+int sipIsErr
+    The handwritten code should set this to a non-zero value, and raise an
+    appropriate Python exception, if an error is detected.  This is the
+    equivalent of setting ``sipError`` to ``sipErrorFail``.  Its initial value
+    will be ``0``.
+
+    ``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
+    :meth:`__imul__`) as their results are handled automatically, nor for class
+    constructors or destructors.
+
+PyObject \*sipSelf
+    If the directive is used in the context of a class constructor, destructor
+    or method then this is the Python object that wraps 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(...)
+
+If the :fanno:`NoArgParser` annotation has been used then only the following
+variables are made available to the handwritten code:
+
+PyObject \*sipArgs
+    This is the tuple of arguments.
+
+PyObject \*sipKwds
+    This is the dictionary of keyword arguments.
+
+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 SIP generates
+helpers that provide access to method.  However, these are not available if
+the Python module is being built with ``protected`` redefined as ``public``.
+
+The following pattern should be used to cover all possibilities::
+
+    #if defined(SIP_PROTECTED_IS_PUBLIC)
+        sipRes = sipSelfWasArg ? sipCpp->Klass::foo(iarr)
+                               : sipCpp->foo(iarr);
+    #else
+        sipRes = sipCpp->sipProtectVirt_foo(sipSelfWasArg, iarr);
+    #endif
+
+If a method is in the ``protected`` section of a C++ class but is not virtual
+then the pattern should instead be::
+
+    #if defined(SIP_PROTECTED_IS_PUBLIC)
+        sipRes = sipCpp->foo(iarr);
+    #else
+        sipRes = sipCpp->sipProtect_foo(iarr);
+    #endif
+
+.. [#] See :directive:`%VirtualCatcherCode` for a description of how SIP
+       generated code handles the reimplementation of C++ virtual methods in
+       Python.
+
+
+.. directive:: %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
+:directive:`%Import` this module.  Under the covers, a module exports an API
+that is used by modules that :directive:`%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
+
+
+.. directive:: %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 :directive:`%ExportedHeaderCode` and :directive:`%ModuleHeaderCode`.
+
+
+.. directive:: %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 :directive:`%ExportedHeaderCode` and :directive:`%ModuleCode`.
+
+
+.. directive:: %OptionalInclude
+
+.. parsed-literal::
+
+    %OptionalInclude *filename*
+
+This directive is identical to the :directive:`%Include` directive except that
+SIP silently continues processing if *filename* could not be opened.
+
+For example::
+
+    %OptionalInclude license.sip
+
+
+.. directive:: %PickleCode
+
+.. parsed-literal::
+
+    %PickleCode
+        *code*
+    %End
+
+This directive is used to specify handwritten code to pickle a C structure or
+C++ class instance.
+
+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.
+
+PyObject \*sipRes
+    The handwritten code must set this to a tuple of the arguments that will
+    be passed to the type's __init__() method when the structure or class
+    instance is unpickled.  If there is an error then the code must raise an
+    exception and set this to ``NULL``.
+
+For example::
+
+    class Point
+    {
+        Point(int x, y);
+
+        int x() const;
+        int y() const;
+
+    %PickleCode
+        sipRes = Py_BuildValue("ii", sipCpp->x(), sipCpp->y());
+    %End
+    }
+
+Note that SIP works around the Python limitation that prevents nested types
+being pickled.
+
+Both named and unnamed enums can be pickled automatically without providing any
+handwritten code.
+
+
+.. directive:: %Platforms
+
+.. parsed-literal::
+
+    %Platforms {*name* *name* ...}
+
+This directive is used to declare a set of platforms.  Platforms (along with
+:directive:`%Feature` and :directive:`%Timeline`) are used by the
+:directive:`%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
+
+
+.. directive:: %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
+
+
+.. directive:: %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
+
+
+.. directive:: %RaiseCode
+
+.. parsed-literal::
+
+    %RaiseCode
+        *code*
+    %End
+
+This directive is used as part of the definition of an exception using the
+:directive:`%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 :directive:`%Exception` directive for an example.
+
+
+.. directive:: %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.
+
+PyObject \*sipPyType
+    If the variable being wrapped is a static class variable then this is the
+    Python type object of the class from which the variable was referenced
+    (*not* the class in which it is defined).  It may be safely cast to a
+    PyTypeObject \* or a sipWrapperType \*.
+
+See the :directive:`%GetCode` directive for an example.
+
+
+.. directive:: %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 :directive:`%Feature` and :directive:`%Platforms`)
+are used by the :directive:`%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
+
+:directive:`%Timeline` can be used any number of times in a module to allow
+multiple libraries to be wrapped in the same module.
+
+
+.. directive:: %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.
+
+
+.. directive:: %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 :directive:`%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.
+    };
+
+
+.. directive:: %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.
+
+
+.. directive:: %VirtualCatcherCode
+
+.. parsed-literal::
+
+    %VirtualCatcherCode
+        *code*
+    %End
+
+For most classes there are corresponding :ref:`generated derived classes
+<ref-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 a0Key
+    There is a variable for each argument of the C++ signature that has a type
+    where it is important to ensure that the corresponding Python object is not
+    garbage collected too soon.  This only applies to output arguments that
+    return ``'\0'`` terminated strings.  The variable would normally be passed
+    to :cfunc:`sipParseResult()` using either the ``A`` or ``B`` format
+    characters.
+
+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 :cfunc:`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.
+
+int sipResKey
+    This variable is only made available if the result has a type where it is
+    important to ensure that the corresponding Python object is not garbage
+    collected too soon.  This only applies to ``'\0'`` terminated strings.  The
+    variable would normally be passed to :cfunc:`sipParseResult()` using either
+    the ``A`` or ``B`` format characters.
+
+sipSimpleWrapper \*sipPySelf
+    This variable is only made available if either the ``a0Key`` or
+    ``sipResKey`` are made available.  It defines the context within which keys
+    are unique.  The variable would normally be passed to
+    :cfunc:`sipParseResult()` using the ``S`` format character.
+
+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
+    };