[pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

.venv/lib/python3.10/site-packages/_pytest/doctest.py

@@ -1,15 +1,18 @@
 # mypy: allow-untyped-defs
 """Discover and run doctests in modules and test files."""
+from __future__ import annotations
+
 import bdb
-from contextlib import contextmanager
 import functools
 import inspect
 import os
-from pathlib import Path
 import platform
 import sys
 import traceback
 import types
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
 from typing import Any
 from typing import Callable
 from typing import Dict
@@ -23,7 +26,6 @@ from typing import Tuple
 from typing import Type
 from typing import TYPE_CHECKING
 from typing import Union
-import warnings
 
 from _pytest import outcomes
 from _pytest._code.code import ExceptionInfo
@@ -49,11 +51,11 @@ if TYPE_CHECKING:
     import doctest
     from typing import Self
 
-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_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,
@@ -66,56 +68,56 @@ DOCTEST_REPORT_CHOICES = (
 # Lazy definition of runner class
 RUNNER_CLASS = None
 # Lazy definition of output checker class
-CHECKER_CLASS: Optional[Type["doctest.OutputChecker"]] = None
+CHECKER_CLASS: type[doctest.OutputChecker] | None = None
 
 
 def pytest_addoption(parser: Parser) -> None:
     parser.addini(
-        "doctest_optionflags",
-        "Option flags for doctests",
-        type="args",
-        default=["ELLIPSIS"],
+        'doctest_optionflags',
+        'Option flags for doctests',
+        type='args',
+        default=['ELLIPSIS'],
     )
     parser.addini(
-        "doctest_encoding", "Encoding used for doctest files", default="utf-8"
+        'doctest_encoding', 'Encoding used for doctest files', default='utf-8',
     )
-    group = parser.getgroup("collect")
+    group = parser.getgroup('collect')
     group.addoption(
-        "--doctest-modules",
-        action="store_true",
+        '--doctest-modules',
+        action='store_true',
         default=False,
-        help="Run doctests in all .py modules",
-        dest="doctestmodules",
+        help='Run doctests in all .py modules',
+        dest='doctestmodules',
     )
     group.addoption(
-        "--doctest-report",
+        '--doctest-report',
         type=str.lower,
-        default="udiff",
-        help="Choose another output format for diffs on doctest failure",
+        default='udiff',
+        help='Choose another output format for diffs on doctest failure',
         choices=DOCTEST_REPORT_CHOICES,
-        dest="doctestreport",
+        dest='doctestreport',
     )
     group.addoption(
-        "--doctest-glob",
-        action="append",
+        '--doctest-glob',
+        action='append',
         default=[],
-        metavar="pat",
-        help="Doctests file matching pattern, default: test*.txt",
-        dest="doctestglob",
+        metavar='pat',
+        help='Doctests file matching pattern, default: test*.txt',
+        dest='doctestglob',
     )
     group.addoption(
-        "--doctest-ignore-import-errors",
-        action="store_true",
+        '--doctest-ignore-import-errors',
+        action='store_true',
         default=False,
-        help="Ignore doctest collection errors",
-        dest="doctest_ignore_import_errors",
+        help='Ignore doctest collection errors',
+        dest='doctest_ignore_import_errors',
     )
     group.addoption(
-        "--doctest-continue-on-failure",
-        action="store_true",
+        '--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",
+        help='For a given doctest, continue to run after the first failure',
+        dest='doctest_continue_on_failure',
     )
 
 
@@ -128,11 +130,11 @@ def pytest_unconfigure() -> None:
 def pytest_collect_file(
     file_path: Path,
     parent: Collector,
-) -> Optional[Union["DoctestModule", "DoctestTextfile"]]:
+) -> DoctestModule | DoctestTextfile | None:
     config = parent.config
-    if file_path.suffix == ".py":
+    if file_path.suffix == '.py':
         if config.option.doctestmodules and not any(
-            (_is_setup_py(file_path), _is_main_py(file_path))
+            (_is_setup_py(file_path), _is_main_py(file_path)),
         ):
             return DoctestModule.from_parent(parent, path=file_path)
     elif _is_doctest(config, file_path, parent):
@@ -141,26 +143,26 @@ def pytest_collect_file(
 
 
 def _is_setup_py(path: Path) -> bool:
-    if path.name != "setup.py":
+    if path.name != 'setup.py':
         return False
     contents = path.read_bytes()
-    return b"setuptools" in contents or b"distutils" in contents
+    return b'setuptools' in contents or b'distutils' in contents
 
 
 def _is_doctest(config: Config, path: Path, parent: Collector) -> bool:
-    if path.suffix in (".txt", ".rst") and parent.session.isinitpath(path):
+    if path.suffix in ('.txt', '.rst') and parent.session.isinitpath(path):
         return True
-    globs = config.getoption("doctestglob") or ["test*.txt"]
+    globs = config.getoption('doctestglob') or ['test*.txt']
     return any(fnmatch_ex(glob, path) for glob in globs)
 
 
 def _is_main_py(path: Path) -> bool:
-    return path.name == "__main__.py"
+    return path.name == '__main__.py'
 
 
 class ReprFailDoctest(TerminalRepr):
     def __init__(
-        self, reprlocation_lines: Sequence[Tuple[ReprFileLocation, Sequence[str]]]
+        self, reprlocation_lines: Sequence[tuple[ReprFileLocation, Sequence[str]]],
     ) -> None:
         self.reprlocation_lines = reprlocation_lines
 
@@ -172,12 +174,12 @@ class ReprFailDoctest(TerminalRepr):
 
 
 class MultipleDoctestFailures(Exception):
-    def __init__(self, failures: Sequence["doctest.DocTestFailure"]) -> None:
+    def __init__(self, failures: Sequence[doctest.DocTestFailure]) -> None:
         super().__init__()
         self.failures = failures
 
 
-def _init_runner_class() -> Type["doctest.DocTestRunner"]:
+def _init_runner_class() -> type[doctest.DocTestRunner]:
     import doctest
 
     class PytestDoctestRunner(doctest.DebugRunner):
@@ -189,8 +191,8 @@ def _init_runner_class() -> Type["doctest.DocTestRunner"]:
 
         def __init__(
             self,
-            checker: Optional["doctest.OutputChecker"] = None,
-            verbose: Optional[bool] = None,
+            checker: doctest.OutputChecker | None = None,
+            verbose: bool | None = None,
             optionflags: int = 0,
             continue_on_failure: bool = True,
         ) -> None:
@@ -200,8 +202,8 @@ def _init_runner_class() -> Type["doctest.DocTestRunner"]:
         def report_failure(
             self,
             out,
-            test: "doctest.DocTest",
-            example: "doctest.Example",
+            test: doctest.DocTest,
+            example: doctest.Example,
             got: str,
         ) -> None:
             failure = doctest.DocTestFailure(test, example, got)
@@ -213,14 +215,14 @@ def _init_runner_class() -> Type["doctest.DocTestRunner"]:
         def report_unexpected_exception(
             self,
             out,
-            test: "doctest.DocTest",
-            example: "doctest.Example",
-            exc_info: Tuple[Type[BaseException], BaseException, types.TracebackType],
+            test: doctest.DocTest,
+            example: doctest.Example,
+            exc_info: tuple[type[BaseException], BaseException, types.TracebackType],
         ) -> None:
             if isinstance(exc_info[1], OutcomeException):
                 raise exc_info[1]
             if isinstance(exc_info[1], bdb.BdbQuit):
-                outcomes.exit("Quitting debugger")
+                outcomes.exit('Quitting debugger')
             failure = doctest.UnexpectedException(test, example, exc_info)
             if self.continue_on_failure:
                 out.append(failure)
@@ -231,11 +233,11 @@ def _init_runner_class() -> Type["doctest.DocTestRunner"]:
 
 
 def _get_runner(
-    checker: Optional["doctest.OutputChecker"] = None,
-    verbose: Optional[bool] = None,
+    checker: doctest.OutputChecker | None = None,
+    verbose: bool | None = None,
     optionflags: int = 0,
     continue_on_failure: bool = True,
-) -> "doctest.DocTestRunner":
+) -> doctest.DocTestRunner:
     # We need this in order to do a lazy import on doctest
     global RUNNER_CLASS
     if RUNNER_CLASS is None:
@@ -254,9 +256,9 @@ class DoctestItem(Item):
     def __init__(
         self,
         name: str,
-        parent: "Union[DoctestTextfile, DoctestModule]",
-        runner: "doctest.DocTestRunner",
-        dtest: "doctest.DocTest",
+        parent: Union[DoctestTextfile, DoctestModule],
+        runner: doctest.DocTestRunner,
+        dtest: doctest.DocTest,
     ) -> None:
         super().__init__(name, parent)
         self.runner = runner
@@ -273,31 +275,31 @@ class DoctestItem(Item):
     @classmethod
     def from_parent(  # type: ignore[override]
         cls,
-        parent: "Union[DoctestTextfile, DoctestModule]",
+        parent: Union[DoctestTextfile, DoctestModule],
         *,
         name: str,
-        runner: "doctest.DocTestRunner",
-        dtest: "doctest.DocTest",
-    ) -> "Self":
+        runner: doctest.DocTestRunner,
+        dtest: doctest.DocTest,
+    ) -> Self:
         # incompatible signature due to imposed limits on subclass
         """The public named constructor."""
         return super().from_parent(name=name, parent=parent, runner=runner, dtest=dtest)
 
     def _initrequest(self) -> None:
-        self.funcargs: Dict[str, object] = {}
+        self.funcargs: dict[str, object] = {}
         self._request = TopRequest(self, _ispytest=True)  # type: ignore[arg-type]
 
     def setup(self) -> None:
         self._request._fillfixtures()
         globs = dict(getfixture=self._request.getfixturevalue)
-        for name, value in self._request.getfixturevalue("doctest_namespace").items():
+        for name, value in self._request.getfixturevalue('doctest_namespace').items():
             globs[name] = value
         self.dtest.globs.update(globs)
 
     def runtest(self) -> None:
         _check_all_skipped(self.dtest)
         self._disable_output_capturing_for_darwin()
-        failures: List["doctest.DocTestFailure"] = []
+        failures: list[doctest.DocTestFailure] = []
         # Type ignored because we change the type of `out` from what
         # doctest expects.
         self.runner.run(self.dtest, out=failures)  # type: ignore[arg-type]
@@ -306,9 +308,9 @@ class DoctestItem(Item):
 
     def _disable_output_capturing_for_darwin(self) -> None:
         """Disable output capturing. Otherwise, stdout is lost to doctest (#985)."""
-        if platform.system() != "Darwin":
+        if platform.system() != 'Darwin':
             return
-        capman = self.config.pluginmanager.getplugin("capturemanager")
+        capman = self.config.pluginmanager.getplugin('capturemanager')
         if capman:
             capman.suspend_global_capture(in_=True)
             out, err = capman.read_global_capture()
@@ -319,14 +321,14 @@ class DoctestItem(Item):
     def repr_failure(  # type: ignore[override]
         self,
         excinfo: ExceptionInfo[BaseException],
-    ) -> Union[str, TerminalRepr]:
+    ) -> str | TerminalRepr:
         import doctest
 
-        failures: Optional[
-            Sequence[Union[doctest.DocTestFailure, doctest.UnexpectedException]]
-        ] = None
+        failures: None | (
+            Sequence[doctest.DocTestFailure | doctest.UnexpectedException]
+        ) = None
         if isinstance(
-            excinfo.value, (doctest.DocTestFailure, doctest.UnexpectedException)
+            excinfo.value, (doctest.DocTestFailure, doctest.UnexpectedException),
         ):
             failures = [excinfo.value]
         elif isinstance(excinfo.value, MultipleDoctestFailures):
@@ -348,43 +350,43 @@ class DoctestItem(Item):
             # TODO: ReprFileLocation doesn't expect a None lineno.
             reprlocation = ReprFileLocation(filename, lineno, message)  # type: ignore[arg-type]
             checker = _get_checker()
-            report_choice = _get_report_choice(self.config.getoption("doctestreport"))
+            report_choice = _get_report_choice(self.config.getoption('doctestreport'))
             if lineno is not None:
                 assert failure.test.docstring is not None
                 lines = failure.test.docstring.splitlines(False)
                 # add line numbers to the left of the error message
                 assert test.lineno is not None
                 lines = [
-                    "%03d %s" % (i + test.lineno + 1, x) for (i, x) in enumerate(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]
+                lines = lines[max(example.lineno - 9, 0): example.lineno + 1]
             else:
                 lines = [
-                    "EXAMPLE LOCATION UNKNOWN, not showing all tests of that example"
+                    'EXAMPLE LOCATION UNKNOWN, not showing all tests of that example',
                 ]
-                indent = ">>>"
+                indent = '>>>'
                 for line in example.source.splitlines():
-                    lines.append(f"??? {indent} {line}")
-                    indent = "..."
+                    lines.append(f'??? {indent} {line}')
+                    indent = '...'
             if isinstance(failure, doctest.DocTestFailure):
                 lines += checker.output_difference(
-                    example, failure.got, report_choice
-                ).split("\n")
+                    example, failure.got, report_choice,
+                ).split('\n')
             else:
                 inner_excinfo = ExceptionInfo.from_exc_info(failure.exc_info)
-                lines += ["UNEXPECTED EXCEPTION: %s" % repr(inner_excinfo.value)]
+                lines += ['UNEXPECTED EXCEPTION: %s' % repr(inner_excinfo.value)]
                 lines += [
-                    x.strip("\n") for x in traceback.format_exception(*failure.exc_info)
+                    x.strip('\n') for x in traceback.format_exception(*failure.exc_info)
                 ]
             reprlocation_lines.append((reprlocation, lines))
         return ReprFailDoctest(reprlocation_lines)
 
-    def reportinfo(self) -> Tuple[Union["os.PathLike[str]", str], Optional[int], str]:
-        return self.path, self.dtest.lineno, "[doctest] %s" % self.name
+    def reportinfo(self) -> tuple[os.PathLike[str] | str, int | None, str]:
+        return self.path, self.dtest.lineno, '[doctest] %s' % self.name
 
 
-def _get_flag_lookup() -> Dict[str, int]:
+def _get_flag_lookup() -> dict[str, int]:
     import doctest
 
     return dict(
@@ -401,7 +403,7 @@ def _get_flag_lookup() -> Dict[str, int]:
 
 
 def get_optionflags(config: Config) -> int:
-    optionflags_str = config.getini("doctest_optionflags")
+    optionflags_str = config.getini('doctest_optionflags')
     flag_lookup_table = _get_flag_lookup()
     flag_acc = 0
     for flag in optionflags_str:
@@ -410,11 +412,11 @@ def get_optionflags(config: Config) -> int:
 
 
 def _get_continue_on_failure(config: Config) -> bool:
-    continue_on_failure: bool = config.getvalue("doctest_continue_on_failure")
+    continue_on_failure: bool = 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"):
+        if config.getvalue('usepdb'):
             continue_on_failure = False
     return continue_on_failure
 
@@ -427,11 +429,11 @@ class DoctestTextfile(Module):
 
         # 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")
+        encoding = self.config.getini('doctest_encoding')
         text = self.path.read_text(encoding)
         filename = str(self.path)
         name = self.path.name
-        globs = {"__name__": "__main__"}
+        globs = {'__name__': '__main__'}
 
         optionflags = get_optionflags(self.config)
 
@@ -446,25 +448,25 @@ class DoctestTextfile(Module):
         test = parser.get_doctest(text, globs, name, filename, 0)
         if test.examples:
             yield DoctestItem.from_parent(
-                self, name=test.name, runner=runner, dtest=test
+                self, name=test.name, runner=runner, dtest=test,
             )
 
 
-def _check_all_skipped(test: "doctest.DocTest") -> None:
+def _check_all_skipped(test: doctest.DocTest) -> None:
     """Raise 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:
-        skip("all tests skipped by +SKIP option")
+        skip('all tests skipped by +SKIP option')
 
 
 def _is_mocked(obj: object) -> bool:
     """Return if an 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)
+        safe_getattr(obj, 'pytest_mock_example_attribute_that_shouldnt_exist', None)
         is not None
     )
 
@@ -476,7 +478,7 @@ def _patch_unwrap_mock_aware() -> Generator[None, None, None]:
     real_unwrap = inspect.unwrap
 
     def _mock_aware_unwrap(
-        func: Callable[..., Any], *, stop: Optional[Callable[[Any], Any]] = None
+        func: Callable[..., Any], *, stop: Callable[[Any], Any] | None = None,
     ) -> Any:
         try:
             if stop is None or stop is _is_mocked:
@@ -485,9 +487,9 @@ def _patch_unwrap_mock_aware() -> Generator[None, None, None]:
             return real_unwrap(func, stop=lambda obj: _is_mocked(obj) or _stop(func))
         except Exception as e:
             warnings.warn(
-                f"Got {e!r} when unwrapping {func!r}.  This is usually caused "
+                f'Got {e!r} when unwrapping {func!r}.  This is usually caused '
                 "by a violation of Python's object protocol; see e.g. "
-                "https://github.com/pytest-dev/pytest/issues/5080",
+                'https://github.com/pytest-dev/pytest/issues/5080',
                 PytestWarning,
             )
             raise
@@ -518,9 +520,9 @@ class DoctestModule(Module):
                 line number is returned. This will be reported upstream. #8796
                 """
                 if isinstance(obj, property):
-                    obj = getattr(obj, "fget", obj)
+                    obj = getattr(obj, 'fget', obj)
 
-                if hasattr(obj, "__wrapped__"):
+                if hasattr(obj, '__wrapped__'):
                     # Get the main obj in case of it being wrapped
                     obj = inspect.unwrap(obj)
 
@@ -531,14 +533,14 @@ class DoctestModule(Module):
                 )
 
             def _find(
-                self, tests, obj, name, module, source_lines, globs, seen
+                self, tests, obj, name, module, source_lines, globs, seen,
             ) -> None:
                 if _is_mocked(obj):
                     return
                 with _patch_unwrap_mock_aware():
                     # Type ignored because this is a private function.
                     super()._find(  # type:ignore[misc]
-                        tests, obj, name, module, source_lines, globs, seen
+                        tests, obj, name, module, source_lines, globs, seen,
                     )
 
             if sys.version_info < (3, 13):
@@ -561,8 +563,8 @@ class DoctestModule(Module):
         try:
             module = self.obj
         except Collector.CollectError:
-            if self.config.getvalue("doctest_ignore_import_errors"):
-                skip("unable to import module %r" % self.path)
+            if self.config.getvalue('doctest_ignore_import_errors'):
+                skip('unable to import module %r' % self.path)
             else:
                 raise
 
@@ -583,11 +585,11 @@ class DoctestModule(Module):
         for test in finder.find(module, module.__name__):
             if test.examples:  # skip empty doctests
                 yield DoctestItem.from_parent(
-                    self, name=test.name, runner=runner, dtest=test
+                    self, name=test.name, runner=runner, dtest=test,
                 )
 
 
-def _init_checker_class() -> Type["doctest.OutputChecker"]:
+def _init_checker_class() -> type[doctest.OutputChecker]:
     import doctest
     import re
 
@@ -633,7 +635,7 @@ def _init_checker_class() -> Type["doctest.OutputChecker"]:
                 return False
 
             def remove_prefixes(regex: Pattern[str], txt: str) -> str:
-                return re.sub(regex, r"\1\2", txt)
+                return re.sub(regex, r'\1\2', txt)
 
             if allow_unicode:
                 want = remove_prefixes(self._unicode_literal_re, want)
@@ -655,10 +657,10 @@ def _init_checker_class() -> Type["doctest.OutputChecker"]:
                 return got
             offset = 0
             for w, g in zip(wants, gots):
-                fraction: Optional[str] = w.group("fraction")
-                exponent: Optional[str] = w.group("exponent1")
+                fraction: str | None = w.group('fraction')
+                exponent: str | None = w.group('exponent1')
                 if exponent is None:
-                    exponent = w.group("exponent2")
+                    exponent = w.group('exponent2')
                 precision = 0 if fraction is None else len(fraction)
                 if exponent is not None:
                     precision -= int(exponent)
@@ -667,7 +669,7 @@ def _init_checker_class() -> Type["doctest.OutputChecker"]:
                     # got with the text we want, so that it will match when we
                     # check the string literally.
                     got = (
-                        got[: g.start() + offset] + w.group() + got[g.end() + offset :]
+                        got[: g.start() + offset] + w.group() + got[g.end() + offset:]
                     )
                     offset += w.end() - w.start() - (g.end() - g.start())
             return got
@@ -675,7 +677,7 @@ def _init_checker_class() -> Type["doctest.OutputChecker"]:
     return LiteralsOutputChecker
 
 
-def _get_checker() -> "doctest.OutputChecker":
+def _get_checker() -> doctest.OutputChecker:
     """Return a doctest.OutputChecker subclass that supports some
     additional options:
 
@@ -699,21 +701,21 @@ def _get_allow_unicode_flag() -> int:
     """Register and return the ALLOW_UNICODE flag."""
     import doctest
 
-    return doctest.register_optionflag("ALLOW_UNICODE")
+    return doctest.register_optionflag('ALLOW_UNICODE')
 
 
 def _get_allow_bytes_flag() -> int:
     """Register and return the ALLOW_BYTES flag."""
     import doctest
 
-    return doctest.register_optionflag("ALLOW_BYTES")
+    return doctest.register_optionflag('ALLOW_BYTES')
 
 
 def _get_number_flag() -> int:
     """Register and return the NUMBER flag."""
     import doctest
 
-    return doctest.register_optionflag("NUMBER")
+    return doctest.register_optionflag('NUMBER')
 
 
 def _get_report_choice(key: str) -> int:
@@ -733,8 +735,8 @@ def _get_report_choice(key: str) -> int:
     }[key]
 
 
-@fixture(scope="session")
-def doctest_namespace() -> Dict[str, Any]:
+@fixture(scope='session')
+def doctest_namespace() -> dict[str, Any]:
     """Fixture that returns a :py:class:`dict` that will be injected into the
     namespace of doctests.