ng-postcode 0.1.0__tar.gz

ng_postcode-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+target/
+Cargo.lock
+.venv/
+__pycache__/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

ng_postcode-0.1.0/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.

ng_postcode-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,68 @@
+# 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/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ng-postcode"
+version = "0.1.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"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kayode Adeniyi" }]
+keywords = ["nigeria", "postcode", "nipost", "ndaps", "address", "address-validation", "geocoding", "postal-code"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+client = ["httpx>=0.27"]
+
+[project.urls]
+Repository = "https://github.com/Adeniyikayodee/ng-postcode"
+Issues = "https://github.com/Adeniyikayodee/ng-postcode/issues"
+"API docs" = "https://docs.postcode.gov.ng"
+
+[dependency-groups]
+dev = ["httpx>=0.27", "mypy>=1.13", "pytest>=8", "ruff>=0.8"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "PT"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+addopts = "--doctest-modules"

ng_postcode-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_api.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+
+from ng_postcode import Postcode, Segment, parse
+from ng_postcode.api import (
+    AdministrativeAddress,
+    ApiError,
+    Coordinate,
+    autocomplete,
+    decode,
+    lookup,
+    nearby,
+    reverse,
+)
+
+HERE = Coordinate(lat=7.62, lng=5.22)
+
+
+def code(text: str) -> Postcode:
+    parsed = parse(text)
+    assert isinstance(parsed, Postcode)
+    return parsed
+
+
+def body(data: object) -> str:
+    return json.dumps({"data": data})
+
+
+def test_builds_requests() -> None:
+    request = lookup(code("ek01a03fk01"), 3)
+    assert (request.path, request.params) == (
+        "/v1/lookup",
+        (("code", "EK-01-A03-FK-01"), ("level", "3")),
+    )
+    assert autocomplete("EK 01 A").params == (("q", "EK 01 A"),)
+    assert reverse(HERE, 100.0).params == (
+        ("lat", "7.62"),
+        ("lng", "5.22"),
+        ("max_distance_m", "100"),
+    )
+    assert nearby(HERE).params == (("lat", "7.62"), ("lng", "5.22"))
+
+
+def test_decodes_the_documented_lookup() -> None:
+    data = {
+        "postcode": "EK-01-A03-FK-01",
+        "valid": True,
+        "administrative_address": {
+            "state_name": "EKITI",
+            "lga_name": "ADO EKITI",
+            "locality_name": "ADO EKITI",
+            "zone": "SOUTH WEST",
+        },
+        "recent_house_address": {"recent": "NTA ROAD, BACK OF FABIAN HOTEL, ADO EKITI"},
+        "building_use_status": "residential",
+    }
+    found = decode(lookup(code("EK-01-A03-FK-01"), 3), 200, body(data))
+    assert not isinstance(found, ApiError)
+    assert found.valid
+    assert found.administrative_address == AdministrativeAddress(
+        "EKITI", "ADO EKITI", "ADO EKITI", "SOUTH WEST"
+    )
+    assert found.recent_house_address == "NTA ROAD, BACK OF FABIAN HOTEL, ADO EKITI"
+    assert (found.building_use_status, found.point_geometry) == ("residential", None)
+
+
+def test_fields_above_the_granted_level_are_none() -> None:
+    data = {"postcode": "EK-01-A03-FK-01", "valid": True}
+    found = decode(lookup(code("EK-01-A03-FK-01")), 200, body(data))
+    assert not isinstance(found, ApiError)
+    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"}]}
+    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"
+
+    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_error_envelopes_and_bad_bodies_become_values() -> None:
+    request = lookup(code("EK-01-A03-FK-01"))
+    # What the live API answered on 2 October 2026 when called without a key.
+    refused = '{"error":{"code":"auth_required","message":"an API key is required"}}'
+    assert decode(request, 401, refused) == ApiError(401, "auth_required", "an API key is required")
+    for status, text in [(502, "<html>Bad Gateway</html>"), (200, "[]"), (200, '{"data": 1}')]:
+        error = decode(request, status, text)
+        assert isinstance(error, ApiError)
+        assert (error.status, error.code) == (status, "malformed_response")

ng_postcode-0.1.0/tests/test_client.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+
+import httpx
+
+from ng_postcode import Postcode
+from ng_postcode.api import ApiError, Lookup, lookup
+from ng_postcode.client import AsyncClient, Client, TransportError
+
+CODE = Postcode("EK01A03FK01")
+
+
+def api(request: httpx.Request) -> httpx.Response:
+    if request.headers.get("X-API-Key") != "key":
+        error = {"code": "invalid_api_key", "message": "the provided API key is invalid"}
+        return httpx.Response(401, json={"error": error})
+    assert request.url.path == "/v1/lookup"
+    assert dict(request.url.params) == {"code": "EK-01-A03-FK-01", "level": "1"}
+    return httpx.Response(200, json={"data": {"postcode": "EK-01-A03-FK-01", "valid": True}})
+
+
+def unreachable(request: httpx.Request) -> httpx.Response:
+    raise httpx.ConnectError("connection refused", request=request)
+
+
+def sync_client(key: str, handler: Callable[[httpx.Request], httpx.Response]) -> Client:
+    return Client(key, http=httpx.Client(transport=httpx.MockTransport(handler)))
+
+
+def test_sends_the_key_and_decodes_the_answer() -> None:
+    with sync_client("key", api) as client:
+        found = client.send(lookup(CODE))
+    assert isinstance(found, Lookup)
+    assert (found.postcode, found.valid) == ("EK-01-A03-FK-01", True)
+
+
+def test_api_and_network_failures_are_values() -> None:
+    with sync_client("wrong", api) as client:
+        assert client.send(lookup(CODE)) == ApiError(
+            401, "invalid_api_key", "the provided API key is invalid"
+        )
+    with sync_client("key", unreachable) as client:
+        assert client.send(lookup(CODE)) == TransportError("connection refused")
+
+
+def test_only_closes_the_http_client_it_created() -> None:
+    http = httpx.Client(transport=httpx.MockTransport(api))
+    with Client("key", http=http):
+        pass
+    assert not http.is_closed
+    http.close()
+
+
+def test_async_client() -> None:
+    async def run() -> Lookup | ApiError | TransportError:
+        http = httpx.AsyncClient(transport=httpx.MockTransport(api))
+        async with AsyncClient("key", http=http) as client:
+            return await client.send(lookup(CODE))
+
+    found = asyncio.run(run())
+    assert isinstance(found, Lookup)
+    assert found.valid

ng_postcode-0.1.0/tests/test_conformance.py

@@ -0,0 +1,80 @@
+"""Runs the shared cases in `spec/vectors.json`, which every implementation must pass."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from ng_postcode import (
+    Corrected,
+    InvalidCharacter,
+    InvalidSegment,
+    ParseError,
+    Postcode,
+    Segment,
+    WrongLength,
+    from_segments,
+    parse,
+    parse_lenient,
+)
+
+VECTORS = Path(__file__).resolve().parents[2] / "spec" / "vectors.json"
+CASES: dict[str, Any] = json.loads(VECTORS.read_text(encoding="utf-8")) if VECTORS.exists() else {}
+
+pytestmark = pytest.mark.skipif(
+    not CASES, reason="spec/vectors.json lives in the repository, not the sdist"
+)
+
+
+def outcome(result: Postcode | Corrected | ParseError) -> dict[str, Any]:
+    match result:
+        case Postcode():
+            return {"canonical": str(result)}
+        case Corrected(postcode, corrections):
+            return {"canonical": str(postcode), "corrections": corrections}
+        case WrongLength(found):
+            return {"error": {"kind": "length", "found": found}}
+        case InvalidCharacter(char, index):
+            return {"error": {"kind": "invalid_character", "char": char, "index": index}}
+        case InvalidSegment(segment):
+            return {"error": {"kind": "segment", "segment": segment.value}}
+
+
+def expected(case: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in case.items() if k in ("canonical", "corrections", "error")}
+
+
+@pytest.mark.parametrize("case", CASES.get("parse", {}).get("valid", []))
+def test_parse_valid(case: dict[str, Any]) -> None:
+    code = parse(case["input"])
+    assert isinstance(code, Postcode)
+    assert (str(code), code.compact, code.spaced) == (
+        case["canonical"],
+        case["compact"],
+        case["spaced"],
+    )
+
+
+@pytest.mark.parametrize("case", CASES.get("parse", {}).get("invalid", []))
+def test_parse_invalid(case: dict[str, Any]) -> None:
+    assert outcome(parse(case["input"])) == expected(case)
+
+
+@pytest.mark.parametrize("case", CASES.get("parse_lenient", []))
+def test_parse_lenient(case: dict[str, Any]) -> None:
+    assert outcome(parse_lenient(case["input"])) == expected(case)
+
+
+@pytest.mark.parametrize("case", CASES.get("from_segments", []))
+def test_from_segments(case: dict[str, Any]) -> None:
+    assert outcome(from_segments(*case["segments"])) == expected(case)
+
+
+@pytest.mark.parametrize("case", CASES.get("prefix", []))
+def test_prefix(case: dict[str, Any]) -> None:
+    code = parse(case["input"])
+    assert isinstance(code, Postcode)
+    assert code.prefix(Segment(case["through"])) == case["prefix"]

ng_postcode-0.1.0/tests/test_postcode.py

@@ -0,0 +1,73 @@
+"""Python-specific behaviour. Shared parsing rules live in test_conformance.py."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from ng_postcode import (
+    Corrected,
+    InvalidCharacter,
+    InvalidSegment,
+    Postcode,
+    Segment,
+    WrongLength,
+    is_valid,
+    parse,
+    parse_lenient,
+)
+
+
+def ok(text: str) -> Postcode:
+    code = parse(text)
+    assert isinstance(code, Postcode), code
+    return code
+
+
+def test_errors_are_values_with_readable_messages() -> None:
+    assert parse("EK-01") == WrongLength(found=4)
+    assert str(WrongLength(found=5)) == "expected 11 letters and digits, found 5"
+    assert str(InvalidCharacter(char="_", index=2)) == "invalid character '_' at index 2"
+    assert str(InvalidSegment(Segment.LGA)) == "invalid lga segment"
+
+
+def test_exposes_segments() -> None:
+    code = ok("la11w06tc10")
+    assert (code.state, code.lga, code.district, code.area, code.unit) == (
+        "LA",
+        "11",
+        "W06",
+        "TC",
+        "10",
+    )
+    assert repr(code) == "Postcode('LA-11-W06-TC-10')"
+
+
+def test_postcodes_are_immutable_hashable_and_ordered() -> None:
+    code = ok("EK-01-A03-FK-01")
+    assert code == ok("ek 01 a03 fk 01")
+    assert len({code, ok("ek01a03fk01")}) == 1
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        setattr(code, "compact", "LA11W06TC10")  # noqa: B010
+    codes = [ok("LA-11-W06-TC-10"), ok("EK-01-A03-FK-02"), code]
+    assert [str(c) for c in sorted(codes)] == [
+        "EK-01-A03-FK-01",
+        "EK-01-A03-FK-02",
+        "LA-11-W06-TC-10",
+    ]
+
+
+@pytest.mark.parametrize("text", ["ek01a03fk01", "EK-01-A03-FK-01", "EK00A03FK01", ""])
+def test_direct_construction_demands_the_compact_form(text: str) -> None:
+    with pytest.raises(ValueError, match="not a compact upper-case postcode"):
+        Postcode(text)
+
+
+def test_lenient_counts_corrections() -> None:
+    assert parse_lenient("EK-O1-A03-FK-0I") == Corrected(ok("EK-01-A03-FK-01"), 2)
+
+
+def test_is_valid_agrees_with_parse() -> None:
+    assert is_valid("ek 01 a03 fk 01")
+    assert not is_valid("EK-01-A03")