]> git.openstreetmap.org Git - nominatim.git/blob - nominatim/data/postcode_format.py
Merge remote-tracking branch 'upstream/master'
[nominatim.git] / nominatim / data / postcode_format.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 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 nominatim.errors import UsageError
15 from nominatim.data 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)