[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, 27 insertions, 25 deletions

diff --git a/searx/version.py b/searx/version.py
index 2005463b1..8f9ef3a84 100644
--- a/searx/version.py
+++ b/searx/version.py
@@ -9,11 +9,11 @@ import subprocess
 
 # fallback values
 # if there is searx.version_frozen module, and it is not possible to get the git tag
-VERSION_STRING = "1.0.0"
-VERSION_TAG = "1.0.0"
-DOCKER_TAG = "1.0.0"
-GIT_URL = "unknown"
-GIT_BRANCH = "unknown"
+VERSION_STRING: str = "1.0.0"
+VERSION_TAG: str = "1.0.0"
+DOCKER_TAG: str = "1.0.0"
+GIT_URL: str = "unknown"
+GIT_BRANCH: str = "unknown"
 
 logger = logging.getLogger("searx")
 
@@ -24,21 +24,22 @@ SUBPROCESS_RUN_ENV = {
 }
 
 
-def subprocess_run(args, **kwargs):
+def subprocess_run(args: str | list[str] | tuple[str], **kwargs) -> str:  # type: ignore
     """Call :py:func:`subprocess.run` and return (striped) stdout.  If returncode is
     non-zero, raise a :py:func:`subprocess.CalledProcessError`.
     """
     if not isinstance(args, (list, tuple)):
         args = shlex.split(args)
 
-    kwargs["env"] = kwargs.get("env", SUBPROCESS_RUN_ENV)
-    kwargs["encoding"] = kwargs.get("encoding", "utf-8")
+    kwargs["env"] = kwargs.get("env", SUBPROCESS_RUN_ENV)  # type: ignore
+    kwargs["encoding"] = kwargs.get("encoding", "utf-8")  # type: ignore
     kwargs["stdout"] = subprocess.PIPE
     kwargs["stderr"] = subprocess.PIPE
     # raise CalledProcessError if returncode is non-zero
     kwargs["check"] = True
-    proc = subprocess.run(args, **kwargs)  # pylint: disable=subprocess-run-check
-    return proc.stdout.strip()
+    # pylint: disable=subprocess-run-check
+    proc = subprocess.run(args, **kwargs)  # type: ignore
+    return proc.stdout.strip()  # type: ignore
 
 
 def get_git_url_and_branch():
@@ -64,13 +65,14 @@ def get_git_url_and_branch():
     return git_url, git_branch
 
 
-def get_git_version():
-    git_commit_date_hash = subprocess_run(r"git show -s --date='format:%Y.%m.%d' --format='%cd+%h'")
+def get_git_version() -> tuple[str, str, str]:
+    git_commit_date_hash: str = subprocess_run(r"git show -s --date='format:%Y.%m.%d' --format='%cd+%h'")
     # Remove leading zero from minor and patch level / replacement of PR-2122
     # which depended on the git version: '2023.05.06+..' --> '2023.5.6+..'
     git_commit_date_hash = git_commit_date_hash.replace('.0', '.')
-    tag_version = git_version = git_commit_date_hash
-    docker_tag = git_commit_date_hash.replace("+", "-")
+    tag_version: str = git_commit_date_hash
+    git_version: str = git_commit_date_hash
+    docker_tag: str = git_commit_date_hash.replace("+", "-")
 
     # add "+dirty" suffix if there are uncommitted changes except searx/settings.yml
     try:
@@ -84,12 +86,12 @@ def get_git_version():
     return git_version, tag_version, docker_tag
 
 
-def get_information():
-    version_string = VERSION_STRING
-    version_tag = VERSION_TAG
-    docker_tag = DOCKER_TAG
-    git_url = GIT_URL
-    git_branch = GIT_BRANCH
+def get_information() -> tuple[str, str, str, str, str]:
+    version_string: str = VERSION_STRING
+    version_tag: str = VERSION_TAG
+    docker_tag: str = DOCKER_TAG
+    git_url: str = GIT_URL
+    git_branch: str = GIT_BRANCH
 
     try:
         version_string, version_tag, docker_tag = get_git_version()
@@ -106,11 +108,11 @@ def get_information():
 try:
     vf = importlib.import_module('searx.version_frozen')
     VERSION_STRING, VERSION_TAG, DOCKER_TAG, GIT_URL, GIT_BRANCH = (
-        vf.VERSION_STRING,
-        vf.VERSION_TAG,
-        vf.DOCKER_TAG,
-        vf.GIT_URL,
-        vf.GIT_BRANCH,
+        str(vf.VERSION_STRING),
+        str(vf.VERSION_TAG),
+        str(vf.DOCKER_TAG),
+        str(vf.GIT_URL),
+        str(vf.GIT_BRANCH),
     )
 except ImportError:
     VERSION_STRING, VERSION_TAG, DOCKER_TAG, GIT_URL, GIT_BRANCH = get_information()