mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 17:08:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

gh-134918: Fix and improve doctest's documentation (GH-134919)

Browse source
This commit is contained in:
Serhiy Storchaka 2025-05-31 12:03:08 +03:00 • committed by GitHub
parent 68784fed78
commit 3c66e59766
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 47 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

95
Doc/library/doctest.rst
View file

@ -174,7 +174,7 @@ with assorted summaries at the end.
You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
prohibit it by passing ``verbose=False``. In either of those cases,
``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
:data:`sys.argv` is not examined by :func:`testmod` (so passing ``-v`` or not
has no effect).
There is also a command line shortcut for running :func:`testmod`, see section
@ -231,7 +231,7 @@ documentation::
As with :func:`testmod`, :func:`testfile` won't display anything unless an
example fails. If an example does fail, then the failing example(s) and the
cause(s) of the failure(s) are printed to stdout, using the same format as
:func:`testmod`.
:func:`!testmod`.
By default, :func:`testfile` looks for files in the calling module's directory.
See section :ref:`doctest-basic-api` for a description of the optional arguments
@ -311,6 +311,9 @@ Which Docstrings Are Examined?
The module docstring, and all function, class and method docstrings are
searched. Objects imported into the module are not searched.
.. attribute:: module.__test__
:no-typesetting:
In addition, there are cases when you want tests to be part of a module but not part
of the help text, which requires that the tests not be included in the docstring.
Doctest looks for a module-level variable called ``__test__`` and uses it to locate other
@ -533,7 +536,7 @@ Some details you should read once, but won't need to remember:
* The interactive shell omits the traceback header line for some
:exc:`SyntaxError`\ s. But doctest uses the traceback header line to
distinguish exceptions from non-exceptions. So in the rare case where you need
to test a :exc:`SyntaxError` that omits the traceback header, you will need to
to test a :exc:`!SyntaxError` that omits the traceback header, you will need to
manually add the traceback header line to your test example.
.. index:: single: ^ (caret); marker
@ -860,15 +863,15 @@ The :const:`ELLIPSIS` directive gives a nice approach for the last example:
<C object at 0x...>
Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for float formatting,
and C libraries vary widely in quality here. ::
platforms, because Python defers to the platform C library for some
floating-point calculations, and C libraries vary widely in quality here. ::
>>> 1./7 # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857
>>> 1000**0.1 # risky
1.9952623149688797
>>> round(1000**0.1, 9) # safer
1.995262315
>>> print(f'{1000**0.1:.4f}') # much safer
1.9953
Numbers of the form ``I/2.**J`` are safe across all platforms, and I often
contrive doctest examples to produce numbers of that form::
@ -938,13 +941,13 @@ and :ref:`doctest-simple-testfile`.
Optional argument *verbose* prints lots of stuff if true, and prints only
failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
is in ``sys.argv``.
is in :data:`sys.argv`.
Optional argument *report* prints a summary at the end when true, else prints
nothing at the end. In verbose mode, the summary is detailed, else the summary
is very brief (in fact, empty if all tests passed).
Optional argument *optionflags* (default value 0) takes the
Optional argument *optionflags* (default value ``0``) takes the
:ref:`bitwise OR <bitwise>` of option flags.
See section :ref:`doctest-options`.
@ -1045,7 +1048,7 @@ from text files and modules with doctests:
The returned :class:`unittest.TestSuite` is to be run by the unittest framework
and runs the interactive examples in each file. If an example in any file
fails, then the synthesized unit test fails, and a :exc:`failureException`
fails, then the synthesized unit test fails, and a :exc:`~unittest.TestCase.failureException`
exception is raised showing the name of the file containing the test and a
(sometimes approximate) line number. If all the examples in a file are
skipped, then the synthesized unit test is also marked as skipped.
@ -1078,13 +1081,14 @@ from text files and modules with doctests:
Optional argument *setUp* specifies a set-up function for the test suite.
This is called before running the tests in each file. The *setUp* function
will be passed a :class:`DocTest` object. The setUp function can access the
test globals as the *globs* attribute of the test passed.
will be passed a :class:`DocTest` object. The *setUp* function can access the
test globals as the :attr:`~DocTest.globs` attribute of the test passed.
Optional argument *tearDown* specifies a tear-down function for the test
suite. This is called after running the tests in each file. The *tearDown*
function will be passed a :class:`DocTest` object. The setUp function can
access the test globals as the *globs* attribute of the test passed.
function will be passed a :class:`DocTest` object. The *tearDown* function can
access the test globals as the :attr:`~DocTest.globs` attribute of the test
passed.
Optional argument *globs* is a dictionary containing the initial global
variables for the tests. A new copy of this dictionary is created for each
@ -1111,11 +1115,12 @@ from text files and modules with doctests:
Convert doctest tests for a module to a :class:`unittest.TestSuite`.
The returned :class:`unittest.TestSuite` is to be run by the unittest framework
and runs each doctest in the module. If any of the doctests fail, then the
synthesized unit test fails, and a :exc:`failureException` exception is raised
and runs each doctest in the module.
Each docstring is run as a separate unit test.
If any of the doctests fail, then the synthesized unit test fails,
and a :exc:`unittest.TestCase.failureException` exception is raised
showing the name of the file containing the test and a (sometimes approximate)
line number. If all the examples in a docstring are skipped, then the
synthesized unit test is also marked as skipped.
Optional argument *module* provides the module to be tested. It can be a module
object or a (possibly dotted) module name. If not specified, the module calling
@ -1123,7 +1128,7 @@ from text files and modules with doctests:
Optional argument *globs* is a dictionary containing the initial global
variables for the tests. A new copy of this dictionary is created for each
test. By default, *globs* is a new empty dictionary.
test. By default, *globs* is the module's :attr:`~module.__dict__`.
Optional argument *extraglobs* specifies an extra set of global variables, which
is merged into *globs*. By default, no extra globals are used.
@ -1132,7 +1137,7 @@ from text files and modules with doctests:
drop-in replacement) that is used to extract doctests from the module.
Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
function :func:`DocFileSuite` above.
function :func:`DocFileSuite` above, but they are called for each docstring.
This function uses the same search technique as :func:`testmod`.
@ -1140,12 +1145,6 @@ from text files and modules with doctests:
: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
@ -1158,15 +1157,15 @@ 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
: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
: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
when and how tests get run. The framework author typically wants to control
:mod:`doctest` reporting options (perhaps, e.g., specified by command line
options), but there's no way to pass options through :mod:`unittest` to
:mod:`doctest` test runners.
:mod:`!doctest` reporting options (perhaps, e.g., specified by command line
options), but there's no way to pass options through :mod:`!unittest` to
:mod:`!doctest` test runners.
For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
For this reason, :mod:`doctest` also supports a notion of :mod:`!doctest`
reporting flags specific to :mod:`unittest` support, via this function:
@ -1181,12 +1180,12 @@ reporting flags specific to :mod:`unittest` support, via this function:
: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
:mod:`unittest` reporting flags are ignored.
:mod:`!unittest` reporting flags are ignored.
The value of the :mod:`unittest` reporting flags in effect before the function
was called is returned by the function.
@ -1279,7 +1278,7 @@ DocTest Objects
.. attribute:: filename
The name of the file that this :class:`DocTest` was extracted from; or
``None`` if the filename is unknown, or if the :class:`DocTest` was not
``None`` if the filename is unknown, or if the :class:`!DocTest` was not
extracted from a file.
@ -1419,10 +1418,10 @@ DocTestFinder objects
The globals for each :class:`DocTest` is formed by combining *globs* and
*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
shallow copy of the globals dictionary is created for each :class:`DocTest`.
If *globs* is not specified, then it defaults to the module's *__dict__*, if
specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
defaults to ``{}``.
shallow copy of the globals dictionary is created for each :class:`!DocTest`.
If *globs* is not specified, then it defaults to the module's
:attr:`~module.__dict__`, if specified, or ``{}`` otherwise.
If *extraglobs* is not specified, then it defaults to ``{}``.
.. _doctest-doctestparser:
@ -1446,7 +1445,7 @@ DocTestParser objects
:class:`DocTest` object.
*globs*, *name*, *filename*, and *lineno* are attributes for the new
:class:`DocTest` object. See the documentation for :class:`DocTest` for more
:class:`!DocTest` object. See the documentation for :class:`DocTest` for more
information.
@ -1461,7 +1460,7 @@ DocTestParser objects
Divide the given string into examples and intervening text, and return them as
a list of alternating :class:`Example`\ s and strings. Line numbers for the
:class:`Example`\ s are 0-based. The optional argument *name* is a name
:class:`!Example`\ s are 0-based. The optional argument *name* is a name
identifying this string, and is only used for error messages.
@ -1501,7 +1500,7 @@ DocTestRunner objects
:class:`OutputChecker`. This comparison may be customized with a number of
option flags; see section :ref:`doctest-options` for more information. If the
option flags are insufficient, then the comparison may also be customized by
passing a subclass of :class:`OutputChecker` to the constructor.
passing a subclass of :class:`!OutputChecker` to the constructor.
The test runner's display output can be controlled in two ways. First, an output
function can be passed to :meth:`run`; this function will be called
@ -1540,7 +1539,7 @@ DocTestRunner objects
output; it should not be called directly.
*example* is the example about to be processed. *test* is the test
*containing example*. *out* is the output function that was passed to
containing *example*. *out* is the output function that was passed to
:meth:`DocTestRunner.run`.
@ -1940,7 +1939,7 @@ several options for organizing tests:
containing test cases for the named topics. These functions can be included in
the same file as the module, or separated out into a separate test file.
* Define a ``__test__`` dictionary mapping from regression test topics to
* Define a :attr:`~module.__test__` dictionary mapping from regression test topics to
docstrings containing test cases.
When you have placed your tests in a module, the module can itself be the test