[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

1 files changed, 35 insertions, 17 deletions

diff --git a/searx/enginelib/__init__.py b/searx/enginelib/__init__.py
index 3fa4edabb..a78981561 100644
--- a/searx/enginelib/__init__.py
+++ b/searx/enginelib/__init__.py
@@ -22,21 +22,25 @@ an example in which the command line is called in the development environment::
 -----
 
 """
-from __future__ import annotations
 
 __all__ = ["EngineCache", "Engine", "ENGINES_CACHE"]
 
-from typing import List, Callable, TYPE_CHECKING, Any
+import typing as t
+import abc
+from collections.abc import Callable
+import logging
 import string
 import typer
 
-from ..cache import ExpireCache, ExpireCacheCfg
+from ..cache import ExpireCacheSQLite, ExpireCacheCfg
 
-if TYPE_CHECKING:
+if t.TYPE_CHECKING:
     from searx.enginelib import traits
+    from searx.enginelib.traits import EngineTraits
+    from searx.extended_types import SXNG_Response
+    from searx.result_types import EngineResults
 
-
-ENGINES_CACHE = ExpireCache.build_cache(
+ENGINES_CACHE: ExpireCacheSQLite = ExpireCacheSQLite.build_cache(
     ExpireCacheCfg(
         name="ENGINES_CACHE",
         MAXHOLD_TIME=60 * 60 * 24 * 7,  # 7 days
@@ -62,7 +66,7 @@ def state():
     title = f"properties of {ENGINES_CACHE.cfg.name}"
     print(title)
     print("=" * len(title))
-    print(str(ENGINES_CACHE.properties))  # type: ignore
+    print(str(ENGINES_CACHE.properties))
 
 
 @app.command()
@@ -152,11 +156,11 @@ class EngineCache:
     """
 
     def __init__(self, engine_name: str, expire: int | None = None):
-        self.expire = expire or ENGINES_CACHE.cfg.MAXHOLD_TIME
+        self.expire: int = expire or ENGINES_CACHE.cfg.MAXHOLD_TIME
         _valid = "-_." + string.ascii_letters + string.digits
-        self.table_name = "".join([c if c in _valid else "_" for c in engine_name])
+        self.table_name: str = "".join([c if c in _valid else "_" for c in engine_name])
 
-    def set(self, key: str, value: Any, expire: int | None = None) -> bool:
+    def set(self, key: str, value: t.Any, expire: int | None = None) -> bool:
         return ENGINES_CACHE.set(
             key=key,
             value=value,
@@ -164,14 +168,14 @@ class EngineCache:
             ctx=self.table_name,
         )
 
-    def get(self, key: str, default=None) -> Any:
+    def get(self, key: str, default: t.Any = None) -> t.Any:
         return ENGINES_CACHE.get(key, default=default, ctx=self.table_name)
 
     def secret_hash(self, name: str | bytes) -> str:
         return ENGINES_CACHE.secret_hash(name=name)
 
 
-class Engine:  # pylint: disable=too-few-public-methods
+class Engine(abc.ABC):  # pylint: disable=too-few-public-methods
     """Class of engine instances build from YAML settings.
 
     Further documentation see :ref:`general engine configuration`.
@@ -181,6 +185,8 @@ class Engine:  # pylint: disable=too-few-public-methods
        This class is currently never initialized and only used for type hinting.
     """
 
+    logger: logging.Logger
+
     # Common options in the engine module
 
     engine_type: str
@@ -220,15 +226,15 @@ class Engine:  # pylint: disable=too-few-public-methods
         region: fr-BE
     """
 
-    fetch_traits: Callable
+    fetch_traits: "Callable[[EngineTraits, bool], None]"
     """Function to to fetch engine's traits from origin."""
 
-    traits: traits.EngineTraits
+    traits: "traits.EngineTraits"
     """Traits of the engine."""
 
     # settings.yml
 
-    categories: List[str]
+    categories: list[str]
     """Specifies to which :ref:`engine categories` the engine should be added."""
 
     name: str
@@ -269,7 +275,7 @@ class Engine:  # pylint: disable=too-few-public-methods
     inactive: bool
     """Remove the engine from the settings (*disabled & removed*)."""
 
-    about: dict
+    about: dict[str, dict[str, str]]
     """Additional fields describing the engine.
 
     .. code:: yaml
@@ -291,9 +297,21 @@ class Engine:  # pylint: disable=too-few-public-methods
     the user is used to build and send a ``Accept-Language`` header in the
     request to the origin search engine."""
 
-    tokens: List[str]
+    tokens: list[str]
     """A list of secret tokens to make this engine *private*, more details see
     :ref:`private engines`."""
 
     weight: int
     """Weighting of the results of this engine (:ref:`weight <settings engines>`)."""
+
+    def init(self, engine_settings: dict[str, t.Any]) -> None:  # pyright: ignore[reportUnusedParameter]
+        """Initialization of the engine. If no initialization is needed, drop
+        this init function."""
+
+    @abc.abstractmethod
+    def request(self, query: str, params: dict[str, t.Any]) -> None:
+        """Build up the params for the online request."""
+
+    @abc.abstractmethod
+    def response(self, resp: "SXNG_Response") -> "EngineResults":
+        """Parse out the result items from the response."""