23.2.4 Basic API

##
23.2.4 Basic API

The functions `testmod()` and `testfile()` provide a simple interface to doctest that should be sufficient for most basic uses. For a less formal introduction to these two functions, see sections 23.2.1 and 23.2.2.

`testfile`( | filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])

  All arguments except filename are optional, and should be specified in keyword form.

  Test examples in the file named filename. Return "`(failure_count, test_count)`".

  Optional argument module_relative specifies how the filename should be interpreted:

  - If module_relative is `True` (the default), then filename specifies an OS-independent module-relative path. By default, this path is relative to the calling module's directory; but if the package argument is specified, then it is relative to that package. To ensure OS-independence, filename should use `/` characters to separate path segments, and may not be an absolute path (i.e., it may not begin with `/`).
  - If module_relative is `False`, then filename specifies an OS-specific path. The path may be absolute or relative; relative paths are resolved with respect to the current working directory.

  Optional argument name gives the name of the test; by default, or if `None`, `os.path.basename(filename)` is used.

  Optional argument package is a Python package or the name of a Python package whose directory should be used as the base directory for a module-relative filename. If no package is specified, then the calling module's directory is used as the base directory for module-relative filenames. It is an error to specify package if module_relative is `False`.

  Optional argument globs gives a dict to be used as the globals when executing examples. A new shallow copy of this dict is created for the doctest, so its examples start with a clean slate. By default, or if `None`, a new empty dict is used.

  Optional argument extraglobs gives a dict merged into the globals used to execute examples. This works like `dict.update()`: if globs and extraglobs have a common key, the associated value in extraglobs appears in the combined dict. By default, or if `None`, no extra globals are used. This is an advanced feature that allows parameterization of doctests. For example, a doctest can be written for a base class, using a generic name for the class, then reused to test any number of subclasses by passing an extraglobs dict mapping the generic name to the subclass to be tested.

  Optional argument verbose prints lots of stuff if true, and prints only failures if false; by default, or if `None`, it's true if and only if `'-v'` is in `sys.argv`.

  Optional argument report prints a summary at the end when true, else prints nothing at the end. In verbose mode, the summary is detailed, else the summary is very brief (in fact, empty if all tests passed).

  Optional argument optionflags or's together option flags. See section 23.2.3.

  Optional argument raise_on_error defaults to false. If true, an exception is raised upon the first failure or unexpected exception in an example. This allows failures to be post-mortem debugged. Default behavior is to continue running examples.

  Optional argument parser specifies a `DocTestParser` (or subclass) that should be used to extract tests from the files. It defaults to a normal parser (i.e., ``DocTestParser`()`).

  Optional argument encoding specifies an encoding that should be used to convert the file to unicode.

  New in version 2.4.

  Changed in version 2.5: The parameter encoding was added.

`testmod`( | [m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])

  All arguments are optional, and all except for m should be specified in keyword form.

  Test examples in docstrings in functions and classes reachable from module m (or module `__main__` if m is not supplied or is `None`), starting with `m.__doc__`.

  Also test examples reachable from dict `m.__test__`, if it exists and is not `None`. `m.__test__` maps names (strings) to functions, classes and strings; function and class docstrings are searched for examples; strings are searched directly, as if they were docstrings.

  Only docstrings attached to objects belonging to module m are searched.

  Return "`(failure_count, test_count)`".

  Optional argument name gives the name of the module; by default, or if `None`, `m.__name__` is used.

  Optional argument exclude_empty defaults to false. If true, objects for which no doctests are found are excluded from consideration. The default is a backward compatibility hack, so that code still using `doctest.master.summarize()` in conjunction with `testmod()` continues to get output for objects with no tests. The exclude_empty argument to the newer `DocTestFinder` constructor defaults to true.

  Optional arguments extraglobs, verbose, report, optionflags, raise_on_error, and globs are the same as for function `testfile()` above, except that globs defaults to `m.__dict__`.

  Changed in version 2.3: The parameter optionflags was added.

  Changed in version 2.4: The parameters extraglobs, raise_on_error and exclude_empty were added.

  Changed in version 2.5: The optional argument isprivate, deprecated in 2.4, was removed.

There's also a function to run the doctests associated with a single object. This function is provided for backward compatibility. There are no plans to deprecate it, but it's rarely useful:

`run_docstring_examples`( | f, globs[, verbose][, name][, compileflags][, optionflags])

  Test examples associated with object f; for example, f may be a module, function, or class object.

  A shallow copy of dictionary argument globs is used for the execution context.

  Optional argument name is used in failure messages, and defaults to `"NoName"`.

  If optional argument verbose is true, output is generated even if there are no failures. By default, output is generated only in case of an example failure.

  Optional argument compileflags gives the set of flags that should be used by the Python compiler when running the examples. By default, or if `None`, flags are deduced corresponding to the set of future features found in globs.

  Optional argument optionflags works as for function `testfile()` above.