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, and a utility function
  14 \function{dedent()}.  If you're just wrapping or filling one or two
  15 text strings, the convenience functions should be good enough; otherwise,
  16 you should use an instance of \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 An additional utility function, \function{dedent()}, is provided to
  46 remove indentation from strings that have unwanted whitespace to the
  47 left of the text.
  48
  49 \begin{funcdesc}{dedent}{text}
  50 Remove any whitespace that can be uniformly removed from the left
  51 of every line in \var{text}.
  52
  53 This is typically used to make triple-quoted strings line up with
  54 the left edge of screen/whatever, while still presenting it in the
  55 source code in indented form.
  56
  57 For example:
  58 \begin{verbatim}
  59 def test():
  60     # end first line with \ to avoid the empty line!
  61     s = '''\
  62     hello
  63       world
  64     '''
  65     print repr(s)          # prints '    hello\n      world\n    '
  66     print repr(dedent(s))  # prints 'hello\n  world\n'
  67 \end{verbatim}
  68 \end{funcdesc}
  69
  70 \begin{classdesc}{TextWrapper}{...}
  71 The \class{TextWrapper} constructor accepts a number of optional
  72 keyword arguments.  Each argument corresponds to one instance attribute,
  73 so for example
  74 \begin{verbatim}
  75 wrapper = TextWrapper(initial_indent="* ")
  76 \end{verbatim}
  77 is the same as
  78 \begin{verbatim}
  79 wrapper = TextWrapper()
  80 wrapper.initial_indent = "* "
  81 \end{verbatim}
  82
  83 You can re-use the same \class{TextWrapper} object many times, and you
  84 can change any of its options through direct assignment to instance
  85 attributes between uses.
  86 \end{classdesc}
  87
  88 The \class{TextWrapper} instance attributes (and keyword arguments to
  89 the constructor) are as follows:
  90
  91 \begin{memberdesc}{width}
  92 (default: \code{70}) The maximum length of wrapped lines.  As long as
  93 there are no individual words in the input text longer than
  94 \member{width}, \class{TextWrapper} guarantees that no output line
  95 will be longer than \member{width} characters.
  96 \end{memberdesc}
  97
  98 \begin{memberdesc}{expand_tabs}
  99 (default: \code{True}) If true, then all tab characters in \var{text}
 100 will be expanded to spaces using the \method{expand_tabs()} method of
 101 \var{text}.
 102 \end{memberdesc}
 103
 104 \begin{memberdesc}{replace_whitespace}
 105 (default: \code{True}) If true, each whitespace character (as defined
 106 by \code{string.whitespace}) remaining after tab expansion will be
 107 replaced by a single space.  \note{If \member{expand_tabs} is false
 108 and \member{replace_whitespace} is true, each tab character will be
 109 replaced by a single space, which is \emph{not} the same as tab
 110 expansion.}
 111 \end{memberdesc}
 112
 113 \begin{memberdesc}{initial_indent}
 114 (default: \code{''}) String that will be prepended to the first line
 115 of wrapped output.  Counts towards the length of the first line.
 116 \end{memberdesc}
 117
 118 \begin{memberdesc}{subsequent_indent}
 119 (default: \code{''}) String that will be prepended to all lines of
 120 wrapped output except the first.  Counts towards the length of each
 121 line except the first.
 122 \end{memberdesc}
 123
 124 \begin{memberdesc}{fix_sentence_endings}
 125 (default: \code{False}) If true, \class{TextWrapper} attempts to detect
 126 sentence endings and ensure that sentences are always separated by
 127 exactly two spaces.  This is generally desired for text in a monospaced
 128 font.  However, the sentence detection algorithm is imperfect: it
 129 assumes that a sentence ending consists of a lowercase letter followed
 130 by one of \character{.},
 131 \character{!}, or \character{?}, possibly followed by one of
 132 \character{"} or \character{'}, followed by a space.  One problem
 133 with this is algorithm is that it is unable to detect the difference
 134 between ``Dr.'' in
 135
 136 \begin{verbatim}
 137 [...] Dr. Frankenstein's monster [...]
 138 \end{verbatim}
 139
 140 and ``Spot.'' in
 141
 142 \begin{verbatim}
 143 [...] See Spot. See Spot run [...]
 144 \end{verbatim}
 145
 146 \member{fix_sentence_endings} is false by default.
 147
 148 Since the sentence detection algorithm relies on
 149 \code{string.lowercase} for the definition of ``lowercase letter,''
 150 and a convention of using two spaces after a period to separate
 151 sentences on the same line, it is specific to English-language texts.
 152 \end{memberdesc}
 153
 154 \begin{memberdesc}{break_long_words}
 155 (default: \code{True}) If true, then words longer than
 156 \member{width} will be broken in order to ensure that no lines are
 157 longer than \member{width}.  If it is false, long words will not be
 158 broken, and some lines may be longer than \member{width}.  (Long words
 159 will be put on a line by themselves, in order to minimize the amount
 160 by which \member{width} is exceeded.)
 161 \end{memberdesc}
 162
 163 \class{TextWrapper} also provides two public methods, analogous to the
 164 module-level convenience functions:
 165
 166 \begin{methoddesc}{wrap}{text}
 167 Wraps the single paragraph in \var{text} (a string) so every line is
 168 at most \member{width} characters long.  All wrapping options are
 169 taken from instance attributes of the \class{TextWrapper} instance.
 170 Returns a list of output lines, without final newlines.
 171 \end{methoddesc}
 172
 173 \begin{methoddesc}{fill}{text}
 174 Wraps the single paragraph in \var{text}, and returns a single string
 175 containing the wrapped paragraph.
 176 \end{methoddesc}