src/nominatim_db/data/postcode_format.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 Functions for formatting postcodes according to their country-specific
   9 format.
  10 """
  11 from typing import Any, Mapping, Optional, Set, Match
  12 import re
  13
  14 from ..errors import UsageError
  15 from . import country_info
  16
  17 class CountryPostcodeMatcher:
  18     """ Matches and formats a postcode according to a format definition
  19         of the given country.
  20     """
  21     def __init__(self, country_code: str, config: Mapping[str, Any]) -> None:
  22         if 'pattern' not in config:
  23             raise UsageError("Field 'pattern' required for 'postcode' "
  24                              f"for country '{country_code}'")
  25
  26         pc_pattern = config['pattern'].replace('d', '[0-9]').replace('l', '[A-Z]')
  27
  28         self.norm_pattern = re.compile(f'\\s*(?:{country_code.upper()}[ -]?)?({pc_pattern})\\s*')
  29         self.pattern = re.compile(pc_pattern)
  30
  31         self.output = config.get('output', r'\g<0>')
  32
  33
  34     def match(self, postcode: str) -> Optional[Match[str]]:
  35         """ Match the given postcode against the postcode pattern for this
  36             matcher. Returns a `re.Match` object if the match was successful
  37             and None otherwise.
  38         """
  39         # Upper-case, strip spaces and leading country code.
  40         normalized = self.norm_pattern.fullmatch(postcode.upper())
  41
  42         if normalized:
  43             return self.pattern.fullmatch(normalized.group(1))
  44
  45         return None
  46
  47
  48     def normalize(self, match: Match[str]) -> str:
  49         """ Return the default format of the postcode for the given match.
  50             `match` must be a `re.Match` object previously returned by
  51             `match()`
  52         """
  53         return match.expand(self.output)
  54
  55
  56 class PostcodeFormatter:
  57     """ Container for different postcode formats of the world and
  58         access functions.
  59     """
  60     def __init__(self) -> None:
  61         # Objects without a country code can't have a postcode per definition.
  62         self.country_without_postcode: Set[Optional[str]] = {None}
  63         self.country_matcher = {}
  64         self.default_matcher = CountryPostcodeMatcher('', {'pattern': '.*'})
  65
  66         for ccode, prop in country_info.iterate('postcode'):
  67             if prop is False:
  68                 self.country_without_postcode.add(ccode)
  69             elif isinstance(prop, dict):
  70                 self.country_matcher[ccode] = CountryPostcodeMatcher(ccode, prop)
  71             else:
  72                 raise UsageError(f"Invalid entry 'postcode' for country '{ccode}'")
  73
  74
  75     def set_default_pattern(self, pattern: str) -> None:
  76         """ Set the postcode match pattern to use, when a country does not
  77             have a specific pattern.
  78         """
  79         self.default_matcher = CountryPostcodeMatcher('', {'pattern': pattern})
  80
  81
  82     def get_matcher(self, country_code: Optional[str]) -> Optional[CountryPostcodeMatcher]:
  83         """ Return the CountryPostcodeMatcher for the given country.
  84             Returns None if the country doesn't have a postcode and the
  85             default matcher if there is no specific matcher configured for
  86             the country.
  87         """
  88         if country_code in self.country_without_postcode:
  89             return None
  90
  91         assert country_code is not None
  92
  93         return self.country_matcher.get(country_code, self.default_matcher)
  94
  95
  96     def match(self, country_code: Optional[str], postcode: str) -> Optional[Match[str]]:
  97         """ Match the given postcode against the postcode pattern for this
  98             matcher. Returns a `re.Match` object if the country has a pattern
  99             and the match was successful or None if the match failed.
 100         """
 101         if country_code in self.country_without_postcode:
 102             return None
 103
 104         assert country_code is not None
 105
 106         return self.country_matcher.get(country_code, self.default_matcher).match(postcode)
 107
 108
 109     def normalize(self, country_code: str, match: Match[str]) -> str:
 110         """ Return the default format of the postcode for the given match.
 111             `match` must be a `re.Match` object previously returned by
 112             `match()`
 113         """
 114         return self.country_matcher.get(country_code, self.default_matcher).normalize(match)