# Engine Library

Implementations of the framework for the SearXNG engines.

Hint

The long term goal is to modularize all implementations of the engine framework here in this Python package. ToDo:

- move implementations of the SearXNG’s engines loader to a new module in the `searx.enginelib` namespace.

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 fields 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]

    Specifies to which categories the engine should be added.

  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 (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

  send_accept_language_header: bool

    When this option is activated, the language (locale) that is selected by the user is used to build and send a `Accept-Language` header in the request to the origin search engine.

  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.

  tokens: List[str]

    A list of secret tokens to make this engine private, more details see Private Engines (tokens).

  traits: EngineTraits

    Traits of the engine.

  using_tor_proxy: bool

    Using tor proxy (`true`) or not (`false`) for this 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: str | None = None, data_type: ~typing.Literal['traits_v1'] = 'traits_v1', custom: ~typing.Dict[str, ~typing.Dict[str, ~typing.Dict] | ~typing.Iterable[str]] = <factory>)

  The class is intended to be instantiated for each engine.

  copy()

    Create a copy of the dataclass object.

  classmethod fetch_traits(engine: Engine) → 'EngineTraits' | 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 `searx.locales.get_engine_locale`. Except for the special value `all` which is determined from `EngineTraits.all_locale`.

  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 `searx.locales.get_engine_locale`. Except for the special value `all` which is determined from `EngineTraits.all_locale`.

  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 `EngineTraits.get_region()` and `EngineTraits.get_language()` 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: str | None = None

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

  custom: Dict[str, Dict[str, Dict] | Iterable[str]]

    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() → EngineTraitsMap

    Instantiate `EngineTraitsMap` object from `ENGINE_TRAITS`

  save_data()

    Store EngineTraitsMap in in file `self.ENGINE_TRAITS_FILE`

  set_traits(engine: Engine | types.ModuleType)

    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`.