From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> Date: Thu, 19 Oct 2023 15:35:04 +0000 (+0200) Subject: [3.12] gh-109510: Clearly explain "Which Docstrings Are Examined" (GH-109696) (#111077) X-Git-Tag: v3.12.1~260 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3e9d84c94c532afbb4c0e8779fcc0b90e829559e;p=thirdparty%2FPython%2Fcpython.git [3.12] gh-109510: Clearly explain "Which Docstrings Are Examined" (GH-109696) (#111077) 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 --- diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index d6e4dca08606..b5583e46a682 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.