From 0b27c8698f7b5bbca5083cf234fabbc7d7308349 Mon Sep 17 00:00:00 2001
From: Alexandre Flament <alex@al-f.net>
Date: Thu, 9 Sep 2021 11:23:57 +0200
Subject: [PATCH] [doc] update docs/dev/plugins.rst

---
 docs/dev/plugins.rst      | 58 ++++++++++++++++++++++++++++++---------
 docs/src/searx.search.rst | 38 +++++++++++++++++++++++++
 searx/search/__init__.py  | 10 +++----
 searx/search/models.py    |  1 +
 4 files changed, 89 insertions(+), 18 deletions(-)
 create mode 100644 docs/src/searx.search.rst

diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
index 16262ea6d..44401e34f 100644
--- a/docs/dev/plugins.rst
+++ b/docs/dev/plugins.rst
@@ -26,8 +26,8 @@ Example plugin
    # attach callback to the post search hook
    #  request: flask request object
    #  ctx: the whole local context of the post search hook
-   def post_search(request, ctx):
-       ctx['search'].suggestions.add('example')
+   def post_search(request, search):
+       search.result_container.suggestions.add('example')
        return True
 
 External plugins
@@ -50,20 +50,52 @@ Plugin entry points
 
 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.
+plugin. A plugin doesn't need to implement all the hooks.
 
-Pre search hook
----------------
 
-Runs BEFORE the search request. Function to implement: ``pre_search``
+.. py:function:: pre_search(request, search) -> bool
 
-Post search hook
-----------------
+   Runs BEFORE the search request.
 
-Runs AFTER the search request. Function to implement: ``post_search``
+   `search.result_container` can be changed.
 
-Result hook
------------
+   Return a boolean:
 
-Runs when a new result is added to the result list. Function to implement:
-``on_result``
+   * True to continue the search
+   * False to stop the search
+
+   :param flask.request request:
+   :param searx.search.SearchWithPlugins search:
+   :return: False to stop the search
+   :rtype: bool
+
+
+.. py:function:: post_search(request, search) -> None
+
+   Runs AFTER the search request.
+
+   :param flask.request request: Flask request.
+   :param searx.search.SearchWithPlugins search: Context.
+
+
+.. py:function:: on_result(request, search, result) -> bool
+
+   Runs for each result of each engine.
+
+   `result` can be changed.
+
+   If `result["url"]` is defined, then `result["parsed_url"] = urlparse(result['url'])`
+
+   .. warning::
+      `result["url"]` can be changed, but `result["parsed_url"]` must be updated too.
+
+   Return a boolean:
+
+   * True to keep the result
+   * False to remove the result
+
+   :param flask.request request:
+   :param searx.search.SearchWithPlugins search:
+   :param typing.Dict result: Result, see - :ref:`engine results`
+   :return: True to keep the result
+   :rtype: bool
diff --git a/docs/src/searx.search.rst b/docs/src/searx.search.rst
new file mode 100644
index 000000000..ad76d4183
--- /dev/null
+++ b/docs/src/searx.search.rst
@@ -0,0 +1,38 @@
+.. _searx.search:
+
+======
+Search
+======
+
+.. autoclass:: searx.search.EngineRef
+  :members:
+
+.. autoclass:: searx.search.SearchQuery
+  :members:
+
+.. autoclass:: searx.search.Search
+
+  .. attribute:: search_query
+    :type: searx.search.SearchQuery
+
+  .. attribute:: result_container
+    :type: searx.results.ResultContainer
+
+  .. automethod:: search() -> searx.results.ResultContainer
+
+.. autoclass:: searx.search.SearchWithPlugins
+  :members:
+
+  .. attribute:: search_query
+    :type: searx.search.SearchQuery
+
+  .. attribute:: result_container
+    :type: searx.results.ResultContainer
+
+  .. attribute:: ordered_plugin_list
+    :type: typing.List
+
+  .. attribute:: request
+    :type: flask.request
+
+  .. automethod:: search() -> searx.results.ResultContainer
diff --git a/searx/search/__init__.py b/searx/search/__init__.py
index 6c750a3f9..69d7ffb25 100644
--- a/searx/search/__init__.py
+++ b/searx/search/__init__.py
@@ -39,7 +39,7 @@ class Search:
 
     __slots__ = "search_query", "result_container", "start_time", "actual_timeout"
 
-    def __init__(self, search_query):
+    def __init__(self, search_query: SearchQuery):
         # init vars
         super().__init__()
         self.search_query = search_query
@@ -163,7 +163,7 @@ class Search:
         return True
 
     # do search-request
-    def search(self):
+    def search(self) -> ResultContainer:
         self.start_time = default_timer()
         if not self.search_external_bang():
             if not self.search_answerers():
@@ -172,11 +172,11 @@ class Search:
 
 
 class SearchWithPlugins(Search):
-    """Similar to the Search class but call the plugins."""
+    """Inherit from the Search class, add calls to the plugins."""
 
     __slots__ = 'ordered_plugin_list', 'request'
 
-    def __init__(self, search_query, ordered_plugin_list, request):
+    def __init__(self, search_query: SearchQuery, ordered_plugin_list, request: "flask.Request"):
         super().__init__(search_query)
         self.ordered_plugin_list = ordered_plugin_list
         self.result_container.on_result = self._on_result
@@ -192,7 +192,7 @@ class SearchWithPlugins(Search):
     def _on_result(self, result):
         return plugins.call(self.ordered_plugin_list, 'on_result', self.request, self, result)
 
-    def search(self):
+    def search(self) -> ResultContainer:
         if plugins.call(self.ordered_plugin_list, 'pre_search', self.request, self):
             super().search()
 
diff --git a/searx/search/models.py b/searx/search/models.py
index 7233fac42..e48cb3611 100644
--- a/searx/search/models.py
+++ b/searx/search/models.py
@@ -4,6 +4,7 @@ import typing
 
 
 class EngineRef:
+    """Reference by names to an engine and category"""
 
     __slots__ = 'name', 'category'