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