addrforge 0.1.0__tar.gz

addrforge-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "addrforge"
+version = "0.1.0"
+description = "Dependency-free US address parser and normalizer"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "addrforge contributors"}]
+keywords = ["address", "parser", "normalization", "usps"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/RohitMadhu/addrforge"
+Repository = "https://github.com/RohitMadhu/addrforge"
+Issues = "https://github.com/RohitMadhu/addrforge/issues"
+
+[project.scripts]
+addrforge = "addrforge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

addrforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

addrforge-0.1.0/src/addrforge/__init__.py

@@ -0,0 +1,22 @@
+"""Public API for addrforge."""
+
+from .lines import split_lines
+from .models import AddressLines, ParsedAddress, ValidationResult
+from .parser import explain, is_probably_address, parse, standardize
+from .validation import CensusGeocoderProvider, NominatimProvider, ValidationProvider, get_provider, validate
+
+__all__ = [
+    "AddressLines",
+    "CensusGeocoderProvider",
+    "NominatimProvider",
+    "ParsedAddress",
+    "ValidationResult",
+    "ValidationProvider",
+    "explain",
+    "get_provider",
+    "is_probably_address",
+    "parse",
+    "split_lines",
+    "standardize",
+    "validate",
+]

addrforge-0.1.0/src/addrforge/cli.py

@@ -0,0 +1,71 @@
+"""Command line interface for addrforge."""
+
+import argparse
+import sys
+from typing import Optional, Sequence, TextIO
+
+from .lines import split_lines
+from .parser import parse
+from .validation import validate
+
+
+def main(argv: Optional[Sequence[str]] = None, *, stdout: Optional[TextIO] = None) -> int:
+    """Run the addrforge command line interface."""
+
+    parser = argparse.ArgumentParser(prog="addrforge", description="Parse and standardize US address strings.")
+    parser.add_argument("address", nargs="*", help="address text; stdin is used when omitted")
+    parser.add_argument("--json", action="store_true", help="print JSON instead of plain text")
+    parser.add_argument("--lines", action="store_true", help="split into mailing-style address lines")
+    parser.add_argument("--strict", action="store_true", help="reject incomplete partial parses")
+    parser.add_argument(
+        "--validate",
+        choices=("census", "nominatim"),
+        help="run an optional external geocodability check",
+    )
+    parser.add_argument("--timeout", type=float, default=5.0, help="validation request timeout in seconds")
+
+    args = parser.parse_args(argv)
+    out = stdout or sys.stdout
+    text = " ".join(args.address).strip() if args.address else sys.stdin.read().strip()
+
+    if args.validate:
+        result = validate(text, provider=args.validate, timeout=args.timeout)
+        print(result.to_json(indent=2) if args.json else _validation_summary(result), file=out)
+        return 0 if result.error is None else 2
+
+    if args.lines:
+        lines = split_lines(text, strict=args.strict)
+        print(lines.to_json(indent=2) if args.json else _line_summary(lines), file=out)
+        return 0
+
+    parsed = parse(text, strict=args.strict)
+    print(parsed.to_json(indent=2) if args.json else parsed.standardized, file=out)
+    return 0
+
+
+def _line_summary(lines: object) -> str:
+    parts = [
+        getattr(lines, "line1", ""),
+        getattr(lines, "line2", ""),
+        " ".join(
+            part
+            for part in (
+                getattr(lines, "city", None),
+                getattr(lines, "state", None),
+                getattr(lines, "zip_code", None),
+            )
+            if part
+        ),
+    ]
+    return "\n".join(part for part in parts if part)
+
+
+def _validation_summary(result: object) -> str:
+    matched = getattr(result, "matched_address", None) or ""
+    status = "matched" if getattr(result, "is_valid", False) else "not matched"
+    provider = getattr(result, "provider", "provider")
+    return f"{provider}: {status}" + (f"\n{matched}" if matched else "")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())