Merge branch 'master' into directorargout_and_java_typemaps

ANNOUNCE

@@ -1,8 +1,8 @@
-*** ANNOUNCE: SWIG 3.0.10 (in progress) ***
+*** ANNOUNCE: SWIG 3.0.11 (in progress) ***
 
 http://www.swig.org
 
-We're pleased to announce SWIG-3.0.10, the latest SWIG release.
+We're pleased to announce SWIG-3.0.11, the latest SWIG release.
 
 What is SWIG?
 =============
@@ -27,11 +27,11 @@ Availability
 ============
 The release is available for download on Sourceforge at
 
-     http://prdownloads.sourceforge.net/swig/swig-3.0.10.tar.gz
+     http://prdownloads.sourceforge.net/swig/swig-3.0.11.tar.gz
 
 A Windows version is also available at
 
-     http://prdownloads.sourceforge.net/swig/swigwin-3.0.10.zip
+     http://prdownloads.sourceforge.net/swig/swigwin-3.0.11.zip
 
 Please report problems with this release to the swig-devel mailing list,
 details at http://www.swig.org/mail.html.

CHANGES

@@ -3,6 +3,48 @@ SWIG (Simplified Wrapper and Interface Generator)
 See the CHANGES.current file for changes in the current version.
 See the RELEASENOTES file for a summary of changes in each release.
 
+Version 3.0.10 (12 Jun 2016)
+============================
+
+2016-06-06: mromberg
+            [Python] Patch #698. Add support for -relativeimport for python 2.7, so -py3 is no
+            longer also required for relative import support.
+
+2016-06-05: mromberg
+            [Python] Patch #694 - Fix package import regressions introduced in swig-3.0.9.
+
+            1) The code in 3.0.9 did not fall back to 'import _foo' if 'import bar._foo' failed
+            (assuming bar.foo was the main module). Every place _foo is imported now first tries
+            it from the package where foo was found and if that fails tries _foo as a global module.
+
+            2) The separate block of Python code that injected code to pull in the attributes
+            from _foo when -builtin is used made use of the -py3 switch to either do
+            'from ._foo import *' or "from _foo import *". This block of code no longer does this
+            and instead checks the Python version at runtime to switch between the two syntaxes.
+
+            In summary, swig-3.0.10 has been modified to ease the creation of wrapper modules
+            that can be fully made part of a Python package.  SWIG no longer
+            assumes the dynamically linked C module is a global module.
+            The dynamic module can now be placed into either the same package as the pure Python
+            module or as a global module.  Both locations are used by the Python wrapper to
+            locate the C module.
+
+            However, this could cause a backwards incompatibility with some code
+            that was relying on the ability of "from package import _module" to
+            pull attributes out of the package directly.  If your code populates a
+            module (which is also a package) with attributes that are SWIG
+            generated modules which were not loaded in a conventional way,
+            swig-3.0.8 and earlier may have worked due to 'from package import
+            _module' bypassing a real import and pulling your module in as an
+            attribute. This will no longer work.  Since this is not a common (or
+            even recommended) practice, most folk should not be affected.
+
+            *** POTENTIAL INCOMPATIBILITY ***
+
+2016-05-31: wsfulton
+            Fix #690 - Smart pointer to %ignored class doesn't expose inherited methods.
+            Regression introduced in swig-3.0.9.
+
 Version 3.0.9 (29 May 2016)
 ===========================
 

CHANGES.current

@@ -2,25 +2,5 @@ Below are the changes for the current release.
 See the CHANGES file for changes in older releases.
 See the RELEASENOTES file for a summary of changes in each release.
 
-Version 3.0.10 (in progress)
+Version 3.0.11 (in progress)
 ============================
-
-2016-06-06: mromberg
-            [Python] Patch #698. Add support for -relativeimport for python 2.7, so -py3 is no
-            longer also required for relative import support.
-
-2016-06-05: mromberg
-            [Python] Patch #694 - Fix package import regressions introduced in swig-3.0.9.
-
-            1) The code in 3.0.9 did not fall back to 'import _foo' if 'import bar._foo' failed
-            (assuming bar.foo was the main module). Every place _foo is imported now first tries
-            it from the package where foo was found and if that fails tries _foo as a global module.
-
-            2) The separate block of python code that injected code to pull in the attributes
-            from _foo when -builtin is used made use of the -py3 switch to either do
-            'from ._foo import *' or "from _foo import *". This block of code no longer does this
-            and instead checks the python version at runtime to switch between the two syntaxes.
-
-2016-05-31: wsfulton
-            Fix #690 - Smart pointer to %ignored class doesn't expose inherited methods.
-            Regression introduced in swig-3.0.9.

Doc/Manual/Contents.html

@@ -1595,6 +1595,13 @@
 <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>
+<li><a href="Python.html#Python_package_search_static">Statically linked C modules</a>
+</ul>
 </ul>
 <li><a href="Python.html#Python_python3support">Python 3 Support</a>
 <ul>

Doc/Manual/Python.html

@@ -117,6 +117,13 @@
 <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>
+<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>
+<li><a href="#Python_package_search_static">Statically linked C modules</a>
+</ul>
 </ul>
 <li><a href="#Python_python3support">Python 3 Support</a>
 <ul>
@@ -5521,6 +5528,23 @@ They should be created by other means. Both files (module <tt>*.py</tt> and
 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).  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  
+<a href="#Python_package_search">searches for the wrapper module</a>
+that 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 +5963,181 @@ zipimporter requires python-3.5.1 or newer to work with subpackages.
 <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 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 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>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>
+  <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>
+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><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/package/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><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/package/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><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
+/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>
+
+<H4><a name="Python_package_search_static">36.11.6.4 Statically linked C modules</a></H4>
+
+
+<p>It is strongly recommended to use dynamically linked modules for the C
+portion of your pair of Python modules.
+If for some reason you still need
+to link the C module of the pair of Python modules generated by SWIG into
+your interpreter, then this section provides some details on how this impacts
+the pure Python modules ability to locate the other part of the pair.
+Please also see the <a href="Python.html#Python_nn8">Static Linking</a> section.
+</p>
+
+<p>When Python is extended with C code the Python interpreter needs to be
+informed about details of the new C functions that have been linked into
+the executable.  The code to do this is created by SWIG and is automatically
+called in the correct way when the module is dynamically loaded.  However
+when the code is not dynamically loaded (because it is statically linked)
+Then the initialization method for the module created by SWIG is not
+called automatically and the Python interpreter has no idea that the
+new SWIG C module exists.
+</p>
+
+<p>Before Python 3, one could simply call the init method created by SWIG
+which would have normally been called when the shared object was dynamically
+loaded.  The specific name of this method is not given here because statically
+linked modules are not encouraged with SWIG
+(<a href="Python.html#Python_nn8">Static Linking</a>).  However one can find this
+init function in the C file generated by SWIG.
+</p>
+
+<p>If you are really keen on static linking there are two ways
+to initialize the SWIG generated C module with the init method.  Which way
+you use depends on what version of Python your module is being linked with.
+Python 2 and Python 3 treat this init function differently.  And the way
+they treat it affects how the pure Python module will be able to
+locate the C module.
+</p>
+
+<p>The details concerning this are covered completly in the documentation
+for Python itself.  Links to the relavent sections follow:
+</p>
+
+<ul>
+  <li><a href="https://docs.python.org/2/extending/extending.html#methodtable">Extending in python2</a></li>
+  <li><a href="https://docs.python.org/3.6/extending/extending.html#the-module-s-method-table-and-initialization-function">Extending in python3</a></li>
+</ul>
+
+<p>There are two keys things to understand.  The first is that in
+Python 2 the init() function returns void.  In Python 3 the init() function
+returns a PyObject * which points to the new module.  Secondly, when
+you call the init() method manually, you are the Python importer.  So, you
+determine which package the C module will be located in.
+</p>
+
+<p>So, if you are using Python 3 it is important that you follow what is
+described in the Python documentation linked above.  In particular, you can't
+simply call the init() function generated by SWIG and cast the PyObject
+pointer it returns over the side.  If you do then Python 3 will have no
+idea that your C module exists and the pure Python half of your wrapper will
+not be able to find it.  You need to register your module with the Python
+interpreter as described in the Python docs.
+</p>
+
+<p>With Python 2 things are somewhat more simple.  In this case the init function
+returns void.  Calling it will register your new C module as a <b>global</b>
+module.  The pure Python part of the SWIG wrapper will be able to find it
+because it tries both the pure Python module it is part of and the global
+module.  If you wish not to have the statically linked module be a global
+module then you will either need to refer to the Python documentation on how
+to do this (remember you are now the Python importer) or use dynamic linking.
+</p>
+
 <H2><a name="Python_python3support">36.12 Python 3 Support</a></H2>
 
 

Doc/Manual/Sections.html

@@ -8,7 +8,7 @@
 <H1><a name="Sections">SWIG-3.0 Documentation</a></H1>
 
 <p>
-Last update : SWIG-3.0.10 (in progress)
+Last update : SWIG-3.0.11 (in progress)
 </p>
 
 <H2><a name="Sections_Sections">Sections</a></H2>

README

@@ -1,6 +1,6 @@
 SWIG (Simplified Wrapper and Interface Generator)
 
-Version: 3.0.10 (in progress)
+Version: 3.0.11 (in progress)
 
 Tagline: SWIG is a compiler that integrates C and C++ with languages
          including Perl, Python, Tcl, Ruby, PHP, Java, C#, D, Go, Lua,

RELEASENOTES

@@ -8,7 +8,7 @@ Detailed release notes are available with the release and are also
 published on the SWIG web site at http://swig.org/release.html.
 
 SWIG-3.0.10 summary:
-- Regression fixes for smart pointers and importing python modules.
+- Regression fixes for smart pointers and importing Python modules.
 
 SWIG-3.0.9 summary:
 - Add support for Python's implicit namespace packages.

configure.ac

@@ -2,7 +2,7 @@ dnl Process this file with autoconf to produce a configure script.
 dnl The macros which aren't shipped with the autotools are stored in the
 dnl Tools/config directory in .m4 files.
 
-AC_INIT([swig],[3.0.10],[http://www.swig.org])
+AC_INIT([swig],[3.0.11],[http://www.swig.org])
 
 dnl NB: When this requirement is increased to 2.60 or later, AC_PROG_SED
 dnl     definition below can be removed