https://github.com/python/cpython/commit/3c66e5976669a599adfb260514c03815b1a9e4e9
commit: 3c66e5976669a599adfb260514c03815b1a9e4e9
branch: main
author: Serhiy Storchaka <storch...@gmail.com>
committer: serhiy-storchaka <storch...@gmail.com>
date: 2025-05-31T12:03:08+03:00
summary:
gh-134918: Fix and improve doctest's documentation (GH-134919)
files:
M Doc/library/doctest.rst
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index b86fef9fd6f310..8236d703fc1e45 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -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
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
