python -> Python in html docs
This commit is contained in:
William S Fulton
parent
f7818d5ed3
commit
c33f352069
5 changed files with 63 additions and 63 deletions
|
|
@ -392,7 +392,7 @@ and many of the target language libraries for linking against.
|
|||
CMake knows how to build shared libraries and loadable modules on many different operating systems.
|
||||
This allows easy cross platform SWIG development. It can also generate the custom commands necessary for
|
||||
driving SWIG from IDEs and makefiles. All of this can be done from a single cross platform input file.
|
||||
The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
|
||||
The following example is a CMake input file for creating a Python wrapper for the SWIG interface file, example.i:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
|
|
|
|||
|
|
@ -984,7 +984,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
|
|||
Also, be aware that certain operators don't map cleanly to Lua, and some Lua operators don't map cleanly to C++ operators. For instance, overloaded assignment operators don't map to Lua semantics and will be ignored, and C++ doesn't support Lua's concatenation operator (<tt>..</tt>).
|
||||
</p>
|
||||
<p>
|
||||
In order to keep maximum compatibility within the different languages in SWIG, the Lua bindings uses the same set of operator names as python. Although internally it renames the functions to something else (on order to work with Lua).
|
||||
In order to keep maximum compatibility within the different languages in SWIG, the Lua bindings uses the same set of operator names as Python. Although internally it renames the functions to something else (on order to work with Lua).
|
||||
<p>
|
||||
The current list of operators which can be overloaded (and the alternative function names) are:<ul>
|
||||
<li><tt>__add__</tt> operator+
|
||||
|
|
|
|||
|
|
@ -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<</tt>, etc.) are also converted to python
|
||||
(<tt>operator==, operator<</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>
|
||||
|
|
|
|||
|
|
@ -5035,19 +5035,19 @@ For example:
|
|||
|
||||
<p>
|
||||
where the code passed to the "ref" and "unref" features will be
|
||||
executed as needed whenever a new object is passed to python, or when
|
||||
python tries to release the proxy object instance, respectively.
|
||||
executed as needed whenever a new object is passed to Python, or when
|
||||
Python tries to release the proxy object instance, respectively.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
On the python side, the use of a reference counted object is no
|
||||
On the Python side, the use of a reference counted object is no
|
||||
different to any other regular instance:
|
||||
</p>
|
||||
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
def create_A():
|
||||
a = A() # SWIG ref 'a' - new object is passed to python (count: 1)
|
||||
a = A() # SWIG ref 'a' - new object is passed to Python (count: 1)
|
||||
b1 = B(a) # C++ ref 'a (count: 2)
|
||||
if 1 + 1 == 2:
|
||||
b2 = B(a) # C++ ref 'a' (count: 3)
|
||||
|
|
@ -5075,8 +5075,8 @@ features:
|
|||
|
||||
<p>
|
||||
In other words, SWIG will not do anything special when a new object
|
||||
is passed to python, and it will always 'delete' the underlying object when
|
||||
python releases the proxy instance.
|
||||
is passed to Python, and it will always 'delete' the underlying object when
|
||||
Python releases the proxy instance.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
@ -5283,7 +5283,7 @@ normal classes.
|
|||
</p>
|
||||
<p>
|
||||
If the target language doesn't support nested classes directly, or the support is not implemented in the
|
||||
language module (like for python currently), then the visible nested classes are moved to the same name
|
||||
language module (like for Python currently), then the visible nested classes are moved to the same name
|
||||
space as the containing class (nesting hierarchy is "flattened"). The same behaviour may be turned on for
|
||||
C# and Java by the %feature ("flatnested"); If there is a class with the same name in the outer namespace
|
||||
the inner class (or the global one) may be renamed or ignored:
|
||||
|
|
|
|||
|
|
@ -149,7 +149,7 @@ PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib<br>
|
|||
|
||||
<p>
|
||||
<b><tt>PYTHON_INCLUDE</tt></b> : Set this to the directory that contains Python.h<br>
|
||||
<b><tt>PYTHON_LIB</tt></b> : Set this to the python library including path for linking<p>
|
||||
<b><tt>PYTHON_LIB</tt></b> : Set this to the Python library including path for linking<p>
|
||||
Example using Python 2.1.1:<br>
|
||||
<tt>
|
||||
PYTHON_INCLUDE: D:\python21\include<br>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue