Changeset 391 for python/trunk/Doc/library/textwrap.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/textwrap.rst (modified) (8 diffs)

python/trunk/Doc/library/textwrap.rst

@@ -1 @@
-
 :mod:`textwrap` --- Text wrapping and filling
 =============================================
@@ -8 +7 @@
 .. sectionauthor:: Greg Ward <gward@python.net>
 
-
 .. versionadded:: 2.3
+
+**Source code:** :source:`Lib/textwrap.py`
+
+--------------
 
 The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and
@@ -17 +19 @@
 otherwise,  you should use an instance of :class:`TextWrapper` for efficiency.
 
-
 .. function:: wrap(text[, width[, ...]])
 
@@ -25 +26 @@
    Optional keyword arguments correspond to the instance attributes of
    :class:`TextWrapper`, documented below.  *width* defaults to ``70``.
+
+   See the :meth:`TextWrapper.wrap` method for additional details on how
+   :func:`wrap` behaves.
 
 
@@ -112 +116 @@
    .. attribute:: replace_whitespace
 
-      (default: ``True``) If true, each whitespace character (as defined by
-      ``string.whitespace``) remaining after tab expansion will be replaced by a
-      single space.
+      (default: ``True``) If true, after tab expansion but before wrapping,
+      the :meth:`wrap` method will replace each whitespace character
+      with a single space.  The whitespace characters replaced are
+      as follows: tab, newline, vertical tab, formfeed, and carriage
+      return (``'\t\n\v\f\r'``).
 
       .. note::
@@ -122 +128 @@
          the same as tab expansion.
 
+      .. note::
+
+         If :attr:`replace_whitespace` is false, newlines may appear in the
+         middle of a line and cause strange output. For this reason, text should
+         be split into paragraphs (using :meth:`str.splitlines` or similar)
+         which are wrapped separately.
+
 
    .. attribute:: drop_whitespace
 
-      (default: ``True``) If true, whitespace that, after wrapping, happens to
-      end up at the beginning or end of a line is dropped (leading whitespace in
-      the first line is always preserved, though).
+      (default: ``True``) If true, whitespace at the beginning and ending of
+      every line (after wrapping but before indenting) is dropped.
+      Whitespace at the beginning of the paragraph, however, is not dropped
+      if non-whitespace follows it.  If whitespace being dropped takes up an
+      entire line, the whole line is dropped.
 
       .. versionadded:: 2.6
@@ -136 +151 @@
 
       (default: ``''``) String that will be prepended to the first line of
-      wrapped output.  Counts towards the length of the first line.
+      wrapped output.  Counts towards the length of the first line.  The empty
+      string is not indented.
 
 
@@ -199 +215 @@
       Wraps the single paragraph in *text* (a string) so every line is at most
       :attr:`width` characters long.  All wrapping options are taken from
-      instance attributes of the :class:`TextWrapper` instance. Returns a list
-      of output lines, without final newlines.
+      instance attributes of the :class:`TextWrapper` instance.  Returns a list
+      of output lines, without final newlines.  If the wrapped output has no
+      content, the returned list is empty.