northpost-parser 1.1.0__py3-none-any.whl

northpost_parser/models.py

@@ -0,0 +1,158 @@
+"""Immutable parsed address components and parsing/normalization strategies."""
+
+from dataclasses import dataclass, fields, replace
+from enum import Enum
+
+
+class AddressType(Enum):
+    CIVIC = "CIVIC"
+    POSTAL_BOX = "POSTAL_BOX"
+    RURAL_ROUTE = "RURAL_ROUTE"
+    GENERAL_DELIVERY = "GENERAL_DELIVERY"
+    MIXED = "MIXED"
+    INCOMPLETE = "INCOMPLETE"
+
+
+class ParsingMode(Enum):
+    STRICT = "STRICT"
+    LENIENT = "LENIENT"
+
+
+class ParsingStrategy(Enum):
+    LENIENT = "LENIENT"
+    STRICT = "STRICT"
+    STRICT_THEN_LENIENT = "STRICT_THEN_LENIENT"
+
+
+class NormalizationStrategy(Enum):
+    FULL_FORM = "FULL_FORM"
+    ABBREVIATED = "ABBREVIATED"
+
+
+@dataclass(frozen=True)
+class AddressComponents:
+    addressee: str = ""
+    care_of: str = ""
+    unit_number: str = ""
+    street_number: str = ""
+    street_name: str = ""
+    street_type: str = ""
+    street_direction: str = ""
+    postal_box_number: str = ""
+    rural_route: str = ""
+    site_info: str = ""
+    municipality: str = ""
+    province: str = ""
+    postal_code: str = ""
+    country: str = ""
+    address_type: AddressType = AddressType.INCOMPLETE
+    parsing_mode: ParsingMode = ParsingMode.LENIENT
+    is_complete: bool = False
+
+    def __post_init__(self) -> None:
+        for field in fields(self):
+            if field.name not in {"address_type", "parsing_mode", "is_complete"}:
+                value = getattr(self, field.name)
+                object.__setattr__(self, field.name, "" if value is None else value.strip().upper())
+        if self.address_type is None:
+            raise TypeError("Address type cannot be null")
+        if self.parsing_mode is None:
+            raise TypeError("Parsing mode cannot be null")
+
+    def has_addressee(self) -> bool:
+        return bool(self.addressee)
+
+    def has_care_of(self) -> bool:
+        return bool(self.care_of)
+
+    def has_unit_number(self) -> bool:
+        return bool(self.unit_number)
+
+    def has_street_number(self) -> bool:
+        return bool(self.street_number)
+
+    def has_street_name(self) -> bool:
+        return bool(self.street_name)
+
+    def has_street_type(self) -> bool:
+        return bool(self.street_type)
+
+    def has_street_direction(self) -> bool:
+        return bool(self.street_direction)
+
+    def has_postal_box_number(self) -> bool:
+        return bool(self.postal_box_number)
+
+    def has_rural_route(self) -> bool:
+        return bool(self.rural_route)
+
+    def has_municipality(self) -> bool:
+        return bool(self.municipality)
+
+    def has_province(self) -> bool:
+        return bool(self.province)
+
+    def has_postal_code(self) -> bool:
+        return bool(self.postal_code)
+
+    def has_country(self) -> bool:
+        return bool(self.country)
+
+    def get_formatted_street_address(self) -> str | None:
+        value = f"{self.unit_number}-" if self.unit_number else ""
+        if self.street_number:
+            value += self.street_number + " "
+        if self.street_name:
+            value += " ".join(filter(None, (self.street_name, self.street_type, self.street_direction)))
+        return value.strip() or None
+
+    def get_full_street_name(self) -> str | None:
+        if not self.street_name:
+            return None
+        return " ".join(filter(None, (self.street_name, self.street_type, self.street_direction)))
+
+    def get_formatted_civic_line(self) -> str | None:
+        match self.address_type:
+            case AddressType.CIVIC:
+                return self.get_formatted_street_address()
+            case AddressType.POSTAL_BOX:
+                return f"PO BOX {self.postal_box_number}" if self.postal_box_number else None
+            case AddressType.RURAL_ROUTE:
+                return f"RR {self.rural_route}" if self.rural_route else None
+            case AddressType.GENERAL_DELIVERY:
+                return "GENERAL DELIVERY"
+            case _:
+                return None
+
+    def get_formatted_last_line(self) -> str | None:
+        value = " ".join(filter(None, (self.municipality, self.province)))
+        if self.postal_code:
+            value += ("  " if value else "") + self.postal_code
+        return value or None
+
+    def get_formatted_address(self) -> str:
+        return "\n".join(filter(None, (
+            self.addressee,
+            f"C/O {self.care_of}" if self.care_of else "",
+            self.get_formatted_civic_line(),
+            self.get_formatted_last_line(),
+            self.country,
+        ))).strip()
+
+    def normalize(self, strategy: NormalizationStrategy) -> "AddressComponents":
+        from .normalizer import AddressNormalizer
+
+        return replace(
+            self,
+            street_type=AddressNormalizer.normalize_street_type(self.street_type, strategy),
+            street_direction=AddressNormalizer.normalize_direction(self.street_direction, strategy),
+        )
+
+    def is_mailing_valid(self) -> bool:
+        return bool(
+            self.addressee
+            and (self.street_name or self.postal_box_number or self.rural_route)
+            and self.municipality
+            and self.province
+            and self.postal_code
+        )

northpost_parser/normalizer.py

@@ -0,0 +1,107 @@
+"""Canada Post street-type and direction normalization tables."""
+
+from .models import NormalizationStrategy
+
+
+def _register(full: dict[str, str], abbreviated: dict[str, str],
+              name: str, abbreviation: str) -> None:
+    full[abbreviation] = name
+    full[name] = name
+    abbreviated.setdefault(name, abbreviation)
+    abbreviated[abbreviation] = abbreviation
+
+
+def _alias(full: dict[str, str], abbreviated: dict[str, str],
+           abbreviation: str, name: str) -> None:
+    full[abbreviation] = name
+    abbreviated[abbreviation] = abbreviated.get(name, abbreviation)
+
+
+_STREET_FULL: dict[str, str] = {}
+_STREET_ABBREVIATED: dict[str, str] = {}
+for _name, _abbreviation in (
+    ("STREET", "ST"), ("AVENUE", "AVE"), ("BOULEVARD", "BLVD"),
+    ("DRIVE", "DR"), ("ROAD", "RD"), ("PLACE", "PL"), ("COURT", "CRT"),
+    ("CRESCENT", "CRES"), ("CIRCLE", "CIR"), ("WAY", "WY"), ("LANE", "LN"),
+    ("TERRACE", "TERR"), ("TRAIL", "TRL"), ("PARKWAY", "PKY"), ("HIGHWAY", "HWY"),
+    ("CLOSE", "CL"), ("GATE", "GT"), ("GREEN", "GR"), ("GROVE", "GV"),
+    ("HEATH", "HE"), ("HEIGHTS", "HTS"), ("HILL", "HL"), ("LANDING", "LD"),
+    ("MEWS", "MS"), ("PARK", "PK"), ("POINT", "PT"), ("SQUARE", "SQ"),
+    ("WALK", "WK"), ("BAY", "BA"), ("BRANCH", "BR"), ("CIRCUIT", "CIRC"),
+    ("COMMON", "CM"), ("CONCESSION", "CON"), ("COVE", "CO"), ("CREEK", "CRK"),
+    ("CROSSING", "XG"), ("ESPLANADE", "ESPL"), ("ESTATES", "ESTS"),
+    ("EXTENSION", "EXTEN"), ("FREEWAY", "FWY"), ("GARDENS", "GDNS"),
+    ("INLET", "INL"), ("LINE", "LI"), ("LOOKOUT", "LKOUT"), ("MANOR", "MR"),
+    ("MOUNT", "MT"), ("MOUNTAIN", "MTN"), ("PASSAGE", "PASS"), ("PRIVATE", "PVT"),
+    ("PROMENADE", "PROM"), ("RANGE", "RG"), ("RISE", "RI"), ("SIDEROAD", "SDRD"),
+    ("TOWNLINE", "TL"), ("TRUNK", "TR"), ("VIEW", "VW"),
+):
+    _register(_STREET_FULL, _STREET_ABBREVIATED, _name, _abbreviation)
+
+for _abbreviation, _name in (
+    ("AV", "AVENUE"), ("BV", "BOULEVARD"), ("DV", "DRIVE"), ("CT", "COURT"),
+    ("CR", "CRESCENT"), ("CI", "CIRCLE"), ("PY", "PARKWAY"), ("HY", "HIGHWAY"),
+    ("CLO", "CLOSE"), ("GA", "GATE"), ("GRN", "GREEN"), ("GRV", "GROVE"),
+    ("HT", "HEIGHTS"), ("LANDNG", "LANDING"), ("PA", "PARK"), ("CV", "COVE"),
+    ("CDS", "CROSSING"), ("GDN", "GARDENS"), ("PR", "PRIVATE"), ("RO", "RISE"),
+    ("SR", "SIDEROAD"), ("VI", "VIEW"), ("ME", "MAZE"), ("TC", "THICKET"),
+    ("TE", "THICKET"), ("XG", "CROSSING"),
+):
+    _alias(_STREET_FULL, _STREET_ABBREVIATED, _abbreviation, _name)
+
+for _name, _abbreviation in (
+    ("BOULEVARD", "BOUL"), ("CHEMIN", "CH"), ("ROUTE", "RTE"),
+    ("IMPASSE", "IMP"), ("TERRASSE", "TSSE"), ("CARRÉ", "CAR"),
+):
+    _register(_STREET_FULL, _STREET_ABBREVIATED, _name, _abbreviation)
+for _abbreviation, _name in (
+    ("BL", "BOULEVARD"), ("CMN", "CHEMIN"), ("CARRE", "CARRÉ"),
+    ("MONTEE", "MONTÉE"), ("COTE", "CÔTE"), ("ALLEE", "ALLÉE"), ("CRETE", "CRÊTE"),
+):
+    _alias(_STREET_FULL, _STREET_ABBREVIATED, _abbreviation, _name)
+
+_DIRECTION_FULL: dict[str, str] = {}
+_DIRECTION_ABBREVIATED: dict[str, str] = {}
+for _name, _abbreviation in (
+    ("NORTH", "N"), ("SOUTH", "S"), ("EAST", "E"), ("WEST", "W"),
+    ("NORTHEAST", "NE"), ("NORTHWEST", "NW"), ("SOUTHEAST", "SE"), ("SOUTHWEST", "SW"),
+    ("NORTHBOUND", "NB"), ("SOUTHBOUND", "SB"), ("EASTBOUND", "EB"), ("WESTBOUND", "WB"),
+):
+    _register(_DIRECTION_FULL, _DIRECTION_ABBREVIATED, _name, _abbreviation)
+for _abbreviation, _name in (
+    ("N.", "NORTH"), ("S.", "SOUTH"), ("E.", "EAST"), ("W.", "WEST"),
+    ("N.E.", "NORTHEAST"), ("N.W.", "NORTHWEST"), ("S.E.", "SOUTHEAST"), ("S.W.", "SOUTHWEST"),
+):
+    _alias(_DIRECTION_FULL, _DIRECTION_ABBREVIATED, _abbreviation, _name)
+for _name, _abbreviation in (("NORD", "N"), ("SUD", "S"), ("EST", "E"), ("OUEST", "O")):
+    _DIRECTION_FULL[_name] = _name
+    _DIRECTION_ABBREVIATED[_name] = _abbreviation
+_DIRECTION_FULL["O"] = "OUEST"
+_DIRECTION_ABBREVIATED["O"] = "O"
+
+
+def _normalize(value: str | None, strategy: NormalizationStrategy,
+               full: dict[str, str], abbreviated: dict[str, str]) -> str | None:
+    if not value:
+        return value
+    match strategy:
+        case NormalizationStrategy.FULL_FORM:
+            return full.get(value.upper(), value)
+        case NormalizationStrategy.ABBREVIATED:
+            return abbreviated.get(value.upper(), value)
+        case _:
+            raise ValueError(f"Unknown normalization strategy: {strategy!r}")
+
+
+class AddressNormalizer:
+    """Normalize known values; preserve unknown and empty values unchanged."""
+
+    @staticmethod
+    def normalize_street_type(street_type: str | None,
+                              strategy: NormalizationStrategy) -> str | None:
+        return _normalize(street_type, strategy, _STREET_FULL, _STREET_ABBREVIATED)
+
+    @staticmethod
+    def normalize_direction(direction: str | None,
+                            strategy: NormalizationStrategy) -> str | None:
+        return _normalize(direction, strategy, _DIRECTION_FULL, _DIRECTION_ABBREVIATED)

northpost_parser/service.py

@@ -0,0 +1,162 @@
+"""ANTLR-backed parsing service with strict and lenient validation."""
+
+from collections import Counter
+from collections.abc import Iterable
+from dataclasses import dataclass
+import logging
+import re
+
+from antlr4 import CommonTokenStream, InputStream
+from antlr4.error.ErrorListener import ErrorListener
+
+from .generated.CanadianAddressLexer import CanadianAddressLexer
+from .generated.CanadianAddressParser import CanadianAddressParser
+from .models import AddressComponents, ParsingMode, ParsingStrategy
+from .visitor import AddressComponentVisitor
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ParsingResult:
+    components: AddressComponents
+    successful: bool
+    errors: tuple[str, ...]
+    warnings: tuple[str, ...]
+    mode_used: ParsingMode
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "errors", tuple(self.errors))
+        object.__setattr__(self, "warnings", tuple(self.warnings))
+
+    def has_errors(self) -> bool:
+        return bool(self.errors)
+
+
+@dataclass(frozen=True)
+class BatchStatistics:
+    total_addresses: int
+    successful_parses: int
+    strict_mode_used: int
+    lenient_mode_used: int
+    complete_addresses: int
+    common_warnings: tuple[str, ...]
+
+
+class _CollectingErrorListener(ErrorListener):
+    def __init__(self) -> None:
+        super().__init__()
+        self.errors: list[str] = []
+
+    def syntaxError(self, recognizer, offendingSymbol, line, column, msg, e):
+        self.errors.append(f"Line {line}:{column} {msg}")
+
+
+class AddressParserService:
+    def parse_address(
+        self, address_text: str | None, strategy: ParsingStrategy = ParsingStrategy.LENIENT
+    ) -> ParsingResult:
+        if address_text is None or not address_text.strip():
+            return ParsingResult(
+                AddressComponents(), False, ("Address text cannot be null or empty",),
+                (), ParsingMode.LENIENT,
+            )
+        normalized = re.sub(r"[ \t]+", " ", address_text.strip()).upper()
+        match strategy:
+            case ParsingStrategy.LENIENT:
+                return self._do_parse(normalized, ParsingMode.LENIENT)
+            case ParsingStrategy.STRICT:
+                return self._do_parse(normalized, ParsingMode.STRICT)
+            case ParsingStrategy.STRICT_THEN_LENIENT:
+                strict = self._do_parse(normalized, ParsingMode.STRICT)
+                if strict.successful:
+                    return strict
+                lenient = self._do_parse(normalized, ParsingMode.LENIENT)
+                return ParsingResult(
+                    lenient.components, lenient.successful, lenient.errors,
+                    lenient.warnings + ("Strict parsing failed: " + "; ".join(strict.errors),),
+                    ParsingMode.LENIENT,
+                )
+            case _:
+                raise ValueError(f"Unknown parsing strategy: {strategy!r}")
+
+    def _do_parse(self, address_text: str, mode: ParsingMode) -> ParsingResult:
+        listener = _CollectingErrorListener()
+        warnings: list[str] = []
+        try:
+            lexer = CanadianAddressLexer(InputStream(address_text))
+            lexer.removeErrorListeners()
+            lexer.addErrorListener(listener)
+            parser = CanadianAddressParser(CommonTokenStream(lexer))
+            parser.removeErrorListeners()
+            parser.addErrorListener(listener)
+            tree = parser.address()
+            if listener.errors:
+                return ParsingResult(
+                    AddressComponents(parsing_mode=mode), False, tuple(listener.errors), (), mode,
+                )
+            components = AddressComponentVisitor(mode).visit(tree)
+            warnings.extend(self._validate_components(components))
+            if mode is ParsingMode.STRICT and not components.is_mailing_valid():
+                return ParsingResult(
+                    components, False, tuple(self._build_strict_errors(components)),
+                    tuple(warnings), mode,
+                )
+            return ParsingResult(components, True, (), tuple(warnings), mode)
+        except Exception as error:
+            _logger.exception("Unexpected error during parsing")
+            return ParsingResult(
+                AddressComponents(parsing_mode=mode), False,
+                (f"Unexpected error: {error}",), tuple(warnings), mode,
+            )
+
+    @staticmethod
+    def _build_strict_errors(components: AddressComponents) -> list[str]:
+        errors = ["Address is not complete for mailing purposes"]
+        if not components.addressee:
+            errors.append("Missing addressee")
+        if not (components.street_number or components.postal_box_number or components.rural_route):
+            errors.append("Missing delivery address")
+        if not components.municipality:
+            errors.append("Missing municipality")
+        if not components.province:
+            errors.append("Missing province")
+        if not components.postal_code:
+            errors.append("Missing postal code")
+        return errors
+
+    @staticmethod
+    def _validate_components(components: AddressComponents) -> list[str]:
+        warnings = []
+        if components.country:
+            warnings.append("Country specification is redundant for Canadian addresses")
+        if not components.is_mailing_valid():
+            warnings.append("Address may be incomplete for mailing purposes")
+        if (components.street_name and not components.street_number
+                and not components.postal_box_number and not components.rural_route):
+            warnings.append("Street name provided without street number")
+        if components.postal_code and len(re.sub(r"\s", "", components.postal_code)) != 6:
+            warnings.append("Postal code format may be invalid")
+        if sum(bool(value) for value in (
+            components.street_name, components.postal_box_number, components.rural_route,
+        )) > 1:
+            warnings.append("Multiple address types detected - this may be unusual")
+        return warnings
+
+    def parse_addresses(
+        self, addresses: Iterable[str | None], strategy: ParsingStrategy = ParsingStrategy.LENIENT
+    ) -> list[ParsingResult]:
+        return [self.parse_address(address, strategy) for address in addresses]
+
+    def get_batch_statistics(self, results: Iterable[ParsingResult]) -> BatchStatistics:
+        results = list(results)
+        total = len(results)
+        counts = Counter(warning for result in results for warning in result.warnings)
+        return BatchStatistics(
+            total,
+            sum(result.successful for result in results),
+            sum(result.mode_used is ParsingMode.STRICT for result in results),
+            sum(result.mode_used is ParsingMode.LENIENT for result in results),
+            sum(result.components.is_complete for result in results),
+            tuple(sorted(warning for warning, count in counts.items() if count > total * 0.1)),
+        )