Engine model

Engine related implementations

Note

The long term goal is to modularize all relevant implementations to the engines here in this Python package. In addition to improved modularization, this will also be necessary in part because the probability of circular imports will increase due to the increased typification of implementations in the future.

ToDo:

• move searx.engines.load_engine to a new module searx.enginelib.

class searx.enginelib.Engine

Class of engine instances build from YAML settings.

Further documentation see General Engine Configuration.

Hint

This class is currently never initialized and only used for type hinting.

about: dict

Additional fileds describing the engine.

about:
   website: https://example.com
   wikidata_id: Q306656
   official_api_documentation: https://example.com/api-doc
   use_official_api: true
   require_api_key: true
   results: HTML

categories: List[str]

Tabs, in which the engine is working.

disabled: bool

To disable by default the engine, but not deleting it. It will allow the user to manually activate it in the settings.

display_error_messages: bool

Display error messages on the web UI.

enable_http: bool

Enable HTTP (by default only HTTPS is enabled).

engine: str

Name of the python file used to handle requests and responses to and from this search engine (file name from git://searx/engines without .py).

engine_type: str

Type of the engine (git://searx/search/processors)

fetch_traits: Callable

Function to to fetch engine’s traits from origin.

inactive: bool

Remove the engine from the settings (disabled & removed).

language: str

For an engine, when there is language: ... in the YAML settings the engine does support only this one language:

- name: google french
  engine: google
  language: fr

language_support: bool

Engine supports languages (locales) search.

name: str

Name that will be used across SearXNG to define this engine. In settings, on the result page ..

paging: bool

Engine supports multiple pages.

proxies: dict

Set proxies for a specific engine (YAML):

proxies :
  http:  socks5://proxy:port
  https: socks5://proxy:port

region: str

For an engine, when there is region: ... in the YAML settings the engine does support only this one region:

.. code:: yaml

• name: google belgium engine: google region: fr-BE

safesearch: bool

Engine supports SafeSearch

shortcut: str

Code used to execute bang requests (!foo)

time_range_support: bool

Engine supports search time range.

timeout: float

Specific timeout for search-engine.

traits: EngineTraits

Traits of the engine.

Engine traits

Engine’s traits are fetched from the origin engines and stored in a JSON file in the data folder. Most often traits are languages and region codes and their mapping from SearXNG’s representation to the representation in the origin search engine. For new traits new properties can be added to the class EngineTraits.

To load traits from the persistence EngineTraitsMap.from_data can be used.

class searx.enginelib.traits.EngineTraits(regions: ~typing.Dict[str, str] = <factory>, languages: ~typing.Dict[str, str] = <factory>, all_locale: ~typing.Optional[str] = None, data_type: ~typing.Literal['traits_v1'] = 'traits_v1', custom: ~typing.Dict[str, ~typing.Dict] = <factory>)

The class is intended to be instantiated for each engine.

copy()

Create a copy of the dataclass object.

classmethod fetch_traits(engine: Engine) → Union[Self, None]

Call a function fetch_traits(engine_traits) from engines namespace to fetch and set properties from the origin engine in the object engine_traits. If function does not exists, None is returned.

get_language(searxng_locale: str, default=None)

Return engine’s language string that best fits to SearXNG’s locale.

Parameters:

• searxng_locale – SearXNG’s internal representation of locale selected by the user.

• default – engine’s default language

The best fits rules are implemented in locales.get_engine_locale. Except for the special value all which is determined from :py:obj`EngineTraits.all_language`.

get_region(searxng_locale: str, default=None)

Return engine’s region string that best fits to SearXNG’s locale.

Parameters:

• searxng_locale – SearXNG’s internal representation of locale selected by the user.

• default – engine’s default region

The best fits rules are implemented in locales.get_engine_locale. Except for the special value all which is determined from :py:obj`EngineTraits.all_language`.

is_locale_supported(searxng_locale: str) → bool

A locale (SearXNG’s internal representation) is considered to be supported by the engine if the region or the language is supported by the engine. For verification the functions self.get_region() and self.get_region() are used.

set_traits(engine: Engine)

Set traits from self object in a Engine namespace.

Parameters:

engine – engine instance build by searx.engines.load_engine()

all_locale: Optional[str] = None

To which locale value SearXNG’s all language is mapped (shown a “Default language”).

custom: Dict[str, Dict]

A place to store engine’s custom traits, not related to the SearXNG core

data_type: Literal['traits_v1'] = 'traits_v1'

Data type, default is ‘traits_v1’.

languages: Dict[str, str]

Maps SearXNG’s internal representation of a language to the one of the engine.

SearXNG’s internal representation can be parsed by babel and the value is send to the engine:

languages = {
    'ca' : <engine's language name>,
}

for key, egnine_lang in languages.items():
   searxng_lang = babel.Locale.parse(key)
   ...

regions: Dict[str, str]

Maps SearXNG’s internal representation of a region to the one of the engine.

SearXNG’s internal representation can be parsed by babel and the value is send to the engine:

regions ={
    'fr-BE' : <engine's region name>,
}

for key, egnine_region regions.items():
   searxng_region = babel.Locale.parse(key, sep='-')
   ...

class searx.enginelib.traits.EngineTraitsEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Encodes EngineTraits to a serializable object, see json.JSONEncoder.

default(o)

Return dictionary of a EngineTraits object.

class searx.enginelib.traits.EngineTraitsMap

A python dictionary to map EngineTraits by engine name.

classmethod from_data() → Self

Instantiate EngineTraitsMap object from ENGINE_TRAITS

save_data()

Store EngineTraitsMap in in file self.ENGINE_TRAITS_FILE

set_traits(engine: Engine)

Set traits in a Engine namespace.

Parameters:

engine – engine instance build by searx.engines.load_engine()

ENGINE_TRAITS_FILE = PosixPath('/home/runner/work/searxng/searxng/searx/data/engine_traits.json')

File with persistence of the EngineTraitsMap.