1
:mod:`textwrap` --- Text wrapping and filling
2
=============================================
5
:synopsis: Text wrapping and filling
6
.. moduleauthor:: Greg Ward <gward@python.net>
7
.. sectionauthor:: Greg Ward <gward@python.net>
11
**Source code:** :source:`Lib/textwrap.py`
15
The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and
16
:func:`fill`, as well as :class:`TextWrapper`, the class that does all the work,
17
and a utility function :func:`dedent`. If you're just wrapping or filling one
18
or two text strings, the convenience functions should be good enough;
19
otherwise, you should use an instance of :class:`TextWrapper` for efficiency.
21
.. function:: wrap(text[, width[, ...]])
23
Wraps the single paragraph in *text* (a string) so every line is at most *width*
24
characters long. Returns a list of output lines, without final newlines.
26
Optional keyword arguments correspond to the instance attributes of
27
:class:`TextWrapper`, documented below. *width* defaults to ``70``.
29
See the :meth:`TextWrapper.wrap` method for additional details on how
33
.. function:: fill(text[, width[, ...]])
35
Wraps the single paragraph in *text*, and returns a single string containing the
36
wrapped paragraph. :func:`fill` is shorthand for ::
38
"\n".join(wrap(text, ...))
40
In particular, :func:`fill` accepts exactly the same keyword arguments as
43
Both :func:`wrap` and :func:`fill` work by creating a :class:`TextWrapper`
44
instance and calling a single method on it. That instance is not reused, so for
45
applications that wrap/fill many text strings, it will be more efficient for you
46
to create your own :class:`TextWrapper` object.
48
Text is preferably wrapped on whitespaces and right after the hyphens in
49
hyphenated words; only then will long words be broken if necessary, unless
50
:attr:`TextWrapper.break_long_words` is set to false.
52
An additional utility function, :func:`dedent`, is provided to remove
53
indentation from strings that have unwanted whitespace to the left of the text.
56
.. function:: dedent(text)
58
Remove any common leading whitespace from every line in *text*.
60
This can be used to make triple-quoted strings line up with the left edge of the
61
display, while still presenting them in the source code in indented form.
63
Note that tabs and spaces are both treated as whitespace, but they are not
64
equal: the lines ``" hello"`` and ``"\thello"`` are considered to have no
65
common leading whitespace. (This behaviour is new in Python 2.5; older versions
66
of this module incorrectly expanded tabs before searching for common leading
72
# end first line with \ to avoid the empty line!
77
print repr(s) # prints ' hello\n world\n '
78
print repr(dedent(s)) # prints 'hello\n world\n'
81
.. class:: TextWrapper(...)
83
The :class:`TextWrapper` constructor accepts a number of optional keyword
84
arguments. Each argument corresponds to one instance attribute, so for example
87
wrapper = TextWrapper(initial_indent="* ")
91
wrapper = TextWrapper()
92
wrapper.initial_indent = "* "
94
You can re-use the same :class:`TextWrapper` object many times, and you can
95
change any of its options through direct assignment to instance attributes
98
The :class:`TextWrapper` instance attributes (and keyword arguments to the
99
constructor) are as follows:
104
(default: ``70``) The maximum length of wrapped lines. As long as there
105
are no individual words in the input text longer than :attr:`width`,
106
:class:`TextWrapper` guarantees that no output line will be longer than
107
:attr:`width` characters.
110
.. attribute:: expand_tabs
112
(default: ``True``) If true, then all tab characters in *text* will be
113
expanded to spaces using the :meth:`expandtabs` method of *text*.
116
.. attribute:: replace_whitespace
118
(default: ``True``) If true, after tab expansion but before wrapping,
119
the :meth:`wrap` method will replace each whitespace character
120
with a single space. The whitespace characters replaced are
121
as follows: tab, newline, vertical tab, formfeed, and carriage
122
return (``'\t\n\v\f\r'``).
126
If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true,
127
each tab character will be replaced by a single space, which is *not*
128
the same as tab expansion.
132
If :attr:`replace_whitespace` is false, newlines may appear in the
133
middle of a line and cause strange output. For this reason, text should
134
be split into paragraphs (using :meth:`str.splitlines` or similar)
135
which are wrapped separately.
138
.. attribute:: drop_whitespace
140
(default: ``True``) If true, whitespace at the beginning and ending of
141
every line (after wrapping but before indenting) is dropped.
142
Whitespace at the beginning of the paragraph, however, is not dropped
143
if non-whitespace follows it. If whitespace being dropped takes up an
144
entire line, the whole line is dropped.
146
.. versionadded:: 2.6
147
Whitespace was always dropped in earlier versions.
150
.. attribute:: initial_indent
152
(default: ``''``) String that will be prepended to the first line of
153
wrapped output. Counts towards the length of the first line. The empty
154
string is not indented.
157
.. attribute:: subsequent_indent
159
(default: ``''``) String that will be prepended to all lines of wrapped
160
output except the first. Counts towards the length of each line except
164
.. attribute:: fix_sentence_endings
166
(default: ``False``) If true, :class:`TextWrapper` attempts to detect
167
sentence endings and ensure that sentences are always separated by exactly
168
two spaces. This is generally desired for text in a monospaced font.
169
However, the sentence detection algorithm is imperfect: it assumes that a
170
sentence ending consists of a lowercase letter followed by one of ``'.'``,
171
``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``,
172
followed by a space. One problem with this is algorithm is that it is
173
unable to detect the difference between "Dr." in ::
175
[...] Dr. Frankenstein's monster [...]
179
[...] See Spot. See Spot run [...]
181
:attr:`fix_sentence_endings` is false by default.
183
Since the sentence detection algorithm relies on ``string.lowercase`` for
184
the definition of "lowercase letter," and a convention of using two spaces
185
after a period to separate sentences on the same line, it is specific to
186
English-language texts.
189
.. attribute:: break_long_words
191
(default: ``True``) If true, then words longer than :attr:`width` will be
192
broken in order to ensure that no lines are longer than :attr:`width`. If
193
it is false, long words will not be broken, and some lines may be longer
194
than :attr:`width`. (Long words will be put on a line by themselves, in
195
order to minimize the amount by which :attr:`width` is exceeded.)
198
.. attribute:: break_on_hyphens
200
(default: ``True``) If true, wrapping will occur preferably on whitespaces
201
and right after hyphens in compound words, as it is customary in English.
202
If false, only whitespaces will be considered as potentially good places
203
for line breaks, but you need to set :attr:`break_long_words` to false if
204
you want truly insecable words. Default behaviour in previous versions
205
was to always allow breaking hyphenated words.
207
.. versionadded:: 2.6
210
:class:`TextWrapper` also provides two public methods, analogous to the
211
module-level convenience functions:
213
.. method:: wrap(text)
215
Wraps the single paragraph in *text* (a string) so every line is at most
216
:attr:`width` characters long. All wrapping options are taken from
217
instance attributes of the :class:`TextWrapper` instance. Returns a list
218
of output lines, without final newlines. If the wrapped output has no
219
content, the returned list is empty.
222
.. method:: fill(text)
224
Wraps the single paragraph in *text*, and returns a single string
225
containing the wrapped paragraph.
added
removed
python-2.7.11-docs-html/_sources/library/textwrap.txt
