mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-03 13:45:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

gh-109510: Clearly explain "Which Docstrings Are Examined" (#109696)

Browse source 
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:
Unique-Usman 2023-10-19 20:40:06 +05:30 • committed by GitHub
parent 63acf78d71
commit bcc941bd4a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 24 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

27
Doc/library/doctest.rst
View file

@ -277,13 +277,34 @@ Which Docstrings Are Examined?
The module docstring, and all function, class and method docstrings are The module docstring, and all function, class and method docstrings are
searched. Objects imported into the module are not searched. 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. 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 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 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 Any classes found are recursively searched similarly, to test docstrings in
their contained methods and nested classes. their contained methods and nested classes.