northpost-parser 1.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- northpost_parser/__init__.py +23 -0
- northpost_parser/generated/CanadianAddressLexer.py +91 -0
- northpost_parser/generated/CanadianAddressParser.py +531 -0
- northpost_parser/generated/CanadianAddressVisitor.py +43 -0
- northpost_parser/generated/__init__.py +1 -0
- northpost_parser/models.py +158 -0
- northpost_parser/normalizer.py +107 -0
- northpost_parser/service.py +162 -0
- northpost_parser/visitor.py +566 -0
- northpost_parser-1.1.0.dist-info/METADATA +120 -0
- northpost_parser-1.1.0.dist-info/RECORD +13 -0
- northpost_parser-1.1.0.dist-info/WHEEL +4 -0
- northpost_parser-1.1.0.dist-info/licenses/LICENSE +200 -0
|
@@ -0,0 +1,566 @@
|
|
|
1
|
+
"""Semantic interpretation of the shared, deliberately minimal address grammar."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass, replace
|
|
4
|
+
import re
|
|
5
|
+
|
|
6
|
+
from .generated.CanadianAddressParser import CanadianAddressParser as P
|
|
7
|
+
from .generated.CanadianAddressVisitor import CanadianAddressVisitor
|
|
8
|
+
from .models import AddressComponents, AddressType, ParsingMode
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
PROVINCE_CODES = set("AB BC MB NB NL NT NS NU ON PE QC SK YT".split())
|
|
12
|
+
POSTAL_PREFIX_TO_PROVINCE = dict(zip("ABCEGHJKLMNPRSTVXY",
|
|
13
|
+
"NL NS PE NB QC QC QC ON ON ON ON ON MB SK AB BC NT YT".split()))
|
|
14
|
+
STREET_TYPES_EN = set("""
|
|
15
|
+
STREET ST AVENUE AVE AV BOULEVARD BLVD BV DRIVE DR DV ROAD RD PLACE PL COURT CRT CT
|
|
16
|
+
CRESCENT CRES CR CIRCLE CIR CI WAY WY LANE LN TERRACE TERR TRAIL TRL PARKWAY PKY PY
|
|
17
|
+
HIGHWAY HWY HY CLOSE CL CLO GATE GT GA GREEN GR GRN GROVE GV GRV HEATH HE HEIGHTS
|
|
18
|
+
HTS HT HILL HL LANDING LANDNG LD MEWS MS PARADE PARK PK PA PATH POINT PT RIDGE ROW
|
|
19
|
+
SQUARE SQ WALK WK ABBEY ACRES ALLEY BAY BA BEACH BEND BRANCH BR BYPASS BYWAY CAPE
|
|
20
|
+
CENTRE CHASE CIRCUIT CIRC COMMON CM CONCESSION CON CORNERS COVE CO CV CREEK CRK
|
|
21
|
+
CROSS CROSSING XG CDS DALE DELL DIVERSION DOWNS END ESPLANADE ESPL ESTATES ESTS
|
|
22
|
+
EXTENSION EXTEN FAIRWAY FARM FIELD FORD FOREST FREEWAY FWY FRONT GARDEN GARDENS
|
|
23
|
+
GDNS GDN GLADE GLEN GRANGE HARBOUR HAVEN HOLLOW INLET INL ISLAND KEY KNOLL LIMITS
|
|
24
|
+
LINE LI LINK LOOKOUT LKOUT LOOP MALL MANOR MR MAZE ME MEADOW MEADOWS MOUNT MT
|
|
25
|
+
MOUNTAIN MTN ORCHARD PARKLAND PASSAGE PASS PINES PLATEAU PLAZA PORT PRIVATE PVT PR
|
|
26
|
+
PROMENADE PROM QUAY RAMP RANGE RG REACH RISE RI RO RUN SHORE SHORES SHORELINE
|
|
27
|
+
SIDEROAD SDRD SR SPRING STROLL TC TE THICKET TOWERS TOWNLINE TL TRUNK TR TUNNEL
|
|
28
|
+
TURNABOUT VALE VIEW VW VI VILLAGE VILLAS VISTA WHARF WOOD WOODS WYND PKWY CREST
|
|
29
|
+
BLUFF SPUR ESTATE GATEWAY GY WALKWAY OUTLOOK GD CA CX PS PZ LP AL HI GL PW CE LK GW
|
|
30
|
+
SIDERD CONC TLINE CIRCT VILLGE PATHWAY PTWAY DRIVEWAY DRWY CTR POINTE HIGHLANDS HGHLDS HARBR
|
|
31
|
+
""".split())
|
|
32
|
+
STREET_TYPES_FR = set("""
|
|
33
|
+
RUE AVENUE AVE AV BOULEVARD BOUL BL CHEMIN CH CMN ROUTE RTE PLACE RANG MONTÉE MONTEE
|
|
34
|
+
CÔTE COTE CROISSANT IMPASSE IMP PASSAGE PROMENADE TERRASSE TSSE ALLÉE ALLEE CARRÉ
|
|
35
|
+
CARRE CAR CERCLE CIRCUIT COUR COURS CRÊTE CRETE PARC PONT SENTIER TUNNEL VOIE RUELLE
|
|
36
|
+
AUTOROUTE DESSERTE JARDIN QUAI DIVERS CROIS RLE SENT
|
|
37
|
+
""".split())
|
|
38
|
+
ALL_STREET_TYPES = STREET_TYPES_EN | STREET_TYPES_FR
|
|
39
|
+
TYPE_WORDS_USED_AS_NAMES = set("""
|
|
40
|
+
ACRES BAY BEACH BEND CAPE CENTRE CHASE COMMON COURT COVE CREEK CRESCENT CROSSING DALE
|
|
41
|
+
DELL DOWNS END ESTATE ESTATES FARM FIELD FORD FOREST FRONT GARDEN GARDENS GLEN
|
|
42
|
+
GRANGE GREEN GROVE HARBOUR HAVEN HEATH HEIGHTS HILL HOLLOW ISLAND KEY KNOLL LANDING
|
|
43
|
+
LINK LOOKOUT MALL MANOR MEADOW MEADOWS MOUNT MOUNTAIN ORCHARD PARK PINES PLATEAU
|
|
44
|
+
POINT PORT RANCH REACH RIDGE RISE RUN SHORE SHORES SPRING SQUARE TERRACE TOWERS
|
|
45
|
+
VALE VIEW VILLAGE VISTA WALK WHARF WOOD WOODS RUE CHEMIN ROUTE RANG PLACE BOULEVARD
|
|
46
|
+
AVENUE ALLÉE ALLEE CÔTE COTE PARC PASSAGE PROMENADE CROISSANT IMPASSE SENTIER CIRCUIT
|
|
47
|
+
CERCLE TUNNEL MONTÉE MONTEE VOIE RUELLE TERRASSE
|
|
48
|
+
""".split())
|
|
49
|
+
PREFIX_DIRECTIONS = set("N S E W O NE NW SE SW N. S. E. W.".split())
|
|
50
|
+
DIRECTIONS = PREFIX_DIRECTIONS | set("""
|
|
51
|
+
NB SB EB WB NORTH SOUTH EAST WEST NORTHEAST NORTHWEST SOUTHEAST SOUTHWEST
|
|
52
|
+
NORTHBOUND SOUTHBOUND EASTBOUND WESTBOUND N.E. N.W. S.E. S.W. EST OUEST NORD SUD
|
|
53
|
+
""".split())
|
|
54
|
+
UNIT_DESIGNATORS = set("""
|
|
55
|
+
APT APARTMENT SUITE STE UNIT BUREAU BUR ROOM RM FLOOR FL OFFICE DEPT DEPARTMENT
|
|
56
|
+
BLDG BUILDING TOWER TWR PH PENTHOUSE APP APPARTEMENT PORTE ÉTAGE ETAGE
|
|
57
|
+
""".split())
|
|
58
|
+
UNIT_DESIGNATORS_BY_LENGTH = sorted(UNIT_DESIGNATORS, key=lambda x: (-len(x), x))
|
|
59
|
+
PROVINCE_NAMES = {
|
|
60
|
+
"NEWFOUNDLAND AND LABRADOR": "NL", "PRINCE EDWARD ISLAND": "PE",
|
|
61
|
+
"BRITISH COLUMBIA": "BC", "NEW BRUNSWICK": "NB", "NORTHWEST TERRITORIES": "NT",
|
|
62
|
+
"NOVA SCOTIA": "NS", "SASKATCHEWAN": "SK", "NEWFOUNDLAND": "NL",
|
|
63
|
+
"MANITOBA": "MB", "ONTARIO": "ON", "ALBERTA": "AB", "NUNAVUT": "NU",
|
|
64
|
+
"QUEBEC": "QC", "QUÉBEC": "QC", "YUKON": "YT", "NFLD.": "NL", "NFLD": "NL",
|
|
65
|
+
"P.E.I.": "PE", "PEI": "PE", "N.S.": "NS", "N.B.": "NB", "QUE.": "QC",
|
|
66
|
+
"QUE": "QC", "ONT.": "ON", "ONT": "ON", "MAN.": "MB", "MAN": "MB",
|
|
67
|
+
"SASK.": "SK", "SASK": "SK", "ALTA.": "AB", "ALTA": "AB", "B.C.": "BC",
|
|
68
|
+
"N.W.T.": "NT", "NWT": "NT", "Y.T.": "YT",
|
|
69
|
+
}
|
|
70
|
+
COUNTRY_KEYWORDS = {"CANADA", "CAN", "CA"}
|
|
71
|
+
PO_BOX_KEYWORDS = {"PO", "P.O.", "CP", "C.P.", "BOX"}
|
|
72
|
+
NUMERIC_TYPES = {P.NUMBER, P.ALPHANUMERIC}
|
|
73
|
+
WORD_TYPES = NUMERIC_TYPES | {P.WORD}
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def normalize_street_type(word: str) -> str | None:
|
|
77
|
+
if word in ALL_STREET_TYPES:
|
|
78
|
+
return word
|
|
79
|
+
stripped = word.removesuffix(".")
|
|
80
|
+
return stripped if stripped in ALL_STREET_TYPES else None
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def is_french_street_type(word: str) -> bool:
|
|
84
|
+
return word.removesuffix(".") in STREET_TYPES_FR
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def is_unit_designator(word: str) -> bool:
|
|
88
|
+
return word.removesuffix(".") in UNIT_DESIGNATORS
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def unit_prefix(word: str) -> tuple[str, str] | None:
|
|
92
|
+
for designator in UNIT_DESIGNATORS_BY_LENGTH:
|
|
93
|
+
if word.startswith(designator):
|
|
94
|
+
remainder = word[len(designator):].removeprefix(".")
|
|
95
|
+
if remainder and remainder[0].isdigit():
|
|
96
|
+
return designator, remainder
|
|
97
|
+
return None
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def opposing_directions(first: str, second: str) -> bool:
|
|
101
|
+
opposites = {
|
|
102
|
+
"EAST": {"WEST", "OUEST"}, "EST": {"WEST", "OUEST"},
|
|
103
|
+
"WEST": {"EAST", "EST"}, "OUEST": {"EAST", "EST"},
|
|
104
|
+
"NORTH": {"SOUTH", "SUD"}, "NORD": {"SOUTH", "SUD"},
|
|
105
|
+
"SOUTH": {"NORTH", "NORD"}, "SUD": {"NORTH", "NORD"},
|
|
106
|
+
}
|
|
107
|
+
return second in opposites.get(first, ())
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def is_fsa(text: str) -> bool:
|
|
111
|
+
return re.fullmatch(r"[A-Z]\d[A-Z]", text) is not None
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def is_ldu(text: str) -> bool:
|
|
115
|
+
return re.fullmatch(r"\d[A-Z]\d", text) is not None
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def format_postal_code(raw: str) -> str:
|
|
119
|
+
compact = re.sub(r"\s", "", raw.upper())
|
|
120
|
+
return compact[:3] + " " + compact[3:] if len(compact) == 6 else compact
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
@dataclass(frozen=True)
|
|
124
|
+
class TokenInfo:
|
|
125
|
+
type: int
|
|
126
|
+
text: str
|
|
127
|
+
start: int
|
|
128
|
+
stop: int
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
@dataclass(frozen=True)
|
|
132
|
+
class LineTokens:
|
|
133
|
+
tokens: list[TokenInfo]
|
|
134
|
+
text: str
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def line_from_tokens(tokens: list[TokenInfo]) -> LineTokens:
|
|
138
|
+
return LineTokens(tokens, " ".join(t.text for t in tokens))
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def adjacent(first: TokenInfo, second: TokenInfo) -> bool:
|
|
142
|
+
return first.stop + 1 == second.start
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def care_of(tokens: list[TokenInfo]) -> bool:
|
|
146
|
+
return (len(tokens) >= 3 and tokens[1].type == P.SLASH
|
|
147
|
+
and (tokens[0].text, tokens[2].text) in {("C", "O"), ("A", "S")})
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def gen_del(tokens: list[TokenInfo]) -> bool:
|
|
151
|
+
return len(tokens) >= 2 and tokens[0].text == "GEN" and tokens[1].text in {"DEL", "DEL."}
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def find_postal_code(line: LineTokens) -> str | None:
|
|
155
|
+
for i, token in enumerate(line.tokens):
|
|
156
|
+
if token.type == P.POSTAL_CODE:
|
|
157
|
+
return format_postal_code(token.text)
|
|
158
|
+
if is_fsa(token.text) and i + 1 < len(line.tokens) and is_ldu(line.tokens[i + 1].text):
|
|
159
|
+
return token.text + " " + line.tokens[i + 1].text
|
|
160
|
+
return None
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def postal_code_only(line: LineTokens) -> bool:
|
|
164
|
+
tokens = [t for t in line.tokens if t.type not in {P.COMMA, P.DOT}]
|
|
165
|
+
if len(tokens) == 1:
|
|
166
|
+
return tokens[0].type == P.POSTAL_CODE
|
|
167
|
+
if len(tokens) in {2, 3} and is_fsa(tokens[0].text):
|
|
168
|
+
return is_ldu("".join(t.text for t in tokens[1:]))
|
|
169
|
+
return False
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def country_line(line: LineTokens) -> bool:
|
|
173
|
+
return len(line.tokens) == 1 and line.tokens[0].text in COUNTRY_KEYWORDS
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def looks_like_delivery(tokens: list[TokenInfo]) -> bool:
|
|
177
|
+
if not tokens:
|
|
178
|
+
return False
|
|
179
|
+
first = tokens[0]
|
|
180
|
+
if first.type in NUMERIC_TYPES:
|
|
181
|
+
return True
|
|
182
|
+
if first.type == P.LPAREN and len(tokens) >= 2 and tokens[1].type in NUMERIC_TYPES:
|
|
183
|
+
return True
|
|
184
|
+
if (first.text in PO_BOX_KEYWORDS | {"RR", "GD", "GENERAL"}
|
|
185
|
+
or gen_del(tokens) or is_unit_designator(first.text) or unit_prefix(first.text)):
|
|
186
|
+
return True
|
|
187
|
+
return len(tokens) >= 2 and first.text in PREFIX_DIRECTIONS and tokens[1].type in NUMERIC_TYPES
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def collect_street_words(tokens: list[TokenInfo], start: int) -> list[str]:
|
|
191
|
+
words: list[str] = []
|
|
192
|
+
i = start
|
|
193
|
+
while i < len(tokens):
|
|
194
|
+
token = tokens[i]
|
|
195
|
+
if token.type in WORD_TYPES:
|
|
196
|
+
if words and i >= 2:
|
|
197
|
+
separator = tokens[i - 1]
|
|
198
|
+
if (separator.type in {P.HYPHEN, P.SLASH}
|
|
199
|
+
and adjacent(tokens[i - 2], separator) and adjacent(separator, token)):
|
|
200
|
+
words[-1] += separator.text + token.text
|
|
201
|
+
i += 1
|
|
202
|
+
continue
|
|
203
|
+
words.append(token.text)
|
|
204
|
+
elif token.type == P.AMPERSAND:
|
|
205
|
+
words.append("&")
|
|
206
|
+
elif token.type == P.LPAREN:
|
|
207
|
+
paren = "("
|
|
208
|
+
for j in range(i + 1, len(tokens)):
|
|
209
|
+
part = tokens[j]
|
|
210
|
+
if part.type == P.RPAREN:
|
|
211
|
+
paren += ")"
|
|
212
|
+
i = j
|
|
213
|
+
break
|
|
214
|
+
if part.type in WORD_TYPES | {P.HYPHEN}:
|
|
215
|
+
if len(paren) > 1:
|
|
216
|
+
paren += "-" if part.type == P.HYPHEN else " "
|
|
217
|
+
paren += part.text
|
|
218
|
+
if words:
|
|
219
|
+
words[-1] += " " + paren
|
|
220
|
+
else:
|
|
221
|
+
words.append(paren)
|
|
222
|
+
elif token.type == P.HYPHEN and words:
|
|
223
|
+
previous = i > 0 and adjacent(tokens[i - 1], token)
|
|
224
|
+
following = i + 1 < len(tokens) and adjacent(token, tokens[i + 1])
|
|
225
|
+
if not previous and not following:
|
|
226
|
+
words.append("-")
|
|
227
|
+
i += 1
|
|
228
|
+
return words
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
class AddressComponentVisitor(CanadianAddressVisitor):
|
|
232
|
+
def __init__(self, parsing_mode: ParsingMode = ParsingMode.LENIENT):
|
|
233
|
+
self.components = AddressComponents(parsing_mode=parsing_mode)
|
|
234
|
+
|
|
235
|
+
def _set(self, **fields) -> None:
|
|
236
|
+
self.components = replace(self.components, **fields)
|
|
237
|
+
|
|
238
|
+
def visitAddress(self, ctx: P.AddressContext) -> AddressComponents:
|
|
239
|
+
body = ctx.addressBody()
|
|
240
|
+
if body is None:
|
|
241
|
+
return self.components
|
|
242
|
+
lines = []
|
|
243
|
+
for line in body.addressLine():
|
|
244
|
+
tokens = [
|
|
245
|
+
TokenInfo(t.start.type, t.getText().upper(), t.start.start, t.stop.stop)
|
|
246
|
+
for t in line.lineContent().lineToken()
|
|
247
|
+
]
|
|
248
|
+
if tokens:
|
|
249
|
+
lines.append(line_from_tokens(tokens))
|
|
250
|
+
if not lines:
|
|
251
|
+
return self.components
|
|
252
|
+
comma_split = False
|
|
253
|
+
if len(lines) == 1:
|
|
254
|
+
split = self._comma_split(lines[0])
|
|
255
|
+
if split:
|
|
256
|
+
lines = split
|
|
257
|
+
comma_split = True
|
|
258
|
+
if len(lines) == 1:
|
|
259
|
+
if comma_split:
|
|
260
|
+
self._region(lines[0])
|
|
261
|
+
elif len(lines[0].tokens) <= 3 and (pc := find_postal_code(lines[0])):
|
|
262
|
+
self._set(postal_code=pc)
|
|
263
|
+
else:
|
|
264
|
+
self._set(addressee=lines[0].text)
|
|
265
|
+
elif comma_split:
|
|
266
|
+
self._region(lines[-1])
|
|
267
|
+
for line in lines[:-1]:
|
|
268
|
+
self._delivery(line)
|
|
269
|
+
else:
|
|
270
|
+
region = len(lines) - 1
|
|
271
|
+
if country_line(lines[region]):
|
|
272
|
+
self._set(country=lines[region].text)
|
|
273
|
+
region -= 1
|
|
274
|
+
if region >= 1 and postal_code_only(lines[region]):
|
|
275
|
+
if pc := find_postal_code(lines[region]):
|
|
276
|
+
self._set(postal_code=pc)
|
|
277
|
+
region -= 1
|
|
278
|
+
self._region(lines[region])
|
|
279
|
+
addressee_seen = False
|
|
280
|
+
for line in lines[:region]:
|
|
281
|
+
tokens = line.tokens
|
|
282
|
+
if country_line(line):
|
|
283
|
+
self._set(country=line.text)
|
|
284
|
+
elif postal_code_only(line):
|
|
285
|
+
if pc := find_postal_code(line):
|
|
286
|
+
self._set(postal_code=pc)
|
|
287
|
+
elif care_of(tokens):
|
|
288
|
+
self._set(care_of=" ".join(t.text for t in tokens[3:]))
|
|
289
|
+
elif tokens[0].text in {"SITE", "COMP", "EMPL"}:
|
|
290
|
+
self._set(site_info=line.text)
|
|
291
|
+
elif looks_like_delivery(tokens):
|
|
292
|
+
self._delivery(line)
|
|
293
|
+
elif not addressee_seen:
|
|
294
|
+
self._set(addressee=line.text)
|
|
295
|
+
addressee_seen = True
|
|
296
|
+
else:
|
|
297
|
+
self._delivery(line)
|
|
298
|
+
if not self.components.province and self.components.postal_code:
|
|
299
|
+
inferred = POSTAL_PREFIX_TO_PROVINCE.get(self.components.postal_code[0])
|
|
300
|
+
if inferred:
|
|
301
|
+
self._set(province=inferred)
|
|
302
|
+
if self.components.address_type == AddressType.INCOMPLETE:
|
|
303
|
+
civic = bool(self.components.street_name or self.components.street_number)
|
|
304
|
+
box = bool(self.components.postal_box_number)
|
|
305
|
+
if box and civic:
|
|
306
|
+
kind = AddressType.MIXED
|
|
307
|
+
elif box:
|
|
308
|
+
kind = AddressType.POSTAL_BOX
|
|
309
|
+
elif self.components.rural_route:
|
|
310
|
+
kind = AddressType.RURAL_ROUTE
|
|
311
|
+
elif civic:
|
|
312
|
+
kind = AddressType.CIVIC
|
|
313
|
+
else:
|
|
314
|
+
kind = AddressType.INCOMPLETE
|
|
315
|
+
self._set(address_type=kind)
|
|
316
|
+
self._set(is_complete=self.components.is_mailing_valid())
|
|
317
|
+
return self.components
|
|
318
|
+
|
|
319
|
+
def _comma_split(self, line: LineTokens) -> list[LineTokens] | None:
|
|
320
|
+
tokens = line.tokens
|
|
321
|
+
for i, token in enumerate(tokens):
|
|
322
|
+
if token.type != P.COMMA:
|
|
323
|
+
continue
|
|
324
|
+
after = i + 1
|
|
325
|
+
while after < len(tokens) and tokens[after].type == P.COMMA:
|
|
326
|
+
after += 1
|
|
327
|
+
marker = any(
|
|
328
|
+
(t.type == P.WORD and (
|
|
329
|
+
t.text in PROVINCE_CODES or t.text in PROVINCE_NAMES
|
|
330
|
+
or t.text.removesuffix(".") in PROVINCE_NAMES))
|
|
331
|
+
or t.type == P.POSTAL_CODE or is_fsa(t.text)
|
|
332
|
+
for t in tokens[after:] if t.type != P.COMMA
|
|
333
|
+
)
|
|
334
|
+
if not marker or not any(t.type in WORD_TYPES for t in tokens[:i]):
|
|
335
|
+
continue
|
|
336
|
+
delivery, region = tokens[:i], tokens[after:]
|
|
337
|
+
if not delivery or not region:
|
|
338
|
+
return None
|
|
339
|
+
if not any(t.type in NUMERIC_TYPES for t in delivery):
|
|
340
|
+
return [line_from_tokens(delivery + region)]
|
|
341
|
+
return [line_from_tokens(delivery), line_from_tokens(region)]
|
|
342
|
+
return None
|
|
343
|
+
|
|
344
|
+
def _region(self, line: LineTokens) -> None:
|
|
345
|
+
tokens = line.tokens
|
|
346
|
+
pc_start = pc_end = -1
|
|
347
|
+
if not self.components.postal_code:
|
|
348
|
+
for i, token in enumerate(tokens):
|
|
349
|
+
pc = None
|
|
350
|
+
if token.type == P.POSTAL_CODE:
|
|
351
|
+
pc, pc_start, pc_end = format_postal_code(token.text), i, i
|
|
352
|
+
elif is_fsa(token.text) and i + 1 < len(tokens):
|
|
353
|
+
if is_ldu(tokens[i + 1].text):
|
|
354
|
+
pc, pc_start, pc_end = token.text + " " + tokens[i + 1].text, i, i + 1
|
|
355
|
+
elif i + 2 < len(tokens) and is_ldu(tokens[i + 1].text + tokens[i + 2].text):
|
|
356
|
+
pc = token.text + " " + tokens[i + 1].text + tokens[i + 2].text
|
|
357
|
+
pc_start, pc_end = i, i + 2
|
|
358
|
+
if pc:
|
|
359
|
+
self._set(postal_code=pc)
|
|
360
|
+
break
|
|
361
|
+
province = None
|
|
362
|
+
province_start = province_end = -1
|
|
363
|
+
for i, token in enumerate(tokens):
|
|
364
|
+
if pc_start <= i <= pc_end:
|
|
365
|
+
continue
|
|
366
|
+
if token.type == P.WORD and token.text in PROVINCE_CODES:
|
|
367
|
+
province, province_start, province_end = token.text, i, i
|
|
368
|
+
break
|
|
369
|
+
if province is None:
|
|
370
|
+
scan_end = pc_start if pc_start >= 0 else len(tokens)
|
|
371
|
+
for i in range(scan_end - 1, -1, -1):
|
|
372
|
+
if tokens[i].type != P.WORD:
|
|
373
|
+
continue
|
|
374
|
+
for name, code in PROVINCE_NAMES.items():
|
|
375
|
+
parts = name.split()
|
|
376
|
+
start = i - len(parts) + 1
|
|
377
|
+
if start < 0:
|
|
378
|
+
continue
|
|
379
|
+
if all(
|
|
380
|
+
not (pc_start >= 0 and pc_start <= start + j <= pc_end)
|
|
381
|
+
and tokens[start + j].text.removesuffix(".") == part.removesuffix(".")
|
|
382
|
+
for j, part in enumerate(parts)
|
|
383
|
+
):
|
|
384
|
+
province, province_start, province_end = code, start, i
|
|
385
|
+
break
|
|
386
|
+
if province:
|
|
387
|
+
break
|
|
388
|
+
if province:
|
|
389
|
+
self._set(province=province)
|
|
390
|
+
country = -1
|
|
391
|
+
for i in range(len(tokens) - 1, -1, -1):
|
|
392
|
+
if pc_start <= i <= pc_end or province_start <= i <= province_end:
|
|
393
|
+
continue
|
|
394
|
+
if tokens[i].type == P.WORD and tokens[i].text in COUNTRY_KEYWORDS:
|
|
395
|
+
self._set(country=tokens[i].text)
|
|
396
|
+
country = i
|
|
397
|
+
break
|
|
398
|
+
end = min([len(tokens)] + [i for i in (pc_start, province_start, country) if i >= 0])
|
|
399
|
+
municipality = " ".join(t.text for t in tokens[:end] if t.type != P.COMMA).strip()
|
|
400
|
+
if municipality:
|
|
401
|
+
self._set(municipality=municipality)
|
|
402
|
+
|
|
403
|
+
def _delivery(self, line: LineTokens) -> None:
|
|
404
|
+
tokens = line.tokens
|
|
405
|
+
if not tokens:
|
|
406
|
+
return
|
|
407
|
+
first = tokens[0]
|
|
408
|
+
if care_of(tokens):
|
|
409
|
+
self._set(care_of=" ".join(t.text for t in tokens[3:]))
|
|
410
|
+
elif first.text in PO_BOX_KEYWORDS:
|
|
411
|
+
self._set(address_type=AddressType.POSTAL_BOX)
|
|
412
|
+
for token in tokens:
|
|
413
|
+
if token.type == P.NUMBER:
|
|
414
|
+
self._set(postal_box_number=token.text)
|
|
415
|
+
break
|
|
416
|
+
elif first.text in {"RR", "R.R."}:
|
|
417
|
+
self._set(address_type=AddressType.RURAL_ROUTE)
|
|
418
|
+
for token in tokens[1:]:
|
|
419
|
+
if token.type == P.NUMBER:
|
|
420
|
+
self._set(rural_route=token.text)
|
|
421
|
+
break
|
|
422
|
+
elif first.text in {"GD", "GENERAL"} or gen_del(tokens):
|
|
423
|
+
self._set(address_type=AddressType.GENERAL_DELIVERY)
|
|
424
|
+
elif first.text in {"SITE", "COMP", "EMPL"}:
|
|
425
|
+
self._set(site_info=line.text)
|
|
426
|
+
elif is_unit_designator(first.text):
|
|
427
|
+
self._leading_unit(tokens)
|
|
428
|
+
elif split := unit_prefix(first.text):
|
|
429
|
+
self._set(unit_number=split[1])
|
|
430
|
+
idx = 1
|
|
431
|
+
if idx < len(tokens) and tokens[idx].type in NUMERIC_TYPES:
|
|
432
|
+
self._set(street_number=tokens[idx].text, address_type=AddressType.CIVIC)
|
|
433
|
+
idx = self._post_civic(tokens, idx + 1)
|
|
434
|
+
self._street(tokens, idx)
|
|
435
|
+
elif first.type in NUMERIC_TYPES:
|
|
436
|
+
self._civic(tokens)
|
|
437
|
+
elif first.type == P.LPAREN and len(tokens) >= 2 and tokens[1].type in NUMERIC_TYPES:
|
|
438
|
+
self._civic([t for t in tokens if t.type not in {P.LPAREN, P.RPAREN}])
|
|
439
|
+
elif any(t.type == P.WORD and normalize_street_type(t.text) for t in tokens):
|
|
440
|
+
self._street(tokens, 0, street_only=True)
|
|
441
|
+
if self.components.address_type == AddressType.INCOMPLETE:
|
|
442
|
+
self._set(address_type=AddressType.CIVIC)
|
|
443
|
+
elif not self.components.care_of:
|
|
444
|
+
self._set(care_of=line.text)
|
|
445
|
+
|
|
446
|
+
def _civic(self, tokens: list[TokenInfo]) -> None:
|
|
447
|
+
if (len(tokens) >= 3 and tokens[0].type == P.NUMBER
|
|
448
|
+
and tokens[1].type == P.HYPHEN and tokens[2].type == P.NUMBER):
|
|
449
|
+
self._set(unit_number=tokens[0].text, street_number=tokens[2].text)
|
|
450
|
+
idx = 3
|
|
451
|
+
else:
|
|
452
|
+
self._set(street_number=tokens[0].text)
|
|
453
|
+
idx = 1
|
|
454
|
+
self._set(address_type=AddressType.CIVIC)
|
|
455
|
+
self._street(tokens, self._post_civic(tokens, idx))
|
|
456
|
+
|
|
457
|
+
def _post_civic(self, tokens: list[TokenInfo], idx: int) -> int:
|
|
458
|
+
if (idx + 2 < len(tokens) and tokens[idx].type == P.NUMBER
|
|
459
|
+
and tokens[idx + 1].type == P.SLASH and tokens[idx + 2].type == P.NUMBER):
|
|
460
|
+
numerator, denominator = tokens[idx].text, tokens[idx + 2].text
|
|
461
|
+
numeric_numerator = numerator.lstrip("0") or "0"
|
|
462
|
+
numeric_denominator = denominator.lstrip("0") or "0"
|
|
463
|
+
# Java's fraction recognizer rejects values outside a signed 32-bit integer.
|
|
464
|
+
if (len(numeric_numerator) <= 10 and numeric_denominator in {"2", "3", "4", "8"}
|
|
465
|
+
and int(numeric_numerator) <= 2147483647
|
|
466
|
+
and int(numeric_numerator) < int(numeric_denominator)):
|
|
467
|
+
self._set(street_number=self.components.street_number + " " + numerator + "/" + denominator)
|
|
468
|
+
return idx + 3
|
|
469
|
+
if idx + 1 < len(tokens) and tokens[idx].type == P.SLASH and tokens[idx + 1].type == P.NUMBER:
|
|
470
|
+
self._set(street_number=self.components.street_number + "/" + tokens[idx + 1].text)
|
|
471
|
+
return idx + 2
|
|
472
|
+
return idx
|
|
473
|
+
|
|
474
|
+
def _leading_unit(self, tokens: list[TokenInfo]) -> None:
|
|
475
|
+
idx = 1
|
|
476
|
+
if idx >= len(tokens):
|
|
477
|
+
return
|
|
478
|
+
if (idx + 3 < len(tokens) and tokens[idx].type == P.NUMBER
|
|
479
|
+
and tokens[idx + 1].type in {P.SLASH, P.HYPHEN, P.DOT}
|
|
480
|
+
and tokens[idx + 2].type == P.NUMBER
|
|
481
|
+
and adjacent(tokens[idx], tokens[idx + 1])
|
|
482
|
+
and adjacent(tokens[idx + 1], tokens[idx + 2])
|
|
483
|
+
and tokens[idx + 3].type in NUMERIC_TYPES):
|
|
484
|
+
self._set(unit_number="".join(t.text for t in tokens[idx:idx + 3]))
|
|
485
|
+
idx += 3
|
|
486
|
+
if idx == 1:
|
|
487
|
+
candidate = tokens[idx]
|
|
488
|
+
following_civic = idx + 1 < len(tokens) and tokens[idx + 1].type in NUMERIC_TYPES
|
|
489
|
+
if candidate.type == P.ALPHANUMERIC or (candidate.type in {P.WORD, P.NUMBER} and following_civic):
|
|
490
|
+
self._set(unit_number=candidate.text)
|
|
491
|
+
idx += 1
|
|
492
|
+
if idx < len(tokens) and tokens[idx].type in NUMERIC_TYPES:
|
|
493
|
+
self._set(street_number=tokens[idx].text, address_type=AddressType.CIVIC)
|
|
494
|
+
idx = self._post_civic(tokens, idx + 1)
|
|
495
|
+
self._street(tokens, idx)
|
|
496
|
+
|
|
497
|
+
def _street(self, tokens: list[TokenInfo], start: int, street_only: bool = False) -> None:
|
|
498
|
+
words = collect_street_words(tokens, start)
|
|
499
|
+
if not words:
|
|
500
|
+
return
|
|
501
|
+
direction = None
|
|
502
|
+
prefix_set = DIRECTIONS if street_only else PREFIX_DIRECTIONS
|
|
503
|
+
prefix = len(words) > 1 and words[0] in prefix_set
|
|
504
|
+
if len(words) > 1 and words[-1] in DIRECTIONS:
|
|
505
|
+
bare_french = len(words) == 2 and len(words[-1]) == 1 and is_french_street_type(words[0])
|
|
506
|
+
if not bare_french and not opposing_directions(words[-2], words[-1]):
|
|
507
|
+
direction = words.pop()
|
|
508
|
+
if direction is None and prefix:
|
|
509
|
+
direction = words.pop(0)
|
|
510
|
+
if not street_only and not self.components.unit_number and len(words) >= 3:
|
|
511
|
+
self._trailing_unit(words)
|
|
512
|
+
self._classify_street(words)
|
|
513
|
+
if direction is not None and not self.components.street_direction:
|
|
514
|
+
self._set(street_direction=direction)
|
|
515
|
+
|
|
516
|
+
def _trailing_unit(self, words: list[str]) -> None:
|
|
517
|
+
type_idx = next((i for i in range(len(words) - 1, 0, -1)
|
|
518
|
+
if normalize_street_type(words[i])), -1)
|
|
519
|
+
if type_idx < 0 or type_idx == len(words) - 1:
|
|
520
|
+
return
|
|
521
|
+
after = type_idx + 1
|
|
522
|
+
direction = None
|
|
523
|
+
if words[after] in DIRECTIONS:
|
|
524
|
+
direction = words[after]
|
|
525
|
+
after += 1
|
|
526
|
+
unit = None
|
|
527
|
+
if after + 1 < len(words) and is_unit_designator(words[after]):
|
|
528
|
+
unit = " ".join(words[after + 1:])
|
|
529
|
+
elif after < len(words) and (split := unit_prefix(words[after])):
|
|
530
|
+
unit = split[1]
|
|
531
|
+
if unit is not None:
|
|
532
|
+
self._set(unit_number=unit)
|
|
533
|
+
if direction:
|
|
534
|
+
self._set(street_direction=direction)
|
|
535
|
+
del words[type_idx + 1 if direction else after:]
|
|
536
|
+
|
|
537
|
+
def _classify_street(self, words: list[str]) -> None:
|
|
538
|
+
if not words:
|
|
539
|
+
return
|
|
540
|
+
if len(words) == 1:
|
|
541
|
+
self._set(street_name=words[0])
|
|
542
|
+
return
|
|
543
|
+
first = words[0]
|
|
544
|
+
if is_french_street_type(first):
|
|
545
|
+
name_words = words[1:]
|
|
546
|
+
stripped = name_words[0].removesuffix(".")
|
|
547
|
+
type_as_name = (len(name_words) == 1 and normalize_street_type(stripped)
|
|
548
|
+
and stripped not in TYPE_WORDS_USED_AS_NAMES)
|
|
549
|
+
if not type_as_name:
|
|
550
|
+
bare = (len(name_words[0]) == 1 and name_words[0].isalpha()
|
|
551
|
+
or re.fullmatch(r"\d{1,2}[A-Za-z]?", name_words[0]) is not None)
|
|
552
|
+
keep_avenue = first.removesuffix(".") in {"AVENUE", "AVE", "AV"} and len(name_words) == 1 and bare
|
|
553
|
+
self._set(street_type=normalize_street_type(first) or first,
|
|
554
|
+
street_name=" ".join(words if keep_avenue else name_words))
|
|
555
|
+
return
|
|
556
|
+
last = normalize_street_type(words[-1])
|
|
557
|
+
preceding = words[-2].removesuffix(".")
|
|
558
|
+
if (last is None or preceding == "THE"
|
|
559
|
+
or (preceding in {"GRAND", "GRANDE", "LE", "LA", "LES"}
|
|
560
|
+
and is_french_street_type(words[-1])
|
|
561
|
+
and (last not in STREET_TYPES_EN or self.components.province == "QC"))):
|
|
562
|
+
self._set(street_name=" ".join(words))
|
|
563
|
+
elif len(words) >= 3 and len(preceding) <= 2 and preceding in DIRECTIONS:
|
|
564
|
+
self._set(street_type=last, street_direction=words[-2], street_name=" ".join(words[:-2]))
|
|
565
|
+
else:
|
|
566
|
+
self._set(street_type=last, street_name=" ".join(words[:-1]))
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: northpost-parser
|
|
3
|
+
Version: 1.1.0
|
|
4
|
+
Summary: Canadian postal address parser built with ANTLR4
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Author: Ryan Smith
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Requires-Dist: antlr4-python3-runtime (==4.13.2)
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# NorthPost Parser for Python
|
|
18
|
+
|
|
19
|
+
A standalone Poetry project alongside the Java library. Requires Python 3.11+.
|
|
20
|
+
Runtime parsing uses `antlr4-python3-runtime`; Java is **not** required to install
|
|
21
|
+
or use the Python package.
|
|
22
|
+
|
|
23
|
+
## Install and test
|
|
24
|
+
|
|
25
|
+
From this directory:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
poetry install
|
|
29
|
+
poetry run pytest
|
|
30
|
+
poetry build
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Or install directly from the repository root with `pip install ./python`.
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
from northpost_parser import (
|
|
39
|
+
AddressParserService,
|
|
40
|
+
NormalizationStrategy,
|
|
41
|
+
ParsingStrategy,
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
parser = AddressParserService()
|
|
45
|
+
result = parser.parse_address(
|
|
46
|
+
"JOHN DOE\n123 MAIN ST W\nTORONTO ON M5V 2Y7",
|
|
47
|
+
ParsingStrategy.STRICT_THEN_LENIENT,
|
|
48
|
+
)
|
|
49
|
+
if result.successful:
|
|
50
|
+
address = result.components
|
|
51
|
+
print(address.street_number) # 123
|
|
52
|
+
print(address.street_name) # MAIN
|
|
53
|
+
print(address.postal_code) # M5V 2Y7
|
|
54
|
+
print(address.get_formatted_address())
|
|
55
|
+
canonical = address.normalize(NormalizationStrategy.FULL_FORM)
|
|
56
|
+
print(canonical.street_type) # STREET
|
|
57
|
+
else:
|
|
58
|
+
print(result.errors)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The Python API uses snake_case names. Immutable dataclasses replace Java records
|
|
62
|
+
and builders; instantiate `AddressComponents(...)` directly or use
|
|
63
|
+
`dataclasses.replace`. String fields are trimmed, uppercased, and null-safe.
|
|
64
|
+
Presence helpers such as `has_unit_number()` are also available.
|
|
65
|
+
Formatting helpers return `str | None` instead of Java `Optional`.
|
|
66
|
+
|
|
67
|
+
`LENIENT` extracts available fields; `STRICT` requires a mailing-valid address;
|
|
68
|
+
`STRICT_THEN_LENIENT` retries and records strict rejection in warnings.
|
|
69
|
+
Mailing validity follows the Java implementation, including its requirement for
|
|
70
|
+
an addressee. Syntax errors and empty input still fail in lenient mode.
|
|
71
|
+
Results contain immutable error/warning tuples and the mode actually used.
|
|
72
|
+
`parse_addresses` and `get_batch_statistics` provide batch parsing and statistics.
|
|
73
|
+
Unknown street types/directions are preserved by normalization.
|
|
74
|
+
|
|
75
|
+
## ANTLR generation
|
|
76
|
+
|
|
77
|
+
The single source of truth is
|
|
78
|
+
[`../src/main/antlr/CanadianAddress.g4`](../src/main/antlr/CanadianAddress.g4).
|
|
79
|
+
Generated Python lexer, parser, and visitor sources are checked in, so installing
|
|
80
|
+
a wheel does not run Java or download tools.
|
|
81
|
+
|
|
82
|
+
After changing the grammar, install Java and run:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
poetry run python scripts/generate_parser.py
|
|
86
|
+
poetry run python scripts/generate_parser.py --check
|
|
87
|
+
poetry run pytest
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The script downloads ANTLR **4.13.2** into the user cache on first use. To avoid
|
|
91
|
+
that download, supply `--antlr-jar /path/to/antlr-4.13.2-complete.jar`.
|
|
92
|
+
The generator version and Poetry runtime pin must match. When upgrading ANTLR,
|
|
93
|
+
update both, regenerate, and rerun tests. Java regeneration remains
|
|
94
|
+
`./gradlew generateGrammarSource` from the repository root.
|
|
95
|
+
|
|
96
|
+
Tests reuse the repository's curated ODA fixture. The large ODA/NAR dataset
|
|
97
|
+
validation runners remain Java tooling; those datasets are not bundled in the
|
|
98
|
+
Python distribution. Existing Java releases and Maven publishing are unchanged.
|
|
99
|
+
|
|
100
|
+
## Releasing to PyPI
|
|
101
|
+
|
|
102
|
+
Publishing a GitHub release with a `vX.Y.Z` tag runs
|
|
103
|
+
[`release-python.yml`](../.github/workflows/release-python.yml) alongside the
|
|
104
|
+
Java release. It sets the package version from the tag, verifies the generated
|
|
105
|
+
sources, runs the tests, builds, and publishes using
|
|
106
|
+
[PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (no token).
|
|
107
|
+
|
|
108
|
+
One-time setup:
|
|
109
|
+
|
|
110
|
+
1. On PyPI, add a trusted publisher for project `northpost-parser`
|
|
111
|
+
(use *pending publisher* for the first release): owner `ryansmith4`,
|
|
112
|
+
repository `northpost-parser`, workflow `release-python.yml`,
|
|
113
|
+
environment `pypi`.
|
|
114
|
+
2. In the GitHub repository settings, create an environment named `pypi`
|
|
115
|
+
(optionally requiring reviewer approval).
|
|
116
|
+
|
|
117
|
+
To retry a failed publish: `gh workflow run release-python.yml --ref vX.Y.Z`.
|
|
118
|
+
|
|
119
|
+
Licensed under the [Apache-2.0 license](LICENSE).
|
|
120
|
+
|