summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorR. David Murray <rdmurray@bitdance.com>2010-06-16 00:37:16 (GMT)
committerR. David Murray <rdmurray@bitdance.com>2010-06-16 00:37:16 (GMT)
commit24d83873ebbeff5bad465457579cd0c5ef02676e (patch)
tree2e04a9b07bae0dcd75b23abf985b5e9416b7a76d
parent1a3a3b8bb61de22e39de524c930560f0e376e1eb (diff)
downloadcpython-24d83873ebbeff5bad465457579cd0c5ef02676e.zip
cpython-24d83873ebbeff5bad465457579cd0c5ef02676e.tar.gz
cpython-24d83873ebbeff5bad465457579cd0c5ef02676e.tar.bz2
Merged revisions 82008 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r82008 | r.david.murray | 2010-06-15 19:46:40 -0400 (Tue, 15 Jun 2010) | 9 lines Merged revisions 81634 via svnmerge from 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. ........ ................
-rw-r--r--Doc/library/doctest.rst23
1 files changed, 17 insertions, 6 deletions
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index a9e1b5b..5d9759a 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -282,11 +282,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.
+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.
::
@@ -317,6 +314,21 @@ The fine print:
blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
is expected.
+* 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).
@@ -1760,4 +1772,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.
-