From 0abd7ef2efad164d362eb4cc27d5b3fc86ad6abf Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Thu, 19 Oct 2023 20:40:06 +0530 Subject: [PATCH] gh-109510: Clearly explain "Which Docstrings Are Examined" (GH-109696) (cherry picked from commit bcc941bd4a7fbed3b20f5a5fc68b183fda1506a5) Co-authored-by: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Co-authored-by: Mariatta Co-authored-by: Jacob Coffee Co-authored-by: Hugo van Kemenade Co-authored-by: C.A.M. Gerlach --- Doc/library/doctest.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index d6e4dca0860671..b5583e46a682aa 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -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``. - .__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.