haveapi-client 0.30.0__py3-none-any.whl

haveapi_client/__init__.py

@@ -0,0 +1,62 @@
+"""Dynamic clients for self-describing HaveAPI APIs."""
+
+from importlib.metadata import version
+
+from ._auth import (
+    AsyncAuthenticationChallenge,
+    Authenticated,
+    AuthenticationChallenge,
+    BasicAuth,
+    OAuth2Auth,
+    TokenAuth,
+)
+from ._protocol import RequestOptions
+from .async_client import AsyncClient
+from .client import Client
+from .exceptions import (
+    ActionError,
+    AuthenticationError,
+    HaveAPIError,
+    NotConnectedError,
+    OperationFailedError,
+    OperationTimeoutError,
+    PaginationError,
+    ProtocolError,
+    StaleDescriptionError,
+    TransportError,
+    ValidationError,
+)
+from .operations import AsyncOperation, Operation
+from .pagination import IdCursor
+from .response import ResourceObject, Response
+
+__version__ = version("haveapi-client")
+
+__all__ = [
+    "ActionError",
+    "AsyncAuthenticationChallenge",
+    "AsyncClient",
+    "AsyncOperation",
+    "Authenticated",
+    "AuthenticationChallenge",
+    "AuthenticationError",
+    "BasicAuth",
+    "Client",
+    "HaveAPIError",
+    "IdCursor",
+    "NotConnectedError",
+    "OAuth2Auth",
+    "Operation",
+    "OperationFailedError",
+    "OperationTimeoutError",
+    "PaginationError",
+    "ProtocolError",
+    "RequestOptions",
+    "ResourceObject",
+    "Response",
+    "StaleDescriptionError",
+    "TokenAuth",
+    "TransportError",
+    "ValidationError",
+    "__version__",
+]

haveapi_client/_auth/__init__.py

@@ -0,0 +1,139 @@
+"""Explicit authentication providers and resumable login outcomes."""
+
+from __future__ import annotations
+
+import base64
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Protocol
+
+from haveapi_client._protocol import Description, ParameterSpec
+from haveapi_client.exceptions import AuthenticationError
+
+_HEADER_NAME = re.compile(r"[!#$%&'*+.^_`|~0-9A-Za-z-]+\Z")
+_FORBIDDEN = {
+    "host",
+    "content-length",
+    "content-type",
+    "transfer-encoding",
+    "connection",
+    "trailer",
+    "te",
+    "upgrade",
+    "proxy-authorization",
+    "proxy-connection",
+    "accept",
+    "accept-language",
+    "user-agent",
+    "cookie",
+}
+
+
+class AuthProvider(Protocol):
+    @property
+    def method(self) -> str: ...
+
+    def headers(self, description: Description) -> Mapping[str, str]: ...
+
+
+def validate_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    seen: set[str] = set()
+    for name, value in headers.items():
+        if (
+            not isinstance(name, str)
+            or not _HEADER_NAME.fullmatch(name)
+            or name.lower() in _FORBIDDEN
+            or name.lower() in seen
+        ):
+            raise AuthenticationError("Invalid authentication header name")
+        if not isinstance(value, str) or any(
+            ord(c) < 32 or ord(c) > 126 for c in value
+        ):
+            raise AuthenticationError("Invalid authentication header value")
+        seen.add(name.lower())
+        result[name] = value
+    return result
+
+
+@dataclass(frozen=True)
+class BasicAuth:
+    username: str = field(repr=False)
+    password: str = field(repr=False)
+    method = "basic"
+
+    def headers(self, description: Description) -> Mapping[str, str]:
+        if ":" in self.username or any(
+            c in self.username + self.password for c in "\r\n"
+        ):
+            raise AuthenticationError("Invalid Basic credentials")
+        encoded = base64.b64encode(f"{self.username}:{self.password}".encode()).decode(
+            "ascii"
+        )
+        return {"Authorization": f"Basic {encoded}"}
+
+
+@dataclass(frozen=True)
+class TokenAuth:
+    token: str = field(repr=False)
+    method = "token"
+
+    def headers(self, description: Description) -> Mapping[str, str]:
+        provider = description.authentication.get(self.method)
+        header = provider.get("http_header") if provider is not None else None
+        if not isinstance(header, str):
+            raise AuthenticationError("Token provider has no valid HTTP header")
+        return validate_headers({header: self.token})
+
+
+@dataclass(frozen=True)
+class OAuth2Auth:
+    access_token: str = field(repr=False)
+    method = "oauth2"
+
+    def headers(self, description: Description) -> Mapping[str, str]:
+        return validate_headers({"Authorization": f"Bearer {self.access_token}"})
+
+
+@dataclass(frozen=True)
+class Authenticated:
+    token: str = field(repr=False)
+    valid_to: str | None = None
+
+
+@dataclass(frozen=True)
+class AuthenticationChallenge:
+    next_action: str
+    input: Mapping[str, ParameterSpec]
+    valid_to: str | None
+    _submit: Callable[
+        [Mapping[str, object]], Authenticated | AuthenticationChallenge
+    ] = field(repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "input", MappingProxyType(dict(self.input)))
+
+    def submit(
+        self, params: Mapping[str, object]
+    ) -> Authenticated | AuthenticationChallenge:
+        return self._submit(params)
+
+
+@dataclass(frozen=True)
+class AsyncAuthenticationChallenge:
+    next_action: str
+    input: Mapping[str, ParameterSpec]
+    valid_to: str | None
+    _submit: Callable[
+        [Mapping[str, object]], Awaitable[Authenticated | AsyncAuthenticationChallenge]
+    ] = field(repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "input", MappingProxyType(dict(self.input)))
+
+    async def submit(
+        self, params: Mapping[str, object]
+    ) -> Authenticated | AsyncAuthenticationChallenge:
+        return await self._submit(params)

haveapi_client/_protocol/__init__.py

@@ -0,0 +1,52 @@
+"""Transport-independent HaveAPI protocol 2 core."""
+
+from .description import (
+    lookup_action,
+    lookup_resource,
+    parse_description,
+    parse_resources,
+)
+from .execution import AsyncExecutor, SyncExecutor
+from .input import coerce_input
+from .models import (
+    ActionSpec,
+    CallContext,
+    DecodedResponse,
+    Description,
+    InputObject,
+    InputParams,
+    LayoutSpec,
+    ParameterSpec,
+    RequestOptions,
+    RequestSpec,
+    ResourceSpec,
+    WireResponse,
+)
+from .request import build_request, resolve_url
+from .response import decode_envelope, decode_response
+
+__all__ = [
+    "ActionSpec",
+    "AsyncExecutor",
+    "CallContext",
+    "DecodedResponse",
+    "Description",
+    "InputObject",
+    "InputParams",
+    "LayoutSpec",
+    "ParameterSpec",
+    "RequestOptions",
+    "RequestSpec",
+    "ResourceSpec",
+    "SyncExecutor",
+    "WireResponse",
+    "build_request",
+    "coerce_input",
+    "decode_envelope",
+    "decode_response",
+    "lookup_action",
+    "lookup_resource",
+    "parse_description",
+    "parse_resources",
+    "resolve_url",
+]

haveapi_client/_protocol/description.py

@@ -0,0 +1,176 @@
+"""Parse HaveAPI descriptions without rewriting server-owned names."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import cast
+
+from ..exceptions import ProtocolError
+from .models import (
+    ActionSpec,
+    Description,
+    LayoutSpec,
+    ParameterSpec,
+    ResourceSpec,
+    frozen_mapping,
+)
+
+PATH_PARAMETER = re.compile(r"\{([a-zA-Z0-9_-]+)\}")
+LAYOUTS = frozenset(("object", "object_list", "hash", "hash_list"))
+
+
+def mapping(value: object, label: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping) or not all(isinstance(k, str) for k in value):
+        raise ProtocolError(f"{label} must be an object with string keys")
+    return cast(Mapping[str, object], value)
+
+
+def _string(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ProtocolError(f"{label} must be a nonempty string")
+    return value
+
+
+def _boolean(raw: Mapping[str, object], name: str) -> bool:
+    value = raw.get(name, False)
+    if value is None:
+        return False
+    if not isinstance(value, bool):
+        raise ProtocolError(f"{name} must be boolean")
+    return value
+
+
+def parse_layout(value: object) -> LayoutSpec | None:
+    if value is None:
+        return None
+    raw = mapping(value, "layout")
+    layout = _string(raw.get("layout"), "layout type")
+    if layout not in LAYOUTS:
+        raise ProtocolError(f"unsupported layout: {layout}")
+    namespace = raw.get("namespace")
+    if namespace is False or namespace is None:
+        namespace = None
+    elif not isinstance(namespace, str) or not namespace:
+        raise ProtocolError("namespace must be a nonempty string or false")
+    parameters = {}
+    for name, entry in mapping(raw.get("parameters", {}), "parameters").items():
+        spec = mapping(entry, f"parameter {name}")
+        parameters[name] = ParameterSpec(
+            name,
+            _string(spec.get("type"), "parameter type"),
+            _boolean(spec, "required"),
+            _boolean(spec, "nullable"),
+            spec,
+        )
+    return LayoutSpec(layout, namespace, parameters, raw)
+
+
+def _action(name: str, value: object, resource_path: tuple[str, ...]) -> ActionSpec:
+    raw = mapping(value, f"action {name}")
+    method = _string(raw.get("method"), "action method").upper()
+    if method not in {"GET", "DELETE", "POST", "PUT"}:
+        raise ProtocolError(f"unsupported action method: {method}")
+    path = _string(raw.get("path"), "action path")
+    unmatched = PATH_PARAMETER.sub("", path)
+    if "{" in unmatched or "}" in unmatched:
+        raise ProtocolError("invalid action path template")
+    aliases = raw.get("aliases", ())
+    if not isinstance(aliases, (list, tuple)) or not all(
+        isinstance(v, str) for v in aliases
+    ):
+        raise ProtocolError("action aliases must be an array of strings")
+    meta = mapping(raw.get("meta") or {}, "action metadata")
+    for scope in ("global", "object"):
+        if meta.get(scope) is not None:
+            scope_raw = mapping(meta[scope], f"{scope} metadata")
+            parse_layout(scope_raw.get("input"))
+            parse_layout(scope_raw.get("output"))
+    return ActionSpec(
+        name,
+        resource_path,
+        method,
+        path,
+        tuple(PATH_PARAMETER.findall(path)),
+        tuple(cast(list[str], aliases)),
+        parse_layout(raw.get("input")),
+        parse_layout(raw.get("output")),
+        meta,
+        _boolean(raw, "blocking"),
+        _boolean(raw, "auth"),
+        raw,
+    )
+
+
+def parse_resources(
+    raw: Mapping[str, object], *, parent_path: tuple[str, ...] = ()
+) -> Mapping[str, ResourceSpec]:
+    resources = {}
+    for name, value in mapping(raw, "resources").items():
+        spec = mapping(value, f"resource {name}")
+        path = (*parent_path, name)
+        actions = {
+            action_name: _action(action_name, entry, path)
+            for action_name, entry in mapping(
+                spec.get("actions", {}), "actions"
+            ).items()
+        }
+        resources[name] = ResourceSpec(
+            name,
+            path,
+            parse_resources(
+                mapping(spec.get("resources", {}), "nested resources"), parent_path=path
+            ),
+            actions,
+            spec,
+        )
+    return frozen_mapping(resources)
+
+
+def parse_description(
+    envelope: Mapping[str, object], *, api_version: str | None = None
+) -> Description:
+    raw = mapping(envelope, "description envelope")
+    if raw.get("status") is not True:
+        raise ProtocolError("description envelope must indicate success")
+    protocol = raw.get("version")
+    if not isinstance(protocol, str) or not re.fullmatch(r"2\.[0-9]+", protocol):
+        raise ProtocolError(
+            "unsupported or missing protocol version (expected major 2)"
+        )
+    body = mapping(raw.get("response"), "API description")
+    resources = parse_resources(mapping(body.get("resources"), "resources"))
+    authentication = {
+        name: mapping(value, f"authentication {name}")
+        for name, value in mapping(
+            body.get("authentication", {}), "authentication"
+        ).items()
+    }
+    meta = mapping(body.get("meta", {}), "metadata description")
+    namespace = _string(meta.get("namespace", "_meta"), "metadata namespace")
+    return Description(
+        protocol, api_version, resources, authentication, namespace, body
+    )
+
+
+def lookup_resource(description: Description, path: tuple[str, ...]) -> ResourceSpec:
+    if not path:
+        raise KeyError("resource path cannot be empty")
+    resources = description.resources
+    for name in path:
+        resource = resources[name]
+        resources = resource.resources
+    return resource
+
+
+def lookup_action(
+    description: Description, resource_path: tuple[str, ...], name: str
+) -> ActionSpec:
+    resource = lookup_resource(description, resource_path)
+    if name in resource.actions:
+        return resource.actions[name]
+    matches = [a for a in resource.actions.values() if name in a.aliases]
+    if len(matches) != 1:
+        reason = "ambiguous" if matches else "unknown"
+        raise KeyError(f"{reason} action or alias: {name}")
+    return matches[0]

haveapi_client/_protocol/execution.py

@@ -0,0 +1,61 @@
+"""Execution boundary shared by the facade and response helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Protocol
+
+from .models import CallContext, Description, InputParams, RequestOptions
+
+if TYPE_CHECKING:
+    from ..response import Response
+
+
+class SyncExecutor(Protocol):
+    @property
+    def description(self) -> Description: ...
+
+    @property
+    def generation(self) -> int: ...
+
+    def resource(
+        self,
+        path: tuple[str, ...],
+        *,
+        bound_args: tuple[str | int, ...] = (),
+        path_params: Mapping[str, str | int] | None = None,
+    ) -> Any: ...
+
+    def execute(
+        self,
+        context: CallContext,
+        *,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Response[Any]: ...
+
+
+class AsyncExecutor(Protocol):
+    @property
+    def description(self) -> Description: ...
+
+    @property
+    def generation(self) -> int: ...
+
+    def resource(
+        self,
+        path: tuple[str, ...],
+        *,
+        bound_args: tuple[str | int, ...] = (),
+        path_params: Mapping[str, str | int] | None = None,
+    ) -> Any: ...
+
+    async def execute(
+        self,
+        context: CallContext,
+        *,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Response[Any]: ...

haveapi_client/_protocol/input.py

@@ -0,0 +1,161 @@
+"""Strict typed inputs from doc/typed-input-validation.md."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime
+
+from ..exceptions import ValidationError
+from .models import InputObject, InputParams, LayoutSpec, ParameterSpec
+
+_INTEGER = re.compile(r"[+-]?[0-9]+\Z")
+_FLOAT = re.compile(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?\Z")
+_DATETIME = re.compile(
+    r"[0-9]{4}-[0-9]{2}-[0-9]{2}"
+    r"(?:T[0-9]{2}:[0-9]{2}(?::[0-9]{2}(?:\.[0-9]+)?)?"
+    r"(?:Z|[+-][0-9]{2}:?[0-9]{2}))?\Z"
+)
+
+
+def json_value(value: object) -> object:
+    """Copy only finite JSON values; never stringify unknown objects."""
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float) and math.isfinite(value):
+        return value
+    if isinstance(value, Mapping) and all(isinstance(k, str) for k in value):
+        return {k: json_value(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [json_value(v) for v in value]
+    raise ValueError("not a finite JSON value")
+
+
+def _coerce(spec: ParameterSpec, value: object) -> object:
+    if value is None or (
+        spec.nullable and isinstance(value, str) and not value.strip()
+    ):
+        if spec.nullable and not spec.required:
+            return None
+        raise ValueError("cannot be null")
+    kind = spec.type
+    if kind == "Integer":
+        if type(value) is int:
+            return value
+        if isinstance(value, float) and math.isfinite(value) and value.is_integer():
+            return int(value)
+        if isinstance(value, str) and _INTEGER.fullmatch(value.strip()):
+            return int(value.strip(), 10)
+        raise ValueError("not a valid integer")
+    if kind == "Float":
+        if type(value) in (int, float) or (
+            isinstance(value, str) and _FLOAT.fullmatch(value.strip())
+        ):
+            try:
+                number = float(value)  # type: ignore[arg-type]
+                if math.isfinite(number):
+                    return number
+            except (ValueError, OverflowError):
+                pass
+        raise ValueError("not a valid float")
+    if kind == "Boolean":
+        if isinstance(value, bool):
+            return value
+        if type(value) is int and value in (0, 1):
+            return bool(value)
+        if isinstance(value, str):
+            token = value.strip().lower()
+            if token in ("true", "t", "yes", "y", "1"):
+                return True
+            if token in ("false", "f", "no", "n", "0"):
+                return False
+        raise ValueError("not a valid boolean")
+    if kind in ("String", "Text"):
+        if isinstance(value, str):
+            return value
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if type(value) is int or isinstance(value, float) and math.isfinite(value):
+            return str(value)
+        raise ValueError("not a valid string")
+    if kind == "Resource":
+        if type(value) is int and value >= 0:
+            return value
+        if isinstance(value, str) and re.fullmatch(r"[0-9]+", value.strip()):
+            return int(value.strip())
+        raise ValueError("not a valid resource ID")
+    if kind == "Datetime":
+        if isinstance(value, datetime):
+            if value.tzinfo is None or value.utcoffset() is None:
+                raise ValueError("not in ISO 8601 format")
+            value = value.isoformat()
+        elif isinstance(value, date):
+            value = value.isoformat()
+        if isinstance(value, str) and _DATETIME.fullmatch(value):
+            try:
+                if "T" in value:
+                    # fromisoformat validates dates and clock/offset components.
+                    datetime.fromisoformat(value)
+                    offset = re.search(r"[+-]([0-9]{2}):?([0-9]{2})$", value)
+                    if offset and (int(offset[1]) > 23 or int(offset[2]) > 59):
+                        raise ValueError("invalid offset")
+                else:
+                    date.fromisoformat(value)
+                return value
+            except ValueError:
+                pass
+        raise ValueError("not in ISO 8601 format")
+    if kind == "Custom":
+        return json_value(value)
+    raise ValueError(f"unsupported input parameter type: {kind}")
+
+
+def _coerce_object(layout: LayoutSpec, params: InputObject) -> InputObject:
+    if not all(isinstance(k, str) for k in params):
+        raise ValidationError("input keys must be strings")
+    errors: dict[str, object] = {
+        k: ["unknown parameter"] for k in params if k not in layout.parameters
+    }
+    result = {}
+    for name, spec in layout.parameters.items():
+        if name not in params:
+            if spec.required:
+                errors[name] = ["required parameter is missing"]
+            continue
+        try:
+            result[name] = _coerce(spec, params[name])
+        except ValueError as error:
+            errors[name] = [str(error)]
+    if errors:
+        raise ValidationError("input parameters are not valid", errors=errors)
+    return result
+
+
+def coerce_input(layout: LayoutSpec | None, params: InputParams | None) -> InputParams:
+    if layout is None:
+        if params:
+            raise ValidationError("action does not accept input parameters")
+        return {}
+    is_list = layout.layout in ("object_list", "hash_list")
+    if params is None:
+        params = [] if is_list else {}
+    if is_list:
+        if not isinstance(params, Sequence) or isinstance(params, (str, bytes)):
+            raise ValidationError("input layout requires a list of objects")
+        result = []
+        errors: dict[str, object] = {}
+        for index, row in enumerate(params):
+            if not isinstance(row, Mapping):
+                errors[str(index)] = ["input row must be an object"]
+                continue
+            try:
+                result.append(_coerce_object(layout, row))
+            except ValidationError as error:
+                errors[str(index)] = error.errors
+        if errors:
+            raise ValidationError("input parameters are not valid", errors=errors)
+        return result
+    if not isinstance(params, Mapping):
+        raise ValidationError("input layout requires an object")
+    return _coerce_object(layout, params)