From 2cbfda1db44153a5417abdb9464f505e77cf4a67 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Mon, 27 Mar 2017 18:34:47 -0400 Subject: [PATCH 1/3] bpo-19824 bpo-20314 --- Doc/library/stdtypes.rst | 9 +++++---- Doc/library/string.rst | 28 +++++++++++++++++----------- Misc/NEWS | 3 +++ 3 files changed, 25 insertions(+), 15 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9cf876783ec25fb..a9877ba666d3f7f 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2076,10 +2076,11 @@ expression support in the :mod:`re` module). The formatting operations described here exhibit a variety of quirks that lead to a number of common errors (such as failing to display tuples and - dictionaries correctly). Using the newer :ref:`formatted - string literals ` or the :meth:`str.format` interface - helps avoid these errors. These alternatives also provide more powerful, - flexible and extensible approaches to formatting text. + dictionaries correctly). Using the newer :ref:`formatted string literals + `, the :meth:`str.format` interface, or :ref:`template strings + ` may help avoid these errors. Each of these + alternatives provides their own trade-offs and benefits of simplicity, + flexibility, and/or extensibility. String objects have one unique built-in operation: the ``%`` operator (modulo). This is also known as the string *formatting* or *interpolation* operator. diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 03eaf3b9cd33129..39c8a6aabd23ce7 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -657,9 +657,15 @@ Nesting arguments and more complex examples:: Template strings ---------------- -Templates provide simpler string substitutions as described in :pep:`292`. -Instead of the normal ``%``\ -based substitutions, Templates support ``$``\ --based substitutions, using the following rules: +Template strings provide simpler string substitutions as described in +:pep:`292`. The primary use case for template strings is for +internationalization (i18n) since in those contexts, the more featured yet +complex formatting languages for f-strings and ``str.format()`` can make +translations more difficult to implement. As an example of a library for i18n +built on template strings, see the `flufl.i18n +`_ package. + +Template strings support ``$``-based substitutions, using the following rules: * ``$$`` is an escape; it is replaced with a single ``$``. @@ -735,14 +741,15 @@ Here is an example of how to use a Template:: >>> Template('$who likes $what').safe_substitute(d) 'tim likes $what' -Advanced usage: you can derive subclasses of :class:`Template` to customize the -placeholder syntax, delimiter character, or the entire regular expression used -to parse template strings. To do this, you can override these class attributes: +Advanced usage: you can derive subclasses of :class:`Template` to customize +the placeholder syntax, delimiter character, or the entire regular expression +used to parse template strings. To do this, you can override these class +attributes: -* *delimiter* -- This is the literal string describing a placeholder introducing - delimiter. The default value is ``$``. Note that this should *not* be a - regular expression, as the implementation will call :meth:`re.escape` on this - string as needed. +* *delimiter* -- This is the literal string describing a placeholder + introducing delimiter. The default value is ``$``. Note that this should + *not* be a regular expression, as the implementation will call + :meth:`re.escape` on this string as needed. * *idpattern* -- This is the regular expression describing the pattern for non-braced placeholders (the braces will be added automatically as @@ -787,4 +794,3 @@ Helper functions or ``None``, runs of whitespace characters are replaced by a single space and leading and trailing whitespace are removed, otherwise *sep* is used to split and join the words. - diff --git a/Misc/NEWS b/Misc/NEWS index c8471b7ebfe4e1d..68de2415061586b 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -876,6 +876,9 @@ C API Documentation ------------- +- bpo-19824, bpo-20314: Improve the documentation for, and links to, template + strings, by emphasizing their utility for internationalization. + - bpo-28929: Link the documentation to its source file on GitHub. - bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to From 2dcc1f4422bc3d5ca861f0547eb89ea3b32b7f83 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Mon, 27 Mar 2017 20:49:11 -0400 Subject: [PATCH 2/3] Address review comments. Also, add bpo-12518 to the list of issues fixed by this PR. --- Doc/library/string.rst | 14 ++++++++------ Misc/NEWS | 5 +++-- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 39c8a6aabd23ce7..1e652e343facf5d 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -659,11 +659,11 @@ Template strings Template strings provide simpler string substitutions as described in :pep:`292`. The primary use case for template strings is for -internationalization (i18n) since in those contexts, the more featured yet -complex formatting languages for f-strings and ``str.format()`` can make -translations more difficult to implement. As an example of a library for i18n -built on template strings, see the `flufl.i18n -`_ package. +internationalization (i18n) since in that context, the simpler syntax and +functionality makes it easier to translate than other built-in string +formatting facilities in Python. As an example of a library built on template +strings for i18n, see the +`flufl.i18n `_ package. Template strings support ``$``-based substitutions, using the following rules: @@ -749,7 +749,9 @@ attributes: * *delimiter* -- This is the literal string describing a placeholder introducing delimiter. The default value is ``$``. Note that this should *not* be a regular expression, as the implementation will call - :meth:`re.escape` on this string as needed. + :meth:`re.escape` on this string as needed. Note further that you cannot + change the delimiter after class creation (i.e. a different delimiter must + be set in the subclass's class namespace). * *idpattern* -- This is the regular expression describing the pattern for non-braced placeholders (the braces will be added automatically as diff --git a/Misc/NEWS b/Misc/NEWS index 68de2415061586b..8ea35fc8bfa53e7 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -876,8 +876,9 @@ C API Documentation ------------- -- bpo-19824, bpo-20314: Improve the documentation for, and links to, template - strings, by emphasizing their utility for internationalization. +- bpo-19824, bpo-20314, bpo-12518: Improve the documentation for, and links + to, template strings by emphasizing their utility for internationalization, + and by clarifying some usage constraints. - bpo-28929: Link the documentation to its source file on GitHub. From e39a2808081a421dbc196e5f7a7633da61d48339 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Tue, 28 Mar 2017 09:30:41 -0400 Subject: [PATCH 3/3] One last small change. --- Doc/library/string.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 1e652e343facf5d..8176a81d4cfe856 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -658,7 +658,7 @@ Template strings ---------------- Template strings provide simpler string substitutions as described in -:pep:`292`. The primary use case for template strings is for +:pep:`292`. A primary use case for template strings is for internationalization (i18n) since in that context, the simpler syntax and functionality makes it easier to translate than other built-in string formatting facilities in Python. As an example of a library built on template