\section{\module{textwrap} ---
         Text wrapping and filling}

\declaremodule{standard}{textwrap}
\modulesynopsis{Text wrapping and filling}
\moduleauthor{Greg Ward}{gward@python.net}
\sectionauthor{Greg Ward}{gward@python.net}

\versionadded{2.3}

The \module{textwrap} module provides two convenience functions,
\function{wrap()} and \function{fill()}, as well as
\class{TextWrapper}, the class that does all the work, and a utility function 
\function{dedent()}.  If you're just wrapping or filling one or two 
text strings, the convenience functions should be good enough; otherwise, 
you should use an instance of \class{TextWrapper} for efficiency.

\begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}}
Wraps the single paragraph in \var{text} (a string) so every line is at
most \var{width} characters long.  Returns a list of output lines,
without final newlines.

Optional keyword arguments correspond to the instance attributes of
\class{TextWrapper}, documented below.  \var{width} defaults to
\code{70}.
\end{funcdesc}

\begin{funcdesc}{fill}{text\optional{, width\optional{, \moreargs}}}
Wraps the single paragraph in \var{text}, and returns a single string
containing the wrapped paragraph.  \function{fill()} is shorthand for
\begin{verbatim}
"\n".join(wrap(text, ...))
\end{verbatim}

In particular, \function{fill()} accepts exactly the same keyword
arguments as \function{wrap()}.
\end{funcdesc}

Both \function{wrap()} and \function{fill()} work by creating a
\class{TextWrapper} instance and calling a single method on it.  That
instance is not reused, so for applications that wrap/fill many text
strings, it will be more efficient for you to create your own
\class{TextWrapper} object.

An additional utility function, \function{dedent()}, is provided to
remove indentation from strings that have unwanted whitespace to the
left of the text.

\begin{funcdesc}{dedent}{text} 
Remove any whitespace that can be uniformly removed from the left
of every line in \var{text}.

This is typically used to make triple-quoted strings line up with
the left edge of screen/whatever, while still presenting it in the
source code in indented form. 

For example:
\begin{verbatim}
def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print repr(s)          # prints '    hello\n      world\n    '
    print repr(dedent(s))  # prints 'hello\n  world\n'
\end{verbatim}
\end{funcdesc}

\begin{classdesc}{TextWrapper}{...}
The \class{TextWrapper} constructor accepts a number of optional
keyword arguments.  Each argument corresponds to one instance attribute,
so for example
\begin{verbatim}
wrapper = TextWrapper(initial_indent="* ")
\end{verbatim}
is the same as
\begin{verbatim}
wrapper = TextWrapper()
wrapper.initial_indent = "* "
\end{verbatim}

You can re-use the same \class{TextWrapper} object many times, and you
can change any of its options through direct assignment to instance
attributes between uses.
\end{classdesc}

The \class{TextWrapper} instance attributes (and keyword arguments to
the constructor) are as follows:

\begin{memberdesc}{width}
(default: \code{70}) The maximum length of wrapped lines.  As long as
there are no individual words in the input text longer than
\member{width}, \class{TextWrapper} guarantees that no output line
will be longer than \member{width} characters.
\end{memberdesc}

\begin{memberdesc}{expand_tabs}
(default: \code{True}) If true, then all tab characters in \var{text}
will be expanded to spaces using the \method{expand_tabs()} method of
\var{text}.
\end{memberdesc}

\begin{memberdesc}{replace_whitespace}
(default: \code{True}) If true, each whitespace character (as defined
by \code{string.whitespace}) remaining after tab expansion will be
replaced by a single space.  \note{If \member{expand_tabs} is false
and \member{replace_whitespace} is true, each tab character will be
replaced by a single space, which is \emph{not} the same as tab
expansion.}
\end{memberdesc}

\begin{memberdesc}{initial_indent}
(default: \code{''}) String that will be prepended to the first line
of wrapped output.  Counts towards the length of the first line.
\end{memberdesc}

\begin{memberdesc}{subsequent_indent}
(default: \code{''}) String that will be prepended to all lines of
wrapped output except the first.  Counts towards the length of each
line except the first.
\end{memberdesc}

\begin{memberdesc}{fix_sentence_endings}
(default: \code{False}) If true, \class{TextWrapper} attempts to detect
sentence endings and ensure that sentences are always separated by
exactly two spaces.  This is generally desired for text in a monospaced
font.  However, the sentence detection algorithm is imperfect: it
assumes that a sentence ending consists of a lowercase letter followed
by one of \character{.},
\character{!}, or \character{?}, possibly followed by one of
\character{"} or \character{'}, followed by a space.  One problem
with this is algorithm is that it is unable to detect the difference
between ``Dr.'' in

\begin{verbatim}
[...] Dr. Frankenstein's monster [...]
\end{verbatim}

and ``Spot.'' in

\begin{verbatim}
[...] See Spot. See Spot run [...]
\end{verbatim}

\member{fix_sentence_endings} is false by default.

Since the sentence detection algorithm relies on
\code{string.lowercase} for the definition of ``lowercase letter,''
and a convention of using two spaces after a period to separate
sentences on the same line, it is specific to English-language texts.
\end{memberdesc}

\begin{memberdesc}{break_long_words}
(default: \code{True}) If true, then words longer than
\member{width} will be broken in order to ensure that no lines are
longer than \member{width}.  If it is false, long words will not be
broken, and some lines may be longer than \member{width}.  (Long words
will be put on a line by themselves, in order to minimize the amount
by which \member{width} is exceeded.)
\end{memberdesc}

\class{TextWrapper} also provides two public methods, analogous to the
module-level convenience functions:

\begin{methoddesc}{wrap}{text}
Wraps the single paragraph in \var{text} (a string) so every line is
at most \member{width} characters long.  All wrapping options are
taken from instance attributes of the \class{TextWrapper} instance.
Returns a list of output lines, without final newlines.
\end{methoddesc}

\begin{methoddesc}{fill}{text}
Wraps the single paragraph in \var{text}, and returns a single string
containing the wrapped paragraph.
\end{methoddesc}