1:mod:`textwrap` --- Text wrapping and filling 2============================================= 3 4.. module:: textwrap 5 :synopsis: Text wrapping and filling 6 7.. moduleauthor:: Greg Ward <gward@python.net> 8.. sectionauthor:: Greg Ward <gward@python.net> 9 10**Source code:** :source:`Lib/textwrap.py` 11 12-------------- 13 14The :mod:`textwrap` module provides some convenience functions, 15as well as :class:`TextWrapper`, the class that does all the work. 16If you're just wrapping or filling one or two text strings, the convenience 17functions should be good enough; otherwise, you should use an instance of 18:class:`TextWrapper` for efficiency. 19 20.. function:: wrap(text, width=70, **kwargs) 21 22 Wraps the single paragraph in *text* (a string) so every line is at most 23 *width* characters long. Returns a list of output lines, without final 24 newlines. 25 26 Optional keyword arguments correspond to the instance attributes of 27 :class:`TextWrapper`, documented below. *width* defaults to ``70``. 28 29 See the :meth:`TextWrapper.wrap` method for additional details on how 30 :func:`wrap` behaves. 31 32 33.. function:: fill(text, width=70, **kwargs) 34 35 Wraps the single paragraph in *text*, and returns a single string containing the 36 wrapped paragraph. :func:`fill` is shorthand for :: 37 38 "\n".join(wrap(text, ...)) 39 40 In particular, :func:`fill` accepts exactly the same keyword arguments as 41 :func:`wrap`. 42 43 44.. function:: shorten(text, width, **kwargs) 45 46 Collapse and truncate the given *text* to fit in the given *width*. 47 48 First the whitespace in *text* is collapsed (all whitespace is replaced by 49 single spaces). If the result fits in the *width*, it is returned. 50 Otherwise, enough words are dropped from the end so that the remaining words 51 plus the :attr:`placeholder` fit within :attr:`width`:: 52 53 >>> textwrap.shorten("Hello world!", width=12) 54 'Hello world!' 55 >>> textwrap.shorten("Hello world!", width=11) 56 'Hello [...]' 57 >>> textwrap.shorten("Hello world", width=10, placeholder="...") 58 'Hello...' 59 60 Optional keyword arguments correspond to the instance attributes of 61 :class:`TextWrapper`, documented below. Note that the whitespace is 62 collapsed before the text is passed to the :class:`TextWrapper` :meth:`fill` 63 function, so changing the value of :attr:`.tabsize`, :attr:`.expand_tabs`, 64 :attr:`.drop_whitespace`, and :attr:`.replace_whitespace` will have no effect. 65 66 .. versionadded:: 3.4 67 68 69.. function:: dedent(text) 70 71 Remove any common leading whitespace from every line in *text*. 72 73 This can be used to make triple-quoted strings line up with the left edge of the 74 display, while still presenting them in the source code in indented form. 75 76 Note that tabs and spaces are both treated as whitespace, but they are not 77 equal: the lines ``" hello"`` and ``"\thello"`` are considered to have no 78 common leading whitespace. 79 80 Lines containing only whitespace are ignored in the input and normalized to a 81 single newline character in the output. 82 83 For example:: 84 85 def test(): 86 # end first line with \ to avoid the empty line! 87 s = '''\ 88 hello 89 world 90 ''' 91 print(repr(s)) # prints ' hello\n world\n ' 92 print(repr(dedent(s))) # prints 'hello\n world\n' 93 94 95.. function:: indent(text, prefix, predicate=None) 96 97 Add *prefix* to the beginning of selected lines in *text*. 98 99 Lines are separated by calling ``text.splitlines(True)``. 100 101 By default, *prefix* is added to all lines that do not consist 102 solely of whitespace (including any line endings). 103 104 For example:: 105 106 >>> s = 'hello\n\n \nworld' 107 >>> indent(s, ' ') 108 ' hello\n\n \n world' 109 110 The optional *predicate* argument can be used to control which lines 111 are indented. For example, it is easy to add *prefix* to even empty 112 and whitespace-only lines:: 113 114 >>> print(indent(s, '+ ', lambda line: True)) 115 + hello 116 + 117 + 118 + world 119 120 .. versionadded:: 3.3 121 122 123:func:`wrap`, :func:`fill` and :func:`shorten` work by creating a 124:class:`TextWrapper` instance and calling a single method on it. That 125instance is not reused, so for applications that process many text 126strings using :func:`wrap` and/or :func:`fill`, it may be more efficient to 127create your own :class:`TextWrapper` object. 128 129Text is preferably wrapped on whitespaces and right after the hyphens in 130hyphenated words; only then will long words be broken if necessary, unless 131:attr:`TextWrapper.break_long_words` is set to false. 132 133.. class:: TextWrapper(**kwargs) 134 135 The :class:`TextWrapper` constructor accepts a number of optional keyword 136 arguments. Each keyword argument corresponds to an instance attribute, so 137 for example :: 138 139 wrapper = TextWrapper(initial_indent="* ") 140 141 is the same as :: 142 143 wrapper = TextWrapper() 144 wrapper.initial_indent = "* " 145 146 You can re-use the same :class:`TextWrapper` object many times, and you can 147 change any of its options through direct assignment to instance attributes 148 between uses. 149 150 The :class:`TextWrapper` instance attributes (and keyword arguments to the 151 constructor) are as follows: 152 153 154 .. attribute:: width 155 156 (default: ``70``) The maximum length of wrapped lines. As long as there 157 are no individual words in the input text longer than :attr:`width`, 158 :class:`TextWrapper` guarantees that no output line will be longer than 159 :attr:`width` characters. 160 161 162 .. attribute:: expand_tabs 163 164 (default: ``True``) If true, then all tab characters in *text* will be 165 expanded to spaces using the :meth:`expandtabs` method of *text*. 166 167 168 .. attribute:: tabsize 169 170 (default: ``8``) If :attr:`expand_tabs` is true, then all tab characters 171 in *text* will be expanded to zero or more spaces, depending on the 172 current column and the given tab size. 173 174 .. versionadded:: 3.3 175 176 177 .. attribute:: replace_whitespace 178 179 (default: ``True``) If true, after tab expansion but before wrapping, 180 the :meth:`wrap` method will replace each whitespace character 181 with a single space. The whitespace characters replaced are 182 as follows: tab, newline, vertical tab, formfeed, and carriage 183 return (``'\t\n\v\f\r'``). 184 185 .. note:: 186 187 If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, 188 each tab character will be replaced by a single space, which is *not* 189 the same as tab expansion. 190 191 .. note:: 192 193 If :attr:`replace_whitespace` is false, newlines may appear in the 194 middle of a line and cause strange output. For this reason, text should 195 be split into paragraphs (using :meth:`str.splitlines` or similar) 196 which are wrapped separately. 197 198 199 .. attribute:: drop_whitespace 200 201 (default: ``True``) If true, whitespace at the beginning and ending of 202 every line (after wrapping but before indenting) is dropped. 203 Whitespace at the beginning of the paragraph, however, is not dropped 204 if non-whitespace follows it. If whitespace being dropped takes up an 205 entire line, the whole line is dropped. 206 207 208 .. attribute:: initial_indent 209 210 (default: ``''``) String that will be prepended to the first line of 211 wrapped output. Counts towards the length of the first line. The empty 212 string is not indented. 213 214 215 .. attribute:: subsequent_indent 216 217 (default: ``''``) String that will be prepended to all lines of wrapped 218 output except the first. Counts towards the length of each line except 219 the first. 220 221 222 .. attribute:: fix_sentence_endings 223 224 (default: ``False``) If true, :class:`TextWrapper` attempts to detect 225 sentence endings and ensure that sentences are always separated by exactly 226 two spaces. This is generally desired for text in a monospaced font. 227 However, the sentence detection algorithm is imperfect: it assumes that a 228 sentence ending consists of a lowercase letter followed by one of ``'.'``, 229 ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``, 230 followed by a space. One problem with this is algorithm is that it is 231 unable to detect the difference between "Dr." in :: 232 233 [...] Dr. Frankenstein's monster [...] 234 235 and "Spot." in :: 236 237 [...] See Spot. See Spot run [...] 238 239 :attr:`fix_sentence_endings` is false by default. 240 241 Since the sentence detection algorithm relies on ``string.lowercase`` for 242 the definition of "lowercase letter", and a convention of using two spaces 243 after a period to separate sentences on the same line, it is specific to 244 English-language texts. 245 246 247 .. attribute:: break_long_words 248 249 (default: ``True``) If true, then words longer than :attr:`width` will be 250 broken in order to ensure that no lines are longer than :attr:`width`. If 251 it is false, long words will not be broken, and some lines may be longer 252 than :attr:`width`. (Long words will be put on a line by themselves, in 253 order to minimize the amount by which :attr:`width` is exceeded.) 254 255 256 .. attribute:: break_on_hyphens 257 258 (default: ``True``) If true, wrapping will occur preferably on whitespaces 259 and right after hyphens in compound words, as it is customary in English. 260 If false, only whitespaces will be considered as potentially good places 261 for line breaks, but you need to set :attr:`break_long_words` to false if 262 you want truly insecable words. Default behaviour in previous versions 263 was to always allow breaking hyphenated words. 264 265 266 .. attribute:: max_lines 267 268 (default: ``None``) If not ``None``, then the output will contain at most 269 *max_lines* lines, with *placeholder* appearing at the end of the output. 270 271 .. versionadded:: 3.4 272 273 274 .. index:: single: ...; placeholder 275 276 .. attribute:: placeholder 277 278 (default: ``' [...]'``) String that will appear at the end of the output 279 text if it has been truncated. 280 281 .. versionadded:: 3.4 282 283 284 :class:`TextWrapper` also provides some public methods, analogous to the 285 module-level convenience functions: 286 287 .. method:: wrap(text) 288 289 Wraps the single paragraph in *text* (a string) so every line is at most 290 :attr:`width` characters long. All wrapping options are taken from 291 instance attributes of the :class:`TextWrapper` instance. Returns a list 292 of output lines, without final newlines. If the wrapped output has no 293 content, the returned list is empty. 294 295 296 .. method:: fill(text) 297 298 Wraps the single paragraph in *text*, and returns a single string 299 containing the wrapped paragraph. 300