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)

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()

Use this to build the string for compile. Takes care of a corner case.

Returns:

str

has_any_code()

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)

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)

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:

str

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)