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

python -> Python in html docs

Browse source
This commit is contained in:
William S Fulton 2018-08-21 22:41:02 +01:00
commit c33f352069
5 changed files with 63 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

106
Doc/Manual/Python.html
View file

@ -218,7 +218,7 @@ int fact(int n);
<p>
The <tt>#define SWIG_FILE_WITH_INIT</tt> line inserts a macro that specifies that the
resulting C file should be built as a python extension, inserting the module
resulting C file should be built as a Python extension, inserting the module
<tt>init</tt> code. This <tt>.i</tt> file wraps the following simple C file:
</p>
@ -296,8 +296,8 @@ how you might go about compiling and using the generated files.
<p>
The preferred approach to building an extension module for python is to compile it with
distutils, which comes with all recent versions of python
The preferred approach to building an extension module for Python is to compile it with
distutils, which comes with all recent versions of Python
(<a href="https://docs.python.org/library/distutils.html">Distutils Docs</a>).
</p>
@ -307,7 +307,7 @@ flags, headers, etc. for the version of Python it is run with. Distutils will co
extension into a shared object file or DLL (<tt>.so</tt> on Linux, <tt>.pyd</tt> on
Windows, etc). In addition, distutils can handle installing your package into
site-packages, if that is desired. A configuration file (conventionally called: <tt>setup.py</tt>)
describes the extension (and related python modules). The distutils will
describes the extension (and related Python modules). The distutils will
then generate all the right compiler directives to build it for you.
</p>
@ -344,9 +344,9 @@ setup (name = 'example',
In this example, the line: <tt>example_module = Extension(....)</tt> creates an Extension
module object, defining the name as <tt>_example</tt>, and using the source code files:
<tt>example_wrap.c</tt>, generated by swig, and <tt>example.c</tt>, your original c
source. The swig (and other python extension modules) tradition is for the compiled
extension to have the name of the python portion, prefixed by an underscore. If the name
of your python module is "<tt>example.py</tt>", then the name of the corresponding object file
source. The swig (and other Python extension modules) tradition is for the compiled
extension to have the name of the Python portion, prefixed by an underscore. If the name
of your Python module is "<tt>example.py</tt>", then the name of the corresponding object file
will be"<tt>_example.so</tt>"
</p>
@ -363,11 +363,11 @@ $ python setup.py build_ext --inplace
<p>
And a .so, or .pyd or... will be created for you. It will build a version that matches the
python that you run the command with. Taking apart the command line:
Python that you run the command with. Taking apart the command line:
</p>
<ul>
<li> <tt>python</tt> -- the version of python you want to build for
<li> <tt>python</tt> -- the version of Python you want to build for
<li> <tt>setup.py</tt> -- the name of your setup script (it can be called anything, but
setup.py is the tradition)
<li> <tt>build_ext</tt> -- telling distutils to build extensions
@ -376,7 +376,7 @@ python that you run the command with. Taking apart the command line:
</ul>
<p>
The distutils have many other features, consult the python distutils docs for details.
The distutils have many other features, consult the Python distutils docs for details.
</p>
<p>
@ -793,7 +793,7 @@ careful about the libraries you link with or the library path you
use. In general, a Linux distribution will have two set of libraries,
one for native x86_64 programs (under /usr/lib64), and another for 32
bits compatibility (under /usr/lib). Also, the compiler options -m32
and -m64 allow you to choose the desired binary format for your python
and -m64 allow you to choose the desired binary format for your Python
extension.
</p>
@ -1185,7 +1185,7 @@ When wrapped, you will be able to use the functions in a natural way from Python
<p>
If this makes you uneasy, rest assured that there is no
deep magic involved. Underneath the covers, pointers to C/C++ objects are
simply represented as opaque values using an especial python container object:
simply represented as opaque values using an especial Python container object:
</p>
<div class="targetlang"><pre>
@ -1213,7 +1213,7 @@ _c0671108_p_FILE
<p>
Also, if you need to pass the raw pointer value to some external
python library, you can do it by casting the pointer object to an
Python library, you can do it by casting the pointer object to an
integer:
</p>
@ -2254,8 +2254,8 @@ and built-in types, let's take a look at what a wrapped object looks like
under both circumstances.
</p>
<p>When proxy classes are used, each wrapped object in python is an instance
of a pure python class. As a reminder, here is what the <tt>__init__</tt> method looks
<p>When proxy classes are used, each wrapped object in Python is an instance
of a pure Python class. As a reminder, here is what the <tt>__init__</tt> method looks
like in a proxy class:
</p>
@ -2270,21 +2270,21 @@ class Foo(object):
<p>When a <tt>Foo</tt> instance is created, the call to <tt>_example.new_Foo()</tt>
creates a new C++ <tt>Foo</tt> instance; wraps that C++ instance inside an instance of
a python built-in type called <tt>SwigPyObject</tt>; and stores the <tt>SwigPyObject</tt>
instance in the 'this' field of the python Foo object. Did you get all that? So, the
python <tt>Foo</tt> object is composed of three parts:</p>
a Python built-in type called <tt>SwigPyObject</tt>; and stores the <tt>SwigPyObject</tt>
instance in the 'this' field of the Python Foo object. Did you get all that? So, the
Python <tt>Foo</tt> object is composed of three parts:</p>
<ul>
<li> The python <tt>Foo</tt> instance, which contains...</li>
<li> The Python <tt>Foo</tt> instance, which contains...</li>
<li> ... an instance of <tt>struct SwigPyObject</tt>, which contains...</li>
<li> ... a C++ <tt>Foo</tt> instance</li>
</ul>
<p>When <tt>-builtin</tt> is used, the pure python layer is stripped off. Each
wrapped class is turned into a new python built-in type which inherits from
<p>When <tt>-builtin</tt> is used, the pure Python layer is stripped off. Each
wrapped class is turned into a new Python built-in type which inherits from
<tt>SwigPyObject</tt>, and <tt>SwigPyObject</tt> instances are returned directly
from the wrapped methods. For more information about python built-in extensions,
please refer to the python documentation:</p>
from the wrapped methods. For more information about Python built-in extensions,
please refer to the Python documentation:</p>
<p><a href="http://docs.python.org/extending/newtypes.html">http://docs.python.org/extending/newtypes.html</a></p>
@ -2300,7 +2300,7 @@ please refer to the python documentation:</p>
They are instead accessed in the idiomatic way (<tt>Dances.FishSlap</tt>).</li>
</ul>
</li>
<li><p>Wrapped types may not be raised as python exceptions. Here's why: the python internals expect that all sub-classes of Exception will have this struct layout:</p>
<li><p>Wrapped types may not be raised as Python exceptions. Here's why: the Python internals expect that all sub-classes of Exception will have this struct layout:</p>
<div class="code">
<pre>
@ -2345,7 +2345,7 @@ private:
</pre>
</div>
<p>... you can define this python class, which may be raised as an exception:</p>
<p>... you can define this Python class, which may be raised as an exception:</p>
<div class="targetlang">
<pre>
@ -2360,7 +2360,7 @@ class MyPyException(Exception):
</li>
<li><p>Reverse binary operators (e.g., <tt>__radd__</tt>) are not supported.</p>
<p>To illustrate this point, if you have a wrapped class called <tt>MyString</tt>,
and you want to use instances of <tt>MyString</tt> interchangeably with native python
and you want to use instances of <tt>MyString</tt> interchangeably with native Python
strings, you can define an <tt>'operator+ (const char*)'</tt> method :</p>
<div class="code">
@ -2375,7 +2375,7 @@ public:
</div>
<p>
SWIG will automatically create an operator overload in python that will allow this:
SWIG will automatically create an operator overload in Python that will allow this:
</p>
<div class="targetlang">
@ -2402,7 +2402,7 @@ episode = "Dead " + mystr
</div>
<p>
The above code fails, because the first operand -- a native python string --
The above code fails, because the first operand -- a native Python string --
doesn't know how to add an instance of <tt>MyString</tt> to itself.
</p>
</li>
@ -2438,7 +2438,7 @@ class Derived : public Base {
<p>The <tt>import "A.i"</tt> statement is required, because module <tt>B</tt> depends on module <tt>A</tt>.</p>
<p>As long as you obey these requirements, your python code may import the modules in any order :</p>
<p>As long as you obey these requirements, your Python code may import the modules in any order :</p>
<div class="targetlang"><pre>
import B
@ -2455,13 +2455,13 @@ assert(issubclass(B.Derived, A.Base))
<p>The entire justification for the <tt>-builtin</tt> option is improved
performance. To that end, the best way to squeeze maximum performance out
of your wrappers is to <b>use operator overloads.</b>
Named method dispatch is slow in python, even when compared to other scripting languages.
However, python built-in types have a large number of "slots",
Named method dispatch is slow in Python, even when compared to other scripting languages.
However, Python built-in types have a large number of "slots",
analogous to C++ operator overloads, which allow you to short-circuit named method dispatch
for certain common operations.
</p>
<p>By default, SWIG will translate most C++ arithmetic operator overloads into python
<p>By default, SWIG will translate most C++ arithmetic operator overloads into Python
slot entries. For example, suppose you have this class:
<div class="code">
@ -2478,7 +2478,7 @@ public:
</pre>
</div>
<p>SWIG will automatically register <tt>operator+</tt> as a python slot operator for addition. You may write python code like this:</p>
<p>SWIG will automatically register <tt>operator+</tt> as a Python slot operator for addition. You may write Python code like this:</p>
<div class="targetlang">
<pre>
@ -2491,24 +2491,24 @@ percival = nigel.add(emily)
</pre>
</div>
<p>The last two lines of the python code are equivalent,
<p>The last two lines of the Python code are equivalent,
but <b>the line that uses the '+' operator is much faster</b>.
</p>
<p>In-place operators (e.g., <tt>operator+=</tt>) and comparison operators
(<tt>operator==, operator&lt;</tt>, etc.) are also converted to python
(<tt>operator==, operator&lt;</tt>, etc.) are also converted to Python
slot operators. For a complete list of C++ operators that are
automatically converted to python slot operators, refer to the file
automatically converted to Python slot operators, refer to the file
<tt>python/pyopers.swig</tt> in the SWIG library.
</p>
<p>
Read about all of the available python slots here:
Read about all of the available Python slots here:
<a href="http://docs.python.org/c-api/typeobj.html">http://docs.python.org/c-api/typeobj.html</a></p>
<p>
There are two ways to define a python slot function: dispatch to a
There are two ways to define a Python slot function: dispatch to a
statically defined function; or dispatch to a method defined on the
operand.
</p>
@ -2595,7 +2595,7 @@ class MyClass {
</div>
<p>
NOTE: Some python slots use a method signature which does not
NOTE: Some Python slots use a method signature which does not
match the signature of SWIG-wrapped methods. For those slots,
SWIG will automatically generate a "closure" function to re-marshal
the arguments before dispatching to the wrapped method. Setting
@ -2912,7 +2912,7 @@ public:
</div>
<p>
then at the python side you can define
then at the Python side you can define
</p>
<div class="targetlang">
@ -2925,7 +2925,7 @@ class MyFoo(mymodule.Foo):
# super().__init__(foo) # Alternative construction for Python3
def one(self):
print "one from python"
print "one from Python"
</pre>
</div>
@ -3440,7 +3440,7 @@ an error for invalid preprocessor directives, so you may have to update
existing interface files to delimit blocks of Python code correctly.</p>
<p>As an alternative to providing a block containing Python code, you can
include python code from a file. The code is inserted exactly as in the
include Python code from a file. The code is inserted exactly as in the
file, so this avoids any issues with the SWIG preprocessor. It's a good
approach if you have a non-trivial chunk of Python code to insert. To
use this feature you specify a filename in double quotes, for example:</p>
@ -3461,7 +3461,7 @@ entirely replace a proxy function you can use
<pre>
%module example
// Rewrite bar() python code
// Rewrite bar() Python code
%feature("shadow") Foo::bar(int) %{
def bar(*args):
@ -3496,7 +3496,7 @@ proxy, just before the return statement.
<pre>
%module example
// Add python code to bar()
// Add Python code to bar()
%feature("pythonprepend") Foo::bar(int) %{
#do something before C++ call
@ -3525,7 +3525,7 @@ SWIG version 1.3.28 you can use the directive forms
<pre>
%module example
// Add python code to bar()
// Add Python code to bar()
%pythonprepend Foo::bar(int) %{
#do something before C++ call
@ -3554,7 +3554,7 @@ as it will then get attached to all the overloaded C++ methods. For example:
<pre>
%module example
// Add python code to bar()
// Add Python code to bar()
%pythonprepend Foo::bar %{
#do something before C++ call
@ -3890,7 +3890,7 @@ Below are some timings in microseconds calling the 3 functions in the example ab
<p>
Although the <tt>-fastproxy</tt> option results in faster code, the generated proxy code is not as user-friendly
as docstring/doxygen comments and functions with default values are not visible in the generated python proxy class.
as docstring/doxygen comments and functions with default values are not visible in the generated Python proxy class.
</p>
@ -4581,7 +4581,7 @@ looking at the files in the SWIG library. Just take into account that
in the latest versions of swig (1.3.22+), the library files are not
very pristine clear for the casual reader, as they used to be. The
extensive use of macros and other ugly techniques in the latest
version produce a very powerful and consistent python typemap library,
version produce a very powerful and consistent Python typemap library,
but at the cost of simplicity and pedagogic value.
</p>
@ -6064,7 +6064,7 @@ packages you can place these files in the following configurations:
</pre>
</div>
<p> Finally suppose that your pure python code is stored in a .zip file or
<p> Finally suppose that your pure Python code is stored in a .zip file or
some other way (database, web service connection, etc). Python can load the
robin.py module using a custom importer. But the _robin.so module will need
to be located on a file system. Implicit namespace packages make this
@ -6192,7 +6192,7 @@ from package import foo
<H4><a name="Python_package_search_wrapper_split">38.11.6.2 Split modules</a></H4>
<p>The pure python module is in a package and the C/C++ module is global:</p>
<p>The pure Python module is in a package and the C/C++ module is global:</p>
<div class="diagram">
<pre>
/dir/package/foo.py
@ -6844,7 +6844,7 @@ will not be able to run any other threads, even if the wrapped C/C++ code is wai
<ul>
<li>
<p>
The <tt>-threads</tt> swig python option at the command line (or in <tt>setup.py</tt>):
The <tt>-threads</tt> SWIG Python option at the command line (or in <tt>setup.py</tt>):
</p>
<div class="shell"><pre>$ swig -python -threads example.i</pre></div>
</li>
@ -6863,13 +6863,13 @@ will not be able to run any other threads, even if the wrapped C/C++ code is wai
</li>
<li><p>You can partially disable thread support for a given method:</p>
<ul>
<li><p>To disable the C++/python thread protection:</p>
<li><p>To disable the C++/Python thread protection:</p>
<div class="code"><pre>%feature("nothreadblock") method;</pre></div>
or
<div class="code"><pre>%nothreadblock method;</pre></div>
</li>
<li>
<p>To disable the python/C++ thread protection</p>
<p>To disable the Python/C++ thread protection</p>
<div class="code"><pre>%feature("nothreadallow") method;</pre></div>
or
<div class="code"><pre>%nothreadallow method;</pre></div>