rest25/library/textwrap.rst => rest262/library/textwrap.rst
36   In particular, :func:`fill` accepts exactly the same keyword arguments as
37   :func:`wrap`.
38
39Both :func:`wrap` and :func:`fill` work by creating a :class:`TextWrapper`
40instance and calling a single method on it.  That instance is not reused, so for
41applications that wrap/fill many text strings, it will be more efficient for you
42to create your own :class:`TextWrapper` object.
43
n44+Text is preferably wrapped on whitespaces and right after the hyphens in
45+hyphenated words; only then will long words be broken if necessary, unless
46+:attr:`TextWrapper.break_long_words` is set to false.
47+ 
44An additional utility function, :func:`dedent`, is provided to remove
45indentation from strings that have unwanted whitespace to the left of the text.
46
47
48.. function:: dedent(text)
49
50   Remove any common leading whitespace from every line in *text*.
51
52   This can be used to make triple-quoted strings line up with the left edge of the
53   display, while still presenting them in the source code in indented form.
54
55   Note that tabs and spaces are both treated as whitespace, but they are not
n56-   equal: the lines ``"  hello"`` and ``"\\thello"`` are considered to have no
n60+   equal: the lines ``"  hello"`` and ``"\thello"`` are considered to have no
57   common leading whitespace.  (This behaviour is new in Python 2.5; older versions
58   of this module incorrectly expanded tabs before searching for common leading
59   whitespace.)
60
61   For example::
62
63      def test():
64          # end first line with \ to avoid the empty line!
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
n90-The :class:`TextWrapper` instance attributes (and keyword arguments to the
n94+   The :class:`TextWrapper` instance attributes (and keyword arguments to the
91-constructor) are as follows:
95+   constructor) are as follows:
92
93
n94-.. attribute:: TextWrapper.width
n98+   .. attribute:: width
95
n96-   (default: ``70``) The maximum length of wrapped lines.  As long as there are no
n100+      (default: ``70``) The maximum length of wrapped lines.  As long as there
97-   individual words in the input text longer than :attr:`width`,
101+      are no individual words in the input text longer than :attr:`width`,
98-   :class:`TextWrapper` guarantees that no output line will be longer than
102+      :class:`TextWrapper` guarantees that no output line will be longer than
99-   :attr:`width` characters.
103+      :attr:`width` characters.
100
101
n102-.. attribute:: TextWrapper.expand_tabs
n106+   .. attribute:: expand_tabs
103
n104-   (default: ``True``) If true, then all tab characters in *text* will be expanded
n108+      (default: ``True``) If true, then all tab characters in *text* will be
105-   to spaces using the :meth:`expandtabs` method of *text*.
109+      expanded to spaces using the :meth:`expandtabs` method of *text*.
106
107
n108-.. attribute:: TextWrapper.replace_whitespace
n112+   .. attribute:: replace_whitespace
109
n110-   (default: ``True``) If true, each whitespace character (as defined by
n114+      (default: ``True``) If true, each whitespace character (as defined by
111-   ``string.whitespace``) remaining after tab expansion will be replaced by a
115+      ``string.whitespace``) remaining after tab expansion will be replaced by a
112-   single space.
116+      single space.
113
n114-   .. note::
n118+      .. note::
115
n116-      If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, each tab
n120+         If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true,
117-      character will be replaced by a single space, which is *not* the same as tab
121+         each tab character will be replaced by a single space, which is *not*
118-      expansion.
122+         the same as tab expansion.
119
120
n125+   .. attribute:: drop_whitespace
126+ 
127+      (default: ``True``) If true, whitespace that, after wrapping, happens to
128+      end up at the beginning or end of a line is dropped (leading whitespace in
129+      the first line is always preserved, though).
130+ 
131+      .. versionadded:: 2.6
132+         Whitespace was always dropped in earlier versions.
133+ 
134+ 
121-.. attribute:: TextWrapper.initial_indent
135+   .. attribute:: initial_indent
122
n123-   (default: ``''``) String that will be prepended to the first line of wrapped
n137+      (default: ``''``) String that will be prepended to the first line of
124-   output.  Counts towards the length of the first line.
138+      wrapped output.  Counts towards the length of the first line.
125
126
n127-.. attribute:: TextWrapper.subsequent_indent
n141+   .. attribute:: subsequent_indent
128
n129-   (default: ``''``) String that will be prepended to all lines of wrapped output
n143+      (default: ``''``) String that will be prepended to all lines of wrapped
130-   except the first.  Counts towards the length of each line except the first.
144+      output except the first.  Counts towards the length of each line except
145+      the first.
131
132
n133-.. attribute:: TextWrapper.fix_sentence_endings
n148+   .. attribute:: fix_sentence_endings
134
n135-   (default: ``False``) If true, :class:`TextWrapper` attempts to detect sentence
n150+      (default: ``False``) If true, :class:`TextWrapper` attempts to detect
136-   endings and ensure that sentences are always separated by exactly two spaces.
151+      sentence endings and ensure that sentences are always separated by exactly
137-   This is generally desired for text in a monospaced font.  However, the sentence
152+      two spaces.  This is generally desired for text in a monospaced font.
138-   detection algorithm is imperfect: it assumes that a sentence ending consists of
153+      However, the sentence detection algorithm is imperfect: it assumes that a
139-   a lowercase letter followed by one of ``'.'``, ``'!'``, or ``'?'``, possibly
154+      sentence ending consists of a lowercase letter followed by one of ``'.'``,
140-   followed by one of ``'"'`` or ``'''``, followed by a space.  One problem with
155+      ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``,
141-   this is algorithm is that it is unable to detect the difference between "Dr." in
156+      followed by a space.  One problem with this is algorithm is that it is
142-   ::
157+      unable to detect the difference between "Dr." in ::
143
n144-      [...] Dr. Frankenstein's monster [...]
n159+         [...] Dr. Frankenstein's monster [...]
145
n146-   and "Spot." in ::
n161+      and "Spot." in ::
147
n148-      [...] See Spot. See Spot run [...]
n163+         [...] See Spot. See Spot run [...]
149
n150-   :attr:`fix_sentence_endings` is false by default.
n165+      :attr:`fix_sentence_endings` is false by default.
151
n152-   Since the sentence detection algorithm relies on ``string.lowercase`` for the
n167+      Since the sentence detection algorithm relies on ``string.lowercase`` for
153-   definition of "lowercase letter," and a convention of using two spaces after a
168+      the definition of "lowercase letter," and a convention of using two spaces
154-   period to separate sentences on the same line, it is specific to English-
169+      after a period to separate sentences on the same line, it is specific to
155-   language texts.
170+      English-language texts.
156
157
n158-.. attribute:: TextWrapper.break_long_words
n173+   .. attribute:: break_long_words
159
n160-   (default: ``True``) If true, then words longer than :attr:`width` will be broken
n175+      (default: ``True``) If true, then words longer than :attr:`width` will be
161-   in order to ensure that no lines are longer than :attr:`width`.  If it is false,
176+      broken in order to ensure that no lines are longer than :attr:`width`.  If
162-   long words will not be broken, and some lines may be longer than :attr:`width`.
177+      it is false, long words will not be broken, and some lines may be longer
163-   (Long words will be put on a line by themselves, in order to minimize the amount
178+      than :attr:`width`.  (Long words will be put on a line by themselves, in
164-   by which :attr:`width` is exceeded.)
179+      order to minimize the amount by which :attr:`width` is exceeded.)
165
n181+ 
182+   .. attribute:: break_on_hyphens
183+ 
184+      (default: ``True``) If true, wrapping will occur preferably on whitespaces
185+      and right after hyphens in compound words, as it is customary in English.
186+      If false, only whitespaces will be considered as potentially good places
187+      for line breaks, but you need to set :attr:`break_long_words` to false if
188+      you want truly insecable words.  Default behaviour in previous versions
189+      was to always allow breaking hyphenated words.
190+ 
191+      .. versionadded:: 2.6
192+ 
193+ 
166-:class:`TextWrapper` also provides two public methods, analogous to the module-
194+   :class:`TextWrapper` also provides two public methods, analogous to the
167-level convenience functions:
195+   module-level convenience functions:
168
n197+   .. method:: wrap(text)
169
n170-.. method:: TextWrapper.wrap(text)
171- 
172-   Wraps the single paragraph in *text* (a string) so every line is at most
199+      Wraps the single paragraph in *text* (a string) so every line is at most
173-   :attr:`width` characters long.  All wrapping options are taken from instance
200+      :attr:`width` characters long.  All wrapping options are taken from
174-   attributes of the :class:`TextWrapper` instance. Returns a list of output lines,
201+      instance attributes of the :class:`TextWrapper` instance. Returns a list
175-   without final newlines.
202+      of output lines, without final newlines.
176
177
n178-.. method:: TextWrapper.fill(text)
n205+   .. method:: fill(text)
179
t180-   Wraps the single paragraph in *text*, and returns a single string containing the
t207+      Wraps the single paragraph in *text*, and returns a single string
181-   wrapped paragraph.
208+      containing the wrapped paragraph.
182
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op