Skip to content
Permalink
Browse files

Improve the documentation for template strings (#856)

  • Loading branch information
warsaw committed Mar 28, 2017
1 parent 8cea592 commit 9f74deba784fc8781d13ed564f69c02ed7c331bb
Showing with 28 additions and 15 deletions.
  1. +5 −4 Doc/library/stdtypes.rst
  2. +19 −11 Doc/library/string.rst
  3. +4 −0 Misc/NEWS
@@ -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 <f-strings>` 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
<f-strings>`, the :meth:`str.format` interface, or :ref:`template strings
<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.
@@ -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`. 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
strings for i18n, see the
`flufl.i18n <http://flufli18n.readthedocs.io/en/latest/>`_ package.

Template strings support ``$``-based substitutions, using the following rules:

* ``$$`` is an escape; it is replaced with a single ``$``.

@@ -735,14 +741,17 @@ 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. 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
@@ -787,4 +796,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.

@@ -879,6 +879,10 @@ C API
Documentation
-------------

- 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.

- bpo-25008: Document smtpd.py as effectively deprecated and add a pointer to

0 comments on commit 9f74deb

Please sign in to comment.
You can’t perform that action at this time.