Update Template/PEP 292 documentation to current implementation.

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}