diff options
author | William S Fulton <wsf@fultondesigns.co.uk> | 2013-12-24 14:39:25 +0000 |
---|---|---|
committer | William S Fulton <wsf@fultondesigns.co.uk> | 2013-12-24 17:22:42 +0000 |
commit | 91120c84f2f3cc12f709d05d9dcc13e60018610c (patch) | |
tree | 29a39eb50c0ca2c66f776b46ed2fb185c8b6a78e /Doc | |
parent | f53bd5a1e18da855a4960eb019644cdcf3f0e393 (diff) | |
download | swig-91120c84f2f3cc12f709d05d9dcc13e60018610c.tar.gz |
Python imports documentation edits
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/Manual/Python.html | 136 |
1 files changed, 68 insertions, 68 deletions
diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index 2a719ca7a..c6cc2f40f 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -108,7 +108,7 @@ <ul> <li><a href="#Python_modulepackage">%module(package="...") syntax</a> <li><a href="#Python_absrelimports">Absolute and relative imports</a></li> -<li><a href="Python_absimport">Enforcing absolute import semantics</a></li> +<li><a href="#Python_absimport">Enforcing absolute import semantics</a></li> <li><a href="#Python_importfrominit">Importing from __init__.py</a></li> </ul> <li><a href="#Python_python3support">Python 3 Support</a> @@ -5284,11 +5284,11 @@ code and may be grouped together to form a package. Packages may be nested, that is they may contain subpackages. This leads to tree-like hierarchy, with packages as intermediate nodes and modules as leaf nodes.</p> -<p>The hierarchy of python packages/modules follows the hierarchy of -<tt>*.py</tt> files found in source tree (or, more generally, in python path). +<p>The hierarchy of Python packages/modules follows the hierarchy of +<tt>*.py</tt> files found in a source tree (or, more generally, in the Python path). Normally, the developer creates new module by placing a <tt>*.py</tt> file -somewhere under python path; the module is then named after that <tt>*.py</tt> -file. A package is created by placing <tt>__init__.py</tt> file within a +somewhere under Python path; the module is then named after that <tt>*.py</tt> +file. A package is created by placing an <tt>__init__.py</tt> file within a directory; the package is then named after that directory. For example, the following source tree:</p> @@ -5303,7 +5303,7 @@ pkg1/pkg2/mod3.py </div> <p> -defines the following python packages and modules: +defines the following Python packages and modules: </p> <div class="diagram"> @@ -5317,28 +5317,28 @@ pkg1.pkg2.mod3 # module </div> <p> -The purpose of <tt>__init__.py</tt> file is two-fold. First, existence of -<tt>__init__.py</tt> in a directory informs python interpreter that this -directory contains python package. Second, the code of <tt>__init__.py</tt> is +The purpose of an <tt>__init__.py</tt> file is two-fold. First, the existence of +<tt>__init__.py</tt> in a directory informs the Python interpreter that this +directory contains a Python package. Second, the code in <tt>__init__.py</tt> is loaded/executed automatically when the package is initialized (when it or its -submodule/subpackage gets <tt>import</tt>'ed). By default, swig generates -proxy python code – one <tt>*.py</tt> file for each <tt>*.i</tt> -interface. The <tt>__init__.py</tt> files, however, are not generated by swig. +submodule/subpackage gets <tt>import</tt>'ed). By default, SWIG generates +proxy Python code – one <tt>*.py</tt> file for each <tt>*.i</tt> +interface. The <tt>__init__.py</tt> files, however, are not generated by SWIG. They should be created by other means. Both files (module <tt>*.py</tt> and <tt>__init__.py</tt>) should be installed in appropriate destination -directories in order to obtain desirable package/module hierarchy. +directories in order to obtain a desirable package/module hierarchy. </p> -<p>The way python defines its modules and packages impacts swig users. Some -users may need to use special features such as <tt>package</tt> option of -<tt>%module</tt> directive or import-related command-line options. These are +<p>The way Python defines its modules and packages impacts SWIG users. Some +users may need to use special features such as the <tt>package</tt> option in the +<tt>%module</tt> directive or import related command line options. These are explained in the following sections.</p> -<H3><a name="Python_modulepackage"></a>34.11.1 %module(package="...") syntax</H3> +<H3><a name="Python_modulepackage"></a>34.11.1 Setting the Python package</H3> <p> -Using the <tt>package</tt> option of the <tt>%module</tt> directive allows you -to specify a Python package that the module will be living in when installed. +Using the <tt>package</tt> option in the <tt>%module</tt> directive allows you +to specify a Python package that the module will be in when installed. </p> <div class="code"> @@ -5351,20 +5351,20 @@ to specify a Python package that the module will be living in when installed. This is useful when the <tt>.i</tt> file is <tt>%import</tt>ed by another <tt>.i</tt> file. By default SWIG will assume that the importer is able to find the importee with just the module name, but -if they live in separate Python packages then that won't work. +if they live in separate Python packages then this won't work. However if the importee specifies what its package is with the <tt>%module</tt> option then the Python code generated for the importer will use that package name when importing the other module -and also in base class declarations, etc.. +and in base class declarations, etc.. </p> -<p>Swig assumes, that the <tt>package</tt> option provided to <tt>%module</tt> +<p>SWIG assumes that the <tt>package</tt> option provided to <tt>%module</tt> together with the <tt>module</tt> name (that is, <tt>wx.xrc</tt> in the above example) forms a fully qualified (absolute) name of a module (in Python terms). This is important especially for Python 3, where absolute imports are used by default. It's up to you to place the generated module files (<tt>.py</tt>, -<tt>.so</tt>) in proper subdirectories. For example, if you have -interface <tt>foo.i</tt> with: +<tt>.so</tt>) in appropriate subdirectories. For example, if you have an +interface file <tt>foo.i</tt> with: </p> <div class="code"> @@ -5374,7 +5374,7 @@ interface <tt>foo.i</tt> with: </div> <p> -then the resultant directory layout should be +then the resulting directory layout should be </p> <div class="diagram"> @@ -5382,8 +5382,8 @@ then the resultant directory layout should be pkg1/ pkg1/__init__.py pkg1/pkg2/__init__.py -pkg1/pkg2/foo.py # (generated by swig) -pkg1/pkg2/_foo.so # (shared library from C/C++ code generated by SWIG) +pkg1/pkg2/foo.py # (generated by SWIG) +pkg1/pkg2/_foo.so # (shared library built from C/C++ code generated by SWIG) </pre> </div> @@ -5409,9 +5409,9 @@ class M3: pass </div> <p> -We edit <tt>pkg1/mod2.py</tt> and want to import module of +We edit <tt>pkg1/mod2.py</tt> and want to import module <tt>pkg1/pkg2/pkg3.py</tt> in order to derive from class <tt>M3</tt>. We can -write appropriate python code in several ways, for example: +write appropriate Python code in several ways, for example: </p> <ol> @@ -5426,7 +5426,7 @@ class M2(pkg1.pkg2.mod3.M3): pass </li> <li><p>Using "<tt>import <></tt>" syntax with package name relative to - <tt>pkg1</tt> (only in python 2.7 and earlier):</p> + <tt>pkg1</tt> (only in Python 2.7 and earlier):</p> <div class="targetlang"> <pre> # pkg1/mod2.py @@ -5437,7 +5437,7 @@ class M2(pkg2.mod3.M3): pass </li> <li><p>Using "<tt>from <> import <></tt>" syntax (relative import - syntax, only in python 2.5 and later):</p> + syntax, only in Python 2.5 and later):</p> <div class="targetlang"> <pre> # pkg1/mod2.py @@ -5449,7 +5449,7 @@ class M2(mod3.M3): pass <li><p>Other variants, for example the following construction in order to have the <tt>pkg2.mod3.M3</tt> symbol available in <tt>mod2</tt> as - in point 2 above (but now under python 3):</p> + in point 2 above (but now under Python 3):</p> <div class="targetlang"> <pre> # pkg1/mod2.py @@ -5483,13 +5483,13 @@ class M2(pkg2.mod3.M3): pass </pre> </div> -<p>By default, swig would generate <tt>mod2.py</tt> proxy file with -<tt>import</tt> directive as in point 1. This may be changed with -<tt>-relativeimport</tt> CLI option. The <tt>-relativeimport</tt> instructs -swig to organize imports as in point 2 (for python 2.x) or as in point 4 (for -python 3, that is when -py3 CLI option is enabled). In short, if you have +<p>By default, SWIG would generate <tt>mod2.py</tt> proxy file with +<tt>import</tt> directive as in point 1. This can be changed with the +<tt>-relativeimport</tt> command line option. The <tt>-relativeimport</tt> instructs +SWIG to organize imports as in point 2 (for Python 2.x) or as in point 4 (for +Python 3, that is when the -py3 command line option is enabled). In short, if you have <tt>mod2.i</tt> and <tt>mod3.i</tt> as above, then without -<tt>-relativeimport</tt> swig will write</p> +<tt>-relativeimport</tt> SWIG will write</p> <div class="targetlang"> <pre> @@ -5515,20 +5515,20 @@ import pkg1.pkg2.mod3 </pre> </div> -<p>when <tt>-py3</tt> option is used.</p> +<p>when <tt>-py3</tt> is used.</p> <p>You should avoid using relative imports and use absolute ones whenever possible. There are some cases, however, when relative imports may be -necessary. The first example is, when some (legacy) python code refers entities -imported by proxy files generated by swig, and it assumes that the proxy file +necessary. The first example is, when some (legacy) Python code refers entities +imported by proxy files generated by SWIG, and it assumes that the proxy file uses relative imports. Second case is, when one puts import directives in <tt>__init__.py</tt> to import symbols from submodules or subpackages and the submodule depends on other submodules (discussed later).</p> <H3><a name="Python_absimport"></a>34.11.3 Enforcing absolute import semantics</H3> -<p>As you may know, there is incompatibility in import semantics (for the -<tt>import <></tt> syntax) between python 2 and 3. In python 2.4 and +<p>As you may know, there is an incompatibility in import semantics (for the +<tt>import <></tt> syntax) between Python 2 and 3. In Python 2.4 and earlier it is not clear whether</p> <div class="targetlang"> @@ -5537,10 +5537,10 @@ import foo </pre> </div> <p>refers to a top-level module or to another module inside the current -package. In python 3 it always refers to a top-level module +package. In Python 3 it always refers to a top-level module (see <a href="http://www.python.org/dev/peps/pep-0328/">PEP 328</a>). -To instruct python 2.5 through 2.7 to use new semantics (that is <tt>import -foo</tt> is interpreted as absolute import), one have to put the following +To instruct Python 2.5 through 2.7 to use new semantics (that is <tt>import +foo</tt> is interpreted as absolute import), one has to put the following line </p> @@ -5550,26 +5550,26 @@ from __future__ import absolute_import </pre> </div> -<p>at the very beginning of his proxy <tt>*.py</tt> file. In swig, it may be +<p>at the very beginning of his proxy <tt>*.py</tt> file. In SWIG, it may be accomplished with <tt>%pythonbegin</tt> directive.</p> <H3><a name="Python_importfrominit"></a>34.11.4 Importing from __init__.py</H3> -<p>Imports in <tt>__init__.py</tt> are handy when you want to populate -package's namespace with names imported from other modules. In swig-based -projects this approach may also be used to split large piece of code into -smaller modules, compile them in parallel and then re-assemble all stuff at -python level by importing submodules' contents in <tt>__init__.py</tt>, for +<p>Imports in <tt>__init__.py</tt> are handy when you want to populate a +package's namespace with names imported from other modules. In SWIG based +projects this approach may also be used to split large pieces of code into +smaller modules, compile them in parallel and then re-assemble everything at another +level by importing submodules' contents in <tt>__init__.py</tt>, for example.</p> -<p>Unfortunately import directives in <tt>__init__.py</tt> may cause troubles, -especially if they refer to package's submodules. This is caused by the way -python initializes packages. If you spot problems with imports from +<p>Unfortunately import directives in <tt>__init__.py</tt> may cause problems, +especially if they refer to a package's submodules. This is caused by the way +Python initializes packages. If you spot problems with imports from <tt>__init__.py</tt> try using <tt>-relativeimport</tt> option. Below we explain in detail one issue, for which the <tt>-relativeimport</tt> workaround may be helpful.</p> -<p>Consider the following example (python 3):</p> +<p>Consider the following example (Python 3):</p> <div class="diagram"> <pre> @@ -5580,10 +5580,10 @@ pkg1/pkg2/bar.py # (imports foo.py) </pre> </div> -<p>Let's the files' contents be:</p> +<p>If the file contents are:</p> <ul> - <li> <p>for <tt>pkg1/pkg2/__init__.py:</tt></p> + <li> <p><tt>pkg1/pkg2/__init__.py:</tt></p> <div class="targetlang"> <pre> # pkg1/pkg2/__init__.py @@ -5592,7 +5592,7 @@ from .bar import Bar </div> </li> - <li> <p>for <tt>pkg1/pkg2/foo.py:</tt></p> + <li> <p><tt>pkg1/pkg2/foo.py:</tt></p> <div class="targetlang"> <pre> # pkg1/pkg2/foo.py @@ -5601,7 +5601,7 @@ class Foo: pass </div> </li> - <li> <p>for <tt>pkg1/pkg2/foo.py:</tt></p> + <li> <p><tt>pkg1/pkg2/bar.py:</tt></p> <div class="targetlang"> <pre> # pkg1/pkg2/bar.py @@ -5612,7 +5612,7 @@ class Bar(pkg1.pkg2.foo.Foo): pass </li> </ul> -<p>Now one would simply do <tt>import pkg1.pkg2</tt>, but this usually fails:</p> +<p>Now if one simply used <tt>import pkg1.pkg2</tt>, it will usually fail:</p> <div class="diagram"> <pre> @@ -5628,16 +5628,16 @@ AttributeError: 'module' object has no attribute 'pkg2' </div> <p>Surprisingly, if we execute the <tt>import pkg1.pkg2</tt> directive for the -second time, it succeeds. The reason seems to be following: when python spots +second time, it succeeds. The reason seems to be following: when Python spots the <tt>from .bar import Bar</tt> directive in <tt>pkg1/pkg2/__init__.py</tt> it starts loading <tt>pkg1/pkg2/bar.py</tt>. This module imports <tt>pkg1.pkg2.foo</tt> in turn and tries to use <tt>pkg1.pkg2.foo.Foo</tt>, but the package <tt>pkg1</tt> is not fully initialized yet (the initialization -procedure is actually in progress) and it seems like the effect of already seen -directive <tt>import pkg1.pkg2.pkg3.foo</tt> is "delayed" or ignored. Exactly -same may happen to a proxy module generated by swig.</p> +procedure is actually in progress) and it seems like the effect of the already seen +<tt>import pkg1.pkg2.pkg3.foo</tt> is "delayed" or ignored. Exactly the +same may happen to a proxy module generated by SWIG.</p> -<p>It's observed, that a possible workaround for this case is to use relative +<p>One workaround for this case is to use a relative import in <tt>pkg1/pkg2/bar.py</tt>. If we change <tt>bar.py</tt> to be:</p> <div class="targetlang"> @@ -5657,9 +5657,9 @@ class Bar(pkg3.foo.Foo): pass </pre> </div> -<p>then the example works again. With swig, you need to enable the +<p>then the example works again. With SWIG, you need to enable the <tt>-relativeimport</tt> option in order to have the above workaround in -effect (note, that python 2 case also needs <tt>-relativeimport</tt> +effect (note, that the Python 2 case also needs the <tt>-relativeimport</tt> workaround).</p> |