You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
901 lines
58 KiB
901 lines
58 KiB
<!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 PyTQt4 API up to but excluding v2.
|
|
void hex() /API=PyTQt4:-2/
|
|
|
|
# This is part of the PyTQt4 API starting from v2.
|
|
void hex() /PyName=hex_, API=PyTQt4:2-/</pre>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
<p>The following example shows argument and function annotations:</p>
|
|
<div class="highlight-python"><pre>void exec(TQWidget * /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> |