From 24d83873ebbeff5bad465457579cd0c5ef02676e Mon Sep 17 00:00:00 2001 From: "R. David Murray" Date: Wed, 16 Jun 2010 00:37:16 +0000 Subject: 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. ........ ................ --- Doc/library/doctest.rst | 23 +++++++++++++++++------ 1 file 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 ```` 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. - -- cgit v0.12