Fix AST handling of docstrings and __future__ ordering

This closes #1367 and closes #1540

hy/compiler.py

@@ -1719,7 +1719,19 @@ def hy_compile(tree, module_name, root=ast.Module, get_expr=False):
     if not get_expr:
         result += result.expr_as_stmt()
 
-    body = compiler.imports_as_stmts(tree) + result.stmts
+    body = []
+
+    # Pull out a single docstring and prepend to the resulting body.
+    if (len(result.stmts) > 0 and
+        issubclass(root, ast.Module) and
+        isinstance(result.stmts[0], ast.Expr) and
+        isinstance(result.stmts[0].value, ast.Str)):
+
+        body += [result.stmts.pop(0)]
+
+    body += sorted(compiler.imports_as_stmts(tree) + result.stmts,
+                   key=lambda a: not (isinstance(a, ast.ImportFrom) and
+                                      a.module == '__future__'))
 
     ret = root(body=body)
 

tests/compilers/test_ast.py

@@ -664,3 +664,25 @@ def test_ast_bad_yield_from():
 def test_eval_generator_with_return():
     """Ensure generators with a return statement works."""
     can_eval("(fn [] (yield 1) (yield 2) (return))")
+
+
+def test_futures_imports():
+    """Make sure __future__ imports go first, especially when builtins are
+    automatically added (e.g. via use of a builtin name like `name`)."""
+    hy_ast = can_compile((
+        '(import [__future__ [print_function]])\n'
+        '(import sys)\n'
+        '(setv name [1 2])'
+        '(print (first name))'))
+
+    assert hy_ast.body[0].module == '__future__'
+    assert hy_ast.body[1].module == 'hy.core.language'
+
+    hy_ast = can_compile((
+        '(import sys)\n'
+        '(import [__future__ [print_function]])\n'
+        '(setv name [1 2])'
+        '(print (first name))'))
+
+    assert hy_ast.body[0].module == '__future__'
+    assert hy_ast.body[1].module == 'hy.core.language'

tests/resources/pydemo.hy

@@ -4,6 +4,7 @@
 
 ;; This Hy module is intended to concisely demonstrate all of
 ;; Python's major syntactic features for the purpose of testing hy2py.
+"This is a module docstring."
 
 (setv mystring (* "foo" 3))
 

tests/test_hy2py.py

@@ -24,6 +24,9 @@ def test_hy2py_import(tmpdir):
 
 def assert_stuff(m):
 
+    # This makes sure that automatically imported builtins go after docstrings.
+    assert m.__doc__ == u'This is a module docstring.'
+
     assert m.mystring == "foofoofoo"
 
     assert m.long_string == u"This is a very long string literal, which would surely exceed any limitations on how long a line or a string literal can be. The string literal alone exceeds 256 characters. It also has a character outside the Basic Multilingual Plane: 😂. Here's a double quote: \". Here are some escaped newlines:\n\n\nHere is a literal newline:\nCall me Ishmael. Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation. Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people’s hats off—then, I account it high time to get to sea as soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, almost all men in their degree, some time or other, cherish very nearly the same feelings towards the ocean with me."