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
  14 class Analyser(Protocol):
  15     """ The `create()` function of an analysis module needs to return an
  16         object that implements the following functions.
  17     """
  18
  19     def normalize(self, name: str) -> str:
  20         """ Return the normalized form of the name. This is the standard form
  21             from which possible variants for the name can be derived.
  22         """
  23
  24     def get_variants_ascii(self, norm_name: str) -> List[str]:
  25         """ Compute the spelling variants for the given normalized name
  26             and transliterate the result.
  27         """
  28
  29 class AnalysisModule(Protocol):
  30     """ Protocol for analysis modules.
  31     """
  32
  33     def configure(self, rules: Mapping[str, Any], normalization_rules: str) -> Any:
  34         """ Prepare the configuration of the analysis module.
  35             This function should prepare all data that can be shared
  36             between instances of this analyser.
  37
  38             Arguments:
  39                 rules: A dictionary with the additional configuration options
  40                        as specified in the tokenizer configuration.
  41                 normalization_rules: ICU rules for normalization as a string
  42                                      that can be used with createFromRules().
  43
  44             Returns:
  45                 A data object with the configuration that was set up. May be
  46                 used freely by the analysis module as needed.
  47         """
  48
  49     def create(self, normalizer: Any, transliterator: Any, config: Any) -> Analyser:
  50         """ Create a new instance of the analyser.
  51             A separate instance of the analyser is created for each thread
  52             when used in multi-threading context.
  53
  54             Arguments:
  55                 normalizer: an ICU Transliterator with the compiled normalization
  56                             rules.
  57                 transliterator: an ICU tranliterator with the compiled
  58                                 transliteration rules.
  59                 config: The object that was returned by the call to configure().
  60
  61             Returns:
  62                 A new analyzer instance. This must be a class that implements
  63                 the Analyser protocol.
  64         """