1 """Text wrapping and filling.
4 # Copyright (C) 1999-2001 Gregory P. Ward.
5 # Copyright (C) 2002, 2003 Python Software Foundation.
6 # Written by Greg Ward <gward@python.net>
12 # Do the right thing with boolean values for all known Python versions
13 # (so this module can be copied to projects that don't depend on Python
14 # 2.3, e.g. Optik and Docutils) by uncommenting the block of code below.
18 # (True, False) = (1, 0)
20 __all__
= ['TextWrapper', 'wrap', 'fill']
22 # Hardcode the recognized whitespace characters to the US-ASCII
23 # whitespace characters. The main reason for doing this is that in
24 # ISO-8859-1, 0xa0 is non-breaking whitespace, so in certain locales
25 # that character winds up in string.whitespace. Respecting
26 # string.whitespace in those cases would 1) make textwrap treat 0xa0 the
27 # same as any other whitespace char, which is clearly wrong (it's a
28 # *non-breaking* space), 2) possibly cause problems with Unicode,
29 # since 0xa0 is not in range(128).
30 _whitespace
= '\t\n\x0b\x0c\r '
34 Object for wrapping/filling text. The public interface consists of
35 the wrap() and fill() methods; the other methods are just there for
36 subclasses to override in order to tweak the default behaviour.
37 If you want to completely replace the main wrapping algorithm,
38 you'll probably have to override _wrap_chunks().
40 Several instance attributes control various aspects of wrapping:
42 the maximum width of wrapped lines (unless break_long_words
44 initial_indent (default: "")
45 string that will be prepended to the first line of wrapped
46 output. Counts towards the line's width.
47 subsequent_indent (default: "")
48 string that will be prepended to all lines save the first
49 of wrapped output; also counts towards each line's width.
50 expand_tabs (default: true)
51 Expand tabs in input text to spaces before further processing.
52 Each tab will become 1 .. 8 spaces, depending on its position in
53 its line. If false, each tab is treated as a single character.
54 replace_whitespace (default: true)
55 Replace all whitespace characters in the input text by spaces
56 after tab expansion. Note that if expand_tabs is false and
57 replace_whitespace is true, every tab will be converted to a
59 fix_sentence_endings (default: false)
60 Ensure that sentence-ending punctuation is always followed
61 by two spaces. Off by default because the algorithm is
62 (unavoidably) imperfect.
63 break_long_words (default: true)
64 Break words longer than 'width'. If false, those words will not
65 be broken, and some lines might be longer than 'width'.
66 break_on_hyphens (default: true)
67 Allow breaking hyphenated words. If true, wrapping will occur
68 preferably on whitespaces and right after hyphens part of
70 drop_whitespace (default: true)
71 Drop leading and trailing whitespace from lines.
74 whitespace_trans
= string
.maketrans(_whitespace
, ' ' * len(_whitespace
))
76 unicode_whitespace_trans
= {}
78 for x
in map(ord, _whitespace
):
79 unicode_whitespace_trans
[x
] = uspace
81 # This funky little regex is just the trick for splitting
82 # text up into word-wrappable chunks. E.g.
83 # "Hello there -- you goof-ball, use the -b option!"
85 # Hello/ /there/ /--/ /you/ /goof-/ball,/ /use/ /the/ /-b/ /option!
86 # (after stripping out empty strings).
87 wordsep_re
= re
.compile(
88 r
'(\s+|' # any whitespace
89 r
'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|' # hyphenated words
90 r
'(?<=[\w\!\"\'\
&\
.\
,\?])-{2,}(?
=\w
))') # em-dash
92 # This less funky little regex just split on recognized spaces. E.g.
93 # "Hello there -- you goof-ball, use the -b option!"
95 # Hello/ /there/ /--/ /you/ /goof-ball,/ /use/ /the/ /-b/ /option!/
96 wordsep_simple_re = re.compile(r'(\s
+)')
98 # XXX this is not locale- or charset-aware -- string.lowercase
99 # is US-ASCII only (and therefore English-only)
100 sentence_end_re = re.compile(r'[%s]' # lowercase letter
101 r'[\
.\
!\?]' # sentence-ending punct.
102 r'[\"\']?
' # optional end-of-quote
110 subsequent_indent="",
112 replace_whitespace=True,
113 fix_sentence_endings=False,
114 break_long_words=True,
115 drop_whitespace=True,
116 break_on_hyphens=True):
118 self.initial_indent = initial_indent
119 self.subsequent_indent = subsequent_indent
120 self.expand_tabs = expand_tabs
121 self.replace_whitespace = replace_whitespace
122 self.fix_sentence_endings = fix_sentence_endings
123 self.break_long_words = break_long_words
124 self.drop_whitespace = drop_whitespace
125 self.break_on_hyphens = break_on_hyphens
128 # -- Private methods -----------------------------------------------
129 # (possibly useful for subclasses to override)
131 def _munge_whitespace(self, text):
132 """_munge_whitespace(text : string) -> string
134 Munge whitespace in text: expand tabs and convert all other
135 whitespace characters to spaces. Eg. " foo\tbar\n\nbaz"
136 becomes " foo bar baz".
139 text = text.expandtabs()
140 if self.replace_whitespace:
141 if isinstance(text, str):
142 text = text.translate(self.whitespace_trans)
143 elif isinstance(text, unicode):
144 text = text.translate(self.unicode_whitespace_trans)
148 def _split(self, text):
149 """_split(text : string) -> [string]
151 Split the text to wrap into indivisible chunks. Chunks are
152 not quite the same as words; see wrap_chunks() for full
153 details. As an example, the text
154 Look, goof-ball -- use the -b option!
155 breaks into the following chunks:
156 'Look
,', ' ', 'goof
-', 'ball
', ' ', '--', ' ',
157 'use
', ' ', 'the
', ' ', '-b
', ' ', 'option
!'
158 if break_on_hyphens is True, or in:
159 'Look
,', ' ', 'goof
-ball
', ' ', '--', ' ',
160 'use
', ' ', 'the
', ' ', '-b
', ' ', option!'
163 if self.break_on_hyphens is True:
164 chunks = self.wordsep_re.split(text)
166 chunks = self.wordsep_simple_re.split(text)
167 chunks = filter(None, chunks) # remove empty chunks
170 def _fix_sentence_endings(self, chunks):
171 """_fix_sentence_endings(chunks
: [string
])
173 Correct
for sentence endings buried
in 'chunks'. Eg
. when the
174 original text contains
"... foo.\nBar ...", munge_whitespace()
175 and split() will convert that to
[..., "foo.", " ", "Bar", ...]
176 which has one too few spaces
; this method simply changes the one
180 pat = self.sentence_end_re
181 while i < len(chunks)-1:
182 if chunks[i+1] == " " and pat.search(chunks[i]):
188 def _handle_long_word(self, reversed_chunks, cur_line, cur_len, width):
189 """_handle_long_word(chunks
: [string
],
191 cur_len
: int, width
: int)
193 Handle a chunk of
text (most likely a word
, not whitespace
) that
194 is too
long to fit
in any line
.
196 # Figure out when indent is larger than the specified width, and make
197 # sure at least one character is stripped off on every pass
201 space_left = width - cur_len
203 # If we're allowed to break long words, then do so: put as much
204 # of the next chunk onto the current line as will fit.
205 if self.break_long_words:
206 cur_line.append(reversed_chunks[-1][:space_left])
207 reversed_chunks[-1] = reversed_chunks[-1][space_left:]
209 # Otherwise, we have to preserve the long word intact. Only add
210 # it to the current line if there's nothing already there --
211 # that minimizes how much we violate the width constraint.
213 cur_line.append(reversed_chunks.pop())
215 # If we're not allowed to break long words, and there's already
216 # text on the current line, do nothing. Next time through the
217 # main loop of _wrap_chunks(), we'll wind up here again, but
218 # cur_len will be zero, so the next line will be entirely
219 # devoted to the long word that we can't handle right now.
221 def _wrap_chunks(self, chunks):
222 """_wrap_chunks(chunks
: [string
]) -> [string
]
224 Wrap a sequence of text chunks
and return a
list of lines of
225 length
'self.width' or less
. (If
'break_long_words' is false
,
226 some lines may be longer than this
.) Chunks correspond roughly
227 to words
and the whitespace between them
: each chunk
is
228 indivisible (modulo
'break_long_words'), but a line
break can
229 come between any two chunks
. Chunks should
not have internal
230 whitespace
; ie
. a chunk
is either all whitespace
or a
"word".
231 Whitespace chunks will be removed
from the beginning
and end of
232 lines
, but apart
from that whitespace
is preserved
.
236 raise ValueError("invalid width %r (must be > 0)" % self.width)
238 # Arrange in reverse order so items can be efficiently popped
239 # from a stack of chucks.
244 # Start the list of chunks that will make up the current line.
245 # cur_len is just the length of all the chunks in cur_line.
249 # Figure out which static string will prefix this line.
251 indent = self.subsequent_indent
253 indent = self.initial_indent
255 # Maximum width for this line.
256 width = self.width - len(indent)
258 # First chunk on line is whitespace -- drop it, unless this
259 # is the very beginning of the text (ie. no lines started yet).
260 if self.drop_whitespace and chunks[-1].strip() == '' and lines:
266 # Can at least squeeze this chunk onto the current line.
267 if cur_len + l <= width:
268 cur_line.append(chunks.pop())
271 # Nope, this line is full.
275 # The current line is full, and the next chunk is too big to
276 # fit on *any* line (not just this one).
277 if chunks and len(chunks[-1]) > width:
278 self._handle_long_word(chunks, cur_line, cur_len, width)
280 # If the last chunk on this line is all whitespace, drop it.
281 if self.drop_whitespace and cur_line and cur_line[-1].strip() == '':
284 # Convert current line back to a string and store it in list
285 # of all lines (return value).
287 lines.append(indent + ''.join(cur_line))
292 # -- Public interface ----------------------------------------------
294 def wrap(self, text):
295 """wrap(text
: string
) -> [string
]
297 Reformat the single paragraph
in 'text' so it fits
in lines of
298 no more than
'self.width' columns
, and return a
list of wrapped
299 lines
. Tabs
in 'text' are expanded with string
.expandtabs(),
300 and all other whitespace
characters (including newline
) are
303 text = self._munge_whitespace(text)
304 chunks = self._split(text)
305 if self.fix_sentence_endings:
306 self._fix_sentence_endings(chunks)
307 return self._wrap_chunks(chunks)
309 def fill(self, text):
310 """fill(text
: string
) -> string
312 Reformat the single paragraph
in 'text' to fit
in lines of no
313 more than
'self.width' columns
, and return a new string
314 containing the entire wrapped paragraph
.
316 return "\n".join(self.wrap(text))
319 # -- Convenience interface ---------------------------------------------
321 def wrap(text, width=70, **kwargs):
322 """Wrap a single paragraph of text
, returning a
list of wrapped lines
.
324 Reformat the single paragraph
in 'text' so it fits
in lines of no
325 more than
'width' columns
, and return a
list of wrapped lines
. By
326 default
, tabs
in 'text' are expanded with string
.expandtabs(), and
327 all other whitespace
characters (including newline
) are converted to
328 space
. See TextWrapper
class for available keyword args to customize
331 w = TextWrapper(width=width, **kwargs)
334 def fill(text, width=70, **kwargs):
335 """Fill a single paragraph of text
, returning a new string
.
337 Reformat the single paragraph
in 'text' to fit
in lines of no more
338 than
'width' columns
, and return a new string containing the entire
339 wrapped paragraph
. As with
wrap(), tabs are expanded
and other
340 whitespace characters converted to space
. See TextWrapper
class for
341 available keyword args to customize wrapping behaviour
.
343 w = TextWrapper(width=width, **kwargs)
347 # -- Loosely related functionality -------------------------------------
349 _whitespace_only_re = re.compile('^[ \t]+$', re.MULTILINE)
350 _leading_whitespace_re = re.compile('(^[ \t]*)(?:[^ \t\n])', re.MULTILINE)
353 """Remove any common leading whitespace
from every line
in `text`
.
355 This can be used to make triple
-quoted strings line up with the left
356 edge of the display
, while still presenting them
in the source code
359 Note that tabs
and spaces are both treated
as whitespace
, but they
360 are
not equal
: the lines
" hello" and "\thello" are
361 considered to have no common leading whitespace
. (This behaviour
is
362 new
in Python
2.5; older versions of this module incorrectly
363 expanded tabs before searching
for common leading whitespace
.)
365 # Look for the longest leading string of spaces and tabs common to
368 text = _whitespace_only_re.sub('', text)
369 indents = _leading_whitespace_re.findall(text)
370 for indent in indents:
374 # Current line more deeply indented than previous winner:
375 # no change (previous winner is still on top).
376 elif indent.startswith(margin):
379 # Current line consistent with and no deeper than previous winner:
380 # it's the new winner.
381 elif margin.startswith(indent):
384 # Current line and previous winner have no common whitespace:
385 # there is no margin.
390 # sanity check (testing/debugging only)
392 for line in text.split("\n"):
393 assert not line or line.startswith(margin), \
394 "line = %r, margin = %r" % (line, margin)
397 text = re.sub(r'(?m)^' + margin, '', text)
400 if __name__ == "__main__":
401 #print dedent("\tfoo\n\tbar")
402 #print dedent(" \thello there\n \t how are you?")
403 print dedent("Hello there.\n This is indented.")