uk-gp-practices 0.1.0__tar.gz

uk_gp_practices-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/python -m pytest:*)"
+    ]
+  }
+}

uk_gp_practices-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+
+# Local data/cache
+.cache/
+data/
+*.db
+*.sqlite
+*.sqlite3

uk_gp_practices-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: uk-gp-practices
+Version: 0.1.0
+Summary: Query UK GP practices (surgeries) via NHS ODS Data Search & Export CSV reports.
+Author: Joshua Evans
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: typer>=0.12
+Provides-Extra: fuzzy
+Requires-Dist: rapidfuzz>=3.0; extra == 'fuzzy'
+Description-Content-Type: text/markdown
+
+# uk-gp-practices
+
+Query UK GP practices ("surgeries") locally using NHS ODS Data Search & Export (DSE) CSV reports.
+
+This package downloads a predefined ODS report (default: `epraccur`), stores it in a local SQLite database, and provides a simple Python API + CLI to query it quickly.
+
+> **Note:** On first use the package will automatically download the latest report from the NHS ODS endpoint. Subsequent queries use the local cache (refreshed daily by default).
+
+## Install
+
+```bash
+pip install uk-gp-practices
+```
+
+For fuzzy name matching (optional):
+
+```bash
+pip install uk-gp-practices[fuzzy]
+```
+
+## Python API
+
+```python
+from uk_gp_practices import PracticeIndex
+
+# Auto-download the latest data (cached for 24 h)
+idx = PracticeIndex.auto_update()
+
+# Look up a single practice by ODS code
+practice = idx.get("A81001")
+print(practice.name, practice.postcode)
+
+# Search by name / postcode / town / status
+results = idx.search(name="castle", status="ACTIVE", limit=10)
+for r in results:
+    print(r.organisation_code, r.name, r.postcode)
+
+# Context-manager usage
+with PracticeIndex.auto_update() as idx:
+    print(idx.get("A81001"))
+```
+
+## CLI
+
+```bash
+# Update the local database
+uk-gp update
+
+# Get a single practice (JSON output)
+uk-gp get A81001
+
+# Search practices
+uk-gp search --name "castle" --status ACTIVE --limit 5
+uk-gp search --postcode "SW1A 1AA"
+uk-gp search --town "Swansea"
+```
+
+## License
+
+MIT

uk_gp_practices-0.1.0/README.md

@@ -0,0 +1,60 @@
+# uk-gp-practices
+
+Query UK GP practices ("surgeries") locally using NHS ODS Data Search & Export (DSE) CSV reports.
+
+This package downloads a predefined ODS report (default: `epraccur`), stores it in a local SQLite database, and provides a simple Python API + CLI to query it quickly.
+
+> **Note:** On first use the package will automatically download the latest report from the NHS ODS endpoint. Subsequent queries use the local cache (refreshed daily by default).
+
+## Install
+
+```bash
+pip install uk-gp-practices
+```
+
+For fuzzy name matching (optional):
+
+```bash
+pip install uk-gp-practices[fuzzy]
+```
+
+## Python API
+
+```python
+from uk_gp_practices import PracticeIndex
+
+# Auto-download the latest data (cached for 24 h)
+idx = PracticeIndex.auto_update()
+
+# Look up a single practice by ODS code
+practice = idx.get("A81001")
+print(practice.name, practice.postcode)
+
+# Search by name / postcode / town / status
+results = idx.search(name="castle", status="ACTIVE", limit=10)
+for r in results:
+    print(r.organisation_code, r.name, r.postcode)
+
+# Context-manager usage
+with PracticeIndex.auto_update() as idx:
+    print(idx.get("A81001"))
+```
+
+## CLI
+
+```bash
+# Update the local database
+uk-gp update
+
+# Get a single practice (JSON output)
+uk-gp get A81001
+
+# Search practices
+uk-gp search --name "castle" --status ACTIVE --limit 5
+uk-gp search --postcode "SW1A 1AA"
+uk-gp search --town "Swansea"
+```
+
+## License
+
+MIT

uk_gp_practices-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uk-gp-practices"
+version = "0.1.0"
+description = "Query UK GP practices (surgeries) via NHS ODS Data Search & Export CSV reports."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Joshua Evans" }]
+dependencies = [
+    "httpx>=0.27",
+    "platformdirs>=4.0",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+fuzzy = ["rapidfuzz>=3.0"]
+
+[project.scripts]
+uk-gp = "uk_gp_practices.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uk_gp_practices"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

uk_gp_practices-0.1.0/src/uk_gp_practices/__init__.py

@@ -0,0 +1,13 @@
+"""UK GP Practices ODS data handling."""
+
+from importlib.metadata import version, PackageNotFoundError
+
+from .index import PracticeIndex
+from .models import Practice
+
+try:
+    __version__ = version("uk-gp-practices")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["Practice", "PracticeIndex", "__version__"]

uk_gp_practices-0.1.0/src/uk_gp_practices/cli.py

@@ -0,0 +1,60 @@
+"""Typer CLI for querying UK GP practices (surgeries) via NHS ODS DSE CSV reports."""
+
+from __future__ import annotations
+
+import json
+import typer
+
+from .index import PracticeIndex
+
+
+app = typer.Typer(help="Query UK GP practices (surgeries) via NHS ODS DSE CSV reports.")
+
+
+@app.command()
+def update(report: str = "epraccur") -> None:
+    """
+    Download the latest report and update the local database.
+    """
+    idx = PracticeIndex.auto_update(report=report)
+    typer.echo(f"DB ready at: {idx.db_file}")
+
+
+@app.command()
+def get(code: str, report: str = "epraccur") -> None:
+    """
+    Get a single practice by organisation code (ODS code).
+    """
+    idx = PracticeIndex.auto_update(report=report)
+    p = idx.get(code)
+    if not p:
+        typer.echo(f"Practice not found: {code}", err=True)
+        raise typer.Exit(code=1)
+    typer.echo(json.dumps(p.raw or {}, indent=2))
+
+
+@app.command()
+def search(
+    name: str = typer.Option("", help="Search by practice name (substring match)."),
+    postcode: str = typer.Option(
+        "", help="Search by postcode (exact after normalization)."
+    ),
+    town: str = typer.Option("", help="Search by town (substring match)."),
+    status: str = typer.Option(
+        "", help="Filter by status (e.g. ACTIVE). Leave blank for any."
+    ),
+    limit: int = typer.Option(10, help="Max results."),
+    report: str = typer.Option("epraccur", help="ODS report code."),
+) -> None:
+    """
+    Search practices by name/postcode/town.
+    """
+    idx = PracticeIndex.auto_update(report=report)
+    res = idx.search(
+        name=name or None,
+        postcode=postcode or None,
+        town=town or None,
+        status=status or None,
+        limit=limit,
+    )
+    typer.echo(json.dumps([r.raw for r in res], indent=2))

uk_gp_practices-0.1.0/src/uk_gp_practices/db.py

@@ -0,0 +1,90 @@
+"""Database access and manipulation."""
+
+from __future__ import annotations
+
+import csv
+import sqlite3
+from pathlib import Path
+from typing import Iterable
+
+
+PRACTICES_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS practices (
+  organisation_code TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  name_norm TEXT,
+  postcode TEXT,
+  postcode_norm TEXT,
+  town TEXT,
+  status TEXT
+);
+"""
+
+INDEXES_SQL = [
+    "CREATE INDEX IF NOT EXISTS idx_practices_postcode_norm ON practices(postcode_norm);",
+    "CREATE INDEX IF NOT EXISTS idx_practices_name_norm ON practices(name_norm);",
+]
+
+
+def connect(db_path: Path) -> sqlite3.Connection:
+    con = sqlite3.connect(str(db_path))
+    con.execute("PRAGMA journal_mode=WAL;")
+    con.execute("PRAGMA synchronous=NORMAL;")
+    return con
+
+
+def init_db(con: sqlite3.Connection) -> None:
+    con.execute(PRACTICES_TABLE_SQL)
+    for stmt in INDEXES_SQL:
+        con.execute(stmt)
+    con.commit()
+
+
+def upsert_practices(
+    con: sqlite3.Connection, rows: Iterable[dict[str, str | None]]
+) -> None:
+    """
+    Upsert practice rows into sqlite.
+
+    Expected keys in each row:
+      organisation_code, name, name_norm, postcode, postcode_norm, town, status
+    """
+    con.executemany(
+        """
+        INSERT INTO practices (
+          organisation_code, name, name_norm, postcode, postcode_norm, town, status
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(organisation_code) DO UPDATE SET
+          name=excluded.name,
+          name_norm=excluded.name_norm,
+          postcode=excluded.postcode,
+          postcode_norm=excluded.postcode_norm,
+          town=excluded.town,
+          status=excluded.status
+        """,
+        [
+            (
+                r.get("organisation_code"),
+                r.get("name"),
+                r.get("name_norm"),
+                r.get("postcode"),
+                r.get("postcode_norm"),
+                r.get("town"),
+                r.get("status"),
+            )
+            for r in rows
+        ],
+    )
+    con.commit()
+
+
+def read_csv_dicts(path: Path) -> list[dict[str, str]]:
+    """Read a normal headered CSV into dict rows."""
+    with path.open("r", newline="", encoding="utf-8-sig") as f:
+        return list(csv.DictReader(f))
+
+
+def read_csv_rows(path: Path) -> list[list[str]]:
+    """Read a CSV into raw rows (positional), for headerless exports."""
+    with path.open("r", newline="", encoding="utf-8-sig") as f:
+        return list(csv.reader(f))

uk_gp_practices-0.1.0/src/uk_gp_practices/download.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import time
+
+import httpx
+
+
+# Prefer the www host. Some networks/DNS resolvers fail on the non-www host.
+DEFAULT_DSE_REPORT_URLS = [
+    "https://www.odsdatasearchandexport.nhs.uk/api/getReport",
+    "https://odsdatasearchandexport.nhs.uk/api/getReport",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class DownloadResult:
+    report: str
+    path: Path
+    bytes_written: int
+    url: str
+
+
+def download_report(
+    report: str,
+    dest: Path,
+    timeout: float = 60.0,
+    retries: int = 3,
+    backoff_seconds: float = 0.6,
+) -> DownloadResult:
+    """
+    Download an NHS ODS Data Search & Export predefined report as a CSV.
+
+    Override endpoint (single URL) with:
+        UK_GP_PRACTICES_DSE_URL
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    override = os.getenv("UK_GP_PRACTICES_DSE_URL")
+    candidate_urls = [override] if override else DEFAULT_DSE_REPORT_URLS
+
+    params = {"report": report}
+    last_exc: Exception | None = None
+
+    for base_url in candidate_urls:
+        if not base_url:
+            continue
+
+        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+            for attempt in range(1, retries + 2):  # retries + 1 initial attempt
+                try:
+                    resp = client.get(base_url, params=params)
+                    resp.raise_for_status()
+                    data = resp.content
+                    dest.write_bytes(data)
+                    return DownloadResult(
+                        report=report,
+                        path=dest,
+                        bytes_written=len(data),
+                        url=str(resp.url),
+                    )
+                except (
+                    httpx.ConnectError,
+                    httpx.ReadTimeout,
+                    httpx.RemoteProtocolError,
+                    httpx.NetworkError,
+                ) as exc:
+                    last_exc = exc
+                    time.sleep(backoff_seconds * (2 ** (attempt - 1)))
+                except httpx.HTTPStatusError as exc:
+                    # If we reached the server but got a real HTTP error, don't keep retrying other hosts forever.
+                    raise RuntimeError(
+                        f"Failed to download report '{report}' from {base_url}: {exc.response.status_code}"
+                    ) from exc
+
+    raise RuntimeError(
+        f"Failed to download report '{report}'. Tried: {', '.join([u for u in candidate_urls if u])}. "
+        f"Last error: {last_exc!r}"
+    )

uk_gp_practices-0.1.0/src/uk_gp_practices/index.py

@@ -0,0 +1,226 @@
+"""Main interface for querying GP practice data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+import sqlite3
+from typing import Any
+
+from .db import connect, init_db, read_csv_rows, upsert_practices
+from .download import download_report
+from .models import Practice
+from .normalise import normalize_name, normalize_postcode
+from .paths import csv_path, db_path as default_db_path
+
+
+DEFAULT_REPORT = "epraccur"
+DEFAULT_MAX_AGE = timedelta(days=1)
+
+_INTERNAL_COLUMNS = frozenset({"name_norm", "postcode_norm"})
+
+
+def _row_to_practice(row: sqlite3.Row) -> Practice:
+    raw = {k: row[k] for k in row.keys() if k not in _INTERNAL_COLUMNS}
+    return Practice(
+        organisation_code=row["organisation_code"],
+        name=row["name"],
+        postcode=row["postcode"],
+        town=row["town"],
+        status=row["status"],
+        raw=raw,
+    )
+
+
+@dataclass(slots=True)
+class PracticeIndex:
+    """
+    Main query interface for GP practice data.
+
+    Backed by:
+      - downloaded NHS ODS DSE CSV report(s)
+      - local SQLite database for fast lookups
+
+    Can be used as a context manager::
+
+        with PracticeIndex.auto_update() as idx:
+            practice = idx.get("A81001")
+    """
+
+    db_file: Path
+    _con_cache: sqlite3.Connection | None = field(default=None, repr=False)
+
+    @classmethod
+    def auto_update(
+        cls,
+        report: str = DEFAULT_REPORT,
+        max_age: timedelta = DEFAULT_MAX_AGE,
+    ) -> "PracticeIndex":
+        idx = cls(db_file=default_db_path())
+        idx._ensure_schema()
+        idx.update_if_needed(report=report, max_age=max_age)
+        return idx
+
+    def _ensure_schema(self) -> None:
+        con = self._con()
+        init_db(con)
+
+    def _con(self) -> sqlite3.Connection:
+        if self._con_cache is None:
+            con = connect(self.db_file)
+            con.row_factory = sqlite3.Row
+            self._con_cache = con
+        return self._con_cache
+
+    def close(self) -> None:
+        """Close the underlying database connection."""
+        if self._con_cache is not None:
+            self._con_cache.close()
+            self._con_cache = None
+
+    def __enter__(self) -> "PracticeIndex":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def update_if_needed(
+        self, report: str = DEFAULT_REPORT, max_age: timedelta = DEFAULT_MAX_AGE
+    ) -> bool:
+        """
+        Download + rebuild if the CSV is missing or older than max_age.
+        Returns True if an update happened.
+        """
+        csvf = csv_path(report)
+        if csvf.exists():
+            mtime = datetime.fromtimestamp(csvf.stat().st_mtime, tz=timezone.utc)
+            if datetime.now(tz=timezone.utc) - mtime < max_age:
+                return False
+
+        self.update(report=report)
+        return True
+
+    def update(self, report: str = DEFAULT_REPORT) -> None:
+        """
+        Download a report CSV and upsert into SQLite.
+        """
+        csvf = csv_path(report)
+        download_report(report=report, dest=csvf)
+        self.load_csv(csvf, report=report)
+
+    def get(self, organisation_code: str) -> Practice | None:
+        """
+        Fetch a single practice by its ODS organisation code.
+        """
+        code = organisation_code.strip()
+        con = self._con()
+        row = con.execute(
+            "SELECT * FROM practices WHERE organisation_code = ?",
+            (code,),
+        ).fetchone()
+        if not row:
+            return None
+        return _row_to_practice(row)
+
+    def search(
+        self,
+        name: str | None = None,
+        postcode: str | None = None,
+        town: str | None = None,
+        status: str | None = None,
+        limit: int = 25,
+    ) -> list[Practice]:
+        """
+        Search practices by name and/or postcode and/or town.
+
+        Note: this is simple LIKE matching for v0.1.
+        Fuzzy matching can come later as an optional dependency.
+        """
+        clauses: list[str] = []
+        params: list[object] = []
+
+        if status:
+            clauses.append("status = ?")
+            params.append(status)
+
+        if postcode:
+            pn = normalize_postcode(postcode)
+            clauses.append("postcode_norm = ?")
+            params.append(pn)
+
+        if town:
+            clauses.append("LOWER(town) LIKE ?")
+            params.append(f"%{town.strip().lower()}%")
+
+        if name:
+            nn = normalize_name(name)
+            clauses.append("name_norm LIKE ?")
+            params.append(f"%{nn}%")
+
+        where = (" WHERE " + " AND ".join(clauses)) if clauses else ""
+        sql = f"SELECT * FROM practices{where} LIMIT ?"
+        params.append(int(limit))
+
+        con = self._con()
+        rows = con.execute(sql, params).fetchall()
+        return [_row_to_practice(r) for r in rows]
+
+    def _prepare_rows_epraccur(self, rows: list[list[str]]) -> list[dict[str, Any]]:
+        """
+        Parse headerless epraccur CSV by positional columns.
+
+        Observed column mapping:
+        0 = organisation_code
+        1 = name
+        7 = town
+        9 = postcode
+        12 = status
+        """
+        prepared: list[dict[str, Any]] = []
+
+        for r in rows:
+            if not r or len(r) < 13:
+                continue
+
+            code = (r[0] or "").strip()
+            name = (r[1] or "").strip()
+            town = (r[7] or "").strip() or None
+            postcode = (r[9] or "").strip() or None
+            status = (r[12] or "").strip() or None
+
+            if not code or not name:
+                continue
+
+            prepared.append(
+                {
+                    "organisation_code": code,
+                    "name": name,
+                    "name_norm": normalize_name(name),
+                    "postcode": postcode,
+                    "postcode_norm": normalize_postcode(postcode),
+                    "town": town,
+                    "status": status,
+                }
+            )
+
+        return prepared
+
+    def load_csv(self, csv_file: str | Path, report: str = DEFAULT_REPORT) -> int:
+        """
+        Load a local CSV file into the SQLite database.
+
+        Returns the number of rows ingested.
+        """
+        csvf = Path(csv_file)
+        con = self._con()
+        init_db(con)
+
+        if report.lower() == "epraccur":
+            rows = read_csv_rows(csvf)
+            prepared = self._prepare_rows_epraccur(rows)
+        else:
+            raise ValueError(f"Unsupported report for local CSV load: {report}")
+
+        upsert_practices(con, prepared)
+        return len(prepared)

uk_gp_practices-0.1.0/src/uk_gp_practices/models.py

@@ -0,0 +1,24 @@
+"""Models representing GP practice data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Any
+
+
+@dataclass(frozen=True, slots=True)
+class Practice:
+    """
+    Represents a UK GP Practice (surgery) record.
+
+    This is based on NHS ODS Data Search & Export (DSE) CSV reports such as `epraccur`.
+    """
+
+    organisation_code: str
+    name: str
+
+    postcode: str | None
+    town: str | None
+    status: str | None
+
+    raw: Optional[dict[str, Any]] = None

uk_gp_practices-0.1.0/src/uk_gp_practices/normalise.py

@@ -0,0 +1,36 @@
+"""Tools for normalizing data for searching."""
+
+from __future__ import annotations
+
+import re
+
+
+_ws = re.compile(r"\s+")
+
+
+def normalize_postcode(value: str | None) -> str | None:
+    """
+    Normalize a UK postcode into a consistent format for searching.
+
+    Example:
+        " sw1a  1aa " -> "SW1A1AA"
+    """
+    if not value:
+        return None
+
+    v = _ws.sub("", value.strip().upper())
+    return v or None
+
+
+def normalize_name(value: str | None) -> str | None:
+    """
+    Normalize a name for case-insensitive searching.
+
+    Example:
+        "  Castle   Medical " -> "castle medical"
+    """
+    if not value:
+        return None
+
+    v = _ws.sub(" ", value.strip())
+    return v.lower() or None

uk_gp_practices-0.1.0/src/uk_gp_practices/paths.py

@@ -0,0 +1,32 @@
+"""Paths for storing cached data and reports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from platformdirs import user_cache_dir
+
+
+APP_NAME = "uk-gp-practices"
+
+
+def cache_dir() -> Path:
+    """
+    Returns the cache directory for the package.
+
+    Example (Linux):
+        ~/.cache/uk-gp-practices/
+    """
+    p = Path(user_cache_dir(APP_NAME))
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def db_path() -> Path:
+    """Default SQLite database path."""
+    return cache_dir() / "practices.sqlite3"
+
+
+def csv_path(report: str) -> Path:
+    """Path for storing a downloaded report CSV file."""
+    safe = report.replace("/", "_").replace("\\", "_").replace("..", "_")
+    return cache_dir() / f"{safe}.csv"

uk_gp_practices-0.1.0/tests/fixtures/epraccur_sample.csv

@@ -0,0 +1,5 @@
+A81001,THE DENSHAM SURGERY,Y63,QHM,HEALTH CENTRE,LAWSON STREET,,STOCKTON-ON-TEES,,TS18 1HU,19740401,,ACTIVE,B,16C,20200401,,01642 672351,,,,1,,16C,,RO76,
+A81002,QUEENS PARK MEDICAL CENTRE,Y63,QHM,FARRER STREET,,,STOCKTON ON TEES,,TS18 2AW,19740401,,ACTIVE,B,16C,20200401,,01642 618170,,,,1,,16C,,RO76,
+W96001,CASTLE MEDICAL PRACTICE,Y59,QHM,CASTLE STREET,,,SWANSEA,,SA1 1AA,19740401,,ACTIVE,B,16C,20200401,,01792 123456,,,,1,,16C,,RO76,
+W96002,RIVERSIDE FAMILY PRACTICE,Y59,QHM,RIVER ROAD,,,SWANSEA,,SA1 2BB,19740401,,INACTIVE,B,16C,20200401,,01792 654321,,,,1,,16C,,RO76,
+E12345,SOME HEALTH CENTRE,Y60,QHM,MAIN ROAD,,,LONDON,,SW1A 1AA,19740401,,ACTIVE,B,16C,20200401,,020 7946 0000,,,,1,,16C,,RO76,

uk_gp_practices-0.1.0/tests/test_cli.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+from uk_gp_practices.cli import app
+from uk_gp_practices.index import PracticeIndex
+
+runner = CliRunner()
+
+
+def _make_index(tmp_path: Path) -> PracticeIndex:
+    """Create a PracticeIndex with sample data loaded."""
+    db_file = tmp_path / "practices.sqlite3"
+    csv_file = Path(__file__).parent / "fixtures" / "epraccur_sample.csv"
+    idx = PracticeIndex(db_file=db_file)
+    idx.load_csv(csv_file)
+    return idx
+
+
+class TestGetCommand:
+    def test_found(self, tmp_path: Path):
+        idx = _make_index(tmp_path)
+        with patch.object(PracticeIndex, "auto_update", return_value=idx):
+            result = runner.invoke(app, ["get", "W96001"])
+        assert result.exit_code == 0
+        assert "CASTLE MEDICAL PRACTICE" in result.output
+
+    def test_not_found(self, tmp_path: Path):
+        idx = _make_index(tmp_path)
+        with patch.object(PracticeIndex, "auto_update", return_value=idx):
+            result = runner.invoke(app, ["get", "ZZZZZ"])
+        assert result.exit_code == 1
+        assert "Practice not found" in result.output
+
+
+class TestSearchCommand:
+    def test_search_by_name(self, tmp_path: Path):
+        idx = _make_index(tmp_path)
+        with patch.object(PracticeIndex, "auto_update", return_value=idx):
+            result = runner.invoke(app, ["search", "--name", "castle"])
+        assert result.exit_code == 0
+        assert "CASTLE MEDICAL PRACTICE" in result.output
+
+    def test_search_no_results(self, tmp_path: Path):
+        idx = _make_index(tmp_path)
+        with patch.object(PracticeIndex, "auto_update", return_value=idx):
+            result = runner.invoke(app, ["search", "--name", "nonexistent999"])
+        assert result.exit_code == 0
+        assert result.output.strip() == "[]"

uk_gp_practices-0.1.0/tests/test_download.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import httpx
+import pytest
+
+from uk_gp_practices.download import download_report
+
+
+def _mock_response(content: bytes = b"code,name\nA1,Test", status_code: int = 200):
+    resp = MagicMock(spec=httpx.Response)
+    resp.content = content
+    resp.status_code = status_code
+    resp.url = "https://example.com/api/getReport?report=epraccur"
+    resp.raise_for_status = MagicMock()
+    if status_code >= 400:
+        resp.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "error", request=MagicMock(), response=resp
+        )
+    return resp
+
+
+class TestDownloadReport:
+    def test_success(self, tmp_path: Path):
+        dest = tmp_path / "report.csv"
+        mock_resp = _mock_response()
+
+        with patch("uk_gp_practices.download.httpx.Client") as mock_client_cls:
+            client = MagicMock()
+            client.get.return_value = mock_resp
+            mock_client_cls.return_value.__enter__ = MagicMock(return_value=client)
+            mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
+
+            result = download_report(report="epraccur", dest=dest)
+
+        assert result.report == "epraccur"
+        assert result.path == dest
+        assert result.bytes_written > 0
+        assert dest.exists()
+
+    def test_http_error_raises(self, tmp_path: Path):
+        dest = tmp_path / "report.csv"
+        mock_resp = _mock_response(status_code=500)
+
+        with patch("uk_gp_practices.download.httpx.Client") as mock_client_cls:
+            client = MagicMock()
+            client.get.return_value = mock_resp
+            mock_client_cls.return_value.__enter__ = MagicMock(return_value=client)
+            mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
+
+            with pytest.raises(RuntimeError, match="Failed to download"):
+                download_report(report="epraccur", dest=dest)
+
+    def test_all_retries_exhausted(self, tmp_path: Path):
+        dest = tmp_path / "report.csv"
+
+        with patch("uk_gp_practices.download.httpx.Client") as mock_client_cls:
+            client = MagicMock()
+            client.get.side_effect = httpx.ConnectError("refused")
+            mock_client_cls.return_value.__enter__ = MagicMock(return_value=client)
+            mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
+
+            with patch("uk_gp_practices.download.time.sleep"):
+                with pytest.raises(RuntimeError, match="Failed to download"):
+                    download_report(report="epraccur", dest=dest, retries=1, backoff_seconds=0)
+
+    def test_env_override(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        dest = tmp_path / "report.csv"
+        monkeypatch.setenv("UK_GP_PRACTICES_DSE_URL", "https://custom.example.com/api")
+        mock_resp = _mock_response()
+
+        with patch("uk_gp_practices.download.httpx.Client") as mock_client_cls:
+            client = MagicMock()
+            client.get.return_value = mock_resp
+            mock_client_cls.return_value.__enter__ = MagicMock(return_value=client)
+            mock_client_cls.return_value.__exit__ = MagicMock(return_value=False)
+
+            result = download_report(report="epraccur", dest=dest)
+
+        client.get.assert_called_once_with("https://custom.example.com/api", params={"report": "epraccur"})
+        assert result.bytes_written > 0

uk_gp_practices-0.1.0/tests/test_epraccur_ingest.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from uk_gp_practices.index import PracticeIndex
+
+
+def test_epraccur_ingest_and_search(tmp_path: Path) -> None:
+    db_file = tmp_path / "practices.sqlite3"
+    csv_file = Path(__file__).parent / "fixtures" / "epraccur_sample.csv"
+
+    idx = PracticeIndex(db_file=db_file)
+    idx.load_csv(csv_file)  # this must ingest the headerless CSV correctly
+
+    # get() by code
+    p = idx.get("W96001")
+    assert p is not None
+    assert p.name == "CASTLE MEDICAL PRACTICE"
+    if p.town:
+        assert p.town.lower().startswith("swansea")
+    if p.postcode:
+        assert p.postcode.replace(" ", "") == "SA11AA"
+
+    # search() by name
+    res = idx.search(name="castle", status=None, limit=10)
+    assert any(r.organisation_code == "W96001" for r in res)
+
+    # status filtering should work when requested
+    active = idx.search(name="practice", status="ACTIVE", limit=50)
+    assert all((r.status or "").upper() == "ACTIVE" for r in active)

uk_gp_practices-0.1.0/tests/test_normalise.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+
+from uk_gp_practices.normalise import normalize_name, normalize_postcode
+
+
+class TestNormalizePostcode:
+    def test_basic(self):
+        assert normalize_postcode("SW1A 1AA") == "SW1A1AA"
+
+    def test_extra_whitespace(self):
+        assert normalize_postcode("  sw1a  1aa ") == "SW1A1AA"
+
+    def test_lowercase(self):
+        assert normalize_postcode("sw1a1aa") == "SW1A1AA"
+
+    def test_none(self):
+        assert normalize_postcode(None) is None
+
+    def test_empty_string(self):
+        assert normalize_postcode("") is None
+
+    def test_whitespace_only(self):
+        assert normalize_postcode("   ") is None
+
+
+class TestNormalizeName:
+    def test_basic(self):
+        assert normalize_name("Castle Medical") == "castle medical"
+
+    def test_extra_whitespace(self):
+        assert normalize_name("  Castle   Medical  ") == "castle medical"
+
+    def test_none(self):
+        assert normalize_name(None) is None
+
+    def test_empty_string(self):
+        assert normalize_name("") is None
+
+    def test_whitespace_only(self):
+        assert normalize_name("   ") is None
+
+    def test_already_lowercase(self):
+        assert normalize_name("castle medical") == "castle medical"

uk_gp_practices-0.1.0/tests/test_paths.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from uk_gp_practices.paths import csv_path
+
+
+class TestCsvPathSanitization:
+    def test_normal_report(self):
+        p = csv_path("epraccur")
+        assert p.name == "epraccur.csv"
+
+    def test_path_traversal_slashes(self):
+        p = csv_path("../../etc/passwd")
+        assert "/" not in p.name.replace(".csv", "")
+        assert "\\" not in p.name.replace(".csv", "")
+
+    def test_dotdot(self):
+        p = csv_path("../secret")
+        assert ".." not in p.name