blob: ec0e7cbe0160d756948a72116ff6e317540ee87f [file] [log] [blame]
Greg Warde807e572002-07-04 14:51:49 +00001"""Text wrapping and filling.
Greg Ward00935822002-06-07 21:43:37 +00002"""
3
Greg Ward78cc0512002-10-13 19:23:18 +00004# Copyright (C) 1999-2001 Gregory P. Ward.
Greg Ward698d9f02002-06-07 22:40:23 +00005# Copyright (C) 2002 Python Software Foundation.
6# Written by Greg Ward <gward@python.net>
7
Greg Ward4c486bc2002-10-22 18:31:50 +00008# XXX currently this module does not work very well with Unicode
9# strings. See http://www.python.org/sf/622831 for updates.
10
Greg Ward00935822002-06-07 21:43:37 +000011__revision__ = "$Id$"
12
13import string, re
14
Greg Ward4c6c9c42003-02-03 14:46:57 +000015__all__ = ['TextWrapper', 'wrap', 'fill']
16
Greg Wardafd44de2002-12-12 17:24:35 +000017# Hardcode the recognized whitespace characters to the US-ASCII
18# whitespace characters. The main reason for doing this is that in
19# ISO-8859-1, 0xa0 is non-breaking whitespace, so in certain locales
20# that character winds up in string.whitespace. Respecting
21# string.whitespace in those cases would 1) make textwrap treat 0xa0 the
22# same as any other whitespace char, which is clearly wrong (it's a
23# *non-breaking* space), 2) possibly cause problems with Unicode,
24# since 0xa0 is not in range(128).
Greg Ward4c6c9c42003-02-03 14:46:57 +000025_whitespace = '\t\n\x0b\x0c\r '
Greg Wardafd44de2002-12-12 17:24:35 +000026
Greg Ward00935822002-06-07 21:43:37 +000027class TextWrapper:
28 """
29 Object for wrapping/filling text. The public interface consists of
30 the wrap() and fill() methods; the other methods are just there for
31 subclasses to override in order to tweak the default behaviour.
32 If you want to completely replace the main wrapping algorithm,
33 you'll probably have to override _wrap_chunks().
34
Greg Wardd34c9592002-06-10 20:26:02 +000035 Several instance attributes control various aspects of wrapping:
36 width (default: 70)
37 the maximum width of wrapped lines (unless break_long_words
38 is false)
Greg Ward62080be2002-06-10 21:37:12 +000039 initial_indent (default: "")
40 string that will be prepended to the first line of wrapped
41 output. Counts towards the line's width.
42 subsequent_indent (default: "")
43 string that will be prepended to all lines save the first
44 of wrapped output; also counts towards each line's width.
Greg Ward62e4f3b2002-06-07 21:56:16 +000045 expand_tabs (default: true)
46 Expand tabs in input text to spaces before further processing.
47 Each tab will become 1 .. 8 spaces, depending on its position in
48 its line. If false, each tab is treated as a single character.
49 replace_whitespace (default: true)
50 Replace all whitespace characters in the input text by spaces
51 after tab expansion. Note that if expand_tabs is false and
52 replace_whitespace is true, every tab will be converted to a
53 single space!
54 fix_sentence_endings (default: false)
55 Ensure that sentence-ending punctuation is always followed
Andrew M. Kuchlinga2ecabe2003-02-14 01:14:15 +000056 by two spaces. Off by default because the algorithm is
Greg Ward62e4f3b2002-06-07 21:56:16 +000057 (unavoidably) imperfect.
58 break_long_words (default: true)
Greg Wardd34c9592002-06-10 20:26:02 +000059 Break words longer than 'width'. If false, those words will not
60 be broken, and some lines might be longer than 'width'.
Greg Ward00935822002-06-07 21:43:37 +000061 """
62
Greg Ward4c6c9c42003-02-03 14:46:57 +000063 whitespace_trans = string.maketrans(_whitespace, ' ' * len(_whitespace))
Greg Ward00935822002-06-07 21:43:37 +000064
Greg Ward2e745412002-12-09 16:23:08 +000065 unicode_whitespace_trans = {}
Greg Ward0e88c9f2002-12-11 13:54:20 +000066 uspace = ord(u' ')
Greg Ward4c6c9c42003-02-03 14:46:57 +000067 for x in map(ord, _whitespace):
Greg Ward0e88c9f2002-12-11 13:54:20 +000068 unicode_whitespace_trans[x] = uspace
Greg Ward2e745412002-12-09 16:23:08 +000069
Tim Petersc411dba2002-07-16 21:35:23 +000070 # This funky little regex is just the trick for splitting
Greg Ward00935822002-06-07 21:43:37 +000071 # text up into word-wrappable chunks. E.g.
72 # "Hello there -- you goof-ball, use the -b option!"
73 # splits into
74 # Hello/ /there/ /--/ /you/ /goof-/ball,/ /use/ /the/ /-b/ /option!
75 # (after stripping out empty strings).
76 wordsep_re = re.compile(r'(\s+|' # any whitespace
Greg Wardcce4d672002-08-22 21:04:21 +000077 r'-*\w{2,}-(?=\w{2,})|' # hyphenated words
Greg Warda409f7c2003-05-07 01:20:58 +000078 r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash
Greg Ward00935822002-06-07 21:43:37 +000079
Greg Ward9b4864e2002-06-07 22:04:15 +000080 # XXX will there be a locale-or-charset-aware version of
81 # string.lowercase in 2.3?
82 sentence_end_re = re.compile(r'[%s]' # lowercase letter
83 r'[\.\!\?]' # sentence-ending punct.
84 r'[\"\']?' # optional end-of-quote
85 % string.lowercase)
Greg Ward62e4f3b2002-06-07 21:56:16 +000086
Greg Ward00935822002-06-07 21:43:37 +000087
Greg Ward47df99d2002-06-09 00:22:07 +000088 def __init__ (self,
Greg Wardd34c9592002-06-10 20:26:02 +000089 width=70,
Greg Ward62080be2002-06-10 21:37:12 +000090 initial_indent="",
91 subsequent_indent="",
Greg Ward47df99d2002-06-09 00:22:07 +000092 expand_tabs=True,
93 replace_whitespace=True,
94 fix_sentence_endings=False,
95 break_long_words=True):
Greg Wardd34c9592002-06-10 20:26:02 +000096 self.width = width
Greg Ward62080be2002-06-10 21:37:12 +000097 self.initial_indent = initial_indent
98 self.subsequent_indent = subsequent_indent
Greg Ward47df99d2002-06-09 00:22:07 +000099 self.expand_tabs = expand_tabs
100 self.replace_whitespace = replace_whitespace
101 self.fix_sentence_endings = fix_sentence_endings
102 self.break_long_words = break_long_words
Tim Petersc411dba2002-07-16 21:35:23 +0000103
Greg Ward00935822002-06-07 21:43:37 +0000104
105 # -- Private methods -----------------------------------------------
106 # (possibly useful for subclasses to override)
107
Greg Wardcb320eb2002-06-07 22:32:15 +0000108 def _munge_whitespace(self, text):
Greg Ward00935822002-06-07 21:43:37 +0000109 """_munge_whitespace(text : string) -> string
110
111 Munge whitespace in text: expand tabs and convert all other
112 whitespace characters to spaces. Eg. " foo\tbar\n\nbaz"
113 becomes " foo bar baz".
114 """
115 if self.expand_tabs:
116 text = text.expandtabs()
117 if self.replace_whitespace:
Greg Ward2e745412002-12-09 16:23:08 +0000118 if isinstance(text, str):
119 text = text.translate(self.whitespace_trans)
120 elif isinstance(text, unicode):
121 text = text.translate(self.unicode_whitespace_trans)
Greg Ward00935822002-06-07 21:43:37 +0000122 return text
123
124
Greg Wardcb320eb2002-06-07 22:32:15 +0000125 def _split(self, text):
Greg Ward00935822002-06-07 21:43:37 +0000126 """_split(text : string) -> [string]
127
128 Split the text to wrap into indivisible chunks. Chunks are
129 not quite the same as words; see wrap_chunks() for full
130 details. As an example, the text
131 Look, goof-ball -- use the -b option!
132 breaks into the following chunks:
133 'Look,', ' ', 'goof-', 'ball', ' ', '--', ' ',
134 'use', ' ', 'the', ' ', '-b', ' ', 'option!'
135 """
136 chunks = self.wordsep_re.split(text)
137 chunks = filter(None, chunks)
138 return chunks
139
Greg Wardcb320eb2002-06-07 22:32:15 +0000140 def _fix_sentence_endings(self, chunks):
Greg Ward00935822002-06-07 21:43:37 +0000141 """_fix_sentence_endings(chunks : [string])
142
143 Correct for sentence endings buried in 'chunks'. Eg. when the
144 original text contains "... foo.\nBar ...", munge_whitespace()
145 and split() will convert that to [..., "foo.", " ", "Bar", ...]
146 which has one too few spaces; this method simply changes the one
147 space to two.
148 """
149 i = 0
Greg Ward9b4864e2002-06-07 22:04:15 +0000150 pat = self.sentence_end_re
Greg Ward00935822002-06-07 21:43:37 +0000151 while i < len(chunks)-1:
Greg Ward9b4864e2002-06-07 22:04:15 +0000152 if chunks[i+1] == " " and pat.search(chunks[i]):
Greg Ward00935822002-06-07 21:43:37 +0000153 chunks[i+1] = " "
154 i += 2
155 else:
156 i += 1
157
Greg Ward62080be2002-06-10 21:37:12 +0000158 def _handle_long_word(self, chunks, cur_line, cur_len, width):
Greg Ward00935822002-06-07 21:43:37 +0000159 """_handle_long_word(chunks : [string],
160 cur_line : [string],
Greg Ward62080be2002-06-10 21:37:12 +0000161 cur_len : int, width : int)
Greg Ward00935822002-06-07 21:43:37 +0000162
163 Handle a chunk of text (most likely a word, not whitespace) that
164 is too long to fit in any line.
165 """
Greg Ward62080be2002-06-10 21:37:12 +0000166 space_left = width - cur_len
Greg Ward00935822002-06-07 21:43:37 +0000167
168 # If we're allowed to break long words, then do so: put as much
169 # of the next chunk onto the current line as will fit.
170 if self.break_long_words:
171 cur_line.append(chunks[0][0:space_left])
172 chunks[0] = chunks[0][space_left:]
173
174 # Otherwise, we have to preserve the long word intact. Only add
175 # it to the current line if there's nothing already there --
176 # that minimizes how much we violate the width constraint.
177 elif not cur_line:
178 cur_line.append(chunks.pop(0))
179
180 # If we're not allowed to break long words, and there's already
181 # text on the current line, do nothing. Next time through the
182 # main loop of _wrap_chunks(), we'll wind up here again, but
183 # cur_len will be zero, so the next line will be entirely
184 # devoted to the long word that we can't handle right now.
185
Greg Wardd34c9592002-06-10 20:26:02 +0000186 def _wrap_chunks(self, chunks):
187 """_wrap_chunks(chunks : [string]) -> [string]
Greg Ward00935822002-06-07 21:43:37 +0000188
189 Wrap a sequence of text chunks and return a list of lines of
Greg Wardd34c9592002-06-10 20:26:02 +0000190 length 'self.width' or less. (If 'break_long_words' is false,
191 some lines may be longer than this.) Chunks correspond roughly
192 to words and the whitespace between them: each chunk is
193 indivisible (modulo 'break_long_words'), but a line break can
194 come between any two chunks. Chunks should not have internal
195 whitespace; ie. a chunk is either all whitespace or a "word".
196 Whitespace chunks will be removed from the beginning and end of
197 lines, but apart from that whitespace is preserved.
Greg Ward00935822002-06-07 21:43:37 +0000198 """
199 lines = []
Greg Ward21820cd2003-05-07 00:55:35 +0000200 if self.width <= 0:
201 raise ValueError("invalid width %r (must be > 0)" % self.width)
Greg Ward00935822002-06-07 21:43:37 +0000202
203 while chunks:
204
Greg Ward62080be2002-06-10 21:37:12 +0000205 # Start the list of chunks that will make up the current line.
206 # cur_len is just the length of all the chunks in cur_line.
207 cur_line = []
208 cur_len = 0
209
210 # Figure out which static string will prefix this line.
211 if lines:
212 indent = self.subsequent_indent
213 else:
214 indent = self.initial_indent
215
216 # Maximum width for this line.
217 width = self.width - len(indent)
Greg Ward00935822002-06-07 21:43:37 +0000218
Greg Wardab73d462002-12-09 16:26:05 +0000219 # First chunk on line is whitespace -- drop it, unless this
220 # is the very beginning of the text (ie. no lines started yet).
221 if chunks[0].strip() == '' and lines:
Greg Ward00935822002-06-07 21:43:37 +0000222 del chunks[0]
223
224 while chunks:
225 l = len(chunks[0])
226
227 # Can at least squeeze this chunk onto the current line.
228 if cur_len + l <= width:
229 cur_line.append(chunks.pop(0))
230 cur_len += l
231
232 # Nope, this line is full.
233 else:
234 break
235
236 # The current line is full, and the next chunk is too big to
Tim Petersc411dba2002-07-16 21:35:23 +0000237 # fit on *any* line (not just this one).
Greg Ward00935822002-06-07 21:43:37 +0000238 if chunks and len(chunks[0]) > width:
Greg Ward62080be2002-06-10 21:37:12 +0000239 self._handle_long_word(chunks, cur_line, cur_len, width)
Greg Ward00935822002-06-07 21:43:37 +0000240
241 # If the last chunk on this line is all whitespace, drop it.
242 if cur_line and cur_line[-1].strip() == '':
243 del cur_line[-1]
244
245 # Convert current line back to a string and store it in list
246 # of all lines (return value).
247 if cur_line:
Greg Ward62080be2002-06-10 21:37:12 +0000248 lines.append(indent + ''.join(cur_line))
Greg Ward00935822002-06-07 21:43:37 +0000249
250 return lines
251
252
253 # -- Public interface ----------------------------------------------
254
Greg Wardd34c9592002-06-10 20:26:02 +0000255 def wrap(self, text):
256 """wrap(text : string) -> [string]
Greg Ward00935822002-06-07 21:43:37 +0000257
Greg Warde807e572002-07-04 14:51:49 +0000258 Reformat the single paragraph in 'text' so it fits in lines of
259 no more than 'self.width' columns, and return a list of wrapped
260 lines. Tabs in 'text' are expanded with string.expandtabs(),
261 and all other whitespace characters (including newline) are
262 converted to space.
Greg Ward00935822002-06-07 21:43:37 +0000263 """
264 text = self._munge_whitespace(text)
Guido van Rossumeb287a22002-10-02 15:47:32 +0000265 indent = self.initial_indent
266 if len(text) + len(indent) <= self.width:
267 return [indent + text]
Greg Ward00935822002-06-07 21:43:37 +0000268 chunks = self._split(text)
Greg Ward62e4f3b2002-06-07 21:56:16 +0000269 if self.fix_sentence_endings:
270 self._fix_sentence_endings(chunks)
Greg Wardd34c9592002-06-10 20:26:02 +0000271 return self._wrap_chunks(chunks)
Greg Ward00935822002-06-07 21:43:37 +0000272
Greg Ward62080be2002-06-10 21:37:12 +0000273 def fill(self, text):
274 """fill(text : string) -> string
Greg Ward00935822002-06-07 21:43:37 +0000275
Greg Warde807e572002-07-04 14:51:49 +0000276 Reformat the single paragraph in 'text' to fit in lines of no
277 more than 'self.width' columns, and return a new string
278 containing the entire wrapped paragraph.
Greg Ward00935822002-06-07 21:43:37 +0000279 """
Greg Ward62080be2002-06-10 21:37:12 +0000280 return "\n".join(self.wrap(text))
Greg Ward00935822002-06-07 21:43:37 +0000281
282
Greg Warde807e572002-07-04 14:51:49 +0000283# -- Convenience interface ---------------------------------------------
Greg Ward00935822002-06-07 21:43:37 +0000284
Greg Wardcf02ac62002-06-10 20:36:07 +0000285def wrap(text, width=70, **kwargs):
Greg Warde807e572002-07-04 14:51:49 +0000286 """Wrap a single paragraph of text, returning a list of wrapped lines.
287
288 Reformat the single paragraph in 'text' so it fits in lines of no
289 more than 'width' columns, and return a list of wrapped lines. By
290 default, tabs in 'text' are expanded with string.expandtabs(), and
291 all other whitespace characters (including newline) are converted to
292 space. See TextWrapper class for available keyword args to customize
293 wrapping behaviour.
294 """
Greg Wardcf02ac62002-06-10 20:36:07 +0000295 w = TextWrapper(width=width, **kwargs)
296 return w.wrap(text)
Greg Ward00935822002-06-07 21:43:37 +0000297
Greg Ward62080be2002-06-10 21:37:12 +0000298def fill(text, width=70, **kwargs):
Greg Warde807e572002-07-04 14:51:49 +0000299 """Fill a single paragraph of text, returning a new string.
300
301 Reformat the single paragraph in 'text' to fit in lines of no more
302 than 'width' columns, and return a new string containing the entire
303 wrapped paragraph. As with wrap(), tabs are expanded and other
304 whitespace characters converted to space. See TextWrapper class for
305 available keyword args to customize wrapping behaviour.
306 """
Greg Wardcf02ac62002-06-10 20:36:07 +0000307 w = TextWrapper(width=width, **kwargs)
Greg Ward62080be2002-06-10 21:37:12 +0000308 return w.fill(text)
Greg Ward478cd482003-05-08 01:58:05 +0000309
310
311# -- Loosely related functionality -------------------------------------
312
313def dedent(text):
314 """dedent(text : string) -> string
315
316 Remove any whitespace than can be uniformly removed from the left
317 of every line in `text`.
318
319 This can be used e.g. to make triple-quoted strings line up with
320 the left edge of screen/whatever, while still presenting it in the
321 source code in indented form.
322
323 For example:
324
325 def test():
326 # end first line with \ to avoid the empty line!
327 s = '''\
328 Hey
329 there
330 '''
331 print repr(s) # prints ' Hey\n there\n '
332 print repr(dedent(s)) # prints 'Hey\nthere\n'
333 """
334 lines = text.expandtabs().split('\n')
335 margin = None
336 for line in lines:
337 content = len(line.lstrip())
338 if not content:
339 continue
340 indent = len(line) - content
341 if margin is None:
342 margin = indent
343 else:
344 margin = min(margin, indent)
345
346 if margin is not None:
347 for i in range(len(lines)):
348 lines[i] = lines[i][margin:]
349
350 return '\n'.join(lines)