---------------------------------------------
The simplest way to start using doctest (but not necessarily the way you'll
-continue to do it) is to end each module :mod:`M` with::
+continue to do it) is to end each module :mod:`!M` with::
if __name__ == "__main__":
import doctest
doctest.testmod()
-:mod:`doctest` then examines docstrings in module :mod:`M`.
+:mod:`!doctest` then examines docstrings in module :mod:`!M`.
Running the module as a script causes the examples in the docstrings to get
executed and verified::
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, each time :mod:`doctest` finds a docstring to test, it uses a
-*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the
-module's real globals, and so that one test in :mod:`M` can't leave behind
+*shallow copy* of :mod:`!M`'s globals, so that running tests doesn't change the
+module's real globals, and so that one test in :mod:`!M` can't leave behind
crumbs that accidentally allow another test to work. This means examples can
-freely use any names defined at top-level in :mod:`M`, and names defined earlier
+freely use any names defined at top-level in :mod:`!M`, and names defined earlier
in the docstring being run. Examples cannot see names defined in other
docstrings.
Optional argument *exclude_empty* defaults to false. If true, objects for which
no doctests are found are excluded from consideration. The default is a backward
- compatibility hack, so that code still using :meth:`doctest.master.summarize` in
+ compatibility hack, so that code still using
+ :meth:`doctest.master.summarize <DocTestRunner.summarize>` in
conjunction with :func:`testmod` continues to get output for objects with no
tests. The *exclude_empty* argument to the newer :class:`DocTestFinder`
constructor defaults to true.
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. To integrate with :mod:`unittest` test discovery, include
-a :func:`load_tests` function in your test module::
+a :ref:`load_tests <load_tests-protocol>` function in your test module::
import unittest
import doctest
:func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if *module*
contains no docstrings instead of raising :exc:`ValueError`.
+.. exception:: failureException
+
+ When doctests which have been converted to unit tests by :func:`DocFileSuite`
+ or :func:`DocTestSuite` fail, this exception is raised showing the name of
+ the file containing the test and a (sometimes approximate) line number.
Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
-of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
-subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented
+of :class:`!doctest.DocTestCase` instances, and :class:`!DocTestCase` is a
+subclass of :class:`unittest.TestCase`. :class:`!DocTestCase` isn't documented
here (it's an internal detail), but studying its code can answer questions about
the exact details of :mod:`unittest` integration.
Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of
-:class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
-of :class:`DocTestCase`.
+:class:`!doctest.DocFileCase` instances, and :class:`!DocFileCase` is a subclass
+of :class:`!DocTestCase`.
So both ways of creating a :class:`unittest.TestSuite` run instances of
-:class:`DocTestCase`. This is important for a subtle reason: when you run
+:class:`!DocTestCase`. This is important for a subtle reason: when you run
:mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
use directly, by passing option flags to :mod:`doctest` functions. However, if
you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls
section :ref:`doctest-options`. Only "reporting flags" can be used.
This is a module-global setting, and affects all future doctests run by module
- :mod:`unittest`: the :meth:`runTest` method of :class:`DocTestCase` looks at
- the option flags specified for the test case when the :class:`DocTestCase`
+ :mod:`unittest`: the :meth:`!runTest` method of :class:`!DocTestCase` looks at
+ the option flags specified for the test case when the :class:`!DocTestCase`
instance was constructed. If no reporting flags were specified (which is the
- typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
+ typical and expected case), :mod:`!doctest`'s :mod:`unittest` reporting flags are
:ref:`bitwise ORed <bitwise>` into the option flags, and the option flags
so augmented are passed to the :class:`DocTestRunner` instance created to
run the doctest. If any reporting flags were specified when the
- :class:`DocTestCase` instance was constructed, :mod:`doctest`'s
+ :class:`!DocTestCase` instance was constructed, :mod:`!doctest`'s
:mod:`unittest` reporting flags are ignored.
The value of the :mod:`unittest` reporting flags in effect before the function
A dictionary mapping from option flags to ``True`` or ``False``, which is used
to override default options for this example. Any option flags not contained
in this dictionary are left at their default value (as specified by the
- :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+ :class:`DocTestRunner`'s :ref:`optionflags <doctest-options>`).
+ By default, no options are set.
.. _doctest-doctestfinder:
The output of each example is checked using the :class:`DocTestRunner`'s
output checker, and the results are formatted by the
- :meth:`DocTestRunner.report_\*` methods.
+ :meth:`!DocTestRunner.report_\*` methods.
.. method:: summarize(verbose=None)
module) of the object with the doctests of interest. The result is a string,
containing the object's docstring converted to a Python script, as described for
:func:`script_from_examples` above. For example, if module :file:`a.py`
- contains a top-level function :func:`f`, then ::
+ contains a top-level function :func:`!f`, then ::
import a, doctest
print(doctest.testsource(a, "a.f"))
- prints a script version of function :func:`f`'s docstring, with doctests
+ prints a script version of function :func:`!f`'s docstring, with doctests
converted to code, and the rest placed in comments.
projects / thirdparty / Python / cpython.git / commitdiff
