tanzania-postcodes 0.1.0__tar.gz

tanzania_postcodes-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: tanzania-postcodes
+Version: 0.1.0
+Summary: Real Tanzania postal codes, sourced directly from TCRA's official gazetted National Postcode System -- not a third-party compilation.
+Author-email: Freddy Nyanda <freddynyanda@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nyandajr/tanzania-postcodes
+Project-URL: Repository, https://github.com/nyandajr/tanzania-postcodes
+Project-URL: Source, https://www.tcra.go.tz/services/publication-of-postcode-list
+Keywords: tanzania,postcode,postal-code,zip-code,tcra,address
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 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 site's compiled or scraped version.
+
+No Python package for Tanzania postcodes existed before this one.
+[`pgeocode`](https://pypi.org/project/pgeocode/), the most common
+general-purpose postal code library, explicitly doesn't support Tanzania
+(`ValueError: country=TZ is not a known country code`) — its data comes
+from GeoNames, which has no real Tanzania coverage.
+
+## Install
+
+```bash
+pip install tanzania-postcodes
+```
+
+## Usage
+
+```python
+import tanzania_postcodes as tzpc
+
+# Look up everything at a postcode
+tzpc.lookup("16112")
+# [Postcode(region='Dar Es Salaam', district='UBUNGO', ward='Goba',
+#            postcode='16112', locality='Goba', ...), ...]
+
+# Search by name (ward, district, region, or locality)
+tzpc.search("Goba")[0].postcode
+# '16112'
+
+# List all 26 regions
+tzpc.regions()
+
+# List all wards, optionally scoped to one region
+tzpc.wards("Dar Es Salaam")
+```
+
+Each result is a `Postcode`:
+
+```python
+Postcode(
+    region: str,               # e.g. "Dar Es Salaam"
+    district: str | None,       # e.g. "UBUNGO"
+    ward: str,                  # e.g. "Goba" -- the unit TCRA's postcode identifies
+    postcode: str,               # e.g. "16112"
+    locality: str | None,       # mtaa/village within the ward
+    sub_locality: str | None,   # kitongoji, where the source PDF has one
+    old_postcode: str | None,   # legacy code, where the source PDF has one
+    district_postcode: str | None,
+)
+```
+
+## Coverage
+
+All **26 regions**, **67,000+ locality-level records**, **3,900+ unique
+ward postcodes**. A postcode identifies a *ward* — the same postcode
+applies to every village/mtaa within it, which is why `lookup()` usually
+returns multiple records for one code.
+
+## Where this data comes from, and how it was built
+
+TCRA publishes the postcode list as 26 separate regional PDFs (no
+CSV/Excel version exists) at
+[tcra.go.tz/services/publication-of-postcode-list](https://www.tcra.go.tz/services/publication-of-postcode-list).
+Each PDF's table uses merged cells for repeated values, and — found
+during development — **three different column layouts** across the 26
+files (some have a separate District level, some don't; some have an Old
+Postcode column, some don't; one region's table has no header row at
+all). `scripts/parse_pdfs.py` detects each table's actual header and
+maps columns by name rather than assuming one fixed schema, with a
+documented fallback for the one region missing a header entirely.
+
+`scripts/download_pdfs.py` and `scripts/parse_pdfs.py` are included in
+this repo if you want to verify the extraction yourself or regenerate
+the dataset from TCRA's source PDFs directly.
+
+## Why this exists
+
+Built after actually needing a Tanzania postcode (Goba ward, Dar es
+Salaam — `16112`), confirming no Python package or well-covered general
+library had it, and finding TCRA's own official data was real, current,
+and genuinely extractable — just never turned into a package before.
+
+## License
+
+MIT for this package's code. The underlying postcode data is Tanzania
+government public record (Government Gazette Notice No. 240, 2016).

tanzania_postcodes-0.1.0/README.md

@@ -0,0 +1,89 @@
+# 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 site's compiled or scraped version.
+
+No Python package for Tanzania postcodes existed before this one.
+[`pgeocode`](https://pypi.org/project/pgeocode/), the most common
+general-purpose postal code library, explicitly doesn't support Tanzania
+(`ValueError: country=TZ is not a known country code`) — its data comes
+from GeoNames, which has no real Tanzania coverage.
+
+## Install
+
+```bash
+pip install tanzania-postcodes
+```
+
+## Usage
+
+```python
+import tanzania_postcodes as tzpc
+
+# Look up everything at a postcode
+tzpc.lookup("16112")
+# [Postcode(region='Dar Es Salaam', district='UBUNGO', ward='Goba',
+#            postcode='16112', locality='Goba', ...), ...]
+
+# Search by name (ward, district, region, or locality)
+tzpc.search("Goba")[0].postcode
+# '16112'
+
+# List all 26 regions
+tzpc.regions()
+
+# List all wards, optionally scoped to one region
+tzpc.wards("Dar Es Salaam")
+```
+
+Each result is a `Postcode`:
+
+```python
+Postcode(
+    region: str,               # e.g. "Dar Es Salaam"
+    district: str | None,       # e.g. "UBUNGO"
+    ward: str,                  # e.g. "Goba" -- the unit TCRA's postcode identifies
+    postcode: str,               # e.g. "16112"
+    locality: str | None,       # mtaa/village within the ward
+    sub_locality: str | None,   # kitongoji, where the source PDF has one
+    old_postcode: str | None,   # legacy code, where the source PDF has one
+    district_postcode: str | None,
+)
+```
+
+## Coverage
+
+All **26 regions**, **67,000+ locality-level records**, **3,900+ unique
+ward postcodes**. A postcode identifies a *ward* — the same postcode
+applies to every village/mtaa within it, which is why `lookup()` usually
+returns multiple records for one code.
+
+## Where this data comes from, and how it was built
+
+TCRA publishes the postcode list as 26 separate regional PDFs (no
+CSV/Excel version exists) at
+[tcra.go.tz/services/publication-of-postcode-list](https://www.tcra.go.tz/services/publication-of-postcode-list).
+Each PDF's table uses merged cells for repeated values, and — found
+during development — **three different column layouts** across the 26
+files (some have a separate District level, some don't; some have an Old
+Postcode column, some don't; one region's table has no header row at
+all). `scripts/parse_pdfs.py` detects each table's actual header and
+maps columns by name rather than assuming one fixed schema, with a
+documented fallback for the one region missing a header entirely.
+
+`scripts/download_pdfs.py` and `scripts/parse_pdfs.py` are included in
+this repo if you want to verify the extraction yourself or regenerate
+the dataset from TCRA's source PDFs directly.
+
+## Why this exists
+
+Built after actually needing a Tanzania postcode (Goba ward, Dar es
+Salaam — `16112`), confirming no Python package or well-covered general
+library had it, and finding TCRA's own official data was real, current,
+and genuinely extractable — just never turned into a package before.
+
+## License
+
+MIT for this package's code. The underlying postcode data is Tanzania
+government public record (Government Gazette Notice No. 240, 2016).

tanzania_postcodes-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tanzania-postcodes"
+version = "0.1.0"
+description = "Real Tanzania postal codes, sourced directly from TCRA's official gazetted National Postcode System -- not a third-party compilation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Freddy Nyanda", email = "freddynyanda@proton.me" }]
+keywords = ["tanzania", "postcode", "postal-code", "zip-code", "tcra", "address"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "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 :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/nyandajr/tanzania-postcodes"
+Repository = "https://github.com/nyandajr/tanzania-postcodes"
+Source = "https://www.tcra.go.tz/services/publication-of-postcode-list"
+
+[tool.setuptools.packages.find]
+include = ["tanzania_postcodes*"]
+
+[tool.setuptools.package-data]
+tanzania_postcodes = ["data/*.json"]

tanzania_postcodes-0.1.0/setup.cfg

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

tanzania_postcodes-0.1.0/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__"]