Finalized future_imports feature.

Changed keyword argument from futures to future_imports for clarity.
Added docstring describing use.

3 files changed, 18 insertions, 9 deletions

diff --git a/mako/lookup.py b/mako/lookup.py
index e583dd2..a67e38e 100644
--- a/mako/lookup.py
+++ b/mako/lookup.py
@@ -169,10 +169,10 @@ class TemplateLookup(TemplateCollection):
                         buffer_filters=(),
                         strict_undefined=False,
                         imports=None,
+                        future_imports=None,
                         enable_loop=True,
                         input_encoding=None,
-                        preprocessor=None,
-                        futures=None):
+                        preprocessor=None):
 
         self.directories = [posixpath.normpath(d) for d in
                             util.to_list(directories, ())
@@ -209,9 +209,9 @@ class TemplateLookup(TemplateCollection):
             'buffer_filters':buffer_filters,
             'strict_undefined':strict_undefined,
             'imports':imports,
+            'future_imports':future_imports,
             'enable_loop':enable_loop,
-            'preprocessor':preprocessor,
-            'futures': futures}
+            'preprocessor':preprocessor}
 
         if collection_size == -1:
             self._collection = {}
diff --git a/mako/template.py b/mako/template.py
index 4e99d9f..84d1ebb 100644
--- a/mako/template.py
+++ b/mako/template.py
@@ -112,6 +112,15 @@ class Template(object):
      preamble of all generated Python modules. See the example
      in :ref:`filtering_default_filters`.
 
+    :param future_imports: String list of names to import from `__future__`.
+     These will be concatenated into a comma-separated string and inserted
+     into the beginning of the template, e.g. ``futures_imports=['FOO',
+     'BAR']`` results in ``from __future__ import FOO, BAR``.  If you're
+     interested in using features like the new division operator, you must
+     use future_imports to convey that to the renderer, as otherwise the
+     import will not appear as the first executed statement in the generated
+     code and will therefore not have the desired effect.
+
     :param input_encoding: Encoding of the template's source code.  Can
      be used in lieu of the coding comment. See
      :ref:`usage_unicode` as well as :ref:`unicode_toplevel` for
@@ -215,9 +224,9 @@ class Template(object):
                     buffer_filters=(),
                     strict_undefined=False,
                     imports=None,
+                    future_imports=None,
                     enable_loop=True,
-                    preprocessor=None,
-                    futures=None):
+                    preprocessor=None):
         if uri:
             self.module_id = re.sub(r'\W', "_", uri)
             self.uri = uri
@@ -248,7 +257,6 @@ class Template(object):
         self.enable_loop = enable_loop
         self.strict_undefined = strict_undefined
         self.module_writer = module_writer
-        self.futures = futures
 
         if util.py3k and disable_unicode:
             raise exceptions.UnsupportedError(
@@ -268,6 +276,7 @@ class Template(object):
         self.buffer_filters = buffer_filters
 
         self.imports = imports
+        self.future_imports = future_imports
         self.preprocessor = preprocessor
 
         # if plain text, compile code in memory only
@@ -604,7 +613,7 @@ def _compile(template, text, filename, generate_magic_comment):
                             default_filters=template.default_filters,
                             buffer_filters=template.buffer_filters,
                             imports=template.imports,
-                            future_imports=template.futures,
+                            future_imports=template.future_imports,
                             source_encoding=lexer.encoding,
                             generate_magic_comment=generate_magic_comment,
                             disable_unicode=template.disable_unicode,
diff --git a/test/test_template.py b/test/test_template.py
index e6fa3c6..2821910 100644
--- a/test/test_template.py
+++ b/test/test_template.py
@@ -1245,5 +1245,5 @@ class PreprocessTest(TemplateTest):
 class FuturesTest(TemplateTest):
 
     def test_future_import(self):
-        t = Template("${ x / y }", futures=["division"])
+        t = Template("${ x / y }", future_imports=["division"])
         assert result_lines(t.render(x=12, y=5)) == ["2.4"]