blob: 24891804dd3315db779ac212ba24b65894de82d1 [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 Ward523008c2003-06-15 15:37:18 +00005# Copyright (C) 2002, 2003 Python Software Foundation.
Greg Ward698d9f02002-06-07 22:40:23 +00006# Written by Greg Ward <gward@python.net>
7
Benjamin Peterson274271d2011-06-28 10:25:04 -05008import re
Greg Ward00935822002-06-07 21:43:37 +00009
Serhiy Storchaka3e4b5282013-10-16 13:07:53 +030010__all__ = ['TextWrapper', 'wrap', 'fill', 'dedent', 'indent', 'shorten']
Greg Ward4c6c9c42003-02-03 14:46:57 +000011
Greg Wardafd44de2002-12-12 17:24:35 +000012# Hardcode the recognized whitespace characters to the US-ASCII
13# whitespace characters. The main reason for doing this is that in
14# ISO-8859-1, 0xa0 is non-breaking whitespace, so in certain locales
15# that character winds up in string.whitespace. Respecting
16# string.whitespace in those cases would 1) make textwrap treat 0xa0 the
17# same as any other whitespace char, which is clearly wrong (it's a
18# *non-breaking* space), 2) possibly cause problems with Unicode,
19# since 0xa0 is not in range(128).
Greg Ward4c6c9c42003-02-03 14:46:57 +000020_whitespace = '\t\n\x0b\x0c\r '
Greg Wardafd44de2002-12-12 17:24:35 +000021
Greg Ward00935822002-06-07 21:43:37 +000022class TextWrapper:
23 """
24 Object for wrapping/filling text. The public interface consists of
25 the wrap() and fill() methods; the other methods are just there for
26 subclasses to override in order to tweak the default behaviour.
27 If you want to completely replace the main wrapping algorithm,
28 you'll probably have to override _wrap_chunks().
29
Greg Wardd34c9592002-06-10 20:26:02 +000030 Several instance attributes control various aspects of wrapping:
31 width (default: 70)
32 the maximum width of wrapped lines (unless break_long_words
33 is false)
Greg Ward62080be2002-06-10 21:37:12 +000034 initial_indent (default: "")
35 string that will be prepended to the first line of wrapped
36 output. Counts towards the line's width.
37 subsequent_indent (default: "")
38 string that will be prepended to all lines save the first
39 of wrapped output; also counts towards each line's width.
Greg Ward62e4f3b2002-06-07 21:56:16 +000040 expand_tabs (default: true)
41 Expand tabs in input text to spaces before further processing.
Hynek Schlawackd5272592012-05-19 13:33:11 +020042 Each tab will become 0 .. 'tabsize' spaces, depending on its position
43 in its line. If false, each tab is treated as a single character.
44 tabsize (default: 8)
45 Expand tabs in input text to 0 .. 'tabsize' spaces, unless
46 'expand_tabs' is false.
Greg Ward62e4f3b2002-06-07 21:56:16 +000047 replace_whitespace (default: true)
48 Replace all whitespace characters in the input text by spaces
49 after tab expansion. Note that if expand_tabs is false and
50 replace_whitespace is true, every tab will be converted to a
51 single space!
52 fix_sentence_endings (default: false)
53 Ensure that sentence-ending punctuation is always followed
Andrew M. Kuchlinga2ecabe2003-02-14 01:14:15 +000054 by two spaces. Off by default because the algorithm is
Greg Ward62e4f3b2002-06-07 21:56:16 +000055 (unavoidably) imperfect.
56 break_long_words (default: true)
Greg Wardd34c9592002-06-10 20:26:02 +000057 Break words longer than 'width'. If false, those words will not
58 be broken, and some lines might be longer than 'width'.
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000059 break_on_hyphens (default: true)
60 Allow breaking hyphenated words. If true, wrapping will occur
61 preferably on whitespaces and right after hyphens part of
62 compound words.
Guido van Rossumd8faa362007-04-27 19:54:29 +000063 drop_whitespace (default: true)
64 Drop leading and trailing whitespace from lines.
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +030065 max_lines (default: None)
66 Truncate wrapped lines.
67 placeholder (default: ' [...]')
68 Append to the last line of truncated text.
Greg Ward00935822002-06-07 21:43:37 +000069 """
70
Greg Ward2e745412002-12-09 16:23:08 +000071 unicode_whitespace_trans = {}
Guido van Rossumef87d6e2007-05-02 19:09:54 +000072 uspace = ord(' ')
Guido van Rossumc1f779c2007-07-03 08:25:58 +000073 for x in _whitespace:
74 unicode_whitespace_trans[ord(x)] = uspace
Greg Ward2e745412002-12-09 16:23:08 +000075
Tim Petersc411dba2002-07-16 21:35:23 +000076 # This funky little regex is just the trick for splitting
Greg Ward00935822002-06-07 21:43:37 +000077 # text up into word-wrappable chunks. E.g.
78 # "Hello there -- you goof-ball, use the -b option!"
79 # splits into
80 # Hello/ /there/ /--/ /you/ /goof-/ball,/ /use/ /the/ /-b/ /option!
81 # (after stripping out empty strings).
Greg Ward40407942005-03-05 02:53:17 +000082 wordsep_re = re.compile(
83 r'(\s+|' # any whitespace
Antoine Pitrou7c59bc62008-12-13 23:20:54 +000084 r'[^\s\w]*\w+[^0-9\W]-(?=\w+[^0-9\W])|' # hyphenated words
Greg Ward40407942005-03-05 02:53:17 +000085 r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash
Greg Ward00935822002-06-07 21:43:37 +000086
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000087 # This less funky little regex just split on recognized spaces. E.g.
88 # "Hello there -- you goof-ball, use the -b option!"
89 # splits into
90 # Hello/ /there/ /--/ /you/ /goof-ball,/ /use/ /the/ /-b/ /option!/
91 wordsep_simple_re = re.compile(r'(\s+)')
92
93 # XXX this is not locale- or charset-aware -- string.lowercase
94 # is US-ASCII only (and therefore English-only)
Guido van Rossum9264ecd2007-08-11 16:40:13 +000095 sentence_end_re = re.compile(r'[a-z]' # lowercase letter
Greg Ward9b4864e2002-06-07 22:04:15 +000096 r'[\.\!\?]' # sentence-ending punct.
97 r'[\"\']?' # optional end-of-quote
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000098 r'\Z') # end of chunk
Greg Ward62e4f3b2002-06-07 21:56:16 +000099
Greg Ward00935822002-06-07 21:43:37 +0000100
Greg Wardf0ba7642004-05-13 01:53:10 +0000101 def __init__(self,
102 width=70,
103 initial_indent="",
104 subsequent_indent="",
105 expand_tabs=True,
106 replace_whitespace=True,
107 fix_sentence_endings=False,
Guido van Rossumd8faa362007-04-27 19:54:29 +0000108 break_long_words=True,
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000109 drop_whitespace=True,
Hynek Schlawackd5272592012-05-19 13:33:11 +0200110 break_on_hyphens=True,
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300111 tabsize=8,
112 *,
113 max_lines=None,
114 placeholder=' [...]'):
Greg Wardd34c9592002-06-10 20:26:02 +0000115 self.width = width
Greg Ward62080be2002-06-10 21:37:12 +0000116 self.initial_indent = initial_indent
117 self.subsequent_indent = subsequent_indent
Greg Ward47df99d2002-06-09 00:22:07 +0000118 self.expand_tabs = expand_tabs
119 self.replace_whitespace = replace_whitespace
120 self.fix_sentence_endings = fix_sentence_endings
121 self.break_long_words = break_long_words
Guido van Rossumd8faa362007-04-27 19:54:29 +0000122 self.drop_whitespace = drop_whitespace
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000123 self.break_on_hyphens = break_on_hyphens
Hynek Schlawackd5272592012-05-19 13:33:11 +0200124 self.tabsize = tabsize
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300125 self.max_lines = max_lines
126 self.placeholder = placeholder
Tim Petersc411dba2002-07-16 21:35:23 +0000127
Greg Ward00935822002-06-07 21:43:37 +0000128
129 # -- Private methods -----------------------------------------------
130 # (possibly useful for subclasses to override)
131
Greg Wardcb320eb2002-06-07 22:32:15 +0000132 def _munge_whitespace(self, text):
Greg Ward00935822002-06-07 21:43:37 +0000133 """_munge_whitespace(text : string) -> string
134
135 Munge whitespace in text: expand tabs and convert all other
136 whitespace characters to spaces. Eg. " foo\tbar\n\nbaz"
137 becomes " foo bar baz".
138 """
139 if self.expand_tabs:
Hynek Schlawackd5272592012-05-19 13:33:11 +0200140 text = text.expandtabs(self.tabsize)
Greg Ward00935822002-06-07 21:43:37 +0000141 if self.replace_whitespace:
Georg Brandl7f13e6b2007-08-31 10:37:15 +0000142 text = text.translate(self.unicode_whitespace_trans)
Greg Ward00935822002-06-07 21:43:37 +0000143 return text
144
145
Greg Wardcb320eb2002-06-07 22:32:15 +0000146 def _split(self, text):
Greg Ward00935822002-06-07 21:43:37 +0000147 """_split(text : string) -> [string]
148
149 Split the text to wrap into indivisible chunks. Chunks are
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000150 not quite the same as words; see _wrap_chunks() for full
Greg Ward00935822002-06-07 21:43:37 +0000151 details. As an example, the text
152 Look, goof-ball -- use the -b option!
153 breaks into the following chunks:
154 'Look,', ' ', 'goof-', 'ball', ' ', '--', ' ',
155 'use', ' ', 'the', ' ', '-b', ' ', 'option!'
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000156 if break_on_hyphens is True, or in:
157 'Look,', ' ', 'goof-ball', ' ', '--', ' ',
158 'use', ' ', 'the', ' ', '-b', ' ', option!'
159 otherwise.
Greg Ward00935822002-06-07 21:43:37 +0000160 """
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000161 if self.break_on_hyphens is True:
162 chunks = self.wordsep_re.split(text)
163 else:
164 chunks = self.wordsep_simple_re.split(text)
Guido van Rossumc1f779c2007-07-03 08:25:58 +0000165 chunks = [c for c in chunks if c]
Greg Ward00935822002-06-07 21:43:37 +0000166 return chunks
167
Greg Wardcb320eb2002-06-07 22:32:15 +0000168 def _fix_sentence_endings(self, chunks):
Greg Ward00935822002-06-07 21:43:37 +0000169 """_fix_sentence_endings(chunks : [string])
170
171 Correct for sentence endings buried in 'chunks'. Eg. when the
172 original text contains "... foo.\nBar ...", munge_whitespace()
173 and split() will convert that to [..., "foo.", " ", "Bar", ...]
174 which has one too few spaces; this method simply changes the one
175 space to two.
176 """
177 i = 0
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000178 patsearch = self.sentence_end_re.search
Greg Ward00935822002-06-07 21:43:37 +0000179 while i < len(chunks)-1:
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000180 if chunks[i+1] == " " and patsearch(chunks[i]):
Greg Ward00935822002-06-07 21:43:37 +0000181 chunks[i+1] = " "
182 i += 2
183 else:
184 i += 1
185
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000186 def _handle_long_word(self, reversed_chunks, cur_line, cur_len, width):
Greg Ward00935822002-06-07 21:43:37 +0000187 """_handle_long_word(chunks : [string],
188 cur_line : [string],
Greg Ward62080be2002-06-10 21:37:12 +0000189 cur_len : int, width : int)
Greg Ward00935822002-06-07 21:43:37 +0000190
191 Handle a chunk of text (most likely a word, not whitespace) that
192 is too long to fit in any line.
193 """
Georg Brandlfceab5a2008-01-19 20:08:23 +0000194 # Figure out when indent is larger than the specified width, and make
195 # sure at least one character is stripped off on every pass
196 if width < 1:
197 space_left = 1
198 else:
199 space_left = width - cur_len
Greg Ward00935822002-06-07 21:43:37 +0000200
201 # If we're allowed to break long words, then do so: put as much
202 # of the next chunk onto the current line as will fit.
203 if self.break_long_words:
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000204 cur_line.append(reversed_chunks[-1][:space_left])
205 reversed_chunks[-1] = reversed_chunks[-1][space_left:]
Greg Ward00935822002-06-07 21:43:37 +0000206
207 # Otherwise, we have to preserve the long word intact. Only add
208 # it to the current line if there's nothing already there --
209 # that minimizes how much we violate the width constraint.
210 elif not cur_line:
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000211 cur_line.append(reversed_chunks.pop())
Greg Ward00935822002-06-07 21:43:37 +0000212
213 # If we're not allowed to break long words, and there's already
214 # text on the current line, do nothing. Next time through the
215 # main loop of _wrap_chunks(), we'll wind up here again, but
216 # cur_len will be zero, so the next line will be entirely
217 # devoted to the long word that we can't handle right now.
218
Greg Wardd34c9592002-06-10 20:26:02 +0000219 def _wrap_chunks(self, chunks):
220 """_wrap_chunks(chunks : [string]) -> [string]
Greg Ward00935822002-06-07 21:43:37 +0000221
222 Wrap a sequence of text chunks and return a list of lines of
Greg Wardd34c9592002-06-10 20:26:02 +0000223 length 'self.width' or less. (If 'break_long_words' is false,
224 some lines may be longer than this.) Chunks correspond roughly
225 to words and the whitespace between them: each chunk is
226 indivisible (modulo 'break_long_words'), but a line break can
227 come between any two chunks. Chunks should not have internal
228 whitespace; ie. a chunk is either all whitespace or a "word".
229 Whitespace chunks will be removed from the beginning and end of
230 lines, but apart from that whitespace is preserved.
Greg Ward00935822002-06-07 21:43:37 +0000231 """
232 lines = []
Greg Ward21820cd2003-05-07 00:55:35 +0000233 if self.width <= 0:
234 raise ValueError("invalid width %r (must be > 0)" % self.width)
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300235 if self.max_lines is not None:
236 if self.max_lines > 1:
237 indent = self.subsequent_indent
238 else:
239 indent = self.initial_indent
240 if len(indent) + len(self.placeholder.lstrip()) > self.width:
241 raise ValueError("placeholder too large for max width")
Greg Ward00935822002-06-07 21:43:37 +0000242
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000243 # Arrange in reverse order so items can be efficiently popped
244 # from a stack of chucks.
245 chunks.reverse()
246
Greg Ward00935822002-06-07 21:43:37 +0000247 while chunks:
248
Greg Ward62080be2002-06-10 21:37:12 +0000249 # Start the list of chunks that will make up the current line.
250 # cur_len is just the length of all the chunks in cur_line.
251 cur_line = []
252 cur_len = 0
253
254 # Figure out which static string will prefix this line.
255 if lines:
256 indent = self.subsequent_indent
257 else:
258 indent = self.initial_indent
259
260 # Maximum width for this line.
261 width = self.width - len(indent)
Greg Ward00935822002-06-07 21:43:37 +0000262
Greg Wardab73d462002-12-09 16:26:05 +0000263 # First chunk on line is whitespace -- drop it, unless this
264 # is the very beginning of the text (ie. no lines started yet).
Guido van Rossumd8faa362007-04-27 19:54:29 +0000265 if self.drop_whitespace and chunks[-1].strip() == '' and lines:
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000266 del chunks[-1]
Greg Ward00935822002-06-07 21:43:37 +0000267
268 while chunks:
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000269 l = len(chunks[-1])
Greg Ward00935822002-06-07 21:43:37 +0000270
271 # Can at least squeeze this chunk onto the current line.
272 if cur_len + l <= width:
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000273 cur_line.append(chunks.pop())
Greg Ward00935822002-06-07 21:43:37 +0000274 cur_len += l
275
276 # Nope, this line is full.
277 else:
278 break
279
280 # The current line is full, and the next chunk is too big to
Tim Petersc411dba2002-07-16 21:35:23 +0000281 # fit on *any* line (not just this one).
Raymond Hettinger8bfa8932005-07-15 06:53:35 +0000282 if chunks and len(chunks[-1]) > width:
Greg Ward62080be2002-06-10 21:37:12 +0000283 self._handle_long_word(chunks, cur_line, cur_len, width)
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300284 cur_len = sum(map(len, cur_line))
Greg Ward00935822002-06-07 21:43:37 +0000285
286 # If the last chunk on this line is all whitespace, drop it.
Guido van Rossumd8faa362007-04-27 19:54:29 +0000287 if self.drop_whitespace and cur_line and cur_line[-1].strip() == '':
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300288 cur_len -= len(cur_line[-1])
Greg Ward00935822002-06-07 21:43:37 +0000289 del cur_line[-1]
290
Greg Ward00935822002-06-07 21:43:37 +0000291 if cur_line:
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300292 if (self.max_lines is None or
293 len(lines) + 1 < self.max_lines or
294 (not chunks or
295 self.drop_whitespace and
296 len(chunks) == 1 and
297 not chunks[0].strip()) and cur_len <= width):
298 # Convert current line back to a string and store it in
299 # list of all lines (return value).
300 lines.append(indent + ''.join(cur_line))
301 else:
302 while cur_line:
303 if (cur_line[-1].strip() and
304 cur_len + len(self.placeholder) <= width):
305 cur_line.append(self.placeholder)
306 lines.append(indent + ''.join(cur_line))
307 break
308 cur_len -= len(cur_line[-1])
309 del cur_line[-1]
310 else:
311 if lines:
312 prev_line = lines[-1].rstrip()
313 if (len(prev_line) + len(self.placeholder) <=
314 self.width):
315 lines[-1] = prev_line + self.placeholder
316 break
317 lines.append(indent + self.placeholder.lstrip())
318 break
Greg Ward00935822002-06-07 21:43:37 +0000319
320 return lines
321
Antoine Pitrou389dec82013-08-12 22:39:09 +0200322 def _split_chunks(self, text):
323 text = self._munge_whitespace(text)
324 return self._split(text)
Greg Ward00935822002-06-07 21:43:37 +0000325
326 # -- Public interface ----------------------------------------------
327
Greg Wardd34c9592002-06-10 20:26:02 +0000328 def wrap(self, text):
329 """wrap(text : string) -> [string]
Greg Ward00935822002-06-07 21:43:37 +0000330
Greg Warde807e572002-07-04 14:51:49 +0000331 Reformat the single paragraph in 'text' so it fits in lines of
332 no more than 'self.width' columns, and return a list of wrapped
333 lines. Tabs in 'text' are expanded with string.expandtabs(),
334 and all other whitespace characters (including newline) are
335 converted to space.
Greg Ward00935822002-06-07 21:43:37 +0000336 """
Antoine Pitrou389dec82013-08-12 22:39:09 +0200337 chunks = self._split_chunks(text)
Greg Ward62e4f3b2002-06-07 21:56:16 +0000338 if self.fix_sentence_endings:
339 self._fix_sentence_endings(chunks)
Greg Wardd34c9592002-06-10 20:26:02 +0000340 return self._wrap_chunks(chunks)
Greg Ward00935822002-06-07 21:43:37 +0000341
Greg Ward62080be2002-06-10 21:37:12 +0000342 def fill(self, text):
343 """fill(text : string) -> string
Greg Ward00935822002-06-07 21:43:37 +0000344
Greg Warde807e572002-07-04 14:51:49 +0000345 Reformat the single paragraph in 'text' to fit in lines of no
346 more than 'self.width' columns, and return a new string
347 containing the entire wrapped paragraph.
Greg Ward00935822002-06-07 21:43:37 +0000348 """
Greg Ward62080be2002-06-10 21:37:12 +0000349 return "\n".join(self.wrap(text))
Greg Ward00935822002-06-07 21:43:37 +0000350
351
Greg Warde807e572002-07-04 14:51:49 +0000352# -- Convenience interface ---------------------------------------------
Greg Ward00935822002-06-07 21:43:37 +0000353
Greg Wardcf02ac62002-06-10 20:36:07 +0000354def wrap(text, width=70, **kwargs):
Greg Warde807e572002-07-04 14:51:49 +0000355 """Wrap a single paragraph of text, returning a list of wrapped lines.
356
357 Reformat the single paragraph in 'text' so it fits in lines of no
358 more than 'width' columns, and return a list of wrapped lines. By
359 default, tabs in 'text' are expanded with string.expandtabs(), and
360 all other whitespace characters (including newline) are converted to
361 space. See TextWrapper class for available keyword args to customize
362 wrapping behaviour.
363 """
Greg Wardcf02ac62002-06-10 20:36:07 +0000364 w = TextWrapper(width=width, **kwargs)
365 return w.wrap(text)
Greg Ward00935822002-06-07 21:43:37 +0000366
Greg Ward62080be2002-06-10 21:37:12 +0000367def fill(text, width=70, **kwargs):
Greg Warde807e572002-07-04 14:51:49 +0000368 """Fill a single paragraph of text, returning a new string.
369
370 Reformat the single paragraph in 'text' to fit in lines of no more
371 than 'width' columns, and return a new string containing the entire
372 wrapped paragraph. As with wrap(), tabs are expanded and other
373 whitespace characters converted to space. See TextWrapper class for
374 available keyword args to customize wrapping behaviour.
375 """
Greg Wardcf02ac62002-06-10 20:36:07 +0000376 w = TextWrapper(width=width, **kwargs)
Greg Ward62080be2002-06-10 21:37:12 +0000377 return w.fill(text)
Greg Ward478cd482003-05-08 01:58:05 +0000378
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300379def shorten(text, width, **kwargs):
Antoine Pitrou389dec82013-08-12 22:39:09 +0200380 """Collapse and truncate the given text to fit in the given width.
381
382 The text first has its whitespace collapsed. If it then fits in
383 the *width*, it is returned as is. Otherwise, as many words
384 as possible are joined and then the placeholder is appended::
385
386 >>> textwrap.shorten("Hello world!", width=12)
387 'Hello world!'
388 >>> textwrap.shorten("Hello world!", width=11)
Antoine Pitrouc5930562013-08-16 22:31:12 +0200389 'Hello [...]'
Antoine Pitrou389dec82013-08-12 22:39:09 +0200390 """
Serhiy Storchakaacc9f3f2013-10-15 21:22:54 +0300391 w = TextWrapper(width=width, max_lines=1, **kwargs)
392 return w.fill(' '.join(text.strip().split()))
Antoine Pitrou389dec82013-08-12 22:39:09 +0200393
Greg Ward478cd482003-05-08 01:58:05 +0000394
395# -- Loosely related functionality -------------------------------------
396
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000397_whitespace_only_re = re.compile('^[ \t]+$', re.MULTILINE)
398_leading_whitespace_re = re.compile('(^[ \t]*)(?:[^ \t\n])', re.MULTILINE)
399
Greg Ward478cd482003-05-08 01:58:05 +0000400def dedent(text):
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000401 """Remove any common leading whitespace from every line in `text`.
Greg Ward478cd482003-05-08 01:58:05 +0000402
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000403 This can be used to make triple-quoted strings line up with the left
404 edge of the display, while still presenting them in the source code
405 in indented form.
Greg Ward478cd482003-05-08 01:58:05 +0000406
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000407 Note that tabs and spaces are both treated as whitespace, but they
408 are not equal: the lines " hello" and "\thello" are
409 considered to have no common leading whitespace. (This behaviour is
410 new in Python 2.5; older versions of this module incorrectly
411 expanded tabs before searching for common leading whitespace.)
Greg Ward478cd482003-05-08 01:58:05 +0000412 """
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000413 # Look for the longest leading string of spaces and tabs common to
414 # all lines.
Greg Ward478cd482003-05-08 01:58:05 +0000415 margin = None
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000416 text = _whitespace_only_re.sub('', text)
417 indents = _leading_whitespace_re.findall(text)
418 for indent in indents:
Greg Ward478cd482003-05-08 01:58:05 +0000419 if margin is None:
420 margin = indent
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000421
422 # Current line more deeply indented than previous winner:
423 # no change (previous winner is still on top).
424 elif indent.startswith(margin):
425 pass
426
427 # Current line consistent with and no deeper than previous winner:
428 # it's the new winner.
429 elif margin.startswith(indent):
430 margin = indent
431
432 # Current line and previous winner have no common whitespace:
433 # there is no margin.
Greg Ward478cd482003-05-08 01:58:05 +0000434 else:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000435 margin = ""
436 break
Greg Ward478cd482003-05-08 01:58:05 +0000437
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000438 # sanity check (testing/debugging only)
439 if 0 and margin:
440 for line in text.split("\n"):
441 assert not line or line.startswith(margin), \
442 "line = %r, margin = %r" % (line, margin)
Greg Ward478cd482003-05-08 01:58:05 +0000443
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000444 if margin:
445 text = re.sub(r'(?m)^' + margin, '', text)
446 return text
447
Nick Coghlan4fae8cd2012-06-11 23:07:51 +1000448
449def indent(text, prefix, predicate=None):
450 """Adds 'prefix' to the beginning of selected lines in 'text'.
451
452 If 'predicate' is provided, 'prefix' will only be added to the lines
453 where 'predicate(line)' is True. If 'predicate' is not provided,
454 it will default to adding 'prefix' to all non-empty lines that do not
455 consist solely of whitespace characters.
456 """
457 if predicate is None:
458 def predicate(line):
459 return line.strip()
460
461 def prefixed_lines():
462 for line in text.splitlines(True):
463 yield (prefix + line if predicate(line) else line)
464 return ''.join(prefixed_lines())
465
466
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000467if __name__ == "__main__":
468 #print dedent("\tfoo\n\tbar")
469 #print dedent(" \thello there\n \t how are you?")
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000470 print(dedent("Hello there.\n This is indented."))