diff options
| -rw-r--r-- | docs/dev/plugins.rst | 58 | ||||
| -rw-r--r-- | docs/src/searx.search.rst | 38 | ||||
| -rw-r--r-- | searx/search/__init__.py | 10 | ||||
| -rw-r--r-- | searx/search/models.py | 1 |
4 files changed, 89 insertions, 18 deletions
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' |