diff options
| -rw-r--r-- | Lib/doctest.py | 126 |
1 files changed, 2 insertions, 124 deletions
diff --git a/Lib/doctest.py b/Lib/doctest.py index b0e53d50..f02fba2 100644 --- a/Lib/doctest.py +++ b/Lib/doctest.py @@ -8,13 +8,11 @@ r"""Module doctest -- a framework for running examples in docstrings. -NORMAL USAGE - In simplest use, end each module M to be tested with: def _test(): import doctest - return doctest.testmod() + doctest.testmod() if __name__ == "__main__": _test() @@ -40,133 +38,13 @@ You can force verbose mode by passing "verbose=True" to testmod, or prohibit it by passing "verbose=False". In either of those cases, sys.argv is not examined by testmod. -In any case, testmod returns a 2-tuple of ints (f, t), where f is the -number of docstring examples that failed and t is the total number of -docstring examples attempted. - There are a variety of other ways to run doctests, including integration with the unittest framework, and support for running non-Python text files containing doctests. There are also many ways to override parts of doctest's default behaviors. See the Library Reference Manual for details. - - -WHICH DOCSTRINGS ARE EXAMINED? - -+ M.__doc__. - -+ f.__doc__ for all functions f in M.__dict__.values(), except those - defined in other modules. - -+ C.__doc__ for all classes C in M.__dict__.values(), except those - defined in other modules. - -+ If M.__test__ exists and "is true", 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 searched directly as if they were docstrings. - In output, a key K in M.__test__ appears with name - <name of M>.__test__.K - -Any classes found are recursively searched similarly, to test docstrings in -their contained methods and nested classes. - - -WHAT'S THE EXECUTION CONTEXT? - -By default, each time testmod finds a docstring to test, it uses a *copy* -of M's globals (so that running tests on a module doesn't change the -module's real globals, and so that one test in M can't leave behind crumbs -that accidentally allow another test to work). This means examples can -freely use any names defined at top-level in M. It also means that sloppy -imports (see above) can cause examples in external docstrings to use -globals inappropriate for them. - -You can force use of your own dict as the execution context by passing -"globs=your_dict" to testmod instead. Presumably this would be a copy of -M.__dict__ merged with the globals from other imported modules. - - -WHAT ABOUT EXCEPTIONS? - -No problem, as long as the only output generated by the example is the -traceback itself. For example: - - >>> [1, 2, 3].remove(42) - Traceback (most recent call last): - File "<stdin>", line 1, in ? - ValueError: list.remove(x): x not in list - >>> - -Note that only the exception type and value are compared. - - -SO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!? - -Oh ya. It's easy! In most cases a copy-and-paste of an interactive -console session works fine -- just make sure the leading whitespace is -rigidly consistent (you can mix tabs and spaces if you're too lazy to do it -right, but doctest is not in the business of guessing what you think a tab -means). - - >>> # comments are ignored - >>> x = 12 - >>> x - 12 - >>> if x == 13: - ... print "yes" - ... else: - ... print "no" - ... print "NO" - ... print "NO!!!" - ... - no - NO - NO!!! - >>> - -Any expected output must immediately follow the final ">>>" or "..." line -containing the code, and the expected output (if any) extends to the next -">>>" or all-whitespace line. That's it. - -Bummers: - -+ Output to stdout is captured, but not output to stderr (exception - tracebacks are captured via a different means). - -+ If you continue a line via backslashing in an interactive session, - or for any other reason use a backslash, you should use a raw - docstring, which will preserve your backslahses exactly as you type - them: - - >>> def f(x): - ... r'''Backslashes in a raw docstring: m\n''' - >>> print f.__doc__ - Backslashes in a raw docstring: m\n - - Otherwise, the backslash will be interpreted as part of the string. - E.g., the "\n" above would be interpreted as a newline character. - Alternatively, you can double each backslash in the doctest version - (and not use a raw string): - - >>> def f(x): - ... '''Backslashes in a raw docstring: m\\n''' - >>> print f.__doc__ - Backslashes in a raw docstring: m\n - -The starting column doesn't matter: - ->>> assert "Easy!" - >>> import math - >>> math.floor(1.9) - 1.0 - -and as many leading whitespace characters are stripped from the expected -output as appeared in the initial ">>>" line that triggered it. - -If you execute this very file, the examples above will be found and -executed. """ + __docformat__ = 'reStructuredText en' __all__ = [ |