# -*- coding: utf-8 -*- """ discover and run doctests in modules and test files.""" from __future__ import absolute_import from __future__ import division from __future__ import print_function import inspect import platform import sys import traceback import warnings from contextlib import contextmanager import pytest from _pytest._code.code import ExceptionInfo from _pytest._code.code import ReprFileLocation from _pytest._code.code import TerminalRepr from _pytest.compat import safe_getattr from _pytest.fixtures import FixtureRequest from _pytest.outcomes import Skipped from _pytest.warning_types import PytestWarning DOCTEST_REPORT_CHOICE_NONE = "none" DOCTEST_REPORT_CHOICE_CDIFF = "cdiff" DOCTEST_REPORT_CHOICE_NDIFF = "ndiff" DOCTEST_REPORT_CHOICE_UDIFF = "udiff" DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE = "only_first_failure" DOCTEST_REPORT_CHOICES = ( DOCTEST_REPORT_CHOICE_NONE, DOCTEST_REPORT_CHOICE_CDIFF, DOCTEST_REPORT_CHOICE_NDIFF, DOCTEST_REPORT_CHOICE_UDIFF, DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE, ) # Lazy definition of runner class RUNNER_CLASS = None def pytest_addoption(parser): parser.addini( "doctest_optionflags", "option flags for doctests", type="args", default=["ELLIPSIS"], ) parser.addini( "doctest_encoding", "encoding used for doctest files", default="utf-8" ) group = parser.getgroup("collect") group.addoption( "--doctest-modules", action="store_true", default=False, help="run doctests in all .py modules", dest="doctestmodules", ) group.addoption( "--doctest-report", type=str.lower, default="udiff", help="choose another output format for diffs on doctest failure", choices=DOCTEST_REPORT_CHOICES, dest="doctestreport", ) group.addoption( "--doctest-glob", action="append", default=[], metavar="pat", help="doctests file matching pattern, default: test*.txt", dest="doctestglob", ) group.addoption( "--doctest-ignore-import-errors", action="store_true", default=False, help="ignore doctest ImportErrors", dest="doctest_ignore_import_errors", ) group.addoption( "--doctest-continue-on-failure", action="store_true", default=False, help="for a given doctest, continue to run after the first failure", dest="doctest_continue_on_failure", ) def pytest_collect_file(path, parent): config = parent.config if path.ext == ".py": if config.option.doctestmodules and not _is_setup_py(config, path, parent): return DoctestModule(path, parent) elif _is_doctest(config, path, parent): return DoctestTextfile(path, parent) def _is_setup_py(config, path, parent): if path.basename != "setup.py": return False contents = path.read() return "setuptools" in contents or "distutils" in contents def _is_doctest(config, path, parent): if path.ext in (".txt", ".rst") and parent.session.isinitpath(path): return True globs = config.getoption("doctestglob") or ["test*.txt"] for glob in globs: if path.check(fnmatch=glob): return True return False class ReprFailDoctest(TerminalRepr): def __init__(self, reprlocation_lines): # List of (reprlocation, lines) tuples self.reprlocation_lines = reprlocation_lines def toterminal(self, tw): for reprlocation, lines in self.reprlocation_lines: for line in lines: tw.line(line) reprlocation.toterminal(tw) class MultipleDoctestFailures(Exception): def __init__(self, failures): super(MultipleDoctestFailures, self).__init__() self.failures = failures def _init_runner_class(): import doctest class PytestDoctestRunner(doctest.DebugRunner): """ Runner to collect failures. Note that the out variable in this case is a list instead of a stdout-like object """ def __init__( self, checker=None, verbose=None, optionflags=0, continue_on_failure=True ): doctest.DebugRunner.__init__( self, checker=checker, verbose=verbose, optionflags=optionflags ) self.continue_on_failure = continue_on_failure def report_failure(self, out, test, example, got): failure = doctest.DocTestFailure(test, example, got) if self.continue_on_failure: out.append(failure) else: raise failure def report_unexpected_exception(self, out, test, example, exc_info): if isinstance(exc_info[1], Skipped): raise exc_info[1] failure = doctest.UnexpectedException(test, example, exc_info) if self.continue_on_failure: out.append(failure) else: raise failure return PytestDoctestRunner def _get_runner(checker=None, verbose=None, optionflags=0, continue_on_failure=True): # We need this in order to do a lazy import on doctest global RUNNER_CLASS if RUNNER_CLASS is None: RUNNER_CLASS = _init_runner_class() return RUNNER_CLASS( checker=checker, verbose=verbose, optionflags=optionflags, continue_on_failure=continue_on_failure, ) class DoctestItem(pytest.Item): def __init__(self, name, parent, runner=None, dtest=None): super(DoctestItem, self).__init__(name, parent) self.runner = runner self.dtest = dtest self.obj = None self.fixture_request = None def setup(self): if self.dtest is not None: self.fixture_request = _setup_fixtures(self) globs = dict(getfixture=self.fixture_request.getfixturevalue) for name, value in self.fixture_request.getfixturevalue( "doctest_namespace" ).items(): globs[name] = value self.dtest.globs.update(globs) def runtest(self): _check_all_skipped(self.dtest) self._disable_output_capturing_for_darwin() failures = [] self.runner.run(self.dtest, out=failures) if failures: raise MultipleDoctestFailures(failures) def _disable_output_capturing_for_darwin(self): """ Disable output capturing. Otherwise, stdout is lost to doctest (#985) """ if platform.system() != "Darwin": return capman = self.config.pluginmanager.getplugin("capturemanager") if capman: capman.suspend_global_capture(in_=True) out, err = capman.read_global_capture() sys.stdout.write(out) sys.stderr.write(err) def repr_failure(self, excinfo): import doctest failures = None if excinfo.errisinstance((doctest.DocTestFailure, doctest.UnexpectedException)): failures = [excinfo.value] elif excinfo.errisinstance(MultipleDoctestFailures): failures = excinfo.value.failures if failures is not None: reprlocation_lines = [] for failure in failures: example = failure.example test = failure.test filename = test.filename if test.lineno is None: lineno = None else: lineno = test.lineno + example.lineno + 1 message = type(failure).__name__ reprlocation = ReprFileLocation(filename, lineno, message) checker = _get_checker() report_choice = _get_report_choice( self.config.getoption("doctestreport") ) if lineno is not None: lines = failure.test.docstring.splitlines(False) # add line numbers to the left of the error message lines = [ "%03d %s" % (i + test.lineno + 1, x) for (i, x) in enumerate(lines) ] # trim docstring error lines to 10 lines = lines[max(example.lineno - 9, 0) : example.lineno + 1] else: lines = [ "EXAMPLE LOCATION UNKNOWN, not showing all tests of that example" ] indent = ">>>" for line in example.source.splitlines(): lines.append("??? %s %s" % (indent, line)) indent = "..." if isinstance(failure, doctest.DocTestFailure): lines += checker.output_difference( example, failure.got, report_choice ).split("\n") else: inner_excinfo = ExceptionInfo(failure.exc_info) lines += ["UNEXPECTED EXCEPTION: %s" % repr(inner_excinfo.value)] lines += traceback.format_exception(*failure.exc_info) reprlocation_lines.append((reprlocation, lines)) return ReprFailDoctest(reprlocation_lines) else: return super(DoctestItem, self).repr_failure(excinfo) def reportinfo(self): return self.fspath, self.dtest.lineno, "[doctest] %s" % self.name def _get_flag_lookup(): import doctest return dict( DONT_ACCEPT_TRUE_FOR_1=doctest.DONT_ACCEPT_TRUE_FOR_1, DONT_ACCEPT_BLANKLINE=doctest.DONT_ACCEPT_BLANKLINE, NORMALIZE_WHITESPACE=doctest.NORMALIZE_WHITESPACE, ELLIPSIS=doctest.ELLIPSIS, IGNORE_EXCEPTION_DETAIL=doctest.IGNORE_EXCEPTION_DETAIL, COMPARISON_FLAGS=doctest.COMPARISON_FLAGS, ALLOW_UNICODE=_get_allow_unicode_flag(), ALLOW_BYTES=_get_allow_bytes_flag(), ) def get_optionflags(parent): optionflags_str = parent.config.getini("doctest_optionflags") flag_lookup_table = _get_flag_lookup() flag_acc = 0 for flag in optionflags_str: flag_acc |= flag_lookup_table[flag] return flag_acc def _get_continue_on_failure(config): continue_on_failure = config.getvalue("doctest_continue_on_failure") if continue_on_failure: # We need to turn off this if we use pdb since we should stop at # the first failure if config.getvalue("usepdb"): continue_on_failure = False return continue_on_failure class DoctestTextfile(pytest.Module): obj = None def collect(self): import doctest # inspired by doctest.testfile; ideally we would use it directly, # but it doesn't support passing a custom checker encoding = self.config.getini("doctest_encoding") text = self.fspath.read_text(encoding) filename = str(self.fspath) name = self.fspath.basename globs = {"__name__": "__main__"} optionflags = get_optionflags(self) runner = _get_runner( verbose=0, optionflags=optionflags, checker=_get_checker(), continue_on_failure=_get_continue_on_failure(self.config), ) _fix_spoof_python2(runner, encoding) parser = doctest.DocTestParser() test = parser.get_doctest(text, globs, name, filename, 0) if test.examples: yield DoctestItem(test.name, self, runner, test) def _check_all_skipped(test): """raises pytest.skip() if all examples in the given DocTest have the SKIP option set. """ import doctest all_skipped = all(x.options.get(doctest.SKIP, False) for x in test.examples) if all_skipped: pytest.skip("all tests skipped by +SKIP option") def _is_mocked(obj): """ returns if a object is possibly a mock object by checking the existence of a highly improbable attribute """ return ( safe_getattr(obj, "pytest_mock_example_attribute_that_shouldnt_exist", None) is not None ) @contextmanager def _patch_unwrap_mock_aware(): """ contextmanager which replaces ``inspect.unwrap`` with a version that's aware of mock objects and doesn't recurse on them """ real_unwrap = getattr(inspect, "unwrap", None) if real_unwrap is None: yield else: def _mock_aware_unwrap(obj, stop=None): try: if stop is None or stop is _is_mocked: return real_unwrap(obj, stop=_is_mocked) return real_unwrap(obj, stop=lambda obj: _is_mocked(obj) or stop(obj)) except Exception as e: warnings.warn( "Got %r when unwrapping %r. This is usually caused " "by a violation of Python's object protocol; see e.g. " "https://github.com/pytest-dev/pytest/issues/5080" % (e, obj), PytestWarning, ) raise inspect.unwrap = _mock_aware_unwrap try: yield finally: inspect.unwrap = real_unwrap class DoctestModule(pytest.Module): def collect(self): import doctest class MockAwareDocTestFinder(doctest.DocTestFinder): """ a hackish doctest finder that overrides stdlib internals to fix a stdlib bug https://github.com/pytest-dev/pytest/issues/3456 https://bugs.python.org/issue25532 """ def _find(self, tests, obj, name, module, source_lines, globs, seen): if _is_mocked(obj): return with _patch_unwrap_mock_aware(): doctest.DocTestFinder._find( self, tests, obj, name, module, source_lines, globs, seen ) if self.fspath.basename == "conftest.py": module = self.config.pluginmanager._importconftest(self.fspath) else: try: module = self.fspath.pyimport() except ImportError: if self.config.getvalue("doctest_ignore_import_errors"): pytest.skip("unable to import module %r" % self.fspath) else: raise # uses internal doctest module parsing mechanism finder = MockAwareDocTestFinder() optionflags = get_optionflags(self) runner = _get_runner( verbose=0, optionflags=optionflags, checker=_get_checker(), continue_on_failure=_get_continue_on_failure(self.config), ) for test in finder.find(module, module.__name__): if test.examples: # skip empty doctests yield DoctestItem(test.name, self, runner, test) def _setup_fixtures(doctest_item): """ Used by DoctestTextfile and DoctestItem to setup fixture information. """ def func(): pass doctest_item.funcargs = {} fm = doctest_item.session._fixturemanager doctest_item._fixtureinfo = fm.getfixtureinfo( node=doctest_item, func=func, cls=None, funcargs=False ) fixture_request = FixtureRequest(doctest_item) fixture_request._fillfixtures() return fixture_request def _get_checker(): """ Returns a doctest.OutputChecker subclass that takes in account the ALLOW_UNICODE option to ignore u'' prefixes in strings and ALLOW_BYTES to strip b'' prefixes. Useful when the same doctest should run in Python 2 and Python 3. An inner class is used to avoid importing "doctest" at the module level. """ if hasattr(_get_checker, "LiteralsOutputChecker"): return _get_checker.LiteralsOutputChecker() import doctest import re class LiteralsOutputChecker(doctest.OutputChecker): """ Copied from doctest_nose_plugin.py from the nltk project: https://github.com/nltk/nltk Further extended to also support byte literals. """ _unicode_literal_re = re.compile(r"(\W|^)[uU]([rR]?[\'\"])", re.UNICODE) _bytes_literal_re = re.compile(r"(\W|^)[bB]([rR]?[\'\"])", re.UNICODE) def check_output(self, want, got, optionflags): res = doctest.OutputChecker.check_output(self, want, got, optionflags) if res: return True allow_unicode = optionflags & _get_allow_unicode_flag() allow_bytes = optionflags & _get_allow_bytes_flag() if not allow_unicode and not allow_bytes: return False else: # pragma: no cover def remove_prefixes(regex, txt): return re.sub(regex, r"\1\2", txt) if allow_unicode: want = remove_prefixes(self._unicode_literal_re, want) got = remove_prefixes(self._unicode_literal_re, got) if allow_bytes: want = remove_prefixes(self._bytes_literal_re, want) got = remove_prefixes(self._bytes_literal_re, got) res = doctest.OutputChecker.check_output(self, want, got, optionflags) return res _get_checker.LiteralsOutputChecker = LiteralsOutputChecker return _get_checker.LiteralsOutputChecker() def _get_allow_unicode_flag(): """ Registers and returns the ALLOW_UNICODE flag. """ import doctest return doctest.register_optionflag("ALLOW_UNICODE") def _get_allow_bytes_flag(): """ Registers and returns the ALLOW_BYTES flag. """ import doctest return doctest.register_optionflag("ALLOW_BYTES") def _get_report_choice(key): """ This function returns the actual `doctest` module flag value, we want to do it as late as possible to avoid importing `doctest` and all its dependencies when parsing options, as it adds overhead and breaks tests. """ import doctest return { DOCTEST_REPORT_CHOICE_UDIFF: doctest.REPORT_UDIFF, DOCTEST_REPORT_CHOICE_CDIFF: doctest.REPORT_CDIFF, DOCTEST_REPORT_CHOICE_NDIFF: doctest.REPORT_NDIFF, DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE: doctest.REPORT_ONLY_FIRST_FAILURE, DOCTEST_REPORT_CHOICE_NONE: 0, }[key] def _fix_spoof_python2(runner, encoding): """ Installs a "SpoofOut" into the given DebugRunner so it properly deals with unicode output. This should patch only doctests for text files because they don't have a way to declare their encoding. Doctests in docstrings from Python modules don't have the same problem given that Python already decoded the strings. This fixes the problem related in issue #2434. """ from _pytest.compat import _PY2 if not _PY2: return from doctest import _SpoofOut class UnicodeSpoof(_SpoofOut): def getvalue(self): result = _SpoofOut.getvalue(self) if encoding and isinstance(result, bytes): result = result.decode(encoding) return result runner._fakeout = UnicodeSpoof() @pytest.fixture(scope="session") def doctest_namespace(): """ Fixture that returns a :py:class:`dict` that will be injected into the namespace of doctests. """ return dict()