Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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

This commit is contained in:
R. David Murray 2010-06-01 01:42:41 +00:00
parent de535cb615
commit ac94f4f716
1 changed files with 17 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Doc/library/doctest.rst
View 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).
@ -1872,4 +1880,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.