nominatim/tokenizer/token_analysis/postcodes.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 Specialized processor for postcodes. Supports a 'lookup' variant of the
   9 token, which produces variants with optional spaces.
  10 """
  11 from typing import Mapping, Any, List
  12
  13 from nominatim.tokenizer.token_analysis.generic_mutation import MutationVariantGenerator
  14
  15 ### Configuration section
  16
  17 def configure(rules: Mapping[str, Any], normalization_rules: str) -> None: # pylint: disable=W0613
  18     """ All behaviour is currently hard-coded.
  19     """
  20     return None
  21
  22 ### Analysis section
  23
  24 def create(normalizer: Any, transliterator: Any, config: None) -> 'PostcodeTokenAnalysis': # pylint: disable=W0613
  25     """ Create a new token analysis instance for this module.
  26     """
  27     return PostcodeTokenAnalysis(normalizer, transliterator)
  28
  29
  30 class PostcodeTokenAnalysis:
  31     """ Special normalization and variant generation for postcodes.
  32
  33         This analyser must not be used with anything but postcodes as
  34         it follows some special rules: `normalize` doesn't necessarily
  35         need to return a standard form as per normalization rules. It
  36         needs to return the canonical form of the postcode that is also
  37         used for output. `get_variants_ascii` then needs to ensure that
  38         the generated variants once more follow the standard normalization
  39         and transliteration, so that postcodes are correctly recognised by
  40         the search algorithm.
  41     """
  42     def __init__(self, norm: Any, trans: Any) -> None:
  43         self.norm = norm
  44         self.trans = trans
  45
  46         self.mutator = MutationVariantGenerator(' ', (' ', ''))
  47
  48
  49     def normalize(self, name: str) -> str:
  50         """ Return the standard form of the postcode.
  51         """
  52         return name.strip().upper()
  53
  54
  55     def get_variants_ascii(self, norm_name: str) -> List[str]:
  56         """ Compute the spelling variants for the given normalized postcode.
  57
  58             Takes the canonical form of the postcode, normalizes it using the
  59             standard rules and then creates variants of the result where
  60             all spaces are optional.
  61         """
  62         # Postcodes follow their own transliteration rules.
  63         # Make sure at this point, that the terms are normalized in a way
  64         # that they are searchable with the standard transliteration rules.
  65         return [self.trans.transliterate(term) for term in
  66                 self.mutator.generate([self.norm.transliterate(norm_name)]) if term]