1:mod:`textwrap` --- Text wrapping and filling
2=============================================
3
4.. module:: textwrap
5   :synopsis: Text wrapping and filling
6
7.. moduleauthor:: Greg Ward <gward@python.net>
8.. sectionauthor:: Greg Ward <gward@python.net>
9
10**Source code:** :source:`Lib/textwrap.py`
11
12--------------
13
14The :mod:`textwrap` module provides some convenience functions,
15as well as :class:`TextWrapper`, the class that does all the work.
16If you're just wrapping or filling one or two text strings, the convenience
17functions should be good enough; otherwise, you should use an instance of
18:class:`TextWrapper` for efficiency.
19
20.. function:: wrap(text, width=70, **kwargs)
21
22   Wraps the single paragraph in *text* (a string) so every line is at most
23   *width* characters long.  Returns a list of output lines, without final
24   newlines.
25
26   Optional keyword arguments correspond to the instance attributes of
27   :class:`TextWrapper`, documented below.  *width* defaults to ``70``.
28
29   See the :meth:`TextWrapper.wrap` method for additional details on how
30   :func:`wrap` behaves.
31
32
33.. function:: fill(text, width=70, **kwargs)
34
35   Wraps the single paragraph in *text*, and returns a single string containing the
36   wrapped paragraph.  :func:`fill` is shorthand for  ::
37
38      "\n".join(wrap(text, ...))
39
40   In particular, :func:`fill` accepts exactly the same keyword arguments as
41   :func:`wrap`.
42
43
44.. function:: shorten(text, width, **kwargs)
45
46   Collapse and truncate the given *text* to fit in the given *width*.
47
48   First the whitespace in *text* is collapsed (all whitespace is replaced by
49   single spaces).  If the result fits in the *width*, it is returned.
50   Otherwise, enough words are dropped from the end so that the remaining words
51   plus the :attr:`placeholder` fit within :attr:`width`::
52
53      >>> textwrap.shorten("Hello  world!", width=12)
54      'Hello world!'
55      >>> textwrap.shorten("Hello  world!", width=11)
56      'Hello [...]'
57      >>> textwrap.shorten("Hello world", width=10, placeholder="...")
58      'Hello...'
59
60   Optional keyword arguments correspond to the instance attributes of
61   :class:`TextWrapper`, documented below.  Note that the whitespace is
62   collapsed before the text is passed to the :class:`TextWrapper` :meth:`fill`
63   function, so changing the value of :attr:`.tabsize`, :attr:`.expand_tabs`,
64   :attr:`.drop_whitespace`, and :attr:`.replace_whitespace` will have no effect.
65
66   .. versionadded:: 3.4
67
68
69.. function:: dedent(text)
70
71   Remove any common leading whitespace from every line in *text*.
72
73   This can be used to make triple-quoted strings line up with the left edge of the
74   display, while still presenting them in the source code in indented form.
75
76   Note that tabs and spaces are both treated as whitespace, but they are not
77   equal: the lines ``"  hello"`` and ``"\thello"`` are considered to have no
78   common leading whitespace.
79
80   Lines containing only whitespace are ignored in the input and normalized to a
81   single newline character in the output.
82
83   For example::
84
85      def test():
86          # end first line with \ to avoid the empty line!
87          s = '''\
88          hello
89            world
90          '''
91          print(repr(s))          # prints '    hello\n      world\n    '
92          print(repr(dedent(s)))  # prints 'hello\n  world\n'
93
94
95.. function:: indent(text, prefix, predicate=None)
96
97   Add *prefix* to the beginning of selected lines in *text*.
98
99   Lines are separated by calling ``text.splitlines(True)``.
100
101   By default, *prefix* is added to all lines that do not consist
102   solely of whitespace (including any line endings).
103
104   For example::
105
106      >>> s = 'hello\n\n \nworld'
107      >>> indent(s, '  ')
108      '  hello\n\n \n  world'
109
110   The optional *predicate* argument can be used to control which lines
111   are indented. For example, it is easy to add *prefix* to even empty
112   and whitespace-only lines::
113
114      >>> print(indent(s, '+ ', lambda line: True))
115      + hello
116      +
117      +
118      + world
119
120   .. versionadded:: 3.3
121
122
123:func:`wrap`, :func:`fill` and :func:`shorten` work by creating a
124:class:`TextWrapper` instance and calling a single method on it.  That
125instance is not reused, so for applications that process many text
126strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to
127create your own :class:`TextWrapper` object.
128
129Text is preferably wrapped on whitespaces and right after the hyphens in
130hyphenated words; only then will long words be broken if necessary, unless
131:attr:`TextWrapper.break_long_words` is set to false.
132
133.. class:: TextWrapper(**kwargs)
134
135   The :class:`TextWrapper` constructor accepts a number of optional keyword
136   arguments.  Each keyword argument corresponds to an instance attribute, so
137   for example ::
138
139      wrapper = TextWrapper(initial_indent="* ")
140
141   is the same as  ::
142
143      wrapper = TextWrapper()
144      wrapper.initial_indent = "* "
145
146   You can re-use the same :class:`TextWrapper` object many times, and you can
147   change any of its options through direct assignment to instance attributes
148   between uses.
149
150   The :class:`TextWrapper` instance attributes (and keyword arguments to the
151   constructor) are as follows:
152
153
154   .. attribute:: width
155
156      (default: ``70``) The maximum length of wrapped lines.  As long as there
157      are no individual words in the input text longer than :attr:`width`,
158      :class:`TextWrapper` guarantees that no output line will be longer than
159      :attr:`width` characters.
160
161
162   .. attribute:: expand_tabs
163
164      (default: ``True``) If true, then all tab characters in *text* will be
165      expanded to spaces using the :meth:`expandtabs` method of *text*.
166
167
168   .. attribute:: tabsize
169
170      (default: ``8``) If :attr:`expand_tabs` is true, then all tab characters
171      in *text* will be expanded to zero or more spaces, depending on the
172      current column and the given tab size.
173
174      .. versionadded:: 3.3
175
176
177   .. attribute:: replace_whitespace
178
179      (default: ``True``) If true, after tab expansion but before wrapping,
180      the :meth:`wrap` method will replace each whitespace character
181      with a single space.  The whitespace characters replaced are
182      as follows: tab, newline, vertical tab, formfeed, and carriage
183      return (``'\t\n\v\f\r'``).
184
185      .. note::
186
187         If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true,
188         each tab character will be replaced by a single space, which is *not*
189         the same as tab expansion.
190
191      .. note::
192
193         If :attr:`replace_whitespace` is false, newlines may appear in the
194         middle of a line and cause strange output. For this reason, text should
195         be split into paragraphs (using :meth:`str.splitlines` or similar)
196         which are wrapped separately.
197
198
199   .. attribute:: drop_whitespace
200
201      (default: ``True``) If true, whitespace at the beginning and ending of
202      every line (after wrapping but before indenting) is dropped.
203      Whitespace at the beginning of the paragraph, however, is not dropped
204      if non-whitespace follows it.  If whitespace being dropped takes up an
205      entire line, the whole line is dropped.
206
207
208   .. attribute:: initial_indent
209
210      (default: ``''``) String that will be prepended to the first line of
211      wrapped output.  Counts towards the length of the first line.  The empty
212      string is not indented.
213
214
215   .. attribute:: subsequent_indent
216
217      (default: ``''``) String that will be prepended to all lines of wrapped
218      output except the first.  Counts towards the length of each line except
219      the first.
220
221
222   .. attribute:: fix_sentence_endings
223
224      (default: ``False``) If true, :class:`TextWrapper` attempts to detect
225      sentence endings and ensure that sentences are always separated by exactly
226      two spaces.  This is generally desired for text in a monospaced font.
227      However, the sentence detection algorithm is imperfect: it assumes that a
228      sentence ending consists of a lowercase letter followed by one of ``'.'``,
229      ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``,
230      followed by a space.  One problem with this is algorithm is that it is
231      unable to detect the difference between "Dr." in ::
232
233         [...] Dr. Frankenstein's monster [...]
234
235      and "Spot." in ::
236
237         [...] See Spot. See Spot run [...]
238
239      :attr:`fix_sentence_endings` is false by default.
240
241      Since the sentence detection algorithm relies on ``string.lowercase`` for
242      the definition of "lowercase letter", and a convention of using two spaces
243      after a period to separate sentences on the same line, it is specific to
244      English-language texts.
245
246
247   .. attribute:: break_long_words
248
249      (default: ``True``) If true, then words longer than :attr:`width` will be
250      broken in order to ensure that no lines are longer than :attr:`width`.  If
251      it is false, long words will not be broken, and some lines may be longer
252      than :attr:`width`.  (Long words will be put on a line by themselves, in
253      order to minimize the amount by which :attr:`width` is exceeded.)
254
255
256   .. attribute:: break_on_hyphens
257
258      (default: ``True``) If true, wrapping will occur preferably on whitespaces
259      and right after hyphens in compound words, as it is customary in English.
260      If false, only whitespaces will be considered as potentially good places
261      for line breaks, but you need to set :attr:`break_long_words` to false if
262      you want truly insecable words.  Default behaviour in previous versions
263      was to always allow breaking hyphenated words.
264
265
266   .. attribute:: max_lines
267
268      (default: ``None``) If not ``None``, then the output will contain at most
269      *max_lines* lines, with *placeholder* appearing at the end of the output.
270
271      .. versionadded:: 3.4
272
273
274   .. index:: single: ...; placeholder
275
276   .. attribute:: placeholder
277
278      (default: ``' [...]'``) String that will appear at the end of the output
279      text if it has been truncated.
280
281      .. versionadded:: 3.4
282
283
284   :class:`TextWrapper` also provides some public methods, analogous to the
285   module-level convenience functions:
286
287   .. method:: wrap(text)
288
289      Wraps the single paragraph in *text* (a string) so every line is at most
290      :attr:`width` characters long.  All wrapping options are taken from
291      instance attributes of the :class:`TextWrapper` instance.  Returns a list
292      of output lines, without final newlines.  If the wrapped output has no
293      content, the returned list is empty.
294
295
296   .. method:: fill(text)
297
298      Wraps the single paragraph in *text*, and returns a single string
299      containing the wrapped paragraph.
300