ideal-postcodes 0.1.0__tar.gz

ideal_postcodes-0.1.0/LICENSE

@@ -0,0 +1 @@
+Copyright (C) IDDQD Limited - All Rights Reserved

ideal_postcodes-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: ideal-postcodes
+Version: 0.1.0
+Summary: Explicit Python client for Ideal Postcodes
+Keywords: address,postcode,address-lookup,address-autocomplete,uk
+Author: Ideal Postcodes
+Author-email: Ideal Postcodes <support@ideal-postcodes.co.uk>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: httpx==0.28.1
+Requires-Dist: pydantic==2.13.5
+Requires-Python: >=3.12
+Project-URL: Documentation, https://docs.ideal-postcodes.co.uk/docs/sdks/python
+Project-URL: Homepage, https://ideal-postcodes.co.uk
+Project-URL: Issues, https://github.com/ideal-postcodes/feedback/issues
+Project-URL: Repository, https://github.com/ideal-postcodes/feedback
+Description-Content-Type: text/markdown
+
+# Ideal Postcodes Python SDK
+
+Client for every current API operation: address search and lookup, place search, email and phone validation, and key, licensee and configuration management. Requires Python 3.12 or later; tested on 3.12, 3.13 and 3.14.
+
+```sh
+pip install ideal-postcodes
+```
+
+```python
+from ideal_postcodes import IdealPostcodes
+
+with IdealPostcodes("ak_test") as client:
+    for address in client.postcodes("BR8 7RE"):
+        print(address.line_1, address.post_town)
+```
+
+`ak_test` is the public test key. The client returns Pydantic models from the API's `result` field. Read fields as attributes and use `model_dump()` for a dictionary. Reuse one client and close it with a context manager. Production keys belong in environment variables.
+
+## Search and resolve
+
+```python
+from ideal_postcodes import IdealPostcodes
+
+with IdealPostcodes("ak_test") as client:
+    hits = client.find_address(query="9 Malyons Road", limit=5).hits
+    if hits:
+        address = client.resolve_address(hits[0].id)
+        print(address.postcode)
+```
+
+Resolve the suggestion the user chooses. An empty suggestion list is a normal result.
+
+## Methods
+
+| Method | Purpose |
+| --- | --- |
+| `postcodes(postcode, ...)` | Addresses at a postcode |
+| `addresses(query=..., ...)` | Paginated address search; filters can be used without query text |
+| `address_cleanse(query=..., ...)` | Cleanse a freeform address, with optional postcode and post town |
+| `find_address(query=..., ...)` | Autocomplete suggestions |
+| `resolve_address(address, ...)` | Resolve a suggestion using the spec's GBR endpoint |
+| `find_place(query=..., ...)` | Place search |
+| `resolve_place(place, ...)` | Resolve a place suggestion |
+| `email_validation(query=..., ...)` | Validate an email address |
+| `phone_number_validation(query=..., ...)` | Validate a phone number |
+| `key_availability(key)` | Public availability and licensed contexts |
+| `key_details(key, user_token=...)` | Private settings and remaining lookups |
+| `update_key_details(key, user_token=..., ...)` | Update selected key settings |
+| `key_usage(key, user_token=..., ...)` | Usage totals and daily breakdown |
+| `key_logs(key, user_token=..., ...)` | Paid lookup logs as CSV text |
+| `list_licensees`, `create_licensee`, `retrieve_licensee`, `update_licensee`, `delete_licensee`, `regenerate_licensee_key` | Licensee management |
+| `list_configs`, `create_config`, `retrieve_config`, `update_config`, `delete_config` | Saved configurations |
+Methods expose every supported input in their signatures. Required keyword arguments must be supplied. Optional `None` values are omitted, leaving defaults to the server. Dataset lists are comma-joined. String flags use `"true"` and `"false"`, as declared by the API. Parameter constraints appear in each method's docstring; scalar ranges, lengths and enums are checked before sending.
+
+Use `help(IdealPostcodes.find_address)` or inspect `ideal_postcodes/client.py` for parameters. Response definitions live in `ideal_postcodes/types.py`. `examples/` has a runnable script for each method.
+
+## Keys
+
+```python
+from ideal_postcodes import IdealPostcodes
+
+with IdealPostcodes("ak_test") as client:
+    availability = client.key_availability("ak_test")
+    print(availability.available)
+```
+
+The `key` argument identifies the key to inspect or update. Availability and `retrieve_config` need no Management Key. Other key, licensee and configuration methods require your Management Key as the keyword `user_token`; the client sends it in the `Authorization` header, never the URL. Load it from your application's secret storage. Usage and logs accept `start` and `end` as UNIX timestamps in milliseconds. `key_logs` returns CSV text rather than a response model.
+
+Update only the settings you want to change. Nested settings accept typed dictionaries from `ideal_postcodes.requests`. For example, `daily_limit={"limit": None}` disables the daily limit, `notifications={"enabled": False}` disables notifications and `allowed_urls=[]` clears the URL restriction. Omitted top-level settings remain unchanged. Nested `None` values are sent as JSON `null`.
+
+## Errors and retries
+
+All SDK request failures derive from `ClientError`:
+
+- `APIError`: unsuccessful HTTP response, with `status`, `code`, `message`, `body` and raw `retry_after`
+- `AuthenticationError`, `PaymentRequiredError`, `NotFoundError`, `RateLimitError` and `ServerError`: API error subclasses
+- `TransportError`: connection or timeout failure before a response
+- `ProtocolError`: unexpected success status, malformed envelope or invalid response fields. When response fields fail validation, `result` holds the unvalidated result, so `except ProtocolError as error: raw = error.result` can fall back to it
+
+`NotFoundError.suggestions` contains postcode suggestions when supplied by the API. HTTP 429 and HTTP 503 with API code 5030 raise `RateLimitError`. Other 5xx responses raise `ServerError`. Exception strings include the API's `message`, for example `API request failed (HTTP 404, code 4040): Postcode not found`, and omit credentials and request URLs. `body` may contain caller input.
+
+There are no automatic retries. A timeout may occur after a lookup was processed. Choose retry behaviour in the application and bound attempts; `Retry-After` can be seconds or an HTTP date. Inputs are checked against the spec before the network call: a missing argument, wrong type or unknown settings key raises `TypeError`, and an out-of-range number, string length or pattern raises `ValueError`. Option values the SDK does not list yet pass through to the API.
+
+## Testing and limits
+
+Pass `transport=httpx.MockTransport(handler)` to test without network access, or override `base_url`. The default timeout is 10 seconds.
+
+Response models validate required fields, types, lists and unions from the checked-in OpenAPI contract, and accept normal API growth: extra fields survive in `model_dump()`, option fields are plain strings so new values come through, and a `native` record from a dataset the SDK does not know yet arrives as a dictionary. An explicit `filter` returns address dictionaries containing the requested fields; paginated address search returns a model whose `hits` are dictionaries. The client is synchronous; run it in a worker thread when calling from an async application.
+
+Signup is not included.
+
+## Development
+
+Run `uv sync --frozen`, then `make ci` and `make build`. `make generate` rebuilds the client, transport and response types from the shared generator and this brand's spec. `make check-generated` detects drift without rewriting committed files. `make format` applies Ruff fixes and formatting; `make ci` checks both. Run commands from this package directory.
+
+## Licence
+
+SEE LICENSE IN LICENSE

ideal_postcodes-0.1.0/README.md

@@ -0,0 +1,98 @@
+# Ideal Postcodes Python SDK
+
+Client for every current API operation: address search and lookup, place search, email and phone validation, and key, licensee and configuration management. Requires Python 3.12 or later; tested on 3.12, 3.13 and 3.14.
+
+```sh
+pip install ideal-postcodes
+```
+
+```python
+from ideal_postcodes import IdealPostcodes
+
+with IdealPostcodes("ak_test") as client:
+    for address in client.postcodes("BR8 7RE"):
+        print(address.line_1, address.post_town)
+```
+
+`ak_test` is the public test key. The client returns Pydantic models from the API's `result` field. Read fields as attributes and use `model_dump()` for a dictionary. Reuse one client and close it with a context manager. Production keys belong in environment variables.
+
+## Search and resolve
+
+```python
+from ideal_postcodes import IdealPostcodes
+
+with IdealPostcodes("ak_test") as client:
+    hits = client.find_address(query="9 Malyons Road", limit=5).hits
+    if hits:
+        address = client.resolve_address(hits[0].id)
+        print(address.postcode)
+```
+
+Resolve the suggestion the user chooses. An empty suggestion list is a normal result.
+
+## Methods
+
+| Method | Purpose |
+| --- | --- |
+| `postcodes(postcode, ...)` | Addresses at a postcode |
+| `addresses(query=..., ...)` | Paginated address search; filters can be used without query text |
+| `address_cleanse(query=..., ...)` | Cleanse a freeform address, with optional postcode and post town |
+| `find_address(query=..., ...)` | Autocomplete suggestions |
+| `resolve_address(address, ...)` | Resolve a suggestion using the spec's GBR endpoint |
+| `find_place(query=..., ...)` | Place search |
+| `resolve_place(place, ...)` | Resolve a place suggestion |
+| `email_validation(query=..., ...)` | Validate an email address |
+| `phone_number_validation(query=..., ...)` | Validate a phone number |
+| `key_availability(key)` | Public availability and licensed contexts |
+| `key_details(key, user_token=...)` | Private settings and remaining lookups |
+| `update_key_details(key, user_token=..., ...)` | Update selected key settings |
+| `key_usage(key, user_token=..., ...)` | Usage totals and daily breakdown |
+| `key_logs(key, user_token=..., ...)` | Paid lookup logs as CSV text |
+| `list_licensees`, `create_licensee`, `retrieve_licensee`, `update_licensee`, `delete_licensee`, `regenerate_licensee_key` | Licensee management |
+| `list_configs`, `create_config`, `retrieve_config`, `update_config`, `delete_config` | Saved configurations |
+Methods expose every supported input in their signatures. Required keyword arguments must be supplied. Optional `None` values are omitted, leaving defaults to the server. Dataset lists are comma-joined. String flags use `"true"` and `"false"`, as declared by the API. Parameter constraints appear in each method's docstring; scalar ranges, lengths and enums are checked before sending.
+
+Use `help(IdealPostcodes.find_address)` or inspect `ideal_postcodes/client.py` for parameters. Response definitions live in `ideal_postcodes/types.py`. `examples/` has a runnable script for each method.
+
+## Keys
+
+```python
+from ideal_postcodes import IdealPostcodes
+
+with IdealPostcodes("ak_test") as client:
+    availability = client.key_availability("ak_test")
+    print(availability.available)
+```
+
+The `key` argument identifies the key to inspect or update. Availability and `retrieve_config` need no Management Key. Other key, licensee and configuration methods require your Management Key as the keyword `user_token`; the client sends it in the `Authorization` header, never the URL. Load it from your application's secret storage. Usage and logs accept `start` and `end` as UNIX timestamps in milliseconds. `key_logs` returns CSV text rather than a response model.
+
+Update only the settings you want to change. Nested settings accept typed dictionaries from `ideal_postcodes.requests`. For example, `daily_limit={"limit": None}` disables the daily limit, `notifications={"enabled": False}` disables notifications and `allowed_urls=[]` clears the URL restriction. Omitted top-level settings remain unchanged. Nested `None` values are sent as JSON `null`.
+
+## Errors and retries
+
+All SDK request failures derive from `ClientError`:
+
+- `APIError`: unsuccessful HTTP response, with `status`, `code`, `message`, `body` and raw `retry_after`
+- `AuthenticationError`, `PaymentRequiredError`, `NotFoundError`, `RateLimitError` and `ServerError`: API error subclasses
+- `TransportError`: connection or timeout failure before a response
+- `ProtocolError`: unexpected success status, malformed envelope or invalid response fields. When response fields fail validation, `result` holds the unvalidated result, so `except ProtocolError as error: raw = error.result` can fall back to it
+
+`NotFoundError.suggestions` contains postcode suggestions when supplied by the API. HTTP 429 and HTTP 503 with API code 5030 raise `RateLimitError`. Other 5xx responses raise `ServerError`. Exception strings include the API's `message`, for example `API request failed (HTTP 404, code 4040): Postcode not found`, and omit credentials and request URLs. `body` may contain caller input.
+
+There are no automatic retries. A timeout may occur after a lookup was processed. Choose retry behaviour in the application and bound attempts; `Retry-After` can be seconds or an HTTP date. Inputs are checked against the spec before the network call: a missing argument, wrong type or unknown settings key raises `TypeError`, and an out-of-range number, string length or pattern raises `ValueError`. Option values the SDK does not list yet pass through to the API.
+
+## Testing and limits
+
+Pass `transport=httpx.MockTransport(handler)` to test without network access, or override `base_url`. The default timeout is 10 seconds.
+
+Response models validate required fields, types, lists and unions from the checked-in OpenAPI contract, and accept normal API growth: extra fields survive in `model_dump()`, option fields are plain strings so new values come through, and a `native` record from a dataset the SDK does not know yet arrives as a dictionary. An explicit `filter` returns address dictionaries containing the requested fields; paginated address search returns a model whose `hits` are dictionaries. The client is synchronous; run it in a worker thread when calling from an async application.
+
+Signup is not included.
+
+## Development
+
+Run `uv sync --frozen`, then `make ci` and `make build`. `make generate` rebuilds the client, transport and response types from the shared generator and this brand's spec. `make check-generated` detects drift without rewriting committed files. `make format` applies Ruff fixes and formatting; `make ci` checks both. Run commands from this package directory.
+
+## Licence
+
+SEE LICENSE IN LICENSE

ideal_postcodes-0.1.0/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-0.1.0/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)