sam-t2/devtools/amd64/html/python/whatsnew/node5.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="whatsnew24.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="whatsnew24.html" title='What's New in Python 2.4' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node6.html" />
<link rel="prev" href="node4.html" />
<link rel="parent" href="whatsnew24.html" />
<link rel="next" href="node6.html" />
<meta name='aesop' content='information' />
<title>4 PEP 292: Simpler String Substitutions</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3 PEP 289: Generator"
  href="node4.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="What's New in Python"
  href="whatsnew24.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="5 PEP 318: Decorators"
  href="node6.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">What's New in Python 2.4</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'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node4.html">3 PEP 289: Generator</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="whatsnew24.html">What's New in Python</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node6.html">5 PEP 318: Decorators</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION000500000000000000000">
4 PEP 292: Simpler String Substitutions</A>
</H1>

<P>
Some new classes in the standard library provide an alternative
mechanism for substituting variables into strings; this style of
substitution may be better for applications where untrained
users need to edit templates.

<P>
The usual way of substituting variables by name is the <code>%</code>
operator:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; '%(page)i: %(title)s' % {'page':2, 'title': 'The Best of Times'}
'2: The Best of Times'
</pre></div>

<P>
When writing the template string, it can be easy to forget the
"<tt class="samp">i</tt>" or "<tt class="samp">s</tt>" after the closing parenthesis.  This isn't a big
problem if the template is in a Python module, because you run the
code, get an ``Unsupported format character'' <tt class="exception">ValueError</tt>,
and fix the problem.  However, consider an application such as Mailman
where template strings or translations are being edited by users who
aren't aware of the Python language.  The format string's syntax is
complicated to explain to such users, and if they make a mistake, it's
difficult to provide helpful feedback to them.

<P>
PEP 292 adds a <tt class="class">Template</tt> class to the <tt class="module">string</tt> module
that uses "<tt class="samp">$</tt>" to indicate a substitution.  <tt class="class">Template</tt> is a
subclass of the built-in Unicode type, so the result is always a
Unicode string:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; import string
&gt;&gt;&gt; t = string.Template('$page: $title')
&gt;&gt;&gt; t.substitute({'page':2, 'title': 'The Best of Times'})
u'2: The Best of Times'
</pre></div>

<P>
If a key is missing from the dictionary, the <tt class="method">substitute</tt> method
will raise a <tt class="exception">KeyError</tt>.  There's also a <tt class="method">safe_substitute</tt>
method that ignores missing keys:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; t = string.SafeTemplate('$page: $title')
&gt;&gt;&gt; t.safe_substitute({'page':3})
u'3: $title'
</pre></div>

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

<dl compact="compact" class="seerfc">
    <dt><a href="http://www.python.org/peps/pep-0292.html"
        title="Simpler String Substitutions"
        >PEP 292, <em>Simpler String Substitutions</em></a>
    <dd>Written and implemented
by Barry Warsaw.
  </dl>
</div>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3 PEP 289: Generator"
  href="node4.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="What's New in Python"
  href="whatsnew24.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="5 PEP 318: Decorators"
  href="node6.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">What's New in Python 2.4</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'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node4.html">3 PEP 289: Generator</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="whatsnew24.html">What's New in Python</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node6.html">5 PEP 318: Decorators</A>
</div>
</div>
<hr />
<span class="release-info">Release 1.01.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>