xdoctest.checker module

Checks for got-vs-want statements

A “got-string” is data produced by a doctest that we want to check matches some expected value.

A “want-string” is a representation of the output we expect, if the “got-string” is different than the “want-string” the doctest will fail with a GotWantException. A want string should come directly after a doctest and should not be prefixed by the three cheverons (``>>> ``).

There are two types of data that a doctest could “get” as a “got-string”, either the contents of standard out the value of an expression itself.

A doctest that uses stdout might look like this

>>> print('We expect this exact string')
We expect this exact string

A doctest that uses a raw expression might look like this

>>> def foo():
>>>     return 3
>>> foo()
3

In most cases it is best to use stdout to write your got-want tests because it is easier to control strings sent to stdout than it is to control the representation of expression-based “got-strings”.

xdoctest.checker.check_got_vs_want(want: str, got_stdout: str, got_eval: Any = <NOT_EVALED>, runstate: RuntimeState | None = None) → bool[source]

Determines to check against either got_stdout or got_eval, and then does the comparison.

If both stdout and eval “got” outputs are specified, then the “want” target may match either value.

Parameters:

  • want (str) – target to match against

  • got_stdout (str) – output from stdout

  • got_eval (str) – output from an eval statement.

  • runstate (xdoctest.directive.RuntimeState | None) – current state

Raises:

GotWantException - If the "got" differs from this parts want. –

xdoctest.checker._strip_exception_details(msg: str) → str[source]
Parameters:

msg (str)

Return type:

str

xdoctest.checker.extract_exc_want(want: str) → str | None[source]
Parameters:

want (str) – the message supplied by the user

Returns:

the matchable exception part

Return type:

str

Example

extract_exc_want(‘’’ Traceback (most recent call last): bar ‘’’)

xdoctest.checker.check_exception(exc_got: str, want: str, runstate: RuntimeState | None = None) → bool[source]

Checks want against an exception

Parameters:

  • exc_got (str) – the exception message

  • want (str) – target to match against

  • runstate (xdoctest.directive.RuntimeState | None) – current state

Raises:

GotWantException - If the "got" differs from this parts want. –

Returns:

True if got matches want

Return type:

bool

xdoctest.checker._xdoctest_check_output(got: str, want: str, runstate: RuntimeState | None = None) → bool[source]

Does the actual comparison between got and want as long as the check is enabled.

Parameters:

  • got (str) – text produced by the test

  • want (str) – target to match against

  • runstate (xdoctest.directive.RuntimeState | None) – current state

Returns:

True if got matches want or if the check is disabled

Return type:

bool

xdoctest.checker._coerce_runstate(runstate: RuntimeState | Mapping[str, object] | None) → RuntimeState[source]

Normalize compatibility mappings without taxing native state.

Real RuntimeState objects are returned unchanged. Sparse mappings take the pre-fast-path compatibility route through stdlib option bits, yielding a complete runtime state before native matching accesses flags.

Example

>>> state = _coerce_runstate({'_output_checker': 'xdoctest'})
>>> isinstance(state, directive.RuntimeState)
True
>>> state.get_output_checker()
'xdoctest'
xdoctest.checker.check_output(got: str, want: str, runstate: RuntimeState | Mapping[str, object] | None = None) → bool[source]

Check output using the currently configured output checker backend.

The default 'xdoctest' checker consumes the structured runtime state directly. Only when a foreign (registered) checker is selected are the runtime state and checker-only bits packed into a stdlib-shaped optionflags int — conversion happens at the boundary, not on the native path.

Parameters:

  • got (str) – text produced by the test

  • want (str) – target to match against

  • runstate (xdoctest.directive.RuntimeState | None) – current state

Returns:

True if got matches want or if the check is disabled

Return type:

bool

xdoctest.checker._check_match(got: str, want: str, runstate: RuntimeState | dict) → bool[source]

Does the actual comparison between got and want

Parameters:

  • got (str) – normalized text produced by the test

  • want (str) – normalized target to match against

  • runstate (xdoctest.directive.RuntimeState) – current state

Returns:

True if got matches want

Return type:

bool

xdoctest.checker._ellipsis_match(got: Any, want: Any) → bool[source]

The ellipsis matching algorithm taken directly from standard doctest.

Worst-case linear-time ellipsis matching.

Parameters:

  • got (str)

  • want (str)

Returns:

True if the text matches according to the ellipsis rule

Return type:

bool

CommandLine

python -m xdoctest.checker _ellipsis_match

Example

>>> _ellipsis_match('aaa', 'aa...aa')
False
>>> _ellipsis_match('anything', '...')
True
>>> _ellipsis_match('prefix-anything', 'prefix-...')
True
>>> _ellipsis_match('suffix-anything', 'prefix-...')
False
>>> _ellipsis_match('foo', '... foo')
True
>>> _ellipsis_match('took=3.4s', 'took=...s')
True
>>> _ellipsis_match('best=3.4s ave=4.5s', 'best=...s ave=...s')
True
>>> _ellipsis_match('took: 1.16e-05 s\nbest=9.63e-07 s ave=1.002e-06 ± 3e-08 s\n',
>>>                 'took: ...s\nbest=...s ave=...s\n')
True
xdoctest.checker._float_cmp_match(got: str, want: str, runstate: RuntimeState | dict) → bool[source]

Compare numeric substrings approximately while preserving text rules.

Numeric fields are replaced with a neutral placeholder before ordinary text or ellipsis matching. Numeric values are then compared separately, with ellipses allowed to consume zero or more numeric fields as well as arbitrary text.

xdoctest.checker._find_float_cmp_numbers(text: str) → list[str][source]

Return independently formatted numeric fields from text.

xdoctest.checker._replace_float_cmp_numbers(text: str) → str[source]

Replace recognized numeric fields without disturbing surrounding text.

xdoctest.checker._float_cmp_number_lists_equal(got: list[str], want: list[str]) → bool[source]
xdoctest.checker._float_cmp_number_chunks_match(got_numbers: list[str], want_chunks: list[list[str]]) → bool[source]

Match numeric chunks separated by expected ellipses.

xdoctest.checker._float_cmp_numeric_equal(got_text: str, want_text: str) → bool[source]
xdoctest.checker._parse_float_cmp_number(text: str) → float[source]
xdoctest.checker.normalize(got: str, want: str, runstate: RuntimeState | Dict[str, bool | Set[str]] | OrderedDict[str, bool | Set[str]] | None = None) → tuple[str, str][source]

Normalizes the got and want string based on the runtime state.

Adapted from doctest_nose_plugin.py from the nltk project:

https://github.com/nltk/nltk

Further extended to also support byte literals.

Parameters:

  • got (str) – unnormalized got str.

  • want (str) – unnormalized want str.

  • runstate (xdoctest.directive.RuntimeState | None) – current state

Returns:

The normalized got and want str

Return type:

Tuple[str, str]

Example

>>> from xdoctest.checker import *  # NOQA
>>> want = "...\n(0, 2, {'weight': 1})\n(0, 3, {'weight': 2})"
>>> got = "(0, 2, {'weight': 1})\n(0, 3, {'weight': 2})"
>>> normalize(got, want)
("(0, 2, {'weight': 1}) (0, 3, {'weight': 2})",
 "... (0, 2, {'weight': 1}) (0, 3, {'weight': 2})")
exception xdoctest.checker.ExtractGotReprException(msg: str, orig_ex: Exception)[source]

Bases: AssertionError

Parameters:

  • msg (str) – The exception message

  • orig_ex (Exception) – The parent exception

orig_ex: Exception

Exception used when we are unable to extract a string “got”

exception xdoctest.checker.GotWantException(msg: str, got: str, want: str)[source]

Bases: AssertionError

Parameters:

  • msg (str) – The exception message

  • got (str) – The unnormalized got str

  • want (str) – The unnormalized want str

got: str
want: str

Exception used when the “got” output of a doctest differs from the expected “want” output.

_do_a_fancy_diff(runstate: RuntimeState | None = None) → bool[source]
_output_difference_xdoctest(runstate: RuntimeState | None = None, colored: bool = True) → str[source]

Return a string describing the differences between the expected output for a given example (example) and the actual output (got). The runstate contains option flags used to compare want and got.

Parameters:

  • runstate (xdoctest.directive.RuntimeState | None) – current state

  • colored (bool) – if the text should be colored

Returns:

formatted difference text

Return type:

str

Note

This does not check if got matches want, it only outputs the raw differences. Got/Want normalization may make the differences appear more exaggerated than they are.

output_difference(runstate: RuntimeState | Mapping[str, object] | None = None, colored: bool = True) → str[source]
output_repr_difference(runstate: RuntimeState | None = None) → str[source]

Constructs a repr difference with minimal normalization.

Parameters:

runstate (xdoctest.directive.RuntimeState | None) – current state

Returns:

formatted repr difference text

Return type:

str

xdoctest.checker.remove_blankline_marker(text: str) → str[source]
Parameters:

text (str) – input text

Returns:

output text

Return type:

str

Example

>>> text1 = 'foo\n{}\nbar'.format(BLANKLINE_MARKER)
>>> text2 = '{}\nbar'.format(BLANKLINE_MARKER)
>>> text4 = 'foo\n{}'.format(BLANKLINE_MARKER)
>>> text3 = '{}'.format(BLANKLINE_MARKER)
>>> text5 = text1 + text1 + text1
>>> assert BLANKLINE_MARKER not in remove_blankline_marker(text1)
>>> assert BLANKLINE_MARKER not in remove_blankline_marker(text2)
>>> assert BLANKLINE_MARKER not in remove_blankline_marker(text3)
>>> assert BLANKLINE_MARKER not in remove_blankline_marker(text4)
>>> assert BLANKLINE_MARKER not in remove_blankline_marker(text5)