hushscript 1.0.0__py3-none-any.whl

hushscript/_errors.py

@@ -0,0 +1,563 @@
+from __future__ import annotations
+
+import json
+import math
+import re
+import sys
+import traceback
+from typing import TYPE_CHECKING, Any, ClassVar, Final
+
+import httpx
+
+from ._json import as_dict, as_list, loads
+from ._redact import Credentials, Secret, redact, redact_queries
+from .generated.catalog import ERROR_CATALOG
+from .generated.hints import HINTS
+from .generated.scopes import OPERATION_SCOPES
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def add_note(error: BaseException, note: str) -> None:
+    if sys.version_info >= (3, 11):
+        error.add_note(note)
+    else:
+        notes = getattr(error, "__notes__", [])
+        notes.append(note)
+        vars(error)["__notes__"] = notes
+
+
+_PLACEHOLDER: Final = re.compile(r"\{(\w+)\}")
+_SENTENCE_BREAK: Final = re.compile(r"(?<=\.) ")
+_TEMPLATE_PARAMETER: Final = re.compile(r"\\\{[^}/]+\\\}")
+_JOB_OR_UPLOAD: Final = re.compile(r"^[A-Z]+ /v1/(?:jobs|uploads)(?:/|$)")
+_INT_LIMIT: Final = 2**63
+"""Numbers the SDK reads stay inside a signed 64-bit range; beyond it, or not finite, they are
+absent."""
+_MAX_RETRY_AFTER_DIGITS: Final = 19
+RETRY_AFTER_CAP: Final = float(2**53 - 1)
+"""R71: a Retry-After that is a non-negative integer, however large, is "over 60" and reported at
+most this."""
+
+
+def _camel(key: str) -> str:
+    head, *rest = key.split("_")
+    return head + "".join(part[:1].upper() + part[1:] for part in rest)
+
+
+def _snake(key: str) -> str:
+    return re.sub(r"(?<=[a-z0-9])([A-Z])", lambda match: "_" + match.group(1).lower(), key)
+
+
+def _snake_keys(value: object) -> object:
+    """Spec 9.3: details keys follow the language convention (snake_case here), recursively."""
+    mapping = as_dict(value)
+    if mapping is not None:
+        return {_snake(key): _snake_keys(item) for key, item in mapping.items()}
+    items = as_list(value)
+    if items is not None:
+        return [_snake_keys(item) for item in items]
+    return value
+
+
+def _number(value: object) -> float | None:
+    """`value` when it is a finite number inside the 64-bit range, else None (absent)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    return value if abs(value) < _INT_LIMIT else None
+
+
+def _format_number(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+def _format_context_value(value: object) -> str | None:
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, (int, float)):
+        usable = _number(value)
+        return None if usable is None else _format_number(usable)
+    items = as_list(value)
+    if items is not None:
+        return ", ".join(str(item) for item in items)
+    return str(value)
+
+
+def _minutes(details: Mapping[str, object], keys: tuple[str, ...], *, up: bool) -> str | None:
+    for key in keys:
+        seconds = _number(details.get(key))
+        if seconds is not None:
+            return str(math.ceil(seconds / 60) if up else math.floor(seconds / 60))
+    return None
+
+
+def _retry_after_detail(value: object) -> float | None:
+    """R71: `retry_after_seconds` as a number of seconds, capped; negative, non-finite and
+    non-numeric values are absent."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    return None if value < 0 else float(min(value, RETRY_AFTER_CAP))
+
+
+def _whole_seconds(retry_after: float | None, from_details: object) -> str | None:
+    seconds = retry_after if retry_after is not None else _retry_after_detail(from_details)
+    return None if seconds is None else str(math.ceil(seconds))
+
+
+def _hint_context(
+    details: Mapping[str, object], retry_after: float | None, scope: str | None
+) -> dict[str, str]:
+    formatted = {_camel(key): _format_context_value(value) for key, value in details.items()}
+    context = {name: text for name, text in formatted.items() if text is not None}
+    derived = {
+        "needed": _minutes(details, ("needed_seconds",), up=True),
+        "balance": _minutes(details, ("balance_seconds",), up=False),
+        "used": _minutes(details, ("used_seconds", "used_today_seconds"), up=False),
+        "max": _minutes(details, ("max_seconds", "max_daily_seconds"), up=False),
+        "retryAfter": _whole_seconds(retry_after, details.get("retry_after_seconds")),
+        "scope": scope,
+    }
+    context.update({name: value for name, value in derived.items() if value is not None})
+    return context
+
+
+def render_hint(
+    code: str,
+    details: Mapping[str, object] | None = None,
+    retry_after: float | None = None,
+    scope: str | None = None,
+) -> str | None:
+    """Spec 9.3 rendering: split after each ". ", drop the sentences with an unfilled placeholder,
+    join the rest with a space; nothing left is None."""
+    template = HINTS.get(code)
+    if template is None:
+        return None
+    context = _hint_context(details or {}, retry_after, scope)
+    kept = [
+        _PLACEHOLDER.sub(lambda match: context[match.group(1)], sentence)
+        for sentence in _SENTENCE_BREAK.split(template)
+        if all(name in context for name in _PLACEHOLDER.findall(sentence))
+    ]
+    return " ".join(kept) or None
+
+
+class HushscriptError(Exception):
+    default_code: ClassVar[str] = "hushscript_error"
+    auto_hint: ClassVar[bool] = True
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        numeric_code: int | None = None,
+        status: int | None = None,
+        hint: str | None = None,
+        details: Mapping[str, object] | None = None,
+        retry_after: float | None = None,
+        scope: str | None = None,
+    ) -> None:
+        self.code: str = code or self.default_code
+        self.numeric_code: int | None = numeric_code
+        self.status: int | None = status
+        self.details: dict[str, object] = dict(details or {})
+        self.retry_after: float | None = retry_after
+        self.idempotency_key: str | None = None
+        """Set on every error `transcribe()` raises once its create was sent (spec 7.3): passing it
+        back to `transcribe()` replays the same job."""
+        self.resume_token: str | None = None
+        self._unsent = False
+        if hint is None and self.auto_hint:
+            hint = render_hint(self.code, self.details, retry_after, scope)
+        self.hint: str | None = redact_queries(redact(hint)) if hint is not None else None
+        self.message: str = redact_queries(redact(message))
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return f"{self.message} {self.hint}" if self.hint else self.message
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(code={self.code!r}, status={self.status!r}, "
+            f"message={self.message!r})"
+        )
+
+
+def mark_unsent(error: HushscriptError) -> None:
+    """R103: the request provably never went out, so a purchase key must not ride along."""
+    error._unsent = True  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]  # the one writer
+
+
+def is_unsent(error: HushscriptError) -> bool:
+    return error._unsent  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]  # the one reader
+
+
+class _RedactedCause(Exception):  # noqa: N818  # a stand-in for an exception, never raised by name
+    """What an unexpected failure looked like, with tokens and signed-URL queries removed."""
+
+
+UNEXPECTED: Final = "unexpected_error"
+
+
+def describe_failure(failure: BaseException, credentials: Credentials | None = None) -> str:
+    """R86: the original's type and its message, with tokens and signed-URL queries removed. A
+    message that is blank, or whose own text breaks, leaves the type alone."""
+    name = type(failure).__name__
+    try:
+        text = str(failure)
+    except Exception:  # noqa: BLE001  # an exception whose own text breaks still has a name
+        text = ""
+    if not text.strip():
+        return name
+    scrubbed = credentials.scrub(text) if credentials is not None else redact(text)
+    return f"{name}: {redact_queries(scrubbed)}"
+
+
+def redacted_cause(failure: BaseException, credentials: Credentials | None = None) -> BaseException:
+    """R86: what stands in for a foreign exception as the cause of an SDK error. The original
+    cannot be redacted in place: an HTTP error keeps the request it sent (bearer header, signed
+    URL, body) and a JSON error keeps the whole text it read. The stand-in has its type and
+    redacted message, and its traceback with the locals of every finished frame cleared, so the
+    HTTP library's frames no longer hold their copy of the request either."""
+    traceback.clear_frames(failure.__traceback__)
+    return _RedactedCause(describe_failure(failure, credentials)).with_traceback(
+        failure.__traceback__
+    )
+
+
+_SENT: Final[dict[bool | None, str]] = {
+    True: " after the request was sent",
+    False: " before the request was sent",
+    None: "",
+}
+
+
+def unexpected_error(
+    failure: BaseException, credentials: Credentials | None = None, *, sent: bool | None = None
+) -> HushscriptError:
+    """Spec 9.2: a failure inside the SDK that fits no other class. The message names the
+    original's type and redacted message (R86) and says whether the request was sent only when
+    `sent` says the SDK knows (R100); the original rides along as a redacted cause."""
+    description = describe_failure(failure, credentials)
+    error = HushscriptError(
+        f"An unexpected {type(failure).__name__} interrupted the SDK{_SENT[sent]} ({description}).",
+        code=UNEXPECTED,
+    )
+    error.__cause__ = redacted_cause(failure, credentials)
+    return error
+
+
+class ConfigurationError(HushscriptError):
+    default_code = "config_invalid"
+    auto_hint = False
+
+
+class PreflightError(HushscriptError):
+    """The request was refused before any credit hold was placed."""
+
+
+class UnsupportedMediaError(PreflightError):
+    default_code = "unsupported_media"
+
+
+class FileLimitError(PreflightError):
+    default_code = "size_out_of_range"
+
+
+class DailyLimitError(PreflightError):
+    default_code = "daily_limit"
+
+
+class ResumeMismatchError(PreflightError):
+    default_code = "resume_file_mismatch"
+
+
+class ApiError(HushscriptError):
+    default_code = "api_error"
+
+
+class AuthenticationError(ApiError):
+    default_code = "unauthorized"
+
+
+class PermissionDeniedError(ApiError):
+    default_code = "pat_forbidden"
+
+
+class InsufficientBalanceError(ApiError):
+    default_code = "insufficient_balance"
+
+
+class NotFoundError(ApiError):
+    default_code = "not_found"
+
+
+class ConflictError(ApiError):
+    default_code = "wrong_state"
+
+
+class ValidationError(ApiError):
+    default_code = "bad_request"
+
+
+class RateLimitError(ApiError):
+    default_code = "rate_limited"
+
+
+class PaymentMethodRequiredError(HushscriptError):
+    default_code = "no_default_card"
+
+
+class UploadError(HushscriptError):
+    default_code = "upload_incomplete"
+
+
+class JobFailedError(HushscriptError):
+    default_code = "job_failed"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        job_id: str | None = None,
+        error: str | None = None,
+        failure_kind: str | None = None,
+        **kwargs: Any,  # noqa: ANN401  # forwarded to HushscriptError, which types them
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.job_id = job_id
+        self.error = redact(error) if error is not None else None
+        self.failure_kind = failure_kind
+
+
+class WaitTimeoutError(HushscriptError):
+    default_code = "wait_timeout"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        resume_token: str | None = None,
+        **kwargs: Any,  # noqa: ANN401  # forwarded to HushscriptError, which types them
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.resume_token = resume_token
+
+
+class AbortError(HushscriptError):
+    default_code = "aborted"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        resume_token: str | None = None,
+        **kwargs: Any,  # noqa: ANN401  # forwarded to HushscriptError, which types them
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.resume_token = resume_token
+
+
+class NetworkError(HushscriptError):
+    default_code = "network_error"
+
+
+class OutcomeUnknownError(HushscriptError):
+    default_code = "outcome_unknown"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        received_token: str | Secret | None = None,
+        **kwargs: Any,  # noqa: ANN401  # forwarded to HushscriptError, which types them
+    ) -> None:
+        super().__init__(message, **kwargs)
+        text = received_token.reveal() if isinstance(received_token, Secret) else received_token
+        self._received = Secret(text if text and text.strip() else "")
+
+    @property
+    def received_token(self) -> str | None:
+        """The token a claim or rotation answer carried when the rest of it could not be used, so
+        the credential the server shows once is not lost; None when there is none. It is never part
+        of the message, the repr, a pickle or a log line; treat it like any token."""
+        return self._received.reveal() or None
+
+
+_CLASS_BY_SLUG: Final[dict[str, type[HushscriptError]]] = {
+    "upload_incomplete": UploadError,
+    "size_exceeded": UploadError,
+    "agent_claim_invalid": AuthenticationError,
+    "unauthorized": AuthenticationError,
+    "pat_scope_missing": PermissionDeniedError,
+    "pat_forbidden": PermissionDeniedError,
+    "account_suspended": PermissionDeniedError,
+    "agent_pack_locked": PermissionDeniedError,
+    "pat_purchase_requires_app": PermissionDeniedError,
+    "pat_purchase_requires_authentication": PermissionDeniedError,
+    "country_restricted": PermissionDeniedError,
+    "signup_not_allowed": PermissionDeniedError,
+    "insufficient_balance": InsufficientBalanceError,
+    "org_insufficient_balance": InsufficientBalanceError,
+    "org_pool_expired": InsufficientBalanceError,
+    "org_plan_frozen": InsufficientBalanceError,
+    "wrong_state": ConflictError,
+    "agent_signup_pending": ConflictError,
+    "pat_limit": ConflictError,
+    "rate_limited": RateLimitError,
+    "too_many_active_jobs": RateLimitError,
+    "agent_purchase_capped": RateLimitError,
+    "url_target_busy": RateLimitError,
+}
+
+_CLASS_BY_STATUS: Final[dict[int, type[HushscriptError]]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: InsufficientBalanceError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+_OPERATION_PATTERNS: Final = [
+    (re.compile("^" + _TEMPLATE_PARAMETER.sub("[^/]+", re.escape(key.split(" ", 1)[1])) + "$"), key)
+    for key in OPERATION_SCOPES
+]
+
+
+def operation_key(method: str, path: str) -> str | None:
+    """Maps a concrete request (`GET`, `/v1/jobs/abc`) to its OPERATION_SCOPES key."""
+    prefix = f"{method.upper()} "
+    for pattern, key in _OPERATION_PATTERNS:
+        if key.startswith(prefix) and pattern.match(path):
+            return key
+    return None
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    if value is None:
+        return None
+    text = value.strip()
+    if not text.isascii() or not text.isdigit():
+        return None
+    digits = text.lstrip("0") or "0"
+    if len(digits) > _MAX_RETRY_AFTER_DIGITS:
+        return RETRY_AFTER_CAP
+    return float(min(int(digits), RETRY_AFTER_CAP))
+
+
+def _extra_details(body: Mapping[str, object]) -> dict[str, object]:
+    details: dict[str, object] = {
+        key: value for key, value in body.items() if key not in {"error", "code", "details"}
+    }
+    nested = body.get("details")
+    nested_details = as_dict(nested)
+    if nested_details is not None:
+        for key, value in nested_details.items():
+            details.setdefault(key, value)
+    elif nested is not None:
+        details["details"] = nested
+    return details
+
+
+def _operation_of(response: httpx.Response) -> str | None:
+    try:
+        request = response.request
+    except RuntimeError:  # the response was built without a request
+        return None
+    return operation_key(request.method, request.url.path)
+
+
+def forget_body(response: httpx.Response) -> None:
+    response.stream = httpx.ByteStream(b"")
+    response._content = b""  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+
+
+def _scrub_queries(value: object) -> object:
+    if isinstance(value, str):
+        return redact_queries(value)
+    fields = as_dict(value)
+    if fields is not None:
+        return {redact_queries(key): _scrub_queries(item) for key, item in fields.items()}
+    items = as_list(value)
+    if items is not None:
+        return [_scrub_queries(item) for item in items]
+    return value
+
+
+def _parse_body(response: httpx.Response, credentials: Credentials) -> dict[str, object]:
+    try:
+        parsed: object = _scrub_queries(credentials.scrub_value(loads(response.content)))
+    except (ValueError, RecursionError):  # not JSON, or nested past what the parser reads
+        return {}
+    finally:
+        forget_body(response)
+    body = as_dict(parsed) or {}
+    # Only sanitized bytes remain reachable through the response.
+    response._content = json.dumps(body).encode()  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+    response.stream = httpx.ByteStream(response.content)
+    return body
+
+
+def _details_of(body: Mapping[str, object], credentials: Credentials) -> dict[str, object]:
+    try:
+        return as_dict(_snake_keys(credentials.scrub_value(_extra_details(body)))) or {}
+    except RecursionError:  # a body nested past what the walkers read carries no details
+        return {}
+
+
+def error_from_response(
+    response: httpx.Response,
+    *,
+    credentials: Credentials | None = None,
+    operation: str | None = None,
+) -> HushscriptError:
+    """Builds the spec 9.2 error for a non-2xx API response."""
+    credentials = credentials or Credentials()
+    status = response.status_code
+    body = _parse_body(response, credentials)
+    raw_slug = body.get("error")
+    slug = credentials.scrub(raw_slug) if isinstance(raw_slug, str) else raw_slug
+    code_value = body.get("code")
+    numeric_code = (
+        code_value if isinstance(code_value, int) and not isinstance(code_value, bool) else None
+    )
+    code = slug if isinstance(slug, str) and slug else f"http_{status}"
+    entry = ERROR_CATALOG.get(code)
+    message = entry.meaning if entry is not None else f"The API answered {status} ({code})."
+    if operation is None:
+        operation = _operation_of(response)
+    retry_after = parse_retry_after(response.headers.get("retry-after"))
+    details = _details_of(body, credentials)
+    error_class = _CLASS_BY_SLUG.get(code) or _CLASS_BY_STATUS.get(status) or ApiError
+    error = error_class(
+        credentials.scrub(message),
+        code=code,
+        numeric_code=numeric_code,
+        status=status,
+        details=details,
+        retry_after=retry_after,
+        scope=OPERATION_SCOPES.get(operation) if operation else None,
+    )
+    if code == "wrong_state" and not _JOB_OR_UPLOAD.match(operation or ""):
+        # The hint names a job call, so only job and upload operations carry it (spec 9.3).
+        error.hint = None
+    return error
+
+
+def raise_for_response(
+    response: httpx.Response,
+    *,
+    credentials: Credentials | None = None,
+    operation: str | None = None,
+) -> None:
+    if response.is_success:
+        return
+    raise error_from_response(response, credentials=credentials, operation=operation)

hushscript/_guard.py

@@ -0,0 +1,61 @@
+"""`hs.api` keeps one promise: nothing but an SDK error leaves it (R61).
+
+The generated functions parse the answer after the transport has returned it, reading its JSON and
+building a model from it, and a body that is not what they expect raises a bare `JSONDecodeError`,
+`KeyError` or `TypeError`. The transport cannot see a call is generated, but the generated function
+is on the stack that called it, so it runs that function's own parser on the answer before handing
+it back and turns a failure into an SDK error. Generated code is never edited (spec section 5).
+"""
+
+from __future__ import annotations
+
+import inspect
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Final
+
+from ._errors import HushscriptError, error_from_response, redacted_cause
+from ._response import unreadable_response
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import httpx
+
+    from ._redact import Credentials
+
+GENERATED_MODULES: Final = "hushscript.generated.api."
+_LENIENT_CLIENT: Final = SimpleNamespace(raise_on_unexpected_status=False)
+"""Stands in for the client: an undocumented status is the generated function's own business."""
+
+
+def generated_parser() -> Callable[..., object] | None:
+    """The `_parse_response` of the generated operation that is making the current request, or
+    None when the request is not one."""
+    frame = inspect.currentframe()
+    try:
+        while frame is not None:
+            name = frame.f_globals.get("__name__")
+            if isinstance(name, str) and name.startswith(GENERATED_MODULES):
+                parse = frame.f_globals.get("_parse_response")
+                return parse if callable(parse) else None
+            frame = frame.f_back
+        return None
+    finally:
+        del frame
+
+
+def unusable_answer(
+    parse: Callable[..., object], response: httpx.Response, credentials: Credentials | None
+) -> HushscriptError | None:
+    """The SDK error for an answer the generated parser cannot read, or None when it can. A 2xx is
+    `bad_response`; any other status is the error the friendly layer would raise for it. The error
+    is returned, not raised, so the original is on neither its cause nor its `__context__`."""
+    try:
+        parse(client=_LENIENT_CLIENT, response=response)
+    except Exception as failure:  # noqa: BLE001  # whatever the generated parser trips on
+        if response.is_success:
+            return unreadable_response(response, failure, credentials)
+        error = error_from_response(response, credentials=credentials)
+        error.__cause__ = redacted_cause(failure, credentials)
+        return error
+    return None