diff options
Diffstat (limited to 'Doc/library/doctest.rst')
| -rw-r--r-- | Doc/library/doctest.rst | 73 |
1 files changed, 44 insertions, 29 deletions
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 5f40432e45..cdd6c26245 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -452,8 +452,9 @@ Some details you should read once, but won't need to remember: with an alphanumeric is taken to be the start of the exception detail. Of course this does the right thing for genuine tracebacks. -* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is is specified, - everything following the leftmost colon is ignored. +* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, + everything following the leftmost colon and any module information in the + exception name is ignored. * The interactive shell omits the traceback header line for some :exc:`SyntaxError`\ s. But doctest uses the traceback header line to @@ -543,20 +544,38 @@ doctest decides whether actual output matches an example's expected output: exception raised is ``ValueError: 3*14``, but will fail, e.g., if :exc:`TypeError` is raised. - Note that a similar effect can be obtained using :const:`ELLIPSIS`, and - :const:`IGNORE_EXCEPTION_DETAIL` may go away when Python releases prior to 2.4 - become uninteresting. Until then, :const:`IGNORE_EXCEPTION_DETAIL` is the only - clear way to write a doctest that doesn't care about the exception detail yet - continues to pass under Python releases prior to 2.4 (doctest directives appear - to be comments to them). For example, :: + It will also ignore the module name used in Python 3 doctest reports. Hence + both these variations will work regardless of whether the test is run under + Python 2.7 or Python 3.2 (or later versions): + + >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL + Traceback (most recent call last): + CustomError: message + + >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL + Traceback (most recent call last): + my_module.CustomError: message + + Note that :const:`ELLIPSIS` can also be used to ignore the + details of the exception message, but such a test may still fail based + on whether or not the module details are printed as part of the + exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details + from Python 2.3 is also the only clear way to write a doctest that doesn't + care about the exception detail yet continues to pass under Python 2.3 or + earlier (those releases do not support doctest directives and ignore them + as irrelevant comments). For example, :: >>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): File "<stdin>", line 1, in ? TypeError: object doesn't support item assignment - passes under Python 2.4 and Python 2.3. The detail changed in 2.4, to say "does - not" instead of "doesn't". + passes under Python 2.3 and later Python versions, even though the detail + changed in Python 2.4 to say "does not" instead of "doesn't". + + .. versionchanged:: 3.2 + :const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating + to the module containing the exception under test. .. data:: SKIP @@ -671,7 +690,6 @@ usually the only meaningful choice. However, option flags can also be passed to functions that run doctests, establishing different defaults. In such cases, disabling an option via ``-`` in a directive can be useful. - There's also a way to register new option flag names, although this isn't useful unless you intend to extend :mod:`doctest` internals via subclassing: @@ -895,18 +913,16 @@ Unittest API As your collection of doctest'ed modules grows, you'll want a way to run all their doctests systematically. :mod:`doctest` provides two functions that can be used to create :mod:`unittest` test suites from modules and text files -containing doctests. These test suites can then be run using :mod:`unittest` -test runners:: +containing doctests. To integrate with :mod:`unittest` test discovery, include +a :func:`load_tests` function in your test module:: import unittest import doctest - import my_module_with_doctests, and_another + import my_module_with_doctests - suite = unittest.TestSuite() - for mod in my_module_with_doctests, and_another: - suite.addTest(doctest.DocTestSuite(mod)) - runner = unittest.TextTestRunner() - runner.run(suite) + def load_tests(loader, tests, ignore): + tests.addTests(doctest.DocTestSuite(my_module_with_doctests)) + return tests There are two main functions for creating :class:`unittest.TestSuite` instances from text files and modules with doctests: @@ -1111,11 +1127,10 @@ DocTest Objects .. class:: DocTest(examples, globs, name, filename, lineno, docstring) A collection of doctest examples that should be run in a single namespace. The - constructor arguments are used to initialize the member variables of the same - names. + constructor arguments are used to initialize the attributes of the same names. - :class:`DocTest` defines the following member variables. They are initialized by + :class:`DocTest` defines the following attributes. They are initialized by the constructor, and should not be modified directly. @@ -1168,11 +1183,11 @@ Example Objects .. class:: Example(source, want, exc_msg=None, lineno=0, indent=0, options=None) A single interactive example, consisting of a Python statement and its expected - output. The constructor arguments are used to initialize the member variables - of the same names. + output. The constructor arguments are used to initialize the attributes of + the same names. - :class:`Example` defines the following member variables. They are initialized by + :class:`Example` defines the following attributes. They are initialized by the constructor, and should not be modified directly. @@ -1659,9 +1674,9 @@ There are two exceptions that may be raised by :class:`DebugRunner` instances: An exception raised by :class:`DocTestRunner` to signal that a doctest example's actual output did not match its expected output. The constructor arguments are - used to initialize the member variables of the same names. + used to initialize the attributes of the same names. -:exc:`DocTestFailure` defines the following member variables: +:exc:`DocTestFailure` defines the following attributes: .. attribute:: DocTestFailure.test @@ -1683,9 +1698,9 @@ There are two exceptions that may be raised by :class:`DebugRunner` instances: An exception raised by :class:`DocTestRunner` to signal that a doctest example raised an unexpected exception. The constructor arguments are used - to initialize the member variables of the same names. + to initialize the attributes of the same names. -:exc:`UnexpectedException` defines the following member variables: +:exc:`UnexpectedException` defines the following attributes: .. attribute:: UnexpectedException.test |