diff options
Diffstat (limited to 'doc/html/annotations.html')
| -rw-r--r-- | doc/html/annotations.html | 901 |
1 files changed, 901 insertions, 0 deletions
diff --git a/doc/html/annotations.html b/doc/html/annotations.html new file mode 100644 index 0000000..fc76524 --- /dev/null +++ b/doc/html/annotations.html @@ -0,0 +1,901 @@ +<!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>Annotations — SIP 4.10.5 Reference Guide</title> + <link rel="stylesheet" href="_static/default.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.10.5', + COLLAPSE_MODINDEX: false, + FILE_SUFFIX: '.html', + HAS_SOURCE: true + }; + </script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="top" title="SIP 4.10.5 Reference Guide" href="index.html" /> + <link rel="next" title="C API for Handwritten Code" href="c_api.html" /> + <link rel="prev" title="Directives" href="directives.html" /> + </head> + <body> + <div class="related"> + <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="modindex.html" title="Global Module Index" + accesskey="M">modules</a> |</li> + <li class="right" > + <a href="c_api.html" title="C API for Handwritten Code" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="directives.html" title="Directives" + accesskey="P">previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> + + <div class="section" id="annotations"> +<h1>Annotations<a class="headerlink" href="#annotations" title="Permalink to this headline">¶</a></h1> +<p>In this section we describe each of the annotations that can be used in +specification files.</p> +<p>Annotations can either be <a class="reference internal" href="#ref-arg-annos"><em>argument annotations</em></a>, +<a class="reference internal" href="#ref-class-annos"><em>class annotations</em></a>, <a class="reference internal" href="#ref-mapped-type-annos"><em>mapped type annotations</em></a>, <a class="reference internal" href="#ref-enum-annos"><em>enum annotations</em></a>, +<a class="reference internal" href="#ref-exception-annos"><em>exception annotations</em></a>, <a class="reference internal" href="#ref-function-annos"><em>function annotations</em></a>, <a class="reference internal" href="#ref-license-annos"><em>license annotations</em></a>, +<a class="reference internal" href="#ref-typedef-annos"><em>typedef annotations</em></a> or <a class="reference internal" href="#ref-variable-annos"><em>variable annotations</em></a> depending on the context in which they can be used.</p> +<p>Annotations are placed between forward slashes (<tt class="docutils literal"><span class="pre">/</span></tt>). Multiple annotations +are comma separated within the slashes.</p> +<p>Annotations have a type and, possibly, a value. The type determines the +format of the value. The name of an annotation and its value are separated by +<tt class="docutils literal"><span class="pre">=</span></tt>.</p> +<p>Annotations can have one of the following types:</p> +<dl class="docutils"> +<dt><em>boolean</em></dt> +<dd>This type of annotation has no value and is implicitly true.</dd> +<dt><em>name</em></dt> +<dd>The value is a name that is compatible with a C/C++ identifier. In some +cases the value is optional.</dd> +<dt><em>dotted name</em></dt> +<dd>The value is a name that is compatible with an identifier preceded by a +Python scope.</dd> +<dt><em>string</em></dt> +<dd>The value is a double quoted string.</dd> +<dt><em>API range</em></dt> +<dd><p class="first">The value is the name of an API (defined using the <a class="reference external" href="directives.html#directive-%API"><tt class="xref docutils literal"><span class="pre">%API</span></tt></a> +directive) separated by a range of version numbers with a colon.</p> +<p>The range of version numbers is a pair of numbers separated by a hyphen +specifying the lower and upper bounds of the range. A version number is +within the range if it is greater or equal to the lower bound and less +than the upper bound. Each bound can be omitted meaning that the range is +unbounded in that direction.</p> +<p>For example:</p> +<div class="last highlight-python"><pre># This is part of the PyQt4 API up to but excluding v2. +void hex() /API=PyQt4:-2/ + +# This is part of the PyQt4 API starting from v2. +void hex() /PyName=hex_, API=PyQt4:2-/</pre> +</div> +</dd> +</dl> +<p>The following example shows argument and function annotations:</p> +<div class="highlight-python"><pre>void exec(QWidget * /Transfer/) /ReleaseGIL, PyName=call_exec/;</pre> +</div> +<p>Note that the current version of SIP does not complain about unknown +annotations, or annotations used out of their correct context.</p> +<div class="section" id="argument-annotations"> +<span id="ref-arg-annos"></span><h2>Argument Annotations<a class="headerlink" href="#argument-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="argument-annotation"> +<dt id="aanno-AllowNone"> +<tt class="descname">AllowNone</tt><a class="headerlink" href="#aanno-AllowNone" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the value of the corresponding +argument (which should be either <a class="reference external" href="specification_files.html#stype-SIP_PYCALLABLE"><tt class="xref docutils literal"><span class="pre">SIP_PYCALLABLE</span></tt></a>, +<a class="reference external" href="specification_files.html#stype-SIP_PYDICT"><tt class="xref docutils literal"><span class="pre">SIP_PYDICT</span></tt></a>, <a class="reference external" href="specification_files.html#stype-SIP_PYLIST"><tt class="xref docutils literal"><span class="pre">SIP_PYLIST</span></tt></a>, <a class="reference external" href="specification_files.html#stype-SIP_PYSLICE"><tt class="xref docutils literal"><span class="pre">SIP_PYSLICE</span></tt></a>, +<a class="reference external" href="specification_files.html#stype-SIP_PYTUPLE"><tt class="xref docutils literal"><span class="pre">SIP_PYTUPLE</span></tt></a> or <a class="reference external" href="specification_files.html#stype-SIP_PYTYPE"><tt class="xref docutils literal"><span class="pre">SIP_PYTYPE</span></tt></a>) may be <tt class="xref docutils literal"><span class="pre">None</span></tt>.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Array"> +<tt class="descname">Array</tt><a class="headerlink" href="#aanno-Array" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that the corresponding argument refers +to an array.</p> +<p>The argument should be either a pointer to a wrapped type, a <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or +a <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt>. If the argument is a character array then the +annotation also implies the <a class="reference internal" href="#aanno-Encoding"><tt class="xref docutils literal"><span class="pre">Encoding</span></tt></a> annotation with an encoding +of <tt class="docutils literal"><span class="pre">"None"</span></tt>.</p> +<p>There must be a corresponding argument with the <a class="reference internal" href="#aanno-ArraySize"><tt class="xref docutils literal"><span class="pre">ArraySize</span></tt></a> +annotation specified. The annotation may only be specified once in a list +of arguments.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-ArraySize"> +<tt class="descname">ArraySize</tt><a class="headerlink" href="#aanno-ArraySize" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span></tt>, +<tt class="docutils literal"><span class="pre">long</span></tt> or <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>) refers to the size of an array. There must +be a corresponding argument with the <a class="reference internal" href="#aanno-Array"><tt class="xref docutils literal"><span class="pre">Array</span></tt></a> annotation specified. +The annotation may only be specified once in a list of arguments.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Constrained"> +<tt class="descname">Constrained</tt><a class="headerlink" href="#aanno-Constrained" title="Permalink to this definition">¶</a></dt> +<dd><p>Python will automatically convert between certain compatible types. For +example, if a floating pointer number is expected and an integer supplied, +then the integer will be converted appropriately. This can cause problems +when wrapping C or C++ functions with similar signatures. For example:</p> +<div class="highlight-python"><pre>// The wrapper for this function will also accept an integer argument +// which Python will automatically convert to a floating point number. +void foo(double); + +// The wrapper for this function will never get used. +void foo(int);</pre> +</div> +<p>This boolean annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">bool</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">double</span></tt>, <tt class="docutils literal"><span class="pre">enum</span></tt> or a +wrapped class) must match the type without any automatic conversions. In +the context of a wrapped class the invocation of any +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is suppressed.</p> +<p>The following example gets around the above problem:</p> +<div class="highlight-python"><pre>// The wrapper for this function will only accept floating point +// numbers. +void foo(double /Constrained/); + +// The wrapper for this function will be used for anything that Python +// can convert to an integer, except for floating point numbers. +void foo(int);</pre> +</div> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#aanno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the type of the argument as it will appear +in any generated docstrings. It is usually used with arguments of type +<a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-DocValue"> +<tt class="descname">DocValue</tt><a class="headerlink" href="#aanno-DocValue" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the default value of the argument as it +will appear in any generated docstrings.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Encoding"> +<tt class="descname">Encoding</tt><a class="headerlink" href="#aanno-Encoding" title="Permalink to this definition">¶</a></dt> +<dd><p>This string annotation specifies that the corresponding argument (which +should be either <tt class="docutils literal"><span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt>) +refers to an encoded character or <tt class="docutils literal"><span class="pre">'\0'</span></tt> terminated encoded string with +the specified encoding. The encoding can be either <tt class="docutils literal"><span class="pre">"ASCII"</span></tt>, +<tt class="docutils literal"><span class="pre">"Latin-1"</span></tt>, <tt class="docutils literal"><span class="pre">"UTF-8"</span></tt> or <tt class="docutils literal"><span class="pre">"None"</span></tt>. An encoding of <tt class="docutils literal"><span class="pre">"None"</span></tt> means +that the corresponding argument refers to an unencoded character or string.</p> +<p>The default encoding is specified by the <a class="reference external" href="directives.html#directive-%DefaultEncoding"><tt class="xref docutils literal"><span class="pre">%DefaultEncoding</span></tt></a> +directive. If the directive is not specified then <tt class="xref docutils literal"><span class="pre">None</span></tt> is used.</p> +<p>Python v3 will use the <tt class="docutils literal"><span class="pre">bytes</span></tt> type to represent the argument if the +encoding is <tt class="docutils literal"><span class="pre">"None"</span></tt> and the <tt class="docutils literal"><span class="pre">str</span></tt> type otherwise.</p> +<p>Python v2 will use the <tt class="docutils literal"><span class="pre">str</span></tt> type to represent the argument if the +encoding is <tt class="docutils literal"><span class="pre">"None"</span></tt> and the <tt class="docutils literal"><span class="pre">unicode</span></tt> type otherwise.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-GetWrapper"> +<tt class="descname">GetWrapper</tt><a class="headerlink" href="#aanno-GetWrapper" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is only ever used in conjunction with handwritten +code specified with the <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> directive. It causes an +extra variable to be generated for the corresponding argument which is a +pointer to the Python object that wraps the argument.</p> +<p>See the <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> directive for more detail.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-In"> +<tt class="descname">In</tt><a class="headerlink" href="#aanno-In" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used to pass a value to the function.</p> +<p>For pointers to wrapped C structures or C++ class instances, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt> then this annotation is assumed unless the <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> +annotation is specified.</p> +<p>For pointers to other types then this annotation must be explicitly +specified if required. The argument will be dereferenced to obtain the +actual value.</p> +<p>Both <a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> and <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> may be specified for the same argument.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-KeepReference"> +<tt class="descname">KeepReference</tt><a class="headerlink" href="#aanno-KeepReference" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that a reference to the +corresponding argument should be kept to ensure that the object is not +garbage collected. If the method is called again with a new argument then +the reference to the previous argument is discarded. Note that ownership +of the argument is not changed.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-NoCopy"> +<tt class="descname">NoCopy</tt><a class="headerlink" href="#aanno-NoCopy" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.1.</span></p> +<p>This boolean annotation is used with arguments of virtual methods that are +a <tt class="docutils literal"><span class="pre">const</span></tt> reference to a class. Normally, if the class defines a copy +constructor then a copy of the returned reference is automatically created +and wrapped before being passed to a Python reimplementation of the method. +The copy will be owned by Python. This means that the reimplementation may +take a reference to the argument without having to make an explicit copy.</p> +<p>If the annotation is specified then the copy is not made and the original +reference is wrapped instead and will be owned by C++.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Out"> +<tt class="descname">Out</tt><a class="headerlink" href="#aanno-Out" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is used to specify that the corresponding argument +(which should be a pointer type) is used by the function to return a value +as an element of a tuple.</p> +<p>For pointers to wrapped C structures or C++ class instances, <tt class="docutils literal"><span class="pre">char</span> <span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span> <span class="pre">*</span></tt> then this annotation must be explicitly specified if +required.</p> +<p>For pointers to other types then this annotation is assumed unless the +<a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> annotation is specified.</p> +<p>Both <a class="reference internal" href="#aanno-In"><tt class="xref docutils literal"><span class="pre">In</span></tt></a> and <a class="reference internal" href="#aanno-Out"><tt class="xref docutils literal"><span class="pre">Out</span></tt></a> may be specified for the same argument.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-ResultSize"> +<tt class="descname">ResultSize</tt><a class="headerlink" href="#aanno-ResultSize" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used with functions or methods that return a +<tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">void</span> <span class="pre">*</span></tt>. It identifies an argument that defines the +size of the block of memory whose address is being returned. This allows +the <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> object that wraps the address to support the Python +buffer protocol and allows the memory to be read and updated when wrapped +by the Python <tt class="docutils literal"><span class="pre">buffer()</span></tt> builtin.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-SingleShot"> +<tt class="descname">SingleShot</tt><a class="headerlink" href="#aanno-SingleShot" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used only with arguments of type +<a class="reference external" href="specification_files.html#stype-SIP_RXOBJ_CON"><tt class="xref docutils literal"><span class="pre">SIP_RXOBJ_CON</span></tt></a> to specify that the signal connected to the slot +will only ever be emitted once. This prevents a certain class of memory +leaks.</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-Transfer"> +<tt class="descname">Transfer</tt><a class="headerlink" href="#aanno-Transfer" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is used to specify that ownership of the +corresponding argument (which should be a wrapped C structure or C++ class +instance) is transferred from Python to C++. In addition, if the argument +is of a class method, then it is associated with the class instance with +regard to the cyclic garbage collector.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-TransferBack"> +<tt class="descname">TransferBack</tt><a class="headerlink" href="#aanno-TransferBack" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is used to specify that ownership of the +corresponding argument (which should be a wrapped C structure or C++ class +instance) is transferred back to Python from C++. In addition, any +association of the argument with regard to the cyclic garbage collector +with another instance is removed.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="argument-annotation"> +<dt id="aanno-TransferThis"> +<tt class="descname">TransferThis</tt><a class="headerlink" href="#aanno-TransferThis" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is only used in C++ constructors or methods. In +the context of a constructor or factory method it specifies that ownership +of the instance being created is transferred from Python to C++ if the +corresponding argument (which should be a wrapped C structure or C++ class +instance) is not <tt class="xref docutils literal"><span class="pre">None</span></tt>. In addition, the newly created instance is +associated with the argument with regard to the cyclic garbage collector.</p> +<p>In the context of a non-factory method it specifies that ownership of +<tt class="docutils literal"><span class="pre">this</span></tt> is transferred from Python to C++ if the corresponding argument is +not <tt class="xref docutils literal"><span class="pre">None</span></tt>. If it is <tt class="xref docutils literal"><span class="pre">None</span></tt> then ownership is transferred to Python.</p> +<p>The annotation may be used more that once, in which case ownership is +transferred to last instance that is not <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +</div> +<div class="section" id="class-annotations"> +<span id="ref-class-annos"></span><h2>Class Annotations<a class="headerlink" href="#class-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="class-annotation"> +<dt id="canno-Abstract"> +<tt class="descname">Abstract</tt><a class="headerlink" href="#canno-Abstract" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that the class has additional +pure virtual methods that have not been specified and so it cannot be +instantiated or sub-classed from Python.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-AllowNone"> +<tt class="descname">AllowNone</tt><a class="headerlink" href="#canno-AllowNone" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.8.2.</span></p> +<p>Normally when a Python object is converted to a C/C++ instance <tt class="xref docutils literal"><span class="pre">None</span></tt> +is handled automatically before the class’s +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is called. This boolean annotation +specifies that the handling of <tt class="xref docutils literal"><span class="pre">None</span></tt> will be left to the +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>. The annotation is ignored if the class +does not have any <a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-API"> +<tt class="descname">API</tt><a class="headerlink" href="#canno-API" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This API range annotation is used to specify an API and corresponding +range of version numbers that the class is enabled for.</p> +<p>If a class or mapped type has different implementations enabled for +different ranges of version numbers then those ranges must not overlap.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-DelayDtor"> +<tt class="descname">DelayDtor</tt><a class="headerlink" href="#canno-DelayDtor" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation is used to specify that the class’s destructor +should not be called until the Python interpreter exits. It would normally +only be applied to singleton classes.</p> +<p>When the Python interpreter exits the order in which any wrapped instances +are garbage collected is unpredictable. However, the underlying C or C++ +instances may need to be destroyed in a certain order. If this annotation +is specified then when the wrapped instance is garbage collected the C or +C++ instance is not destroyed but instead added to a list of delayed +instances. When the interpreter exits then the function +<a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> is called with the list of delayed instances. +<a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> can then choose to call (or ignore) the +destructors in any desired order.</p> +<p>The <a title="sipDelayedDtors" class="reference internal" href="#sipDelayedDtors"><tt class="xref docutils literal"><span class="pre">sipDelayedDtors()</span></tt></a> function must be specified using the +<a class="reference external" href="directives.html#directive-%ModuleCode"><tt class="xref docutils literal"><span class="pre">%ModuleCode</span></tt></a> directive.</p> +</dd></dl> + +<dl class="cfunction"> +<dt id="sipDelayedDtors"> +void <tt class="descname">sipDelayedDtors</tt><big>(</big>const <a title="sipDelayedDtor" class="reference internal" href="#sipDelayedDtor">sipDelayedDtor</a><em> *dd_list</em><big>)</big><a class="headerlink" href="#sipDelayedDtors" title="Permalink to this definition">¶</a></dt> +<dd><table class="docutils field-list" frame="void" rules="none"> +<col class="field-name" /> +<col class="field-body" /> +<tbody valign="top"> +<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>dd_list</em> – the linked list of delayed instances.</td> +</tr> +</tbody> +</table> +</dd></dl> + +<dl class="ctype"> +<dt id="sipDelayedDtor"> +<tt class="descname">sipDelayedDtor</tt><a class="headerlink" href="#sipDelayedDtor" title="Permalink to this definition">¶</a></dt> +<dd><p>This structure describes a particular delayed destructor.</p> +<dl class="cmember"> +<dt id="dd_name"> +const char *<tt class="descname">dd_name</tt><a class="headerlink" href="#dd_name" title="Permalink to this definition">¶</a></dt> +<dd>This is the name of the class excluding any package or module name.</dd></dl> + +<dl class="cmember"> +<dt id="dd_ptr"> +void *<tt class="descname">dd_ptr</tt><a class="headerlink" href="#dd_ptr" title="Permalink to this definition">¶</a></dt> +<dd>This is the address of the C or C++ instance to be destroyed. It’s +exact type depends on the value of <a title="dd_isderived" class="reference internal" href="#dd_isderived"><tt class="xref docutils literal"><span class="pre">dd_isderived</span></tt></a>.</dd></dl> + +<dl class="cmember"> +<dt id="dd_isderived"> +int <tt class="descname">dd_isderived</tt><a class="headerlink" href="#dd_isderived" title="Permalink to this definition">¶</a></dt> +<dd>This is non-zero if the type of <a title="dd_ptr" class="reference internal" href="#dd_ptr"><tt class="xref docutils literal"><span class="pre">dd_ptr</span></tt></a> is actually the +generated derived class. This allows the correct destructor to be +called. See <a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>.</dd></dl> + +<dl class="cmember"> +<dt id="dd_next"> +<a title="sipDelayedDtor" class="reference internal" href="#sipDelayedDtor">sipDelayedDtor</a> *<tt class="descname">dd_next</tt><a class="headerlink" href="#dd_next" title="Permalink to this definition">¶</a></dt> +<dd>This is the address of the next entry in the list or zero if this is +the last one.</dd></dl> + +<p>Note that the above applies only to C and C++ instances that are owned by +Python.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-Deprecated"> +<tt class="descname">Deprecated</tt><a class="headerlink" href="#canno-Deprecated" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that the class is deprecated. +It is the equivalent of annotating all the class’s constructors, function +and methods as being deprecated.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-External"> +<tt class="descname">External</tt><a class="headerlink" href="#canno-External" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that the class is defined in +another module. Declarations of external classes are private to the module +in which they appear.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-Metatype"> +<tt class="descname">Metatype</tt><a class="headerlink" href="#canno-Metatype" title="Permalink to this definition">¶</a></dt> +<dd><p>This dotted name annotation specifies the name of the Python type object +(i.e. the value of the <tt class="docutils literal"><span class="pre">tp_name</span></tt> field) used as the meta-type used when +creating the type object for this C structure or C++ type.</p> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-NoDefaultCtors"> +<tt class="descname">NoDefaultCtors</tt><a class="headerlink" href="#canno-NoDefaultCtors" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to suppress the automatic generation of +default constructors for the class.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#canno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation specifies an alternative name for the class being +wrapped which is used when it is referred to from Python. It is required +when a class name is the same as a Python keyword. It may also be used to +avoid name clashes with other objects (e.g. enums, exceptions, functions) +that have the same name in the same C++ scope.</dd></dl> + +<dl class="class-annotation"> +<dt id="canno-Supertype"> +<tt class="descname">Supertype</tt><a class="headerlink" href="#canno-Supertype" title="Permalink to this definition">¶</a></dt> +<dd><p>This dotted name annotation specifies the name of the Python type object +(i.e. the value of the <tt class="docutils literal"><span class="pre">tp_name</span></tt> field) used as the super-type used when +creating the type object for this C structure or C++ type.</p> +<p>See the section <a class="reference external" href="using.html#ref-types-metatypes"><em>Types and Meta-types</em></a> for more details.</p> +</dd></dl> + +</div> +<div class="section" id="mapped-type-annotations"> +<span id="ref-mapped-type-annos"></span><h2>Mapped Type Annotations<a class="headerlink" href="#mapped-type-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="mapped-type-annotation"> +<dt id="manno-AllowNone"> +<tt class="descname">AllowNone</tt><a class="headerlink" href="#manno-AllowNone" title="Permalink to this definition">¶</a></dt> +<dd>Normally when a Python object is converted to a C/C++ instance <tt class="xref docutils literal"><span class="pre">None</span></tt> +is handled automatically before the mapped type’s +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> is called. This boolean annotation +specifies that the handling of <tt class="xref docutils literal"><span class="pre">None</span></tt> will be left to the +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a>.</dd></dl> + +<dl class="mapped-type-annotation"> +<dt id="manno-API"> +<tt class="descname">API</tt><a class="headerlink" href="#manno-API" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This API range annotation is used to specify an API and corresponding +range of version numbers that the mapped type is enabled for.</p> +<p>If a class or mapped type has different implementations enabled for +different ranges of version numbers then those ranges must not overlap.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +</dd></dl> + +<dl class="mapped-type-annotation"> +<dt id="manno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#manno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the name of the type as it will appear in +any generated docstrings.</p> +</dd></dl> + +<dl class="mapped-type-annotation"> +<dt id="manno-NoRelease"> +<tt class="descname">NoRelease</tt><a class="headerlink" href="#manno-NoRelease" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that the mapped type does not +support the <a title="sipReleaseType" class="reference external" href="c_api.html#sipReleaseType"><tt class="xref docutils literal"><span class="pre">sipReleaseType()</span></tt></a> function. Any +<a class="reference external" href="directives.html#directive-%ConvertToTypeCode"><tt class="xref docutils literal"><span class="pre">%ConvertToTypeCode</span></tt></a> should not create temporary instances of +the mapped type, i.e. it should not return <tt class="xref docutils literal"><span class="pre">SIP_TEMPORARY</span></tt>.</dd></dl> + +</div> +<div class="section" id="enum-annotations"> +<span id="ref-enum-annos"></span><h2>Enum Annotations<a class="headerlink" href="#enum-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="enum-annotation"> +<dt id="eanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#eanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation specifies an alternative name for the enum or enum +member being wrapped which is used when it is referred to from Python. It +is required when an enum or enum member name is the same as a Python +keyword. It may also be used to avoid name clashes with other objects +(e.g. classes, exceptions, functions) that have the same name in the same +C++ scope.</dd></dl> + +</div> +<div class="section" id="exception-annotations"> +<span id="ref-exception-annos"></span><h2>Exception Annotations<a class="headerlink" href="#exception-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="exception-annotation"> +<dt id="xanno-Default"> +<tt class="descname">Default</tt><a class="headerlink" href="#xanno-Default" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the exception being defined will be +used as the default exception to be caught if a function or constructor +does not have a <tt class="docutils literal"><span class="pre">throw</span></tt> clause.</dd></dl> + +<dl class="exception-annotation"> +<dt id="xanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#xanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation specifies an alternative name for the exception being +defined which is used when it is referred to from Python. It is required +when an exception name is the same as a Python keyword. It may also be +used to avoid name clashes with other objects (e.g. classes, enums, +functions) that have the same name.</dd></dl> + +</div> +<div class="section" id="function-annotations"> +<span id="ref-function-annos"></span><h2>Function Annotations<a class="headerlink" href="#function-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="function-annotation"> +<dt id="fanno-API"> +<tt class="descname">API</tt><a class="headerlink" href="#fanno-API" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.9.</span></p> +<p>This API range annotation is used to specify an API and corresponding +range of version numbers that the function is enabled for.</p> +<p>See <a class="reference external" href="using.html#ref-incompat-apis"><em>Managing Incompatible APIs</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-AutoGen"> +<tt class="descname">AutoGen</tt><a class="headerlink" href="#fanno-AutoGen" title="Permalink to this definition">¶</a></dt> +<dd>This optional name annotation is used with class methods to specify that +the method be automatically included in all sub-classes. The value is the +name of a feature (specified using the <a class="reference external" href="directives.html#directive-%Feature"><tt class="xref docutils literal"><span class="pre">%Feature</span></tt></a> directive) +which must be enabled for the method to be generated.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Default"> +<tt class="descname">Default</tt><a class="headerlink" href="#fanno-Default" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is only used with C++ constructors. Sometimes SIP +needs to create a class instance. By default it uses a constructor with no +compulsory arguments if one is specified. (SIP will automatically generate +a constructor with no arguments if no constructors are specified.) This +annotation is used to explicitly specify which constructor to use. Zero is +passed as the value of any arguments to the constructor.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Deprecated"> +<tt class="descname">Deprecated</tt><a class="headerlink" href="#fanno-Deprecated" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used to specify that the constructor or function +is deprecated. A deprecation warning is issued whenever the constructor or +function is called.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#fanno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the name of the type of the returned value +as it will appear in any generated docstrings. It is usually used with +values of type <a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Factory"> +<tt class="descname">Factory</tt><a class="headerlink" href="#fanno-Factory" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that the value returned by the function +(which should be a wrapped C structure or C++ class instance) is a newly +created instance and is owned by Python.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-HoldGIL"> +<tt class="descname">HoldGIL</tt><a class="headerlink" href="#fanno-HoldGIL" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the Python Global Interpreter Lock +(GIL) is not released before the call to the underlying C or C++ function. +See <a class="reference external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the <a class="reference internal" href="#fanno-ReleaseGIL"><tt class="xref docutils literal"><span class="pre">ReleaseGIL</span></tt></a> annotation.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-KeywordArgs"> +<tt class="descname">KeywordArgs</tt><a class="headerlink" href="#fanno-KeywordArgs" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This boolean annotation specifies that the argument parser generated for +this function will support passing the parameters using Python’s keyword +argument syntax. Keyword arguments cannot be used for functions that have +unnamed arguments or use an ellipsis to designate that the function has a +variable number of arguments.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-__len__"> +<tt class="descname">__len__</tt><a class="headerlink" href="#fanno-__len__" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.3.</span></p> +<p>This boolean annotation specifies that a <tt class="docutils literal"><span class="pre">__len__()</span></tt> method should be +automatically generated that will use the method being annotated to compute +the value that the <tt class="docutils literal"><span class="pre">__len__()</span></tt> method will return.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NewThread"> +<tt class="descname">NewThread</tt><a class="headerlink" href="#fanno-NewThread" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the function will create a new +thread.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoArgParser"> +<tt class="descname">NoArgParser</tt><a class="headerlink" href="#fanno-NoArgParser" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is used with methods and global functions to +specify that the supplied <a class="reference external" href="directives.html#directive-%MethodCode"><tt class="xref docutils literal"><span class="pre">%MethodCode</span></tt></a> will handle the parsing +of the arguments.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoCopy"> +<tt class="descname">NoCopy</tt><a class="headerlink" href="#fanno-NoCopy" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.1.</span></p> +<p>This boolean annotation is used with methods and global functions that +return a <tt class="docutils literal"><span class="pre">const</span></tt> reference to a class. Normally, if the class defines a +copy constructor then a copy of the returned reference is automatically +created and wrapped. The copy will be owned by Python.</p> +<p>If the annotation is specified then the copy is not made and the original +reference is wrapped instead and will be owned by C++.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoDerived"> +<tt class="descname">NoDerived</tt><a class="headerlink" href="#fanno-NoDerived" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation is only used with C++ constructors. In many cases +SIP generates a derived class for each class being wrapped (see +<a class="reference external" href="c_api.html#ref-derived-classes"><em>Generated Derived Classes</em></a>). This derived class contains constructors with +the same C++ signatures as the class being wrapped. Sometimes you may want +to define a Python constructor that has no corresponding C++ constructor. +This annotation is used to suppress the generation of the constructor in +the derived class.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-NoKeywordArgs"> +<tt class="descname">NoKeywordArgs</tt><a class="headerlink" href="#fanno-NoKeywordArgs" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This boolean annotation specifies that the argument parser generated for +this function will not support passing the parameters using Python’s +keyword argument syntax. In other words, the argument parser will only +support only normal positional arguments. This annotation is useful when +the default setting of allowing keyword arguments has been changed via the +command line, but you would still like certain functions to only support +positional arguments.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Numeric"> +<tt class="descname">Numeric</tt><a class="headerlink" href="#fanno-Numeric" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the operator should be interpreted +as a numeric operator rather than a sequence operator. Python uses the +<tt class="docutils literal"><span class="pre">+</span></tt> operator for adding numbers and concatanating sequences, and the +<tt class="docutils literal"><span class="pre">*</span></tt> operator for multiplying numbers and repeating sequences. SIP tries +to work out which is meant by looking at other operators that have been +defined for the type. If it finds either <tt class="docutils literal"><span class="pre">-</span></tt>, <tt class="docutils literal"><span class="pre">-=</span></tt>, <tt class="docutils literal"><span class="pre">/</span></tt>, <tt class="docutils literal"><span class="pre">/=</span></tt>, +<tt class="docutils literal"><span class="pre">%</span></tt> or <tt class="docutils literal"><span class="pre">%=</span></tt> defined then it assumes that <tt class="docutils literal"><span class="pre">+</span></tt>, <tt class="docutils literal"><span class="pre">+=</span></tt>, <tt class="docutils literal"><span class="pre">*</span></tt> and +<tt class="docutils literal"><span class="pre">*=</span></tt> should be numeric operators. Otherwise, if it finds either <tt class="docutils literal"><span class="pre">[]</span></tt>, +<tt class="xref docutils literal"><span class="pre">__getitem__()</span></tt>, <tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt> or <tt class="xref docutils literal"><span class="pre">__delitem__()</span></tt> defined +then it assumes that they should be sequence operators. This annotation is +used to force SIP to treat the operator as numeric.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-PostHook"> +<tt class="descname">PostHook</tt><a class="headerlink" href="#fanno-PostHook" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation is used to specify the name of a Python builtin that +is called immediately after the call to the underlying C or C++ function or +any handwritten code. The builtin is not called if an error occurred. It +is primarily used to integrate with debuggers.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-PreHook"> +<tt class="descname">PreHook</tt><a class="headerlink" href="#fanno-PreHook" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation is used to specify the name of a Python builtin that +is called immediately after the function’s arguments have been successfully +parsed and before the call to the underlying C or C++ function or any +handwritten code. It is primarily used to integrate with debuggers.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#fanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation specifies an alternative name for the function being +wrapped which is used when it is referred to from Python. It is required +when a function or method name is the same as a Python keyword. It may +also be used to avoid name clashes with other objects (e.g. classes, enums, +exceptions) that have the same name in the same C++ scope.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-ReleaseGIL"> +<tt class="descname">ReleaseGIL</tt><a class="headerlink" href="#fanno-ReleaseGIL" title="Permalink to this definition">¶</a></dt> +<dd>This boolean annotation specifies that the Python Global Interpreter Lock +(GIL) is released before the call to the underlying C or C++ function and +reacquired afterwards. It should be used for functions that might block or +take a significant amount of time to execute. See <a class="reference external" href="using.html#ref-gil"><em>The Python Global Interpreter Lock</em></a> and the +<a class="reference internal" href="#fanno-HoldGIL"><tt class="xref docutils literal"><span class="pre">HoldGIL</span></tt></a> annotation.</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-Transfer"> +<tt class="descname">Transfer</tt><a class="headerlink" href="#fanno-Transfer" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that ownership of the value returned by +the function (which should be a wrapped C structure or C++ class instance) +is transferred to C++. It is only used in the context of a class +constructor or a method.</p> +<p>In the case of methods returned values (unless they are new references to +already wrapped values) are normally owned by C++ anyway. However, in +addition, an association between the returned value and the instance +containing the method is created with regard to the cyclic garbage +collector.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-TransferBack"> +<tt class="descname">TransferBack</tt><a class="headerlink" href="#fanno-TransferBack" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that ownership of the value returned by +the function (which should be a wrapped C structure or C++ class instance) +is transferred back to Python from C++. Normally returned values (unless +they are new references to already wrapped values) are owned by C++. In +addition, any association of the returned value with regard to the cyclic +garbage collector with another instance is removed.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +<dl class="function-annotation"> +<dt id="fanno-TransferThis"> +<tt class="descname">TransferThis</tt><a class="headerlink" href="#fanno-TransferThis" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that ownership of <tt class="docutils literal"><span class="pre">this</span></tt> is transferred +from Python to C++.</p> +<p>See <a class="reference external" href="using.html#ref-object-ownership"><em>Ownership of Objects</em></a> for more detail.</p> +</dd></dl> + +</div> +<div class="section" id="license-annotations"> +<span id="ref-license-annos"></span><h2>License Annotations<a class="headerlink" href="#license-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="license-annotation"> +<dt id="lanno-Licensee"> +<tt class="descname">Licensee</tt><a class="headerlink" href="#lanno-Licensee" title="Permalink to this definition">¶</a></dt> +<dd><p>This optional string annotation specifies the license’s licensee. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +<dl class="license-annotation"> +<dt id="lanno-Signature"> +<tt class="descname">Signature</tt><a class="headerlink" href="#lanno-Signature" title="Permalink to this definition">¶</a></dt> +<dd><p>This optional string annotation specifies the license’s signature. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +<dl class="license-annotation"> +<dt id="lanno-Timestamp"> +<tt class="descname">Timestamp</tt><a class="headerlink" href="#lanno-Timestamp" title="Permalink to this definition">¶</a></dt> +<dd><p>This optional string annotation specifies the license’s timestamp. No +restrictions are placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +<dl class="license-annotation"> +<dt id="lanno-Type"> +<tt class="descname">Type</tt><a class="headerlink" href="#lanno-Type" title="Permalink to this definition">¶</a></dt> +<dd><p>This string annotation specifies the license’s type. No restrictions are +placed on the contents of the string.</p> +<p>See the <a class="reference external" href="directives.html#directive-%License"><tt class="xref docutils literal"><span class="pre">%License</span></tt></a> directive.</p> +</dd></dl> + +</div> +<div class="section" id="typedef-annotations"> +<span id="ref-typedef-annos"></span><h2>Typedef Annotations<a class="headerlink" href="#typedef-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="typedef-annotation"> +<dt id="tanno-NoTypeName"> +<tt class="descname">NoTypeName</tt><a class="headerlink" href="#tanno-NoTypeName" title="Permalink to this definition">¶</a></dt> +<dd><p>This boolean annotation specifies that the definition of the type rather +than the name of the type being defined should be used in the generated +code.</p> +<p>Normally a typedef would be defined as follows:</p> +<div class="highlight-python"><pre>typedef bool MyBool;</pre> +</div> +<p>This would result in <tt class="docutils literal"><span class="pre">MyBool</span></tt> being used in the generated code.</p> +<p>Specifying the annotation means that <tt class="docutils literal"><span class="pre">bool</span></tt> will be used in the generated +code instead.</p> +</dd></dl> + +</div> +<div class="section" id="variable-annotations"> +<span id="ref-variable-annos"></span><h2>Variable Annotations<a class="headerlink" href="#variable-annotations" title="Permalink to this headline">¶</a></h2> +<dl class="variable-annotation"> +<dt id="vanno-DocType"> +<tt class="descname">DocType</tt><a class="headerlink" href="#vanno-DocType" title="Permalink to this definition">¶</a></dt> +<dd><p> +<span class="versionmodified">New in version 4.10.</span></p> +<p>This string annotation specifies the name of the type of the variable as it +will appear in any generated docstrings. It is usually used with variables +of type <a class="reference external" href="specification_files.html#stype-SIP_PYOBJECT"><tt class="xref docutils literal"><span class="pre">SIP_PYOBJECT</span></tt></a> to provide a more specific type.</p> +</dd></dl> + +<dl class="variable-annotation"> +<dt id="vanno-PyName"> +<tt class="descname">PyName</tt><a class="headerlink" href="#vanno-PyName" title="Permalink to this definition">¶</a></dt> +<dd>This name annotation specifies an alternative name for the variable being +wrapped which is used when it is referred to from Python. It is required +when a variable name is the same as a Python keyword. It may also be used +to avoid name clashes with other objects (e.g. classes, functions) that +have the same name in the same C++ scope.</dd></dl> + +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table Of Contents</a></h3> + <ul> +<li><a class="reference external" href="#">Annotations</a><ul> +<li><a class="reference external" href="#argument-annotations">Argument Annotations</a></li> +<li><a class="reference external" href="#class-annotations">Class Annotations</a></li> +<li><a class="reference external" href="#mapped-type-annotations">Mapped Type Annotations</a></li> +<li><a class="reference external" href="#enum-annotations">Enum Annotations</a></li> +<li><a class="reference external" href="#exception-annotations">Exception Annotations</a></li> +<li><a class="reference external" href="#function-annotations">Function Annotations</a></li> +<li><a class="reference external" href="#license-annotations">License Annotations</a></li> +<li><a class="reference external" href="#typedef-annotations">Typedef Annotations</a></li> +<li><a class="reference external" href="#variable-annotations">Variable Annotations</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="directives.html" + title="previous chapter">Directives</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="c_api.html" + title="next chapter">C API for Handwritten Code</a></p> + <div id="searchbox" style="display: none"> + <h3>Quick search</h3> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" size="18" /> + <input type="submit" value="Go" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> + <p class="searchtip" style="font-size: 90%"> + Enter search terms or a module, class or function name. + </p> + </div> + <script type="text/javascript">$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related"> + <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="modindex.html" title="Global Module Index" + >modules</a> |</li> + <li class="right" > + <a href="c_api.html" title="C API for Handwritten Code" + >next</a> |</li> + <li class="right" > + <a href="directives.html" title="Directives" + >previous</a> |</li> + <li><a href="index.html">SIP 4.10.5 Reference Guide</a> »</li> + </ul> + </div> + <div class="footer"> + © Copyright 2010 Riverbank Computing Limited. + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4. + </div> + </body> +</html>
\ No newline at end of file |