kenya-data 0.1.0__py3-none-any.whl

kenya_data/__init__.py

@@ -0,0 +1,7 @@
+"""Kenya Data — Python SDK."""
+
+from .client import Kenya
+from .exceptions import EntityNotFoundError
+
+__all__ = ["EntityNotFoundError", "Kenya"]
+__version__ = "0.1.0"

kenya_data/client.py

@@ -0,0 +1,36 @@
+"""The top-level Kenya Data client."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from .constituencies import Constituencies
+from .counties import Counties
+from .dataset import Dataset
+from .db import connect
+from .wards import Wards
+
+
+class Kenya:
+    """Entry point for the Kenya Data SDK.
+
+    >>> kenya = Kenya()
+    >>> kenya.counties.list()          # doctest: +SKIP
+    >>> kenya.counties.get("Nakuru")   # doctest: +SKIP
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        self._conn: sqlite3.Connection = connect(db_path)
+        self.counties = Counties(self._conn)
+        self.constituencies = Constituencies(self._conn)
+        self.wards = Wards(self._conn)
+        self.dataset = Dataset(self._conn)
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> Kenya:  # noqa: PYI034 (Self requires Python >=3.11)
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()

kenya_data/constituencies.py

@@ -0,0 +1,39 @@
+"""Constituency lookups."""
+from __future__ import annotations
+
+import builtins
+import sqlite3
+
+from .counties import Counties
+from .exceptions import EntityNotFoundError
+from .models import Constituency
+
+
+class Constituencies:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def list(self) -> builtins.list[Constituency]:
+        rows = self._conn.execute(
+            "SELECT id, code, name, county_id, status FROM constituencies ORDER BY name"
+        ).fetchall()
+        return [Constituency(**dict(r)) for r in rows]
+
+    def get(self, name_or_code: str) -> Constituency:
+        row = self._conn.execute(
+            "SELECT id, code, name, county_id, status FROM constituencies "
+            "WHERE name = ? COLLATE NOCASE OR code = ? COLLATE NOCASE",
+            (name_or_code, name_or_code),
+        ).fetchone()
+        if row is None:
+            raise EntityNotFoundError("constituency", name_or_code)
+        return Constituency(**dict(row))
+
+    def in_county(self, county_name_or_code: str) -> builtins.list[Constituency]:
+        county = Counties(self._conn).get(county_name_or_code)
+        rows = self._conn.execute(
+            "SELECT id, code, name, county_id, status FROM constituencies "
+            "WHERE county_id = ? ORDER BY name",
+            (county.id,),
+        ).fetchall()
+        return [Constituency(**dict(r)) for r in rows]

kenya_data/counties.py

@@ -0,0 +1,29 @@
+"""County lookups."""
+from __future__ import annotations
+
+import builtins
+import sqlite3
+
+from .exceptions import EntityNotFoundError
+from .models import County
+
+
+class Counties:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def list(self) -> builtins.list[County]:
+        rows = self._conn.execute(
+            "SELECT id, code, name, capital, status FROM counties ORDER BY name"
+        ).fetchall()
+        return [County(**dict(r)) for r in rows]
+
+    def get(self, name_or_code: str) -> County:
+        row = self._conn.execute(
+            "SELECT id, code, name, capital, status FROM counties "
+            "WHERE name = ? COLLATE NOCASE OR code = ? COLLATE NOCASE",
+            (name_or_code, name_or_code),
+        ).fetchone()
+        if row is None:
+            raise EntityNotFoundError("county", name_or_code)
+        return County(**dict(row))

kenya_data/dataset.py

@@ -0,0 +1,28 @@
+"""Dataset (as opposed to SDK) version metadata."""
+from __future__ import annotations
+
+import sqlite3
+
+from .models import DatasetInfo
+
+
+class Dataset:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def info(self) -> DatasetInfo:
+        row = self._conn.execute(
+            "SELECT version, status, created_at FROM dataset_versions "
+            "ORDER BY id DESC LIMIT 1"
+        ).fetchone()
+        if row is None:
+            return DatasetInfo(version="unknown", status="unknown", updated_at="unknown")
+        return DatasetInfo(version=row["version"], status=row["status"], updated_at=row["created_at"])
+
+    @property
+    def version(self) -> str:
+        return self.info().version
+
+    @property
+    def updated_at(self) -> str:
+        return self.info().updated_at

kenya_data/db.py

@@ -0,0 +1,28 @@
+"""Connection handling and packaged database resolution."""
+
+from __future__ import annotations
+
+import sqlite3
+from importlib.resources import files
+from pathlib import Path
+
+
+def default_db_path() -> Path:
+    packaged = Path(str(files("kenya_data").joinpath("kenya.db")))
+    if packaged.exists():
+        return packaged
+
+    # Local repository fallback.
+    return Path(__file__).resolve().parents[4] / "data" / "kenya.db"
+
+
+def connect(db_path: str | Path | None = None) -> sqlite3.Connection:
+    path = Path(db_path) if db_path is not None else default_db_path()
+
+    if not path.exists():
+        raise FileNotFoundError(f"No Kenya Data database found at {path}")
+
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn

kenya_data/exceptions.py

@@ -0,0 +1,14 @@
+"""Exceptions raised by the Kenya Data SDK."""
+
+
+class KenyaDataError(Exception):
+    """Base class for all kenya-data SDK errors."""
+
+
+class EntityNotFoundError(KenyaDataError):
+    """Raised when a lookup does not match any entity."""
+
+    def __init__(self, entity_type: str, identifier: str) -> None:
+        self.entity_type = entity_type
+        self.identifier = identifier
+        super().__init__(f"No {entity_type} found matching {identifier!r}")

kenya_data/models.py

@@ -0,0 +1,38 @@
+"""Lightweight, typed record wrappers returned by the SDK."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class County:
+    id: int
+    code: str
+    name: str
+    capital: str | None
+    status: str
+
+
+@dataclass(frozen=True)
+class Constituency:
+    id: int
+    code: str
+    name: str
+    county_id: int
+    status: str
+
+
+@dataclass(frozen=True)
+class Ward:
+    id: int
+    code: str
+    name: str
+    constituency_id: int
+    status: str
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    version: str
+    status: str
+    updated_at: str

kenya_data/wards.py

@@ -0,0 +1,51 @@
+"""Ward lookups."""
+from __future__ import annotations
+
+import builtins
+import sqlite3
+
+from .constituencies import Constituencies
+from .exceptions import EntityNotFoundError
+from .models import Ward
+
+
+class Wards:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def list(self) -> builtins.list[Ward]:
+        rows = self._conn.execute(
+            "SELECT id, code, name, constituency_id, status FROM wards ORDER BY name"
+        ).fetchall()
+        return [Ward(**dict(r)) for r in rows]
+
+    def get(self, name_or_code: str) -> Ward:
+        row = self._conn.execute(
+            "SELECT id, code, name, constituency_id, status FROM wards "
+            "WHERE name = ? COLLATE NOCASE OR code = ? COLLATE NOCASE",
+            (name_or_code, name_or_code),
+        ).fetchone()
+        if row is None:
+            raise EntityNotFoundError("ward", name_or_code)
+        return Ward(**dict(row))
+
+    def in_constituency(self, constituency_name_or_code: str) -> builtins.list[Ward]:
+        constituency = Constituencies(self._conn).get(constituency_name_or_code)
+        rows = self._conn.execute(
+            "SELECT id, code, name, constituency_id, status FROM wards "
+            "WHERE constituency_id = ? ORDER BY name",
+            (constituency.id,),
+        ).fetchall()
+        return [Ward(**dict(r)) for r in rows]
+
+    def in_county(self, county_name_or_code: str) -> builtins.list[Ward]:
+        rows = self._conn.execute(
+            """SELECT wards.id, wards.code, wards.name, wards.constituency_id, wards.status
+               FROM wards
+               JOIN constituencies ON constituencies.id = wards.constituency_id
+               JOIN counties ON counties.id = constituencies.county_id
+               WHERE counties.name = ? COLLATE NOCASE OR counties.code = ? COLLATE NOCASE
+               ORDER BY wards.name""",
+            (county_name_or_code, county_name_or_code),
+        ).fetchall()
+        return [Ward(**dict(r)) for r in rows]

kenya_data-0.1.0.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: kenya-data
+Version: 0.1.0
+Summary: Python SDK for the Kenya Data structured dataset
+Project-URL: Homepage, https://github.com/ToshGitonga0/kenya-data
+Project-URL: Repository, https://github.com/ToshGitonga0/kenya-data
+Project-URL: Issues, https://github.com/ToshGitonga0/kenya-data/issues
+Author: Kenya Data contributors
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kenya-data (Python SDK)
+
+```python
+from kenya_data import Kenya
+
+kenya = Kenya()                       # loads the bundled data/kenya.db by default
+kenya = Kenya(db_path="/path/to/kenya.db")  # or point at a specific build
+
+kenya.counties.list()
+kenya.counties.get("Nakuru")
+kenya.constituencies.in_county("Nakuru")
+kenya.wards.in_constituency("Naivasha")
+
+kenya.dataset.version
+kenya.dataset.updated_at
+```
+
+Backed by the SQLite database built from `database/schema/schema.sql` —
+see the repository root [README](../../README.md) and
+[docs/sdk-design.md](../../docs/sdk-design.md).

kenya_data-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kenya_data/__init__.py,sha256=gW9PvFotPYtxoUFbL1y9EwUo6k6WG44V6ZlfKqRFd0c,170
+kenya_data/client.py,sha256=cHaKkc7_Z9EXNvXIv-TPDMXNUEK-ReIGXVU8U_01dAw,1012
+kenya_data/constituencies.py,sha256=jkJ8pnjpROhSoTsH0ealArX4bQMjKlo8DGRqrXtieNM,1405
+kenya_data/counties.py,sha256=aJJKBRXihHLy7tlJfzee75V0UHLQtLYWGnXQksVvdgc,902
+kenya_data/dataset.py,sha256=irm3Zp4xPpSy98GUIye2NB9srEBSMQDkRY_Sqlnx9cQ,822
+kenya_data/db.py,sha256=ag6VsYup_Qks_yXRpQOP4p-wdx2tKeRKdP04T6DGpTY,803
+kenya_data/exceptions.py,sha256=t32YbufRyu-S1EGUgLDCWINNOpJRi9qcWzNeOwZNtQM,457
+kenya_data/models.py,sha256=f7WzA5FUg0y76R8Beko9JFtAGkW4mB_HisEaqVy1PsI,590
+kenya_data/wards.py,sha256=HtWIBFQDV1oQAZ18qTjqLgi9piVkUtly2PFI2QYlax0,2001
+kenya_data/kenya.db,sha256=KE6py0ekepZxKShKehfkwyuMz8ZuWHdJ5Y0R4zsSn_g,466944
+kenya_data-0.1.0.dist-info/METADATA,sha256=umj1lHI8bDDBJbmUMqtLfvZ0ROdl1wgA_HWnkoiHo7U,1305
+kenya_data-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+kenya_data-0.1.0.dist-info/RECORD,,

kenya_data-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any