Merged revisions 81634 via svnmerge from
authorR. David Murray <rdmurray@bitdance.com>
Tue, 15 Jun 2010 23:21:18 +0000 (23:21 +0000)
committerR. David Murray <rdmurray@bitdance.com>
Tue, 15 Jun 2010 23:21:18 +0000 (23:21 +0000)
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r81634 | r.david.murray | 2010-05-31 21:42:41 -0400 (Mon, 31 May 2010) | 2 lines

  #7583: clarify discussion of hard tab expansion in doctests.
........

Doc/library/doctest.rst

index de9340c65e7e4d4052fbed2d538aa207b5ea11ca..1a43a335246be0d6a7a7c80d2af888244be43518 100644 (file)
@@ -299,15 +299,8 @@ their contained methods and nested classes.
 How are Docstring Examples Recognized?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In most cases a copy-and-paste of an interactive console session works fine, but
-doctest isn't trying to do an exact emulation of any specific Python shell.  All
-hard tab characters are expanded to spaces, using 8-column tab stops.  If you
-don't believe tabs should mean that, too bad:  don't use hard tabs, or write
-your own :class:`DocTestParser` class.
-
-.. versionchanged:: 2.4
-   Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
-   with confusing results.
+In most cases a copy-and-paste of an interactive console session works fine,
+but doctest isn't trying to do an exact emulation of any specific Python shell.
 
 ::
 
@@ -342,6 +335,21 @@ The fine print:
      ``<BLANKLINE>`` was added; there was no way to use expected output containing
      empty lines in previous versions.
 
+* All hard tab characters are expanded to spaces, using 8-column tab stops.
+  Tabs in output generated by the tested code are not modified.  Because any
+  hard tabs in the sample output *are* expanded, this means that if the code
+  output includes hard tabs, the only way the doctest can pass is if the
+  :const:`NORMALIZE_WHITESPACE` option or directive is in effect.
+  Alternatively, the test can be rewritten to capture the output and compare it
+  to an expected value as part of the test.  This handling of tabs in the
+  source was arrived at through trial and error, and has proven to be the least
+  error prone way of handling them.  It is possible to use a different
+  algorithm for handling tabs by writing a custom :class:`DocTestParser` class.
+
+  .. versionchanged:: 2.4
+     Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
+     with confusing results.
+
 * Output to stdout is captured, but not output to stderr (exception tracebacks
   are captured via a different means).
 
@@ -1856,4 +1864,3 @@ several options for organizing tests:
 .. [#] Examples containing both expected output and an exception are not supported.
    Trying to guess where one ends and the other begins is too error-prone, and that
    also makes for a confusing test.
-