nominatim/tokenizer/token_analysis/base.py

   1 # SPDX-License-Identifier: GPL-2.0-only
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2022 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Common data types and protocols for analysers.
   9 """
  10 from typing import Mapping, List, Any
  11
  12 from nominatim.typing import Protocol
  13 from nominatim.data.place_name import PlaceName
  14
  15 class Analyzer(Protocol):
  16     """ The `create()` function of an analysis module needs to return an
  17         object that implements the following functions.
  18     """
  19
  20     def get_canonical_id(self, name: PlaceName) -> str:
  21         """ Return the canonical form of the given name. The canonical ID must
  22             be unique (the same ID must always yield the same variants) and
  23             must be a form from which the variants can be derived.
  24
  25             Arguments:
  26                 name: Extended place name description as prepared by
  27                       the sanitizers.
  28
  29             Returns:
  30                 ID string with a canonical form of the name. The string may
  31                     be empty, when the analyzer cannot analyze the name at all,
  32                     for example because the character set in use does not match.
  33         """
  34
  35     def compute_variants(self, canonical_id: str) -> List[str]:
  36         """ Compute the transliterated spelling variants for the given
  37             canonical ID.
  38
  39             Arguments:
  40                 canonical_id: ID string previously computed with
  41                               `get_canonical_id()`.
  42
  43             Returns:
  44                 A list of possible spelling variants. All strings must have
  45                     been transformed with the global normalizer and
  46                     transliterator ICU rules. Otherwise they cannot be matched
  47                     against the input by the query frontend.
  48                     The list may be empty, when there are no useful
  49                     spelling variants. This may happen when an analyzer only
  50                     usually outputs additional variants to the canonical spelling
  51                     and there are no such variants.
  52         """
  53
  54
  55 class AnalysisModule(Protocol):
  56     """ The setup of the token analysis is split into two parts:
  57         configuration and analyser factory. A token analysis module must
  58         therefore implement the two functions here described.
  59     """
  60
  61     def configure(self, rules: Mapping[str, Any],
  62                   normalizer: Any, transliterator: Any) -> Any:
  63         """ Prepare the configuration of the analysis module.
  64             This function should prepare all data that can be shared
  65             between instances of this analyser.
  66
  67             Arguments:
  68                 rules: A dictionary with the additional configuration options
  69                        as specified in the tokenizer configuration.
  70                 normalizer: an ICU Transliterator with the compiled
  71                             global normalization rules.
  72                 transliterator: an ICU Transliterator with the compiled
  73                                 global transliteration rules.
  74
  75             Returns:
  76                 A data object with configuration data. This will be handed
  77                     as is into the `create()` function and may be
  78                     used freely by the analysis module as needed.
  79         """
  80
  81     def create(self, normalizer: Any, transliterator: Any, config: Any) -> Analyzer:
  82         """ Create a new instance of the analyser.
  83             A separate instance of the analyser is created for each thread
  84             when used in multi-threading context.
  85
  86             Arguments:
  87                 normalizer: an ICU Transliterator with the compiled normalization
  88                             rules.
  89                 transliterator: an ICU Transliterator with the compiled
  90                                 transliteration rules.
  91                 config: The object that was returned by the call to configure().
  92
  93             Returns:
  94                 A new analyzer instance. This must be an object that implements
  95                     the Analyzer protocol.
  96         """