From 57b9673efb1b4fd18a3ac15e26da642201e2cd33 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 22 Aug 2025 17:17:51 +0200 Subject: [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 Format: reST --- searx/enginelib/__init__.py | 52 ++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 17 deletions(-) (limited to 'searx/enginelib/__init__.py') 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 `).""" + + 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.""" -- cgit v1.2.3