sipref.txt

这是关于RFC3261实现sip的源代码

            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()`_.


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 Scintilla API file to generate.  This file contains a
        description of the module API in a form that the Scintilla editor
        component can use for auto-completion and call tips.  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.  The 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.
-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`_ | `%Feature`_ | `%Import`_ | `%Include`_ |
            `%License`_ | `%MappedType`_ | *mapped-type-template* |
            `%Module`_ | `%ModuleCode`_ | `%ModuleHeaderCode`_ |
            `%OptionalInclude`_ | `%Platforms`_ | `%PreInitialisationCode`_ |
            `%PostInitialisationCode`_ | `%SIPNoEmitters`_ | `%Timeline`_]

    *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*]
            [*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*} ``"``