gh-102856: Update "Formatted string literals" docs section after PEP701 (#104861)

1 files changed, 35 insertions, 17 deletions

diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
index 8adb4b7..757f887 100644
--- a/Doc/reference/lexical_analysis.rst
+++ b/Doc/reference/lexical_analysis.rst
@@ -741,16 +741,28 @@ Expressions in formatted string literals are treated like regular
 Python expressions surrounded by parentheses, with a few exceptions.
 An empty expression is not allowed, and both :keyword:`lambda`  and
 assignment expressions ``:=`` must be surrounded by explicit parentheses.
-Replacement expressions 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.
+Each expression is evaluated in the context where the formatted string literal
+appears, in order from left to right.  Replacement expressions can contain
+newlines in both single-quoted and triple-quoted f-strings and they can contain
+comments.  Everything that comes after a ``#`` inside a replacement field
+is a comment (even closing braces and quotes). In that case, replacement fields
+must be closed in a different line.
+
+.. code-block:: text
+
+   >>> f"abc{a # This is a comment }"
+   ... + 3}"
+   'abc5'
 
 .. versionchanged:: 3.7
    Prior to Python 3.7, an :keyword:`await` expression and comprehensions
    containing an :keyword:`async for` clause were illegal in the expressions
    in formatted string literals due to a problem with the implementation.
 
+.. versionchanged:: 3.12
+   Prior to Python 3.12, comments were not allowed inside f-string replacement
+   fields.
+
 When the equal sign ``'='`` is provided, the output will have the expression
 text, the ``'='`` and the evaluated value. Spaces after the opening brace
 ``'{'``, within the expression and after the ``'='`` are all retained in the
@@ -813,24 +825,30 @@ Some examples of formatted string literals::
    'line = "The mill\'s closed" '
 
 
-A consequence of sharing the same syntax as regular string literals is
-that characters in the replacement fields must not conflict with the
-quoting used in the outer formatted string literal::
+Reusing the outer f-string quoting type inside a replacement field is
+permitted::
 
-   f"abc {a["x"]} def"    # error: outer string literal ended prematurely
-   f"abc {a['x']} def"    # workaround: use different quoting
+   >>> a = dict(x=2)
+   >>> f"abc {a["x"]} def"
+   'abc 2 def'
 
-Backslashes are not allowed in format expressions and will raise
-an error::
+.. versionchanged:: 3.12
+   Prior to Python 3.12, reuse of the same quoting type of the outer f-string
+   inside a replacement field was not possible.
 
-   f"newline: {ord('\n')}"  # raises SyntaxError
+Backslashes are also allowed in replacement fields and are evaluated the same
+way as in any other context::
 
-To include a value in which a backslash escape is required, create
-a temporary variable.
+   >>> a = ["a", "b", "c"]
+   >>> print(f"List a contains:\n{"\n".join(a)}")
+   List a contains:
+   a
+   b
+   c
 
-   >>> newline = ord('\n')
-   >>> f"newline: {newline}"
-   'newline: 10'
+.. versionchanged:: 3.12
+   Prior to Python 3.12, backslashes were not permitted inside an f-string
+   replacement field.
 
 Formatted string literals cannot be used as docstrings, even if they do not
 include expressions.