ideal-postcodes 0.1.0__py3-none-any.whl

ideal_postcodes/__init__.py

@@ -0,0 +1,27 @@
+"""IdealPostcodes address and key client."""
+
+from .client import IdealPostcodes
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ClientError,
+    NotFoundError,
+    PaymentRequiredError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+)
+
+__all__ = [
+    "IdealPostcodes",
+    "APIError",
+    "AuthenticationError",
+    "ClientError",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "ProtocolError",
+    "RateLimitError",
+    "ServerError",
+    "TransportError",
+]

ideal_postcodes/_transport.py

@@ -0,0 +1,194 @@
+"""Connection lifecycle and envelope handling shared by generated methods."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from functools import cache
+from importlib.metadata import version
+from typing import Any, Literal, Self, cast
+from urllib.parse import quote
+
+import httpx
+from pydantic import TypeAdapter, ValidationError
+
+from .errors import ProtocolError, TransportError, error_for
+
+BASE_URL = "https://api.ideal-postcodes.co.uk/v1"
+USER_AGENT = f"ideal-postcodes-python-sdk/{version('ideal-postcodes')}"
+
+
+def segment(value: str | int) -> str:
+    """Encode a single non-empty path segment without treating it as a URL."""
+    text = str(value)
+    if not text or text in {".", ".."}:
+        raise ValueError("Path identifiers must be non-empty and cannot be dot segments")
+    return quote(text, safe="")
+
+
+def fields(values: Mapping[str, object]) -> dict[str, object]:
+    """Omit optional inputs; preserve false, zero and empty strings."""
+    return {key: value for key, value in values.items() if value is not None}
+
+
+TYPES: dict[str, tuple[type, ...]] = {
+    "string": (str,),
+    "integer": (int,),
+    "number": (int, float),
+    "boolean": (bool,),
+    "array": (list, tuple),
+    "object": (Mapping,),
+}
+
+
+def check(name: str, value: object, schema: Mapping[str, Any]) -> None:
+    """Raise TypeError or ValueError when an input breaks its spec schema. Messages omit the value."""
+    if value is None:
+        if not schema.get("nullable"):
+            raise TypeError(f"{name} cannot be None")
+        return
+    kind = schema.get("type")
+    if kind and (not isinstance(value, TYPES[kind]) or (isinstance(value, bool) and kind != "boolean")):
+        raise TypeError(f"{name} must be a{'n' if kind[0] in 'aeiou' else ''} {kind}")
+    broken: str | None = None
+    if isinstance(value, int | float) and not isinstance(value, bool):
+        if value < schema.get("minimum", value):
+            broken = "minimum"
+        elif value > schema.get("maximum", value):
+            broken = "maximum"
+    elif isinstance(value, str):
+        if len(value) < schema.get("minLength", 0):
+            broken = "minLength"
+        elif len(value) > schema.get("maxLength", len(value)):
+            broken = "maxLength"
+        elif "pattern" in schema and not re.search(schema["pattern"], value):
+            broken = "pattern"
+    elif isinstance(value, list | tuple):
+        size = len(cast("list[object]", value))
+        if size < schema.get("minItems", 0):
+            broken = "minItems"
+        elif size > schema.get("maxItems", size):
+            broken = "maxItems"
+    if broken:
+        raise ValueError(f"{name} must satisfy {broken}={schema[broken]!r}")
+    if "items" in schema:
+        for index, item in enumerate(cast("list[object]", value)):
+            check(f"{name}[{index}]", item, schema["items"])
+    if "properties" in schema:
+        entries = cast("Mapping[str, object]", value)
+        properties: Mapping[str, Any] = schema["properties"]
+        unknown = sorted(set(entries) - set(properties))
+        if unknown:
+            raise TypeError(f"{name} has unknown keys: {', '.join(map(str, unknown))}")
+        missing = [key for key in schema.get("required", []) if key not in entries]
+        if missing:
+            raise TypeError(f"{name} is missing keys: {', '.join(missing)}")
+        for key, item in entries.items():
+            check(f"{name}.{key}", item, properties[key])
+
+
+def check_inputs(schemas: Mapping[str, Mapping[str, Any]], **values: object) -> None:
+    """Check every supplied argument; None means omitted."""
+    for name, value in values.items():
+        if value is not None:
+            check(name, value, schemas[name])
+
+
+@cache
+def adapter(schema: Any) -> TypeAdapter[Any]:
+    return TypeAdapter(schema)
+
+
+def validate(schema: Any, value: object) -> Any:
+    """Validate results without including payload values in error messages."""
+    try:
+        return adapter(schema).validate_python(value)
+    except ValidationError as error:
+        details = error.errors(include_input=False)
+        locations = ", ".join(".".join(map(str, item["loc"])) for item in details[:8])
+        if len(details) > 8:
+            locations += f" (+{len(details) - 8} more)"
+        raise ProtocolError(f"Invalid response fields: {locations}", value) from None
+
+
+class Transport:
+    """Synchronous connection pool. Use a context manager or call close().
+
+    api_key: API key sent in the Authorization header, with any Management Key the operation takes.
+    timeout: Per-request HTTPX timeout in seconds, default 10.
+    base_url: API root including /v1, or a test server URL.
+    transport: Optional HTTPX transport for offline tests.
+
+    Requests are never retried automatically, including billable lookups.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        timeout: float = 10.0,
+        base_url: str = BASE_URL,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/") + "/",
+            timeout=timeout,
+            transport=transport,
+            headers={"User-Agent": USER_AGENT},
+        )
+        self._api_key = api_key
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the connection pool."""
+        self._http.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, object] | None = None,
+        body: Mapping[str, object] | None = None,
+        result_shape: Literal["object", "array", "csv"] = "object",
+        user_token: str | None = None,
+    ) -> object:
+        params: dict[str, Any] = {}
+        for key, value in fields(query or {}).items():
+            params[key] = (
+                ",".join(str(item) for item in cast("list[object]", value)) if isinstance(value, list) else value
+            )
+        # v1 credentials: api_key="ak_..." user_token="uk_..." in one Authorization header.
+        credentials = [
+            f'{name}="{value}"' for name, value in (("api_key", self._api_key), ("user_token", user_token)) if value
+        ]
+        headers = {"Authorization": " ".join(credentials)} if credentials else None
+        try:
+            response = self._http.request(method, path.lstrip("/"), params=params, json=body, headers=headers)
+        except httpx.RequestError:
+            raise TransportError("Request failed before a response was received; no retry was made") from None
+        try:
+            payload: object = response.json()
+        except ValueError:
+            payload = None
+        envelope = cast("dict[str, Any]", payload) if isinstance(payload, dict) else {}
+        if not 200 <= response.status_code < 300:
+            raise error_for(response.status_code, envelope, response.headers.get("Retry-After"))
+        if response.status_code != 200:
+            raise ProtocolError(f"Unexpected success status {response.status_code}")
+        if result_shape == "csv":
+            if response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower() != "text/csv":
+                raise ProtocolError("Expected a CSV response")
+            return response.text
+        if envelope.get("code") != 2000 or "result" not in envelope or envelope["result"] is None:
+            raise ProtocolError("Expected a JSON success envelope with code 2000 and a result")
+        result = envelope["result"]
+        expected = list if result_shape == "array" else dict
+        if not isinstance(result, expected):
+            raise ProtocolError(f"Expected result to be a JSON {result_shape}")
+        return cast("list[object] | dict[str, object]", result)