<h1>SIP Specification Files<aclass="headerlink"href="#sip-specification-files"title="Permalink to this headline">¶</a></h1>
<p>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.</p>
<p>It is important to understand that a SIP specification describes the Python
API, i.e. the API available to the Python programmer when they <ttclass="docutils literal"><spanclass="pre">import</span></tt> 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.</p>
<p>In most cases the Python API matches the C/C++ API. In some cases handwritten
code (see <aclass="reference external"href="directives.html#directive-%MethodCode"><ttclass="xref docutils literal"><spanclass="pre">%MethodCode</span></tt></a>) 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
<aclass="reference external"href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>) and needs to know the exact C++ signature. To deal
with these cases SIP allows two signatures to be specified. For example:</p>
<divclass="highlight-python"><pre>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
};</pre>
</div>
<divclass="section"id="syntax-definition">
<h2>Syntax Definition<aclass="headerlink"href="#syntax-definition"title="Permalink to this headline">¶</a></h2>
<p>The following is a semi-formal description of the syntax of a specification
<h2>Variable Numbers of Arguments<aclass="headerlink"href="#variable-numbers-of-arguments"title="Permalink to this headline">¶</a></h2>
<p>SIP supports the use of <ttclass="docutils literal"><spanclass="pre">...</span></tt> as the last part of a function signature. Any
remaining arguments are collected as a Python tuple.</p>
</div>
<divclass="section"id="additional-sip-types">
<h2>Additional SIP Types<aclass="headerlink"href="#additional-sip-types"title="Permalink to this headline">¶</a></h2>
<p>SIP supports a number of additional data types that can be used in Python
signatures.</p>
<dlclass="sip-type">
<dtid="stype-SIP_ANYSLOT">
<ttclass="descname">SIP_ANYSLOT</tt><aclass="headerlink"href="#stype-SIP_ANYSLOT"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is both a <ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> and a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is used as the type
of the member instead of <ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> in functions that implement the
connection or disconnection of an explicitly generated signal to a slot.
Handwritten code must be provided to interpret the conversion correctly.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYCALLABLE">
<ttclass="descname">SIP_PYCALLABLE</tt><aclass="headerlink"href="#stype-SIP_PYCALLABLE"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python callable object.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYDICT">
<ttclass="descname">SIP_PYDICT</tt><aclass="headerlink"href="#stype-SIP_PYDICT"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python dictionary object.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYLIST">
<ttclass="descname">SIP_PYLIST</tt><aclass="headerlink"href="#stype-SIP_PYLIST"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python list object.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYOBJECT">
<ttclass="descname">SIP_PYOBJECT</tt><aclass="headerlink"href="#stype-SIP_PYOBJECT"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> of any Python type.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYSLICE">
<ttclass="descname">SIP_PYSLICE</tt><aclass="headerlink"href="#stype-SIP_PYSLICE"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python slice object.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYTUPLE">
<ttclass="descname">SIP_PYTUPLE</tt><aclass="headerlink"href="#stype-SIP_PYTUPLE"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python tuple object.</p>
<dlclass="sip-type">
<dtid="stype-SIP_PYTYPE">
<ttclass="descname">SIP_PYTYPE</tt><aclass="headerlink"href="#stype-SIP_PYTYPE"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python type object.</p>
<p>This is a <ttclass="docutils literal"><spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from TQt’s
<p>This is a <ttclass="docutils literal"><spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from TQt’s
<ttclass="docutils literal"><spanclass="pre">TQObject</span></tt> class. It is used as the type of the receiver instead of <ttclass="docutils literal"><spanclass="pre">const</span>
<spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> in functions that implement a connection to a slot.</p>
<p>This is a <ttclass="docutils literal"><spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from TQt’s
<ttclass="docutils literal"><spanclass="pre">TQObject</span></tt> class. It is used as the type of the receiver instead of <ttclass="docutils literal"><spanclass="pre">const</span>
<spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> in functions that implement a disconnection from a slot.</p>
<ttclass="descname">SIP_SIGNAL</tt><aclass="headerlink"href="#stype-SIP_SIGNAL"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> that is used as the type of the signal instead of
<ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> in functions that implement the connection or disconnection
of an explicitly generated signal to a slot.</p>
<dlclass="sip-type">
<dtid="stype-SIP_SLOT">
<ttclass="descname">SIP_SLOT</tt><aclass="headerlink"href="#stype-SIP_SLOT"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> that is used as the type of the member instead of
<ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> in functions that implement the connection or disconnection
of an explicitly generated signal to a slot.</p>
<dlclass="sip-type">
<dtid="stype-SIP_SLOT_CON">
<ttclass="descname">SIP_SLOT_CON</tt><aclass="headerlink"href="#stype-SIP_SLOT_CON"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> that is used as the type of the member instead of
<ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> in functions that implement the connection of an internally
generated signal to a slot. The type includes a comma separated list of types
<ttclass="descname">SIP_SLOT_DIS</tt><aclass="headerlink"href="#stype-SIP_SLOT_DIS"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> that is used as the type of the member instead of
<ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> in functions that implement the disconnection of an
internally generated signal to a slot. The type includes a comma separated
list of types that is the C++ signature of of the signal.</p>
<h2>Classic Division and True Division<aclass="headerlink"href="#classic-division-and-true-division"title="Permalink to this headline">¶</a></h2>
<p>SIP supports the <ttclass="docutils literal"><spanclass="pre">__div__</span></tt> and <ttclass="docutils literal"><spanclass="pre">__truediv__</span></tt> special methods (and the
corresponding inplace versions) for both Python v2 and v3.</p>
<p>For Python v2 the <ttclass="docutils literal"><spanclass="pre">__div__</span></tt> method will be used for both classic and true
division if a <ttclass="docutils literal"><spanclass="pre">__truediv__</span></tt> method is not defined.</p>
<p>For Python v3 the <ttclass="docutils literal"><spanclass="pre">__div__</span></tt> method will be used for true division if a
<ttclass="docutils literal"><spanclass="pre">__truediv__</span></tt> method is not defined.</p>
<p>For all versions of Python, if both methods are defined then <ttclass="docutils literal"><spanclass="pre">__div__</span></tt>
should be defined first.</p>
</div>
</div>
</div>
</div>
</div>
<divclass="sphinxsidebar">
<divclass="sphinxsidebarwrapper">
<h3><ahref="index.html">Table Of Contents</a></h3>
