tanzania-postcodes 0.1.0__py3-none-any.whl

tanzania_postcodes/__init__.py

@@ -0,0 +1,86 @@
+"""tanzania-postcodes: real Tanzania postal codes, sourced directly from
+TCRA's official gazetted National Postcode System (Government Gazette
+Notice No. 240, 22 April 2016) -- not a third-party's compiled version.
+
+    >>> import tanzania_postcodes as tzpc
+    >>> tzpc.lookup("16112")[0].ward
+    'Goba'
+    >>> tzpc.search("Goba")[0].postcode
+    '16112'
+"""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+__version__ = "0.1.0"
+
+_DATA_PATH = Path(__file__).parent / "data" / "postcodes.json"
+
+
+@dataclass(frozen=True)
+class Postcode:
+    """One locality-level record. Multiple localities share the same
+    ward-level `postcode` -- that's the actual unit TCRA's system
+    identifies, not the individual village/mtaa.
+    """
+    region: str
+    district: Optional[str]
+    ward: str
+    postcode: str
+    locality: Optional[str]
+    sub_locality: Optional[str]
+    old_postcode: Optional[str] = None
+    district_postcode: Optional[str] = None
+
+
+def _load():
+    with open(_DATA_PATH, encoding="utf-8") as f:
+        raw = json.load(f)
+    return [Postcode(**r) for r in raw]
+
+
+_RECORDS = None
+
+
+def _records():
+    global _RECORDS
+    if _RECORDS is None:
+        _RECORDS = _load()
+    return _RECORDS
+
+
+def lookup(postcode: str) -> list[Postcode]:
+    """All records sharing this exact postcode (usually several -- one
+    ward maps to multiple villages/mtaa)."""
+    postcode = postcode.strip()
+    return [r for r in _records() if r.postcode == postcode]
+
+
+def search(query: str) -> list[Postcode]:
+    """Case-insensitive substring search across ward, district, region,
+    locality, and sub_locality names."""
+    q = query.strip().lower()
+    if not q:
+        return []
+    results = []
+    for r in _records():
+        haystack = " ".join(filter(None, [r.region, r.district, r.ward, r.locality, r.sub_locality])).lower()
+        if q in haystack:
+            results.append(r)
+    return results
+
+
+def regions() -> list[str]:
+    """All 26 regions with postcode data."""
+    return sorted({r.region for r in _records()})
+
+
+def wards(region: Optional[str] = None) -> list[str]:
+    """All ward names, optionally filtered to one region."""
+    recs = _records() if region is None else [r for r in _records() if r.region.lower() == region.lower()]
+    return sorted({r.ward for r in recs})
+
+
+__all__ = ["Postcode", "lookup", "search", "regions", "wards", "__version__"]