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 --- searx/plugins/__init__.py | 88 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 23 deletions(-) (limited to 'searx/plugins/__init__.py') 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 ` - - :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(..) ` + +The :py:obj:`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) -- cgit v1.2.3