diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index e950ae667..152f7764c 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -120,6 +120,11 @@ module: Making a Request ================ +.. sidebar:: info + + - Demo of :py:obj:`request(query, params) + ` function. + To perform a search an URL have to be specified. In addition to specifying an URL, arguments can be passed to the query. @@ -205,109 +210,18 @@ following parameters can be used to specify a search request: raise_for_httperror bool True by default: raise an exception if the HTTP code of response is >= 300 =================== =========== ========================================================================== +.. _engine response: -.. _engine results: -.. _engine media types: +Making a Response +================= -Media Types -=========== +.. sidebar:: info -Each result item of an engine can be of different media-types. Currently the -following media-types are supported. To set another media-type as ``default``, -the parameter ``template`` must be set to the desired type. + - Demo of a :py:obj:`response(resp) ` function. -.. table:: Parameter of the **default** media type: - :width: 100% +In the ``response`` function of the engine, the HTTP response (``resp``) is +parsed and a list of results is returned. - ========================= ===================================================== - result-parameter information - ========================= ===================================================== - url string, url of the result - title string, title of the result - content string, general result-text - publishedDate :py:class:`datetime.datetime`, time of publish - ========================= ===================================================== - - -.. table:: Parameter of the **images** media type: - :width: 100% - - ========================= ===================================================== - result-parameter information - ------------------------- ----------------------------------------------------- - template is set to ``images.html`` - ========================= ===================================================== - url string, url to the result site - title string, title of the result *(partly implemented)* - content *(partly implemented)* - publishedDate :py:class:`datetime.datetime`, - time of publish *(partly implemented)* - img\_src string, url to the result image - thumbnail\_src string, url to a small-preview image - ========================= ===================================================== - - -.. table:: Parameter of the **videos** media type: - :width: 100% - - ========================= ===================================================== - result-parameter information - ------------------------- ----------------------------------------------------- - template is set to ``videos.html`` - ========================= ===================================================== - url string, url of the result - title string, title of the result - content *(not implemented yet)* - publishedDate :py:class:`datetime.datetime`, time of publish - thumbnail string, url to a small-preview image - ========================= ===================================================== - -.. _magnetlink: https://en.wikipedia.org/wiki/Magnet_URI_scheme - -.. table:: Parameter of the **torrent** media type: - :width: 100% - - ========================= ===================================================== - result-parameter information - ------------------------- ----------------------------------------------------- - template is set to ``torrent.html`` - ========================= ===================================================== - url string, url of the result - title string, title of the result - content string, general result-text - publishedDate :py:class:`datetime.datetime`, - time of publish *(not implemented yet)* - seed int, number of seeder - leech int, number of leecher - filesize int, size of file in bytes - files int, number of files - magnetlink string, magnetlink_ of the result - torrentfile string, torrentfile of the result - ========================= ===================================================== - -.. table:: Parameter of the **map** media type: - :width: 100% - - ========================= ===================================================== - result-parameter information - ------------------------- ----------------------------------------------------- - template is set to ``map.html`` - ========================= ===================================================== - url string, url of the result - title string, title of the result - content string, general result-text - publishedDate :py:class:`datetime.datetime`, time of publish - latitude latitude of result (in decimal format) - longitude longitude of result (in decimal format) - boundingbox boundingbox of result (array of 4. values - ``[lat-min, lat-max, lon-min, lon-max]``) - geojson geojson of result (https://geojson.org/) - osm.type type of osm-object (if OSM-Result) - osm.id id of osm-object (if OSM-Result) - address.name name of object - address.road street name of object - address.house_number house number of object - address.locality city, place of object - address.postcode postcode of object - address.country country of object - ========================= ===================================================== +A engine can append result-items of different media-types and different +result-types to the result list. The list of the result items is render to HTML +by templates. For more details read section :ref:`engine results`. diff --git a/docs/dev/searxng_extra/update.rst b/docs/dev/searxng_extra/update.rst index d05c81409..5b12c3327 100644 --- a/docs/dev/searxng_extra/update.rst +++ b/docs/dev/searxng_extra/update.rst @@ -61,6 +61,8 @@ Scripts to update static data in :origin:`searx/data/` :members: +.. _update_osm_keys_tags.py: + ``update_osm_keys_tags.py`` =========================== diff --git a/docs/src/searx.results.rst b/docs/src/searx.results.rst new file mode 100644 index 000000000..08d914fc1 --- /dev/null +++ b/docs/src/searx.results.rst @@ -0,0 +1,460 @@ +.. _engine results: +.. _searx.results: + +============== +Engine Results +============== + +.. automodule:: searx.results + :members: + +The result items are organized in the :py:obj:`container.ResultContainer` and +rendered in the :ref:`result template macros` and :ref:`result template files`. + +.. contents:: Contents + :depth: 2 + :local: + :backlinks: entry + +.. _standard result: + +Result items +============ + +A result **item** is a python dictionary with dedicated keys and values. In the +result list a **standard result type** is identified by the existence of the key +``url``. Other **result types** are: + +- :py:obj:`searx.results.suggestion` +- :py:obj:`searx.results.answer` +- :py:obj:`searx.results.correction` +- :py:obj:`searx.results.infobox` + +The **standard result type**: + +.. code:: python + + results.append({ + 'template' : str, + + # result_header + + 'url' : str, + 'title' : str, + 'content' : str, + 'img_src' : str, + 'thumbnail' : str, + + # result_sub_header + + 'publishedDate' : datetime.datetime, + 'length' : time.struct_time, + 'author' : str, + 'metadata' : str, + }) + +template : ``str`` + :reF:`Media type ` of the result item. Name of the + :ref:`template file ` from :origin:`result_templates + `. If unset, ``default.html`` is + used. + +.. hint:: + + Each **standard result type** of an engine can be of different + :reF:`media-types `. + + +.. _result template macros: + +Result template macros +====================== + +.. _macro result_header: + +``result_header`` +----------------- + +Execpt ``image.html`` this macro is used in all :ref:`result template files`. +Fields used in the template :origin:`macro result_header +`: + +url : ``str`` + Link URL of the result item. + +title : ``str`` + Link title of the result item. + +img_src, thumbnail : ``str`` + URL of a image or thumbnail that is displayed in the result item. + +.. _macro result_sub_header: + +``result_sub_header`` +--------------------- + +Execpt ``image.html`` this macro is used in all :ref:`result template files`. +Fields used in the template :origin:`macro result_sub_header +`: + +publishedDate : :py:obj:`datetime.datetime` + The date on which the object was published. + +length: :py:obj:`time.struct_time` + Playing duration in seconds. + +author : ``str`` + Author of the title. + +metadata : ``str`` + Miscellaneous metadata. + +.. _engine_data: + +``engine_data_form`` +-------------------- + +The ``engine_data_form`` macro is used in :origin:`results,html +` in a HTML ``
`` element. The +intention of this macro is to pass data of a engine from one :py:obj:`response +` to the :py:obj:`searx.search.SearchQuery` +of the next :py:obj:`request `. + +To pass data, engine's response handler can append result items of typ +``engine_data``. This is by example used to pass a token from the response to +the next request: + +.. code:: python + + def response(resp): + ... + results.append({ + 'engine_data': token, + 'key': 'next_page_token', + }) + ... + return results + + def request(query, params): + page_token = params['engine_data'].get('next_page_token') + +.. _result media types: +.. _result template files: + +Result template files +===================== + +The **media types** of the **standard result type** are the template files in +the :origin:`result_templates `. + +``default.html`` +---------------- + +Displays result fields from: + +- :ref:`macro result_header` and +- :ref:`macro result_sub_header` + +Additional fields used in the :origin:`default.html +`: + +content : ``str`` + General text of the result item. + +iframe_src : ``str`` + URL of an embedded ``