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)[source]¶
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)[source]¶
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)[source]¶
- xdoctest.runner.doctest_module(module_identifier=None, command=None, argv=None, exclude=[], style='auto', verbose=None, config=None, durations=None, analysis='auto')[source]¶
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)[source]¶
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'}