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