======================================
textwrap -- Formatting text paragraphs
======================================
.. module:: textwrap
:synopsis: Formatting text by adjusting where line breaks occur in a paragraph.
:Purpose: Formatting text by adjusting where line breaks occur in a paragraph.
:Python Version: 2.5
The :mod:`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.
Example Data
============
The examples below use ``textwrap_example.py``, which contains a
string ``sample_text``:
.. include:: textwrap_example.py
:literal:
:start-after: #end_pymotw_header
Filling Paragraphs
==================
The :func:`fill()` convenience function takes text as input and
produces formatted text as output. Let's see what it does with the
sample_text provided.
.. include:: textwrap_fill.py
:literal:
:start-after: #end_pymotw_header
The results are something less than what we want:
.. {{{cog
.. cog.out(run_script(cog.inFile, 'textwrap_fill.py'))
.. }}}
::
$ 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.
.. {{{end}}}
Removing Existing Indentation
=============================
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.
.. include:: textwrap_dedent.py
:literal:
:start-after: #end_pymotw_header
The results are starting to look better:
.. {{{cog
.. cog.out(run_script(cog.inFile, 'textwrap_dedent.py'))
.. }}}
::
$ 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.
.. {{{end}}}
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.
::
One tab.
Two tabs.
One tab.
becomes
::
One tab.
Two tabs.
One tab.
Combining Dedent and Fill
=========================
Next, let's see what happens if we take the dedented text and pass it
through :func:`fill()` with a few different *width* values.
.. include:: textwrap_fill_width.py
:literal:
:start-after: #end_pymotw_header
This gives several sets of output in the specified widths:
.. {{{cog
.. cog.out(run_script(cog.inFile, 'textwrap_fill_width.py'))
.. }}}
::
$ 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.
.. {{{end}}}
Hanging Indents
===============
Besides the width of the output, you can control the indent of the
first line independently of subsequent lines.
.. include:: textwrap_hanging_indent.py
:literal:
:start-after: #end_pymotw_header
This makes it relatively easy to produce a hanging indent, where the
first line is indented less than the other lines.
.. {{{cog
.. cog.out(run_script(cog.inFile, 'textwrap_hanging_indent.py'))
.. }}}
::
$ 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.
.. {{{end}}}
The indent values can include non-whitespace characters, too, so the
hanging indent can be prefixed with ``*`` 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 :mod:`textwrap`, I was able to format the
output pages so almost no manual tweaking was needed after the
conversion.
.. seealso::
`textwrap <http://docs.python.org/lib/module-textwrap.html>`_
Standard library documentation for this module.
:ref:`article-text-processing`
More tools for working with text.