[mod] addition of various type hints / tbc

- pyright configuration [1]_
- stub files: types-lxml [2]_
- addition of various type hints
- enable use of new type system features on older Python versions [3]_
- ``.tool-versions`` - set python to lowest version we support (3.10.18) [4]_:
  Older versions typically lack some typing features found in newer Python
  versions.  Therefore, for local type checking (before commit), it is necessary
  to use the older Python interpreter.

.. [1] https://docs.basedpyright.com/v1.20.0/configuration/config-files/
.. [2] https://pypi.org/project/types-lxml/
.. [3] https://typing-extensions.readthedocs.io/en/latest/#
.. [4] https://mise.jdx.dev/configuration.html#tool-versions

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Format: reST

searx/plugins/_core.py

@@ -11,6 +11,7 @@ import inspect
 import logging
 import re
 import typing
+from collections.abc import Sequence
 
 from dataclasses import dataclass, field
 
@@ -89,7 +90,7 @@ class Plugin(abc.ABC):
 
     fqn: str = ""
 
-    def __init__(self, plg_cfg: PluginCfg) -> None:
+    def __init__(self, plg_cfg: "PluginCfg") -> None:
         super().__init__()
         if not self.fqn:
             self.fqn = self.__class__.__mro__[0].__module__
@@ -120,7 +121,7 @@ class Plugin(abc.ABC):
 
         return id(self)
 
-    def __eq__(self, other):
+    def __eq__(self, other: typing.Any):
         """py:obj:`Plugin` objects are equal if the hash values of the two
         objects are equal."""
 
@@ -166,7 +167,7 @@ class Plugin(abc.ABC):
         """
         return True
 
-    def post_search(self, request: SXNG_Request, search: "SearchWithPlugins") -> None | typing.Sequence[Result]:
+    def post_search(self, request: SXNG_Request, search: "SearchWithPlugins") -> None | Sequence[Result]:
         """Runs AFTER the search request.  Can return a list of
         :py:obj:`Result <searx.result_types._base.Result>` objects to be added to the
         final result list."""
@@ -207,7 +208,7 @@ class PluginStorage:
 
         return [p.info for p in self.plugin_list]
 
-    def load_settings(self, cfg: dict[str, dict]):
+    def load_settings(self, cfg: dict[str, dict[str, typing.Any]]):
         """Load plugins configured in SearXNG's settings :ref:`settings
         plugins`."""
 

searx/plugins/ahmia_filter.py

@@ -1,25 +1,26 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # pylint: disable=missing-module-docstring
-from __future__ import annotations
-import typing
+
+import typing as t
 from hashlib import md5
 
-from flask_babel import gettext
+from flask_babel import gettext  # pyright: ignore[reportUnknownVariableType]
 
 from searx.data import ahmia_blacklist_loader
 from searx import get_setting
 from searx.plugins import Plugin, PluginInfo
 
-if typing.TYPE_CHECKING:
+if t.TYPE_CHECKING:
     import flask
     from searx.search import SearchWithPlugins
     from searx.extended_types import SXNG_Request
     from searx.result_types import Result
     from searx.plugins import PluginCfg
 
-ahmia_blacklist: list = []
+ahmia_blacklist: list[str] = []
 
 
+@t.final
 class SXNGPlugin(Plugin):
     """Filter out onion results that appear in Ahmia's blacklist (See https://ahmia.fi/blacklist)."""
 
@@ -35,7 +36,7 @@ class SXNGPlugin(Plugin):
         )
 
     def on_result(
-        self, request: "SXNG_Request", search: "SearchWithPlugins", result: Result
+        self, request: "SXNG_Request", search: "SearchWithPlugins", result: "Result"
     ) -> bool:  # pylint: disable=unused-argument
         if not getattr(result, "is_onion", False) or not getattr(result, "parsed_url", False):
             return True

searx/plugins/hostnames.py

@@ -1,10 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # pylint: disable=too-many-branches, unused-argument
-"""
-
-During the initialization phase, the plugin checks whether a ``hostnames:``
-configuration exists. If this is not the case, the plugin is not included
-in the PluginStorage (it is not available for selection).
+"""During the initialization phase, the plugin checks whether a ``hostnames:``
+configuration exists. If this is not the case, the plugin is not included in the
+PluginStorage (it is not available for selection).
 
 - ``hostnames.replace``: A **mapping** of regular expressions to hostnames to be
   replaced by other hostnames.
@@ -82,13 +80,12 @@ something like this:
 
 """
 
-from __future__ import annotations
-import typing
+import typing as t
 
 import re
 from urllib.parse import urlunparse, urlparse
 
-from flask_babel import gettext
+from flask_babel import gettext  # pyright: ignore[reportUnknownVariableType]
 
 from searx import settings
 from searx.result_types._base import MainResult, LegacyResult
@@ -97,14 +94,13 @@ from searx.plugins import Plugin, PluginInfo
 
 from ._core import log
 
-if typing.TYPE_CHECKING:
+if t.TYPE_CHECKING:
     import flask
     from searx.search import SearchWithPlugins
     from searx.extended_types import SXNG_Request
     from searx.result_types import Result
     from searx.plugins import PluginCfg
 
-
 REPLACE: dict[re.Pattern, str] = {}
 REMOVE: set = set()
 HIGH: set = set()
@@ -125,7 +121,7 @@ class SXNGPlugin(Plugin):
             preference_section="general",
         )
 
-    def on_result(self, request: "SXNG_Request", search: "SearchWithPlugins", result: Result) -> bool:
+    def on_result(self, request: "SXNG_Request", search: "SearchWithPlugins", result: "Result") -> bool:
 
         for pattern in REMOVE:
             if result.parsed_url and pattern.search(result.parsed_url.netloc):

searx/plugins/tracker_url_remover.py

@@ -1,28 +1,27 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # pylint: disable=missing-module-docstring, unused-argument
 
-from __future__ import annotations
-
 import logging
-import typing
+import typing as t
 
-from flask_babel import gettext
+from flask_babel import gettext  # pyright: ignore[reportUnknownVariableType]
 
 from searx.data import TRACKER_PATTERNS
 
 from . import Plugin, PluginInfo
 
-if typing.TYPE_CHECKING:
+if t.TYPE_CHECKING:
     import flask
     from searx.search import SearchWithPlugins
     from searx.extended_types import SXNG_Request
-    from searx.result_types import Result, LegacyResult
+    from searx.result_types import Result, LegacyResult  # pyright: ignore[reportPrivateLocalImportUsage]
     from searx.plugins import PluginCfg
 
 
 log = logging.getLogger("searx.plugins.tracker_url_remover")
 
 
+@t.final
 class SXNGPlugin(Plugin):
     """Remove trackers arguments from the returned URL."""
 
@@ -42,7 +41,7 @@ class SXNGPlugin(Plugin):
         TRACKER_PATTERNS.init()
         return True
 
-    def on_result(self, request: "SXNG_Request", search: "SearchWithPlugins", result: Result) -> bool:
+    def on_result(self, request: "SXNG_Request", search: "SearchWithPlugins", result: "Result") -> bool:
 
         result.filter_urls(self.filter_url_field)
         return True