From f6cb83cae6c39e2577f5ffc30f12db3cd41bfd2e Mon Sep 17 00:00:00 2001 From: Dave Date: Sat, 20 Sep 2025 19:24:04 +0000 Subject: [PATCH 1/5] Improve description of Interpolation.expression --- Doc/library/string.templatelib.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst index 85d65fa9de1e22..1275d5d50d5b8e 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -258,13 +258,14 @@ Types .. attribute:: expression :type: str - The text of a valid Python expression, or an empty string. - - The :attr:`.expression` is the original text of the - interpolation's Python expression, if the interpolation was created - from a t-string literal. Developers creating interpolations manually - should either set this to an empty string or choose a suitable valid - Python expression. + For interpolations created from t-string literals, :attr:`!expression` + is the source text found inside the curly braces, including any + whitespace, but excluding the curly braces themselves. For manually + created interpolations, :attr:`!expression` is an arbitrary string. + + It is recommended that developers manually creating + :class:`!Interpolation` instances use valid Python expressions or leave + the string empty, but this is not enforced. >>> t'{1 + 2}'.interpolations[0].expression '1 + 2' From 44ea6c30589621d35bc12291be70b5321701cc82 Mon Sep 17 00:00:00 2001 From: Dave Peck Date: Sun, 21 Sep 2025 10:21:20 -0700 Subject: [PATCH 2/5] Update Doc/library/string.templatelib.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/string.templatelib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst index 1275d5d50d5b8e..b04bfa3e6a4042 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -258,7 +258,7 @@ Types .. attribute:: expression :type: str - For interpolations created from t-string literals, :attr:`!expression` + For interpolations created by t-string literals, :attr:`!expression` is the source text found inside the curly braces, including any whitespace, but excluding the curly braces themselves. For manually created interpolations, :attr:`!expression` is an arbitrary string. From ca45cd1fac349e6c007cc90785701d55fdb109ae Mon Sep 17 00:00:00 2001 From: Dave Date: Sun, 21 Sep 2025 10:26:44 -0700 Subject: [PATCH 3/5] Minor updates --- Doc/library/string.templatelib.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst index 1275d5d50d5b8e..a5317e3fe5c85a 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -259,13 +259,14 @@ Types :type: str For interpolations created from t-string literals, :attr:`!expression` - is the source text found inside the curly braces, including any - whitespace, but excluding the curly braces themselves. For manually - created interpolations, :attr:`!expression` is an arbitrary string. - - It is recommended that developers manually creating - :class:`!Interpolation` instances use valid Python expressions or leave - the string empty, but this is not enforced. + is the source text found inside the curly braces (``{`` & ``}``), + including any whitespace, but excluding the curly braces themselves. + For manually created interpolations, :attr:`!expression` is the arbitrary + string provided when constructing the interpolation instance. + + We recommend using valid Python expressions or the empty string for the + ``expression`` field of manually created :class:`!Interpolation` + instances, although this is not enforced at runtime. >>> t'{1 + 2}'.interpolations[0].expression '1 + 2' From 2061750a15a8d882ecb7ad9dda6ce0faacd082e0 Mon Sep 17 00:00:00 2001 From: Dave Date: Mon, 22 Sep 2025 11:15:35 -0700 Subject: [PATCH 4/5] Clarify further what goes into --- Doc/library/string.templatelib.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst index 31bdfaa282bfa0..db808fd0f7a5a7 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -259,8 +259,9 @@ Types :type: str For interpolations created by t-string literals, :attr:`!expression` - is the source text found inside the curly braces (``{`` & ``}``), - including any whitespace, but excluding the curly braces themselves. + is the expression text found inside the curly braces (``{`` & ``}``), + including any whitespace, excluding the curly braces themselves, + and ending before the first ``!``, ``:``, or ``=`` if any is present. For manually created interpolations, :attr:`!expression` is the arbitrary string provided when constructing the interpolation instance. From e7ea9ebe617fa1abf208445813f596be67c30303 Mon Sep 17 00:00:00 2001 From: Dave Date: Sat, 4 Oct 2025 16:03:22 -0400 Subject: [PATCH 5/5] braces -> brackets --- Doc/library/string.templatelib.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/string.templatelib.rst b/Doc/library/string.templatelib.rst index db808fd0f7a5a7..a5b2d796aaf4b8 100644 --- a/Doc/library/string.templatelib.rst +++ b/Doc/library/string.templatelib.rst @@ -24,7 +24,7 @@ Template strings Template strings are a mechanism for custom string processing. They have the full flexibility of Python's :ref:`f-strings`, but return a :class:`Template` instance that gives access -to the static and interpolated (in curly braces) parts of a string +to the static and interpolated (in curly brackets) parts of a string *before* they are combined. To write a t-string, use a ``'t'`` prefix instead of an ``'f'``, like so: @@ -259,8 +259,8 @@ Types :type: str For interpolations created by t-string literals, :attr:`!expression` - is the expression text found inside the curly braces (``{`` & ``}``), - including any whitespace, excluding the curly braces themselves, + is the expression text found inside the curly brackets (``{`` & ``}``), + including any whitespace, excluding the curly brackets themselves, and ending before the first ``!``, ``:``, or ``=`` if any is present. For manually created interpolations, :attr:`!expression` is the arbitrary string provided when constructing the interpolation instance.