diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/doctest.rst | 23 |
1 files changed, 17 insertions, 6 deletions
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 3ecbdd0..696a4f7 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). @@ -1778,4 +1790,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. - |