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 Any, List
  12
  13 from nominatim.tokenizer.token_analysis.generic_mutation import MutationVariantGenerator
  14 from nominatim.data.place_name import PlaceName
  15
  16 ### Configuration section
  17
  18 def configure(*_: Any) -> None:
  19     """ All behaviour is currently hard-coded.
  20     """
  21     return None
  22
  23 ### Analysis section
  24
  25 def create(normalizer: Any, transliterator: Any, config: None) -> 'PostcodeTokenAnalysis': # pylint: disable=W0613
  26     """ Create a new token analysis instance for this module.
  27     """
  28     return PostcodeTokenAnalysis(normalizer, transliterator)
  29
  30
  31 class PostcodeTokenAnalysis:
  32     """ Special normalization and variant generation for postcodes.
  33
  34         This analyser must not be used with anything but postcodes as
  35         it follows some special rules: the canonial ID is the form that
  36         is used for the output. `compute_variants` then needs to ensure that
  37         the generated variants once more follow the standard normalization
  38         and transliteration, so that postcodes are correctly recognised by
  39         the search algorithm.
  40     """
  41     def __init__(self, norm: Any, trans: Any) -> None:
  42         self.norm = norm
  43         self.trans = trans
  44
  45         self.mutator = MutationVariantGenerator(' ', (' ', ''))
  46
  47
  48     def get_canonical_id(self, name: PlaceName) -> str:
  49         """ Return the standard form of the postcode.
  50         """
  51         return name.name.strip().upper()
  52
  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]