xdoctest.doctest_example module¶
This module defines the main class that holds a DocTest example
- class xdoctest.doctest_example.DoctestConfig(*args, **kwargs)[source]¶
Bases:
dict
Doctest configuration
Static configuration for collection, execution, and reporting doctests. Note dynamic directives are not managed by DoctestConfig, they use RuntimeState.
- class xdoctest.doctest_example.DocTest(docsrc, modpath=None, callname=None, num=0, lineno=1, fpath=None, block_type=None, mode='pytest')[source]¶
Bases:
object
Holds information necessary to execute and verify a doctest
- Variables:
docsrc (str) – doctest source code
modpath (str | PathLike) – module the source was read from
callname (str) – name of the function/method/class/module being tested
num (int) – the index of the doctest in the docstring. (i.e. this object refers to the num-th doctest within a docstring)
lineno (int) – The line (starting from 1) in the file that the doctest begins on. (i.e. if you were to go to this line in the file, the first line of the doctest should be on this line).
fpath (PathLike) – Typically the same as modpath, only specified for non-python files (e.g. rst files).
block_type (str | None) – Hint indicating the type of docstring block. Can be (‘Example’, ‘Doctest’, ‘Script’, ‘Benchmark’, ‘zero-arg’, etc..).
mode (str) – Hint at what created / is running this doctest. This impacts how results are presented and what doctests are skipped. Can be “native” or “pytest”. Defaults to “pytest”.
config (DoctestConfig) – configuration for running / checking the doctest
module (ModuleType | None) – a reference to the module that contains the doctest
modname (str) – name of the module that contains the doctest.
failed_tb_lineno (int | None) – Line number a failure occurred on.
exc_info (None | TracebackType) – traceback of a failure if one occurred.
failed_part (None | DoctestPart) – the part containing the failure if one occurred.
warn_list (list) – from
warnings.catch_warnings()
logged_evals (OrderedDict) – Mapping from part index to what they evaluated to (if anything)
logged_stdout (OrderedDict) – Mapping from part index to captured stdout.
global_namespace (dict) – globals visible to the doctest
CommandLine
xdoctest -m xdoctest.doctest_example DocTest
Example
>>> from xdoctest import core >>> from xdoctest import doctest_example >>> import os >>> modpath = doctest_example.__file__.replace('.pyc', '.py') >>> modpath = os.path.realpath(modpath) >>> testables = core.parse_doctestables(modpath) >>> for test in testables: >>> if test.callname == 'DocTest': >>> self = test >>> break >>> assert self.num == 0 >>> assert self.modpath == modpath >>> print(self) <DocTest(xdoctest.doctest_example DocTest:0 ln ...)>
- Parameters:
docsrc (str) – the text of the doctest
modpath (str | PathLike | None)
callname (str | None)
num (int)
lineno (int)
fpath (str | None)
block_type (str | None)
mode (str)
- UNKNOWN_MODNAME = '<modname?>'¶
- UNKNOWN_MODPATH = '<modpath?>'¶
- UNKNOWN_CALLNAME = '<callname?>'¶
- UNKNOWN_FPATH = '<fpath?>'¶
- is_disabled(pytest=False)[source]¶
Checks for comment directives on the first line of the doctest
A doctest is force-disabled if it starts with any of the following patterns
>>> # DISABLE_DOCTEST
>>> # SCRIPT
>>> # UNSTABLE
>>> # FAILING
And if running in pytest, you can also use
>>> import pytest; pytest.skip()
Note
modern versions of xdoctest contain directives like # xdoctest: +SKIP, which are a better way to do this.
Todo
Robustly deprecate these non-standard ways of disabling a doctest. Generate a warning for several versions if they are used, and indicate what the replacement strategy is. Then raise an error for several more versions before finally removing this code.
- Return type:
- property unique_callname¶
A key that references this doctest given its module
- Returns:
str
- property node¶
A key that references this doctest within pytest
- Returns:
str
- property valid_testnames¶
A set of callname and unique_callname
- Returns:
Set[str]
- format_parts(linenos=True, colored=None, want=True, offset_linenos=None, prefix=True)[source]¶
Used by
format_src()
- Parameters:
linenos (bool) – show line numbers
colored (bool | None) – pygmentize the code
want (bool) – include the want value if it exists
offset_linenos (bool) – if True include the line offset relative to the source file
prefix (bool) – if False, exclude the doctest ``>>> `` prefix
- format_src(linenos=True, colored=None, want=True, offset_linenos=None, prefix=True)[source]¶
Adds prefix and line numbers to a doctest
- Parameters:
linenos (bool) – if True, adds line numbers to output
colored (bool) – if True highlight text with ansi colors. Default is specified in the config.
want (bool) – if True includes “want” lines (default False).
offset_linenos (bool) – if True offset line numbers to agree with their position in the source text file (default False).
prefix (bool) – if False, exclude the doctest `>>> ` prefix
- Returns:
str
Example
>>> from xdoctest.core import * >>> from xdoctest import core >>> testables = parse_doctestables(core.__file__) >>> self = next(testables) >>> self._parse() >>> print(self.format_src()) >>> print(self.format_src(linenos=False, colored=False)) >>> assert not self.is_disabled()
- run(verbose=None, on_error=None)[source]¶
Executes the doctest, checks the results, reports the outcome.
- Parameters:
verbose (int) – verbosity level
on_error (str) – can be ‘raise’ or ‘return’
- Returns:
summary
- Return type:
Dict
- property globs¶
Alias for
global_namespace
for pytest 8.0 compatability
- repr_failure(with_tb=True)[source]¶
Constructs lines detailing information about a failed doctest
- Parameters:
with_tb (bool) – if True include the traceback
- Returns:
List[str]
CommandLine
python -m xdoctest.core DocTest.repr_failure:0 python -m xdoctest.core DocTest.repr_failure:1 python -m xdoctest.core DocTest.repr_failure:2
Example
>>> from xdoctest.core import * >>> docstr = utils.codeblock( ''' >>> x = 1 >>> print(x + 1) 2 >>> print(x + 3) 3 >>> print(x + 100) 101 ''') >>> parsekw = dict(fpath='foo.txt', callname='bar', lineno=42) >>> self = list(parse_docstr_examples(docstr, **parsekw))[0] >>> summary = self.run(on_error='return', verbose=0) >>> print('[res]' + '\n[res]'.join(self.repr_failure()))
Example
>>> from xdoctest.core import * >>> docstr = utils.codeblock( r''' >>> 1 1 >>> print('.▴ .\n.▴ ▴.') # xdoc: -NORMALIZE_WHITESPACE . ▴ . .▴ ▴. ''') >>> parsekw = dict(fpath='foo.txt', callname='bar', lineno=42) >>> self = list(parse_docstr_examples(docstr, **parsekw))[0] >>> summary = self.run(on_error='return', verbose=1) >>> print('[res]' + '\n[res]'.join(self.repr_failure()))
Example
>>> from xdoctest.core import * >>> docstr = utils.codeblock( ''' >>> assert True >>> assert False >>> x = 100 ''') >>> self = list(parse_docstr_examples(docstr))[0] >>> summary = self.run(on_error='return', verbose=0) >>> print('[res]' + '\n[res]'.join(self.repr_failure()))