xdoctest.runner module

The Native XDoctest Runner

This file defines the native xdoctest interface to the collecting, executing, and summarizing the results of running doctests. This is an alternative to running through pytest.

Using the XDoctest Runner via the Terminal

This interface is exposed via the xdoctest.__main__ script and can be invoked on any module via: python -m xdoctest <modname>, where <modname> is the path to. For example to run the tests in this module you could execute:

python -m xdoctest xdoctest.runner all

For more details see:

python -m xdoctest --help

Using the XDoctest Runner Programmatically

This interface may also be run programmatically using xdoctest.doctest_module(path), which can be placed in the __main__ section of any module as such:

if __name__ == '__main__':
    import xdoctest as xdoc
    xdoc.doctest_module(__file__)

This allows you to invoke the runner on a specific module by simply running that module as the main module. Via: python -m <modname> <command>. For example, the this module ends with the previous code, which means you can run the doctests as such:

python -m xdoctest.runner list

xdoctest.runner.log(msg, verbose, level=1)

Simple conditional print logger

Parameters:

• msg (str) – message to print

• verbose (int) – verbosity level, higher means more is print

• level (int) – verbosity level at which this is printed. 0 is always, 1 is info, 2 is verbose, 3 is very-verbose.

xdoctest.runner.doctest_callable(func)

Executes doctests an in-memory function or class.

Parameters:

func (callable) – live method or class for which we will run its doctests.

Example

>>> def inception(text):
>>>     '''
>>>     Example:
>>>         >>> inception("I heard you liked doctests")
>>>     '''
>>>     print(text)
>>> func = inception
>>> doctest_callable(func)

xdoctest.runner.gather_doctests(doctest_identifiers, style='auto', analysis='auto', verbose=None)

xdoctest.runner.doctest_module(module_identifier=None, command=None, argv=None, exclude=[], style='auto', verbose=None, config=None, durations=None, analysis='auto')

Executes requestsed google-style doctests in a package or module. Main entry point into the testing framework.

Parameters:

• module_identifier (str | ModuleType | None) – The name of / path to the module, or the live module itself. If not specified, dynamic analysis will be used to introspect the module that called this function and that module will be used. This can also contain the callname followed by the :: token.

• command (str) – determines which doctests to run. if command is None, this is determined by parsing sys.argv Value values are ‘all’ - find and run all tests in a module ‘list’ - list the tests in a module ‘dump’ - dumps tests to stdout

• argv (List[str] | None) – if specified, command line flags that might influence beharior. if None uses sys.argv. SeeAlso :func:_update_argparse_cli SeeAlso :func:doctest_example.DoctestConfig._update_argparse_cli

• style (str) – Determines how doctests are recognized and grouped. Can be freeform, google, or auto.

• verbose (int | None) – Verbosity level. 0 - disables all text 1 - minimal printing 3 - verbose printing

• exclude (List[str]) – ignores any modname matching any of these glob-like patterns

• config (Dict[str, object]) – modifies each examples configuration. Defaults and expected keys are documented in xdoctest.doctest_example.DoctestConfig

• durations (int | None) – if specified report top N slowest tests

• analysis (str) – determines if doctests are found using static or dynamic analysis.

Returns:

run_summary

Return type:

Dict[str, Any]

Example

>>> modname = 'xdoctest.dynamic_analysis'
>>> result = doctest_module(modname, 'list', argv=[''])

Example

>>> # xdoctest: +SKIP
>>> # Demonstrate different ways "module_identifier" can be specified
>>> #
>>> # Using a module name
>>> result = doctest_module('xdoctest.static_analysis')
>>> #
>>> # Using a module path
>>> result = doctest_module(os.expandpath('~/code/xdoctest/src/xdoctest/static_analysis.py'))
>>> #
>>> # Using a module itself
>>> from xdoctest import runner
>>> result = doctest_module(runner)
>>> #
>>> # Using a module name and a specific callname
>>> from xdoctest import runner
>>> result = doctest_module('xdoctest.static_analysis::parse_static_value')

xdoctest.runner.undefined_names(sourcecode)

Parses source code for undefined names

Parameters:

sourcecode (str) – code to check for unused names

Returns:

the unused variable names

Return type:

Set[str]

Example

>>> # xdoctest: +REQUIRES(module:pyflakes)
>>> print(undefined_names('x = y'))
{'y'}