<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"node110.html" />
<link rel=
"prev" href=
"node108.html" />
<link rel=
"parent" href=
"module-string.html" />
<link rel=
"next" href=
"node110.html" />
<meta name='aesop' content='information'
/>
<title>4.1.2 Template strings
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"4.1.1 String constants"
href=
"node108.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"4.1 string "
href=
"module-string.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"4.1.3 String functions"
href=
"node110.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"node108.html">4.1.1 String constants
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-string.html">4.1 string
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"node110.html">4.1.3 String functions
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION006120000000000000000">
4.1.2 Template strings
</A>
Templates provide simpler string substitutions as described in
<a class=
"rfc" id='rfcref-
86823' xml:id='rfcref-
86823'
href=
"http://www.python.org/peps/pep-0292.html">PEP
292</a>.
Instead of the normal
"<tt class="samp
">%</tt>"-based substitutions, Templates support
"<tt class="samp
">$</tt>"-based substitutions, using the following rules:
<LI>"<tt class="samp
">$$</tt>" is an escape; it is replaced with a single
"<tt class="samp
">$</tt>".
<LI>"<tt class="samp
">$identifier</tt>" names a substitution placeholder matching a mapping
key of
"identifier". By default,
"identifier" must spell a Python
identifier. The first non-identifier character after the
"<tt class="samp
">$</tt>" character terminates this placeholder specification.
<LI>"<tt class="samp
">${identifier}</tt>" is equivalent to
"<tt class="samp
">$identifier</tt>". It is
required when valid identifier characters follow the placeholder but are
not part of the placeholder, such as
"${noun}ification".
Any other appearance of
"<tt class="samp
">$</tt>" in the string will result in a
<tt class=
"exception">ValueError
</tt> being raised.
<span class=
"versionnote">New in version
2.4.
</span>
The
<tt class=
"module">string
</tt> module provides a
<tt class=
"class">Template
</tt> class that implements
these rules. The methods of
<tt class=
"class">Template
</tt> are:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
830' xml:id='l2h-
830'
class=
"class">Template
</tt></b>(
</nobr></td>
<td><var>template
</var>)
</td></tr></table></dt>
The constructor takes a single argument which is the template string.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
831' xml:id='l2h-
831'
class=
"method">substitute
</tt></b>(
</nobr></td>
<td><var>mapping
</var><big>[
</big><var>, **kws
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Performs the template substitution, returning a new string.
<var>mapping
</var> 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
</var> and
<var>kws
</var> are
given and there are duplicates, the placeholders from
<var>kws
</var> take
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
832' xml:id='l2h-
832'
class=
"method">safe_substitute
</tt></b>(
</nobr></td>
<td><var>mapping
</var><big>[
</big><var>, **kws
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Like
<tt class=
"method">substitute()
</tt>, except that if placeholders are missing from
<var>mapping
</var> and
<var>kws
</var>, instead of raising a
<tt class=
"exception">KeyError
</tt>
exception, the original placeholder will appear in the resulting string
intact. Also, unlike with
<tt class=
"method">substitute()
</tt>, any other appearances of the
"<tt class="samp
">$</tt>" will simply return
"<tt class="samp
">$</tt>" instead of raising
<tt class=
"exception">ValueError
</tt>.
While other exceptions may still occur, this method is called ``safe'' because
substitutions always tries to return a usable string instead of raising an
exception. In another sense,
<tt class=
"method">safe_substitute()
</tt> may be anything other
than safe, since it will silently ignore malformed templates containing
dangling delimiters, unmatched braces, or placeholders that are not valid
<tt class=
"class">Template
</tt> instances also provide one public data attribute:
<dl><dt><b><tt id='l2h-
833' xml:id='l2h-
833'
class=
"member">template
</tt></b></dt>
This is the object passed to the constructor's
<var>template
</var> argument. In
general, you shouldn't change it, but read-only access is not enforced.
Here is an example of how to use a Template:
<div class=
"verbatim"><pre>
>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
>>> d = dict(who='tim')
>>> Template('Give $who $
100').substitute(d)
Traceback (most recent call last):
ValueError: Invalid placeholder in string: line
1, col
10>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
>>> Template('$who likes $what').safe_substitute(d)
Advanced usage: you can derive subclasses of
<tt class=
"class">Template
</tt> 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
<LI><var>delimiter
</var> - This is the literal string describing a placeholder
introducing delimiter. The default value
"<tt class="samp
">$</tt>". Note that this
should
<em>not
</em> be a regular expression, as the implementation will
call
<tt class=
"method">re.escape()
</tt> on this string as needed.
<LI><var>idpattern
</var> - 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
"<tt class="samp
">[_a-z][_a-z0-9]*</tt>".
Alternatively, you can provide the entire regular expression pattern by
overriding the class attribute
<var>pattern
</var>. 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
<LI><var>escaped
</var> - This group matches the escape sequence,
e.g.
"<tt class="samp
">$$</tt>", in the default pattern.
<LI><var>named
</var> - This group matches the unbraced placeholder name; it
should not include the delimiter in capturing group.
<LI><var>braced
</var> - This group matches the brace enclosed placeholder name;
it should not include either the delimiter or braces in the capturing
<LI><var>invalid
</var> - This group matches any other delimiter pattern (usually
a single delimiter), and it should appear last in the regular
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"4.1.1 String constants"
href=
"node108.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"4.1 string "
href=
"module-string.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"4.1.3 String functions"
href=
"node110.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"node108.html">4.1.1 String constants
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-string.html">4.1 string
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"node110.html">4.1.3 String functions
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob