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:
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:
- 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:
- 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:
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:
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:
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.
- xdoctest.checker.remove_blankline_marker(text)[source]¶
- Parameters:
text (str) – input text
- Returns:
output text
- Return type:
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)