diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -22,8 +22,13 @@ *width* characters long. Returns a list of output lines, without final newlines. - Optional keyword arguments correspond to the instance attributes of - :class:`TextWrapper`, documented below. *width* defaults to ``70``. + The optional keyword arguments correspond to the keyword arguments to the + :class:`TextWrapper` class constructor. *width* defaults to ``70``. + + See the :class:`TextWrapper` class for information on the optional keyword + arguments and :meth:`TextWrapper.wrap` for additional details on how + :func:`wrap` behaves. + .. function:: fill(text, width=70, **kwargs) @@ -167,15 +172,18 @@ .. 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 first line, however, is not dropped + (provided that non-whitespace follows it on that line). If a line is + entirely whitespace, the whole line is removed. .. attribute:: initial_indent (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. .. attribute:: subsequent_indent @@ -239,6 +247,8 @@ instance attributes of the :class:`TextWrapper` instance. Returns a list of output lines, without final newlines. + This method returns an empty list if the wrapped output is an empty line. + .. method:: fill(text) diff --git a/Lib/test/test_textwrap.py b/Lib/test/test_textwrap.py --- a/Lib/test/test_textwrap.py +++ b/Lib/test/test_textwrap.py @@ -22,7 +22,7 @@ result = [] for i in range(len(textin)): result.append(" %d: %r" % (i, textin[i])) - result = '\n'.join(result) + result = "\n".join(result) if result else " no lines" elif isinstance(textin, str): result = " %s\n" % repr(textin) return result @@ -66,6 +66,8 @@ "I'm glad to hear it!"]) self.check_wrap(text, 80, [text]) + def test_empty_string(self): + self.check_wrap("", 10, []) def test_whitespace(self): # Whitespace munging and end-of-sentence detection @@ -331,7 +333,8 @@ ["blah", " ", "(ding", " ", "dong),", " ", "wubba"]) - def test_initial_whitespace(self): + def test_drop_whitespace__initial_whitespace(self): + # Check that drop_whitespace does not drop initial whitespace. # SF bug #622849 reported inconsistent handling of leading # whitespace; let's test that a bit, shall we? text = " This is a sentence with leading whitespace." @@ -340,7 +343,32 @@ self.check_wrap(text, 30, [" This is a sentence with", "leading whitespace."]) - def test_no_drop_whitespace(self): + def test_drop_whitespace__initial_whitespace_line(self): + # Check that drop_whitespace drops initial whitespace if that + # whitespace is on a line by itself. + text = " abcd" + self.check_wrap(text, 6, ["++ ", "abcd"], initial_indent="++", + drop_whitespace=False) + self.check_wrap(text, 6, ["++abcd"], initial_indent="++") + + def test_drop_whitespace__before_indenting(self): + # Check that dropping whitespace occurs before indenting. + self.check_wrap(" ", 6, [], initial_indent="++") + + def test_drop_whitespace__whitespace_indent(self): + # Check that drop_whitespace does not drop whitespace indents. + self.check_wrap("abcd efgh", 6, [" abcd", " efgh"], + initial_indent=" ", subsequent_indent=" ") + + def test_drop_whitespace__whitespace_line(self): + # Check that drop_whitespace drops the whole line if a line consists + # only of whitespace. + text = "abcd efgh" + self.check_wrap(text, 6, ["abcd", " ", "efgh"], + drop_whitespace=False) + self.check_wrap(text, 6, ["abcd", "efgh"]) + + def test_drop_whitespace__false(self): # SF patch #1581073 text = " This is a sentence with much whitespace." self.check_wrap(text, 10, @@ -348,6 +376,11 @@ "with ", "much white", "space."], drop_whitespace=False) + def test_drop_whitespace__false_whitespace_only(self): + # Check that a whitespace-only string is not dropped when + # drop_whitespace is False. + self.check_wrap(" ", 10, [" "], drop_whitespace=False) + def test_split(self): # Ensure that the standard _split() method works as advertised # in the comments @@ -477,6 +510,15 @@ result = fill(self.text, 40, initial_indent=" ") self.check(result, expect) + def test_initial_indent__empty_string(self): + # Check that the empty string is not indented. + self.check_wrap("", 10, [], initial_indent="++") + + def test_initial_indent__whitespace_only(self): + # Check that a whitespace-only string gets indented (when + # drop_whitespace is False). + self.check_wrap(" ", 10, [" "], initial_indent=" ", + drop_whitespace=False) def test_subsequent_indent(self): # Test subsequent_indent parameter