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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode
-Version: 0.1.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.1.0 → ng_postcode-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode"
-version = "0.1.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.1.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
@@ -74,12 +75,17 @@ class Lookup:
     """Level 4. Undocumented, so left as raw JSON."""
     point_geometry: Any
     """Level 5. Undocumented, so left as raw JSON."""
+    status: str | None = None
+    """`valid`, `not_found`, or `invalid` for a malformed code. Sent at every level."""
+    verified: bool | None = None
 
 
 @dataclass(frozen=True, slots=True)
 class Suggestion:
     code: str
-    label: str
+    """The value of the segment being completed, such as `A03`, not a full prefix."""
+    label: str | None
+    """Documented by NIPOST but not sent by the live API as of October 2026."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -117,29 +123,54 @@ class Reverse:
     """Set when nothing is in range."""
     radius_m: float | None
     """The radius the API actually applied."""
+    depth: str | None = None
+    """How deep the match goes, such as `unit`."""
+
+
+@dataclass(frozen=True, slots=True)
+class NearbyUnit:
+    postcode: str
+    display: str
+    distance_m: float | None
 
 
 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)
 
 
 def autocomplete(partial: str) -> Request[Autocomplete]:
-    """Suggest completions for a partial postcode such as `EK 01 A`."""
+    """Suggest completions for a partial postcode such as `EK 01 A`.
+
+    Raises `ValueError` for an empty `partial`: the live API never answers one.
+    """
+    if not partial.strip():
+        raise ValueError("partial must not be empty")
     return Request("/v1/search/autocomplete", (("q", partial),), _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[Any]:
-    """List buildings around a point, within 300 m unless `radius_m` says otherwise.
-    The API does not document the response, so it stays raw JSON."""
-    return Request("/v1/search/nearby", _around(at, "radius", radius_m), _raw)
+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.
+
+    Raises `ValueError` for a coordinate or radius that is not a finite number.
+    """
+    return Request("/v1/search/nearby", _around(at, "radius", radius_m), _nearby)
 
 
 def decode(request: Request[T], status: int, body: str) -> T | ApiError:
@@ -150,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")
 
@@ -165,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)
 
 
@@ -191,8 +228,18 @@ def _float(value: Any) -> float | None:
     return float(value) if is_number else None
 
 
-def _raw(data: Any) -> Any:
-    return data
+def _nearby(data: Any) -> tuple[NearbyUnit, ...] | None:
+    if not isinstance(data, list):
+        return None
+    return tuple(
+        NearbyUnit(
+            postcode=_text(item, "postcode") or "",
+            display=_text(item, "display") or "",
+            distance_m=_number(item, "distance_m"),
+        )
+        for item in data
+        if isinstance(item, dict)
+    )
 
 
 def _lookup(data: Any) -> Lookup | None:
@@ -215,6 +262,8 @@ def _lookup(data: Any) -> Lookup | None:
         building_use_status=_text(data, "building_use_status"),
         other_building_info=data.get("other_building_info"),
         point_geometry=data.get("point_geometry"),
+        status=_text(data, "status"),
+        verified=data["verified"] if isinstance(data.get("verified"), bool) else None,
     )
 
 
@@ -223,7 +272,7 @@ def _autocomplete(data: Any) -> Autocomplete | None:
         return None
     items = data.get("suggestions")
     suggestions = tuple(
-        Suggestion(code=_text(item, "code") or "", label=_text(item, "label") or "")
+        Suggestion(code=_text(item, "code") or "", label=_text(item, "label"))
         for item in (items if isinstance(items, list) else [])
         if isinstance(item, dict)
     )
@@ -255,6 +304,7 @@ def _reverse(data: Any) -> Reverse | None:
         state=_text(data, "state"),
         message=_text(data, "message"),
         radius_m=_number(data, "radius_m"),
+        depth=_text(data, "depth"),
     )
 
 

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

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import json
 
+import pytest
+
 from ng_postcode import Postcode, Segment, parse
 from ng_postcode.api import (
     AdministrativeAddress,
@@ -72,20 +74,22 @@ def test_fields_above_the_granted_level_are_none() -> None:
     assert (found.administrative_address, found.recent_house_address) == (None, None)
 
 
-def test_decodes_autocomplete_reverse_and_nearby() -> None:
-    data = {"segment": "lga", "suggestions": [{"code": "EK-01", "label": "ADO EKITI"}]}
+def test_decodes_documented_labels_and_echoed_coordinates() -> None:
+    data = {"segment": "lga", "suggestions": [{"code": "01", "label": "ADO EKITI"}]}
     found = decode(autocomplete("EK"), 200, body(data))
     assert not isinstance(found, ApiError)
     assert found.segment is Segment.LGA
-    assert found.suggestions[0].code == "EK-01"
+    assert (found.suggestions[0].code, found.suggestions[0].label) == ("01", "ADO EKITI")
 
     miss = {"found": False, "coordinate": [5.22, 7.62], "message": "none", "radius_m": 25}
     result = decode(reverse(HERE), 200, body(miss))
     assert not isinstance(result, ApiError)
-    assert (result.found, result.unit, result.radius_m) == (False, None, 25.0)
     assert result.coordinate == HERE
 
-    assert decode(nearby(HERE), 200, body({"results": []})) == {"results": []}
+
+def test_an_empty_autocomplete_is_refused_before_it_hangs_the_api() -> None:
+    with pytest.raises(ValueError, match="must not be empty"):
+        autocomplete("  ")
 
 
 def test_error_envelopes_and_bad_bodies_become_values() -> None:
@@ -97,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_live_responses.py

@@ -0,0 +1,116 @@
+"""Decodes the response bodies captured from the live API in `spec/responses.json`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, TypeVar
+
+import pytest
+
+from ng_postcode import Postcode, Segment
+from ng_postcode.api import (
+    ApiError,
+    Coordinate,
+    NearbyUnit,
+    Request,
+    autocomplete,
+    decode,
+    lookup,
+    nearby,
+    reverse,
+)
+
+T = TypeVar("T")
+
+RESPONSES = Path(__file__).resolve().parents[2] / "spec" / "responses.json"
+LIVE: dict[str, Any] = (
+    json.loads(RESPONSES.read_text(encoding="utf-8")) if RESPONSES.exists() else {}
+)
+CODE = Postcode("FC03B06AG12")
+HERE = Coordinate(lat=7.6211, lng=5.2214)
+
+pytestmark = pytest.mark.skipif(
+    not LIVE, reason="spec/responses.json lives in the repository, not the sdist"
+)
+
+
+def live(request: Request[T], name: str) -> T | ApiError:
+    captured = LIVE[name]
+    return decode(request, captured["status"], json.dumps(captured["body"]))
+
+
+def test_lookup_statuses() -> None:
+    valid = live(lookup(CODE), "lookup_valid")
+    assert not isinstance(valid, ApiError)
+    assert (valid.valid, valid.status, valid.verified) == (True, "valid", False)
+    assert valid.administrative_address is None
+
+    missing = live(lookup(CODE), "lookup_not_found")
+    assert not isinstance(missing, ApiError)
+    assert (missing.valid, missing.status) == (False, "not_found")
+
+    malformed = live(lookup(CODE), "lookup_invalid")
+    assert not isinstance(malformed, ApiError)
+    assert (malformed.valid, malformed.status) == (False, "invalid")
+
+
+def test_autocomplete_sends_segment_values_without_labels() -> None:
+    states = live(autocomplete("E"), "autocomplete_state")
+    assert not isinstance(states, ApiError)
+    assert states.segment is Segment.STATE
+    assert [(s.code, s.label) for s in states.suggestions] == [
+        ("EB", None),
+        ("ED", None),
+        ("EK", None),
+        ("EN", None),
+    ]
+    units = live(autocomplete("EK 01 A29 KR 3"), "autocomplete_unit_empty")
+    assert not isinstance(units, ApiError)
+    assert (units.segment, units.suggestions) == (Segment.UNIT, ())
+
+
+def test_reverse() -> None:
+    found = live(reverse(HERE), "reverse_found")
+    assert not isinstance(found, ApiError)
+    assert found.unit is not None
+    assert (found.unit.postcode, found.unit.distance_m, found.unit.confidence) == (
+        "EK-01-A29-KR-36",
+        15.7,
+        "high",
+    )
+    assert (found.area, found.district, found.state, found.depth) == (
+        "EK-01-A29-KR",
+        "EK-01-A29",
+        "EK",
+        "unit",
+    )
+    assert found.coordinate == HERE
+    assert (found.unit.address, found.radius_m) == (None, 25.0)
+
+    nothing = live(reverse(HERE), "reverse_not_found")
+    assert not isinstance(nothing, ApiError)
+    assert (nothing.found, nothing.unit) == (False, None)
+    assert nothing.message == "no postcode within range of this location"
+
+
+def test_nearby_is_a_list_nearest_first() -> None:
+    units = live(nearby(HERE), "nearby_found")
+    assert not isinstance(units, ApiError)
+    assert units[0] == NearbyUnit("EK-01-A29-KR-36", "EK 01 A29 KR 36", 15.7)
+    assert [u.distance_m for u in units] == [15.7, 18.3, 31.0]
+    assert live(nearby(HERE), "nearby_empty") == ()
+
+
+@pytest.mark.parametrize(
+    ("name", "code"),
+    [
+        ("lookup_level_not_granted", "level_not_granted"),
+        ("reverse_bad_request", "bad_request"),
+        ("invalid_api_key", "invalid_api_key"),
+    ],
+)
+def test_errors(name: str, code: str) -> None:
+    error = live(lookup(CODE), name)
+    assert isinstance(error, ApiError)
+    assert (error.status, error.code) == (LIVE[name]["status"], code)

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"))