ci: Update lint/type-checking

Author: pawamoy

config/ruff.toml

@@ -18,13 +18,16 @@ ignore = [
     "EM101",  # String literal when raising exception
     "EM102",  # f-string when raising exception
     "ERA001",  # Commented out code
+    "FIX",  # TODO, FIXME, etc.
     "G004",  # Logging statement uses f-string
     "PLR0911",  # Too many return statements
     "PLR0912",  # Too many branches
     "PLR0913",  # Too many arguments to function call
     "PLR0915",  # Too many statements
     "SLF001", # Private member accessed
     "S704", # Unsafe use of `markupsafe.Markup`
+    "TD002",  # Missing author in TODO
+    "TD003",  # Missing issue link for TODO
     "TRY003",  # Avoid specifying long messages outside the exception class
 ]
 

config/ty.toml

@@ -0,0 +1,2 @@
+[src]
+exclude = ["tests/fixtures"]

duties.py

@@ -79,7 +79,13 @@ def check_types(ctx: Context) -> None:
     """Check that the code is correctly typed."""
     py = f"{sys.version_info.major}.{sys.version_info.minor}"
     ctx.run(
-        tools.ty.check(*PY_SRC_LIST, color=True, error_on_warning=True, python_version=py),
+        tools.ty.check(
+            *PY_SRC_LIST,
+            config_file="config/ty.toml",
+            color=True,
+            error_on_warning=True,
+            python_version=py,
+        ),
         title=pyprefix("Type-checking"),
     )
 

src/mkdocstrings/_internal/download.py

@@ -1,14 +1,19 @@
+from __future__ import annotations
+
 import base64
 import gzip
 import os
 import re
 import urllib.parse
 import urllib.request
-from collections.abc import Mapping
-from typing import BinaryIO, Optional
+from typing import TYPE_CHECKING, BinaryIO
 
 from mkdocstrings._internal.loggers import get_logger
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
 _logger = get_logger("mkdocstrings")
 
 # Regex pattern for an environment variable in the form ${ENV_VAR}.
@@ -25,11 +30,11 @@ def _download_url_with_gz(url: str) -> bytes:
     with urllib.request.urlopen(req) as resp:  # noqa: S310
         content: BinaryIO = resp
         if "gzip" in resp.headers.get("content-encoding", ""):
-            content = gzip.GzipFile(fileobj=resp)  # type: ignore[assignment]
+            content = gzip.GzipFile(fileobj=resp)  # ty: ignore[invalid-assignment]
         return content.read()
 
 
-def _expand_env_vars(credential: str, url: str, env: Optional[Mapping[str, str]] = None) -> str:
+def _expand_env_vars(credential: str, url: str, env: Mapping[str, str] | None = None) -> str:
     """A safe implementation of environment variable substitution.
 
     It only supports the following forms: `${ENV_VAR}`.

src/mkdocstrings/_internal/extension.py

@@ -189,7 +189,7 @@ def _process_block(
         if "locale" in signature(handler.render).parameters:
             render = partial(handler.render, locale=self._handlers._locale)
         else:
-            render = handler.render  # type: ignore[assignment]
+            render = handler.render
         try:
             rendered = render(data, options)
         except TemplateNotFound as exc:
@@ -301,7 +301,7 @@ def _remove_duplicated_headings(self, parent: Element) -> None:
 
 class _TocLabelsTreeProcessor(Treeprocessor):
     def run(self, root: Element) -> None:  # noqa: ARG002
-        self._override_toc_labels(self.md.toc_tokens)  # type: ignore[attr-defined]
+        self._override_toc_labels(self.md.toc_tokens)  # ty: ignore[unresolved-attribute]
 
     def _override_toc_labels(self, tokens: list[dict[str, Any]]) -> None:
         for token in tokens:
@@ -349,7 +349,7 @@ def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802 (casing: parent me
 
         # Zensical integration: get the current page from the Zensical-specific preprocessor.
         if "zensical_current_page" in md.preprocessors:
-            self._autorefs.current_page = md.preprocessors["zensical_current_page"]  # type: ignore[assignment]
+            self._autorefs.current_page = md.preprocessors["zensical_current_page"]
 
         md.parser.blockprocessors.register(
             AutoDocProcessor(md, handlers=self._handlers, autorefs=self._autorefs),
@@ -389,7 +389,7 @@ def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802 (casing: parent me
 
 def _split_configs(markdown_extensions: list[str | dict]) -> tuple[list[str | Extension], dict[str, Any]]:
     # Split markdown extensions and their configs from mkdocs.yml
-    mdx: list[str] = []
+    mdx: list[str | Extension] = []
     mdx_config: dict[str, Any] = {}
     for item in markdown_extensions:
         if isinstance(item, str):
@@ -399,7 +399,7 @@ def _split_configs(markdown_extensions: list[str | dict]) -> tuple[list[str | Ex
                 mdx.append(key)
                 mdx_config[key] = value
                 break  # Only one item per dict
-    return mdx, mdx_config  # type: ignore[return-value]
+    return mdx, mdx_config
 
 
 class _ToolConfig:

src/mkdocstrings/_internal/handlers/base.py

@@ -150,16 +150,14 @@ def __init__(
 
         # add extended theme templates
         extended_templates_dirs = self.get_extended_templates_dirs(self.name)
-        for templates_dir in extended_templates_dirs:
-            paths.append(templates_dir / self.theme)
+        paths.extend(templates_dir / self.theme for templates_dir in extended_templates_dirs)
 
         # add fallback theme templates
         if self.fallback_theme and self.fallback_theme != self.theme:
             paths.append(themes_dir / self.fallback_theme)
 
             # add fallback theme of extended templates
-            for templates_dir in extended_templates_dirs:
-                paths.append(templates_dir / self.fallback_theme)
+            paths.extend(templates_dir / self.fallback_theme for templates_dir in extended_templates_dirs)
 
         for path in paths:
             css_path = path / "style.css"
@@ -361,24 +359,24 @@ def do_convert_markdown(
         global _markdown_conversion_layer  # noqa: PLW0603
         _markdown_conversion_layer += 1
         treeprocessors = self.md.treeprocessors
-        treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level  # type: ignore[attr-defined]
-        treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"  # type: ignore[attr-defined]
-        treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph  # type: ignore[attr-defined]
+        treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level
+        treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"
+        treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph
         if BacklinksTreeProcessor.name in treeprocessors:
-            treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id  # type: ignore[attr-defined]
+            treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id
         if autoref_hook and AutorefsInlineProcessor.name in self.md.inlinePatterns:
-            self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook  # type: ignore[attr-defined]
+            self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook  # ty: ignore[unresolved-attribute]
 
         try:
             return Markup(self.md.convert(text))
         finally:
-            treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0  # type: ignore[attr-defined]
-            treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""  # type: ignore[attr-defined]
-            treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False  # type: ignore[attr-defined]
+            treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0
+            treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""
+            treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False
             if BacklinksTreeProcessor.name in treeprocessors:
-                treeprocessors[BacklinksTreeProcessor.name].initial_id = None  # type: ignore[attr-defined]
+                treeprocessors[BacklinksTreeProcessor.name].initial_id = None
             if AutorefsInlineProcessor.name in self.md.inlinePatterns:
-                self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None  # type: ignore[attr-defined]
+                self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None
             self.md.reset()
             _markdown_conversion_layer -= 1
 
@@ -475,11 +473,11 @@ def _update_env(self, md: Markdown, *, config: Any | None = None) -> None:
         # MkDocs adds its own (required) extension that's not part of the config. Propagate it.
         if "relpath" in md.treeprocessors:
             relpath = md.treeprocessors["relpath"]
-            new_relpath = type(relpath)(relpath.file, relpath.files, relpath.config)  # type: ignore[attr-defined,call-arg]
+            new_relpath = type(relpath)(relpath.file, relpath.files, relpath.config)
             new_md.treeprocessors.register(new_relpath, "relpath", priority=0)
         elif "zrelpath" in md.treeprocessors:
             zrelpath = md.treeprocessors["zrelpath"]
-            new_zrelpath = type(zrelpath)(new_md, zrelpath.path, zrelpath.use_directory_urls)  # type: ignore[attr-defined,call-arg]
+            new_zrelpath = type(zrelpath)(new_md, zrelpath.path, zrelpath.use_directory_urls)
             new_md.treeprocessors.register(new_zrelpath, "zrelpath", priority=0)
 
         self._md = new_md
@@ -603,7 +601,7 @@ def _download_inventories(self) -> None:
         for handler_name, conf in self._handlers_config.items():
             handler = self.get_handler(handler_name)
 
-            if handler.get_inventory_urls.__func__ is BaseHandler.get_inventory_urls:  # type: ignore[attr-defined]
+            if handler.get_inventory_urls.__func__ is BaseHandler.get_inventory_urls:
                 if inv_configs := conf.pop("import", ()):
                     warn(
                         "mkdocstrings v1 will stop handling 'import' in handlers configuration. "
@@ -645,7 +643,7 @@ def _yield_inventory_items(self) -> Iterator[tuple[str, str]]:
             for fut, (handler, url, conf) in reversed(self._inv_futures.items()):
                 try:
                     yield from handler.load_inventory(BytesIO(fut.result()), url, **conf)
-                except Exception as error:  # noqa: BLE001
+                except Exception as error:  # noqa: BLE001,PERF203
                     _logger.error("Couldn't load inventory %s through handler '%s': %s", url, handler.name, error)  # noqa: TRY400
             self._inv_futures = {}
 

src/mkdocstrings/_internal/handlers/rendering.py

@@ -84,7 +84,7 @@ def __init__(self, md: Markdown):
         self._css_class = config.pop("css_class", "highlight")
         super().__init__(**{name: opt for name, opt in config.items() if name in self._highlight_config_keys})
 
-    def highlight(
+    def highlight(  # ty: ignore[invalid-method-override]
         self,
         src: str,
         language: str | None = None,
@@ -113,7 +113,7 @@ def highlight(
             src = textwrap.dedent(src)
 
         kwargs.setdefault("css_class", self._css_class)
-        old_linenums = self.linenums  # type: ignore[has-type]
+        old_linenums = self.linenums
         if linenums is not None:
             self.linenums = linenums
         try:
@@ -240,7 +240,7 @@ def __init__(self, md: Markdown, headings: list[Element]):
 
     def run(self, root: Element) -> None:
         """Record all heading elements encountered in the document."""
-        permalink_class = self.md.treeprocessors["toc"].permalink_class  # type: ignore[attr-defined]
+        permalink_class = self.md.treeprocessors["toc"].permalink_class
         for el in root.iter():
             if self.regex.fullmatch(el.tag):
                 el = copy.copy(el)  # noqa: PLW2901

src/mkdocstrings/_internal/loggers.py

@@ -82,7 +82,7 @@ def log(self, level: int, msg: object, *args: object, **kwargs: object) -> None:
             if (key := (self, str(msg))) in self._logged:
                 return
             self._logged.add(key)
-        super().log(level, msg, *args, **kwargs)  # type: ignore[arg-type]
+        super().log(level, msg, *args, **kwargs)  # ty: ignore[invalid-argument-type]
 
 
 class TemplateLogger:

src/mkdocstrings/_internal/plugin.py

@@ -140,7 +140,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         handlers = Handlers(
             default=self.config.default_handler,
             handlers_config=self.config.handlers,
-            theme=config.theme.name or os.path.dirname(config.theme.dirs[0]),
+            theme=config.theme.name or os.path.dirname(config.theme.dirs[0]),  # noqa: PTH120
             custom_templates=self.config.custom_templates,
             mdx=config.markdown_extensions,
             mdx_config=config.mdx_configs,
@@ -156,7 +156,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         autorefs: AutorefsPlugin
         try:
             # If autorefs plugin is explicitly enabled, just use it.
-            autorefs = config.plugins["autorefs"]  # type: ignore[assignment]
+            autorefs = config.plugins["autorefs"]  # ty: ignore[invalid-assignment]
             _logger.debug("Picked up existing autorefs instance %r", autorefs)
         except KeyError:
             # Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
@@ -167,7 +167,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
             _logger.debug("Added a subdued autorefs instance %r", autorefs)
 
         mkdocstrings_extension = MkdocstringsExtension(handlers, autorefs)
-        config.markdown_extensions.append(mkdocstrings_extension)  # type: ignore[arg-type]
+        config.markdown_extensions.append(mkdocstrings_extension)  # ty: ignore[invalid-argument-type]
 
         config.extra_css.insert(0, self.css_filename)  # So that it has lower priority than user files.
 
@@ -199,22 +199,22 @@ def plugin_enabled(self) -> bool:
     @event_priority(50)  # Early, before autorefs' starts applying cross-refs and collecting backlinks.
     def _on_env_load_inventories(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
         if self.plugin_enabled and self._handlers:
-            register = config.plugins["autorefs"].register_url  # type: ignore[attr-defined]
+            register = config.plugins["autorefs"].register_url  # ty: ignore[possibly-missing-attribute]
             for identifier, url in self._handlers._yield_inventory_items():
                 register(identifier, url)
 
     @event_priority(-20)  # Late, not important.
     def _on_env_add_css(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
         if self.plugin_enabled and self._handlers:
             css_content = "\n".join(handler.extra_css for handler in self.handlers.seen_handlers)
-            write_file(css_content.encode("utf-8"), os.path.join(config.site_dir, self.css_filename))
+            write_file(css_content.encode("utf-8"), os.path.join(config.site_dir, self.css_filename))  # noqa: PTH118
 
     @event_priority(-20)  # Late, not important.
     def _on_env_write_inventory(self, env: Environment, config: MkDocsConfig, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
         if self.plugin_enabled and self._handlers and self.inventory_enabled:
             _logger.debug("Creating inventory file objects.inv")
             inv_contents = self.handlers.inventory.format_sphinx()
-            write_file(inv_contents, os.path.join(config.site_dir, "objects.inv"))
+            write_file(inv_contents, os.path.join(config.site_dir, "objects.inv"))  # noqa: PTH118
 
     @event_priority(-100)  # Last, after autorefs has finished applying cross-refs and collecting backlinks.
     def _on_env_apply_backlinks(self, env: Environment, /, *, config: MkDocsConfig, files: Files) -> Environment:  # noqa: ARG002
@@ -226,12 +226,12 @@ def repl(match: Match) -> str:
 
             # The handler doesn't implement backlinks,
             # return early to avoid computing them.
-            if handler.render_backlinks.__func__ is BaseHandler.render_backlinks:  # type: ignore[attr-defined]
+            if handler.render_backlinks.__func__ is BaseHandler.render_backlinks:
                 return ""
 
             identifier = match.group(1)
             aliases = handler.get_aliases(identifier)
-            backlinks = self._autorefs.get_backlinks(identifier, *aliases, from_url=file.page.url)  # type: ignore[union-attr]
+            backlinks = self._autorefs.get_backlinks(identifier, *aliases, from_url=file.page.url)
 
             # No backlinks, avoid calling the handler's method.
             if not backlinks:
@@ -240,7 +240,7 @@ def repl(match: Match) -> str:
             if "locale" in signature(handler.render_backlinks).parameters:
                 render_backlinks = partial(handler.render_backlinks, locale=self.handlers._locale)
             else:
-                render_backlinks = handler.render_backlinks  # type: ignore[assignment]
+                render_backlinks = handler.render_backlinks
 
             return render_backlinks(backlinks)
 

tests/conftest.py

@@ -23,7 +23,7 @@ def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Itera
     """Yield a MkDocs configuration object."""
     conf = MkDocsConfig()
     while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"):
-        request = request._parent_request
+        request = request._parent_request  # ty: ignore[invalid-assignment]
 
     conf_dict = {
         "site_name": "foo",
@@ -33,7 +33,7 @@ def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Itera
         **getattr(request, "param", {}),
     }
     # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289
-    mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", [])))
+    mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", [])))  # ty: ignore[invalid-argument-type]
 
     conf.load_dict(conf_dict)
     assert conf.validate() == ([], [])