From 7b1b2e177f7f7cfe9498133cf920f0fc7177e3d7 Mon Sep 17 00:00:00 2001
From: Mike Romberg <mike-romberg@comcast.net>
Date: Tue, 7 Jun 2016 15:28:40 -0600
Subject: [PATCH 1/2] Add documentation about how foo.py finds/loads _foo for
 python.

---
 Doc/Manual/Python.html | 112 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html
index 83baa1a475f..e19aae9a9e1 100644
--- a/Doc/Manual/Python.html
+++ b/Doc/Manual/Python.html
@@ -117,6 +117,7 @@ <H1><a name="Python">36 SWIG and Python</a></H1>
 <li><a href="#Python_absimport">Enforcing absolute import semantics</a>
 <li><a href="#Python_importfrominit">Importing from __init__.py</a>
 <li><a href="#Python_implicit_namespace_packages">Implicit Namespace Packages</a>
+<li><a href="#Python_package_search">Searching for the wrapper module</a></li>
 </ul>
 <li><a href="#Python_python3support">Python 3 Support</a>
 <ul>
@@ -5521,6 +5522,23 @@ <H2><a name="Python_nn72">36.11 Python Packages</a></H2>
 directories in order to obtain a desirable package/module hierarchy.
 </p>
 
+<p>
+Python3 adds another option for packages with
+<a href="https://www.python.org/dev/peps/pep-0420/">PEP 0420</a> (implicit
+namespace packages).  These new type of python packages no longer use
+__init__.py files.  Swig generated python modules support implicit
+namespace packages.  See
+<a href="#Python_implicit_namespace_packages">36.11.5 Implicit Namespace
+Packages</a> for more information.
+</p>
+
+<p>
+If you place a swig generated module into a python package then there
+are details concerning the way swig  
+<a href="#Python_package_search">searches for the wrapper module</a>
+you may want to familiarize yourself with.
+</p>
+
 <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
@@ -5939,6 +5957,100 @@ <H3><a name="Python_implicit_namespace_packages">36.11.5 Implicit Namespace Pack
 <b>Compatibility Note:</b> Support for implicit namespace packages was added in SWIG-3.0.9.
 </p>
 
+<H3><a name="Python_package_search">36.11.6 Searching for the wrapper module</a>
+</H3>
+<p>
+When swig creates wrappers from the interface file foo.i two python modules are
+created.  There is a pure python module module (foo.py) and C code which is
+built and linked into a dynamically (or statically) loaded python module _foo
+(see <a href="#Python_nn3">section 36.2</a> for details).  So, the interface
+file really defines two python modules.   How these two modules are loaded is
+covered here.
+</p>
+
+<p>
+The pure python module needs to load the companion module in order to link
+the python to the wrapped C methods.   To do this it must make some assumptions
+about what package the companion module may be located in.  The method the
+python shadow file uses to find the other half is as follows:
+</p>
+
+<ol>
+  <li><p>foo.py tries to load _foo from the same package foo.py is
+      located in.  The package name is determined from the __name__
+      attribute given to foo.py by the python loader that imported
+      foo.py.  If foo.py is not in a package then _foo is loaded
+      as a global module.</p>
+  </li>
+  <li><p>If the above import of _foo results in an ImportError
+      being thrown, then foo.py makes a final attempt to load _foo
+    as a global module.</p>
+  </li>
+</ol>
+
+<p>
+Here foo.py is the pure python module and _foo is the dynamically or statically
+loaded C module.  
+</p>
+
+<p>
+As an example suppose foo.i is compiled into foo.py and _foo.so.  Assuming
+/dir is on PYTHONPATH, then the two modules can be installed and used in the
+following ways:
+</p>
+
+<h4>Both halves in the same package</h4>
+<div class="diagram">
+<pre>
+/dir/pakage/foo.py
+/dir/package/__init__.py
+/dir/package/_foo.so
+</pre>
+</div>
+<p>And imported with</p>
+<div class="diagram">
+<pre>
+from package import foo
+</pre>
+</div>
+
+<h4>Wrapper module is global</h4>
+<div class="diagram">
+<pre>
+/dir/pakage/foo.py
+/dir/package/__init__.py
+/dir/_foo.so
+</pre>
+</div>
+<p>And imported with</p>
+<div class="diagram">
+<pre>
+from package import foo
+</pre>
+</div>
+
+<h4>Both modules are global</h4>
+<div class="diagram">
+<pre>
+/dir/foo.py
+/dir/_foo.so
+</pre>
+</div>
+<p>And imported with</p>
+<div class="diagram">
+<pre>
+import foo
+</pre>
+</div>
+
+<p>
+If _foo is statically linked into an embedded python interpreter, then it may or
+may not be in a python package.  This depends in the exact way the module was
+loaded statically.  The above search order will still be used for statically
+loaded modules.  So, one may place the module either globally or in a package
+as desired.
+</p>
+
 <H2><a name="Python_python3support">36.12 Python 3 Support</a></H2>
 
 

From d18b6e2c8d18ad97eff72c2fc7a07e4b95df90de Mon Sep 17 00:00:00 2001
From: William S Fulton <wsf@fultondesigns.co.uk>
Date: Sat, 11 Jun 2016 00:59:00 +0100
Subject: [PATCH 2/2] Python module loading documentation tweaks

---
 Doc/Manual/Contents.html |  6 +++
 Doc/Manual/Python.html   | 80 +++++++++++++++++++++++-----------------
 2 files changed, 53 insertions(+), 33 deletions(-)

diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html
index ffb467c35a7..b75da40e3ce 100644
--- a/Doc/Manual/Contents.html
+++ b/Doc/Manual/Contents.html
@@ -1595,6 +1595,12 @@ <h3><a href="Python.html#Python">36 SWIG and Python</a></h3>
 <li><a href="Python.html#Python_absimport">Enforcing absolute import semantics</a>
 <li><a href="Python.html#Python_importfrominit">Importing from __init__.py</a>
 <li><a href="Python.html#Python_implicit_namespace_packages">Implicit Namespace Packages</a>
+<li><a href="Python.html#Python_package_search">Searching for the wrapper module</a>
+<ul>
+<li><a href="Python.html#Python_package_search_both_package_modules">Both modules in the same package</a>
+<li><a href="Python.html#Python_package_search_wrapper_split">Split modules</a>
+<li><a href="Python.html#Python_package_search_both_global_modules">Both modules are global</a>
+</ul>
 </ul>
 <li><a href="Python.html#Python_python3support">Python 3 Support</a>
 <ul>
diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html
index e19aae9a9e1..a4af54de5b7 100644
--- a/Doc/Manual/Python.html
+++ b/Doc/Manual/Python.html
@@ -117,7 +117,12 @@ <H1><a name="Python">36 SWIG and Python</a></H1>
 <li><a href="#Python_absimport">Enforcing absolute import semantics</a>
 <li><a href="#Python_importfrominit">Importing from __init__.py</a>
 <li><a href="#Python_implicit_namespace_packages">Implicit Namespace Packages</a>
-<li><a href="#Python_package_search">Searching for the wrapper module</a></li>
+<li><a href="#Python_package_search">Searching for the wrapper module</a>
+<ul>
+<li><a href="#Python_package_search_both_package_modules">Both modules in the same package</a>
+<li><a href="#Python_package_search_wrapper_split">Split modules</a>
+<li><a href="#Python_package_search_both_global_modules">Both modules are global</a>
+</ul>
 </ul>
 <li><a href="#Python_python3support">Python 3 Support</a>
 <ul>
@@ -5525,18 +5530,18 @@ <H2><a name="Python_nn72">36.11 Python Packages</a></H2>
 <p>
 Python3 adds another option for packages with
 <a href="https://www.python.org/dev/peps/pep-0420/">PEP 0420</a> (implicit
-namespace packages).  These new type of python packages no longer use
-__init__.py files.  Swig generated python modules support implicit
+namespace packages).  Implicit namespace packages no longer use
+__init__.py files.  SWIG generated Python modules support implicit
 namespace packages.  See
 <a href="#Python_implicit_namespace_packages">36.11.5 Implicit Namespace
 Packages</a> for more information.
 </p>
 
 <p>
-If you place a swig generated module into a python package then there
-are details concerning the way swig  
+If you place a SWIG generated module into a Python package then there
+are details concerning the way SWIG  
 <a href="#Python_package_search">searches for the wrapper module</a>
-you may want to familiarize yourself with.
+that you may want to familiarize yourself with.
 </p>
 
 <p>The way Python defines its modules and packages impacts SWIG users. Some
@@ -5957,28 +5962,30 @@ <H3><a name="Python_implicit_namespace_packages">36.11.5 Implicit Namespace Pack
 <b>Compatibility Note:</b> Support for implicit namespace packages was added in SWIG-3.0.9.
 </p>
 
-<H3><a name="Python_package_search">36.11.6 Searching for the wrapper module</a>
-</H3>
+
+<H3><a name="Python_package_search">36.11.6 Searching for the wrapper module</a></H3>
+
+
 <p>
-When swig creates wrappers from the interface file foo.i two python modules are
-created.  There is a pure python module module (foo.py) and C code which is
-built and linked into a dynamically (or statically) loaded python module _foo
-(see <a href="#Python_nn3">section 36.2</a> for details).  So, the interface
-file really defines two python modules.   How these two modules are loaded is
-covered here.
+When SWIG creates wrappers from an interface file, say foo.i, two Python modules are
+created.  There is a pure Python module module (foo.py) and C/C++ code which is
+built and linked into a dynamically (or statically) loaded module _foo
+(see the <a href="Python.html#Python_nn3">Preliminaries section</a> for details).  So, the interface
+file really defines two Python modules.   How these two modules are loaded is
+covered next.
 </p>
 
 <p>
-The pure python module needs to load the companion module in order to link
-the python to the wrapped C methods.   To do this it must make some assumptions
-about what package the companion module may be located in.  The method the
-python shadow file uses to find the other half is as follows:
+The pure Python module needs to load the C/C++ module in order to link
+to the wrapped C/C++ methods.   To do this it must make some assumptions
+about what package the C/C++ module may be located in.  The approach the
+pure Python module uses to find the C/C++ module is as follows:
 </p>
 
 <ol>
-  <li><p>foo.py tries to load _foo from the same package foo.py is
-      located in.  The package name is determined from the __name__
-      attribute given to foo.py by the python loader that imported
+  <li><p>The pure Python module, foo.py, tries to load the C/C++ module, _foo, from the same package foo.py is
+      located in.  The package name is determined from the <tt>__name__</tt>
+      attribute given to foo.py by the Python loader that imported
       foo.py.  If foo.py is not in a package then _foo is loaded
       as a global module.</p>
   </li>
@@ -5988,21 +5995,20 @@ <H3><a name="Python_package_search">36.11.6 Searching for the wrapper module</a>
   </li>
 </ol>
 
-<p>
-Here foo.py is the pure python module and _foo is the dynamically or statically
-loaded C module.  
-</p>
-
 <p>
 As an example suppose foo.i is compiled into foo.py and _foo.so.  Assuming
 /dir is on PYTHONPATH, then the two modules can be installed and used in the
 following ways:
 </p>
 
-<h4>Both halves in the same package</h4>
+
+<H4><a name="Python_package_search_both_package_modules">36.11.6.1 Both modules in the same package</a></H4>
+
+
+<p>Both modules are in one package:</p>
 <div class="diagram">
 <pre>
-/dir/pakage/foo.py
+/dir/package/foo.py
 /dir/package/__init__.py
 /dir/package/_foo.so
 </pre>
@@ -6014,10 +6020,14 @@ <h4>Both halves in the same package</h4>
 </pre>
 </div>
 
-<h4>Wrapper module is global</h4>
+
+<H4><a name="Python_package_search_wrapper_split">36.11.6.2 Split modules</a></H4>
+
+
+<p>The pure python module is in a package and the C/C++ module is global:</p>
 <div class="diagram">
 <pre>
-/dir/pakage/foo.py
+/dir/package/foo.py
 /dir/package/__init__.py
 /dir/_foo.so
 </pre>
@@ -6029,7 +6039,11 @@ <h4>Wrapper module is global</h4>
 </pre>
 </div>
 
-<h4>Both modules are global</h4>
+
+<H4><a name="Python_package_search_both_global_modules">36.11.6.3 Both modules are global</a></H4>
+
+
+<p>Both modules are global:</p>
 <div class="diagram">
 <pre>
 /dir/foo.py
@@ -6044,8 +6058,8 @@ <h4>Both modules are global</h4>
 </div>
 
 <p>
-If _foo is statically linked into an embedded python interpreter, then it may or
-may not be in a python package.  This depends in the exact way the module was
+If _foo is statically linked into an embedded Python interpreter, then it may or
+may not be in a Python package.  This depends in the exact way the module was
 loaded statically.  The above search order will still be used for statically
 loaded modules.  So, one may place the module either globally or in a package
 as desired.