sipref.html

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

<li>The <tt class="docutils literal"><span class="pre">public</span></tt> keyword used in defining the super-classes has been
removed.  This is not supported by SIP.</li>
<li>The <a class="reference" href="#transferthis">TransferThis</a> annotation has been added to the first argument
of the constructor.  It specifies that if the argument is not 0 (i.e. the
<tt class="docutils literal"><span class="pre">Hello</span></tt> 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 <tt class="docutils literal"><span class="pre">QObject</span></tt> 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 <a class="reference" href="#ownership-of-objects">Ownership of Objects</a>.  SIP provides many other
annotations that can be applied to arguments, functions and classes.
Multiple annotations are separated by commas.  Annotations may have
values.</li>
<li>The <tt class="docutils literal"><span class="pre">=</span></tt> operator has been removed.  This operator is not supported by
SIP.</li>
<li>The <a class="reference" href="#if">%If</a> directive has been added to specify that everything up to the
matching <a class="reference" href="#end">%End</a> directive does not apply to Windows.  <tt class="docutils literal"><span class="pre">WS_WIN</span></tt> is
another tag defined by PyQt, this time using the <a class="reference" href="#platforms">%Platforms</a> directive.
Tags defined by the <a class="reference" href="#platforms">%Platforms</a> directive are mutually exclusive, i.e.
only one may be valid at a time <a class="footnote-reference" href="#id13" id="id10" name="id10">[6]</a>.</li>
</ul>
</blockquote>
<p>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.</p>
<p>We now look at the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script.  This is a little different to the
script in the previous examples for two related reasons.</p>
<p>Firstly, PyQt includes a pure Python module called <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> 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.</p>
<p>Secondly, we generate a configuration module (called <tt class="docutils literal"><span class="pre">helloconfig</span></tt>) for our
own <tt class="docutils literal"><span class="pre">hello</span></tt> 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.</p>
<p>Now we have two scripts.  First the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script:</p>
<pre class="literal-block">
import os
import sipconfig
import pyqtconfig

# The name of the SIP build file generated by SIP and used by the build
# system.
build_file = &quot;hello.sbf&quot;

# 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(&quot; &quot;.join([config.sip_bin, &quot;-c&quot;, &quot;.&quot;, &quot;-b&quot;, build_file, &quot;-I&quot;, config.pyqt_sip_dir, qt_sip_flags, &quot;hello.sip&quot;]))

# We are going to install the SIP specification file for this module and
# its configuration module.
installs = []

installs.append([&quot;hello.sip&quot;, os.path.join(config.default_sip_dir, &quot;hello&quot;)])

installs.append([&quot;helloconfig.py&quot;, 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 &quot;lib&quot; prefix on UNIX, or the
# &quot;.dll&quot; extension on Windows).
makefile.extra_libs = [&quot;hello&quot;]

# 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.
    &quot;hello_sip_dir&quot;:    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.
    &quot;hello_sip_flags&quot;:  qt_sip_flags
}

# This creates the helloconfig.py module from the helloconfig.py.in
# template and the dictionary.
sipconfig.create_config_module(&quot;helloconfig.py&quot;, &quot;helloconfig.py.in&quot;, content)
</pre>
<p>Next we have the <tt class="docutils literal"><span class="pre">helloconfig.py.in</span></tt> template script:</p>
<pre class="literal-block">
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.
# &#64;SIP_CONFIGURATION&#64;

class Configuration(pyqtconfig.Configuration):
    &quot;&quot;&quot;The class that represents Hello configuration values.
    &quot;&quot;&quot;
    def __init__(self, sub_cfg=None):
        &quot;&quot;&quot;Initialise an instance of the class.

        sub_cfg is the list of sub-class configurations.  It should be None
        when called normally.
        &quot;&quot;&quot;
        # 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):
    &quot;&quot;&quot;The Makefile class for modules that %Import hello.
    &quot;&quot;&quot;
    def finalise(self):
        &quot;&quot;&quot;Finalise the macros.
        &quot;&quot;&quot;
        # Make sure our C++ library is linked.
        self.extra_libs.append(&quot;hello&quot;)

        # Let the super-class do what it needs to.
        pyqtconfig.QtModuleMakefile.finalise(self)
</pre>
<p>Again, we hope that the scripts are self documenting.</p>
<table class="docutils footnote" frame="void" id="id11" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id8" name="id11">[4]</a></td><td>Some parts of a SIP specification aren't subject to version control.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9" name="id12">[5]</a></td><td>Actually in <tt class="docutils literal"><span class="pre">versions.sip</span></tt>.  PyQt uses the <a class="reference" href="#include">%Include</a> directive to
split the SIP specification for Qt across a large number of separate
<tt class="docutils literal"><span class="pre">.sip</span></tt> files.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id10" name="id13">[6]</a></td><td>Tags can also be defined by the <a class="reference" href="#feature">%Feature</a> directive.  These tags are
not mutually exclusive, i.e. any number may be valid at a time.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="ownership-of-objects">
<h2><a class="toc-backref" href="#id40" name="ownership-of-objects">4.4&nbsp;&nbsp;&nbsp;Ownership of Objects</a></h2>
<p>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.</p>
<p>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.</p>
<p>The <a class="reference" href="#transferthis">TransferThis</a>, <a class="reference" href="#transfer">Transfer</a> 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).</p>
<p>This applies equally to C structures where the structure is returned to the
heap using the <tt class="docutils literal"><span class="pre">free()</span></tt> function.</p>
<p>See also <a class="reference" href="#siptransferto">sipTransferTo()</a> and <a class="reference" href="#siptransferback">sipTransferBack()</a>.</p>
</div>
</div>
<div class="section" id="the-sip-command-line">
<h1><a class="toc-backref" href="#id41