morphiaone 0.1.0__py3-none-any.whl

morphiaone/__init__.py

@@ -0,0 +1,91 @@
+"""MorphiaOne SDK (Developer Preview): the V1 API client, its errors and retry policy.
+
+from morphiaone import MorphiaOne
+
+client = MorphiaOne(api_key=..., base_url=...)
+asset = client.assets.upload("face.jpg")
+job = client.skin.analyze(asset.id, ["acne"], wait=True)
+"""
+
+from .client import RetryPolicy
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    DeadlineExceeded,
+    InsufficientCreditsError,
+    InsufficientScopeError,
+    MorphiaOneError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    ProcessingError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    TransportError,
+    UnsupportedFeatureError,
+    ValidationError,
+)
+from .models import JobError, JobStatus
+from .v1 import (
+    Asset,
+    AssetContent,
+    AsyncMorphiaOne,
+    HairAppliedColorGradient,
+    HairAppliedColorStop,
+    HairTryOnApplied,
+    HairTryOnOutput,
+    Job,
+    JobInputRef,
+    JobOutput,
+    MakeupTryOnOutput,
+    MorphiaOne,
+    ResultAssetRef,
+    SkinAnalysisOutput,
+    SkinConcernResult,
+    UnknownJobOutput,
+    UsageReport,
+)
+
+__all__ = [
+    "ApiError",
+    "Asset",
+    "AssetContent",
+    "AsyncMorphiaOne",
+    "AuthenticationError",
+    "ConflictError",
+    "DeadlineExceeded",
+    "HairAppliedColorGradient",
+    "HairAppliedColorStop",
+    "HairTryOnApplied",
+    "HairTryOnOutput",
+    "InsufficientCreditsError",
+    "InsufficientScopeError",
+    "Job",
+    "JobError",
+    "JobInputRef",
+    "JobOutput",
+    "JobStatus",
+    "MakeupTryOnOutput",
+    "MorphiaOne",
+    "MorphiaOneError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "PermissionDeniedError",
+    "ProcessingError",
+    "ProtocolError",
+    "RateLimitError",
+    "ResultAssetRef",
+    "RetryPolicy",
+    "ServerError",
+    "ServiceUnavailableError",
+    "SkinAnalysisOutput",
+    "SkinConcernResult",
+    "TransportError",
+    "UnknownJobOutput",
+    "UnsupportedFeatureError",
+    "UsageReport",
+    "ValidationError",
+]

morphiaone/client.py

@@ -0,0 +1,499 @@
+"""The transport MorphiaOne and AsyncMorphiaOne share, and nothing else.
+
+The legacy public API this module once wrapped is retired; what stays is the request
+loop, the retry policy and the error table, which `v1.py` borrows through `_transport`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Self
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    DeadlineExceeded,
+    InsufficientCreditsError,
+    InsufficientScopeError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    ServiceUnavailableError,
+    TransportError,
+    UnsupportedFeatureError,
+    ValidationError,
+)
+
+#: The same set as the TypeScript client. The contract marks 429, 500 and 503
+#: retryable (`scripts/developer_docs.py` STATUS_MEANINGS); 408, 502 and 504 are a
+#: proxy's, never the API's, and a retry of them resends the same Idempotency-Key.
+#: 425 is not here: nothing in the contract answers it.
+_RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+#: Refusals a blind retry cannot cure (staff Gate F, B3): a daily quota resets on its
+#: own clock and a credit balance only moves when someone tops it up, so the SDK
+#: raises them at once, whatever `Retry-After` says.
+_NEVER_AUTO_RETRIED_CODES = frozenset({"QUOTA_EXCEEDED", "INSUFFICIENT_CREDITS"})
+#: A 429 the SDK retries only when the server says when: the account's own queue is
+#: full, and without a `Retry-After` there is no interval worth waiting.
+_RETRIED_ONLY_WITH_RETRY_AFTER = frozenset({"TENANT_QUEUE_LIMIT_EXCEEDED"})
+#: A server-named ``Retry-After`` is honoured as named, not shortened to ``max_delay``:
+#: a retry sent before the server said it would answer is refused again. Above this
+#: ceiling, or when the caller's deadline cannot hold the wait, the SDK raises the error
+#: (with ``retry_after`` set) instead of retrying early. Same values as TypeScript.
+RETRY_AFTER_CEILING = 60.0
+#: The poll interval when the server names none, and the floor under any it names, so a
+#: ``Retry-After: 0`` or ``max_delay=0`` never becomes a tight poll loop.
+_DEFAULT_POLL_INTERVAL = 1.0
+MIN_POLL_INTERVAL = 0.25
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    max_attempts: int = 4
+    base_delay: float = 0.25
+    max_delay: float = 5.0
+    jitter_ratio: float = 0.2
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be positive")
+        if self.base_delay < 0 or self.max_delay < 0:
+            raise ValueError("retry delays cannot be negative")
+        if self.base_delay > self.max_delay:
+            raise ValueError("base_delay cannot exceed max_delay")
+        if not 0 <= self.jitter_ratio <= 1:
+            raise ValueError("jitter_ratio must be between 0 and 1")
+
+
+class _Transport:
+    """One credentialed HTTP client with bounded, jittered retries."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        request_timeout: float = 10.0,
+        operation_timeout: float = 120.0,
+        max_image_bytes: int = 10 * 1024 * 1024,
+        retry_policy: RetryPolicy | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        _validate_client_options(
+            api_key, base_url, request_timeout, operation_timeout, max_image_bytes
+        )
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._request_timeout = request_timeout
+        self._operation_timeout = operation_timeout
+        self._max_image_bytes = max_image_bytes
+        self._retry_policy = retry_policy or RetryPolicy()
+        self._client = http_client or httpx.Client()
+        self._owns_client = http_client is None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def _request(
+        self,
+        send: Callable[[float], httpx.Response],
+        deadline: float,
+        *,
+        expected: set[int],
+    ) -> httpx.Response:
+        last_transport_error: httpx.TransportError | None = None
+        for attempt in range(self._retry_policy.max_attempts):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise DeadlineExceeded("operation deadline exceeded")
+            try:
+                response = send(min(self._request_timeout, remaining))
+            except httpx.TransportError as error:
+                last_transport_error = error
+                if attempt + 1 >= self._retry_policy.max_attempts:
+                    break
+                self._backoff(attempt, deadline)
+                continue
+            if response.status_code in expected:
+                return response
+            _refuse_redirect(response)
+            last = attempt + 1 >= self._retry_policy.max_attempts
+            if not last and _retryable_status(response):
+                retry_after = _retry_after_seconds(response.headers.get("Retry-After"))
+                if retry_after is None:
+                    self._backoff(attempt, deadline)
+                    continue
+                if _fits_server_wait(retry_after, deadline, self._retry_policy):
+                    time.sleep(_server_delay(retry_after, self._retry_policy))
+                    continue
+                raise _parse_api_error(response)
+            api_error = _parse_api_error(response)
+            retryable = (
+                response.status_code == 409
+                and api_error.code == "IDEMPOTENCY_IN_PROGRESS"
+            )
+            if not retryable or last:
+                raise api_error
+            if api_error.retry_after is None:
+                self._backoff(attempt, deadline)
+            elif _fits_server_wait(api_error.retry_after, deadline, self._retry_policy):
+                time.sleep(_server_delay(api_error.retry_after, self._retry_policy))
+            else:
+                raise api_error
+        if last_transport_error is not None:
+            raise TransportError(
+                "request failed after bounded retries"
+            ) from last_transport_error
+        raise DeadlineExceeded("operation deadline exceeded")
+
+    def _backoff(self, attempt: int, deadline: float) -> None:
+        base = self._retry_policy.base_delay * (2**attempt)
+        self._sleep(_jittered_delay(base, self._retry_policy), deadline)
+
+    @staticmethod
+    def _sleep(delay: float, deadline: float) -> None:
+        if delay >= deadline - time.monotonic():
+            raise DeadlineExceeded("operation deadline exceeded")
+        time.sleep(delay)
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+
+class _AsyncTransport:
+    """The asyncio twin of `_Transport`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        request_timeout: float = 10.0,
+        operation_timeout: float = 120.0,
+        max_image_bytes: int = 10 * 1024 * 1024,
+        retry_policy: RetryPolicy | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        _validate_client_options(
+            api_key, base_url, request_timeout, operation_timeout, max_image_bytes
+        )
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._request_timeout = request_timeout
+        self._operation_timeout = operation_timeout
+        self._max_image_bytes = max_image_bytes
+        self._retry_policy = retry_policy or RetryPolicy()
+        self._client = http_client or httpx.AsyncClient()
+        self._owns_client = http_client is None
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def _request(
+        self,
+        send: Callable[[float], Awaitable[httpx.Response]],
+        deadline: float,
+        *,
+        expected: set[int],
+    ) -> httpx.Response:
+        last_transport_error: httpx.TransportError | None = None
+        for attempt in range(self._retry_policy.max_attempts):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise DeadlineExceeded("operation deadline exceeded")
+            try:
+                response = await send(min(self._request_timeout, remaining))
+            except httpx.TransportError as error:
+                last_transport_error = error
+                if attempt + 1 >= self._retry_policy.max_attempts:
+                    break
+                await self._backoff(attempt, deadline)
+                continue
+            if response.status_code in expected:
+                return response
+            _refuse_redirect(response)
+            last = attempt + 1 >= self._retry_policy.max_attempts
+            if not last and _retryable_status(response):
+                retry_after = _retry_after_seconds(response.headers.get("Retry-After"))
+                if retry_after is None:
+                    await self._backoff(attempt, deadline)
+                    continue
+                if _fits_server_wait(retry_after, deadline, self._retry_policy):
+                    await asyncio.sleep(_server_delay(retry_after, self._retry_policy))
+                    continue
+                raise _parse_api_error(response)
+            api_error = _parse_api_error(response)
+            retryable = (
+                response.status_code == 409
+                and api_error.code == "IDEMPOTENCY_IN_PROGRESS"
+            )
+            if not retryable or last:
+                raise api_error
+            if api_error.retry_after is None:
+                await self._backoff(attempt, deadline)
+            elif _fits_server_wait(api_error.retry_after, deadline, self._retry_policy):
+                await asyncio.sleep(
+                    _server_delay(api_error.retry_after, self._retry_policy)
+                )
+            else:
+                raise api_error
+        if last_transport_error is not None:
+            raise TransportError(
+                "request failed after bounded retries"
+            ) from last_transport_error
+        raise DeadlineExceeded("operation deadline exceeded")
+
+    async def _backoff(self, attempt: int, deadline: float) -> None:
+        base = self._retry_policy.base_delay * (2**attempt)
+        await self._sleep(_jittered_delay(base, self._retry_policy), deadline)
+
+    @staticmethod
+    async def _sleep(delay: float, deadline: float) -> None:
+        if delay >= deadline - time.monotonic():
+            raise DeadlineExceeded("operation deadline exceeded")
+        await asyncio.sleep(delay)
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+
+def _validate_client_options(
+    api_key: str,
+    base_url: str,
+    request_timeout: float,
+    operation_timeout: float,
+    max_image_bytes: int,
+) -> None:
+    parsed = urlsplit(base_url)
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.netloc
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError("base_url must be an absolute HTTP(S) URL")
+    if not api_key:
+        raise ValueError("api_key cannot be empty")
+    if request_timeout <= 0 or operation_timeout <= 0:
+        raise ValueError("timeouts must be positive")
+    if operation_timeout < request_timeout:
+        raise ValueError("operation_timeout must be at least request_timeout")
+    if max_image_bytes < 1:
+        raise ValueError("max_image_bytes must be positive")
+
+
+def _deadline(timeout: float | None, default: float) -> float:
+    duration = default if timeout is None else timeout
+    if duration <= 0:
+        raise ValueError("timeout must be positive")
+    return time.monotonic() + duration
+
+
+def _jittered_delay(delay: float, policy: RetryPolicy) -> float:
+    """The client's own backoff, when the server named no ``Retry-After``.
+
+    Capped at ``max_delay``, positive jitter only. Same formula as TypeScript.
+    """
+    bounded = min(max(0.0, delay), policy.max_delay)
+    return min(
+        policy.max_delay,
+        bounded + random.uniform(0, bounded * policy.jitter_ratio),
+    )
+
+
+def _server_delay(retry_after: float, policy: RetryPolicy) -> float:
+    """A server-named wait: never shorter than it, jitter no larger than ``max_delay``."""
+    base = max(0.0, retry_after)
+    return base + random.uniform(0, min(base * policy.jitter_ratio, policy.max_delay))
+
+
+def _fits_server_wait(retry_after: float, deadline: float, policy: RetryPolicy) -> bool:
+    """Whether a server-named wait may be slept before the retry.
+
+    At most ``RETRY_AFTER_CEILING``, and short enough (jitter included) that the retry
+    still lands before the caller's deadline. Otherwise the caller raises the error.
+    """
+    if retry_after > RETRY_AFTER_CEILING:
+        return False
+    worst = retry_after + min(retry_after * policy.jitter_ratio, policy.max_delay)
+    return worst < deadline - time.monotonic()
+
+
+def _poll_delay(retry_after: float | None, policy: RetryPolicy) -> float:
+    """The wait between two polls of an unsettled job.
+
+    The server's ``Retry-After``, floored at ``MIN_POLL_INTERVAL`` and held under
+    ``RETRY_AFTER_CEILING``; 1 s when it names none. Independent of ``max_delay``,
+    which bounds the client's own retry backoff only.
+    """
+    named = _DEFAULT_POLL_INTERVAL if retry_after is None else retry_after
+    base = min(max(named, MIN_POLL_INTERVAL), RETRY_AFTER_CEILING)
+    return _server_delay(base, policy)
+
+
+def _refuse_redirect(response: httpx.Response) -> None:
+    """A redirect answer to a credentialed request is a fault, never a hop.
+
+    Every request this client sends carries the API key, and httpx strips only
+    ``Authorization`` when it follows a redirect to another origin -- ``X-API-Key``
+    would travel. So every call passes ``follow_redirects=False`` (an injected
+    ``http_client`` may have turned following on) and the answer is refused here,
+    before the error parser reads it as an unrelated envelope fault.
+    """
+    if 300 <= response.status_code < 400:
+        raise ProtocolError(
+            f"server answered HTTP {response.status_code} with a redirect; "
+            "a credentialed request is not followed"
+        )
+
+
+# One status, one class. Ordered widest-last so the specific entries win, and written
+# as a table rather than a chain because the table is what the contract-alignment test
+# reads: a status the runtime answers and this table does not name fails there.
+_ERROR_TYPES: dict[int, type[ApiError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    410: NotFoundError,
+    413: PayloadTooLargeError,
+    415: ValidationError,
+    422: ValidationError,
+    429: RateLimitError,
+    501: UnsupportedFeatureError,
+    503: ServiceUnavailableError,
+}
+
+
+# One code, one class, consulted before the status table. This is the narrow half of
+# the mapping and it stays narrow: an entry belongs here only when a code's remedy
+# differs from what its status alone implies. `INSUFFICIENT_SCOPE` qualifies -- the
+# other three codes the gateway answers 403 for are a disabled tenant, a disabled
+# account and an unrecognized key, and none of those is a scope problem.
+_ERROR_CODES: dict[str, type[ApiError]] = {
+    "INSUFFICIENT_SCOPE": InsufficientScopeError,
+}
+
+
+def _error_type(status_code: int, code: str = "") -> type[ApiError]:
+    """The class for one status, refined by code where the code says more.
+
+    The code is checked first because `error.code` is the machine contract and the
+    status is the coarser reading of it. Every class the code table can return is a
+    subclass of the one the status table returns for the same response, so a caller
+    who catches by status keeps catching it either way.
+
+    An unlisted 5xx -- other than 501/503 -- is `ServerError`, and any other unlisted
+    status `ApiError`, with every response field filled in, so a status this SDK does
+    not know yet is readable rather than a parsing failure.
+    """
+    refined = _ERROR_CODES.get(code)
+    if refined is not None:
+        return refined
+    named = _ERROR_TYPES.get(status_code)
+    if named is not None:
+        return named
+    return ServerError if status_code >= 500 else ApiError
+
+
+def _retryable_status(response: httpx.Response) -> bool:
+    """Whether a refusal is retried by its status, before its error is raised.
+
+    The three 429 codes are distinct (B3): `RATE_LIMITED` is retried, honouring
+    `Retry-After`; `TENANT_QUEUE_LIMIT_EXCEEDED` is retried only with a `Retry-After`;
+    `QUOTA_EXCEEDED` is never retried blindly. A 429 whose body names no code is
+    retried as a rate limit.
+    """
+    if response.status_code not in _RETRYABLE_STATUS_CODES:
+        return False
+    if response.status_code != 429:
+        return True
+    try:
+        code = response.json()["error"]["code"]
+    except (KeyError, TypeError, ValueError):
+        return True
+    if code in _NEVER_AUTO_RETRIED_CODES:
+        return False
+    if code in _RETRIED_ONLY_WITH_RETRY_AFTER:
+        return _retry_after_seconds(response.headers.get("Retry-After")) is not None
+    return True
+
+
+def _parse_api_error(response: httpx.Response) -> ApiError:
+    try:
+        payload = response.json()["error"]
+        code = payload["code"]
+        message = payload["message"]
+        details = payload.get("details", {})
+        request_id = payload.get("request_id")
+        if request_id is None:
+            request_id = response.headers.get("X-Request-Id")
+        if not isinstance(code, str) or not isinstance(message, str):
+            raise TypeError
+        if not isinstance(details, (dict, list)):
+            raise TypeError
+        if request_id is not None and not isinstance(request_id, str):
+            raise TypeError
+    except (KeyError, TypeError, json.JSONDecodeError) as error:
+        raise ProtocolError(
+            f"server returned an invalid error envelope for HTTP {response.status_code}"
+        ) from error
+    retry_after = _retry_after_seconds(response.headers.get("Retry-After"))
+    error_type = _error_type(response.status_code, code)
+    return error_type(
+        message,
+        status=response.status_code,
+        code=code,
+        details=details,
+        request_id=request_id,
+        retry_after=retry_after,
+    )
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    if normalized.isdigit():
+        return float(normalized)
+    try:
+        retry_at = parsedate_to_datetime(normalized)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if retry_at is None:
+        return None
+    if retry_at.tzinfo is None:
+        retry_at = retry_at.replace(tzinfo=timezone.utc)
+    return max(0.0, (retry_at - datetime.now(timezone.utc)).total_seconds())