Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`textwrap` --- Text wrapping and filling |
| 2 | ============================================= |
| 3 | |
| 4 | .. module:: textwrap |
| 5 | :synopsis: Text wrapping and filling |
| 6 | .. moduleauthor:: Greg Ward <gward@python.net> |
| 7 | .. sectionauthor:: Greg Ward <gward@python.net> |
| 8 | |
| 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and |
| 11 | :func:`fill`, as well as :class:`TextWrapper`, the class that does all the work, |
| 12 | and a utility function :func:`dedent`. If you're just wrapping or filling one |
| 13 | or two text strings, the convenience functions should be good enough; |
| 14 | otherwise, you should use an instance of :class:`TextWrapper` for efficiency. |
| 15 | |
| 16 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 17 | .. function:: wrap(text, width=70, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 19 | Wraps the single paragraph in *text* (a string) so every line is at most |
| 20 | *width* characters long. Returns a list of output lines, without final |
| 21 | newlines. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | |
| 23 | Optional keyword arguments correspond to the instance attributes of |
| 24 | :class:`TextWrapper`, documented below. *width* defaults to ``70``. |
| 25 | |
| 26 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 27 | .. function:: fill(text, width=70, **kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
| 29 | Wraps the single paragraph in *text*, and returns a single string containing the |
| 30 | wrapped paragraph. :func:`fill` is shorthand for :: |
| 31 | |
| 32 | "\n".join(wrap(text, ...)) |
| 33 | |
| 34 | In particular, :func:`fill` accepts exactly the same keyword arguments as |
| 35 | :func:`wrap`. |
| 36 | |
| 37 | Both :func:`wrap` and :func:`fill` work by creating a :class:`TextWrapper` |
| 38 | instance and calling a single method on it. That instance is not reused, so for |
| 39 | applications that wrap/fill many text strings, it will be more efficient for you |
| 40 | to create your own :class:`TextWrapper` object. |
| 41 | |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 42 | Text is preferably wrapped on whitespaces and right after the hyphens in |
| 43 | hyphenated words; only then will long words be broken if necessary, unless |
| 44 | :attr:`TextWrapper.break_long_words` is set to false. |
| 45 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | An additional utility function, :func:`dedent`, is provided to remove |
| 47 | indentation from strings that have unwanted whitespace to the left of the text. |
| 48 | |
| 49 | |
| 50 | .. function:: dedent(text) |
| 51 | |
| 52 | Remove any common leading whitespace from every line in *text*. |
| 53 | |
| 54 | This can be used to make triple-quoted strings line up with the left edge of the |
| 55 | display, while still presenting them in the source code in indented form. |
| 56 | |
| 57 | Note that tabs and spaces are both treated as whitespace, but they are not |
| 58 | equal: the lines ``" hello"`` and ``"\thello"`` are considered to have no |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 59 | common leading whitespace. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | For example:: |
| 62 | |
| 63 | def test(): |
| 64 | # end first line with \ to avoid the empty line! |
| 65 | s = '''\ |
| 66 | hello |
| 67 | world |
| 68 | ''' |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 69 | print(repr(s)) # prints ' hello\n world\n ' |
| 70 | print(repr(dedent(s))) # prints 'hello\n world\n' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 73 | .. class:: TextWrapper(**kwargs) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
| 75 | The :class:`TextWrapper` constructor accepts a number of optional keyword |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 76 | arguments. Each keyword argument corresponds to an instance attribute, so |
| 77 | for example :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | wrapper = TextWrapper(initial_indent="* ") |
| 80 | |
| 81 | is the same as :: |
| 82 | |
| 83 | wrapper = TextWrapper() |
| 84 | wrapper.initial_indent = "* " |
| 85 | |
| 86 | You can re-use the same :class:`TextWrapper` object many times, and you can |
| 87 | change any of its options through direct assignment to instance attributes |
| 88 | between uses. |
| 89 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 90 | The :class:`TextWrapper` instance attributes (and keyword arguments to the |
| 91 | constructor) are as follows: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 94 | .. attribute:: width |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 96 | (default: ``70``) The maximum length of wrapped lines. As long as there |
| 97 | are no individual words in the input text longer than :attr:`width`, |
| 98 | :class:`TextWrapper` guarantees that no output line will be longer than |
| 99 | :attr:`width` characters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 102 | .. attribute:: expand_tabs |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 104 | (default: ``True``) If true, then all tab characters in *text* will be |
| 105 | expanded to spaces using the :meth:`expandtabs` method of *text*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
| 107 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 108 | .. attribute:: replace_whitespace |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 110 | (default: ``True``) If true, each whitespace character (as defined by |
| 111 | ``string.whitespace``) remaining after tab expansion will be replaced by a |
| 112 | single space. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 114 | .. note:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 116 | If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, |
| 117 | each tab character will be replaced by a single space, which is *not* |
| 118 | the same as tab expansion. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
| 120 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 121 | .. attribute:: drop_whitespace |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 123 | (default: ``True``) If true, whitespace that, after wrapping, happens to |
| 124 | end up at the beginning or end of a line is dropped (leading whitespace in |
| 125 | the first line is always preserved, though). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 128 | .. attribute:: initial_indent |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 130 | (default: ``''``) String that will be prepended to the first line of |
| 131 | wrapped output. Counts towards the length of the first line. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 134 | .. attribute:: subsequent_indent |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 136 | (default: ``''``) String that will be prepended to all lines of wrapped |
| 137 | output except the first. Counts towards the length of each line except |
| 138 | the first. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | |
| 140 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 141 | .. attribute:: fix_sentence_endings |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 143 | (default: ``False``) If true, :class:`TextWrapper` attempts to detect |
| 144 | sentence endings and ensure that sentences are always separated by exactly |
| 145 | two spaces. This is generally desired for text in a monospaced font. |
| 146 | However, the sentence detection algorithm is imperfect: it assumes that a |
| 147 | sentence ending consists of a lowercase letter followed by one of ``'.'``, |
| 148 | ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``, |
| 149 | followed by a space. One problem with this is algorithm is that it is |
| 150 | unable to detect the difference between "Dr." in :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 152 | [...] Dr. Frankenstein's monster [...] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 154 | and "Spot." in :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 156 | [...] See Spot. See Spot run [...] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 158 | :attr:`fix_sentence_endings` is false by default. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 160 | Since the sentence detection algorithm relies on ``string.lowercase`` for |
| 161 | the definition of "lowercase letter," and a convention of using two spaces |
| 162 | after a period to separate sentences on the same line, it is specific to |
| 163 | English-language texts. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |
| 165 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 166 | .. attribute:: break_long_words |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 168 | (default: ``True``) If true, then words longer than :attr:`width` will be |
| 169 | broken in order to ensure that no lines are longer than :attr:`width`. If |
| 170 | it is false, long words will not be broken, and some lines may be longer |
| 171 | than :attr:`width`. (Long words will be put on a line by themselves, in |
| 172 | order to minimize the amount by which :attr:`width` is exceeded.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 174 | |
| 175 | .. attribute:: break_on_hyphens |
| 176 | |
| 177 | (default: ``True``) If true, wrapping will occur preferably on whitespaces |
| 178 | and right after hyphens in compound words, as it is customary in English. |
| 179 | If false, only whitespaces will be considered as potentially good places |
| 180 | for line breaks, but you need to set :attr:`break_long_words` to false if |
| 181 | you want truly insecable words. Default behaviour in previous versions |
| 182 | was to always allow breaking hyphenated words. |
| 183 | |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 184 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 185 | :class:`TextWrapper` also provides two public methods, analogous to the |
| 186 | module-level convenience functions: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 188 | .. method:: wrap(text) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 190 | Wraps the single paragraph in *text* (a string) so every line is at most |
| 191 | :attr:`width` characters long. All wrapping options are taken from |
| 192 | instance attributes of the :class:`TextWrapper` instance. Returns a list |
| 193 | of output lines, without final newlines. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | |
| 195 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 196 | .. method:: fill(text) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 197 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 198 | Wraps the single paragraph in *text*, and returns a single string |
| 199 | containing the wrapped paragraph. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | |