Add ruff config

twmr · twmr · commit d9ede383b369 · 2025-11-28T23:39:43.000+01:00
diff --git a/pyproject.toml b/pyproject.toml
@@ -55,3 +55,76 @@ build-backend = "setuptools.build_meta"
 dev = [
     "sphinx>=8.1.3",
 ]
+
+
+[tool.ruff]
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+
+# Same as Black.
+line-length = 88
+indent-width = 4
+
+target-version = "py310"
+
+
+[tool.ruff.lint]
+select = ["E", # pycodestyle
+          "F", # pyflakes
+          "PL", # pylint
+          "UP", # refurb
+          "R", # pylint-related
+          "D", # docstring
+          "PT", # pytest
+          "B",  # bugbear
+          "D212", # summary of multi-line docstrings should start at first line
+          "D417", # undocumented-param
+          "I",  # isort
+]
+ignore = [
+    "PLR2004", # magic value used in comparison
+    "PLR0911", # too many return statements
+    "PLR0912", # too many branches
+    "PLR0915", # too many statements
+    "D100", # missing docstring in public module
+    "D101", # missing docstring in public class
+    "D102", # missing docstring in public method
+    "D103", # missing docstring in public function
+    "D104", # missing docstring in public package
+    "D105", # missing docstring in magic method
+    "D107", # missing docstring in __init__
+    "D401", # imperative mood
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.isort]
+force-single-line = true
diff --git a/src/pytest_sphinx.py b/src/pytest_sphinx.py
@@ -1,26 +1,24 @@
-"""
+"""Sphinx pytest plugin.
+
 http://www.sphinx-doc.org/en/stable/ext/doctest.html
-https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/doctest.py
+https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/doctest.py.
 
 * TODO
 ** CLEANUP: use the sphinx directive parser from the sphinx project
 """
 
+from __future__ import annotations
+
 import doctest
 import enum
 import re
 import sys
 import textwrap
 import traceback
+from collections.abc import Iterator
 from pathlib import Path
 from typing import TYPE_CHECKING
 from typing import Any
-from typing import Dict
-from typing import Iterator
-from typing import List
-from typing import Optional
-from typing import Tuple
-from typing import Union
 
 import _pytest.doctest
 import pytest
@@ -60,12 +58,12 @@ class SphinxDoctestDirectives(enum.Enum):
 
 
 def pytest_collect_file(
-    file_path: Path, parent: Union[Session, Package]
-) -> Optional[Union["SphinxDoctestModule", "SphinxDoctestTextfile"]]:
+    file_path: Path, parent: Session | Package
+) -> SphinxDoctestModule | SphinxDoctestTextfile | None:
     config = parent.config
     if file_path.suffix == ".py":
         if config.option.doctestmodules:
-            mod: Union["SphinxDoctestModule", "SphinxDoctestTextfile"] = (
+            mod: SphinxDoctestModule | SphinxDoctestTextfile = (
                 SphinxDoctestModule.from_parent(parent, path=file_path)
             )
             return mod
@@ -74,10 +72,10 @@ def pytest_collect_file(
     return None
 
 
-GlobDict = Dict[str, Any]
+GlobDict = dict[str, Any]
 
 
-def _is_doctest(config: Config, path: Path, parent: Union[Session, Package]) -> bool:
+def _is_doctest(config: Config, path: Path, parent: Session | Package) -> bool:
     if path.suffix in (".txt", ".rst") and parent.session.isinitpath(path):
         return True
     globs = config.getoption("doctestglob") or ["test*.txt"]
@@ -108,7 +106,7 @@ def _is_doctest(config: Config, path: Path, parent: Union[Session, Package]) ->
 
 def _split_into_body_and_options(
     section_content: str,
-) -> Tuple[str, Optional[str], Dict[int, bool]]:
+) -> tuple[str, str | None, dict[int, bool]]:
     """Parse the the full content of a directive and split it.
 
     It is split into a string, where the options (:options:, :hide: and
@@ -184,8 +182,8 @@ def _split_into_body_and_options(
 
 
 def _get_next_textoutputsections(
-    sections: List["Section"], index: int
-) -> Iterator["Section"]:
+    sections: list[Section], index: int
+) -> Iterator[Section]:
     """Yield successive TESTOUTPUT sections."""
     for j in range(index, len(sections)):
         section = sections[j]
@@ -195,7 +193,7 @@ def _get_next_textoutputsections(
             break
 
 
-SectionGroups = Optional[List[str]]
+SectionGroups = list[str] | None
 
 
 class Section:
@@ -221,7 +219,7 @@ def __init__(
         self.options = options
 
 
-def get_sections(docstring: str) -> List[Union[Any, Section]]:
+def get_sections(docstring: str) -> list[Any | Section]:
     lines = textwrap.dedent(docstring).splitlines()
     sections = []
 
@@ -271,11 +269,11 @@ def add_match(
 
 
 def docstring2examples(
-    docstring: str, globs: Optional[GlobDict] = None
-) -> List[Union[Any, doctest.Example]]:
-    """
-    Parse all sphinx test directives in the docstring and create a
-    list of examples.
+    docstring: str, globs: GlobDict | None = None
+) -> list[Any | doctest.Example]:
+    """Parse all sphinx test directives in the docstring.
+
+    This function also creates a list of examples that are returned.
     """
     # TODO subclass doctest.DocTestParser instead?
 
@@ -285,11 +283,11 @@ def docstring2examples(
     sections = get_sections(docstring)
 
     def get_testoutput_section_data(
-        section: "Section",
-    ) -> Tuple[str, Dict[int, bool], int, Optional[Any]]:
+        section: Section,
+    ) -> tuple[str, dict[int, bool], int, Any | None]:
         want = section.body
         exc_msg = None
-        options: Dict[int, bool] = {}
+        options: dict[int, bool] = {}
 
         if section.skipif_expr and eval(section.skipif_expr, globs):
             want = ""
@@ -344,20 +342,19 @@ def get_testoutput_section_data(
 
 
 class SphinxDocTestRunner(doctest.DebugRunner):
-    """
-    overwrite doctest.DocTestRunner.__run, since it uses 'single' for the
-    `compile` function instead of 'exec'.
+    """Overwrite `doctest.DocTestRunner.__run`.
+
+    since it uses 'single' for the `compile` function instead of 'exec'.
     """
 
-    _checker: "doctest.OutputChecker"
-    _fakeout: "_SpoofOut"
-    debugger: "pdb.Pdb"
+    _checker: doctest.OutputChecker
+    _fakeout: _SpoofOut
+    debugger: pdb.Pdb
 
     def _DocTestRunner__run(
-        self, test: doctest.DocTest, compileflags: int, out: "_Out"
+        self, test: doctest.DocTest, compileflags: int, out: _Out
     ) -> doctest.TestResults:
-        """
-        Run the examples in `test`.
+        """Run the examples in `test`.
 
         Write the outcome of each example with one of the
         `DocTestRunner.report_*` methods, using the writer function
@@ -409,7 +406,7 @@ def _DocTestRunner__run(
             # Use a special filename for compile(), so we can retrieve
             # the source code during interactive debugging (see
             # __patched_linecache_getlines).
-            filename = "<doctest %s[%d]>" % (test.name, examplenum)
+            filename = f"<doctest {test.name}[{examplenum}]>"
 
             # Run the example in the given context (globs), and record
             # any exception that gets raised.  (But don't intercept
@@ -484,7 +481,7 @@ def _DocTestRunner__run(
                     )
                 failures += 1
             else:
-                assert False, ("unknown outcome", outcome)
+                raise AssertionError(("unknown outcome", outcome))
 
             if failures and self.optionflags & doctest.FAIL_FAST:
                 break
@@ -504,7 +501,7 @@ class SphinxDocTestParser:
     def get_doctest(
         self,
         docstring: str,
-        globs: Dict[str, Any],
+        globs: dict[str, Any],
         name: str,
         filename: str,
         lineno: int,
@@ -563,7 +560,7 @@ def collect(self) -> Iterator[_pytest.doctest.DoctestItem]:
             )
         except ImportError:
             if self.config.getvalue("doctest_ignore_import_errors"):
-                pytest.skip("unable to import module %r" % self.path)
+                pytest.skip(f"unable to import module {self.path!r}")
             else:
                 raise
         optionflags = _pytest.doctest.get_optionflags(self.config)  # type:ignore
diff --git a/tests/test_doc2test.py b/tests/test_doc2test.py
@@ -10,17 +10,17 @@
 
 @pytest.mark.parametrize("in_between_content", ["", "\nsome text\nmore text"])
 def test_simple(in_between_content: str) -> None:
-    doc = """
+    doc = f"""
 .. testcode::
 
     import pprint
     pprint.pprint({{'3': 4, '5': 6}})
-{}
+{in_between_content}
 .. testoutput::
 
     {{'3': 4,
      '5': 6}}
-""".format(in_between_content)
+"""
 
     examples = docstring2examples(doc)
     assert len(examples) == 1
diff --git a/tests/test_options.py b/tests/test_options.py
@@ -87,12 +87,12 @@ def test_options_and_text() -> None:
 @pytest.mark.parametrize("with_options", [True, False])
 def test_skipif_and_text(expr: str, with_options: bool) -> None:
     want = textwrap.dedent(
-        """
-        :skipif: {}
+        f"""
+        :skipif: {expr}
 
         abcedf
         abcedf
-    """.format(expr)
+    """
     )
     if with_options:
         want = "\n:options: +NORMALIZE_WHITESPACE" + want
diff --git a/tests/test_sphinx_doctest.py b/tests/test_sphinx_doctest.py
@@ -5,9 +5,8 @@
 import subprocess
 import sys
 import textwrap
+from collections.abc import Iterator
 from pathlib import Path
-from typing import Iterator
-from typing import Union
 
 import pytest
 from _pytest._py.path import LocalPath
@@ -58,7 +57,7 @@ def __call__(
         if sphinxopts:
             cmd.append(sphinxopts)
 
-        def to_str(subprocess_output: Union[str, bytes]) -> str:
+        def to_str(subprocess_output: str | bytes) -> str:
             if isinstance(subprocess_output, bytes):
                 output_str = "\n".join(subprocess_output.decode().splitlines())
             else:
@@ -187,16 +186,16 @@ def test_doctest_multiple(
     def test_skipif_true(
         self, testdir: Testdir, sphinx_tester: SphinxDoctestRunner, testcode: str
     ) -> None:
-        code = """
+        code = f"""
             .. testcode::
 
-                {}
+                {testcode}
 
             .. testoutput::
                 :skipif: True
 
                 NOT EVALUATED
-            """.format(testcode)
+            """
 
         raise_in_testcode = testcode != "pass"
         sphinx_output = sphinx_tester(code, must_raise=raise_in_testcode)
@@ -218,16 +217,16 @@ def test_skipif_true(
     def test_skipif_false(
         self, testdir: Testdir, sphinx_tester: SphinxDoctestRunner, testcode: str
     ) -> None:
-        code = """
+        code = f"""
             .. testcode::
 
-                {}
+                {testcode}
 
             .. testoutput::
                 :skipif: False
 
                 EVALUATED
-            """.format(testcode)
+            """
 
         expected_failure = "EVALUATED" not in testcode
 
@@ -287,17 +286,17 @@ def test_skipif_multiple_testoutput(
     def test_skipif_true_in_testcode(
         self, testdir: Testdir, sphinx_tester: SphinxDoctestRunner, testcode: str
     ) -> None:
-        code = """
+        code = f"""
             .. testcode::
                 :skipif: True
 
-                {}
+                {testcode}
 
             .. testoutput::
                 :skipif: False
 
                 NOT EVALUATED
-            """.format(testcode)
+            """
 
         sphinx_output = sphinx_tester(code, must_raise=False)
         assert "0 tests" in sphinx_output
