ng-postcode 0.2.0__tar.gz → 0.2.1__tar.gz

{ng_postcode-0.2.0 → ng_postcode-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode
-Version: 0.2.0
+Version: 0.2.1
 Summary: Parse, validate and format Nigeria's NIPOST digital postcode (NDAPS) offline, plus a client for the postcode.gov.ng API.
 Project-URL: Repository, https://github.com/Adeniyikayodee/ng-postcode
 Project-URL: Issues, https://github.com/Adeniyikayodee/ng-postcode/issues

{ng_postcode-0.2.0 → ng_postcode-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode"
-version = "0.2.0"
+version = "0.2.1"
 description = "Parse, validate and format Nigeria's NIPOST digital postcode (NDAPS) offline, plus a client for the postcode.gov.ng API."
 readme = "README.md"
 requires-python = ">=3.10"

{ng_postcode-0.2.0 → ng_postcode-0.2.1}/src/ng_postcode/api.py

@@ -8,6 +8,7 @@ offline.
 from __future__ import annotations
 
 import json
+import math
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from typing import Any, Generic, TypeVar
@@ -135,7 +136,12 @@ class NearbyUnit:
 
 def lookup(code: Postcode, level: int = 1) -> Request[Lookup]:
     """Resolve a postcode. Levels are cumulative from 1 (validity only) to 5, and
-    the API caps the answer at the level granted to the key."""
+    the API caps the answer at the level granted to the key.
+
+    Raises `ValueError` for a level outside 1 to 5.
+    """
+    if level not in range(1, 6):
+        raise ValueError(f"level must be 1 to 5, got {level!r}")
     return Request("/v1/lookup", (("code", str(code)), ("level", str(level))), _lookup)
 
 
@@ -151,13 +157,19 @@ def autocomplete(partial: str) -> Request[Autocomplete]:
 
 def reverse(at: Coordinate, max_distance_m: float | None = None) -> Request[Reverse]:
     """Find the postcode of the nearest building, within 25 m unless `max_distance_m`
-    says otherwise. The API clamps it to 250 m."""
+    says otherwise. The API clamps it to 250 m.
+
+    Raises `ValueError` for a coordinate or distance that is not a finite number.
+    """
     return Request("/v1/search/reverse", _around(at, "max_distance_m", max_distance_m), _reverse)
 
 
 def nearby(at: Coordinate, radius_m: float | None = None) -> Request[tuple[NearbyUnit, ...]]:
     """List buildings around a point, nearest first, within 300 m unless `radius_m`
-    says otherwise. Empty when nothing is in range."""
+    says otherwise. Empty when nothing is in range.
+
+    Raises `ValueError` for a coordinate or radius that is not a finite number.
+    """
     return Request("/v1/search/nearby", _around(at, "radius", radius_m), _nearby)
 
 
@@ -169,10 +181,14 @@ def decode(request: Request[T], status: int, body: str) -> T | ApiError:
         return _malformed(status, f"not JSON: {error}")
     if not isinstance(envelope, dict):
         return _malformed(status, "expected a JSON object")
-    failure = _object(envelope, "error")
-    if failure is not None:
+    failure = envelope.get("error")
+    if isinstance(failure, dict):
         code = _text(failure, "code") or "unknown_error"
         return ApiError(status, code, _text(failure, "message") or "")
+    if isinstance(failure, str):
+        return ApiError(status, "unknown_error", failure)
+    if not 200 <= status < 300:
+        return _malformed(status, "an error status without an error")
     data = request.read(envelope.get("data"))
     return data if data is not None else _malformed(status, "unexpected data")
 
@@ -184,6 +200,8 @@ def _around(at: Coordinate, key: str, metres: float | None) -> Params:
 
 def _number_text(value: float) -> str:
     number = float(value)
+    if not math.isfinite(number):
+        raise ValueError(f"expected a finite number, got {value!r}")
     return str(int(number)) if number.is_integer() else repr(number)
 
 

{ng_postcode-0.2.0 → ng_postcode-0.2.1}/tests/test_api.py

@@ -101,3 +101,15 @@ def test_error_envelopes_and_bad_bodies_become_values() -> None:
         error = decode(request, status, text)
         assert isinstance(error, ApiError)
         assert (error.status, error.code) == (status, "malformed_response")
+
+
+def test_rejects_requests_the_api_cannot_answer() -> None:
+    code = Postcode("EK01A03FK01")
+    for level in (0, 6):
+        with pytest.raises(ValueError, match="level must be 1 to 5"):
+            lookup(code, level)
+    for bad in (float("nan"), float("inf")):
+        with pytest.raises(ValueError, match="finite"):
+            reverse(Coordinate(lat=bad, lng=5.2))
+        with pytest.raises(ValueError, match="finite"):
+            nearby(Coordinate(lat=7.6, lng=5.2), bad)

ng_postcode-0.2.1/tests/test_tolerance.py

@@ -0,0 +1,50 @@
+"""Runs the shared cases in `spec/tolerance.json`: bodies the live API may one day send."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from ng_postcode import Postcode
+from ng_postcode.api import (
+    ApiError,
+    Coordinate,
+    Request,
+    autocomplete,
+    decode,
+    lookup,
+    nearby,
+    reverse,
+)
+
+SPEC = Path(__file__).resolve().parents[2] / "spec" / "tolerance.json"
+CASES: list[dict[str, Any]] = (
+    json.loads(SPEC.read_text(encoding="utf-8"))["cases"] if SPEC.exists() else []
+)
+HERE = Coordinate(lat=7.6211, lng=5.2214)
+REQUESTS: dict[str, Request[Any]] = {
+    "lookup": lookup(Postcode("FC03B06AG12"), 1),
+    "autocomplete": autocomplete("E"),
+    "reverse": reverse(HERE),
+    "nearby": nearby(HERE),
+}
+
+pytestmark = pytest.mark.skipif(
+    not CASES, reason="spec/tolerance.json lives in the repository, not the sdist"
+)
+
+
+@pytest.mark.parametrize("case", CASES, ids=[case["name"] for case in CASES])
+def test_reaches_the_shared_outcome(case: dict[str, Any]) -> None:
+    body = case["text"] if "text" in case else json.dumps(case["body"])
+    decoded = decode(REQUESTS[case["request"]], case["status"], body)
+    if not isinstance(decoded, ApiError):
+        found: tuple[str, str | None] = ("ok", None)
+    elif decoded.code == "malformed_response":
+        found = ("malformed", None)
+    else:
+        found = ("rejected", decoded.code)
+    assert found == (case["outcome"], case.get("code"))