Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 1 | \section{\module{textwrap} --- |
| 2 | Text wrapping and filling} |
| 3 | |
| 4 | \declaremodule{standard}{textwrap} |
| 5 | \modulesynopsis{Text wrapping and filling} |
| 6 | \moduleauthor{Greg Ward}{gward@python.net} |
| 7 | \sectionauthor{Greg Ward}{gward@python.net} |
| 8 | |
| 9 | \versionadded{2.3} |
| 10 | |
| 11 | The \module{textwrap} module provides two convenience functions, |
| 12 | \function{wrap()} and \function{fill()}, as well as |
Greg Ward | 8f6329c | 2003-05-08 02:09:49 +0000 | [diff] [blame] | 13 | \class{TextWrapper}, the class that does all the work, and a utility function |
| 14 | \function{dedent()}. If you're just wrapping or filling one or two |
| 15 | text strings, the convenience functions should be good enough; otherwise, |
| 16 | you should use an instance of \class{TextWrapper} for efficiency. |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 17 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 18 | \begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}} |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 19 | Wraps the single paragraph in \var{text} (a string) so every line is at |
| 20 | most \var{width} characters long. Returns a list of output lines, |
| 21 | without final newlines. |
| 22 | |
| 23 | Optional keyword arguments correspond to the instance attributes of |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 24 | \class{TextWrapper}, documented below. \var{width} defaults to |
| 25 | \code{70}. |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 26 | \end{funcdesc} |
| 27 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 28 | \begin{funcdesc}{fill}{text\optional{, width\optional{, \moreargs}}} |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 29 | Wraps the single paragraph in \var{text}, and returns a single string |
| 30 | containing the wrapped paragraph. \function{fill()} is shorthand for |
| 31 | \begin{verbatim} |
| 32 | "\n".join(wrap(text, ...)) |
| 33 | \end{verbatim} |
| 34 | |
| 35 | In particular, \function{fill()} accepts exactly the same keyword |
| 36 | arguments as \function{wrap()}. |
| 37 | \end{funcdesc} |
| 38 | |
| 39 | Both \function{wrap()} and \function{fill()} work by creating a |
| 40 | \class{TextWrapper} instance and calling a single method on it. That |
| 41 | instance is not reused, so for applications that wrap/fill many text |
| 42 | strings, it will be more efficient for you to create your own |
| 43 | \class{TextWrapper} object. |
| 44 | |
Greg Ward | 8f6329c | 2003-05-08 02:09:49 +0000 | [diff] [blame] | 45 | An additional utility function, \function{dedent()}, is provided to |
| 46 | remove indentation from strings that have unwanted whitespace to the |
| 47 | left of the text. |
| 48 | |
| 49 | \begin{funcdesc}{dedent}{text} |
Raymond Hettinger | 4c9800d | 2004-02-08 18:09:32 +0000 | [diff] [blame] | 50 | Remove any whitespace that can be uniformly removed from the left |
Greg Ward | 8f6329c | 2003-05-08 02:09:49 +0000 | [diff] [blame] | 51 | of every line in \var{text}. |
| 52 | |
| 53 | This is typically used to make triple-quoted strings line up with |
| 54 | the left edge of screen/whatever, while still presenting it in the |
| 55 | source code in indented form. |
| 56 | |
| 57 | For example: |
| 58 | \begin{verbatim} |
| 59 | def test(): |
| 60 | # end first line with \ to avoid the empty line! |
| 61 | s = '''\ |
Greg Ward | 86e1790 | 2003-05-08 02:12:35 +0000 | [diff] [blame] | 62 | hello |
| 63 | world |
Greg Ward | 8f6329c | 2003-05-08 02:09:49 +0000 | [diff] [blame] | 64 | ''' |
Greg Ward | 86e1790 | 2003-05-08 02:12:35 +0000 | [diff] [blame] | 65 | print repr(s) # prints ' hello\n world\n ' |
| 66 | print repr(dedent(s)) # prints 'hello\n world\n' |
Greg Ward | 8f6329c | 2003-05-08 02:09:49 +0000 | [diff] [blame] | 67 | \end{verbatim} |
| 68 | \end{funcdesc} |
| 69 | |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 70 | \begin{classdesc}{TextWrapper}{...} |
| 71 | The \class{TextWrapper} constructor accepts a number of optional |
| 72 | keyword arguments. Each argument corresponds to one instance attribute, |
| 73 | so for example |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 74 | \begin{verbatim} |
| 75 | wrapper = TextWrapper(initial_indent="* ") |
| 76 | \end{verbatim} |
| 77 | is the same as |
| 78 | \begin{verbatim} |
| 79 | wrapper = TextWrapper() |
| 80 | wrapper.initial_indent = "* " |
| 81 | \end{verbatim} |
| 82 | |
| 83 | You can re-use the same \class{TextWrapper} object many times, and you |
| 84 | can change any of its options through direct assignment to instance |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 85 | attributes between uses. |
| 86 | \end{classdesc} |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 87 | |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 88 | The \class{TextWrapper} instance attributes (and keyword arguments to |
| 89 | the constructor) are as follows: |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 90 | |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 91 | \begin{memberdesc}{width} |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 92 | (default: \code{70}) The maximum length of wrapped lines. As long as |
| 93 | there are no individual words in the input text longer than |
| 94 | \member{width}, \class{TextWrapper} guarantees that no output line |
| 95 | will be longer than \member{width} characters. |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 96 | \end{memberdesc} |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 97 | |
| 98 | \begin{memberdesc}{expand_tabs} |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 99 | (default: \code{True}) If true, then all tab characters in \var{text} |
| 100 | will be expanded to spaces using the \method{expand_tabs()} method of |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 101 | \var{text}. |
| 102 | \end{memberdesc} |
| 103 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 104 | \begin{memberdesc}{replace_whitespace} |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 105 | (default: \code{True}) If true, each whitespace character (as defined |
| 106 | by \code{string.whitespace}) remaining after tab expansion will be |
| 107 | replaced by a single space. \note{If \member{expand_tabs} is false |
| 108 | and \member{replace_whitespace} is true, each tab character will be |
| 109 | replaced by a single space, which is \emph{not} the same as tab |
| 110 | expansion.} |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 111 | \end{memberdesc} |
| 112 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 113 | \begin{memberdesc}{initial_indent} |
| 114 | (default: \code{''}) String that will be prepended to the first line |
| 115 | of wrapped output. Counts towards the length of the first line. |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 116 | \end{memberdesc} |
| 117 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 118 | \begin{memberdesc}{subsequent_indent} |
| 119 | (default: \code{''}) String that will be prepended to all lines of |
| 120 | wrapped output except the first. Counts towards the length of each |
| 121 | line except the first. |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 122 | \end{memberdesc} |
| 123 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 124 | \begin{memberdesc}{fix_sentence_endings} |
| 125 | (default: \code{False}) If true, \class{TextWrapper} attempts to detect |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 126 | sentence endings and ensure that sentences are always separated by |
| 127 | exactly two spaces. This is generally desired for text in a monospaced |
| 128 | font. However, the sentence detection algorithm is imperfect: it |
| 129 | assumes that a sentence ending consists of a lowercase letter followed |
| 130 | by one of \character{.}, |
| 131 | \character{!}, or \character{?}, possibly followed by one of |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 132 | \character{"} or \character{'}, followed by a space. One problem |
| 133 | with this is algorithm is that it is unable to detect the difference |
| 134 | between ``Dr.'' in |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 135 | |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 136 | \begin{verbatim} |
| 137 | [...] Dr. Frankenstein's monster [...] |
| 138 | \end{verbatim} |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 139 | |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 140 | and ``Spot.'' in |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 141 | |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 142 | \begin{verbatim} |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 143 | [...] See Spot. See Spot run [...] |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 144 | \end{verbatim} |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 145 | |
| 146 | \member{fix_sentence_endings} is false by default. |
| 147 | |
| 148 | Since the sentence detection algorithm relies on |
| 149 | \code{string.lowercase} for the definition of ``lowercase letter,'' |
| 150 | and a convention of using two spaces after a period to separate |
| 151 | sentences on the same line, it is specific to English-language texts. |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 152 | \end{memberdesc} |
| 153 | |
Fred Drake | ca23ee2 | 2002-07-02 20:37:12 +0000 | [diff] [blame] | 154 | \begin{memberdesc}{break_long_words} |
Greg Ward | 285f4a7 | 2002-07-02 21:48:12 +0000 | [diff] [blame] | 155 | (default: \code{True}) If true, then words longer than |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 156 | \member{width} will be broken in order to ensure that no lines are |
| 157 | longer than \member{width}. If it is false, long words will not be |
| 158 | broken, and some lines may be longer than \member{width}. (Long words |
| 159 | will be put on a line by themselves, in order to minimize the amount |
| 160 | by which \member{width} is exceeded.) |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 161 | \end{memberdesc} |
| 162 | |
| 163 | \class{TextWrapper} also provides two public methods, analogous to the |
| 164 | module-level convenience functions: |
| 165 | |
| 166 | \begin{methoddesc}{wrap}{text} |
Fred Drake | 228f6e4 | 2002-07-03 05:08:48 +0000 | [diff] [blame] | 167 | Wraps the single paragraph in \var{text} (a string) so every line is |
| 168 | at most \member{width} characters long. All wrapping options are |
| 169 | taken from instance attributes of the \class{TextWrapper} instance. |
| 170 | Returns a list of output lines, without final newlines. |
Greg Ward | ae64f3ad | 2002-06-29 02:38:50 +0000 | [diff] [blame] | 171 | \end{methoddesc} |
| 172 | |
| 173 | \begin{methoddesc}{fill}{text} |
| 174 | Wraps the single paragraph in \var{text}, and returns a single string |
| 175 | containing the wrapped paragraph. |
| 176 | \end{methoddesc} |