Add %pythonbegin directive.

For adding code at the beginning of the generated .py file.

CHANGES.current

@@ -5,6 +5,16 @@ See the RELEASENOTES file for a summary of changes in each release.
 Version 2.0.11 (in progress)
 ============================
 
+2013-07-05: wsfulton
+            [Python] Add %pythonbegin directive which works like %pythoncode, except the specified code is
+            added at the beginning of the generated .py file. This is primarily needed for importing from
+            __future__ statements required to be at the very beginning of the file. Example:
+
+              %pythonbegin %{
+              from __future__ import print_function
+              print("Loading", "Whizz", "Bang", sep=' ... ')
+              %}
+
 2013-07-01: wsfulton
             [Python] Apply SF patch #340 - Uninitialized variable fix in SWIG_Python_NonDynamicSetAttr
             when using -builtin.

Doc/Manual/Python.html

@@ -3314,6 +3314,53 @@ what can be done without having to rely on any of the more advanced
 customization features.
 </p>
 
+<p>
+There is also <tt>%pythonbegin</tt> which is another directive very similar to <tt>%pythoncode</tt>,
+but generates the given Python code at the beginning of the <tt>.py</tt> file.
+This directive works in the same way as <tt>%pythoncode</tt>, except the code is copied
+just after the SWIG banner (comment) at the top of the file, before any real code.
+This provides an opportunity to add your own description in a comment near the top of the file as well
+as Python imports that have to appear at the top of the file, such as "<tt>from __future__ import</tt>"
+statements.
+</p>
+
+<p>
+The following shows example usage for Python 2.6 to use <tt>print</tt> as it can in Python 3, that is, as a function instead of a statement:
+</p>
+
+<div class="code">
+<pre>
+%pythonbegin %{
+# This module provides wrappers to the Whizz Bang library
+%}
+
+%pythonbegin %{
+from __future__ import print_function
+print("Loading", "Whizz", "Bang", sep=' ... ')
+%}
+</pre>
+</div>
+
+<p>
+which can be seen when viewing the first few lines of the generated <tt>.py</tt> file:
+</p>
+
+<div class="code">
+<pre>
+# This file was automatically generated by SWIG (http://www.swig.org).
+# Version 2.0.11
+#
+# Do not make changes to this file unless you know what you are doing--modify
+# the SWIG interface file instead.
+
+# This module provides wrappers to the Whizz Bang library
+
+from __future__ import print_function
+print("Loading", "Whizz", "Bang", sep=' ... ')
+
+</pre>
+</div>
+
 <p>Sometimes you may want to replace or modify the wrapper function
 that SWIG creates in the proxy <tt>.py</tt> file.  The Python module
 in SWIG provides some features that enable you to do this.  First, to

Examples/test-suite/python_append.i

@@ -1,11 +1,10 @@
 /*
-Testcase to test %pythonprepend and %pythonappend
+Testcase to test %pythonprepend and %pythonappend %pythoncode %pythonbegin
 */
 
 %module python_append 
 
 %pythoncode %{
-  import os.path
   mypath = os.path.dirname("/a/b/c/d.txt")
   funcpath = None
   staticfuncpath = None
@@ -35,6 +34,10 @@ pass
     pass
 }
 
+%pythonbegin %{
+import os.path
+%}
+
 %inline %{
 
 class Test {

Lib/python/pyuserdir.swg

@@ -7,6 +7,7 @@
 /* shadow code */
 #define %shadow      %insert("shadow")
 #define %pythoncode  %insert("python")
+#define %pythonbegin %insert("pythonbegin")
 
 
 /* ------------------------------------------------------------------------- */

Source/Modules/python.cxx

@@ -42,6 +42,7 @@ static File *f_directors_h = 0;
 static File *f_init = 0;
 static File *f_shadow_py = 0;
 static String *f_shadow = 0;
+static String *f_shadow_begin = 0;
 static Hash *f_shadow_imports = 0;
 static String *f_shadow_builtin_imports = 0;
 static String *f_shadow_stubs = 0;
@@ -784,6 +785,7 @@ public:
       filen = NULL;
 
       f_shadow = NewString("");
+      f_shadow_begin = NewString("");
       f_shadow_imports = NewHash();
       f_shadow_builtin_imports = NewString("");
       f_shadow_stubs = NewString("");
@@ -977,6 +979,7 @@ public:
       if (!modern) {
 	Printv(f_shadow, "# This file is compatible with both classic and new-style classes.\n", NIL);
       }
+      Printv(f_shadow_py, "\n", f_shadow_begin, "\n", NIL);
       Printv(f_shadow_py, "\n", f_shadow_builtin_imports, "\n", NIL);
       Printv(f_shadow_py, f_shadow, "\n", NIL);
       Printv(f_shadow_py, f_shadow_stubs, "\n", NIL);
@@ -4451,12 +4454,16 @@ public:
     String *code = Getattr(n, "code");
     String *section = Getattr(n, "section");
 
-    if ((!ImportMode) && ((Cmp(section, "python") == 0) || (Cmp(section, "shadow") == 0))) {
+    if (!ImportMode && (Cmp(section, "python") == 0 || Cmp(section, "shadow") == 0)) {
       if (shadow) {
 	String *pycode = pythoncode(code, shadow_indent);
 	Printv(f_shadow, pycode, NIL);
 	Delete(pycode);
       }
+    } else if (!ImportMode && (Cmp(section, "pythonbegin") == 0)) {
+      String *pycode = pythoncode(code, "");
+      Printv(f_shadow_begin, pycode, NIL);
+      Delete(pycode);
     } else {
       Language::insertDirective(n);
     }