src/nominatim_db/tokenizer/token_analysis/base.py

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