Module doc_checker.

DocChecker

The DocChecker class is used to help verify the documentation code examples. It builds upon Sybil and provides the ability to adjust the doc examples so that they verify correctly. If, for instance, a code example involves a timestamp, the expected output written at the time of the example will fail to match the timestamp generated when the example is tested. Example 1 below shows a way to make the adjustment to the timestamp so that it will match.

The DocChecker also has a way to print messages for troubleshooting cases that fail to verify. In example 1 below, the line

self.msgs.append([old_want, want, old_got, got])

will show the input and output values to help solve problems. Using messages is optional and can be customized for any purpose.

Example 1:

This example shows how to make an adjustment to accommodate doc examples in a module called time_hdr that have timestamps in the output. The code needs to replace the timestamps in the ‘want’ variable so that it will match the timestamp from running the example at the time of the doctest. Place the following code into a conftest.py file in the project top directory (see scottbrian-utils for an example).

from doctest import ELLIPSIS
from doctest import OutputChecker as BaseOutputChecker

import re

from sybil import Sybil
from sybil.parsers.rest import PythonCodeBlockParser

from scottbrian_utils.time_hdr import get_datetime_match_string
from scottbrian_utils.doc_checker import DocCheckerTestParser

from typing import Any

class SbtDocCheckerOutputChecker(DocCheckerOutputChecker):
    def __init__(self) -> None:
        super().__init__()

    def check_output(self, want, got, optionflags):
        old_want = want
        old_got = got

        def repl_dt(match_obj: Any) -> str:
            return found_items.__next__().group()

        if self.mod_name == 'time_hdr' or self.mod_name == 'README':
            # find the actual occurrences and replace in want
            for time_hdr_dt_format in ["%a %b %d %Y %H:%M:%S",
                                       "%m/%d/%y %H:%M:%S"]:
                match_str = get_datetime_match_string(
                                time_hdr_dt_format)

                match_re = re.compile(match_str)
                found_items = match_re.finditer(got)
                want = match_re.sub(repl_dt, want)

            # replace elapsed time in both want and got
            match_str = 'Elapsed time: 0:00:00.[0-9| ]{6,6}'
            replacement = 'Elapsed time: 0:00:00       '
            want = re.sub(match_str, replacement, want)
            got = re.sub(match_str, replacement, got)

        self.msgs.append([old_want, want, old_got, got])
        return super().check_output(want, got, optionflags)


pytest_collect_file = Sybil(
    parsers=[
        DocCheckerTestParser(optionflags=ELLIPSIS,
                             doc_checker_output_checker=SbtDocCheckerOutputChecker()
                             ),
        PythonCodeBlockParser(),],
    patterns=['*.rst', '*.py'],
    ).pytest()

Example 2:

For standard doctest checking with no special cases, place the following code into a conftest.py file in the project top directory (see scottbrian-locking for an example).

from doctest import ELLIPSIS

from sybil import Sybil
from sybil.parsers.rest import PythonCodeBlockParser

from scottbrian_utils.doc_checker import DocCheckerTestParser


pytest_collect_file = Sybil(
    parsers=[
        DocCheckerTestParser(optionflags=ELLIPSIS,
                             ),
        PythonCodeBlockParser(),],
    patterns=['*.rst', '*.py'],
    ).pytest()

class doc_checker.DocCheckerOutputChecker

Initialize the output checker object.

check_output(want, got, optionflags)

Check the output of the example against expected value.

Parameters:

• want (str) – the expected value of the example output

• got (str) – the actual value of the example output

• optionflags (int) – doctest option flags for the Sybil BaseOutPutChecker check_output method

Return type:

bool

Returns:

True if the want and got values match, False otherwise

class doc_checker.DocCheckerTestEvaluator(doc_checker_output_checker, optionflags=0)

Initialize the evaluator object.

Parameters:

• doc_checker_output_checker (DocCheckerOutputChecker) – invocation of the output check to use

• optionflags (int) – flags passed along to the Sybil DocTestEvaluator