xdoctest.doctest_part module¶
Simple storage container used to store a single executable part of a doctest
example. Multiple parts are typically stored in a
xdoctest.doctest_example.Doctest
, which manages execution of each
part.
- class xdoctest.doctest_part.DoctestPart(exec_lines, want_lines=None, line_offset=0, orig_lines=None, directives=None, partno=None)[source]¶
Bases:
object
The result of parsing that represents a “logical block” of code. If a want statement is defined, it is stored here.
- Variables:
exec_lines (List[str]) – executable lines in this part
want_lines (List[str] | None) – lines that the result of the execution should match
line_offset (int) – line number relative to the start of the doctest
orig_lines (List[str] | None) – the original text parsed into exec and want
directives (list | None) – directives that this part will apply before being run
partno (int | None) – identifies the part number in the larger example
compile_mode (str) – mode passed to compile.
- Parameters:
exec_lines (List[str]) – executable lines in this part
want_lines (List[str] | None) – lines that the result of the execution should match
line_offset (int) – line number relative to the start of the doctest
orig_lines (List[str] | None) – The original text parsed into exec and want. This is only used in formatting and may be removed in the future.
directives (list | None) – directives that this part will apply before being run. If unspecified, these will be extracted.
partno (int | None) – identifies the part number in the larger example
- property n_lines¶
Returns: int: number of lines in the entire source (i.e. exec + want)
- property n_exec_lines¶
Returns: int: number of executable lines (excluding want)
- property n_want_lines¶
Returns: int: number of lines in the “want” statement.
- property source¶
Returns: str: A single block of text representing the source code.
- compilable_source()[source]¶
Use this to build the string for compile. Takes care of a corner case.
- Returns:
str
- has_any_code()[source]¶
Heuristic to check if there is any runnable code in this doctest. We currently just check that not every line is a comment, which helps the runner count a test as skipped if only lines with comments “ran”.
- Returns:
bool
- property directives¶
- Returns:
- The extracted or provided directives to
be applied.
- Return type:
List[directive.Directive]
Example
>>> self = DoctestPart([' >>> print(', '.join(list(map(str, self.directives)))) <Directive(+SKIP)>
- property want¶
Returns: str | None: what the test is expected to produce
- check(got_stdout, got_eval=<NOT_EVALED>, runstate=None, unmatched=None)[source]¶
Check if the “got” output obtained by running this test matches the “want” target. Note there are two types of “got” output: (1) output from stdout and (2) evaled output. If both are specified, then want may match either value.
- Parameters:
got_stdout (str) – output from stdout
got_eval (str) – output from an eval statement
runstate (directive.RuntimeState) – runner options
unmatched (list) – if specified, the want statement is allowed to match any trailing sequence of unmatched output and got_stdout from this doctest part.
- Raises:
xdoctest.checker.GotWantException - If the "got" differs from this parts want. –
Example
>>> # xdoctest: +REQUIRES(module:pytest) >>> import pytest >>> got_stdout = 'more text\n' >>> unmatched = ['some text\n'] >>> self = DoctestPart(None, want_lines=['some text', 'more text']) >>> self.check(got_stdout, unmatched=unmatched) >>> # Leading junk doesnt matter if we match a trailing sequence >>> self.check(got_stdout, unmatched=['junk\n'] + unmatched) >>> # fail when want doesnt match any trailing sequence >>> with pytest.raises(checker.GotWantException): >>> self.check(got_stdout) >>> with pytest.raises(checker.GotWantException): >>> self.check(got_stdout, ['some text\n', 'junk\n'])
- format_part(linenos=True, want=True, startline=1, n_digits=None, colored=False, partnos=False, prefix=True)[source]¶
Customizable formatting of the source and want for this doctest.
- Parameters:
linenos (bool) – show line numbers
want (bool) – include the want value if it exists
startline (int) – offsets the line numbering
n_digits (int) – number of digits to use for line numbers
colored (bool) – pygmentize the code
partnos (bool) – if True, shows the part number in the string
prefix (bool) – if False, exclude the doctest ``>>> `` prefix
- Returns:
pretty text suitable for printing
- Return type:
CommandLine
python -m xdoctest.doctest_part DoctestPart.format_part
Example
>>> from xdoctest.parser import * >>> self = DoctestPart(exec_lines=['print(123)'], >>> want_lines=['123'], line_offset=0, partno=1) >>> # xdoctest: -NORMALIZE_WHITESPACE >>> print(self.format_part(partnos=True)) (p1) 1 >>> print(123) 123
Example
>>> from xdoctest.parser import * >>> self = DoctestPart(exec_lines=['print(123)'], >>> want_lines=['123'], line_offset=0, partno=1) >>> # xdoctest: -NORMALIZE_WHITESPACE >>> print(self.format_part(partnos=False, prefix=False, >>> linenos=False, want=False)) print(123)