structured-address-fix 0.1.0__py3-none-any.whl

structured_address_fix/__init__.py

@@ -0,0 +1,60 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""structured-address-fix: ISO 20022 postal-address remediation.
+
+Detects, scores, and remediates non-compliant postal addresses in ISO
+20022 payment messages ahead of the 14 November 2026 cliff, when fully
+unstructured addresses are rejected across the major cross-border and
+high-value schemes. The public surface is the :mod:`structured_address_fix.
+services` facade; the domain models are re-exported here for convenience.
+"""
+
+from structured_address_fix.domain import (
+    AddressClassification,
+    AddressedParty,
+    CanonicalAddress,
+    FindingCode,
+    MessageType,
+    PartyRole,
+    PatchOp,
+    PatchOperation,
+    PolicyId,
+    RemediationResult,
+    RemediationSuggestion,
+    RiskFinding,
+    Severity,
+    ValidationReport,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AddressClassification",
+    "AddressedParty",
+    "CanonicalAddress",
+    "FindingCode",
+    "MessageType",
+    "PartyRole",
+    "PatchOp",
+    "PatchOperation",
+    "PolicyId",
+    "RemediationResult",
+    "RemediationSuggestion",
+    "RiskFinding",
+    "Severity",
+    "ValidationReport",
+    "__version__",
+]

structured_address_fix/adapters/__init__.py

@@ -0,0 +1,58 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Adapters layer: I/O boundaries around the pure domain.
+
+This package translates between the outside world and the domain entities:
+
+- :mod:`iso3166` — offline ISO 3166-1 alpha-2 and US-state validation.
+- :mod:`heuristics` — country-aware unstructured-to-hybrid address splitting.
+- :mod:`xpath` — ISO 20022 ``PstlAdr`` location tables and message-type
+  detection.
+- :mod:`xml_reader` — parse a message into addressed parties (XXE-safe).
+- :mod:`xml_writer` — apply remediation patches back onto a message.
+"""
+
+from __future__ import annotations
+
+from structured_address_fix.adapters.heuristics import (
+    HeuristicResult,
+    split_unstructured,
+)
+from structured_address_fix.adapters.iso3166 import (
+    ALPHA2_CODES,
+    US_STATES,
+    is_iso_3166_1_alpha_2,
+    is_us_state,
+)
+from structured_address_fix.adapters.xml_reader import read_addresses
+from structured_address_fix.adapters.xml_writer import apply_operations
+from structured_address_fix.adapters.xpath import (
+    detect_message_type,
+    paths_for,
+)
+
+__all__ = [
+    "ALPHA2_CODES",
+    "US_STATES",
+    "HeuristicResult",
+    "apply_operations",
+    "detect_message_type",
+    "is_iso_3166_1_alpha_2",
+    "is_us_state",
+    "paths_for",
+    "read_addresses",
+    "split_unstructured",
+]

structured_address_fix/adapters/_xmlutil.py

@@ -0,0 +1,146 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Namespace-aware XML pointer utilities shared by the reader and writer.
+
+ISO 20022 documents use a single default namespace, so ``ElementTree``
+renders every tag in Clark notation (``{namespace}LocalName``). These
+helpers strip that namespace for local-name matching and resolve the
+slash-separated JSON pointers that :mod:`xml_reader` emits and
+:mod:`xml_writer` consumes.
+
+Pointer grammar: ``/Seg/Seg/...`` where each ``Seg`` is either an element
+local name or a decimal index. An index immediately follows the element-name
+segment it disambiguates and selects the zero-based occurrence among
+same-named siblings; a name with no following index means occurrence ``0``.
+The first segment must be the root element's local name.
+"""
+
+from __future__ import annotations
+
+from xml.etree.ElementTree import Element
+
+
+class PointerResolutionError(ValueError):
+    """A JSON pointer did not resolve to an element in the tree."""
+
+
+def local_name(tag: str) -> str:
+    """Return the local name of a (possibly namespaced) Clark-notation tag.
+
+    Args:
+        tag: An element tag, optionally in ``{namespace}LocalName`` form.
+
+    Returns:
+        The tag with any ``{namespace}`` prefix removed.
+    """
+    if tag.startswith("{"):
+        return tag.split("}", 1)[1]
+    return tag
+
+
+def namespace_of(tag: str) -> str:
+    """Return the namespace URI of a Clark-notation tag, or ``""``.
+
+    Args:
+        tag: An element tag, optionally in ``{namespace}LocalName`` form.
+
+    Returns:
+        The namespace URI, or the empty string if the tag is unqualified.
+    """
+    if tag.startswith("{"):
+        return tag[1:].split("}", 1)[0]
+    return ""
+
+
+def children_named(parent: Element, name: str) -> list[Element]:
+    """Return ``parent``'s direct children whose local name is ``name``.
+
+    Args:
+        parent: The element whose children to scan.
+        name: The local name to match.
+
+    Returns:
+        The matching child elements, in document order.
+    """
+    return [child for child in parent if local_name(child.tag) == name]
+
+
+def split_pointer_steps(pointer: str) -> list[tuple[str, int]]:
+    """Parse a JSON pointer into ``(local_name, index)`` steps.
+
+    Args:
+        pointer: A slash-separated pointer, e.g.
+            ``"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/0/Cdtr/PstlAdr"``.
+
+    Returns:
+        One ``(name, index)`` tuple per element step, with ``index``
+        defaulting to ``0`` when no explicit index segment follows.
+
+    Raises:
+        PointerResolutionError: if the pointer is empty or an index segment
+            has no preceding element name.
+    """
+    raw = [seg for seg in pointer.split("/") if seg != ""]
+    if not raw:
+        raise PointerResolutionError(f"empty pointer: {pointer!r}")
+
+    steps: list[tuple[str, int]] = []
+    for seg in raw:
+        if seg.isdigit():
+            if not steps:
+                raise PointerResolutionError(
+                    f"index segment with no element name: {pointer!r}"
+                )
+            name, _ = steps[-1]
+            steps[-1] = (name, int(seg))
+        else:
+            steps.append((seg, 0))
+    return steps
+
+
+def resolve_steps(root: Element, steps: list[tuple[str, int]]) -> Element:
+    """Resolve parsed pointer ``steps`` to an element, starting at ``root``.
+
+    Args:
+        root: The document root element.
+        steps: Parsed ``(name, index)`` steps; the first must name the root.
+
+    Returns:
+        The element the steps address.
+
+    Raises:
+        PointerResolutionError: if the root name mismatches or any step
+            selects a missing child/occurrence.
+    """
+    if not steps:
+        raise PointerResolutionError("cannot resolve empty steps")
+
+    root_name, _ = steps[0]
+    if local_name(root.tag) != root_name:
+        raise PointerResolutionError(
+            f"root is {local_name(root.tag)!r}, pointer expects {root_name!r}"
+        )
+
+    current = root
+    for name, index in steps[1:]:
+        matches = children_named(current, name)
+        if index >= len(matches):
+            raise PointerResolutionError(
+                f"no {name!r} occurrence {index} under "
+                f"{local_name(current.tag)!r}"
+            )
+        current = matches[index]
+    return current

structured_address_fix/adapters/heuristics/__init__.py

@@ -0,0 +1,94 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Country-aware unstructured-to-hybrid address heuristics.
+
+:func:`split_unstructured` dispatches free-form address lines to a
+country-specific splitter (``GB``, ``US``, ``DE``, ``FR``, ``JP``) or the
+best-effort fallback, returning a :class:`HeuristicResult` that carries the
+recovered structured fields plus a ``confidence`` score for downstream
+patch operations. Ported from ``pacs008.standards.address.from_unstructured``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from structured_address_fix.adapters.heuristics import (
+    de,
+    fallback,
+    fr,
+    gb,
+    jp,
+    us,
+)
+from structured_address_fix.adapters.heuristics.base import (
+    CONFIDENCE_EMPTY,
+    HeuristicResult,
+)
+from structured_address_fix.adapters.iso3166 import is_iso_3166_1_alpha_2
+from structured_address_fix.errors import InvalidAddressError
+
+_Splitter = Callable[[list[str], str], HeuristicResult]
+
+_HANDLERS: dict[str, _Splitter] = {
+    "GB": gb.split,
+    "US": us.split,
+    "DE": de.split,
+    "FR": fr.split,
+    "JP": jp.split,
+}
+
+
+def split_unstructured(
+    lines: Sequence[str],
+    country: str,
+) -> HeuristicResult:
+    """Split unstructured address lines into a country-aware hybrid form.
+
+    Country-specific heuristics cover ``GB``, ``US``, ``DE``, ``FR`` and
+    ``JP``; every other country falls back to promoting the last line to
+    ``town_name``. Empty or whitespace-only input yields a country-only
+    result with ``0.0`` confidence.
+
+    Args:
+        lines: Free-form address lines from legacy data. Empty and
+            whitespace-only lines are skipped.
+        country: The ISO 3166-1 alpha-2 country code (e.g. ``"GB"``).
+
+    Returns:
+        A :class:`HeuristicResult` carrying the derived structured fields,
+        residual ``address_lines``, and a heuristic ``confidence``.
+
+    Raises:
+        InvalidAddressError: if ``country`` is not a valid ISO 3166-1
+            alpha-2 code.
+    """
+    if not is_iso_3166_1_alpha_2(country):
+        raise InvalidAddressError(
+            "country must be ISO 3166-1 alpha-2 (e.g. 'GB', 'US'); "
+            f"got {country!r}",
+            context={"country": country},
+        )
+
+    cleaned = [line.strip() for line in lines if line and line.strip()]
+    if not cleaned:
+        return HeuristicResult(country=country, confidence=CONFIDENCE_EMPTY)
+
+    handler = _HANDLERS.get(country, fallback.split)
+    return handler(cleaned, country)
+
+
+__all__ = ["HeuristicResult", "split_unstructured"]

structured_address_fix/adapters/heuristics/base.py

@@ -0,0 +1,122 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared types and helpers for the country-aware address heuristics.
+
+Ported from ``pacs008.standards.address``. The behavioural change from the
+original is the return type: rather than a bare ``PostalAddress``, each
+country splitter yields a :class:`HeuristicResult` carrying the derived
+structured fields, the residual free-form ``address_lines``, and a
+``confidence`` score in ``[0, 1]`` that downstream remediation copies onto
+each :class:`~structured_address_fix.domain.remediation.PatchOperation`.
+
+Confidence is assigned by anchor quality:
+
+- ``0.9`` when a country-specific postcode/state anchor matched, so town
+  and postcode were located structurally.
+- ``0.4`` when no anchor matched and the last line was promoted to
+  ``town_name`` as a best-effort fallback.
+- ``0.0`` when the input carried no usable content at all.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from structured_address_fix.domain.address import (
+    MAX_ADDRESS_LINE,
+    MAX_HYBRID_ADDRESS_LINE_COUNT,
+    MAX_TOWN_NAME,
+)
+
+#: Confidence when a postcode/state anchor located town and postcode.
+CONFIDENCE_ANCHOR: float = 0.9
+
+#: Confidence when the last line was promoted to town as a fallback.
+CONFIDENCE_FALLBACK: float = 0.4
+
+#: Confidence when the input carried no usable content.
+CONFIDENCE_EMPTY: float = 0.0
+
+
+class HeuristicResult(BaseModel):
+    """The structured fields a splitter recovered from free-form lines.
+
+    Immutable. ``street_name`` is included for completeness — the current
+    country splitters do not infer it, so it is always ``None`` for now —
+    while ``town_name``, ``post_code`` and ``country_sub_division`` are
+    populated when an anchor is found. ``address_lines`` holds the residual
+    free-form text, capped at the CBPR+ hybrid limit of two lines.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    town_name: str | None = None
+    post_code: str | None = None
+    country_sub_division: str | None = None
+    street_name: str | None = None
+    country: str
+    address_lines: tuple[str, ...] = ()
+    confidence: float = Field(ge=0.0, le=1.0, default=0.0)
+
+
+def clip(value: str | None, maximum: int) -> str | None:
+    """Truncate ``value`` to ``maximum`` characters, preserving ``None``.
+
+    Args:
+        value: The string to clip, or ``None``.
+        maximum: The maximum permitted length.
+
+    Returns:
+        ``None`` if ``value`` is ``None``, else ``value`` truncated to
+        ``maximum`` characters.
+    """
+    if value is None:
+        return None
+    return value[:maximum]
+
+
+def pack_adr_lines(remaining: Sequence[str]) -> tuple[str, ...]:
+    """Pack residual lines into the hybrid ``AdrLine`` cap.
+
+    Whitespace-only lines are dropped, each surviving line is truncated to
+    the 70-character ISO 20022 maximum, and at most two lines are kept to
+    respect the CBPR+ UG2026 hybrid cap.
+
+    Args:
+        remaining: The leftover free-form lines.
+
+    Returns:
+        Up to two cleaned, length-clamped address lines.
+    """
+    cleaned = [line.strip() for line in remaining if line and line.strip()]
+    return tuple(
+        line[:MAX_ADDRESS_LINE]
+        for line in cleaned[:MAX_HYBRID_ADDRESS_LINE_COUNT]
+    )
+
+
+def clip_town(value: str | None) -> str | None:
+    """Clip a candidate town name to the ISO 20022 ``TwnNm`` maximum.
+
+    Args:
+        value: The candidate town name, or ``None``.
+
+    Returns:
+        The clipped town name, or ``None``.
+    """
+    return clip(value, MAX_TOWN_NAME)

structured_address_fix/adapters/heuristics/continental.py

@@ -0,0 +1,81 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared continental-European ``<5 digits> <town>`` splitter.
+
+Germany (``PLZ Ort``) and France (``code postal Ville``) share the same
+line shape: a five-digit postcode immediately followed by the town name.
+The country-specific modules supply their own compiled pattern.
+"""
+
+from __future__ import annotations
+
+import re
+
+from structured_address_fix.adapters.heuristics.base import (
+    CONFIDENCE_ANCHOR,
+    CONFIDENCE_FALLBACK,
+    HeuristicResult,
+    clip,
+    clip_town,
+    pack_adr_lines,
+)
+from structured_address_fix.domain.address import MAX_POST_CODE
+
+
+def split_continental(
+    lines: list[str],
+    country: str,
+    pattern: re.Pattern[str],
+) -> HeuristicResult:
+    """Split a continental-European address on a ``<5 digits> <town>`` line.
+
+    Args:
+        lines: Cleaned, non-empty address lines.
+        country: The ISO 3166-1 alpha-2 country code.
+        pattern: The compiled postcode pattern (capturing postcode then
+            town).
+
+    Returns:
+        A :class:`HeuristicResult` with ``0.9`` confidence when the
+        pattern anchored the split, else ``0.4`` for the last-line
+        fallback.
+    """
+    pst_cd: str | None = None
+    twn_nm: str | None = None
+    remaining: list[str] = []
+
+    for i, line in enumerate(lines):
+        match = pattern.search(line)
+        if match:
+            pst_cd = match.group(1)
+            twn_nm = match.group(2).strip()
+            remaining = [ln for j, ln in enumerate(lines) if j != i]
+            break
+
+    if pst_cd is None:
+        twn_nm = lines[-1]
+        remaining = lines[:-1]
+        confidence = CONFIDENCE_FALLBACK
+    else:
+        confidence = CONFIDENCE_ANCHOR
+
+    return HeuristicResult(
+        town_name=clip_town(twn_nm),
+        post_code=clip(pst_cd, MAX_POST_CODE),
+        country=country,
+        address_lines=pack_adr_lines(remaining),
+        confidence=confidence,
+    )

structured_address_fix/adapters/heuristics/de.py

@@ -0,0 +1,40 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Germany address splitter: five-digit PLZ followed by the Ort."""
+
+from __future__ import annotations
+
+import re
+
+from structured_address_fix.adapters.heuristics.base import HeuristicResult
+from structured_address_fix.adapters.heuristics.continental import (
+    split_continental,
+)
+
+_DE_POSTCODE = re.compile(r"\b(\d{5})\s+([^\d]{2,})")
+
+
+def split(lines: list[str], country: str) -> HeuristicResult:
+    """Split a German address on its ``PLZ Ort`` line.
+
+    Args:
+        lines: Cleaned, non-empty address lines.
+        country: The ISO 3166-1 alpha-2 country code (``"DE"``).
+
+    Returns:
+        A :class:`HeuristicResult` for the German address.
+    """
+    return split_continental(lines, country, _DE_POSTCODE)

structured_address_fix/adapters/heuristics/fallback.py

@@ -0,0 +1,50 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Best-effort splitter for countries without a dedicated heuristic.
+
+The last line is promoted to ``town_name`` and everything before it is
+packed into the residual address lines. Confidence is always ``0.4``
+because no postcode anchor is consulted.
+"""
+
+from __future__ import annotations
+
+from structured_address_fix.adapters.heuristics.base import (
+    CONFIDENCE_FALLBACK,
+    HeuristicResult,
+    clip_town,
+    pack_adr_lines,
+)
+
+
+def split(lines: list[str], country: str) -> HeuristicResult:
+    """Promote the last line to town for an unhandled country.
+
+    Args:
+        lines: Cleaned, non-empty address lines.
+        country: The ISO 3166-1 alpha-2 country code.
+
+    Returns:
+        A :class:`HeuristicResult` with ``0.4`` fallback confidence.
+    """
+    twn_nm = lines[-1]
+    remaining = lines[:-1]
+    return HeuristicResult(
+        town_name=clip_town(twn_nm),
+        country=country,
+        address_lines=pack_adr_lines(remaining),
+        confidence=CONFIDENCE_FALLBACK,
+    )

structured_address_fix/adapters/heuristics/fr.py

@@ -0,0 +1,40 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""France address splitter: five-digit code postal followed by the Ville."""
+
+from __future__ import annotations
+
+import re
+
+from structured_address_fix.adapters.heuristics.base import HeuristicResult
+from structured_address_fix.adapters.heuristics.continental import (
+    split_continental,
+)
+
+_FR_POSTCODE = re.compile(r"\b(\d{5})\s+([^\d]{2,})")
+
+
+def split(lines: list[str], country: str) -> HeuristicResult:
+    """Split a French address on its ``code postal Ville`` line.
+
+    Args:
+        lines: Cleaned, non-empty address lines.
+        country: The ISO 3166-1 alpha-2 country code (``"FR"``).
+
+    Returns:
+        A :class:`HeuristicResult` for the French address.
+    """
+    return split_continental(lines, country, _FR_POSTCODE)