[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, 38 insertions, 24 deletions

diff --git a/searx/plugins/tracker_url_remover.py b/searx/plugins/tracker_url_remover.py
index f33f7fdfd..d9c767a36 100644
--- a/searx/plugins/tracker_url_remover.py
+++ b/searx/plugins/tracker_url_remover.py
@@ -2,12 +2,21 @@
 # pylint: disable=missing-module-docstring
 
 from __future__ import annotations
+import typing
 
 import re
 from urllib.parse import urlunparse, parse_qsl, urlencode
 
 from flask_babel import gettext
 
+from searx.plugins import Plugin, PluginInfo
+
+if typing.TYPE_CHECKING:
+    from searx.search import SearchWithPlugins
+    from searx.extended_types import SXNG_Request
+    from searx.result_types import Result
+    from searx.plugins import PluginCfg
+
 regexes = {
     re.compile(r'utm_[^&]+'),
     re.compile(r'(wkey|wemail)[^&]*'),
@@ -15,30 +24,35 @@ regexes = {
     re.compile(r'&$'),
 }
 
-name = gettext('Tracker URL remover')
-description = gettext('Remove trackers arguments from the returned URL')
-default_on = True
-preference_section = 'privacy'
-
 
-def on_result(_request, _search, result) -> bool:
+class SXNGPlugin(Plugin):
+    """Remove trackers arguments from the returned URL"""
+
+    id = "tracker_url_remover"
+
+    def __init__(self, plg_cfg: "PluginCfg") -> None:
+        super().__init__(plg_cfg)
+        self.info = PluginInfo(
+            id=self.id,
+            name=gettext("Tracker URL remover"),
+            description=gettext("Remove trackers arguments from the returned URL"),
+            preference_section="privacy",
+        )
+
+    def on_result(
+        self, request: "SXNG_Request", search: "SearchWithPlugins", result: Result
+    ) -> bool:  # pylint: disable=unused-argument
+        if not result.parsed_url:
+            return True
+
+        parsed_query: list[tuple[str, str]] = parse_qsl(result.parsed_url.query)
+        for name_value in list(parsed_query):
+            param_name = name_value[0]
+            for reg in regexes:
+                if reg.match(param_name):
+                    parsed_query.remove(name_value)
+                    result.parsed_url = result.parsed_url._replace(query=urlencode(parsed_query))
+                    result.url = urlunparse(result.parsed_url)
+                    break
 
-    parsed_url = getattr(result, "parsed_url", None)
-    if not parsed_url:
         return True
-
-    if parsed_url.query == "":
-        return True
-
-    parsed_query = parse_qsl(parsed_url.query)
-    changes = 0
-    for i, (param_name, _) in enumerate(list(parsed_query)):
-        for reg in regexes:
-            if reg.match(param_name):
-                parsed_query.pop(i - changes)
-                changes += 1
-                result.parsed_url = result.parsed_url._replace(query=urlencode(parsed_query))
-                result.url = urlunparse(result.parsed_url)
-                break
-
-    return True