kenya-data 0.1.0__tar.gz

kenya_data-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node / TypeScript
+node_modules/
+packages/typescript/dist/
+packages/typescript/coverage/
+npm-debug.log*
+
+# Database (generated artifact — rebuilt via `make build-db`)
+data/kenya.db
+data/kenya.db-journal
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Env
+.env
+.env.local

kenya_data-0.1.0/PKG-INFO

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

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

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kenya-data"
+version = "0.1.0"
+description = "Python SDK for the Kenya Data structured dataset"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Kenya Data contributors" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ToshGitonga0/kenya-data"
+Repository = "https://github.com/ToshGitonga0/kenya-data"
+Issues = "https://github.com/ToshGitonga0/kenya-data/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "mypy>=1.0", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kenya_data"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/kenya_data/kenya.db" = "kenya_data/kenya.db"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.ruff]
+line-length = 100

kenya_data-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/conftest.py

@@ -0,0 +1,18 @@
+"""Builds a throwaway SQLite database from the real approved data for each test session."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+
+@pytest.fixture(scope="session")
+def test_db_path(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    db_path = tmp_path_factory.mktemp("kenya-data-db") / "kenya.db"
+    seed_script = REPO_ROOT / "database" / "seeds" / "load_approved_data.py"
+    subprocess.run([sys.executable, str(seed_script), str(db_path)], check=True)
+    return db_path

kenya_data-0.1.0/tests/test_client.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from kenya_data import EntityNotFoundError, Kenya
+
+
+def test_counties_list_returns_real_counties(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    counties = kenya.counties.list()
+    assert len(counties) > 0
+    assert all(c.name for c in counties)
+
+
+def test_counties_get_by_name_case_insensitive(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    county = kenya.counties.get("nakuru")
+    assert county.name.lower() == "nakuru"
+
+
+def test_counties_get_unknown_raises(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    with pytest.raises(EntityNotFoundError):
+        kenya.counties.get("Not A Real County")
+
+
+def test_constituencies_in_county(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    constituencies = kenya.constituencies.in_county("Nakuru")
+    assert len(constituencies) > 0
+    assert all(c.county_id == kenya.counties.get("Nakuru").id for c in constituencies)
+
+
+def test_wards_in_constituency(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    constituency = kenya.constituencies.list()[0]
+    wards = kenya.wards.in_constituency(constituency.code)
+    assert all(w.constituency_id == constituency.id for w in wards)
+
+
+def test_wards_in_county_traverses_hierarchy(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    wards = kenya.wards.in_county("Nakuru")
+    assert len(wards) > 0
+
+
+def test_dataset_metadata_present(test_db_path: Path) -> None:
+    kenya = Kenya(db_path=test_db_path)
+    assert kenya.dataset.version
+    assert kenya.dataset.updated_at
+
+
+def test_missing_database_raises_file_not_found(tmp_path: Path) -> None:
+    with pytest.raises(FileNotFoundError):
+        Kenya(db_path=tmp_path / "does-not-exist.db")