[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

3 files changed, 45 insertions, 29 deletions

diff --git a/searx/metrics/__init__.py b/searx/metrics/__init__.py
index 00a811635..da833a8c9 100644
--- a/searx/metrics/__init__.py
+++ b/searx/metrics/__init__.py
@@ -1,11 +1,9 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # pylint: disable=missing-module-docstring
 
-import typing
 import math
 import contextlib
 from timeit import default_timer
-from operator import itemgetter
 
 from searx.engines import engines
 from searx.openmetrics import OpenMetricsFamily
@@ -30,8 +28,8 @@ __all__ = [
 ENDPOINTS = {'search'}
 
 
-histogram_storage: typing.Optional[HistogramStorage] = None
-counter_storage: typing.Optional[CounterStorage] = None
+histogram_storage: HistogramStorage = None  # type: ignore
+counter_storage: CounterStorage = None  # type: ignore
 
 
 @contextlib.contextmanager
@@ -57,11 +55,11 @@ def histogram(*args, raise_on_not_found=True):
     return h
 
 
-def counter_inc(*args):
+def counter_inc(*args: str):
     counter_storage.add(1, *args)
 
 
-def counter_add(value, *args):
+def counter_add(value: int, *args: str):
     counter_storage.add(value, *args)
 
 
@@ -69,7 +67,7 @@ def counter(*args):
     return counter_storage.get(*args)
 
 
-def initialize(engine_names=None, enabled=True):
+def initialize(engine_names: list[str] | None = None, enabled: bool = True) -> None:
     """
     Initialize metrics
     """
@@ -174,7 +172,7 @@ def get_reliabilities(engline_name_list, checker_results):
     return reliabilities
 
 
-def get_engines_stats(engine_name_list):
+def get_engines_stats(engine_name_list: list[str]):
     assert counter_storage is not None
     assert histogram_storage is not None
 
diff --git a/searx/metrics/error_recorder.py b/searx/metrics/error_recorder.py
index df25e8d41..e653bbf2f 100644
--- a/searx/metrics/error_recorder.py
+++ b/searx/metrics/error_recorder.py
@@ -1,7 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # pylint: disable=missing-module-docstring, invalid-name
 
-import typing
+import typing as t
+
 import inspect
 from json import JSONDecodeError
 from urllib.parse import urlparse
@@ -16,7 +17,9 @@ from searx import searx_parent_dir, settings
 from searx.engines import engines
 
 
-errors_per_engines = {}
+errors_per_engines: dict[str, t.Any] = {}
+
+LogParametersType = tuple[str, ...]
 
 
 class ErrorContext:  # pylint: disable=missing-class-docstring
@@ -33,16 +36,24 @@ class ErrorContext:  # pylint: disable=missing-class-docstring
     )
 
     def __init__(  # pylint: disable=too-many-arguments
-        self, filename, function, line_no, code, exception_classname, log_message, log_parameters, secondary
+        self,
+        filename: str,
+        function: str,
+        line_no: int,
+        code: str,
+        exception_classname: str,
+        log_message: str,
+        log_parameters: LogParametersType,
+        secondary: bool,
     ):
-        self.filename = filename
-        self.function = function
-        self.line_no = line_no
-        self.code = code
-        self.exception_classname = exception_classname
-        self.log_message = log_message
-        self.log_parameters = log_parameters
-        self.secondary = secondary
+        self.filename: str = filename
+        self.function: str = function
+        self.line_no: int = line_no
+        self.code: str = code
+        self.exception_classname: str = exception_classname
+        self.log_message: str = log_message
+        self.log_parameters: LogParametersType = log_parameters
+        self.secondary: bool = secondary
 
     def __eq__(self, o) -> bool:  # pylint: disable=invalid-name
         if not isinstance(o, ErrorContext):
@@ -92,7 +103,7 @@ def add_error_context(engine_name: str, error_context: ErrorContext) -> None:
 
 def get_trace(traces):
     for trace in reversed(traces):
-        split_filename = trace.filename.split('/')
+        split_filename: list[str] = trace.filename.split('/')
         if '/'.join(split_filename[-3:-1]) == 'searx/engines':
             return trace
         if '/'.join(split_filename[-4:-1]) == 'searx/search/processors':
@@ -100,7 +111,7 @@ def get_trace(traces):
     return traces[-1]
 
 
-def get_hostname(exc: HTTPError) -> typing.Optional[None]:
+def get_hostname(exc: HTTPError) -> str | None:
     url = exc.request.url
     if url is None and exc.response is not None:
         url = exc.response.url
@@ -109,7 +120,7 @@ def get_hostname(exc: HTTPError) -> typing.Optional[None]:
 
 def get_request_exception_messages(
     exc: HTTPError,
-) -> typing.Tuple[typing.Optional[str], typing.Optional[str], typing.Optional[str]]:
+) -> tuple[str | None, str | None, str | None]:
     url = None
     status_code = None
     reason = None
@@ -128,7 +139,7 @@ def get_request_exception_messages(
     return (status_code, reason, hostname)
 
 
-def get_messages(exc, filename) -> typing.Tuple:  # pylint: disable=too-many-return-statements
+def get_messages(exc, filename) -> tuple[str, ...]:  # pylint: disable=too-many-return-statements
     if isinstance(exc, JSONDecodeError):
         return (exc.msg,)
     if isinstance(exc, TypeError):
@@ -157,7 +168,9 @@ def get_exception_classname(exc: Exception) -> str:
     return exc_module + '.' + exc_name
 
 
-def get_error_context(framerecords, exception_classname, log_message, log_parameters, secondary) -> ErrorContext:
+def get_error_context(
+    framerecords, exception_classname, log_message, log_parameters: LogParametersType, secondary: bool
+) -> ErrorContext:
     searx_frame = get_trace(framerecords)
     filename = searx_frame.filename
     if filename.startswith(searx_parent_dir):
@@ -183,7 +196,10 @@ def count_exception(engine_name: str, exc: Exception, secondary: bool = False) -
 
 
 def count_error(
-    engine_name: str, log_message: str, log_parameters: typing.Optional[typing.Tuple] = None, secondary: bool = False
+    engine_name: str,
+    log_message: str,
+    log_parameters: LogParametersType | None = None,
+    secondary: bool = False,
 ) -> None:
     if not settings['general']['enable_metrics']:
         return
diff --git a/searx/metrics/models.py b/searx/metrics/models.py
index b3ef582e0..3061e9ac8 100644
--- a/searx/metrics/models.py
+++ b/searx/metrics/models.py
@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # pylint: disable=missing-module-docstring
 
+import typing as t
+
 import decimal
 import threading
 
@@ -135,16 +137,16 @@ class CounterStorage:  # pylint: disable=missing-class-docstring
 
     def clear(self):
         with self.lock:
-            self.counters = {}
+            self.counters: dict[t.Hashable, int] = {}
 
-    def configure(self, *args):
+    def configure(self, *args: str):
         with self.lock:
             self.counters[args] = 0
 
-    def get(self, *args):
+    def get(self, *args: str):
         return self.counters[args]
 
-    def add(self, value, *args):
+    def add(self, value: int, *args: str):
         with self.lock:
             self.counters[args] += value