Improve the documentation for template strings (#856) · python/cpython@9f74deb (original) (raw)
`@@ -657,9 +657,15 @@ Nesting arguments and more complex examples::
`
657
657
`Template strings
`
658
658
`----------------
`
659
659
``
660
``
`` -
Templates provide simpler string substitutions as described in :pep:292.
``
661
``
Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
662
``
`-
-based substitutions, using the following rules:
`
``
660
`+
Template strings provide simpler string substitutions as described in
`
``
661
`` +
:pep:292. A primary use case for template strings is for
``
``
662
`+
internationalization (i18n) since in that context, the simpler syntax and
`
``
663
`+
functionality makes it easier to translate than other built-in string
`
``
664
`+
formatting facilities in Python. As an example of a library built on template
`
``
665
`+
strings for i18n, see the
`
``
666
`` +
flufl.i18n <http://flufli18n.readthedocs.io/en/latest/>_ package.
``
``
667
+
``
668
Template strings support ``$``-based substitutions, using the following rules:
663
669
``
664
670
``` * $$ is an escape; it is replaced with a single $.
`665`
`671`
``
`@@ -735,14 +741,17 @@ Here is an example of how to use a Template::
`
`735`
`741`
` >>> Template('$who likes $what').safe_substitute(d)
`
`736`
`742`
` 'tim likes $what'
`
`737`
`743`
``
`738`
``
`` -
Advanced usage: you can derive subclasses of :class:`Template` to customize the
``
`739`
``
`-
placeholder syntax, delimiter character, or the entire regular expression used
`
`740`
``
`-
to parse template strings. To do this, you can override these class attributes:
`
``
`744`
`` +
Advanced usage: you can derive subclasses of :class:`Template` to customize
``
``
`745`
`+
the placeholder syntax, delimiter character, or the entire regular expression
`
``
`746`
`+
used to parse template strings. To do this, you can override these class
`
``
`747`
`+
attributes:
`
`741`
`748`
``
`742`
``
`-
* *delimiter* -- This is the literal string describing a placeholder introducing
`
`743`
``
``` -
delimiter. The default value is ``$``. Note that this should *not* be a
744
``
`` -
regular expression, as the implementation will call :meth:re.escape on this
``
745
``
`-
string as needed.
`
``
749
`+
- delimiter -- This is the literal string describing a placeholder
`
``
750
introducing delimiter. The default value is ``$``. Note that this should
``
751
`+
not be a regular expression, as the implementation will call
`
``
752
`` +
:meth:re.escape on this string as needed. Note further that you cannot
``
``
753
`+
change the delimiter after class creation (i.e. a different delimiter must
`
``
754
`+
be set in the subclass's class namespace).
`
746
755
``
747
756
`* idpattern -- This is the regular expression describing the pattern for
`
748
757
` non-braced placeholders (the braces will be added automatically as
`
`@@ -787,4 +796,3 @@ Helper functions
`
787
796
``` or None, runs of whitespace characters are replaced by a single space
```
788
797
` and leading and trailing whitespace are removed, otherwise sep is used to
`
789
798
` split and join the words.
`
790
``
-