Debian Codegraph @

Doc/library/textwrap.rst

raw
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
14 The :mod:`textwrap` module provides some convenience functions,
15 as well as :class:`TextWrapper`, the class that does all the work.
16 If you're just wrapping or filling one or two text strings, the convenience
17 functions 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 *placeholder* fit within *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
136 instance is not reused, so for applications that process many text
137 strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to
138 create your own :class:`TextWrapper` object.
139
140 Text is preferably wrapped on whitespaces and right after the hyphens in
141 hyphenated 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 reuse 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:`~str.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 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.