Add type annotations to fix mypy --strict errors across all specified files

Agent-Logs-Url: https://github.com/ProperDocs/properdocs/sessions/1095dc3b-4da6-4f7c-bc57-f18d05944c90

Co-authored-by: oprypin <371383+oprypin@users.noreply.github.com>

Author: Copilot

properdocs/__main__.py

@@ -7,7 +7,8 @@
 import textwrap
 import traceback
 import warnings
-from typing import ClassVar
+from collections.abc import Callable
+from typing import Any, ClassVar
 
 import click
 
@@ -29,7 +30,14 @@
 log = logging.getLogger(__name__)
 
 
-def _showwarning(message, category, filename, lineno, file=None, line=None):
+def _showwarning(
+    message: Warning | str,
+    category: type[Warning],
+    filename: str,
+    lineno: int,
+    file: Any = None,
+    line: str | None = None,
+) -> None:
     try:
         # Last stack frames:
         # * ...
@@ -49,7 +57,7 @@ def _showwarning(message, category, filename, lineno, file=None, line=None):
     log.info(f'{category.__name__}: {message}\n{tb}')
 
 
-def _enable_warnings():
+def _enable_warnings() -> None:
     # When `python -W...` or `PYTHONWARNINGS` are used, `sys.warnoptions` is set.
     # In that case, we skip warnings configuration since
     # we don't want to overwrite the user configuration.
@@ -79,7 +87,7 @@ class ColorFormatter(logging.Formatter):
         subsequent_indent=' ' * 11,
     )
 
-    def format(self, record):
+    def format(self, record: logging.LogRecord) -> str:
         message = super().format(record)
         prefix = f'{record.levelname:<8}-  '
         if record.levelname in self.colors:
@@ -95,7 +103,7 @@ def format(self, record):
 class State:
     """Maintain logging level."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.logger = logging.getLogger('properdocs')
         self.logger.setLevel(logging.INFO)
         self.logger.propagate = False
@@ -111,7 +119,7 @@ def __init__(self):
         self.stream.name = 'ProperDocsStreamHandler'
         self.logger.addHandler(self.stream)
 
-    def __del__(self):
+    def __del__(self) -> None:
         self.logger.removeHandler(self.stream)
 
 
@@ -158,17 +166,17 @@ def __del__(self):
 )
 
 
-def add_options(*opts):
-    def inner(f):
+def add_options(*opts: Callable[..., Any]) -> Callable[..., Any]:
+    def inner(f: Callable[..., Any]) -> Callable[..., Any]:
         for i in reversed(opts):
             f = i(f)
         return f
 
     return inner
 
 
-def verbose_option(f):
-    def callback(ctx, param, value):
+def verbose_option(f: Callable[..., Any]) -> Callable[..., Any]:
+    def callback(ctx: click.Context, param: click.Parameter, value: Any) -> None:
         state = ctx.ensure_object(State)
         if value:
             state.logger.setLevel(logging.DEBUG)
@@ -183,8 +191,8 @@ def callback(ctx, param, value):
     )(f)
 
 
-def quiet_option(f):
-    def callback(ctx, param, value):
+def quiet_option(f: Callable[..., Any]) -> Callable[..., Any]:
+    def callback(ctx: click.Context, param: click.Parameter, value: Any) -> None:
         state = ctx.ensure_object(State)
         if value:
             state.logger.setLevel(logging.ERROR)
@@ -199,8 +207,8 @@ def callback(ctx, param, value):
     )(f)
 
 
-def color_option(f):
-    def callback(ctx, param, value):
+def color_option(f: Callable[..., Any]) -> Callable[..., Any]:
+    def callback(ctx: click.Context, param: click.Parameter, value: Any) -> None:
         state = ctx.ensure_object(State)
         if value is False or (
             value is None
@@ -253,7 +261,7 @@ def callback(ctx, param, value):
 )
 @common_options
 @color_option
-def cli():
+def cli() -> None:
     """ProperDocs - Project documentation with Markdown."""
 
 
@@ -271,7 +279,7 @@ def cli():
 )
 @common_config_options
 @common_options
-def serve_command(**kwargs):
+def serve_command(**kwargs: Any) -> None:
     """Run the builtin development server."""
     from properdocs.commands import serve
 
@@ -289,7 +297,7 @@ def serve_command(**kwargs):
 @common_config_options
 @click.option('-d', '--site-dir', type=click.Path(), help=site_dir_help)
 @common_options
-def build_command(clean, **kwargs):
+def build_command(clean: bool, **kwargs: Any) -> None:
     """Build the ProperDocs documentation."""
     from properdocs.commands import build
 
@@ -315,8 +323,8 @@ def build_command(clean, **kwargs):
 @click.option('-d', '--site-dir', type=click.Path(), help=site_dir_help)
 @common_options
 def gh_deploy_command(
-    clean, message, remote_branch, remote_name, force, no_history, ignore_version, shell, **kwargs
-):
+    clean: bool, message: str | None, remote_branch: str | None, remote_name: str | None, force: bool, no_history: bool, ignore_version: bool, shell: bool, **kwargs: Any
+) -> None:
     """Deploy your documentation to GitHub Pages."""
     from properdocs.commands import build, gh_deploy
 
@@ -347,7 +355,7 @@ def gh_deploy_command(
     help=projects_file_help,
     show_default=True,
 )
-def get_deps_command(config_file, projects_file):
+def get_deps_command(config_file: Any, projects_file: str | None) -> None:
     """Show required PyPI packages inferred from plugins in properdocs.yml."""
     from properdocs.commands.get_deps import get_deps, get_projects_file
     from properdocs.config.base import _open_config_file
@@ -370,7 +378,7 @@ def get_deps_command(config_file, projects_file):
 @cli.command(name="new")
 @click.argument("project_directory")
 @common_options
-def new_command(project_directory):
+def new_command(project_directory: str) -> None:
     """Create a new ProperDocs project."""
     from properdocs.commands import new
 

properdocs/contrib/search/__init__.py

@@ -7,6 +7,7 @@
 from properdocs import utils
 from properdocs.config import base
 from properdocs.config import config_options as c
+from properdocs.config.base import ValidationError
 from properdocs.contrib.search.search_index import SearchIndex
 from properdocs.plugins import BasePlugin
 
@@ -23,7 +24,7 @@
 class LangOption(c.OptionallyRequired[list[str]]):
     """Validate Language(s) provided in config are known languages."""
 
-    def get_lunr_supported_lang(self, lang):
+    def get_lunr_supported_lang(self, lang: str) -> str | None:
         fallback = {'uk': 'ru'}
         for lang_part in lang.split("_"):
             lang_part = lang_part.lower()
@@ -32,11 +33,11 @@ def get_lunr_supported_lang(self, lang):
                 return lang_part
         return None
 
-    def run_validation(self, value: object):
+    def run_validation(self, value: object) -> list[str]:
         if isinstance(value, str):
             value = [value]
         if not isinstance(value, list):
-            raise c.ValidationError('Expected a list of language codes.')
+            raise ValidationError('Expected a list of language codes.')
         for lang in value[:]:
             if lang != 'en':
                 lang_detected = self.get_lunr_supported_lang(lang)
@@ -63,7 +64,7 @@ class _PluginConfig(base.Config):
 class SearchPlugin(BasePlugin[_PluginConfig]):
     """Add a search feature to ProperDocs."""
 
-    def on_config(self, config: ProperDocsConfig, **kwargs) -> ProperDocsConfig:
+    def on_config(self, config: ProperDocsConfig, **kwargs: object) -> ProperDocsConfig:
         """Add plugin templates and scripts to config."""
         if config.theme.get('include_search_page'):
             config.theme.static_templates.add('search.html')
@@ -85,15 +86,15 @@ def on_config(self, config: ProperDocsConfig, **kwargs) -> ProperDocsConfig:
             )
         return config
 
-    def on_pre_build(self, config: ProperDocsConfig, **kwargs) -> None:
+    def on_pre_build(self, config: ProperDocsConfig, **kwargs: object) -> None:
         """Create search index instance for later use."""
         self.search_index = SearchIndex(**self.config)
 
-    def on_page_context(self, context: TemplateContext, page: Page, **kwargs) -> None:
+    def on_page_context(self, context: TemplateContext, page: Page, **kwargs: object) -> None:
         """Add page to search index."""
         self.search_index.add_entry_from_context(page)
 
-    def on_post_build(self, config: ProperDocsConfig, **kwargs) -> None:
+    def on_post_build(self, config: ProperDocsConfig, **kwargs: object) -> None:
         """Build search index."""
         output_base_path = os.path.join(config.site_dir, 'search')
         search_index = self.search_index.generate_search_index()

properdocs/contrib/search/search_index.py

@@ -5,6 +5,7 @@
 import os
 import re
 import subprocess
+from collections.abc import Iterable
 from html.parser import HTMLParser
 from typing import TYPE_CHECKING
 
@@ -28,11 +29,11 @@ class SearchIndex:
     tags and their following content are sections).
     """
 
-    def __init__(self, **config) -> None:
-        self._entries: list[dict] = []
+    def __init__(self, **config: object) -> None:
+        self._entries: list[dict[str, object]] = []
         self.config = config
 
-    def _find_toc_by_id(self, toc, id_: str | None) -> AnchorLink | None:
+    def _find_toc_by_id(self, toc: Iterable[AnchorLink], id_: str | None) -> AnchorLink | None:
         """
         Given a table of contents and HTML ID, iterate through
         and return the matched item in the TOC.
@@ -155,7 +156,9 @@ def __init__(
         self.id = id_
         self.title = title
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ContentSection):
+            return NotImplemented
         return self.text == other.text and self.id == other.id and self.title == other.title
 
 
@@ -169,8 +172,8 @@ class ContentParser(HTMLParser):
     for that section.
     """
 
-    def __init__(self, *args, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
+    def __init__(self) -> None:
+        super().__init__()
 
         self.data: list[ContentSection] = []
         self.section: ContentSection | None = None

properdocs/localization.py

@@ -13,22 +13,25 @@
     import jinja2
 
 try:
-    from babel.core import Locale, UnknownLocaleError
-    from babel.support import NullTranslations, Translations
+    from babel.core import Locale, UnknownLocaleError  # type: ignore[import-untyped]
+    from babel.support import NullTranslations, Translations  # type: ignore[import-untyped]
 
     has_babel = True
 except ImportError:  # pragma: no cover
-    from properdocs.utils.babel_stub import Locale, UnknownLocaleError  # type: ignore[assignment]
+    from properdocs.utils.babel_stub import Locale, UnknownLocaleError
 
     has_babel = False
 
+if TYPE_CHECKING:
+    from properdocs.utils.babel_stub import Locale as Locale  # noqa: F811
+
 
 log = logging.getLogger(__name__)
 base_path = os.path.dirname(os.path.abspath(__file__))
 
 
 class NoBabelExtension(InternationalizationExtension):  # pragma: no cover
-    def __init__(self, environment):
+    def __init__(self, environment: jinja2.Environment) -> None:
         Extension.__init__(self, environment)
         environment.extend(
             install_null_translations=self._install_null,