Your IP : 216.73.216.48
| Current Path : /usr/doc/sip-4.18/html/ |
|
|
| Current File : //usr/doc/sip-4.18/html/specification_files.html |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>SIP Specification Files — SIP 4.18 Reference Guide</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '4.18',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/logo_tn.ico"/>
<link rel="top" title="SIP 4.18 Reference Guide" href="index.html" />
<link rel="next" title="Directives" href="directives.html" />
<link rel="prev" title="The SIP Command Line" href="command_line.html" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="directives.html" title="Directives"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="command_line.html" title="The SIP Command Line"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SIP 4.18 Reference Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="sip-specification-files">
<h1>SIP Specification Files<a class="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 <code class="docutils literal"><span class="pre">import</span></code> 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 <a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></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
<a class="reference internal" href="c_api.html#ref-derived-classes"><span class="std std-ref">Generated Derived Classes</span></a>) and needs to know the exact C++ signature. To deal
with these cases SIP allows two signatures to be specified. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>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>
</div>
<div class="section" id="syntax-definition">
<h2>Syntax Definition<a class="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
file.</p>
<pre class="literal-block">
<em>specification</em> ::= {<em>module-statement</em>}
<em>module-statement</em> ::= [<em>module-directive</em> | <em>statement</em>]
<em>module-directive</em> ::= [
<a class="reference internal" href="directives.html#directive-%API"><code class="xref std std-directive docutils literal"><span class="pre">%API</span></code></a> |
<a class="reference internal" href="directives.html#directive-%CompositeModule"><code class="xref std std-directive docutils literal"><span class="pre">%CompositeModule</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ConsolidatedModule"><code class="xref std std-directive docutils literal"><span class="pre">%ConsolidatedModule</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Copying"><code class="xref std std-directive docutils literal"><span class="pre">%Copying</span></code></a> |
<a class="reference internal" href="directives.html#directive-%DefaultEncoding"><code class="xref std std-directive docutils literal"><span class="pre">%DefaultEncoding</span></code></a> |
<a class="reference internal" href="directives.html#directive-%DefaultMetatype"><code class="xref std std-directive docutils literal"><span class="pre">%DefaultMetatype</span></code></a> |
<a class="reference internal" href="directives.html#directive-%DefaultSupertype"><code class="xref std std-directive docutils literal"><span class="pre">%DefaultSupertype</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ExportedHeaderCode"><code class="xref std std-directive docutils literal"><span class="pre">%ExportedHeaderCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ExportedTypeHintCode"><code class="xref std std-directive docutils literal"><span class="pre">%ExportedTypeHintCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Extract"><code class="xref std std-directive docutils literal"><span class="pre">%Extract</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Feature"><code class="xref std std-directive docutils literal"><span class="pre">%Feature</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Import"><code class="xref std std-directive docutils literal"><span class="pre">%Import</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Include"><code class="xref std std-directive docutils literal"><span class="pre">%Include</span></code></a> |
<a class="reference internal" href="directives.html#directive-%InitialisationCode"><code class="xref std std-directive docutils literal"><span class="pre">%InitialisationCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%License"><code class="xref std std-directive docutils literal"><span class="pre">%License</span></code></a> |
<a class="reference internal" href="directives.html#directive-%MappedType"><code class="xref std std-directive docutils literal"><span class="pre">%MappedType</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Module"><code class="xref std std-directive docutils literal"><span class="pre">%Module</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ModuleCode"><code class="xref std std-directive docutils literal"><span class="pre">%ModuleCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ModuleHeaderCode"><code class="xref std std-directive docutils literal"><span class="pre">%ModuleHeaderCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%OptionalInclude"><code class="xref std std-directive docutils literal"><span class="pre">%OptionalInclude</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Platforms"><code class="xref std std-directive docutils literal"><span class="pre">%Platforms</span></code></a> |
<a class="reference internal" href="directives.html#directive-%PreInitialisationCode"><code class="xref std std-directive docutils literal"><span class="pre">%PreInitialisationCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%PostInitialisationCode"><code class="xref std std-directive docutils literal"><span class="pre">%PostInitialisationCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Timeline"><code class="xref std std-directive docutils literal"><span class="pre">%Timeline</span></code></a> |
<a class="reference internal" href="directives.html#directive-%TypeHintCode"><code class="xref std std-directive docutils literal"><span class="pre">%TypeHintCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%UnitCode"><code class="xref std std-directive docutils literal"><span class="pre">%UnitCode</span></code></a> |
<em>mapped-type-template</em>]
<em>statement</em> :: [<em>class-statement</em> | <em>function</em> | <em>variable</em>]
<em>class-statement</em> :: [
<a class="reference internal" href="directives.html#directive-%If"><code class="xref std std-directive docutils literal"><span class="pre">%If</span></code></a> |
<em>class</em> |
<em>class-template</em> |
<em>enum</em> |
<em>namespace</em> |
<em>opaque-class</em> |
<em>operator</em> |
<em>struct</em> |
<em>typedef</em> |
<em>exception</em>]
<em>class</em> ::= <strong>class</strong> <em>name</em> [<strong>:</strong> <em>super-classes</em>] [<em>class-annotations</em>]
<strong>{</strong> {<em>class-line</em>} <strong>};</strong>
<em>super-classes</em> ::= [<strong>public</strong> | <strong>protected</strong> | <strong>private</strong>] <em>name</em>
[<strong>,</strong> <em>super-classes</em>]
<em>class-line</em> ::= [
<em>class-statement</em> |
<a class="reference internal" href="directives.html#directive-%BIGetBufferCode"><code class="xref std std-directive docutils literal"><span class="pre">%BIGetBufferCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%BIGetReadBufferCode"><code class="xref std std-directive docutils literal"><span class="pre">%BIGetReadBufferCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%BIGetWriteBufferCode"><code class="xref std std-directive docutils literal"><span class="pre">%BIGetWriteBufferCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%BIGetSegCountCode"><code class="xref std std-directive docutils literal"><span class="pre">%BIGetSegCountCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%BIGetCharBufferCode"><code class="xref std std-directive docutils literal"><span class="pre">%BIGetCharBufferCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%BIReleaseBufferCode"><code class="xref std std-directive docutils literal"><span class="pre">%BIReleaseBufferCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ConvertToSubClassCode"><code class="xref std std-directive docutils literal"><span class="pre">%ConvertToSubClassCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%ConvertToTypeCode"><code class="xref std std-directive docutils literal"><span class="pre">%ConvertToTypeCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%Docstring"><code class="xref std std-directive docutils literal"><span class="pre">%Docstring</span></code></a> |
<a class="reference internal" href="directives.html#directive-%GCClearCode"><code class="xref std std-directive docutils literal"><span class="pre">%GCClearCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%GCTraverseCode"><code class="xref std std-directive docutils literal"><span class="pre">%GCTraverseCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%InstanceCode"><code class="xref std std-directive docutils literal"><span class="pre">%InstanceCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%PickleCode"><code class="xref std std-directive docutils literal"><span class="pre">%PickleCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%TypeCode"><code class="xref std std-directive docutils literal"><span class="pre">%TypeCode</span></code></a> |
<a class="reference internal" href="directives.html#directive-%TypeHeaderCode"><code class="xref std std-directive docutils literal"><span class="pre">%TypeHeaderCode</span></code></a> |
<em>constructor</em> |
<em>destructor</em> |
<em>method</em> |
<em>static-method</em> |
<em>virtual-method</em> |
<em>special-method</em> |
<em>operator</em> |
<em>virtual-operator</em> |
<em>class-variable</em> |
<strong>public:</strong> |
<strong>public Q_SLOTS:</strong> |
<strong>public slots:</strong> |
<strong>protected:</strong> |
<strong>protected Q_SLOTS:</strong> |
<strong>protected slots:</strong> |
<strong>private:</strong> |
<strong>private Q_SLOTS:</strong> |
<strong>private slots:</strong> |
<strong>Q_SIGNALS:</strong> |
<strong>signals:</strong>]
<em>constructor</em> ::= [<strong>explicit</strong>] <em>name</em> <strong>(</strong> [<em>argument-list</em>] <strong>)</strong>
[<em>exceptions</em>] [<em>function-annotations</em>]
[<em>c++-constructor-signature</em>] <strong>;</strong> [<a class="reference internal" href="directives.html#directive-%Docstring"><code class="xref std std-directive docutils literal"><span class="pre">%Docstring</span></code></a>]
[<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
<em>c++-constructor-signature</em> ::= <strong>[(</strong> [<em>argument-list</em>] <strong>)]</strong>
<em>destructor</em> ::= [<strong>virtual</strong>] <strong>~</strong> <em>name</em> <strong>()</strong> [<em>exceptions</em>] [<strong>= 0</strong>]
[<em>function-annotations</em>] <strong>;</strong> [<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
[<a class="reference internal" href="directives.html#directive-%VirtualCatcherCode"><code class="xref std std-directive docutils literal"><span class="pre">%VirtualCatcherCode</span></code></a>]
<em>method</em> ::= [<strong>Q_SIGNAL</strong>] [<strong>Q_SLOT</strong>] <em>type</em> <em>name</em> <strong>(</strong>
[<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] [<strong>= 0</strong>]
[<em>function-annotations</em>] [<em>c++-signature</em>] <strong>;</strong>
[<a class="reference internal" href="directives.html#directive-%Docstring"><code class="xref std std-directive docutils literal"><span class="pre">%Docstring</span></code></a>] [<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
<em>c++-signature</em> ::= <strong>[</strong> <em>type</em> <strong>(</strong> [<em>argument-list</em>] <strong>)]</strong>
<em>static-method</em> ::= <strong>static</strong> <em>function</em>
<em>virtual-method</em> ::= [<strong>Q_SIGNAL</strong>] [<strong>Q_SLOT</strong>] <strong>virtual</strong> <em>type</em> <em>name</em>
<strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] [<strong>= 0</strong>]
[<em>function-annotations</em>] [<em>c++-signature</em>] <strong>;</strong>
[<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>] [<a class="reference internal" href="directives.html#directive-%VirtualCatcherCode"><code class="xref std std-directive docutils literal"><span class="pre">%VirtualCatcherCode</span></code></a>]
[<a class="reference internal" href="directives.html#directive-%VirtualCallCode"><code class="xref std std-directive docutils literal"><span class="pre">%VirtualCallCode</span></code></a>]
<em>special-method</em> ::= <em>type</em> <em>special-method-name</em>
<strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<em>function-annotations</em>] <strong>;</strong>
[<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
<em>special-method-name</em> ::= [<strong>__abs__</strong> | <strong>__add__</strong> | <strong>__and__</strong> |
<strong>__aiter__</strong> | <strong>__anext__</strong> | <strong>__await__</strong> | <strong>__bool__</strong> |
<strong>__call__</strong> | <strong>__cmp__</strong> | <strong>__contains__</strong> | <strong>__delattr__</strong> |
<strong>__delitem__</strong> | <strong>__div__</strong> | <strong>__eq__</strong> | <strong>__float__</strong> |
<strong>__floordiv__</strong> | <strong>__ge__</strong> | <strong>__getattr__</strong> |
<strong>__getattribute__</strong> | <strong>__getitem__</strong> | <strong>__gt__</strong> |
<strong>__hash__</strong> | <strong>__iadd__</strong> | <strong>__iand__</strong> | <strong>__idiv__</strong> |
<strong>__ifloordiv__</strong> | <strong>__ilshift__</strong> | <strong>__imatmul__</strong> |
<strong>__imod__</strong> | <strong>__imul__</strong> | <strong>__index__</strong> | <strong>__int__</strong> |
<strong>__invert__</strong> | <strong>__ior__</strong> | <strong>__irshift__</strong> | <strong>__isub__</strong> |
<strong>__iter__</strong> | <strong>__itruediv__</strong> | <strong>__ixor__</strong> | <strong>__le__</strong> |
<strong>__len__</strong> | <strong>__long__</strong> | <strong>__lshift__</strong> | <strong>__lt__</strong> |
<strong>__matmul</strong> | <strong>__mod__</strong> | <strong>__mul__</strong> | <strong>__ne__</strong> |
<strong>__neg__</strong> | <strong>__next__</strong> | <strong>__nonzero__</strong> | <strong>__or__</strong> |
<strong>__pos__</strong> | <strong>__repr__</strong> | <strong>__rshift__</strong> | <strong>__setattr__</strong> |
<strong>__setitem__</strong> | <strong>__str__</strong> | <strong>__sub__</strong> | <strong>__truediv__</strong> |
<strong>__xor__</strong>]
<em>operator</em> ::= <em>operator-type</em>
<strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>]
[<em>function-annotations</em>] <strong>;</strong> [<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
<em>virtual-operator</em> ::= <strong>virtual</strong> <em>operator-type</em>
<strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<strong>const</strong>] [<em>exceptions</em>] [<strong>= 0</strong>]
[<em>function-annotations</em>] <strong>;</strong> [<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
[<a class="reference internal" href="directives.html#directive-%VirtualCatcherCode"><code class="xref std std-directive docutils literal"><span class="pre">%VirtualCatcherCode</span></code></a>] [<a class="reference internal" href="directives.html#directive-%VirtualCallCode"><code class="xref std std-directive docutils literal"><span class="pre">%VirtualCallCode</span></code></a>]
<em>operatator-type</em> ::= [ <em>operator-function</em> | <em>operator-cast</em> ]
<em>operator-function</em> ::= <em>type</em> <strong>operator</strong> <em>operator-name</em>
<em>operator-cast</em> ::= <strong>operator</strong> <em>type</em>
<em>operator-name</em> ::= [<strong>+</strong> | <strong>-</strong> | <strong>*</strong> | <strong>/</strong> | <strong>%</strong> | <strong>&</strong> |
<strong>|</strong> | <strong>^</strong> | <strong><<</strong> | <strong>>></strong> | <strong>+=</strong> | <strong>-=</strong> | <strong>*=</strong> |
<strong>/=</strong> | <strong>%=</strong> | <strong>&=</strong> | <strong>|=</strong> | <strong>^=</strong> | <strong><<=</strong> | <strong>>>=</strong> |
<strong>~</strong> | <strong>()</strong> | <strong>[]</strong> | <strong><</strong> | <strong><=</strong> | <strong>==</strong> | <strong>!=</strong> |
<strong>></strong> | <strong>>>=</strong> | <strong>=</strong>]
<em>class-variable</em> ::= [<strong>static</strong>] <em>variable</em>
<em>class-template</em> :: = <strong>template</strong> <strong><</strong> <em>type-list</em> <strong>></strong> <em>class</em>
<em>mapped-type-template</em> :: = <strong>template</strong> <strong><</strong> <em>type-list</em> <strong>></strong>
<a class="reference internal" href="directives.html#directive-%MappedType"><code class="xref std std-directive docutils literal"><span class="pre">%MappedType</span></code></a>
<em>enum</em> ::= <strong>enum</strong> [<em>name</em>] [<em>enum-annotations</em>] <strong>{</strong> {<em>enum-line</em>} <strong>};</strong>
<em>enum-line</em> ::= [<a class="reference internal" href="directives.html#directive-%If"><code class="xref std std-directive docutils literal"><span class="pre">%If</span></code></a> | <em>name</em> [<em>enum-annotations</em>] <strong>,</strong>
<em>function</em> ::= <em>type</em> <em>name</em> <strong>(</strong> [<em>argument-list</em>] <strong>)</strong> [<em>exceptions</em>]
[<em>function-annotations</em>] <strong>;</strong> [<a class="reference internal" href="directives.html#directive-%Docstring"><code class="xref std std-directive docutils literal"><span class="pre">%Docstring</span></code></a>]
[<a class="reference internal" href="directives.html#directive-%MethodCode"><code class="xref std std-directive docutils literal"><span class="pre">%MethodCode</span></code></a>]
<em>namespace</em> ::= <strong>namespace</strong> <em>name</em> [<strong>{</strong> {<em>namespace-line</em>} <strong>}</strong>] <strong>;</strong>
<em>namespace-line</em> ::= [<a class="reference internal" href="directives.html#directive-%TypeHeaderCode"><code class="xref std std-directive docutils literal"><span class="pre">%TypeHeaderCode</span></code></a> | <em>statement</em>]
<em>opaque-class</em> ::= <strong>class</strong> <em>scoped-name</em> <strong>;</strong>
<em>struct</em> ::= <strong>struct</strong> <em>name</em> <strong>{</strong> {<em>class-line</em>} <strong>};</strong>
<em>typedef</em> ::= <strong>typedef</strong> [<em>typed-name</em> | <em>function-pointer</em>]
<em>typedef-annotations</em> <strong>;</strong>
<em>variable</em>::= <em>typed-name</em> [<em>variable-annotations</em>] <strong>;</strong>
[<a class="reference internal" href="directives.html#directive-%AccessCode"><code class="xref std std-directive docutils literal"><span class="pre">%AccessCode</span></code></a>] [<a class="reference internal" href="directives.html#directive-%GetCode"><code class="xref std std-directive docutils literal"><span class="pre">%GetCode</span></code></a>]
[<a class="reference internal" href="directives.html#directive-%SetCode"><code class="xref std std-directive docutils literal"><span class="pre">%SetCode</span></code></a>]
<em>exception</em> ::= <a class="reference internal" href="directives.html#directive-%Exception"><code class="xref std std-directive docutils literal"><span class="pre">%Exception</span></code></a> <em>exception-name</em> [<em>exception-base</em>]
<strong>{</strong> [<a class="reference internal" href="directives.html#directive-%TypeHeaderCode"><code class="xref std std-directive docutils literal"><span class="pre">%TypeHeaderCode</span></code></a>] <a class="reference internal" href="directives.html#directive-%RaiseCode"><code class="xref std std-directive docutils literal"><span class="pre">%RaiseCode</span></code></a> <strong>};</strong>
<em>exception-name</em> ::= <em>scoped-name</em>
<em>exception-base</em> ::= <strong>(</strong> [<em>exception-name</em> | <em>python-exception</em>] <strong>)</strong>
<em>python-exception</em> ::= [<strong>SIP_ArithmeticError</strong> | <strong>SIP_AssertionError</strong> |
<strong>SIP_AttributeError</strong> | <strong>SIP_BaseException</strong> |
<strong>SIP_BlockingIOError</strong> | <strong>SIP_BrokenPipeError</strong> |
<strong>SIP_BufferError</strong> | <strong>SIP_ChildProcessError</strong> |
<strong>SIP_ConnectionAbortedError</strong> | <strong>SIP_ConnectionError</strong> |
<strong>SIP_ConnectionRefusedError</strong> | <strong>SIP_ConnectionResetError</strong> |
<strong>SIP_EnvironmentError</strong> | <strong>SIP_EOFError</strong> | <strong>SIP_Exception</strong> |
<strong>SIP_FileExistsError</strong> | <strong>SIP_FileNotFoundError</strong> |
<strong>SIP_FloatingPointError</strong> | <strong>SIP_GeneratorExit</strong> |
<strong>SIP_ImportError</strong> | <strong>SIP_IndentationError</strong> |
<strong>SIP_IndexError</strong> | <strong>SIP_InterruptedError</strong> | <strong>SIP_IOError</strong> |
<strong>SIP_IsADirectoryError</strong> | <strong>SIP_KeyboardInterrupt</strong> |
<strong>SIP_KeyError</strong> | <strong>SIP_LookupError</strong> | <strong>SIP_MemoryError</strong> |
<strong>SIP_NameError</strong> | <strong>SIP_NotADirectoryError</strong> |
<strong>SIP_NotImplementedError</strong> | <strong>SIP_OSError</strong> |
<strong>SIP_OverflowError</strong> | <strong>SIP_PermissionError</strong> |
<strong>SIP_ProcessLookupError</strong> | <strong>SIP_ReferenceError</strong> |
<strong>SIP_RuntimeError</strong> | <strong>SIP_StandardError</strong> |
<strong>SIP_StopIteration</strong> | <strong>SIP_SyntaxError</strong> | <strong>SIP_SystemError</strong> |
<strong>SIP_SystemExit</strong> | <strong>SIP_TabError</strong> | <strong>SIP_TimeoutError</strong> |
<strong>SIP_TypeError</strong> | <strong>SIP_UnboundLocalError</strong> |
<strong>SIP_UnicodeDecodeError</strong> | <strong>SIP_UnicodeEncodeError</strong> |
<strong>SIP_UnicodeError</strong> | <strong>SIP_UnicodeTranslateError</strong> |
<strong>SIP_ValueError</strong> | <strong>SIP_VMSError</strong> | <strong>SIP_WindowsError</strong> |
<strong>SIP_ZeroDivisionError</strong> | <strong>SIP_Warning</strong> |
<strong>SIP_BytesWarning</strong> | <strong>SIP_DeprecationWarning</strong> |
<strong>SIP_FutureWarning</strong> | <strong>SIP_ImportWarning</strong> |
<strong>SIP_PendingDeprecationWarning</strong> | <strong>SIP_ResourceWarning</strong> |
<strong>SIP_RuntimeWarning</strong> | <strong>SIP_SyntaxWarning</strong> |
<strong>SIP_UnicodeWarning</strong> | <strong>SIP_UserWarning</strong>]
<em>exceptions</em> ::= <strong>throw (</strong> [<em>exception-list</em>] <strong>)</strong>
<em>exception-list</em> ::= <em>scoped-name</em> [<strong>,</strong> <em>exception-list</em>]
<em>argument-list</em> ::= <em>argument</em> [<strong>,</strong> <em>argument-list</em>] [<strong>,</strong> <strong>...</strong>]
<em>argument</em> ::= [
<em>type</em> [<em>name</em>] [<em>argument-annotations</em>] [<em>default-value</em>] |
<a class="reference internal" href="#sip-type-SIP_ANYSLOT"><code class="xref std std-stype docutils literal"><span class="pre">SIP_ANYSLOT</span></code></a> [<em>default-value</em>] |
<a class="reference internal" href="#sip-type-SIP_QOBJECT"><code class="xref std std-stype docutils literal"><span class="pre">SIP_QOBJECT</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_RXOBJ_CON"><code class="xref std std-stype docutils literal"><span class="pre">SIP_RXOBJ_CON</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_RXOBJ_DIS"><code class="xref std std-stype docutils literal"><span class="pre">SIP_RXOBJ_DIS</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_SIGNAL"><code class="xref std std-stype docutils literal"><span class="pre">SIP_SIGNAL</span></code></a> [<em>default-value</em>] |
<a class="reference internal" href="#sip-type-SIP_SLOT"><code class="xref std std-stype docutils literal"><span class="pre">SIP_SLOT</span></code></a> [<em>default-value</em>] |
<a class="reference internal" href="#sip-type-SIP_SLOT_CON"><code class="xref std std-stype docutils literal"><span class="pre">SIP_SLOT_CON</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_SLOT_DIS"><code class="xref std std-stype docutils literal"><span class="pre">SIP_SLOT_DIS</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_SSIZE_T"><code class="xref std std-stype docutils literal"><span class="pre">SIP_SSIZE_T</span></code></a>]
<em>default-value</em> ::= <strong>=</strong> <em>expression</em>
<em>expression</em> ::= [<em>value</em> | <em>value</em> <em>binary-operator</em> <em>expression</em>]
<em>value</em> ::= [<em>unary-operator</em>] <em>simple-value</em>
<em>simple-value</em> ::= [<em>scoped-name</em> | <em>function-call</em> | <em>real-value</em> |
<em>integer-value</em> | <em>boolean-value</em> | <em>string-value</em> |
<em>character-value</em>]
<em>typed-name</em>::= <em>type</em> <em>name</em>
<em>function-pointer</em>::= <em>type</em> <strong>(*</strong> <em>name</em> <strong>)(</strong> [<em>type-list</em>] <strong>)</strong>
<em>type-list</em> ::= <em>type</em> [<strong>,</strong> <em>type-list</em>]
<em>function-call</em> ::= <em>scoped-name</em> <strong>(</strong> [<em>value-list</em>] <strong>)</strong>
<em>value-list</em> ::= <em>value</em> [<strong>,</strong> <em>value-list</em>]
<em>real-value</em> ::= a floating point number
<em>integer-value</em> ::= a number
<em>boolean-value</em> ::= [<strong>true</strong> | <strong>false</strong>]
<em>string-value</em> ::= <strong>"</strong> {<em>character</em>} <strong>"</strong>
<em>character-value</em> ::= <strong>'</strong> <em>character</em> <strong>'</strong>
<em>unary-operator</em> ::= [<strong>!</strong> | <strong>~</strong> | <strong>-</strong> | <strong>+</strong> | <strong>*</strong> | <strong>&</strong>]
<em>binary-operator</em> ::= [<strong>-</strong> | <strong>+</strong> | <strong>*</strong> | <strong>/</strong> | <strong>&</strong> | <strong>|</strong>]
<em>argument-annotations</em> ::= see <a class="reference internal" href="annotations.html#ref-arg-annos"><span class="std std-ref">Argument Annotations</span></a>
<em>class-annotations</em> ::= see <a class="reference internal" href="annotations.html#ref-class-annos"><span class="std std-ref">Class Annotations</span></a>
<em>enum-annotations</em> ::= see <a class="reference internal" href="annotations.html#ref-enum-annos"><span class="std std-ref">Enum Annotations</span></a>
<em>function-annotations</em> ::= see <a class="reference internal" href="annotations.html#ref-function-annos"><span class="std std-ref">Function Annotations</span></a>
<em>typedef-annotations</em> ::= see <a class="reference internal" href="annotations.html#ref-typedef-annos"><span class="std std-ref">Typedef Annotations</span></a>
<em>variable-annotations</em> ::= see <a class="reference internal" href="annotations.html#ref-variable-annos"><span class="std std-ref">Variable Annotations</span></a>
<em>type</em> ::= [<strong>const</strong>] <em>base-type</em> {<strong>*</strong>} [<strong>&</strong>]
<em>type-list</em> ::= <em>type</em> [<strong>,</strong> <em>type-list</em>]
<em>base-type</em> ::= [<em>scoped-name</em> | <em>template</em> | <strong>struct</strong> <em>scoped-name</em> |
<strong>char</strong> | <strong>signed char</strong> | <strong>unsigned char</strong> | <strong>wchar_t</strong> |
<strong>int</strong> | <strong>unsigned</strong> | <strong>unsigned int</strong> |
<strong>short</strong> | <strong>unsigned short</strong> |
<strong>long</strong> | <strong>unsigned long</strong> |
<strong>long long</strong> | <strong>unsigned long long</strong> |
<strong>float</strong> | <strong>double</strong> |
<strong>bool</strong> |
<strong>void</strong> |
<strong>PyObject</strong> |
<a class="reference internal" href="#sip-type-SIP_PYBUFFER"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYBUFFER</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYCALLABLE"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYCALLABLE</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYDICT"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYDICT</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYLIST"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYLIST</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYOBJECT"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYOBJECT</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYSLICE"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYSLICE</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYTUPLE"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYTUPLE</span></code></a> |
<a class="reference internal" href="#sip-type-SIP_PYTYPE"><code class="xref std std-stype docutils literal"><span class="pre">SIP_PYTYPE</span></code></a>]
<em>scoped-name</em> ::= <em>name</em> [<strong>::</strong> <em>scoped-name</em>]
<em>template</em> ::= <em>scoped-name</em> <strong><</strong> <em>type-list</em> <strong>></strong>
<em>dotted-name</em> ::= <em>name</em> [<strong>.</strong> <em>dotted-name</em>]
<em>name</em> ::= _A-Za-z {_A-Za-z0-9}
</pre>
<p>Here is a short list of differences between C++ and the subset supported by
SIP that might trip you up.</p>
<blockquote>
<div><ul class="simple">
<li>SIP does not support the use of <code class="docutils literal"><span class="pre">[]</span></code> in types. Use pointers instead.</li>
<li>A global <code class="docutils literal"><span class="pre">operator</span></code> can only be defined if its first argument is a
class or a named enum that has been wrapped in the same module.</li>
<li>Variables declared outside of a class are effectively read-only.</li>
<li>A class’s list of super-classes doesn’t not include any access specifier
(e.g. <code class="docutils literal"><span class="pre">public</span></code>).</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="variable-numbers-of-arguments">
<h2>Variable Numbers of Arguments<a class="headerlink" href="#variable-numbers-of-arguments" title="Permalink to this headline">¶</a></h2>
<p>SIP supports the use of <code class="docutils literal"><span class="pre">...</span></code> as the last part of a function signature. Any
remaining arguments are collected as a Python tuple.</p>
</div>
<div class="section" id="additional-sip-types">
<h2>Additional SIP Types<a class="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>
<dl class="sip-type">
<dt id="sip-type-SIP_ANYSLOT">
<code class="descname">SIP_ANYSLOT</code><a class="headerlink" href="#sip-type-SIP_ANYSLOT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is both a <code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> and a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is used as the type
of the member instead of <code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> 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>
<dl class="sip-type">
<dt id="sip-type-SIP_PYBUFFER">
<code class="descname">SIP_PYBUFFER</code><a class="headerlink" href="#sip-type-SIP_PYBUFFER" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that implements the Python buffer protocol.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYCALLABLE">
<code class="descname">SIP_PYCALLABLE</code><a class="headerlink" href="#sip-type-SIP_PYCALLABLE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is a Python callable object.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYDICT">
<code class="descname">SIP_PYDICT</code><a class="headerlink" href="#sip-type-SIP_PYDICT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is a Python dictionary object.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYLIST">
<code class="descname">SIP_PYLIST</code><a class="headerlink" href="#sip-type-SIP_PYLIST" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is a Python list object.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYOBJECT">
<code class="descname">SIP_PYOBJECT</code><a class="headerlink" href="#sip-type-SIP_PYOBJECT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> of any Python type. The type <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> can also
be used.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYSLICE">
<code class="descname">SIP_PYSLICE</code><a class="headerlink" href="#sip-type-SIP_PYSLICE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is a Python slice object.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYTUPLE">
<code class="descname">SIP_PYTUPLE</code><a class="headerlink" href="#sip-type-SIP_PYTUPLE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is a Python tuple object.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_PYTYPE">
<code class="descname">SIP_PYTYPE</code><a class="headerlink" href="#sip-type-SIP_PYTYPE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">PyObject</span> <span class="pre">*</span></code> that is a Python type object.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_QOBJECT">
<code class="descname">SIP_QOBJECT</code><a class="headerlink" href="#sip-type-SIP_QOBJECT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></code> that is a C++ instance of a class derived from Qt’s
<code class="docutils literal"><span class="pre">QObject</span></code> class.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_RXOBJ_CON">
<code class="descname">SIP_RXOBJ_CON</code><a class="headerlink" href="#sip-type-SIP_RXOBJ_CON" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></code> that is a C++ instance of a class derived from Qt’s
<code class="docutils literal"><span class="pre">QObject</span></code> class. It is used as the type of the receiver instead of <code class="docutils literal"><span class="pre">const</span>
<span class="pre">QObject</span> <span class="pre">*</span></code> in functions that implement a connection to a slot.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_RXOBJ_DIS">
<code class="descname">SIP_RXOBJ_DIS</code><a class="headerlink" href="#sip-type-SIP_RXOBJ_DIS" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">QObject</span> <span class="pre">*</span></code> that is a C++ instance of a class derived from Qt’s
<code class="docutils literal"><span class="pre">QObject</span></code> class. It is used as the type of the receiver instead of <code class="docutils literal"><span class="pre">const</span>
<span class="pre">QObject</span> <span class="pre">*</span></code> in functions that implement a disconnection from a slot.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_SIGNAL">
<code class="descname">SIP_SIGNAL</code><a class="headerlink" href="#sip-type-SIP_SIGNAL" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> that is used as the type of the signal instead of
<code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> in functions that implement the connection or disconnection
of an explicitly generated signal to a slot.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_SLOT">
<code class="descname">SIP_SLOT</code><a class="headerlink" href="#sip-type-SIP_SLOT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> that is used as the type of the member instead of
<code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> in functions that implement the connection or disconnection
of an explicitly generated signal to a slot.</p>
<dl class="sip-type">
<dt id="sip-type-SIP_SLOT_CON">
<code class="descname">SIP_SLOT_CON</code><a class="headerlink" href="#sip-type-SIP_SLOT_CON" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> that is used as the type of the member instead of
<code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> in functions that implement the connection of an internally
generated signal to a slot. The type includes a comma separated list of types
that is the C++ signature of of the signal.</p>
<p>To take an example, <code class="docutils literal"><span class="pre">QAccel::connectItem()</span></code> connects an internally generated
signal to a slot. The signal is emitted when the keyboard accelerator is
activated and it has a single integer argument that is the ID of the
accelerator. The C++ signature is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">bool</span> <span class="n">connectItem</span><span class="p">(</span><span class="nb">int</span> <span class="nb">id</span><span class="p">,</span> <span class="n">const</span> <span class="n">QObject</span> <span class="o">*</span><span class="n">receiver</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">member</span><span class="p">);</span>
</pre></div>
</div>
<p>The corresponding SIP specification is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nb">bool</span> <span class="n">connectItem</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">SIP_RXOBJ_CON</span><span class="p">,</span> <span class="n">SIP_SLOT_CON</span><span class="p">(</span><span class="nb">int</span><span class="p">));</span>
</pre></div>
</div>
<dl class="sip-type">
<dt id="sip-type-SIP_SLOT_DIS">
<code class="descname">SIP_SLOT_DIS</code><a class="headerlink" href="#sip-type-SIP_SLOT_DIS" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 4.18.</span></p>
</div>
<p>This is a <code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> that is used as the type of the member instead of
<code class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></code> 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>
<dl class="sip-type">
<dt id="sip-type-SIP_SSIZE_T">
<code class="descname">SIP_SSIZE_T</code><a class="headerlink" href="#sip-type-SIP_SSIZE_T" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a <code class="docutils literal"><span class="pre">Py_ssize_t</span></code> in Python v2.5 and later and <code class="docutils literal"><span class="pre">int</span></code> in earlier
versions of Python.</p>
</div>
<div class="section" id="classic-division-and-true-division">
<h2>Classic Division and True Division<a class="headerlink" href="#classic-division-and-true-division" title="Permalink to this headline">¶</a></h2>
<p>SIP supports the <code class="docutils literal"><span class="pre">__div__</span></code> and <code class="docutils literal"><span class="pre">__truediv__</span></code> special methods (and the
corresponding inplace versions) for both Python v2 and v3.</p>
<p>For Python v2 the <code class="docutils literal"><span class="pre">__div__</span></code> method will be used for both classic and true
division if a <code class="docutils literal"><span class="pre">__truediv__</span></code> method is not defined.</p>
<p>For Python v3 the <code class="docutils literal"><span class="pre">__div__</span></code> method will be used for true division if a
<code class="docutils literal"><span class="pre">__truediv__</span></code> method is not defined.</p>
<p>For all versions of Python, if both methods are defined then <code class="docutils literal"><span class="pre">__div__</span></code>
should be defined first.</p>
</div>
<div class="section" id="namespaces">
<h2>Namespaces<a class="headerlink" href="#namespaces" title="Permalink to this headline">¶</a></h2>
<p>SIP implements C++ namespaces as a Python class which cannot be instantiated.
The contents of the namespace, including nested namespaces, are implemented as
attributes of the class.</p>
<p>The namespace class is created in the module that SIP is parsing when it first
sees the namespace defined. If a function (for example) is defined in a
namespace that is first defined in another module then the function is added to
the namespace class in that other module.</p>
<p>Say that we have a file <code class="docutils literal"><span class="pre">a.sip</span></code> that defines a module <code class="docutils literal"><span class="pre">a_module</span></code> as
follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">Module</span> <span class="n">a_module</span>
<span class="n">namespace</span> <span class="n">N</span>
<span class="p">{</span>
<span class="n">void</span> <span class="n">hello</span><span class="p">();</span>
<span class="p">};</span>
</pre></div>
</div>
<p>We also have a file <code class="docutils literal"><span class="pre">b.sip</span></code> that defines a module <code class="docutils literal"><span class="pre">b_module</span></code> as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">Module</span> <span class="n">b_module</span>
<span class="o">%</span><span class="n">Import</span> <span class="n">a</span><span class="o">.</span><span class="n">sip</span>
<span class="n">namespace</span> <span class="n">N</span>
<span class="p">{</span>
<span class="n">void</span> <span class="n">bye</span><span class="p">();</span>
<span class="p">};</span>
</pre></div>
</div>
<p>When SIP parses <code class="docutils literal"><span class="pre">b.sip</span></code> it first sees the <code class="docutils literal"><span class="pre">N</span></code> namespace defined in module
<code class="docutils literal"><span class="pre">a_module</span></code>. Therefore it places the <code class="docutils literal"><span class="pre">bye()</span></code> function in the <code class="docutils literal"><span class="pre">N</span></code> Python
class in the <code class="docutils literal"><span class="pre">a_module</span></code>. It does not create an <code class="docutils literal"><span class="pre">N</span></code> Python class in the
<code class="docutils literal"><span class="pre">b_module</span></code>. Consequently the following code will call the <code class="docutils literal"><span class="pre">bye()</span></code>
function:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">a_module</span>
<span class="kn">import</span> <span class="nn">b_module</span>
<span class="n">a_module</span><span class="o">.</span><span class="n">N</span><span class="o">.</span><span class="n">bye</span><span class="p">()</span>
</pre></div>
</div>
<p>While this reflects the C++ usage it may not be obvious to the Python
programmer who might expect to call the <code class="docutils literal"><span class="pre">bye()</span></code> function using:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">b_module</span>
<span class="n">b_module</span><span class="o">.</span><span class="n">N</span><span class="o">.</span><span class="n">bye</span><span class="p">()</span>
</pre></div>
</div>
<p>In order to achieve this behavior make sure that the <code class="docutils literal"><span class="pre">N</span></code> namespace is first
defined in the <code class="docutils literal"><span class="pre">b_module</span></code>. The following version of <code class="docutils literal"><span class="pre">b.sip</span></code> does this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">Module</span> <span class="n">b_module</span>
<span class="n">namespace</span> <span class="n">N</span><span class="p">;</span>
<span class="o">%</span><span class="n">Import</span> <span class="n">a</span><span class="o">.</span><span class="n">sip</span>
<span class="n">namespace</span> <span class="n">N</span>
<span class="p">{</span>
<span class="n">void</span> <span class="n">bye</span><span class="p">();</span>
<span class="p">};</span>
</pre></div>
</div>
<p>Alternatively you could just move the <a class="reference internal" href="directives.html#directive-%Import"><code class="xref std std-directive docutils literal"><span class="pre">%Import</span></code></a> directive so that it
is at the end of the file.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">SIP Specification Files</a><ul>
<li><a class="reference internal" href="#syntax-definition">Syntax Definition</a></li>
<li><a class="reference internal" href="#variable-numbers-of-arguments">Variable Numbers of Arguments</a></li>
<li><a class="reference internal" href="#additional-sip-types">Additional SIP Types</a></li>
<li><a class="reference internal" href="#classic-division-and-true-division">Classic Division and True Division</a></li>
<li><a class="reference internal" href="#namespaces">Namespaces</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="command_line.html"
title="previous chapter">The SIP Command Line</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="directives.html"
title="next chapter">Directives</a></p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="directives.html" title="Directives"
>next</a> |</li>
<li class="right" >
<a href="command_line.html" title="The SIP Command Line"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">SIP 4.18 Reference Guide</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015 Riverbank Computing Limited.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.
</div>
</body>
</html>