<!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>textwrap – Formatting text paragraphs — 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="Data Types" href="../data_types.html" />
<link rel="prev" title="struct – Working with Binary Data" href="../struct/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="../data_types.html" title="Data Types"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../struct/index.html" title="struct – Working with Binary Data"
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="#">textwrap – Formatting text paragraphs</a><ul>
<li><a class="reference internal" href="#example-data">Example Data</a></li>
<li><a class="reference internal" href="#filling-paragraphs">Filling Paragraphs</a></li>
<li><a class="reference internal" href="#removing-existing-indentation">Removing Existing Indentation</a></li>
<li><a class="reference internal" href="#combining-dedent-and-fill">Combining Dedent and Fill</a></li>
<li><a class="reference internal" href="#hanging-indents">Hanging Indents</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../struct/index.html"
title="previous chapter">struct – Working with Binary Data</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../data_types.html"
title="next chapter">Data Types</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/textwrap/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-textwrap">
<span id="textwrap-formatting-text-paragraphs"></span><h1>textwrap – Formatting text paragraphs<a class="headerlink" href="#module-textwrap" 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">Formatting text by adjusting where line breaks occur in a paragraph.</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-textwrap" title="textwrap: Formatting text by adjusting where line breaks occur in a paragraph."><tt class="xref py py-mod docutils literal"><span class="pre">textwrap</span></tt></a> module can be used to format text for output in
situations where pretty-printing is desired. It offers programmatic
functionality similar to the paragraph wrapping or filling features
found in many text editors.</p>
<div class="section" id="example-data">
<h2>Example Data<a class="headerlink" href="#example-data" title="Permalink to this headline">¶</a></h2>
<p>The examples below use <tt class="docutils literal"><span class="pre">textwrap_example.py</span></tt>, which contains a
string <tt class="docutils literal"><span class="pre">sample_text</span></tt>:</p>
<pre class="literal-block">
sample_text = ‘’’
The textwrap module can be used to format text for output in situations
where pretty-printing is desired. It offers programmatic functionality similar
to the paragraph wrapping or filling features found in many text editors.
‘’’
</pre>
</div>
<div class="section" id="filling-paragraphs">
<h2>Filling Paragraphs<a class="headerlink" href="#filling-paragraphs" title="Permalink to this headline">¶</a></h2>
<p>The <tt class="xref py py-func docutils literal"><span class="pre">fill()</span></tt> convenience function takes text as input and
produces formatted text as output. Let’s see what it does with the
sample_text provided.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">textwrap</span>
<span class="kn">from</span> <span class="nn">textwrap_example</span> <span class="kn">import</span> <span class="n">sample_text</span>
<span class="k">print</span> <span class="s">'No dedent:</span><span class="se">\n</span><span class="s">'</span>
<span class="k">print</span> <span class="n">textwrap</span><span class="o">.</span><span class="n">fill</span><span class="p">(</span><span class="n">sample_text</span><span class="p">)</span>
</pre></div>
</div>
<p>The results are something less than what we want:</p>
<div class="highlight-python"><pre>$ python textwrap_fill.py
No dedent:
The textwrap module can be used to format text for output in
situations where pretty-printing is desired. It offers
programmatic functionality similar to the paragraph wrapping
or filling features found in many text editors.</pre>
</div>
</div>
<div class="section" id="removing-existing-indentation">
<h2>Removing Existing Indentation<a class="headerlink" href="#removing-existing-indentation" title="Permalink to this headline">¶</a></h2>
<p>Notice the embedded tabs and extra spaces mixed into the middle of the
output. It looks pretty rough. We can do better if we start by
removing any common whitespace prefix from all of the lines in the
sample text. This allows us to use docstrings or embedded multi-line
strings straight from our Python code while removing the formatting of
the code itself. The sample string has an artificial indent level
introduced for illustrating this feature.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">textwrap</span>
<span class="kn">from</span> <span class="nn">textwrap_example</span> <span class="kn">import</span> <span class="n">sample_text</span>
<span class="n">dedented_text</span> <span class="o">=</span> <span class="n">textwrap</span><span class="o">.</span><span class="n">dedent</span><span class="p">(</span><span class="n">sample_text</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'Dedented:</span><span class="se">\n</span><span class="s">'</span>
<span class="k">print</span> <span class="n">dedented_text</span>
</pre></div>
</div>
<p>The results are starting to look better:</p>
<div class="highlight-python"><pre>$ python textwrap_dedent.py
Dedented:
The textwrap module can be used to format text for output in situations
where pretty-printing is desired. It offers programmatic functionality similar
to the paragraph wrapping or filling features found in many text editors.</pre>
</div>
<p>Since “dedent” is the opposite of “indent”, the result is a block of
text with the common initial whitespace from each line removed. If one
line is already indented more than another, some of the whitespace
will not be removed.</p>
<div class="highlight-python"><pre> One tab.
Two tabs.
One tab.</pre>
</div>
<p>becomes</p>
<div class="highlight-python"><pre>One tab.
Two tabs.
One tab.</pre>
</div>
</div>
<div class="section" id="combining-dedent-and-fill">
<h2>Combining Dedent and Fill<a class="headerlink" href="#combining-dedent-and-fill" title="Permalink to this headline">¶</a></h2>
<p>Next, let’s see what happens if we take the dedented text and pass it
through <tt class="xref py py-func docutils literal"><span class="pre">fill()</span></tt> with a few different <em>width</em> values.</p>
<pre class="literal-block">
import textwrap
from textwrap_example import sample_text
dedented_text = textwrap.dedent(sample_text).strip()
for width in [ 20, 60, 80 ]:
print
print ‘%d Columns:\n’ % width
print textwrap.fill(dedented_text, width=width)
</pre>
<p>This gives several sets of output in the specified widths:</p>
<div class="highlight-python"><pre>$ python textwrap_fill_width.py
20 Columns:
The textwrap module
can be used to
format text for
output in situations
where pretty-
printing is desired.
It offers
programmatic
functionality
similar to the
paragraph wrapping
or filling features
found in many text
editors.
60 Columns:
The textwrap module can be used to format text for output in
situations where pretty-printing is desired. It offers
programmatic functionality similar to the paragraph wrapping
or filling features found in many text editors.
80 Columns:
The textwrap module can be used to format text for output in situations where
pretty-printing is desired. It offers programmatic functionality similar to the
paragraph wrapping or filling features found in many text editors.</pre>
</div>
</div>
<div class="section" id="hanging-indents">
<h2>Hanging Indents<a class="headerlink" href="#hanging-indents" title="Permalink to this headline">¶</a></h2>
<p>Besides the width of the output, you can control the indent of the
first line independently of subsequent lines.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">textwrap</span>
<span class="kn">from</span> <span class="nn">textwrap_example</span> <span class="kn">import</span> <span class="n">sample_text</span>
<span class="n">dedented_text</span> <span class="o">=</span> <span class="n">textwrap</span><span class="o">.</span><span class="n">dedent</span><span class="p">(</span><span class="n">sample_text</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
<span class="k">print</span> <span class="n">textwrap</span><span class="o">.</span><span class="n">fill</span><span class="p">(</span><span class="n">dedented_text</span><span class="p">,</span> <span class="n">initial_indent</span><span class="o">=</span><span class="s">''</span><span class="p">,</span> <span class="n">subsequent_indent</span><span class="o">=</span><span class="s">' '</span><span class="p">)</span>
</pre></div>
</div>
<p>This makes it relatively easy to produce a hanging indent, where the
first line is indented less than the other lines.</p>
<div class="highlight-python"><pre>$ python textwrap_hanging_indent.py
The textwrap module can be used to format text for output in
situations where pretty-printing is desired. It offers
programmatic functionality similar to the paragraph wrapping or
filling features found in many text editors.</pre>
</div>
<p>The indent values can include non-whitespace characters, too, so the
hanging indent can be prefixed with <tt class="docutils literal"><span class="pre">*</span></tt> to produce bullet points,
etc. That came in handy when I converted my old zwiki content so I
could import it into trac. I used the StructuredText package from Zope
to parse the zwiki data, then created a formatter to produce trac’s
wiki markup as output. Using <a class="reference internal" href="#module-textwrap" title="textwrap: Formatting text by adjusting where line breaks occur in a paragraph."><tt class="xref py py-mod docutils literal"><span class="pre">textwrap</span></tt></a>, I was able to format the
output pages so almost no manual tweaking was needed after the
conversion.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://docs.python.org/lib/module-textwrap.html">textwrap</a></dt>
<dd>Standard library documentation for this module.</dd>
<dt><a class="reference internal" href="../articles/text_processing.html#article-text-processing"><em>Text Processing Tools</em></a></dt>
<dd>More tools for working with text.</dd>
</dl>
</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="../data_types.html" title="Data Types"
>next</a> |</li>
<li class="right" >
<a href="../struct/index.html" title="struct – Working with Binary Data"
>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>