ng-postcode 0.1.0__py3-none-any.whl

ng_postcode/__init__.py

@@ -0,0 +1,44 @@
+"""Nigeria's National Digital Alphanumeric Postcode (NDAPS), the building-level
+postcode issued by NIPOST.
+
+Expected failures come back as values, never exceptions:
+
+>>> from ng_postcode import Postcode, Segment, parse
+>>> code = parse("ek 01 a03 fk 01")
+>>> isinstance(code, Postcode)
+True
+>>> str(code), code.compact, code.spaced
+('EK-01-A03-FK-01', 'EK01A03FK01', 'EK 01 A03 FK 01')
+>>> code.prefix(Segment.AREA)
+'EK-01-A03-FK'
+>>> str(parse("EK-01-A03"))
+'expected 11 letters and digits, found 7'
+"""
+
+from ._postcode import (
+    Corrected,
+    InvalidCharacter,
+    InvalidSegment,
+    ParseError,
+    Postcode,
+    Segment,
+    WrongLength,
+    from_segments,
+    is_valid,
+    parse,
+    parse_lenient,
+)
+
+__all__ = [
+    "Corrected",
+    "InvalidCharacter",
+    "InvalidSegment",
+    "ParseError",
+    "Postcode",
+    "Segment",
+    "WrongLength",
+    "from_segments",
+    "is_valid",
+    "parse",
+    "parse_lenient",
+]

ng_postcode/_postcode.py

@@ -0,0 +1,235 @@
+"""Offline parsing, validation and formatting. Pure: no I/O, no mutation."""
+
+from __future__ import annotations
+
+import string
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeAlias
+
+LENGTH = 11
+
+_LETTERS = frozenset(string.ascii_uppercase)
+_DIGITS = frozenset(string.digits)
+_SEPARATORS = frozenset(" -")
+_TO_LETTER = str.maketrans("0158", "OISB")
+_TO_DIGIT = str.maketrans("OILSB", "01158")
+
+
+class Segment(Enum):
+    """The five segments of a postcode, `AA-99-H77-BB-55`, widest first."""
+
+    STATE = "state"
+    LGA = "lga"
+    DISTRICT = "district"
+    AREA = "area"
+    UNIT = "unit"
+
+
+_SPANS = {
+    Segment.STATE: range(0, 2),
+    Segment.LGA: range(2, 4),
+    Segment.DISTRICT: range(4, 7),
+    Segment.AREA: range(7, 9),
+    Segment.UNIT: range(9, 11),
+}
+_ALPHA = frozenset({Segment.STATE, Segment.AREA})
+_NUMERIC = frozenset({Segment.LGA, Segment.UNIT})
+
+
+@dataclass(frozen=True, slots=True)
+class WrongLength:
+    """The input did not hold exactly 11 letters and digits."""
+
+    found: int
+
+    def __str__(self) -> str:
+        return f"expected {LENGTH} letters and digits, found {self.found}"
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidCharacter:
+    """The input held something other than letters, digits, spaces and hyphens."""
+
+    char: str
+    index: int
+
+    def __str__(self) -> str:
+        return f"invalid character {self.char!r} at index {self.index}"
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidSegment:
+    """A segment has the wrong shape, such as digits in the state or `00` as a unit."""
+
+    segment: Segment
+
+    def __str__(self) -> str:
+        return f"invalid {self.segment.value} segment"
+
+
+ParseError: TypeAlias = WrongLength | InvalidCharacter | InvalidSegment
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class Postcode:
+    """A well-formed postcode, held in its compact upper-case form.
+
+    Well formed is not the same as assigned: only the NIPOST API knows whether
+    a code belongs to a real building. Build one with `parse`; constructing it
+    from an unchecked string raises `ValueError`, as that is a programming error.
+    """
+
+    compact: str
+
+    def __post_init__(self) -> None:
+        if _collect(self.compact) != self.compact or _validate(self.compact) is not None:
+            raise ValueError(f"not a compact upper-case postcode: {self.compact!r}")
+
+    def __str__(self) -> str:
+        return self.prefix(Segment.UNIT)
+
+    def __repr__(self) -> str:
+        return f"Postcode('{self}')"
+
+    @property
+    def spaced(self) -> str:
+        """The form shown to people, `EK 01 A03 FK 01`."""
+        return " ".join(self.segment(s) for s in Segment)
+
+    @property
+    def state(self) -> str:
+        return self.segment(Segment.STATE)
+
+    @property
+    def lga(self) -> str:
+        return self.segment(Segment.LGA)
+
+    @property
+    def district(self) -> str:
+        return self.segment(Segment.DISTRICT)
+
+    @property
+    def area(self) -> str:
+        return self.segment(Segment.AREA)
+
+    @property
+    def unit(self) -> str:
+        return self.segment(Segment.UNIT)
+
+    def segment(self, segment: Segment) -> str:
+        return _part(self.compact, segment)
+
+    def prefix(self, through: Segment) -> str:
+        """The hyphenated code down to `through`: `prefix(Segment.AREA)` is `EK-01-A03-FK`."""
+        order = list(Segment)
+        return "-".join(self.segment(s) for s in order[: order.index(through) + 1])
+
+
+@dataclass(frozen=True, slots=True)
+class Corrected:
+    """The result of `parse_lenient`."""
+
+    postcode: Postcode
+    corrections: int
+    """How many characters were swapped for their look-alike."""
+
+
+def parse(text: str) -> Postcode | ParseError:
+    """Parse a hyphenated, spaced or compact code in either case.
+
+    >>> parse("ek 01 a03 fk 01")
+    Postcode('EK-01-A03-FK-01')
+    >>> parse("EK-00-A03-FK-01")
+    InvalidSegment(segment=<Segment.LGA: 'lga'>)
+    """
+    compact = _collect(text)
+    if not isinstance(compact, str):
+        return compact
+    error = _validate(compact)
+    return error if error is not None else Postcode(compact)
+
+
+def parse_lenient(text: str) -> Corrected | ParseError:
+    """Parse after swapping look-alikes that cannot occur where they stand: `0 1 5 8`
+    become `O I S B` where a letter is required, and `O I L S B` become `0 1 1 5 8`
+    where a digit is. The district allows both, so it is never rewritten.
+
+    The result is well formed but may not be the code the user meant, so confirm
+    it with them when `corrections` is not zero.
+
+    >>> parse_lenient("EK-O1-A03-FK-0I")
+    Corrected(postcode=Postcode('EK-01-A03-FK-01'), corrections=2)
+    """
+    raw = _collect(text)
+    if not isinstance(raw, str):
+        return raw
+    fixed = "".join(_unconfuse(s, _part(raw, s)) for s in Segment)
+    error = _validate(fixed)
+    if error is not None:
+        return error
+    return Corrected(Postcode(fixed), sum(a != b for a, b in zip(raw, fixed, strict=True)))
+
+
+def from_segments(
+    state: str, lga: str, district: str, area: str, unit: str
+) -> Postcode | ParseError:
+    """Build a code from its segments, zero-filling the LGA and unit.
+
+    >>> from_segments("ek", "1", "a03", "fk", "1")
+    Postcode('EK-01-A03-FK-01')
+    """
+    values = (state, lga, district, area, unit)
+    padded = [_padded(s, v) for s, v in zip(Segment, values, strict=True)]
+    error = next((p for p in padded if isinstance(p, InvalidSegment)), None)
+    if error is not None:
+        return error
+    return parse("".join(p for p in padded if isinstance(p, str)))
+
+
+def is_valid(text: str) -> bool:
+    """Whether `text` is a well-formed postcode."""
+    return isinstance(parse(text), Postcode)
+
+
+def _collect(text: str) -> str | ParseError:
+    kept = [(index, char) for index, char in enumerate(text) if char not in _SEPARATORS]
+    invalid = next(((i, c) for i, c in kept if not (c.isascii() and c.isalnum())), None)
+    if invalid is not None:
+        return InvalidCharacter(char=invalid[1], index=invalid[0])
+    if len(kept) != LENGTH:
+        return WrongLength(found=len(kept))
+    return "".join(char for _, char in kept).upper()
+
+
+def _part(compact: str, segment: Segment) -> str:
+    span = _SPANS[segment]
+    return compact[span.start : span.stop]
+
+
+def _validate(compact: str) -> InvalidSegment | None:
+    return next((InvalidSegment(s) for s in Segment if not _accepts(s, _part(compact, s))), None)
+
+
+def _accepts(segment: Segment, text: str) -> bool:
+    chars = set(text)
+    if segment in _ALPHA:
+        return chars <= _LETTERS
+    if segment in _NUMERIC:
+        return chars <= _DIGITS and text != "00"
+    return chars <= _LETTERS | _DIGITS
+
+
+def _unconfuse(segment: Segment, text: str) -> str:
+    if segment in _ALPHA:
+        return text.translate(_TO_LETTER)
+    if segment in _NUMERIC:
+        return text.translate(_TO_DIGIT)
+    return text
+
+
+def _padded(segment: Segment, value: str) -> str | InvalidSegment:
+    text, width = value.strip(), len(_SPANS[segment])
+    shortest = 1 if segment in _NUMERIC else width
+    fits = shortest <= len(text) <= width and text.isascii() and text.isalnum()
+    return text.rjust(width, "0") if fits else InvalidSegment(segment)

ng_postcode/api.py

@@ -0,0 +1,266 @@
+"""The NIPOST Postcode API as plain data: requests to send and responses to decode.
+
+Nothing here performs I/O, so it works with any HTTP client, sync or async.
+Assembly and disassembly are not modelled: `parse` and `from_segments` do both
+offline.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+from ._postcode import Postcode, Segment
+
+T = TypeVar("T")
+
+BASE_URL = "https://api.postcode.gov.ng"
+
+Params = tuple[tuple[str, str], ...]
+
+
+@dataclass(frozen=True)
+class Request(Generic[T]):
+    """A GET request whose successful response decodes to `T`."""
+
+    path: str
+    params: Params
+    read: Callable[[Any], T | None] = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True, slots=True)
+class Coordinate:
+    lat: float
+    lng: float
+
+
+@dataclass(frozen=True, slots=True)
+class ApiError:
+    """The API refused the request, with `code` taken from its error envelope
+    (`auth_required`, `insufficient_credits`, ...), or its answer was not the
+    documented envelope, with `code` set to `malformed_response`."""
+
+    status: int
+    code: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.code} ({self.status}): {self.message}"
+
+
+@dataclass(frozen=True, slots=True)
+class AdministrativeAddress:
+    state_name: str | None
+    lga_name: str | None
+    locality_name: str | None
+    zone: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Lookup:
+    """Fields above the level granted to the key are `None`."""
+
+    postcode: str
+    valid: bool
+    administrative_address: AdministrativeAddress | None
+    """Level 2."""
+    recent_house_address: str | None
+    """Level 2."""
+    building_use_status: str | None
+    """Level 3."""
+    other_building_info: Any
+    """Level 4. Undocumented, so left as raw JSON."""
+    point_geometry: Any
+    """Level 5. Undocumented, so left as raw JSON."""
+
+
+@dataclass(frozen=True, slots=True)
+class Suggestion:
+    code: str
+    label: str
+
+
+@dataclass(frozen=True, slots=True)
+class Autocomplete:
+    segment: Segment | None
+    """The segment the suggestions complete."""
+    suggestions: tuple[Suggestion, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class NearestUnit:
+    postcode: str
+    display: str
+    distance_m: float | None
+    confidence: str | None
+    """`high`, `medium` or `low`, graded by distance."""
+    state_name: str | None
+    lga_name: str | None
+    locality_name: str | None
+    address: str | None
+    """Recent house address. This and the names above need level 2."""
+
+
+@dataclass(frozen=True, slots=True)
+class Reverse:
+    found: bool
+    coordinate: Coordinate | None
+    """The queried point, echoed back."""
+    unit: NearestUnit | None
+    """The nearest building, absent when nothing is in range."""
+    area: str | None
+    district: str | None
+    state: str | None
+    message: str | None
+    """Set when nothing is in range."""
+    radius_m: float | None
+    """The radius the API actually applied."""
+
+
+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."""
+    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`."""
+    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."""
+    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 decode(request: Request[T], status: int, body: str) -> T | ApiError:
+    """Decode the response to `request` from its status and body."""
+    try:
+        envelope = json.loads(body)
+    except ValueError as error:
+        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:
+        code = _text(failure, "code") or "unknown_error"
+        return ApiError(status, code, _text(failure, "message") or "")
+    data = request.read(envelope.get("data"))
+    return data if data is not None else _malformed(status, "unexpected data")
+
+
+def _around(at: Coordinate, key: str, metres: float | None) -> Params:
+    point = (("lat", _number_text(at.lat)), ("lng", _number_text(at.lng)))
+    return point if metres is None else (*point, (key, _number_text(metres)))
+
+
+def _number_text(value: float) -> str:
+    number = float(value)
+    return str(int(number)) if number.is_integer() else repr(number)
+
+
+def _malformed(status: int, message: str) -> ApiError:
+    return ApiError(status, "malformed_response", message)
+
+
+def _object(data: Mapping[str, Any], key: str) -> Mapping[str, Any] | None:
+    value = data.get(key)
+    return value if isinstance(value, dict) else None
+
+
+def _text(data: Mapping[str, Any], key: str) -> str | None:
+    value = data.get(key)
+    return value if isinstance(value, str) else None
+
+
+def _number(data: Mapping[str, Any], key: str) -> float | None:
+    return _float(data.get(key))
+
+
+def _float(value: Any) -> float | None:
+    is_number = isinstance(value, int | float) and not isinstance(value, bool)
+    return float(value) if is_number else None
+
+
+def _raw(data: Any) -> Any:
+    return data
+
+
+def _lookup(data: Any) -> Lookup | None:
+    if not isinstance(data, dict):
+        return None
+    admin = _object(data, "administrative_address")
+    recent = _object(data, "recent_house_address")
+    return Lookup(
+        postcode=_text(data, "postcode") or "",
+        valid=data.get("valid") is True,
+        administrative_address=None
+        if admin is None
+        else AdministrativeAddress(
+            state_name=_text(admin, "state_name"),
+            lga_name=_text(admin, "lga_name"),
+            locality_name=_text(admin, "locality_name"),
+            zone=_text(admin, "zone"),
+        ),
+        recent_house_address=None if recent is None else _text(recent, "recent"),
+        building_use_status=_text(data, "building_use_status"),
+        other_building_info=data.get("other_building_info"),
+        point_geometry=data.get("point_geometry"),
+    )
+
+
+def _autocomplete(data: Any) -> Autocomplete | None:
+    if not isinstance(data, dict):
+        return None
+    items = data.get("suggestions")
+    suggestions = tuple(
+        Suggestion(code=_text(item, "code") or "", label=_text(item, "label") or "")
+        for item in (items if isinstance(items, list) else [])
+        if isinstance(item, dict)
+    )
+    segment = next((s for s in Segment if s.value == data.get("segment")), None)
+    return Autocomplete(segment=segment, suggestions=suggestions)
+
+
+def _reverse(data: Any) -> Reverse | None:
+    if not isinstance(data, dict):
+        return None
+    unit = _object(data, "unit")
+    return Reverse(
+        found=data.get("found") is True,
+        coordinate=_coordinate(data.get("coordinate")),
+        unit=None
+        if unit is None
+        else NearestUnit(
+            postcode=_text(unit, "postcode") or "",
+            display=_text(unit, "display") or "",
+            distance_m=_number(unit, "distance_m"),
+            confidence=_text(unit, "confidence"),
+            state_name=_text(unit, "state_name"),
+            lga_name=_text(unit, "lga_name"),
+            locality_name=_text(unit, "locality_name"),
+            address=_text(unit, "address"),
+        ),
+        area=_text(data, "area"),
+        district=_text(data, "district"),
+        state=_text(data, "state"),
+        message=_text(data, "message"),
+        radius_m=_number(data, "radius_m"),
+    )
+
+
+def _coordinate(value: Any) -> Coordinate | None:
+    """The API echoes points as `[lng, lat]`."""
+    if not isinstance(value, list) or len(value) != 2:
+        return None
+    lng, lat = (_float(v) for v in value)
+    return None if lng is None or lat is None else Coordinate(lat=lat, lng=lng)

ng_postcode/client.py

@@ -0,0 +1,91 @@
+"""HTTP shell over `ng_postcode.api`, built on httpx: the only module that performs I/O.
+
+Install with `pip install "ng-postcode[client]"`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeVar
+
+import httpx
+
+from .api import BASE_URL, ApiError, Request, decode
+
+T = TypeVar("T")
+
+TIMEOUT = 10.0
+
+
+@dataclass(frozen=True, slots=True)
+class TransportError:
+    """The request never produced a response: DNS, TLS, timeout and the like."""
+
+    reason: str
+
+    def __str__(self) -> str:
+        return self.reason
+
+
+class Client:
+    """Blocking client. Pass `http` to reuse your own `httpx.Client`; it stays yours to close."""
+
+    def __init__(
+        self, api_key: str, *, base_url: str = BASE_URL, http: httpx.Client | None = None
+    ) -> None:
+        self._http = http if http is not None else httpx.Client(timeout=TIMEOUT)
+        self._owns_http = http is None
+        self._base_url = base_url
+        self._headers = {"X-API-Key": api_key}
+
+    def send(self, request: Request[T]) -> T | ApiError | TransportError:
+        url = self._base_url + request.path
+        try:
+            response = self._http.get(url, params=request.params, headers=self._headers)
+        except httpx.HTTPError as error:
+            return _transport(error)
+        return decode(request, response.status_code, response.text)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncClient:
+    """Async client. Pass `http` to reuse your own `httpx.AsyncClient`; it stays yours to close."""
+
+    def __init__(
+        self, api_key: str, *, base_url: str = BASE_URL, http: httpx.AsyncClient | None = None
+    ) -> None:
+        self._http = http if http is not None else httpx.AsyncClient(timeout=TIMEOUT)
+        self._owns_http = http is None
+        self._base_url = base_url
+        self._headers = {"X-API-Key": api_key}
+
+    async def send(self, request: Request[T]) -> T | ApiError | TransportError:
+        url = self._base_url + request.path
+        try:
+            response = await self._http.get(url, params=request.params, headers=self._headers)
+        except httpx.HTTPError as error:
+            return _transport(error)
+        return decode(request, response.status_code, response.text)
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+
+def _transport(error: httpx.HTTPError) -> TransportError:
+    return TransportError(str(error) or type(error).__name__)

ng_postcode-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: ng-postcode
+Version: 0.1.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
+Project-URL: API docs, https://docs.postcode.gov.ng
+Author: Kayode Adeniyi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: address,address-validation,geocoding,ndaps,nigeria,nipost,postal-code,postcode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == 'client'
+Description-Content-Type: text/markdown
+
+# ng-postcode
+
+Python library for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. Parse, validate and format postcodes offline, and call the [postcode.gov.ng](https://docs.postcode.gov.ng) API for lookup, autocomplete and reverse geocoding.
+
+Also available for Rust: [`ng-postcode` on crates.io](https://crates.io/crates/ng-postcode).
+
+```sh
+pip install ng-postcode            # offline core, no dependencies
+pip install "ng-postcode[client]"  # adds the API client (httpx)
+```
+
+## Format
+
+An 11-character code in five segments: state, LGA, district, area, building unit.
+
+| Style | Example |
+| --- | --- |
+| Canonical | `EK-01-A03-FK-01` |
+| Display | `EK 01 A03 FK 01` |
+| Compact | `EK01A03FK01` |
+
+Compact form as a regular expression: `^[A-Z]{2}(0[1-9]|[1-9][0-9])[A-Z0-9]{3}[A-Z]{2}(0[1-9]|[1-9][0-9])$`
+
+## Offline
+
+Expected failures are returned as values, not raised, so the type checker makes you handle them.
+
+```python
+from ng_postcode import Postcode, Segment, parse
+
+match parse("ek 01 a03 fk 01"):
+    case Postcode() as code:
+        print(code)  # EK-01-A03-FK-01
+        print(code.compact)  # EK01A03FK01, store this
+        print(code.spaced)  # EK 01 A03 FK 01
+        print(code.prefix(Segment.AREA))  # EK-01-A03-FK
+    case error:
+        print(error)  # e.g. "invalid lga segment"
+```
+
+- `parse` accepts hyphenated, spaced or compact input in either case.
+- `parse_lenient` first swaps look-alikes that cannot occur where they stand (`O`/`0`, `I`/`1`, `S`/`5`, `B`/`8`) and reports how many it changed.
+- `from_segments` assembles a code from its parts and zero-fills the LGA and unit.
+- `Postcode` is immutable, hashable and sorts by state, LGA, district, area, unit.
+
+A well-formed code is not necessarily assigned to a building. Only the API can confirm that a postcode exists.
+
+## API
+
+```python
+from ng_postcode import Postcode, parse
+from ng_postcode.api import lookup
+from ng_postcode.client import Client
+
+code = parse("EK-01-A03-FK-01")
+assert isinstance(code, Postcode)
+
+with Client(api_key="nipost_live_...") as client:
+    found = client.send(lookup(code, level=2))
+```
+
+`send` returns the typed response, an `ApiError` (for example `auth_required` or `insufficient_credits`) or a `TransportError`. `AsyncClient` has the same interface for asyncio.
+
+`ng_postcode.api` covers lookup, autocomplete, reverse geocoding and nearby search. Each function returns a `Request` value and `decode` turns a status and body into a typed result, so it works with any HTTP client without the `client` extra.
+
+## License
+
+MIT

ng_postcode-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ng_postcode/__init__.py,sha256=SPlQ7P6HF35AztumNfYW1iY0iiX3gInn_W9Y4lPrN7Y,930
+ng_postcode/_postcode.py,sha256=fgMsN0_r04_Nzz9tqPhnXxI0bxbUQGAFBPcFnO1TAQ8,7184
+ng_postcode/api.py,sha256=0_8oi6fDmCa2p5wpf67eCYkQd2mxMFUcKaXVRxfQN10,8596
+ng_postcode/client.py,sha256=CrLHgq47N_m09CcvpttCRfmrfRb2I-tG4gaxXDyckn4,2799
+ng_postcode/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ng_postcode-0.1.0.dist-info/METADATA,sha256=myuOFZlUpcDqZBWlUI03BfjhLb2l0dqCTG5JFTb0Ni4,3927
+ng_postcode-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ng_postcode-0.1.0.dist-info/licenses/LICENSE,sha256=5J4ejW4oekCqBi05kyohGmFDQp7wWDwN4vP5w_R7lGM,1071
+ng_postcode-0.1.0.dist-info/RECORD,,

ng_postcode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

ng_postcode-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayode Adeniyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.