Adopt Ruff and use stricter MyPy settings

Author: AA-Turner

.flake8

@@ -71,7 +71,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        env: [flake8, mypy]
+        env:
+          - ruff
+          - mypy
 
     steps:
       - uses: actions/checkout@v3

.github/workflows/test.yml

@@ -0,0 +1,53 @@
+target-version = "py39"  # Pin Ruff to Python 3.9
+output-format = "full"
+line-length = 95
+
+[lint]
+preview = true
+select = [
+#    "ANN",   # flake8-annotations
+    "C4",    # flake8-comprehensions
+    "COM",   # flake8-commas
+    "B",     # flake8-bugbear
+    "DTZ",   # flake8-datetimez
+    "E",     # pycodestyle
+    "EM",    # flake8-errmsg
+    "EXE",   # flake8-executable
+    "F",     # pyflakes
+    "FA",    # flake8-future-annotations
+    "FLY",   # flynt
+    "FURB",  # refurb
+    "G",     # flake8-logging-format
+    "I",     # isort
+    "ICN",   # flake8-import-conventions
+    "INT",   # flake8-gettext
+    "LOG",   # flake8-logging
+    "PERF",  # perflint
+    "PGH",   # pygrep-hooks
+    "PIE",   # flake8-pie
+    "PT",    # flake8-pytest-style
+    "SIM",   # flake8-simplify
+    "SLOT",  # flake8-slots
+    "TCH",   # flake8-type-checking
+    "UP",    # pyupgrade
+    "W",     # pycodestyle
+    "YTT",   # flake8-2020
+]
+ignore = [
+    "E116",
+    "E241",
+    "E251",
+]
+
+[lint.per-file-ignores]
+"tests/*" = [
+    "ANN",  # tests don't need annotations
+]
+
+[lint.isort]
+forced-separate = [
+    "tests",
+]
+required-imports = [
+    "from __future__ import annotations",
+]

.ruff.toml

@@ -47,7 +47,7 @@ clean-mypyfiles:
 
 .PHONY: style-check
 style-check:
-	@flake8
+	@ruff check
 
 .PHONY: type-check
 type-check:

Makefile

@@ -48,9 +48,9 @@ test = [
     "pytest",
 ]
 lint = [
-    "flake8",
+    "ruff==0.5.5",
     "mypy",
-    "docutils-stubs",
+    "types-docutils",
 ]
 standalone = [
     "Sphinx>=5",
@@ -76,4 +76,34 @@ exclude = [
 ]
 
 [tool.mypy]
-ignore_missing_imports = true
+python_version = "3.9"
+packages = [
+    "sphinxcontrib",
+    "tests",
+]
+exclude = [
+    "tests/roots",
+]
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+explicit_package_bases = true
+extra_checks = true
+no_implicit_reexport = true
+show_column_numbers = true
+show_error_context = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_configs = true
+warn_unused_ignores = true
+enable_error_code = [
+    "type-arg",
+    "redundant-self",
+    "truthy-iterable",
+    "ignore-without-code",
+    "unused-awaitable",
+]

pyproject.toml

@@ -4,7 +4,7 @@
 import pickle
 import types
 from os import path
-from typing import Any
+from typing import TYPE_CHECKING
 
 from sphinx.application import ENV_PICKLE_FILENAME, Sphinx
 from sphinx.builders.html import BuildInfo, StandaloneHTMLBuilder
@@ -13,6 +13,16 @@
 
 from sphinxcontrib.serializinghtml import jsonimpl
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import Any, Protocol
+
+    class SerialisingImplementation(Protocol):
+        def dump(self, obj: Any, file: Any, *args: Any, **kwargs: Any) -> None: ...
+        def dumps(self, obj: Any, *args: Any, **kwargs: Any) -> str | bytes: ...
+        def load(self, file: Any, *args: Any, **kwargs: Any) -> Any: ...
+        def loads(self, data: Any, *args: Any, **kwargs: Any) -> Any: ...
+
 __version__ = '1.1.10'
 __version_info__ = (1, 1, 10)
 
@@ -31,11 +41,11 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder):
     """
     #: the serializing implementation to use.  Set this to a module that
     #: implements a `dump`, `load`, `dumps` and `loads` functions
-    #: (pickle, simplejson etc.)
-    implementation: Any = None
+    #: (pickle, json etc.)
+    implementation: SerialisingImplementation
     implementation_dumps_unicode = False
     #: additional arguments for dump()
-    additional_dump_args: tuple = ()
+    additional_dump_args: Sequence[Any] = ()
 
     #: the filename for the global context file
     globalcontext_filename: str = ''
@@ -62,7 +72,7 @@ def get_target_uri(self, docname: str, typ: str | None = None) -> str:
             return docname[:-5]  # up to sep
         return docname + SEP
 
-    def dump_context(self, context: dict, filename: str | os.PathLike[str]) -> None:
+    def dump_context(self, context: dict[str, Any], filename: str | os.PathLike[str]) -> None:
         context = context.copy()
         if 'css_files' in context:
             context['css_files'] = [css.filename for css in context['css_files']]
@@ -75,7 +85,7 @@ def dump_context(self, context: dict, filename: str | os.PathLike[str]) -> None:
             with open(filename, 'wb') as fb:
                 self.implementation.dump(context, fb, *self.additional_dump_args)
 
-    def handle_page(self, pagename: str, ctx: dict, templatename: str = 'page.html',
+    def handle_page(self, pagename: str, ctx: dict[str, Any], templatename: str = 'page.html',
                     outfilename: str | None = None, event_arg: Any = None) -> None:
         ctx['current_page_name'] = pagename
         ctx.setdefault('pathto', lambda p: p)
@@ -132,7 +142,7 @@ class PickleHTMLBuilder(SerializingHTMLBuilder):
 
     implementation = pickle
     implementation_dumps_unicode = False
-    additional_dump_args = (pickle.HIGHEST_PROTOCOL,)
+    additional_dump_args: tuple[Any] = (pickle.HIGHEST_PROTOCOL,)
     indexer_format = pickle
     indexer_dumps_unicode = False
     out_suffix = '.fpickle'

sphinxcontrib/serializinghtml/__init__.py

@@ -4,7 +4,7 @@
 
 import json
 from collections import UserString
-from typing import Any, IO
+from typing import IO, Any
 
 
 class SphinxJSONEncoder(json.JSONEncoder):
@@ -15,9 +15,9 @@ def default(self, obj: Any) -> str:
         return super().default(obj)
 
 
-def dump(obj: Any, fp: IO, *args: Any, **kwds: Any) -> None:
+def dump(obj: Any, file: IO[str] | IO[bytes], *args: Any, **kwds: Any) -> None:
     kwds['cls'] = SphinxJSONEncoder
-    json.dump(obj, fp, *args, **kwds)
+    json.dump(obj, file, *args, **kwds)
 
 
 def dumps(obj: Any, *args: Any, **kwds: Any) -> str:

sphinxcontrib/serializinghtml/jsonimpl.py

@@ -1,17 +1,14 @@
+from __future__ import annotations
+
 from pathlib import Path
 
 import pytest
 
-import sphinx
-
-pytest_plugins = 'sphinx.testing.fixtures'
+pytest_plugins = (
+    'sphinx.testing.fixtures',
+)
 
 
 @pytest.fixture(scope='session')
-def rootdir():
-    if sphinx.version_info[:2] < (7, 2):
-        from sphinx.testing.path import path
-
-        return path(__file__).parent.abspath() / 'roots'
-
+def rootdir() -> Path:
     return Path(__file__).resolve().parent / 'roots'

sphinxcontrib/serializinghtml/py.typed

@@ -1,13 +1,20 @@
 """Test for serializinghtml extension."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 import pytest
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 
 @pytest.mark.sphinx('json', testroot='basic')
-def test_json(app, status, warning):
+def test_json(app: Sphinx) -> None:
     app.builder.build_all()
 
 
 @pytest.mark.sphinx('pickle', testroot='basic')
-def test_pickle(app, status, warning):
+def test_pickle(app: Sphinx) -> None:
     app.builder.build_all()