\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.  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, width=70, **kwargs}
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.
\end{funcdesc}

\begin{funcdesc}{fill}{text, width=70, **kwargs}
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.

% XXX how to typeset long argument lists? this just spills off
% the edge of the page, with or without \\ delimiters
\begin{classdesc}{TextWrapper}{width=70, \\
                               initial_indent="", \\
                               subsequent_indent="", \\
                               expand_tabs=True, \\
                               replace_whitespace=True, \\
                               fix_sentence_endings=False, \\
                               break_long_words=True}

Each keyword argument to the constructor corresponds to an 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.  The effects of the instance attributes are as
follows:

\begin{memberdesc}[bool]{expand_tabs}
If true (the default), 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}[bool]{replace_whitespace}
If true (the default), each whitespace character (as defined by
\var{string.whitespace}) remaining after tab expansion will be replaced
by a single space.  \note{If \var{expand_tabs} is false and
\var{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}

% XXX how to typeset the empty string? this looks awful, and "" is worse.
\begin{memberdesc}[string]{initial_indent}
(default: '') String that will be prepended to the first line of wrapped
output.  Counts towards the length of the first line.
\end{memberdesc}

\begin{memberdesc}[string]{subsequent_indent}
(default: '') 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}[bool]{fix_sentence_endings}
(default: 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{'}.  One problem with this is algoritm 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}
Furthermore, since it relies on \var{string.lowercase} for the
definition of ``lowercase letter'', it is specific to English-language
texts.  Thus, \var{fix_sentence_endings} is false by default.
\end{memberdesc}

\begin{memberdesc}[bool]{break_long_words}
If true (the default), then words longer than \var{width} will be broken
in order to ensure that no lines are longer than \var{width}.  If it is
false, long words will not be broken, and some lines may be longer than
\var{width}.  (Long words will be put on a line by themselves, in order
to minimize the amount by which \var{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 \var{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}

\end{classdesc}