[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, 65 insertions, 23 deletions

diff --git a/searx/plugins/__init__.py b/searx/plugins/__init__.py
index 9aaf2f2db..4eacf52bd 100644
--- a/searx/plugins/__init__.py
+++ b/searx/plugins/__init__.py
@@ -3,11 +3,29 @@
 
    - :ref:`plugins admin`
    - :ref:`SearXNG settings <settings plugins>`
-   - :ref:`builtin plugins`
 
 Plugins can extend or replace functionality of various components of SearXNG.
-Here is an example of a very simple plugin that adds a "Hello" into the answer
-area:
+
+Entry points (hooks) define when a plugin runs.  Right now only three hooks are
+implemented.  So feel free to implement a hook if it fits the behaviour of your
+plugin / a plugin doesn't need to implement all the hooks.
+
+- pre search: :py:obj:`Plugin.pre_search`
+- post search: :py:obj:`Plugin.post_search`
+- on each result item: :py:obj:`Plugin.on_result`
+
+Below you will find some examples, for more coding examples have a look at the
+built-in plugins :origin:`searx/plugins/` or `Only show green hosted results`_.
+
+.. _Only show green hosted results:
+   https://github.com/return42/tgwf-searx-plugins/
+
+
+Add Answer example
+==================
+
+Here is an example of a very simple plugin that adds a "Hello World" into the
+answer area:
 
 .. code:: python
 
@@ -17,27 +35,51 @@ area:
 
    class MyPlugin(Plugin):
 
-       id = "self_info"
-       default_on = True
+       id = "hello world"
 
-       def __init__(self):
-           super().__init__()
-           info = PluginInfo(id=self.id, name=_("Hello"), description=_("demo plugin"))
+       def __init__(self, plg_cfg):
+           super().__init__(plg_cfg)
+           self.info = PluginInfo(id=self.id, name=_("Hello"), description=_("demo plugin"))
 
        def post_search(self, request, search):
-           return [ Answer(answer="Hello") ]
+           return [ Answer(answer="Hello World") ]
 
-Entry points (hooks) define when a plugin runs.  Right now only three hooks are
-implemented.  So feel free to implement a hook if it fits the behaviour of your
-plugin / a plugin doesn't need to implement all the hooks.
+.. _filter urls example:
 
-- pre search: :py:obj:`Plugin.pre_search`
-- post search: :py:obj:`Plugin.post_search`
-- on each result item: :py:obj:`Plugin.on_result`
+Filter URLs example
+===================
+
+.. sidebar:: Further reading ..
+
+   - :py:obj:`Result.filter_urls(..) <searx.result_types._base.Result.filter_urls>`
+
+The :py:obj:`Result.filter_urls(..) <searx.result_types._base.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
 
-For a coding example have a look at :ref:`self_info plugin`.
+   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
+
+
+Implementation
+==============
 
 .. autoclass:: Plugin
    :members:
@@ -48,21 +90,21 @@ For a coding example have a look at :ref:`self_info plugin`.
 .. autoclass:: PluginStorage
    :members:
 
-.. autoclass:: searx.plugins._core.ModulePlugin
+.. autoclass:: PluginCfg
    :members:
-   :show-inheritance:
-
 """
 
 from __future__ import annotations
 
-__all__ = ["PluginInfo", "Plugin", "PluginStorage"]
+__all__ = ["PluginInfo", "Plugin", "PluginStorage", "PluginCfg"]
+
 
-from ._core import PluginInfo, Plugin, PluginStorage
+import searx
+from ._core import PluginInfo, Plugin, PluginStorage, PluginCfg
 
 STORAGE: PluginStorage = PluginStorage()
 
 
 def initialize(app):
-    STORAGE.load_builtins()
+    STORAGE.load_settings(searx.get_setting("plugins"))
     STORAGE.init(app)