Mercurial > cpython-lru_cache-weakref

annotate Doc/library/textwrap.rst @ 54294:dba767bc3155 legacy-trunk

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