summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorBarry Warsaw <barry@python.org>2004-09-18 21:13:43 (GMT)
committerBarry Warsaw <barry@python.org>2004-09-18 21:13:43 (GMT)
commit33db656dbfa7de5e4fdf9ff20d140c4d3b26614b (patch)
treef4e2b7c801cf6257884708f9cf6a7db7301554b7 /Doc/lib
parent0273f5b6b29486629f74f184da84172cb43fe221 (diff)
downloadcpython-33db656dbfa7de5e4fdf9ff20d140c4d3b26614b.zip
cpython-33db656dbfa7de5e4fdf9ff20d140c4d3b26614b.tar.gz
cpython-33db656dbfa7de5e4fdf9ff20d140c4d3b26614b.tar.bz2
Update Template/PEP 292 documentation to current implementation.
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/libstring.tex107
1 files changed, 70 insertions, 37 deletions
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
index bb28a2b..c9d27b5 100644
--- a/Doc/lib/libstring.tex
+++ b/Doc/lib/libstring.tex
@@ -89,10 +89,8 @@ The constants defined in this module are:
\subsection{Template strings}
-Templates are Unicode strings that can be used to provide string substitutions
-as described in \pep{292}. There is a \class{Template} class that is a
-subclass of \class{unicode}, overriding the default \method{__mod__()} method.
-Instead of the normal \samp{\%}-based substitutions, Template strings support
+Templates provide simpler string substitutions as described in \pep{292}.
+Instead of the normal \samp{\%}-based substitutions, Templates support
\samp{\$}-based substitutions, using the following rules:
\begin{itemize}
@@ -113,55 +111,90 @@ Any other appearance of \samp{\$} in the string will result in a
\versionadded{2.4}
-Template strings are used just like normal strings, in that the modulus
-operator is used to interpolate a dictionary of values into a Template string,
-for example:
+The \module{string} module provides a \class{Template} class that implements
+these rules. The methods of \class{Template} are:
+
+\begin{classdesc}{Template}{template}
+The constructor takes a single argument which is the template string.
+\end{classdesc}
+
+\begin{methoddesc}[Template]{substitute}{mapping\optional{, **kws}}
+Performs the template substitution, returning a new string. \var{mapping} is
+any dictionary-like object with keys that match the placeholders in the
+template. Alternatively, you can provide keyword arguments, where the
+keywords are the placeholders. When both \var{mapping} and \var{kws} are
+given and there are duplicates, the placeholders from \var{kws} take
+precedence.
+\end{methoddesc}
+
+\begin{methoddesc}[Template]{safe_substitute}{mapping\optional{, **kws}}
+Like \method{substitute()}, except that if placeholders are missing from
+\var{mapping} and \var{kws}, instead of raising a \exception{KeyError}
+exception, the original placeholder will appear in the resulting string
+intact. Note that other exceptions may still be raised, including
+\exception{ValueError} as described above.
+\end{methoddesc}
+
+\class{Template} instances also provide one public data attribute:
+
+\begin{memberdesc}[string]{template}
+This is the object passed to the constructor's \var{template} argument. In
+general, you shouldn't change it, but read-only access is not enforced.
+\end{memberdesc}
+
+Here is an example of how to use a Template:
\begin{verbatim}
>>> from string import Template
>>> s = Template('$who likes $what')
->>> print s % dict(who='tim', what='kung pao')
-tim likes kung pao
->>> Template('Give $who $100') % dict(who='tim')
+>>> s.substitute(who='tim', what='kung pao')
+'tim likes kung pao'
+>>> d = dict(who='tim')
+>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
[...]
-ValueError: Invalid placeholder at index 10
+ValueError: Invalid placeholder in string: line 1, col 10
+>>> Template('$who likes $what').substitute(d)
+Traceback (most recent call last):
+[...]
+KeyError: 'what'
+>>> Template('$who likes $what').safe_substitute(d)
+'tim likes $what'
\end{verbatim}
-There is also a \class{SafeTemplate} class, derived from \class{Template}
-which acts the same as \class{Template}, except that if placeholders are
-missing in the interpolation dictionary, no \exception{KeyError} will be
-raised. Instead the original placeholder (with or without the braces, as
-appropriate) will be used:
-
-\begin{verbatim}
->>> from string import SafeTemplate
->>> s = SafeTemplate('$who likes $what for ${meal}')
->>> print s % dict(who='tim')
-tim likes $what for ${meal}
-\end{verbatim}
+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:
-The values in the mapping will automatically be converted to Unicode strings,
-using the built-in \function{unicode()} function, which will be called without
-optional arguments \var{encoding} or \var{errors}.
+\begin{itemize}
+\item \var{delimiter} -- This is the literal string describing a placeholder
+ introducing delimiter. The default value \samp{\$}. Note that this
+ should \emph{not} be a regular expression, as the implementation will
+ call \method{re.escape()} on this string as needed.
+\item \var{idpattern} -- This is the regular expression describing the pattern
+ for non-braced placeholders (the braces will be added automatically as
+ appropriate). The default value is the regular expression
+ \samp{[_a-z][_a-z0-9]*}.
+\end{itemize}
-Advanced usage: you can derive subclasses of \class{Template} or
-\class{SafeTemplate} to use application-specific placeholder rules. To do
-this, you override the class attribute \member{pattern}; the value must be a
-compiled regular expression object with four named capturing groups. The
+Alternatively, you can provide the entire regular expression pattern by
+overriding the class attribute \var{pattern}. If you do this, the value must
+be a regular expression object with four named capturing groups. The
capturing groups correspond to the rules given above, along with the invalid
placeholder rule:
\begin{itemize}
-\item \var{escaped} -- This group matches the escape sequence, \samp{\$\$},
- in the default pattern.
+\item \var{escaped} -- This group matches the escape sequence,
+ e.g. \samp{\$\$}, in the default pattern.
\item \var{named} -- This group matches the unbraced placeholder name; it
- should not include the \samp{\$} in capturing group.
-\item \var{braced} -- This group matches the brace delimited placeholder name;
- it should not include either the \samp{\$} or braces in the capturing
+ should not include the delimiter in capturing group.
+\item \var{braced} -- This group matches the brace enclosed placeholder name;
+ it should not include either the delimiter or braces in the capturing
group.
-\item \var{bogus} -- This group matches any other \samp{\$}. It usually just
- matches a single \samp{\$} and should appear last.
+\item \var{invalid} -- This group matches any other delimiter pattern (usually
+ a single delimiter), and it should appear last in the regular
+ expression.
\end{itemize}
\subsection{String functions}