[refactor] migrate plugins from "module" to class SXNGPlugin

This patch brings two major changes:

- ``Result.filter_urls(..)`` to pass a filter function for URL fields
- The ``enabled_plugins:`` section in SearXNG's settings do no longer exists.

To understand plugin development compile documentation:

    $ make docs.clean docs.live

and read http://0.0.0.0:8000/dev/plugins/development.html

There is no longer a distinction between built-in and external plugin, all
plugins are registered via the settings in the ``plugins:`` section.

In SearXNG, plugins can be registered via a fully qualified class name.  A
configuration (`PluginCfg`) can be transferred to the plugin, e.g. to activate
it by default / *opt-in* or *opt-out* from user's point of view.

built-in plugins
================

The built-in plugins are all located in the namespace `searx.plugins`.

.. code:: yaml

    plugins:

      searx.plugins.calculator.SXNGPlugin:
        active: true

      searx.plugins.hash_plugin.SXNGPlugin:
        active: true

      searx.plugins.self_info.SXNGPlugin:
        active: true

      searx.plugins.tracker_url_remover.SXNGPlugin:
        active: true

      searx.plugins.unit_converter.SXNGPlugin:
        active: true

      searx.plugins.ahmia_filter.SXNGPlugin:
        active: true

      searx.plugins.hostnames.SXNGPlugin:
        active: true

      searx.plugins.oa_doi_rewrite.SXNGPlugin:
        active: false

      searx.plugins.tor_check.SXNGPlugin:
        active: false

external plugins
================

SearXNG supports *external plugins* / there is no need to install one, SearXNG
runs out of the box.

- Only show green hosted results: https://github.com/return42/tgwf-searx-plugins/

To get a developer installation in a SearXNG developer environment:

.. code:: sh

   $ git clone git@github.com:return42/tgwf-searx-plugins.git
   $ ./manage pyenv.cmd python -m \
         pip install -e tgwf-searx-plugins

To register the plugin in SearXNG add ``only_show_green_results.SXNGPlugin`` to
the ``plugins:``:

.. code:: yaml

    plugins:
      # ...
      only_show_green_results.SXNGPlugin:
        active: false

Result.filter_urls(..)
======================

The ``Result.filter_urls(..)`` can be used to filter and/or modify URL fields.
In the following example, the filter function ``my_url_filter``:

.. code:: python

   def my_url_filter(result, field_name, url_src) -> bool | str:
       if "google" in url_src:
           return False              # remove URL field from result
       if "facebook" in url_src:
           new_url = url_src.replace("facebook", "fb-dummy")
           return new_url            # return modified URL
       return True                   # leave URL in field unchanged

is applied to all URL fields in the :py:obj:`Plugin.on_result` hook:

.. code:: python

   class MyUrlFilter(Plugin):
       ...
       def on_result(self, request, search, result) -> bool:
           result.filter_urls(my_url_filter)
           return True

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

1 files changed, 45 insertions, 50 deletions

diff --git a/searx/plugins/tor_check.py b/searx/plugins/tor_check.py
index e719207bf..6a24714c3 100644
--- a/searx/plugins/tor_check.py
+++ b/searx/plugins/tor_check.py
@@ -3,47 +3,24 @@
 user searches for ``tor-check``.  It fetches the tor exit node list from
 :py:obj:`url_exit_list` and parses all the IPs into a list, then checks if the
 user's IP address is in it.
-
-Enable in ``settings.yml``:
-
-.. code:: yaml
-
-  enabled_plugins:
-    ..
-    - 'Tor check plugin'
-
 """
-
 from __future__ import annotations
+import typing
 
 import re
 from flask_babel import gettext
 from httpx import HTTPError
 
 from searx.network import get
+from searx.plugins import Plugin, PluginInfo
 from searx.result_types import EngineResults
 from searx.botdetection import get_real_ip
 
+if typing.TYPE_CHECKING:
+    from searx.search import SearchWithPlugins
+    from searx.extended_types import SXNG_Request
+    from searx.plugins import PluginCfg
 
-default_on = False
-
-name = gettext("Tor check plugin")
-'''Translated name of the plugin'''
-
-description = gettext(
-    "This plugin checks if the address of the request is a Tor exit-node, and"
-    " informs the user if it is; like check.torproject.org, but from SearXNG."
-)
-'''Translated description of the plugin.'''
-
-preference_section = 'query'
-'''The preference section where the plugin is shown.'''
-
-query_keywords = ['tor-check']
-'''Query keywords shown in the preferences.'''
-
-query_examples = ''
-'''Query examples shown in the preferences.'''
 
 # Regex for exit node addresses in the list.
 reg = re.compile(r"(?<=ExitAddress )\S+")
@@ -52,33 +29,51 @@ url_exit_list = "https://check.torproject.org/exit-addresses"
 """URL to load Tor exit list from."""
 
 
-def post_search(request, search) -> EngineResults:
-    results = EngineResults()
+class SXNGPlugin(Plugin):
+    """Rewrite hostnames, remove results or prioritize them."""
 
-    if search.search_query.pageno > 1:
-        return results
+    id = "tor_check"
+    keywords = ["tor-check"]
 
-    if search.search_query.query.lower() == "tor-check":
+    def __init__(self, plg_cfg: "PluginCfg") -> None:
+        super().__init__(plg_cfg)
+        self.info = PluginInfo(
+            id=self.id,
+            name=gettext("Tor check plugin"),
+            description=gettext(
+                "This plugin checks if the address of the request is a Tor exit-node, and"
+                " informs the user if it is; like check.torproject.org, but from SearXNG."
+            ),
+            preference_section="query",
+        )
 
-        # Request the list of tor exit nodes.
-        try:
-            resp = get(url_exit_list)
-            node_list = re.findall(reg, resp.text)  # type: ignore
+    def post_search(self, request: "SXNG_Request", search: "SearchWithPlugins") -> EngineResults:
+        results = EngineResults()
 
-        except HTTPError:
-            # No answer, return error
-            msg = gettext("Could not download the list of Tor exit-nodes from")
-            results.add(results.types.Answer(answer=f"{msg} {url_exit_list}"))
+        if search.search_query.pageno > 1:
             return results
 
-        real_ip = get_real_ip(request)
+        if search.search_query.query.lower() == "tor-check":
+
+            # Request the list of tor exit nodes.
+            try:
+                resp = get(url_exit_list)
+                node_list = re.findall(reg, resp.text)  # type: ignore
 
-        if real_ip in node_list:
-            msg = gettext("You are using Tor and it looks like you have the external IP address")
-            results.add(results.types.Answer(answer=f"{msg} {real_ip}"))
+            except HTTPError:
+                # No answer, return error
+                msg = gettext("Could not download the list of Tor exit-nodes from")
+                results.add(results.types.Answer(answer=f"{msg} {url_exit_list}"))
+                return results
 
-        else:
-            msg = gettext("You are not using Tor and you have the external IP address")
-            results.add(results.types.Answer(answer=f"{msg} {real_ip}"))
+            real_ip = get_real_ip(request)
 
-    return results
+            if real_ip in node_list:
+                msg = gettext("You are using Tor and it looks like you have the external IP address")
+                results.add(results.types.Answer(answer=f"{msg} {real_ip}"))
+
+            else:
+                msg = gettext("You are not using Tor and you have the external IP address")
+                results.add(results.types.Answer(answer=f"{msg} {real_ip}"))
+
+        return results