[Python-checkins] [3.12] gh-102856: Update "Formatted string literals" docs section after PEP701 (GH-104861) (#104865)
lysnikolaou
webhook-mailer at python.org
Wed May 24 09:40:38 EDT 2023
https://github.com/python/cpython/commit/25890ebbb8502a19b76da7634d9a85e3c8ddcb54
commit: 25890ebbb8502a19b76da7634d9a85e3c8ddcb54
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: lysnikolaou <lisandrosnik at gmail.com>
date: 2023-05-24T15:40:31+02:00
summary:
[3.12] gh-102856: Update "Formatted string literals" docs section after PEP701 (GH-104861) (#104865)
(cherry picked from commit 8e5b3b90c83d9aaca1dc2299da696b994780bcc0)
Co-authored-by: Lysandros Nikolaou <lisandrosnik at gmail.com>
files:
M Doc/reference/lexical_analysis.rst
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
index 8adb4b740825..757f887caa40 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.
More information about the Python-checkins
mailing list