From 33db656dbfa7de5e4fdf9ff20d140c4d3b26614b Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Sat, 18 Sep 2004 21:13:43 +0000 Subject: [PATCH] Update Template/PEP 292 documentation to current implementation. --- Doc/lib/libstring.tex | 107 +++++++++++++++++++++++++++--------------- 1 file changed, 70 insertions(+), 37 deletions(-) diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex index bb28a2b21de..c9d27b5d575 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: +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: -\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} +\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} -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}. - -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}