From 50f92779bd9f2762d92a24a63851f4069f88297d Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 20 Mar 2025 07:47:38 +0100 Subject: [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 --- docs/admin/settings/settings_plugins.rst | 92 ++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 41 deletions(-) (limited to 'docs/admin/settings/settings_plugins.rst') 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 +` via a fully qualified class name. +A configuration (:py:obj:`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] -`__: + 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`_ +- .. -- cgit v1.2.3