[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, 51 insertions, 41 deletions

diff --git a/docs/admin/settings/settings_plugins.rst b/docs/admin/settings/settings_plugins.rst
index 991e7ee53..6e7b7bd6c 100644
--- a/docs/admin/settings/settings_plugins.rst
+++ b/docs/admin/settings/settings_plugins.rst
@@ -1,67 +1,77 @@
 .. _settings plugins:
 
-=======
-Plugins
-=======
+============
+``plugins:``
+============
+
+.. attention::
+
+   The ``enabled_plugins:`` section in SearXNG's settings no longer exists.
+   There is no longer a distinction between built-in and external plugin, all
+   plugins are registered via the settings in the ``plugins:`` section.
 
 .. sidebar:: Further reading ..
 
    - :ref:`plugins admin`
    - :ref:`dev plugin`
-   - :ref:`builtin plugins`
-
 
-The built-in plugins can be activated or deactivated via the settings
-(:ref:`settings enabled_plugins`) and external plugins can be integrated into
-SearXNG (:ref:`settings external_plugins`).
+In SearXNG, plugins can be registered in the :py:obj:`PluginStore
+<searx.plugins.PluginStorage>` via a fully qualified class name.
 
+A configuration (:py:obj:`PluginCfg <searx.plugins.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.
 
-.. _settings enabled_plugins:
+Please note that some plugins, such as the :ref:`hostnames plugin` plugin,
+require further configuration before they can be made available for selection.
 
-``enabled_plugins:`` (internal)
-===============================
+built-in plugins
+================
 
-In :ref:`plugins admin` you find a complete list of all plugins, the default
-configuration looks like:
+The built-in plugins are all located in the namespace `searx.plugins`.
 
 .. code:: yaml
 
-   enabled_plugins:
-     - 'Basic Calculator'
-     - 'Hash plugin'
-     - 'Self Information'
-     - 'Tracker URL remover'
-     - 'Unit converter plugin'
-     - 'Ahmia blacklist'
+    plugins:
 
+      searx.plugins.calculator.SXNGPlugin:
+        active: true
 
-.. _settings external_plugins:
+      searx.plugins.hash_plugin.SXNGPlugin:
+        active: true
 
-``plugins:`` (external)
-=======================
+      searx.plugins.self_info.SXNGPlugin:
+        active: true
 
-SearXNG supports *external plugins* / there is no need to install one, SearXNG
-runs out of the box.  But to demonstrate; in the example below we install the
-SearXNG plugins from *The Green Web Foundation* `[ref]
-<https://www.thegreenwebfoundation.org/news/searching-the-green-web-with-searx/>`__:
+      searx.plugins.tracker_url_remover.SXNGPlugin:
+        active: true
 
-.. code:: bash
+      searx.plugins.unit_converter.SXNGPlugin:
+        active: true
 
-   $ sudo utils/searxng.sh instance cmd bash -c
-   (searxng-pyenv)$ pip install git+https://github.com/return42/tgwf-searx-plugins
+      searx.plugins.ahmia_filter.SXNGPlugin:
+        active: true
 
-In the :ref:`settings.yml` activate the ``plugins:`` section and add module
-``only_show_green_results`` from ``tgwf-searx-plugins``.
+      searx.plugins.hostnames.SXNGPlugin:
+        active: true
 
-.. code:: yaml
+      searx.plugins.oa_doi_rewrite.SXNGPlugin:
+        active: false
 
-   plugins:
-     - only_show_green_results
-     # - mypackage.mymodule.MyPlugin
-     # - mypackage.mymodule.MyOtherPlugin
+      searx.plugins.tor_check.SXNGPlugin:
+        active: false
 
-.. hint::
 
-   ``only_show_green_results`` is an old plugin that was still implemented in
-   the old style.  There is a legacy treatment for backward compatibility, but
-   new plugins should be implemented as a :py:obj:`searx.plugins.Plugin` class.
+.. _settings external_plugins:
+
+external plugins
+================
+
+.. _Only show green hosted results:
+   https://github.com/return42/tgwf-searx-plugins/
+
+SearXNG supports *external plugins* / there is no need to install one, SearXNG
+runs out of the box.
+
+- `Only show green hosted results`_
+- ..