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, got_stdout, got_eval=<NOT_EVALED>, runstate=None)[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.extract_exc_want(want)[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, want, runstate=None)[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.check_output(got, want, runstate=None)[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.normalize(got, want, runstate=None)[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, orig_ex)[source]¶

Bases: AssertionError

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

Parameters:

msg (str) – The exception message
orig_ex (Exception) – The parent exception

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

Bases: AssertionError

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

Parameters:

msg (str) – The exception message
got (str) – The unnormalized got str
want (str) – The unnormalized want str

output_difference(runstate=None, colored=True)[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_repr_difference(runstate=None)[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)[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)