bpo-39545: Document restrictions on "await" and "async for" in f-strings. (GH-18459)

2 files changed, 10 insertions, 1 deletions

diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index b4e95b90db..8d050a69a9 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -730,7 +730,7 @@ Functions defined with ``async def`` syntax are always coroutine functions,
 even if they do not contain ``await`` or ``async`` keywords.
 
 It is a :exc:`SyntaxError` to use ``yield from`` expressions in
-``async def`` coroutines. Using ``await`` in :keyword:`f-strings` will also produce a :exc:`SyntaxError`.
+``async def`` coroutines.
 
 An example of a coroutine function::
 
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
index bee02443e6..3a03b94716 100644
--- a/Doc/reference/lexical_analysis.rst
+++ b/Doc/reference/lexical_analysis.rst
@@ -683,6 +683,15 @@ can contain line breaks (e.g. in triple-quoted strings), but they
 cannot contain comments.  Each expression is evaluated in the context
 where the formatted string literal appears, in order from left to right.
 
+.. index::
+   keyword: await
+   single: async for; in comprehensions
+
+An :keyword:`await` expression and comprehensions containing an
+:keyword:`async for` clause are illegal in the expression in formatted
+string literals. (The reason is a problem with the implementation ---
+this restriction is lifted in Python 3.7).
+
 If a conversion is specified, the result of evaluating the expression
 is converted before formatting.  Conversion ``'!s'`` calls :func:`str` on
 the result, ``'!r'`` calls :func:`repr`, and ``'!a'`` calls :func:`ascii`.