Doc/lib/libtextwrap.tex

   1 \section{\module{textwrap} ---
   2          Text wrapping and filling}
   3
   4 \declaremodule{standard}{textwrap}
   5 \modulesynopsis{Text wrapping and filling}
   6 \moduleauthor{Greg Ward}{gward@python.net}
   7 \sectionauthor{Greg Ward}{gward@python.net}
   8
   9 \versionadded{2.3}
  10
  11 The \module{textwrap} module provides two convenience functions,
  12 \function{wrap()} and \function{fill()}, as well as
  13 \class{TextWrapper}, the class that does all the work.  If you're just
  14 wrapping or filling one or two text strings, the convenience functions
  15 should be good enough; otherwise, you should use an instance of
  16 \class{TextWrapper} for efficiency.
  17
  18 \begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}}
  19 Wraps the single paragraph in \var{text} (a string) so every line is at
  20 most \var{width} characters long.  Returns a list of output lines,
  21 without final newlines.
  22
  23 Optional keyword arguments correspond to the instance attributes of
  24 \class{TextWrapper}, documented below.  \var{width} defaults to
  25 \code{70}.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{fill}{text\optional{, width\optional{, \moreargs}}}
  29 Wraps the single paragraph in \var{text}, and returns a single string
  30 containing the wrapped paragraph.  \function{fill()} is shorthand for
  31 \begin{verbatim}
  32 "\n".join(wrap(text, ...))
  33 \end{verbatim}
  34
  35 In particular, \function{fill()} accepts exactly the same keyword
  36 arguments as \function{wrap()}.
  37 \end{funcdesc}
  38
  39 Both \function{wrap()} and \function{fill()} work by creating a
  40 \class{TextWrapper} instance and calling a single method on it.  That
  41 instance is not reused, so for applications that wrap/fill many text
  42 strings, it will be more efficient for you to create your own
  43 \class{TextWrapper} object.
  44
  45 \begin{classdesc}{TextWrapper}{...}
  46 The \class{TextWrapper} constructor accepts a number of optional
  47 keyword arguments.  Each argument corresponds to one instance attribute,
  48 so for example
  49 \begin{verbatim}
  50 wrapper = TextWrapper(initial_indent="* ")
  51 \end{verbatim}
  52 is the same as
  53 \begin{verbatim}
  54 wrapper = TextWrapper()
  55 wrapper.initial_indent = "* "
  56 \end{verbatim}
  57
  58 You can re-use the same \class{TextWrapper} object many times, and you
  59 can change any of its options through direct assignment to instance
  60 attributes between uses.
  61 \end{classdesc}
  62
  63 The \class{TextWrapper} instance attributes (and keyword arguments to
  64 the constructor) are as follows:
  65
  66 \begin{memberdesc}{width}
  67 (default: \code{70}) The maximum length of wrapped lines.  As long as
  68 there are no individual words in the input text longer than
  69 \member{width}, \class{TextWrapper} guarantees that no output line
  70 will be longer than \member{width} characters.
  71 \end{memberdesc}
  72
  73 \begin{memberdesc}{expand_tabs}
  74 (default: \code{True}) If true, then all tab characters in \var{text}
  75 will be expanded to spaces using the \method{expand_tabs()} method of
  76 \var{text}.
  77 \end{memberdesc}
  78
  79 \begin{memberdesc}{replace_whitespace}
  80 (default: \code{True}) If true, each whitespace character (as defined
  81 by \code{string.whitespace}) remaining after tab expansion will be
  82 replaced by a single space.  \note{If \member{expand_tabs} is false
  83 and \member{replace_whitespace} is true, each tab character will be
  84 replaced by a single space, which is \emph{not} the same as tab
  85 expansion.}
  86 \end{memberdesc}
  87
  88 \begin{memberdesc}{initial_indent}
  89 (default: \code{''}) String that will be prepended to the first line
  90 of wrapped output.  Counts towards the length of the first line.
  91 \end{memberdesc}
  92
  93 \begin{memberdesc}{subsequent_indent}
  94 (default: \code{''}) String that will be prepended to all lines of
  95 wrapped output except the first.  Counts towards the length of each
  96 line except the first.
  97 \end{memberdesc}
  98
  99 \begin{memberdesc}{fix_sentence_endings}
 100 (default: \code{False}) If true, \class{TextWrapper} attempts to detect
 101 sentence endings and ensure that sentences are always separated by
 102 exactly two spaces.  This is generally desired for text in a monospaced
 103 font.  However, the sentence detection algorithm is imperfect: it
 104 assumes that a sentence ending consists of a lowercase letter followed
 105 by one of \character{.},
 106 \character{!}, or \character{?}, possibly followed by one of
 107 \character{"} or \character{'}, followed by a space.  One problem
 108 with this is algorithm is that it is unable to detect the difference
 109 between ``Dr.'' in
 110
 111 \begin{verbatim}
 112 [...] Dr. Frankenstein's monster [...]
 113 \end{verbatim}
 114
 115 and ``Spot.'' in
 116
 117 \begin{verbatim}
 118 [...] See Spot. See Spot run [...]
 119 \end{verbatim}
 120
 121 \member{fix_sentence_endings} is false by default.
 122
 123 Since the sentence detection algorithm relies on
 124 \code{string.lowercase} for the definition of ``lowercase letter,''
 125 and a convention of using two spaces after a period to separate
 126 sentences on the same line, it is specific to English-language texts.
 127 \end{memberdesc}
 128
 129 \begin{memberdesc}{break_long_words}
 130 (default: \code{True}) If true, then words longer than
 131 \member{width} will be broken in order to ensure that no lines are
 132 longer than \member{width}.  If it is false, long words will not be
 133 broken, and some lines may be longer than \member{width}.  (Long words
 134 will be put on a line by themselves, in order to minimize the amount
 135 by which \member{width} is exceeded.)
 136 \end{memberdesc}
 137
 138 \class{TextWrapper} also provides two public methods, analogous to the
 139 module-level convenience functions:
 140
 141 \begin{methoddesc}{wrap}{text}
 142 Wraps the single paragraph in \var{text} (a string) so every line is
 143 at most \member{width} characters long.  All wrapping options are
 144 taken from instance attributes of the \class{TextWrapper} instance.
 145 Returns a list of output lines, without final newlines.
 146 \end{methoddesc}
 147
 148 \begin{methoddesc}{fill}{text}
 149 Wraps the single paragraph in \var{text}, and returns a single string
 150 containing the wrapped paragraph.
 151 \end{methoddesc}