searxng/searx
Markus Heiser 50f92779bd [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>
2025-03-29 10:16:43 +01:00
..
answerers [fix] gettext can't work with f-strings (i10n) 2025-01-29 06:04:09 +01:00
botdetection [fix] plugins: bugfix of tor_check and unit_converter 2025-03-15 10:36:33 +01:00
data [data] update searx.data - update_ahmia_blacklist.py 2025-03-29 09:49:27 +01:00
enginelib [fix] make data.traits - partial revert of commit 30a8204 2025-03-22 07:52:36 +01:00
engines [fix] presearch engine: Unexpected crash if duration not in videos 2025-03-28 16:26:39 +01:00
favicons [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
infopage [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
metrics [fix] openmetrics: value is None if there's no data 2024-11-25 16:57:03 +01:00
network [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
plugins [refactor] migrate plugins from "module" to class SXNGPlugin 2025-03-29 10:16:43 +01:00
result_types [refactor] migrate plugins from "module" to class SXNGPlugin 2025-03-29 10:16:43 +01:00
search [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
static/themes/simple [build] /static 2025-03-27 12:27:37 +01:00
templates/simple [mod] migrate all key-value.html templates to KeyValue type 2025-03-15 10:36:33 +01:00
translations [l10n] update translations from Weblate 2025-03-28 08:51:09 +01:00
__init__.py [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
autocomplete.py [feat] add Sogou engine for searxng 2025-03-02 13:31:31 +01:00
babel_extract.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
compat.py [mod] Revision of the favicon solution 2024-10-05 08:18:28 +02:00
exceptions.py [fix] engine: duckduckgo - CAPTCHA detection 2024-10-19 14:55:44 +02:00
extended_types.py [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
external_bang.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
external_urls.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
flaskfix.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
limiter.py [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
limiter.toml [chore] *: fix typos detected by typos-cli 2024-11-24 12:41:57 +01:00
locales.py [refactor] typification of SearXNG (initial) / result items (part 1) 2025-01-28 07:07:08 +01:00
openmetrics.py [fix] openmetrics: value is None if there's no data 2024-11-25 16:57:03 +01:00
preferences.py [refactor] migrate plugins from "module" to class SXNGPlugin 2025-03-29 10:16:43 +01:00
query.py [refactor] unit tests to utilize paramaterized and break down monolithic tests 2024-10-03 13:20:32 +02:00
redisdb.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
redislib.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
results.py [refactor] typification of SearXNG (MainResult) / result items (part 2) 2025-03-15 10:36:33 +01:00
searxng.msg Revert "[l10n ga] trigger weblate.push.translations (another try)" 2025-01-06 17:12:16 +01:00
settings.yml [refactor] migrate plugins from "module" to class SXNGPlugin 2025-03-29 10:16:43 +01:00
settings_defaults.py [refactor] migrate plugins from "module" to class SXNGPlugin 2025-03-29 10:16:43 +01:00
settings_loader.py [mod] revision of the settings_loader 2024-07-14 18:10:06 +02:00
sqlitedb.py [mod] sqlitedb: access to SQLite databases a little more convenient. 2024-10-05 08:18:28 +02:00
sxng_locales.py [fix] make data.traits - partial revert of commit 30a8204 2025-03-22 07:52:36 +01:00
unixthreadname.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
utils.py [refactor] duration strings: move parsing logic to utils.py 2025-03-25 16:48:44 +01:00
version.py [mod] pylint all files with one profile / drop PYLINT_SEARXNG_DISABLE_OPTION 2024-03-11 14:55:38 +01:00
webadapter.py [chore] *: fix typos detected by typos-cli 2024-11-24 12:41:57 +01:00
webapp.py [refactor] migrate plugins from "module" to class SXNGPlugin 2025-03-29 10:16:43 +01:00
webutils.py [fix] JSON & CSV format return error 500 2025-01-29 05:04:41 +01:00