jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Python function annotations removed from -py3 option.

Browse source 
Python function annotations containing C/C++ types are no longer
generated when using the -py3 option. Function annotations support
has been moved to a feature to provide finer grained control.
It can be turned on globally by adding:

  %feature("python:annotations", "c");

or by using the command line argument:

  -features python:annotations=c

The implementation is designed to be expandable to support different
annotations implementations. Future implementations could implement
something like the following for generating pure Python types:

  %feature("python:annotations", "python");

or typing module types to conform to PEP-484:

  %feature("python:annotations", "typing");

Closes #1561
Issue #735
This commit is contained in:
William S Fulton 2022-02-27 10:06:45 +00:00
commit 2072ae19c9
7 changed files with 133 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

5
Doc/Manual/Contents.html
View file

@ -1478,7 +1478,10 @@
</ul>
<li><a href="Python.html#Python_python3support">Python 3 Support</a>
<ul>
<li><a href="Python.html#Python_nn74">Function annotation</a>
<li><a href="Python.html#Python_nn74">Function annotations</a>
<ul>
<li><a href="Python.html#Python_annotations_c">C/C++ annotation types</a>
</ul>
<li><a href="Python.html#Python_nn75">Buffer interface</a>
<li><a href="Python.html#Python_nn76">Abstract base classes</a>
<li><a href="Python.html#Python_nn77">Byte string output conversion</a>

86
Doc/Manual/Python.html
View file

@ -133,7 +133,10 @@
</ul>
<li><a href="#Python_python3support">Python 3 Support</a>
<ul>
<li><a href="#Python_nn74">Function annotation</a>
<li><a href="#Python_nn74">Function annotations</a>
<ul>
<li><a href="#Python_annotations_c">C/C++ annotation types</a>
</ul>
<li><a href="#Python_nn75">Buffer interface</a>
<li><a href="#Python_nn76">Abstract base classes</a>
<li><a href="#Python_nn77">Byte string output conversion</a>
@ -6753,37 +6756,64 @@ The following are Python 3 new features that are currently supported by
SWIG.
</p>
<H3><a name="Python_nn74">33.12.1 Function annotation</a></H3>
<H3><a name="Python_nn74">33.12.1 Function annotations</a></H3>
<p>
The <tt>-py3</tt> option will enable function annotation support. When used
SWIG is able to generate proxy method definitions like this:
</p>
<div class="code"><pre>
def foo(self, bar : "int"=0) -&gt; "void" : ...
</pre></div>
<p>
Also, even if without passing SWIG the <tt>-py3</tt> option, the parameter list
still could be generated:
</p>
<div class="code"><pre>
def foo(self, bar=0): ...
</pre></div>
<p>
But for overloaded function or method, the parameter list would fallback to
<tt>*args</tt> or <tt>self, *args</tt>, and <tt>**kwargs</tt> may be append
depend on whether you enabled the keyword argument. This fallback is due to
all overloaded functions share the same function in SWIG generated proxy class.
</p>
<p>
For detailed usage of function annotation, see
Python 3 supports function annotations as defined in
<a href="https://www.python.org/dev/peps/pep-3107/">PEP 3107</a>.
Annotation support is via a <tt>python:annotations</tt>
<a href="Customization.html#Customization_features">%feature directives</a>.
SWIG currently supports one type of function annotation.
</p>
<H4><a name="Python_annotations_c">33.12.1.1 C/C++ annotation types</a></H4>
<p>
The <tt>%feature("python:annotations", "c")</tt> directive generates function annotations
containing C/C++ types. For example:
</p>
<div class="code"><pre>
%feature("python:annotations", "c") global_ints;
int *global_ints(int &amp;ri);
</pre></div>
<p>
The generated code then contains function annotations containing the C types:
</p>
<div class="targetlang"><pre>
def global_ints(ri: "int &amp;") -&gt; "int *":
return _python_annotations_c.global_ints(ri)
</pre></div>
<p>
There are some limitations with annotations support, for example, overloaded functions use
<tt>*args</tt> or <tt>**kwargs</tt> when keyword arguments are enabled.
The parameter names and types are then not shown. For example, with input:
</p>
<div class="code"><pre>
int *global_overloaded(int &amp;ri);
int *global_overloaded();
</pre></div>
<p>
The generated Python function including annotations is shown below.
Only the return type is annotated.
</p>
<div class="targetlang"><pre>
def global_overloaded(*args) -&gt; "int *":
return _python_annotations_c.global_overloaded(*args)
</pre></div>
<p>
<b>Compatibility Note:</b> SWIG-4.1.0 changed the way that function annotations are generated.
Prior versions required the <tt>-py3</tt> option which enabled function annotation support
containing C/C++ types instead of supporting <tt>%feature("python:annotations", "c")</tt>.
</p>
<H3><a name="Python_nn75">33.12.2 Buffer interface</a></H3>