addrforge 0.1.0__py3-none-any.whl

addrforge/validation.py

@@ -0,0 +1,255 @@
+"""Optional external lookup providers for address geocodability checks."""
+
+import json
+from typing import Any, Callable, Dict, Optional, Protocol
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen as default_urlopen
+
+from .models import ParsedAddress, ValidationResult
+from .parser import parse
+
+Urlopen = Callable[..., Any]
+
+
+class ValidationProvider(Protocol):
+    """Protocol implemented by optional validation providers."""
+
+    name: str
+
+    def validate(self, text: str, *, timeout: float = 5.0) -> ValidationResult:
+        """Validate or geocode an address string."""
+
+
+class CensusGeocoderProvider:
+    """US Census Geocoder provider.
+
+    This checks whether an address can be matched to Census MAF/TIGER address
+    ranges. It is not USPS delivery validation and does not prove mailability.
+    """
+
+    name = "census"
+
+    def __init__(
+        self,
+        *,
+        benchmark: str = "Public_AR_Current",
+        base_url: str = "https://geocoding.geo.census.gov/geocoder/locations/onelineaddress",
+        urlopen: Optional[Urlopen] = None,
+    ) -> None:
+        self.benchmark = benchmark
+        self.base_url = base_url
+        self._urlopen = urlopen or default_urlopen
+
+    def validate(self, text: str, *, timeout: float = 5.0) -> ValidationResult:
+        parsed = parse(text)
+        if not parsed.is_us:
+            return _skipped_result(text, self.name, parsed, "non_us_address")
+
+        params = urlencode({"address": text, "benchmark": self.benchmark, "format": "json"})
+        url = f"{self.base_url}?{params}"
+        try:
+            payload = _load_json(url, self._urlopen, timeout=timeout)
+        except Exception as exc:  # pragma: no cover - exact urllib failures vary
+            return _error_result(text, self.name, parsed, exc)
+
+        matches = (((payload or {}).get("result") or {}).get("addressMatches") or [])
+        if not matches:
+            return ValidationResult(
+                raw=text,
+                provider=self.name,
+                parsed=parsed,
+                is_valid=False,
+                is_deliverable=None,
+                match_level="unknown",
+                confidence=0.2,
+                warnings=("no_census_match", "not_delivery_validation"),
+                metadata={"query_url": url},
+            )
+
+        match = matches[0]
+        coords = match.get("coordinates") or {}
+        matched_address = match.get("matchedAddress")
+        return ValidationResult(
+            raw=text,
+            provider=self.name,
+            parsed=parsed,
+            is_valid=True,
+            is_deliverable=None,
+            match_level="exact-ish",
+            confidence=0.9,
+            matched_address=matched_address,
+            latitude=_float_or_none(coords.get("y")),
+            longitude=_float_or_none(coords.get("x")),
+            warnings=("not_delivery_validation",),
+            metadata={
+                "benchmark": self.benchmark,
+                "address_components": match.get("addressComponents") or {},
+                "tiger_line": match.get("tigerLine") or {},
+            },
+        )
+
+
+class NominatimProvider:
+    """OpenStreetMap Nominatim provider.
+
+    Public Nominatim usage requires a real identifying User-Agent or Referer,
+    clear attribution, caching where appropriate, and low request volume.
+    """
+
+    name = "nominatim"
+
+    def __init__(
+        self,
+        *,
+        user_agent: str = "addrforge/0.1",
+        base_url: str = "https://nominatim.openstreetmap.org/search",
+        urlopen: Optional[Urlopen] = None,
+    ) -> None:
+        self.user_agent = user_agent
+        self.base_url = base_url
+        self._urlopen = urlopen or default_urlopen
+
+    def validate(self, text: str, *, timeout: float = 5.0) -> ValidationResult:
+        parsed = parse(text)
+        if not parsed.is_us:
+            return _skipped_result(text, self.name, parsed, "non_us_address")
+
+        params = urlencode(
+            {
+                "q": text,
+                "format": "jsonv2",
+                "addressdetails": "1",
+                "limit": "1",
+                "countrycodes": "us",
+            }
+        )
+        url = f"{self.base_url}?{params}"
+        request = Request(url, headers={"User-Agent": self.user_agent})
+        try:
+            payload = _load_json(request, self._urlopen, timeout=timeout)
+        except Exception as exc:  # pragma: no cover - exact urllib failures vary
+            return _error_result(text, self.name, parsed, exc)
+
+        results = payload if isinstance(payload, list) else []
+        if not results:
+            return ValidationResult(
+                raw=text,
+                provider=self.name,
+                parsed=parsed,
+                is_valid=False,
+                is_deliverable=None,
+                match_level="unknown",
+                confidence=0.2,
+                warnings=("no_nominatim_match", "not_delivery_validation"),
+                metadata={"query_url": url},
+            )
+
+        result = results[0]
+        address = result.get("address") or {}
+        is_us = (address.get("country_code") or "").lower() == "us"
+        has_street = bool(address.get("road") or address.get("pedestrian"))
+        has_number = bool(address.get("house_number"))
+        confidence = _nominatim_confidence(result, is_us=is_us, has_street=has_street, has_number=has_number)
+        return ValidationResult(
+            raw=text,
+            provider=self.name,
+            parsed=parsed,
+            is_valid=is_us,
+            is_deliverable=None,
+            match_level="partial" if is_us else "unknown",
+            confidence=confidence,
+            matched_address=result.get("display_name"),
+            latitude=_float_or_none(result.get("lat")),
+            longitude=_float_or_none(result.get("lon")),
+            warnings=("not_delivery_validation", "requires_osm_attribution"),
+            metadata={
+                "osm_type": result.get("osm_type"),
+                "osm_id": result.get("osm_id"),
+                "address": address,
+                "has_house_number": has_number,
+                "has_street": has_street,
+            },
+        )
+
+
+def validate(text: str, provider: Any = "census", *, timeout: float = 5.0) -> ValidationResult:
+    """Run an optional external geocodability check.
+
+    ``provider`` may be ``"census"``, ``"nominatim"``, or an object with a
+    ``validate(text, timeout=...)`` method. Results are not proof of USPS
+    deliverability.
+    """
+
+    selected = get_provider(provider)
+    return selected.validate(text, timeout=timeout)
+
+
+def get_provider(provider: Any) -> ValidationProvider:
+    """Return a provider instance for a provider name or provider object."""
+
+    if isinstance(provider, str):
+        key = provider.lower()
+        if key == "census":
+            return CensusGeocoderProvider()
+        if key == "nominatim":
+            return NominatimProvider()
+        raise ValueError(f"unknown validation provider: {provider}")
+    if hasattr(provider, "validate"):
+        return provider
+    raise TypeError("provider must be a provider name or validation provider object")
+
+
+def _load_json(request: Any, opener: Urlopen, *, timeout: float) -> Any:
+    response = opener(request, timeout=timeout)
+    with response:
+        data = response.read().decode("utf-8")
+    return json.loads(data)
+
+
+def _skipped_result(text: str, provider: str, parsed: ParsedAddress, reason: str) -> ValidationResult:
+    return ValidationResult(
+        raw=text,
+        provider=provider,
+        parsed=parsed,
+        is_valid=False,
+        is_deliverable=None,
+        match_level="unknown",
+        confidence=0.0,
+        warnings=(reason,),
+    )
+
+
+def _error_result(text: str, provider: str, parsed: ParsedAddress, exc: Exception) -> ValidationResult:
+    return ValidationResult(
+        raw=text,
+        provider=provider,
+        parsed=parsed,
+        is_valid=False,
+        is_deliverable=None,
+        match_level="unknown",
+        confidence=0.0,
+        warnings=("provider_error",),
+        error=str(exc),
+    )
+
+
+def _nominatim_confidence(result: Dict[str, Any], *, is_us: bool, has_street: bool, has_number: bool) -> float:
+    if not is_us:
+        return 0.0
+    confidence = 0.45
+    if has_street:
+        confidence += 0.2
+    if has_number:
+        confidence += 0.2
+    try:
+        confidence += min(float(result.get("importance") or 0), 0.1)
+    except (TypeError, ValueError):
+        pass
+    return round(min(confidence, 0.9), 2)
+
+
+def _float_or_none(value: Any) -> Optional[float]:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

addrforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: addrforge
+Version: 0.1.0
+Summary: Dependency-free US address parser and normalizer
+Author: addrforge contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/RohitMadhu/addrforge
+Project-URL: Repository, https://github.com/RohitMadhu/addrforge
+Project-URL: Issues, https://github.com/RohitMadhu/addrforge/issues
+Keywords: address,parser,normalization,usps
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# addrforge
+
+`addrforge` is a lightweight, dependency-free Python package for parsing and standardizing messy US address strings. It returns structured components, USPS-like uppercase normalized strings, mailing-style address lines, and optional geocodability checks through free public providers.
+
+The local parser is offline and dependency-free. Optional validation providers may call external public APIs, but they still do not prove USPS deliverability.
+
+## Install
+
+```bash
+pip install addrforge
+```
+
+For editable local development:
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```python
+from addrforge import explain, parse, split_lines, standardize, validate
+
+parsed = parse("123 north main street apartment 4b")
+print(parsed.kind)          # street
+print(parsed.number)        # 123
+print(parsed.predir)        # N
+print(parsed.suffix)        # ST
+print(parsed.unit_type)     # APT
+print(parsed.standardized)  # 123 N MAIN ST APT 4B
+print(parsed.confidence)    # 0.99
+print(parsed.parse_notes)   # ('missing_place_tail',)
+print(parsed.match_level)   # partial
+
+print(standardize("PO Box 45, Fairfax, VA 22030"))
+# PO BOX 45 FAIRFAX VA 22030
+
+print(explain("Main Street"))
+# ('missing_house_number', 'missing_place_tail')
+
+lines = split_lines("123 Main St Apt 4B, Fairfax VA 22030")
+print(lines.line1)          # 123 MAIN ST
+print(lines.line2)          # APT 4B
+
+result = validate("1600 Pennsylvania Ave NW, Washington DC 20500", provider="census")
+print(result.is_valid)      # True when Census returns an address-range match
+print(result.is_deliverable)  # None; this is not USPS delivery validation
+```
+
+For strict parsing:
+
+```python
+parse("Main Street", strict=True).kind
+# unknown
+```
+
+For JSON:
+
+```python
+print(parse("123 Main St").to_json(indent=2))
+```
+
+From the command line:
+
+```bash
+addrforge "123 north main street apartment 4b"
+addrforge --json "123 Main St, Fairfax VA 22030"
+addrforge --lines "123 Main St Apt 4B, Fairfax VA 22030"
+```
+
+## Supported Patterns
+
+- Standard street addresses such as `123 Main Street`, `123 N Main St`, `12-14 W Elm Rd`, and `1600 Pennsylvania Avenue NW`
+- Named streets without a house number such as `42nd Street`
+- Unit and subaddress designators including `Apt`, `Apartment`, `Suite`, `Ste`, `Unit`, `Room`, `Floor`, `Bldg`, `Lot`, `No. 4`, `#200`, and unit-before-street forms such as `Suite 200 123 Main Street`
+- Highway and route forms including `I-95`, `US 29`, `State Route 7`, `County Road 12`, `Farm to Market Road 1960`, and `Route 66`
+- PO Box forms including `PO Box 45`, `P.O. Box 45`, and `Post Office Box 45`
+- Rural, highway contract, and military mailbox forms such as `RR 2 Box 152`, `HC 67 Box 12`, `PSC 123 Box 456 APO AE 09012`, and `CMR 123 Box 456`
+- Optional city, state, and ZIP tails such as `Fairfax, VA 22030`, `Arlington VA 22201`, and `Washington, DC 20001-1234`
+- Obvious non-US addresses are rejected cleanly with `is_us=False` and `reject_reason`
+
+Parsed results include:
+
+- `confidence`: heuristic score from `0.0` to `0.99`
+- `match_level`: `exact-ish`, `partial`, `weak`, or `unknown`
+- `components_missing`: component names still needed for mailing-style completeness
+- `warnings`: machine-readable warning codes
+- `parse_notes`: explanation codes for partial or ambiguous parses
+- `is_complete_for_mailing`: whether the parsed components include a primary line, city, state, and ZIP
+
+These are heuristics for caller triage, not proof that an address is real.
+
+## Optional Validation Providers
+
+`addrforge.validate()` supports two no-registration providers:
+
+- `provider="census"` uses the US Census Geocoder. It can indicate whether an address is geocodable against Census address-range data.
+- `provider="nominatim"` uses OpenStreetMap Nominatim. It can indicate whether OSM found a US place/address-like result.
+
+Both providers use only the Python standard library. Both may be free to call without registration, but they are external services with their own usage policies. Nominatim requires a real identifying User-Agent and low request volume. Neither provider is a USPS/CASS/DPV deliverability validator.
+
+## Non-Goals
+
+- USPS/CASS/DPV deliverability checks
+- Misspelling correction
+- International address parsing
+- Replacing specialized address parsers for every edge case
+
+## Development
+
+Run the test suite with:
+
+```bash
+PYTHONPATH=src python -m unittest discover
+```
+
+The library targets Python 3.9+ and uses only the Python standard library.

addrforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+addrforge/__init__.py,sha256=R4qif8gf5WcLC3v2_Azhwr6qybAo6H1DemvstKa8amY,599
+addrforge/cli.py,sha256=BPIilTBfvBrR_8zGiFVeYFrwCFAqTIPiWzHlLgOAQWg,2680
+addrforge/data.py,sha256=PGSk3ZDrgiS69hN5NWkSSbB0pqwxyKvAlVmTJmJpvgE,11889
+addrforge/errors.py,sha256=gsiKceA3eWtj8PwEMay90SNz8gasVXzQrslwIX92SrY,239
+addrforge/format.py,sha256=LfuKjrQhPchKZ_BFMfUEEIlY6UtUC8lx7Hnc2BCaCrA,2081
+addrforge/lines.py,sha256=OzYu031yL3Pi00UDve1wunbZVrZOUVhS0RtloGnRo90,737
+addrforge/models.py,sha256=yQ3LgscWlFyZqgE2dFCa30B7KBRwCmYlPO1twLaPvlc,2794
+addrforge/normalize.py,sha256=DZhYdnu7iM5bVJjH88eEem5YWd_tDkCT-RzjSQcwaoU,2103
+addrforge/parser.py,sha256=hGiOAHV9_itmGkNuyBpc8QRN6y-5tR4sH2HRuECar98,12057
+addrforge/patterns.py,sha256=nkNYdPMe_aGOYpUIIsAmRX0x98vZnPlnCChOuk3JvMg,2845
+addrforge/validation.py,sha256=Ifa9-KsqTSta3hNzP3vyF9CuZmaseVFsu54ytvIVgzo,8672
+addrforge-0.1.0.dist-info/licenses/LICENSE,sha256=AY8-IgyHqK8mBGYchYHeQmHEvX4a7gWDjXRQ_-WnXEc,1079
+addrforge-0.1.0.dist-info/METADATA,sha256=Y0H9H920_F0jTV_5DpwAFG_7jYZlWZjHqB_JAfALrVI,5388
+addrforge-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+addrforge-0.1.0.dist-info/entry_points.txt,sha256=FpVEaxyBHzkWZZviUCqHWb_HFPDVuEX2P0vP4wtkCDA,49
+addrforge-0.1.0.dist-info/top_level.txt,sha256=MGlWeqQOrAmIXUHyiUZIsTudf4mlPH7fp4FShzr6lRQ,10
+addrforge-0.1.0.dist-info/RECORD,,

addrforge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

addrforge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+addrforge = addrforge.cli:main

addrforge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 addrforge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

addrforge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+addrforge