From 62796e72304f12359471be2a16ce8894707e55e6 Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Fri, 18 May 2018 10:38:27 -0700
Subject: [PATCH] bpo-33477: clarify compile "exec" mode and changes in 3.7

This makes it slightly clearer that `compile(..., 'exec')` is supposed
to be interpreted as a module and not just a sequence of statement, and
note that the *body* the returned `Module` have changed in 3.7.
---
 Doc/library/functions.rst                      | 18 +++++++++++++-----
 .../2018-05-22-11-33-23.bpo-33477.qiSjaw.rst   |  1 +
 2 files changed, 14 insertions(+), 5 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2018-05-22-11-33-23.bpo-33477.qiSjaw.rst

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 457e1c34ec9a26..4d919682d36648 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -234,11 +234,14 @@ are always available.  They are listed here in alphabetical order.
    pass some recognizable value if it wasn't read from a file (``'<string>'`` is
    commonly used).
 
-   The *mode* argument specifies what kind of code must be compiled; it can be
-   ``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
-   consists of a single expression, or ``'single'`` if it consists of a single
-   interactive statement (in the latter case, expression statements that
-   evaluate to something other than ``None`` will be printed).
+   The *mode* argument specifies what kind of code must be compiled; it can be:
+    - ``'exec'`` if *source* consists of a sequence of statements. If the first
+      statement is a string literal it will be interpreted as a module
+      docstring.
+    - ``'eval'`` if *source* consists of a single expression.
+    - ``'single'`` if *source* consists of a single interactive statement. In
+      this mode, expression statements that evaluate to something other than ``None``
+      will be printed).
 
    The optional arguments *flags* and *dont_inherit* control which future
    statements (see :pep:`236`) affect the compilation of *source*.  If neither
@@ -288,6 +291,11 @@ are always available.  They are listed here in alphabetical order.
       Previously, :exc:`TypeError` was raised when null bytes were encountered
       in *source*.
 
+   .. versionchanged:: 3.7
+      In ``exec`` **mode**, if the first statement is a string literal it will
+      be interpreted as a module docstring, and assigned to the ``Module``
+      **docstring** field instead of being the first **body** node.
+
 
 .. class:: complex([real[, imag]])
 
diff --git a/Misc/NEWS.d/next/Documentation/2018-05-22-11-33-23.bpo-33477.qiSjaw.rst b/Misc/NEWS.d/next/Documentation/2018-05-22-11-33-23.bpo-33477.qiSjaw.rst
new file mode 100644
index 00000000000000..9dcd0e5f863710
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-05-22-11-33-23.bpo-33477.qiSjaw.rst
@@ -0,0 +1 @@
+Improve builtin's compile documentation.