mirror of
https://github.com/searxng/searxng
synced 2024-01-01 19:24:07 +01:00
[mod] mudularize & document searx.results
The intention of this patch is to improve modularization & documentation of the implementations about the *result* items. This patch does not contain any functional change! Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser
parent
cee586029c
commit
069e1d7fb4
15 changed files with 935 additions and 262 deletions
|
|
@ -120,6 +120,11 @@ module:
|
|||
Making a Request
|
||||
================
|
||||
|
||||
.. sidebar:: info
|
||||
|
||||
- Demo of :py:obj:`request(query, params)
|
||||
<searx.engines.demo_online.request>` 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) <searx.engines.demo_online.response>` 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`.
|
||||
|
|
|
|||
|
|
@ -61,6 +61,8 @@ Scripts to update static data in :origin:`searx/data/`
|
|||
:members:
|
||||
|
||||
|
||||
.. _update_osm_keys_tags.py:
|
||||
|
||||
``update_osm_keys_tags.py``
|
||||
===========================
|
||||
|
||||
|
|
|
|||
460
docs/src/searx.results.rst
Normal file
460
docs/src/searx.results.rst
Normal file
|
|
@ -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 <result media types>` of the result item. Name of the
|
||||
:ref:`template file <result template files>` from :origin:`result_templates
|
||||
<searx/templates/simple/result_templates>`. If unset, ``default.html`` is
|
||||
used.
|
||||
|
||||
.. hint::
|
||||
|
||||
Each **standard result type** of an engine can be of different
|
||||
:reF:`media-types <result 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
|
||||
<searx/templates/simple/macros.html>`:
|
||||
|
||||
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
|
||||
<searx/templates/simple/macros.html>`:
|
||||
|
||||
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
|
||||
<searx/templates/simple/results.html>` in a HTML ``<form/>`` element. The
|
||||
intention of this macro is to pass data of a engine from one :py:obj:`response
|
||||
<searx.engines.demo_online.response>` to the :py:obj:`searx.search.SearchQuery`
|
||||
of the next :py:obj:`request <searx.engines.demo_online.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 <searx/templates/simple/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
|
||||
<searx/templates/simple/result_templates/default.html>`:
|
||||
|
||||
content : ``str``
|
||||
General text of the result item.
|
||||
|
||||
iframe_src : ``str``
|
||||
URL of an embedded ``<iframe>`` / the frame is collapsible.
|
||||
|
||||
audio_src : uri,
|
||||
URL of an embedded ``<audio controls>``.
|
||||
|
||||
|
||||
``code.html``
|
||||
-------------
|
||||
|
||||
Displays result fields from:
|
||||
|
||||
- :ref:`macro result_header` and
|
||||
- :ref:`macro result_sub_header`
|
||||
|
||||
Additional fields used in the :origin:`code.html
|
||||
<searx/templates/simple/result_templates/code.html>`:
|
||||
|
||||
content : ``str``
|
||||
Description of the code fragment.
|
||||
|
||||
codelines : ``[line1, line2, ...]``
|
||||
Lines of the code fragment.
|
||||
|
||||
code_language : ``str``
|
||||
Name of the code language, the value is passed to
|
||||
:py:obj:`pygments.lexers.get_lexer_by_name`.
|
||||
|
||||
repository : ``str``
|
||||
URL of the repository of the code fragment.
|
||||
|
||||
|
||||
``images.html``
|
||||
---------------
|
||||
|
||||
Fields used in the :origin:`images.html
|
||||
<searx/templates/simple/result_templates/images.html>`:
|
||||
|
||||
title : ``str``
|
||||
Title of the image.
|
||||
|
||||
thumbnail_src : ``str``
|
||||
URL of a preview of the image.
|
||||
|
||||
img_src : ``str``
|
||||
URL of the full size image.
|
||||
|
||||
Image labels
|
||||
~~~~~~~~~~~~
|
||||
|
||||
content: ``str``
|
||||
Description of the image.
|
||||
|
||||
author: ``str``
|
||||
Name of the author of the image.
|
||||
|
||||
img_format : ``str``
|
||||
Format of the image.
|
||||
|
||||
source : ``str``
|
||||
Source of the image.
|
||||
|
||||
url : ``str``
|
||||
URL of the page from where the images comes from (source).
|
||||
|
||||
|
||||
``videos.html``
|
||||
---------------
|
||||
|
||||
Displays result fields from:
|
||||
|
||||
- :ref:`macro result_header` and
|
||||
- :ref:`macro result_sub_header`
|
||||
|
||||
Additional fields used in the :origin:`videos.html
|
||||
<searx/templates/simple/result_templates/videos.html>`:
|
||||
|
||||
iframe_src : ``str``
|
||||
URL of an embedded ``<iframe>`` / the frame is collapsible.
|
||||
|
||||
content : ``str``
|
||||
Description of the code fragment.
|
||||
|
||||
|
||||
``map.html``
|
||||
------------
|
||||
|
||||
.. _GeoJSON: https://en.wikipedia.org/wiki/GeoJSON
|
||||
.. _Leaflet: https://github.com/Leaflet/Leaflet
|
||||
.. _bbox: https://wiki.openstreetmap.org/wiki/Bounding_Box
|
||||
.. _HTMLElement.dataset: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset
|
||||
.. _Nominatim: https://nominatim.org/release-docs/latest/
|
||||
.. _Lookup: https://nominatim.org/release-docs/latest/api/Lookup/
|
||||
.. _place_id is not a persistent id:
|
||||
https://nominatim.org/release-docs/latest/api/Output/#place_id-is-not-a-persistent-id
|
||||
.. _perma_id: https://wiki.openstreetmap.org/wiki/Permanent_ID
|
||||
.. _country code: https://wiki.openstreetmap.org/wiki/Country_code
|
||||
|
||||
Displays result fields from:
|
||||
|
||||
- :ref:`macro result_header` and
|
||||
- :ref:`macro result_sub_header`
|
||||
|
||||
Additional fields used in the :origin:`map.html
|
||||
<searx/templates/simple/result_templates/map.html>`:
|
||||
|
||||
content : ``str``
|
||||
Description of the item.
|
||||
|
||||
address_label : ``str``
|
||||
Label of the address / default ``_('address')``.
|
||||
|
||||
geojson : GeoJSON_
|
||||
Geometries mapped to HTMLElement.dataset_ (``data-map-geojson``) and used by
|
||||
Leaflet_.
|
||||
|
||||
boundingbox : ``[ min-lon, min-lat, max-lon, max-lat]``
|
||||
A bbox_ area defined by min longitude , min latitude , max longitude and max
|
||||
latitude. The bounding box is mapped to HTMLElement.dataset_
|
||||
(``data-map-boundingbox``) and is used by Leaflet_.
|
||||
|
||||
longitude, latitude : ``str``
|
||||
Geographical coordinates, mapped to HTMLElement.dataset_ (``data-map-lon``,
|
||||
``data-map-lat``) and is used by Leaflet_.
|
||||
|
||||
address : ``{...}``
|
||||
A dicticonary with the address data:
|
||||
|
||||
.. code:: python
|
||||
|
||||
address = {
|
||||
'name' : str, # name of object
|
||||
'road' : str, # street name of object
|
||||
'house_number' : str, # house number of object
|
||||
'postcode' : str, # postcode of object
|
||||
'country' : str, # country of object
|
||||
'country_code' : str,
|
||||
'locality' : str,
|
||||
}
|
||||
|
||||
country_code : ``str``
|
||||
`Country code`_ of the object.
|
||||
|
||||
locality : ``str``
|
||||
The name of the city, town, township, village, borough, etc. in which this
|
||||
object is located.
|
||||
|
||||
links : ``[link1, link2, ...]``
|
||||
A list of links with labels:
|
||||
|
||||
.. code:: python
|
||||
|
||||
links.append({
|
||||
'label' : str,
|
||||
'url' : str,
|
||||
'url_label' : str, # set by some engines but unused (oscar)
|
||||
})
|
||||
|
||||
data : ``[data1, data2, ...]``
|
||||
A list of additional data, shown in two columns and containing a label and
|
||||
value.
|
||||
|
||||
.. code:: python
|
||||
|
||||
data.append({
|
||||
'label' : str,
|
||||
'value' : str,
|
||||
'key' : str, # set by some engines but unused
|
||||
})
|
||||
|
||||
type : ``str`` # set by some engines but unused (oscar)
|
||||
Tag label from :ref:`OSM_KEYS_TAGS['tags'] <update_osm_keys_tags.py>`.
|
||||
|
||||
type_icon : ``str`` # set by some engines but unused (oscar)
|
||||
Type's icon.
|
||||
|
||||
osm : ``{...}``
|
||||
OSM-type and OSM-ID, can be used to Lookup_ OSM data (Nominatim_). There is
|
||||
also a discussion about "`place_id is not a persistent id`_" and the
|
||||
perma_id_.
|
||||
|
||||
.. code:: python
|
||||
|
||||
osm = {
|
||||
'type': str,
|
||||
'id': str,
|
||||
}
|
||||
|
||||
type : ``str``
|
||||
Type of osm-object (if OSM-Result).
|
||||
|
||||
id :
|
||||
ID of osm-object (if OSM-Result).
|
||||
|
||||
.. hint::
|
||||
|
||||
The ``osm`` property is set by engine ``openstreetmap.py``, but it is not
|
||||
used in the ``map.html`` template yet.
|
||||
|
||||
|
||||
``products.html``
|
||||
-----------------
|
||||
|
||||
Displays result fields from:
|
||||
|
||||
- :ref:`macro result_header` and
|
||||
- :ref:`macro result_sub_header`
|
||||
|
||||
Additional fields used in the :origin:`products.html
|
||||
<searx/templates/simple/result_templates/products.html>`:
|
||||
|
||||
content : ``str``
|
||||
Description of the product.
|
||||
|
||||
price : ``str``
|
||||
The price must include the currency.
|
||||
|
||||
shipping : ``str``
|
||||
Shipping details.
|
||||
|
||||
source_country : ``str``
|
||||
Place from which the shipment is made.
|
||||
|
||||
|
||||
``torrent.html``
|
||||
----------------
|
||||
|
||||
.. _magnet link: https://en.wikipedia.org/wiki/Magnet_URI_scheme
|
||||
.. _torrent file: https://en.wikipedia.org/wiki/Torrent_file
|
||||
|
||||
Displays result fields from:
|
||||
|
||||
- :ref:`macro result_header` and
|
||||
- :ref:`macro result_sub_header`
|
||||
|
||||
Additional fields used in the :origin:`torrent.html
|
||||
<searx/templates/simple/result_templates/torrent.html>`:
|
||||
|
||||
magnetlink:
|
||||
URL of the `magnet link`_.
|
||||
|
||||
torrentfile
|
||||
URL of the `torrent file`_.
|
||||
|
||||
seed : ``int``
|
||||
Number of seeders.
|
||||
|
||||
leech : ``int``
|
||||
Number of leecher
|
||||
|
||||
filesize : ``int``
|
||||
Size in Bytes (rendered to human readable unit of measurement).
|
||||
|
||||
files : ``int``
|
||||
Number of files.
|
||||
|
||||
|
||||
Suggestion results
|
||||
==================
|
||||
|
||||
.. automodule:: searx.results.suggestion
|
||||
:members:
|
||||
|
||||
|
||||
Answer results
|
||||
==============
|
||||
|
||||
.. automodule:: searx.results.answer
|
||||
:members:
|
||||
|
||||
|
||||
Correction results
|
||||
==================
|
||||
|
||||
.. automodule:: searx.results.correction
|
||||
:members:
|
||||
|
||||
|
||||
Infobox results
|
||||
===============
|
||||
|
||||
.. automodule:: searx.results.infobox
|
||||
:members:
|
||||
|
||||
|
||||
Result container
|
||||
================
|
||||
|
||||
.. automodule:: searx.results.container
|
||||
:members:
|
||||
|
||||
results.core
|
||||
============
|
||||
|
||||
.. automodule:: searx.results.core
|
||||
:members:
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue