improve docs & tests

Author: picnixz

Doc/library/doctest.rst

@@ -689,6 +689,29 @@ doctest decides whether actual output matches an example's expected output:
       'the string
       to split'
 
+   Note that any leading whitespaces on each expected output line are retained.
+   In other words, the following expected outputs are equivalent under the
+   :data:`!IGNORE_LINEBREAK`:
+
+      [
+         'a', 'b', 'c',
+         '1', '2', '3'
+      ]
+
+      [    'a', 'b', 'c',    '1', '2', '3']
+
+   To break a list-like output with :data:`!IGNORE_LINEBREAK`,
+   leading whitespaces for visual indentation purposes should
+   be avoided, for instance:
+
+   .. code-block:: pycon
+
+      >>> list("abc123")            # doctest: +IGNORE_LINEBREAK
+      ['a', 'b', 'c',
+       '1', '2', '3']
+
+   For more complex outputs, consider using :func:`pprint.pprint` instead.
+
    .. versionadded:: next
 
 

Lib/test/test_doctest/test_doctest.py

@@ -1396,17 +1396,23 @@ def optionflags(): r"""
     [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
     10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
 
-The IGNORE_LINEBREAK flag causes all sequences of newlines to be removed:
+The IGNORE_LINEBREAK flag causes all sequences of newlines to be removed,
+but retains the leading whitespaces as they cannot be distinguished from
+real textual whitespaces:
 
-    >>> def f(x):
-    ...     '\n>>> "foobar"\n\'foo\nbar\''
+    >>> def f(x): pass
+    >>> f.__doc__ = '''
+    ... >>> "foobar"
+    ... 'foo
+    ... bar'
+    ... '''.strip()
 
     >>> # Without the flag:
     >>> test = doctest.DocTestFinder().find(f)[0]
     >>> doctest.DocTestRunner(verbose=False).run(test)
     ... # doctest: +ELLIPSIS
     **********************************************************************
-    File ..., line 3, in f
+    File ..., line ?, in f
     Failed example:
         "foobar"
     Expected:
@@ -1454,12 +1460,50 @@ def optionflags(): r"""
 
     ... mixing flags:
 
-    >>> import string
-    >>> print(list(string.ascii_letters))  # doctest: +IGNORE_LINEBREAK
-    ...                                    # doctest: +ELLIPSIS
-    ...                                    # doctest: +NORMALIZE_WHITESPACE
-    ['a', ..., 'z',
-     'A', ..., 'Z']
+    >>> print(list("abc123"))  # doctest: +IGNORE_LINEBREAK
+    ...                        # doctest: +ELLIPSIS
+    ...                        # doctest: +NORMALIZE_WHITESPACE
+    ['a', ..., 'c',
+     '1', ..., '3']
+
+    >>> prelude = r'''
+    ... >>> print(list("abc123"))  # doctest: +IGNORE_LINEBREAK
+    ... ...                        # doctest: +ELLIPSIS
+    ... ...                        # doctest: +NORMALIZE_WHITESPACE
+    ... '''.strip()
+
+    >>> def good(x): pass
+    >>> good.__doc__ = '\n'.join([prelude, r'''
+    ... ['a', ..., 'c',
+    ...  '1', ..., '3']
+    ... '''.lstrip()]).lstrip()
+    >>> test = doctest.DocTestFinder().find(good)[0]
+    >>> doctest.DocTestRunner(verbose=False).run(test)
+    TestResults(failed=0, attempted=1)
+
+    >>> def fail(x): pass
+    >>> fail.__doc__ = '\n'.join([prelude, '''
+    ... [
+    ...     'a', ..., 'c',
+    ...     '1', ..., '3'
+    ... ]\n'''.lstrip()])
+    >>> test = doctest.DocTestFinder().find(fail)[0]
+    >>> doctest.DocTestRunner(verbose=False).run(test)
+    ... # doctest: +ELLIPSIS
+    **********************************************************************
+    File ..., line ?, in fail
+    Failed example:
+        print(list("abc123"))  # doctest: +IGNORE_LINEBREAK
+                               # doctest: +ELLIPSIS
+                               # doctest: +NORMALIZE_WHITESPACE
+    Expected:
+        [
+            'a', ..., 'c',
+            '1', ..., '3'
+        ]
+    Got:
+        ['a', 'b', 'c', '1', '2', '3']
+    TestResults(failed=1, attempted=1)
 
 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
 output to match any substring in the actual output: