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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ng-postcode
-Version: 0.1.0
+Version: 0.2.0
 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ng-postcode"
-version = "0.1.0"
+version = "0.2.0"
 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.0}/src/ng_postcode/api.py

@@ -74,12 +74,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,6 +122,15 @@ 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]:
@@ -126,7 +140,12 @@ def lookup(code: Postcode, level: int = 1) -> Request[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)
 
 
@@ -136,10 +155,10 @@ def reverse(at: Coordinate, max_distance_m: float | None = None) -> Request[Reve
     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."""
+    return Request("/v1/search/nearby", _around(at, "radius", radius_m), _nearby)
 
 
 def decode(request: Request[T], status: int, body: str) -> T | ApiError:
@@ -191,8 +210,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 +244,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 +254,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 +286,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.0}/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:

ng_postcode-0.2.0/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)