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