• 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

These changes collectively enhance code maintainability, ensure better compatibility with type checkers and development tools, and improve the overall robustness of the project.

To avoid further complicating static typing due to the quirks that still exist in Python 3.9, it was also necessary to remove Python 3.9 from the support matrix. This PR is based on:

• [mod] py3.9 EOL #5148

This is intended to form a first basis for the typification of our source code. Much more will be required, but I already mentioned it in PR-5075:

I think we need to put more effort into typing, but we shouldn't try to type everything either; that just creates unnecessary work and is frustrating. Python is and remains a dynamically typed language, but types can improve quality and, with the LSP (IDE), positively impact productivity. In this sense, we should also align our goals with regard to typing.

The changes in this PR-5147 are also designed in this sense.

Some people might think, what could be so difficult about retroactively typing code? If you work with static types in a project from the beginning, it is still easy, but if you retroactively typing the code there are some challenges.

Basically, you have to re-engineer the code to find the correct types. Wich is not feasible with reasonable effort for modules such as searx.network or searx.metrics. Here, one should consider whether these modules might be replaced by new modules in the future (network, for example, based on curl impoersonate / metrics replaced by container classes).

However, there will always be a lot of code in SearXNG that cannot be (reasonably) typed; for example, the JSON and DOM trees that are examined by the engines. Requirements like pygments also have generic interfaces (classes) that make static type checking impossible.

I/we are still at the very beginning. With a little more experience, we'll be able to provide (write down) somewhat helpful recommendations for action, and as the quality of our source code improves, we'll also be increasingly able to implement some criteria in CI as quality gates. But we still have a long way to go.

But all the complaining doesn't help, we have to start with the topic... this PR takes us a first step in the right direction and the benefits can already be felt with the merge of this PR in the developers' IDEs.

We use basedpyright, which can be easily installed via pipx, for example:

 pipx install basedpyright

Its recommended to have a look at the following links:

• https://docs.basedpyright.com/latest/installation/command-line-and-language-server/
• https://docs.basedpyright.com/latest/installation/ides/