<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>string – Working with text — Python Module of the Week</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.132',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="top" title="Python Module of the Week" href="../index.html" />
<link rel="up" title="String Services" href="../string_services.html" />
<link rel="next" title="StringIO and cStringIO – Work with text buffers using file-like API" href="../StringIO/index.html" />
<link rel="prev" title="difflib – Compare sequences" href="../difflib/index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../StringIO/index.html" title="StringIO and cStringIO – Work with text buffers using file-like API"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../difflib/index.html" title="difflib – Compare sequences"
accesskey="P">previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../string_services.html" accesskey="U">String Services</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">string – Working with text</a><ul>
<li><a class="reference internal" href="#constants">Constants</a></li>
<li><a class="reference internal" href="#functions">Functions</a></li>
<li><a class="reference internal" href="#templates">Templates</a></li>
<li><a class="reference internal" href="#advanced-templates">Advanced Templates</a></li>
<li><a class="reference internal" href="#deprecated-functions">Deprecated Functions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../difflib/index.html"
title="previous chapter">difflib – Compare sequences</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../StringIO/index.html"
title="next chapter">StringIO and cStringIO – Work with text buffers using file-like API</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/string/index.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-string">
<span id="string-working-with-text"></span><h1>string – Working with text<a class="headerlink" href="#module-string" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Purpose:</th><td class="field-body">Contains constants and classes for working with text.</td>
</tr>
<tr class="field"><th class="field-name">Python Version:</th><td class="field-body">2.5</td>
</tr>
</tbody>
</table>
<p>The <a class="reference internal" href="#module-string" title="string: Contains constants and classes for working with text."><tt class="xref py py-mod docutils literal"><span class="pre">string</span></tt></a> module dates from the earliest versions of
Python. In version 2.0, many of the functions previously implemented
only in the module were moved to methods of <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> and
<tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> objects. Legacy versions of those functions are still
available, but their use is deprecated and they will be dropped in
Python 3.0. The <a class="reference internal" href="#module-string" title="string: Contains constants and classes for working with text."><tt class="xref py py-mod docutils literal"><span class="pre">string</span></tt></a> module still contains several useful
constants and classes for working with string and unicode objects, and
this discussion will concentrate on them.</p>
<div class="section" id="constants">
<h2>Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h2>
<p>The constants in the string module can be used to specify categories
of characters such as <tt class="docutils literal"><span class="pre">ascii_letters</span></tt> and <tt class="docutils literal"><span class="pre">digits</span></tt>. Some of the
constants, such as <tt class="docutils literal"><span class="pre">lowercase</span></tt>, are locale-dependent so the value
changes to reflect the language settings of the user. Others, such as
<tt class="docutils literal"><span class="pre">hexdigits</span></tt>, do not change when the locale changes.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">dir</span><span class="p">(</span><span class="n">string</span><span class="p">):</span>
<span class="k">if</span> <span class="n">n</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">'_'</span><span class="p">):</span>
<span class="k">continue</span>
<span class="n">v</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">string</span><span class="p">,</span> <span class="n">n</span><span class="p">)</span>
<span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="nb">basestring</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">=</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">v</span><span class="p">))</span>
<span class="k">print</span>
</pre></div>
</div>
<p>Most of the names for the constants are self-explanatory.</p>
<div class="highlight-python"><pre>$ python string_constants.py
ascii_letters='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
ascii_lowercase='abcdefghijklmnopqrstuvwxyz'
ascii_uppercase='ABCDEFGHIJKLMNOPQRSTUVWXYZ'
digits='0123456789'
hexdigits='0123456789abcdefABCDEF'
letters='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
lowercase='abcdefghijklmnopqrstuvwxyz'
octdigits='01234567'
printable='0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ \t\n\r\x0b\x0c'
punctuation='!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'
uppercase='ABCDEFGHIJKLMNOPQRSTUVWXYZ'
whitespace='\t\n\x0b\x0c\r '</pre>
</div>
</div>
<div class="section" id="functions">
<h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2>
<p>There are two functions not moving from the string
module. <tt class="xref py py-func docutils literal"><span class="pre">capwords()</span></tt> capitalizes all of the words in a string.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="n">s</span> <span class="o">=</span> <span class="s">'The quick brown fox jumped over the lazy dog.'</span>
<span class="k">print</span> <span class="n">s</span>
<span class="k">print</span> <span class="n">string</span><span class="o">.</span><span class="n">capwords</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
</pre></div>
</div>
<p>The results are the same as if you called <tt class="xref py py-func docutils literal"><span class="pre">split()</span></tt>, capitalized
the words in the resulting list, then called <tt class="xref py py-func docutils literal"><span class="pre">join()</span></tt> to combine
the results.</p>
<div class="highlight-python"><pre>$ python string_capwords.py
The quick brown fox jumped over the lazy dog.
The Quick Brown Fox Jumped Over The Lazy Dog.</pre>
</div>
<p>The other function creates translation tables that can be used with
the <tt class="xref py py-func docutils literal"><span class="pre">translate()</span></tt> method to change one set of characters to
another.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="n">leet</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">maketrans</span><span class="p">(</span><span class="s">'abegiloprstz'</span><span class="p">,</span> <span class="s">'463611092572'</span><span class="p">)</span>
<span class="n">s</span> <span class="o">=</span> <span class="s">'The quick brown fox jumped over the lazy dog.'</span>
<span class="k">print</span> <span class="n">s</span>
<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">translate</span><span class="p">(</span><span class="n">leet</span><span class="p">)</span>
</pre></div>
</div>
<p>In this example, some letters are replaced by their <a class="reference external" href="http://en.wikipedia.org/wiki/Leet">l33t</a> number alternatives.</p>
<div class="highlight-python"><pre>$ python string_maketrans.py
The quick brown fox jumped over the lazy dog.
Th3 qu1ck 620wn f0x jum93d 0v32 7h3 142y d06.</pre>
</div>
</div>
<div class="section" id="templates">
<h2>Templates<a class="headerlink" href="#templates" title="Permalink to this headline">¶</a></h2>
<p>String templates were added in Python 2.4 as part of <span class="target" id="index-0"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0292"><strong>PEP 292</strong></a> and
are intended as an alternative to the built-in interpolation
syntax. With <tt class="xref py py-class docutils literal"><span class="pre">string.Template</span></tt> interpolation, variables are
identified by name prefixed with <tt class="docutils literal"><span class="pre">$</span></tt> (e.g., <tt class="docutils literal"><span class="pre">$var</span></tt>) or, if
necessary to set them off from surrounding text, they can also be
wrapped with curly braces (e.g., <tt class="docutils literal"><span class="pre">${var}</span></tt>).</p>
<p>This example compares a simple template with a similar string
interpolation setup.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="n">values</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'var'</span><span class="p">:</span><span class="s">'foo'</span> <span class="p">}</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">Template</span><span class="p">(</span><span class="s">"""</span>
<span class="s">$var</span>
<span class="s">$$</span>
<span class="s">${var}iable</span>
<span class="s">"""</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'TEMPLATE:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">substitute</span><span class="p">(</span><span class="n">values</span><span class="p">)</span>
<span class="n">s</span> <span class="o">=</span> <span class="s">"""</span>
<span class="si">%(var)s</span><span class="s"></span>
<span class="si">%%</span><span class="s"></span>
<span class="si">%(var)s</span><span class="s">iable</span>
<span class="s">"""</span>
<span class="k">print</span> <span class="s">'INTERPLOATION:'</span><span class="p">,</span> <span class="n">s</span> <span class="o">%</span> <span class="n">values</span>
</pre></div>
</div>
<p>As you see, in both cases the trigger character (<tt class="docutils literal"><span class="pre">$</span></tt> or <tt class="docutils literal"><span class="pre">%</span></tt>) is
escaped by repeating it twice.</p>
<div class="highlight-python"><pre>$ python string_template.py
TEMPLATE:
foo
$
fooiable
INTERPLOATION:
foo
%
fooiable</pre>
</div>
<p>One key difference between templates and standard string interpolation
is that the type of the arguments is not taken into account. The
values are converted to strings, and the strings are inserted into the
result. No formatting options are available. For example, there is no
way to control the number of digits used to represent a floating point
value.</p>
<p>A benefit, though, is that by using the <tt class="xref py py-func docutils literal"><span class="pre">safe_substitute()</span></tt>
method, it is possible to avoid exceptions if not all of the values
needed by the template are provided as arguments.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="n">values</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'var'</span><span class="p">:</span><span class="s">'foo'</span> <span class="p">}</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">Template</span><span class="p">(</span><span class="s">"$var is here but $missing is not provided"</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'TEMPLATE:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">substitute</span><span class="p">(</span><span class="n">values</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">KeyError</span><span class="p">,</span> <span class="n">err</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'ERROR:'</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">err</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'TEMPLATE:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">safe_substitute</span><span class="p">(</span><span class="n">values</span><span class="p">)</span>
</pre></div>
</div>
<p>Since there is no value for missing in the values dictionary, a
<a class="reference internal" href="../exceptions/index.html#exceptions-keyerror"><em>KeyError</em></a> is raised by
<tt class="xref py py-func docutils literal"><span class="pre">substitute()</span></tt>. Instead of raising the error,
<tt class="xref py py-func docutils literal"><span class="pre">safe_substitute()</span></tt> catches it and leaves the variable
expression alone in the text.</p>
<div class="highlight-python"><pre>$ python string_template_missing.py
TEMPLATE: ERROR: 'missing'
TEMPLATE: foo is here but $missing is not provided</pre>
</div>
</div>
<div class="section" id="advanced-templates">
<h2>Advanced Templates<a class="headerlink" href="#advanced-templates" title="Permalink to this headline">¶</a></h2>
<p>If the default syntax for <tt class="xref py py-class docutils literal"><span class="pre">string.Template</span></tt> is not to your
liking, you can change the behavior by adjusting the regular
expression patterns it uses to find the variable names in the template
body. A simple way to do that is to change the <em>delimiter</em> and
<em>idpattern</em> class attributes.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="k">class</span> <span class="nc">MyTemplate</span><span class="p">(</span><span class="n">string</span><span class="o">.</span><span class="n">Template</span><span class="p">):</span>
<span class="n">delimiter</span> <span class="o">=</span> <span class="s">'%'</span>
<span class="n">idpattern</span> <span class="o">=</span> <span class="s">'[a-z]+_[a-z]+'</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">MyTemplate</span><span class="p">(</span><span class="s">'</span><span class="si">%%</span><span class="s"> %with_underscore %notunderscored'</span><span class="p">)</span>
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'with_underscore'</span><span class="p">:</span><span class="s">'replaced'</span><span class="p">,</span>
<span class="s">'notunderscored'</span><span class="p">:</span><span class="s">'not replaced'</span><span class="p">,</span>
<span class="p">}</span>
<span class="k">print</span> <span class="n">t</span><span class="o">.</span><span class="n">safe_substitute</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
</pre></div>
</div>
<p>In this example, variable ids must include an underscore somewhere in
the middle, so <tt class="docutils literal"><span class="pre">%notunderscored</span></tt> is not replaced by anything.</p>
<div class="highlight-python"><pre>$ python string_template_advanced.py
% replaced %notunderscored</pre>
</div>
<p>For more complex changes, you can override the <em>pattern</em> attribute and
define an entirely new regular expression. The pattern provided must
contain four named groups for capturing the escaped delimiter, the
named variable, a braced version of the variable name, and invalid
delimiter patterns.</p>
<p>Let’s look at the default pattern:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">string</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">string</span><span class="o">.</span><span class="n">Template</span><span class="p">(</span><span class="s">'$var'</span><span class="p">)</span>
<span class="k">print</span> <span class="n">t</span><span class="o">.</span><span class="n">pattern</span><span class="o">.</span><span class="n">pattern</span>
</pre></div>
</div>
<p>Since <tt class="docutils literal"><span class="pre">t.pattern</span></tt> is a compiled regular expression, we have to
access its pattern attribute to see the actual string.</p>
<div class="highlight-python"><pre>$ python string_template_defaultpattern.py
\$(?:
(?P<escaped>\$) | # Escape sequence of two delimiters
(?P<named>[_a-z][_a-z0-9]*) | # delimiter and a Python identifier
{(?P<braced>[_a-z][_a-z0-9]*)} | # delimiter and a braced identifier
(?P<invalid>) # Other ill-formed delimiter exprs
)</pre>
</div>
<p>If we wanted to create a new type of template using, for example,
<tt class="docutils literal"><span class="pre">{{var}}</span></tt> as the variable syntax, we could use a pattern like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">re</span>
<span class="kn">import</span> <span class="nn">string</span>
<span class="k">class</span> <span class="nc">MyTemplate</span><span class="p">(</span><span class="n">string</span><span class="o">.</span><span class="n">Template</span><span class="p">):</span>
<span class="n">delimiter</span> <span class="o">=</span> <span class="s">'{{'</span>
<span class="n">pattern</span> <span class="o">=</span> <span class="s">r'''</span>
<span class="s"> \{\{(?:</span>
<span class="s"> (?P<escaped>\{\{)|</span>
<span class="s"> (?P<named>[_a-z][_a-z0-9]*)\}\}|</span>
<span class="s"> (?P<braced>[_a-z][_a-z0-9]*)\}\}|</span>
<span class="s"> (?P<invalid>)</span>
<span class="s"> )</span>
<span class="s"> '''</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">MyTemplate</span><span class="p">(</span><span class="s">'''</span>
<span class="s">{{{{</span>
<span class="s">{{var}}</span>
<span class="s">'''</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'MATCHES:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">pattern</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">template</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'SUBSTITUTED:'</span><span class="p">,</span> <span class="n">t</span><span class="o">.</span><span class="n">safe_substitute</span><span class="p">(</span><span class="n">var</span><span class="o">=</span><span class="s">'replacement'</span><span class="p">)</span>
</pre></div>
</div>
<p>We still have to provide both the named and braced patterns, even
though they are the same. Here’s the output:</p>
<div class="highlight-python"><pre>$ python string_template_newsyntax.py
MATCHES: [('{{', '', '', ''), ('', 'var', '', '')]
SUBSTITUTED:
{{
replacement</pre>
</div>
</div>
<div class="section" id="deprecated-functions">
<h2>Deprecated Functions<a class="headerlink" href="#deprecated-functions" title="Permalink to this headline">¶</a></h2>
<p>For information on the deprecated functions moved to the string and
unicode classes, refer to <a class="reference external" href="http://docs.python.org/lib/string-methods.html#string-methods">String Methods</a> in
the manual.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="docutils">
<dt><a class="reference external" href="http://docs.python.org/lib/module-string.html">string</a></dt>
<dd>Standard library documentation for this module.</dd>
<dt><span class="target" id="index-1"></span><a class="pep reference external" href="http://www.python.org/dev/peps/pep-0292"><strong>PEP 292</strong></a></dt>
<dd>Simpler String Substitutions</dd>
</dl>
<p class="last"><a class="reference internal" href="../articles/text_processing.html#article-text-processing"><em>Text Processing Tools</em></a></p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../StringIO/index.html" title="StringIO and cStringIO – Work with text buffers using file-like API"
>next</a> |</li>
<li class="right" >
<a href="../difflib/index.html" title="difflib – Compare sequences"
>previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../string_services.html" >String Services</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Doug Hellmann.
Last updated on Oct 24, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br/><a href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/" rel="license"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png"/></a>
</div>
</body>
</html>