elmo-sdk 0.1.0__py3-none-any.whl

elmo_sdk/__init__.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._internal.binding.rest.errors import (
+        AuthenticationError,
+        BadRequestError,
+        ConflictError,
+        InternalServerError,
+        NotFoundError,
+        PaymentRequiredError,
+        PermissionDeniedError,
+        RateLimitError,
+        UnprocessableEntityError,
+    )
+    from ._internal.core.backoff import Jitter, RetryAfterHeader
+    from ._internal.core.errors import (
+        APIError,
+        DecodeError,
+        ElmoError,
+        FailureBody,
+        MissingCredentialError,
+        TransportError,
+        TransportTimeoutError,
+    )
+    from ._internal.core.missing import MISSING, Missing
+    from ._internal.core.response import Response
+    from ._internal.core.types import (
+        AsyncAuthResolver,
+        AsyncAuthValue,
+        AsyncCredentialValue,
+        AuthResolver,
+        AuthScheme,
+        AuthToken,
+        AuthValue,
+        CallTimeout,
+        CredentialValue,
+        PhasedTimeout,
+        PreparedRequest,
+        RawResponse,
+        Result,
+        RetryOptions,
+        RetryValue,
+        TimeoutPolicy,
+        TimeoutValue,
+    )
+    from ._internal.feature.interceptors import (
+        ErrorHook,
+        Interceptors,
+        RequestHook,
+        ResponseHook,
+    )
+    from ._internal.feature.logger import LogLevel
+    from ._internal.page.page import AsyncPage, Page
+    from ._internal.transport.httpx import AsyncHttpxLike, HttpxLike
+    from .client import AsyncElmo, Elmo, __version__
+    from .resources.shared.request_options import AsyncRequestOptions, RequestOptions
+
+__all__ = [
+    "MISSING",
+    "APIError",
+    "AsyncAuthResolver",
+    "AsyncAuthValue",
+    "AsyncCredentialValue",
+    "AsyncElmo",
+    "AsyncHttpxLike",
+    "AsyncPage",
+    "AsyncRequestOptions",
+    "AuthResolver",
+    "AuthScheme",
+    "AuthToken",
+    "AuthValue",
+    "AuthenticationError",
+    "BadRequestError",
+    "CallTimeout",
+    "ConflictError",
+    "CredentialValue",
+    "DecodeError",
+    "Elmo",
+    "ElmoError",
+    "ErrorHook",
+    "FailureBody",
+    "HttpxLike",
+    "Interceptors",
+    "InternalServerError",
+    "Jitter",
+    "LogLevel",
+    "Missing",
+    "MissingCredentialError",
+    "NotFoundError",
+    "Page",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "PhasedTimeout",
+    "PreparedRequest",
+    "RateLimitError",
+    "RawResponse",
+    "RequestHook",
+    "RequestOptions",
+    "Response",
+    "ResponseHook",
+    "Result",
+    "RetryAfterHeader",
+    "RetryOptions",
+    "RetryValue",
+    "TimeoutPolicy",
+    "TimeoutValue",
+    "TransportError",
+    "TransportTimeoutError",
+    "UnprocessableEntityError",
+    "__version__",
+]
+
+
+_LAZY_EXPORTS = {
+    "APIError": ("._internal.core.errors", "APIError"),
+    "AsyncAuthResolver": ("._internal.core.types", "AsyncAuthResolver"),
+    "AsyncAuthValue": ("._internal.core.types", "AsyncAuthValue"),
+    "AsyncCredentialValue": ("._internal.core.types", "AsyncCredentialValue"),
+    "AsyncElmo": (".client", "AsyncElmo"),
+    "AsyncHttpxLike": ("._internal.transport.httpx", "AsyncHttpxLike"),
+    "AsyncPage": ("._internal.page.page", "AsyncPage"),
+    "AsyncRequestOptions": (".resources.shared.request_options", "AsyncRequestOptions"),
+    "AuthResolver": ("._internal.core.types", "AuthResolver"),
+    "AuthScheme": ("._internal.core.types", "AuthScheme"),
+    "AuthToken": ("._internal.core.types", "AuthToken"),
+    "AuthValue": ("._internal.core.types", "AuthValue"),
+    "AuthenticationError": ("._internal.binding.rest.errors", "AuthenticationError"),
+    "BadRequestError": ("._internal.binding.rest.errors", "BadRequestError"),
+    "CallTimeout": ("._internal.core.types", "CallTimeout"),
+    "ConflictError": ("._internal.binding.rest.errors", "ConflictError"),
+    "CredentialValue": ("._internal.core.types", "CredentialValue"),
+    "DecodeError": ("._internal.core.errors", "DecodeError"),
+    "Elmo": (".client", "Elmo"),
+    "ElmoError": ("._internal.core.errors", "ElmoError"),
+    "ErrorHook": ("._internal.feature.interceptors", "ErrorHook"),
+    "FailureBody": ("._internal.core.errors", "FailureBody"),
+    "HttpxLike": ("._internal.transport.httpx", "HttpxLike"),
+    "Interceptors": ("._internal.feature.interceptors", "Interceptors"),
+    "InternalServerError": ("._internal.binding.rest.errors", "InternalServerError"),
+    "Jitter": ("._internal.core.backoff", "Jitter"),
+    "LogLevel": ("._internal.feature.logger", "LogLevel"),
+    "MISSING": ("._internal.core.missing", "MISSING"),
+    "Missing": ("._internal.core.missing", "Missing"),
+    "MissingCredentialError": ("._internal.core.errors", "MissingCredentialError"),
+    "NotFoundError": ("._internal.binding.rest.errors", "NotFoundError"),
+    "Page": ("._internal.page.page", "Page"),
+    "PaymentRequiredError": ("._internal.binding.rest.errors", "PaymentRequiredError"),
+    "PermissionDeniedError": (
+        "._internal.binding.rest.errors",
+        "PermissionDeniedError",
+    ),
+    "PhasedTimeout": ("._internal.core.types", "PhasedTimeout"),
+    "PreparedRequest": ("._internal.core.types", "PreparedRequest"),
+    "RateLimitError": ("._internal.binding.rest.errors", "RateLimitError"),
+    "RawResponse": ("._internal.core.types", "RawResponse"),
+    "RequestHook": ("._internal.feature.interceptors", "RequestHook"),
+    "RequestOptions": (".resources.shared.request_options", "RequestOptions"),
+    "Response": ("._internal.core.response", "Response"),
+    "ResponseHook": ("._internal.feature.interceptors", "ResponseHook"),
+    "Result": ("._internal.core.types", "Result"),
+    "RetryAfterHeader": ("._internal.core.backoff", "RetryAfterHeader"),
+    "RetryOptions": ("._internal.core.types", "RetryOptions"),
+    "RetryValue": ("._internal.core.types", "RetryValue"),
+    "TimeoutPolicy": ("._internal.core.types", "TimeoutPolicy"),
+    "TimeoutValue": ("._internal.core.types", "TimeoutValue"),
+    "TransportError": ("._internal.core.errors", "TransportError"),
+    "TransportTimeoutError": ("._internal.core.errors", "TransportTimeoutError"),
+    "UnprocessableEntityError": (
+        "._internal.binding.rest.errors",
+        "UnprocessableEntityError",
+    ),
+    "__version__": (".client", "__version__"),
+}
+
+
+if not TYPE_CHECKING:
+
+    def __getattr__(name: str) -> object:
+        if name not in _LAZY_EXPORTS:
+            raise AttributeError(f"module {__name__} has no attribute {name}")
+        module, attribute = _LAZY_EXPORTS[name]
+        value = getattr(import_module(module, __name__), attribute)
+        globals()[name] = value
+        return value
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

elmo_sdk/_internal/binding/rest/binding.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import codecs
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ...codec.registry import essence_of
+from ...core.config import base_url_of
+from ...core.errors import ElmoError
+from ...core.types import (
+    Credential,
+    OperationDescriptor,
+    PreparedRequest,
+    RawResponse,
+    Result,
+)
+from .errors import to_api_error, unreadable_body
+from .url import BuildURL
+
+DEFAULT_ACCEPT = "application/json"
+
+
+def place_in_header(credential: Credential, request: PreparedRequest) -> None:
+    request.meta[credential.name.lower()] = credential.value
+
+
+Placer = Callable[[Credential, PreparedRequest], None]
+
+
+PLACERS: dict[str, Placer] = {"header": place_in_header}
+
+
+def parser_for(content_type: str) -> str:
+    if not content_type:
+        return "text"
+    essence = essence_of(content_type)
+    if essence == "application/json" or essence.endswith("+json"):
+        return "json"
+    if essence.startswith("text/"):
+        return "text"
+    return "bytes"
+
+
+def asks_for_json(request: PreparedRequest) -> bool:
+    accept = request.meta.get("accept", "")
+    return accept != "" and all(parser_for(one) == "json" for one in accept.split(","))
+
+
+def json_or_text(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+WINDOWS_1252 = ("ascii", "iso8859-1")
+
+
+def charset_of(content_type: str) -> str | None:
+    for param in content_type.split(";")[1:]:
+        name, _, value = param.partition("=")
+        if name.strip().lower() == "charset":
+            return value.strip().strip('"')
+    return None
+
+
+def read_text(raw: RawResponse, json_body: bool, ok: bool) -> str:
+    label = None if json_body else charset_of(raw.headers.get("content-type", ""))
+    try:
+        name = codecs.lookup(label or "utf-8").name
+    except LookupError:
+        name = "utf-8"
+    if name in WINDOWS_1252:
+        name = "cp1252"
+    elif name == "utf-8":
+        name = "utf-8-sig"
+    try:
+        return raw.content.decode(name, "strict" if ok else "replace")
+    except UnicodeDecodeError as cause:
+        raise unreadable_body(raw, cause) from cause
+
+
+@dataclass
+class RestBinding:
+    build_url: BuildURL
+    accept: str | None = DEFAULT_ACCEPT
+    name: str = "rest"
+
+    def apply_auth(self, credential: Credential, request: PreparedRequest) -> None:
+        place = PLACERS.get(credential.location)
+        if place is None:
+            where = credential.location
+            address = request.operation.address
+            raise ElmoError(
+                f'This client places no credential in the {where}, so "{address}" cannot be authenticated.',
+            )
+        place(credential, request)
+
+    def read_error(
+        self, result: Result, request: PreparedRequest
+    ) -> BaseException | None:
+        response = result.response
+        if (
+            response is None
+            or 200 <= response.status_code < 300
+            and result.error is None
+        ):
+            return None
+        return to_api_error(response.status_code, result.error, response)
+
+    def read_result(self, raw: RawResponse, request: PreparedRequest) -> Result:
+        ok = 200 <= raw.status_code < 300
+        if raw.status_code in (204, 205):
+            return Result(response=raw) if ok else Result(error=None, response=raw)
+        parser = parser_for(raw.headers.get("content-type", ""))
+        if parser == "bytes":
+            value: Any = raw.content
+        else:
+            text = read_text(raw, parser == "json", ok)
+            if text == "":
+                value = None
+            elif parser == "json":
+                try:
+                    value = json.loads(text)
+                except ValueError as cause:
+                    if ok:
+                        raise unreadable_body(raw, cause) from cause
+                    value = text
+            else:
+                value = json_or_text(text) if asks_for_json(request) else text
+        return (
+            Result(data=value, response=raw)
+            if ok
+            else Result(error=value, response=raw)
+        )
+
+    def resolve_address(
+        self, operation: OperationDescriptor, options: dict[str, Any]
+    ) -> str:
+        return self.build_url(
+            address=operation.address,
+            base_url=base_url_of(options, operation.base_url),
+            path=options.get("path"),
+            query=options.get("query"),
+            serialization=operation.serialization,
+        )
+
+
+def create_rest_binding(build_url: BuildURL) -> RestBinding:
+    return RestBinding(build_url=build_url)

elmo_sdk/_internal/binding/rest/encode.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from ...core.text import to_text
+
+_UNRESERVED = "!'()*-._~"
+
+
+def encode_component(value: Any) -> str:
+    return quote(to_text(value), safe=_UNRESERVED)
+
+
+def encode_name(name: str) -> str:
+    return encode_component(name).replace("%5B", "[").replace("%5D", "]")

elmo_sdk/_internal/binding/rest/errors.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any
+
+from ...core.errors import APIError, DecodeError, safe_address
+from ...core.types import RawResponse
+
+if TYPE_CHECKING:
+    from ....types.shared.error import Error
+
+
+def unreadable_body(
+    response: RawResponse, cause: BaseException | None = None
+) -> DecodeError:
+    url = getattr(response, "url", "") or ""
+    where = f' for "{safe_address(url)}"' if url else ""
+    headers: Mapping[str, str] = getattr(response, "headers", None) or {}
+    content_type = headers.get("content-type")
+    said = f' Its content type said "{content_type}".' if content_type else ""
+    error = DecodeError(
+        f"The API answered {response.status_code}{where} with a body this client could not read.{said}",
+        response=response,
+    )
+    error.__cause__ = cause
+    return error
+
+
+class BadRequestError(APIError["Error"]):
+    """The API could not read the request, so it did not act on it."""
+
+    data: Error | None
+
+
+class AuthenticationError(APIError["Error"]):
+    """No usable credential reached the API: it was missing, unreadable, or rejected."""
+
+    data: Error | None
+
+
+class PaymentRequiredError(APIError["Error"]):
+    """The plan or the quota on this account does not cover the call."""
+
+    data: Error | None
+
+
+class PermissionDeniedError(APIError["Error"]):
+    """The credential was accepted, but it does not grant this call."""
+
+    data: Error | None
+
+
+class NotFoundError(APIError["Error"]):
+    """Nothing is at this address, or the credential may not see what is."""
+
+    data: Error | None
+
+
+class ConflictError(APIError["Error"]):
+    """The call collided with the resource's current state: a duplicate, or a concurrent
+    change.
+    """
+
+    data: Error | None
+
+
+class UnprocessableEntityError(APIError):
+    """The request was read, and its contents were rejected."""
+
+
+class RateLimitError(APIError["Error"]):
+    """Too many calls. `retry_after_seconds` carries how long the API asked to wait."""
+
+    data: Error | None
+
+
+APIErrorClass = Callable[..., APIError]
+
+
+BY_STATUS: dict[int, APIErrorClass] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+class InternalServerError(APIError["Error"]):
+    """The API failed after accepting the call. Every status from 500 up arrives as
+    this.
+    """
+
+    data: Error | None
+
+
+def to_api_error(
+    status: int,
+    body: Any,
+    response: RawResponse,
+    unauthenticated: Callable[[], str] | None = None,
+) -> APIError:
+    failure = BY_STATUS.get(status) or (
+        InternalServerError if status >= 500 else APIError
+    )
+    note = unauthenticated() if unauthenticated and status in (401, 403) else None
+    return failure(status, body, response, note)

elmo_sdk/_internal/binding/rest/url.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from typing import Any, Protocol, cast
+
+from ...codec.json import dumped
+from ...core.errors import empty_path_parameter
+from ...core.types import SerializationDescriptor
+from .encode import encode_component, encode_name
+
+
+class BuildURL(Protocol):
+    def __call__(
+        self,
+        *,
+        address: str,
+        base_url: str | None = None,
+        path: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        serialization: SerializationDescriptor | None = None,
+    ) -> str: ...
+
+
+PATH_PARAM_RE = re.compile(r"\{[^{}]+\}")
+
+
+ABSOLUTE_URL_RE = re.compile(r"^[a-z][a-z\d+.-]*://", re.IGNORECASE | re.ASCII)
+
+
+def join_url(base_url: str | None, path: str) -> str:
+    base = (base_url or "").partition("#")[0]
+    kept, _, query = base.partition("?")
+    if kept.endswith("/") and path.startswith("/"):
+        path = path[1:]
+    joined = kept + path
+    if not query:
+        return joined
+    return f"{joined}{'&' if '?' in joined else '?'}{query}"
+
+
+def address_url(address: str, base_url: str | None) -> str:
+    absolute = bool(ABSOLUTE_URL_RE.match(address))
+    path_url = address if absolute or address.startswith("/") else "/" + address
+    return path_url if absolute else join_url(base_url, path_url)
+
+
+def path_value(value: Any) -> str:
+    if isinstance(value, (list, tuple)):
+        return ",".join(encode_component(item) for item in cast(Sequence[Any], value))
+    if isinstance(value, dict):
+        parts: list[str] = []
+        for key, item in cast(dict[str, Any], value).items():
+            parts.append(encode_component(key))
+            parts.append(encode_component(item))
+        return ",".join(parts)
+    return encode_component(value)
+
+
+def filled_url(address: str, base_url: str | None, path: dict[str, Any] | None) -> str:
+    path = dumped(path)
+    url = address_url(address, base_url)
+    if not path:
+        return url
+
+    def substitute(match: re.Match[str]) -> str:
+        name = match.group()[1:-1]
+        value = path.get(name)
+        if value is None or value == "":
+            raise empty_path_parameter(name, address)
+        return path_value(value)
+
+    return PATH_PARAM_RE.sub(substitute, url)
+
+
+def with_query(url: str, query: dict[str, Any] | None) -> str:
+    query = dumped(query)
+    if not query:
+        return url
+    search: list[str] = []
+    for name, value in query.items():
+        if isinstance(value, dict):
+            pairs: Iterable[tuple[str, Any]] = cast(dict[str, Any], value).items()
+        elif isinstance(value, (list, tuple)):
+            pairs = [(name, item) for item in cast(Sequence[Any], value)]
+        else:
+            pairs = [(name, value)]
+        for key, item in pairs:
+            if item is not None:
+                search.append(f"{encode_name(key)}={encode_component(item)}")
+    if not search:
+        return url
+    return f"{url}{'&' if '?' in url else '?'}{'&'.join(search)}"
+
+
+def simple_url(
+    *,
+    address: str,
+    base_url: str | None = None,
+    path: dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+    serialization: SerializationDescriptor | None = None,
+) -> str:
+    return with_query(filled_url(address, base_url, path), query)

elmo_sdk/_internal/codec/json.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import numbers
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import date, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from ipaddress import IPv4Address, IPv6Address
+from typing import Any, TypeGuard, cast
+from uuid import UUID
+
+from ..core.errors import ElmoError
+from ..core.types import EncodedBody
+
+
+def is_mapping(value: Any) -> TypeGuard[Mapping[Any, Any]]:
+    return isinstance(value, Mapping)
+
+
+def is_sequence(value: Any) -> bool:
+    if isinstance(value, (str, bytes, bytearray, memoryview)):
+        return False
+    return isinstance(value, Sequence)
+
+
+def iso_duration(value: timedelta) -> str:
+    sign = "-" if value < timedelta(0) else ""
+    value = abs(value)
+    hours, rest = divmod(value.seconds, 3600)
+    minutes, seconds = divmod(rest, 60)
+    clock = ""
+    if hours:
+        clock += f"{hours}H"
+    if minutes:
+        clock += f"{minutes}M"
+    if value.microseconds:
+        clock += f"{seconds}.{value.microseconds:06d}".rstrip("0") + "S"
+    elif seconds or not (value.days or clock):
+        clock += f"{seconds}S"
+    days = f"{value.days}D" if value.days else ""
+    return f"{sign}P{days}T{clock}" if clock else f"{sign}P{days}"
+
+
+def type_name(value: Any) -> str:
+    kind: type[Any] = value.__class__
+    if kind.__module__ == "builtins":
+        return kind.__qualname__
+    return f"{kind.__module__}.{kind.__qualname__}"
+
+
+def as_json(value: Any) -> Any:
+    dump = getattr(value, "model_dump", None)
+    if dump is not None:
+        return dump(by_alias=True, exclude_unset=True, mode="json")
+    serializer = getattr(value.__class__, "__pydantic_serializer__", None)
+    if serializer is not None:
+        return serializer.to_python(value, mode="json")
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (date, time)):
+        return value.isoformat()
+    if isinstance(value, timedelta):
+        return iso_duration(value)
+    if isinstance(value, (Decimal, IPv4Address, IPv6Address, UUID)):
+        return str(value)
+    if is_mapping(value):
+        return dict(value)
+    if isinstance(value, (set, frozenset)) or is_sequence(value):
+        return list(cast(Iterable[Any], value))
+    if isinstance(value, numbers.Integral):
+        return int(value)
+    if isinstance(value, numbers.Real):
+        return float(value)
+    raise ElmoError(f"A value of type {type_name(value)} cannot be written as JSON.")
+
+
+def json_text(value: Any) -> str:
+    try:
+        return json.dumps(
+            value,
+            allow_nan=False,
+            default=as_json,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+    except (RecursionError, TypeError, ValueError) as error:
+        if str(error).startswith("Out of range float values"):
+            raise ElmoError("NaN and Infinity cannot be written as JSON.") from None
+        raise ElmoError(f"A value cannot be written as JSON: {error}") from error
+
+
+@dataclass
+class JSONCodec:
+    media_types: list[str] = field(default_factory=lambda: ["application/json"])
+    name: str = "json"
+
+    def encode(self, value: Any) -> EncodedBody:
+        return EncodedBody(
+            payload=json_text(value).encode("utf-8"), content_type="application/json"
+        )
+
+
+json_codec = JSONCodec()
+
+
+def dumped(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return as_json(value)
+    if is_mapping(value):
+        return {key: dumped(item) for key, item in value.items()}
+    if is_sequence(value):
+        return [dumped(item) for item in cast(Sequence[Any], value)]
+    return value