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.
@@ -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
+