mirror of https://github.com/python/cpython
gh-109510: Clearly explain "Which Docstrings Are Examined" (#109696)
Co-authored-by: Mariatta <Mariatta@users.noreply.github.com> Co-authored-by: Jacob Coffee <jacob@z7x.org> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
parent
63acf78d71
commit
bcc941bd4a
|
@ -277,13 +277,34 @@ Which Docstrings Are Examined?
|
|||
The module docstring, and all function, class and method docstrings are
|
||||
searched. Objects imported into the module are not searched.
|
||||
|
||||
In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each
|
||||
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
|
||||
tests. If ``M.__test__`` exists and is truthy, it must be a dict, and each
|
||||
entry maps a (string) name to a function object, class object, or string.
|
||||
Function and class object docstrings found from ``M.__test__`` are searched, and
|
||||
strings are treated as if they were docstrings. In output, a key ``K`` in
|
||||
``M.__test__`` appears with name ::
|
||||
``M.__test__`` appears with name ``M.__test__.K``.
|
||||
|
||||
<name of M>.__test__.K
|
||||
For example, place this block of code at the top of :file:`example.py`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
__test__ = {
|
||||
'numbers': """
|
||||
>>> factorial(6)
|
||||
720
|
||||
|
||||
>>> [factorial(n) for n in range(6)]
|
||||
[1, 1, 2, 6, 24, 120]
|
||||
"""
|
||||
}
|
||||
|
||||
The value of ``example.__test__["numbers"]`` will be treated as a
|
||||
docstring and all the tests inside it will be run. It is
|
||||
important to note that the value can be mapped to a function,
|
||||
class object, or module; if so, :mod:`!doctest`
|
||||
searches them recursively for docstrings, which are then scanned for tests.
|
||||
|
||||
Any classes found are recursively searched similarly, to test docstrings in
|
||||
their contained methods and nested classes.
|
||||
|
|
Loading…
Reference in New Issue