hushscript 1.0.0__py3-none-any.whl

hushscript/_retry.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import enum
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+import httpx
+
+from ._pacing import ACTIVE_JOBS_RETRIES, ACTIVE_JOBS_WAIT, CREATE_RATE_LIMIT_BACKOFF
+
+if TYPE_CHECKING:
+    import random
+
+MAX_RETRY_AFTER: Final = 60.0
+BACKOFF_CAP: Final = 8.0
+BACKOFF_BASE: Final = 0.5
+TOO_MANY_ACTIVE_JOBS: Final = "too_many_active_jobs"
+TOO_MANY_REQUESTS: Final = 429
+
+# Spec 7.4: only DNS, connect, TLS-handshake and pool-wait failures happen before the request body
+# is written; httpx maps the first three to ConnectError/ConnectTimeout. Everything else is "sent".
+_NOT_SENT: Final = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout)
+
+
+class NetworkRetry(enum.Enum):
+    ANY = "any"
+    BEFORE_SENT = "before-sent"
+    NONE = "none"
+
+
+class RetryClass(enum.Enum):
+    SAFE = "safe"
+    PART = "part"
+    COMPLETE = "complete"
+    CREATE = "create"
+    PURCHASE = "purchase"
+    NEVER = "never"
+    MUTATE = "mutate"
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    statuses: frozenset[int]
+    network: NetworkRetry
+    cap: int | None = None
+
+
+_SERVER_ERRORS: Final = frozenset(range(500, 600))
+_POLICIES: Final = {
+    RetryClass.SAFE: RetryPolicy(frozenset({429, 500, 502, 503, 504}), NetworkRetry.ANY),
+    RetryClass.PART: RetryPolicy(frozenset({429}) | _SERVER_ERRORS, NetworkRetry.ANY),
+    RetryClass.COMPLETE: RetryPolicy(frozenset({429}) | _SERVER_ERRORS, NetworkRetry.ANY),
+    RetryClass.CREATE: RetryPolicy(frozenset({429}) | _SERVER_ERRORS, NetworkRetry.ANY),
+    RetryClass.PURCHASE: RetryPolicy(frozenset({502, 503}), NetworkRetry.ANY, cap=1),
+    RetryClass.NEVER: RetryPolicy(frozenset(), NetworkRetry.NONE),
+    RetryClass.MUTATE: RetryPolicy(frozenset(), NetworkRetry.BEFORE_SENT),
+}
+
+CLAIM: Final = "claim"
+ROTATE: Final = "rotate"
+SIGNUP: Final = "signup"
+
+_JOB: Final = r"/v1/uploads/[^/]+"
+# (method, path, class, name of a route whose lost response needs its own hint)
+_ROUTES: Final = (
+    ("POST", re.compile(rf"^{_JOB}/heartbeat$"), RetryClass.SAFE, None),
+    ("PUT", re.compile(rf"^{_JOB}/parts/[^/]+$"), RetryClass.PART, None),
+    ("POST", re.compile(rf"^{_JOB}/complete$"), RetryClass.COMPLETE, None),
+    ("POST", re.compile(r"^/v1/uploads$"), RetryClass.CREATE, None),
+    ("POST", re.compile(r"^/v1/billing/(purchase|setup-session)$"), RetryClass.PURCHASE, None),
+    ("POST", re.compile(r"^/v1/agent/accounts/[^/]+/claim$"), RetryClass.NEVER, CLAIM),
+    ("POST", re.compile(r"^/v1/agent/credentials/rotate$"), RetryClass.NEVER, ROTATE),
+    ("POST", re.compile(r"^/v1/agent/accounts$"), RetryClass.NEVER, SIGNUP),
+)
+
+
+def _route(method: str, path: str) -> tuple[RetryClass, str | None] | None:
+    verb = method.upper()
+    for route_method, pattern, retry_class, name in _ROUTES:
+        if verb == route_method and pattern.match(path.rstrip("/") or "/"):
+            return retry_class, name
+    return None
+
+
+def classify(method: str, path: str) -> RetryClass:
+    """The spec 7.2 operation class of a request; `path` is relative to the base URL."""
+    route = _route(method, path)
+    if route is not None:
+        return route[0]
+    return RetryClass.SAFE if method.upper() in {"GET", "HEAD", "OPTIONS"} else RetryClass.MUTATE
+
+
+def unrecoverable_route(method: str, path: str) -> str | None:
+    """`claim`, `rotate` or `signup` when the request is one of the spec 7.4 routes, else None."""
+    route = _route(method, path)
+    return None if route is None else route[1]
+
+
+def is_not_sent(failure: httpx.RequestError) -> bool:
+    """True when the failure happened before the request body was written (spec 7.4)."""
+    return isinstance(failure, _NOT_SENT)
+
+
+def policy_for(retry_class: RetryClass) -> RetryPolicy:
+    return _POLICIES[retry_class]
+
+
+def backoff_delay(attempt: int, rng: random.Random) -> float:
+    """Full jitter: random(0, min(8 s, 0.5 s * 2^attempt)); `attempt` counts retries from 0."""
+    return rng.uniform(0.0, min(BACKOFF_CAP, BACKOFF_BASE * 2.0**attempt))
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome:
+    """What one attempt produced: a response (status, Retry-After, slug) or a transport failure."""
+
+    status: int | None = None
+    retry_after: float | None = None
+    slug: str | None = None
+    failure: httpx.RequestError | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    retry: bool
+    delay: float = 0.0
+
+
+STOP: Final = Decision(retry=False)
+
+
+def _after_failure(
+    policy: RetryPolicy, attempt: int, failure: httpx.RequestError, rng: random.Random
+) -> Decision:
+    if policy.network is NetworkRetry.NONE:
+        return STOP
+    if policy.network is NetworkRetry.BEFORE_SENT and not is_not_sent(failure):
+        return STOP
+    return Decision(retry=True, delay=backoff_delay(attempt, rng))
+
+
+RATE_LIMITED: Final = "rate_limited"
+ACTIVE_JOBS: Final = "active_jobs"
+
+
+def create_limit_kind(retry_class: RetryClass, outcome: Outcome) -> str | None:
+    """The 429 schedule (spec 7.5) a response belongs to: `active_jobs`, `rate_limited` or None."""
+    if retry_class is not RetryClass.CREATE or outcome.status != TOO_MANY_REQUESTS:
+        return None
+    return ACTIVE_JOBS if outcome.slug == TOO_MANY_ACTIVE_JOBS else RATE_LIMITED
+
+
+def _after_create_rate_limit(own_429: int, outcome: Outcome) -> Decision:
+    if outcome.slug == TOO_MANY_ACTIVE_JOBS:
+        return Decision(retry=True, delay=ACTIVE_JOBS_WAIT)
+    if own_429 >= len(CREATE_RATE_LIMIT_BACKOFF):
+        return STOP
+    return Decision(retry=True, delay=CREATE_RATE_LIMIT_BACKOFF[own_429])
+
+
+def _after_response(
+    retry_class: RetryClass, attempt: int, own_429: int, outcome: Outcome, rng: random.Random
+) -> Decision:
+    if outcome.status is None or outcome.status not in policy_for(retry_class).statuses:
+        return STOP
+    if outcome.retry_after is not None:
+        if outcome.retry_after > MAX_RETRY_AFTER:
+            return STOP
+        return Decision(retry=True, delay=outcome.retry_after)
+    if create_limit_kind(retry_class, outcome) is not None:
+        return _after_create_rate_limit(own_429, outcome)
+    return Decision(retry=True, delay=backoff_delay(attempt, rng))
+
+
+def _exhausted(
+    retry_class: RetryClass, attempt: int, own_429: int, max_retries: int, outcome: Outcome
+) -> bool:
+    if create_limit_kind(retry_class, outcome) == ACTIVE_JOBS:
+        # Spec 7.5: ten tries whatever max_retries says, counted over active-jobs 429s only; only
+        # max_retries=0 turns this off.
+        return max_retries == 0 or own_429 >= ACTIVE_JOBS_RETRIES
+    cap = policy_for(retry_class).cap
+    return attempt >= (max_retries if cap is None else min(max_retries, cap))
+
+
+def decide(  # the attempt counters are separate on purpose (spec 7.2)
+    retry_class: RetryClass,
+    attempt: int,
+    max_retries: int,
+    outcome: Outcome,
+    rng: random.Random,
+    own_429: int | None = None,
+) -> Decision:
+    """Whether to try again after attempt number `attempt` (0 is the first) and how long to wait.
+
+    `own_429` is how many earlier responses were 429s of the same schedule as this one; the 429
+    schedules count only those, not retries of other kinds. It defaults to `attempt`.
+    """
+    own = attempt if own_429 is None else own_429
+    if _exhausted(retry_class, attempt, own, max_retries, outcome):
+        return STOP
+    if outcome.failure is not None:
+        return _after_failure(policy_for(retry_class), attempt, outcome.failure, rng)
+    return _after_response(retry_class, attempt, own, outcome, rng)

hushscript/_shape.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Mapping  # the Shape alias is built at runtime
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Final, TypeAlias
+
+from ._json import as_dict, as_list
+from ._response import BadBodyError
+
+INT_LIMIT: Final = 2**63
+"""Whole numbers in a body stay inside a signed 64-bit range, as the API's own counters do."""
+MAX_UNIX_SECONDS: Final = 253_402_300_799
+"""9999-12-31T23:59:59Z: the last instant a `datetime` holds."""
+_EPOCH: Final = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
+@dataclass(frozen=True, slots=True)
+class Problem:
+    """Where a body departs from its shape: the path to the field and what was expected there."""
+
+    path: tuple[str | int, ...]
+    expected: str
+
+    def under(self, step: str | int) -> Problem:
+        return Problem((step, *self.path), self.expected)
+
+    def describe(self) -> str:
+        where = ""
+        for part in self.path:
+            if isinstance(part, int):
+                where += f"[{part}]"
+            else:
+                where += f".{part}" if where else part
+        return f"{where}: expected {self.expected}" if where else f"expected {self.expected}"
+
+
+Shape: TypeAlias = Callable[[object], Problem | None]
+
+
+def _whole(value: object) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def string(value: object) -> Problem | None:
+    return None if isinstance(value, str) else Problem((), "a string")
+
+
+def boolean(value: object) -> Problem | None:
+    return None if isinstance(value, bool) else Problem((), "a boolean")
+
+
+def integer(value: object) -> Problem | None:
+    whole = _whole(value)
+    return None if whole is not None and abs(whole) < INT_LIMIT else Problem((), "a whole number")
+
+
+def count(value: object) -> Problem | None:
+    """A quantity that cannot be negative: seconds, bytes, jobs."""
+    whole = _whole(value)
+    ok = whole is not None and 0 <= whole < INT_LIMIT
+    return None if ok else Problem((), "a whole number of 0 or more")
+
+
+def positive(value: object) -> Problem | None:
+    whole = _whole(value)
+    return None if whole is not None and 0 < whole < INT_LIMIT else Problem((), "a number above 0")
+
+
+def finite_number(value: object) -> bool:
+    """A number inside the 64-bit range; total, where `math.isfinite` raises on a huge int."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return False
+    if isinstance(value, float) and not math.isfinite(value):
+        return False
+    return abs(value) < INT_LIMIT
+
+
+def number(value: object) -> Problem | None:
+    """A finite number; `NaN` and `Infinity` parse in Python but are not JSON."""
+    return None if finite_number(value) else Problem((), "a number")
+
+
+def timestamp(value: object) -> Problem | None:
+    whole = _whole(value)
+    ok = whole is not None and 0 <= whole <= MAX_UNIX_SECONDS
+    return None if ok else Problem((), "a unix timestamp in seconds")
+
+
+def anything(_value: object) -> Problem | None:
+    return None
+
+
+def nullable(shape: Shape) -> Shape:
+    return lambda value: None if value is None else shape(value)
+
+
+def array_of(shape: Shape) -> Shape:
+    def check(value: object) -> Problem | None:
+        items = as_list(value)
+        if items is None:
+            return Problem((), "an array")
+        for index, item in enumerate(items):
+            found = shape(item)
+            if found is not None:
+                return found.under(index)
+        return None
+
+    return check
+
+
+def record_of(shape: Shape) -> Shape:
+    """An object with arbitrary keys whose values all fit `shape`."""
+
+    def check(value: object) -> Problem | None:
+        fields = as_dict(value)
+        if fields is None:
+            return Problem((), "an object")
+        for key, item in fields.items():
+            found = shape(item)
+            if found is not None:
+                return found.under(key)
+        return None
+
+    return check
+
+
+def object_of(required: Mapping[str, Shape], optional: Mapping[str, Shape] | None = None) -> Shape:
+    """An object with each required key present and fitting, and each optional key fitting when it
+    is there. Keys the shape does not list pass, so a newer API still parses."""
+    extras = optional or {}
+
+    def check(value: object) -> Problem | None:
+        fields = as_dict(value)
+        if fields is None:
+            return Problem((), "an object")
+        for key, shape in required.items():
+            found = shape(fields[key]) if key in fields else Problem((), "a value")
+            if found is not None:
+                return found.under(key)
+        for key, shape in extras.items():
+            found = shape(fields[key]) if key in fields else None
+            if found is not None:
+                return found.under(key)
+        return None
+
+    return check
+
+
+def check_shape(value: object, shape: Shape, what: str) -> None:
+    """Raises BadBodyError naming the path and the expectation, never the value, when `value` does
+    not fit `shape`."""
+    found = shape(value)
+    if found is not None:
+        raise BadBodyError(f"{what} ({found.describe()})")
+
+
+def to_datetime(seconds: object) -> datetime:
+    """The aware UTC `datetime` of a unix timestamp that the `timestamp` shape accepted."""
+    whole = _whole(seconds)
+    if whole is None:
+        raise BadBodyError("a timestamp (not a whole number)")
+    return _EPOCH + timedelta(seconds=whole)
+
+
+def as_whole(value: object) -> int:
+    """`value` as an int once the shape has vouched for it; a stray type is BadBodyError, never
+    a TypeError at a later line."""
+    whole = _whole(value)
+    if whole is None:
+        raise BadBodyError("a whole number")
+    return whole
+
+
+def as_text(value: object) -> str:
+    if not isinstance(value, str):
+        raise BadBodyError("a string")
+    return value
+
+
+def as_flag(value: object) -> bool:
+    if not isinstance(value, bool):
+        raise BadBodyError("a boolean")
+    return value
+
+
+def maybe_whole(value: object) -> int | None:
+    return None if value is None else as_whole(value)
+
+
+def maybe_text(value: object) -> str | None:
+    return None if value is None else as_text(value)
+
+
+def maybe_flag(value: object) -> bool | None:
+    return None if value is None else as_flag(value)

hushscript/_shapes.py

@@ -0,0 +1,248 @@
+"""What the friendly layer reads from each 2xx body, checked before any field is touched.
+
+The tables list the fields the mappers use (`openapi.json` is the reference); keys they do not
+list pass through, so a newer API still parses.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from ._shape import (
+    Shape,
+    anything,
+    array_of,
+    boolean,
+    count,
+    integer,
+    nullable,
+    number,
+    object_of,
+    record_of,
+    string,
+    timestamp,
+)
+
+UPLOAD_LIMITS: Final[Shape] = object_of(
+    {
+        "max_daily_seconds": count,
+        "max_active_jobs": count,
+        "active_jobs": count,
+        "used_today_seconds": count,
+    }
+)
+
+# `purchases_remaining_in_window` is in the body for agent accounts only, and not yet in the schema.
+BALANCE: Final[Shape] = object_of(
+    {"balance_seconds": integer, "held_seconds": count},
+    {
+        "credits_expire_at": nullable(timestamp),
+        "purchases_remaining_in_window": nullable(count),
+    },
+)
+
+ACCOUNT: Final[Shape] = object_of(
+    {
+        "balance_seconds": integer,
+        "held_seconds": count,
+        "credits_expire_at": nullable(timestamp),
+        "card_on_file": boolean,
+        "data_region": string,
+        "limits": UPLOAD_LIMITS,
+    },
+    {"purchases_remaining_in_window": nullable(count)},
+)
+
+OPTIONS_SUMMARY: Final[Shape] = object_of(
+    {
+        "language_code": nullable(string),
+        "speaker_detection": boolean,
+        "medical_mode": boolean,
+        "multichannel": boolean,
+        "translation_targets": array_of(string),
+        "keyterms": boolean,
+        "prompt": boolean,
+        "auto_generate_insights": nullable(boolean),
+    }
+)
+
+JOB: Final[Shape] = object_of(
+    {
+        "id": string,
+        "state": string,
+        "mode": string,
+        "declared_seconds": nullable(count),
+        "verified_seconds": nullable(count),
+        "actual_seconds": nullable(count),
+        "billable_seconds": nullable(count),
+        "error": nullable(string),
+        "failure_kind": nullable(string),
+        "retry_of": nullable(string),
+        "created_at": timestamp,
+        "transcript_id": nullable(string),
+        "options": OPTIONS_SUMMARY,
+    }
+)
+
+JOB_LIST: Final[Shape] = object_of({"jobs": array_of(JOB), "next_cursor": nullable(string)})
+
+_UTTERANCE: Final[Shape] = object_of(
+    {"speaker": string, "start_ms": number, "end_ms": number, "text": string}
+)
+_TRANSCRIPT_LANGUAGE: Final[Shape] = object_of({"utterances": array_of(_UTTERANCE)})
+
+TRANSCRIPT_DETAIL: Final[Shape] = object_of(
+    {
+        "id": string,
+        "title": string,
+        "language_detected": nullable(string),
+        "duration_seconds": count,
+        "speaker_names": record_of(string),
+        "tags": array_of(string),
+        "created_at": timestamp,
+        "updated_at": timestamp,
+        "auto_delete_at": nullable(timestamp),
+        "edited": boolean,
+        "body": object_of(
+            {"original": _TRANSCRIPT_LANGUAGE, "translations": record_of(_TRANSCRIPT_LANGUAGE)}
+        ),
+    }
+)
+
+TRANSCRIPT_LIST: Final[Shape] = object_of(
+    {
+        "transcripts": array_of(
+            object_of(
+                {
+                    "id": string,
+                    "title": string,
+                    "language_detected": nullable(string),
+                    "duration_seconds": count,
+                    "created_at": timestamp,
+                    "auto_delete_at": nullable(timestamp),
+                    "tags": array_of(string),
+                }
+            )
+        ),
+        "next_cursor": nullable(string),
+    }
+)
+
+DELETED_LIST: Final[Shape] = object_of(
+    {
+        "deleted": array_of(
+            object_of(
+                {
+                    "id": string,
+                    "title": string,
+                    "duration_seconds": count,
+                    "created_at": timestamp,
+                    "deleted_at": timestamp,
+                    "cause": string,
+                    "receipt": nullable(record_of(anything)),
+                }
+            )
+        ),
+        "next_cursor": nullable(string),
+    }
+)
+
+PACKS: Final[Shape] = object_of(
+    {
+        "packs": array_of(
+            object_of(
+                {
+                    "id": string,
+                    "amount": integer,
+                    "currency": string,
+                    "seconds": count,
+                    "referral_bonus_seconds": count,
+                },
+                {"available": nullable(boolean)},
+            )
+        )
+    }
+)
+
+CARDS: Final[Shape] = object_of(
+    {
+        "default_id": nullable(string),
+        "methods": array_of(
+            object_of(
+                {
+                    "id": string,
+                    "type": string,
+                    "brand": string,
+                    "last4": string,
+                    "exp_month": count,
+                    "exp_year": count,
+                    "is_default": boolean,
+                    "fast_checkout_eligible": boolean,
+                },
+                {"email": nullable(string)},
+            )
+        ),
+    }
+)
+
+SETUP_SESSION: Final[Shape] = object_of({"checkout_url": string})
+
+PURCHASE: Final[Shape] = object_of({"status": string, "balance_seconds": integer})
+
+TRANSACTIONS: Final[Shape] = object_of(
+    {
+        "transactions": array_of(
+            object_of(
+                {
+                    "id": integer,
+                    "seconds": integer,
+                    "amount_cents": integer,
+                    "amount_refunded_cents": integer,
+                    "currency": string,
+                    "status": string,
+                    "created_at": timestamp,
+                },
+                {
+                    "payment_method_type": nullable(string),
+                    "payment_method_brand": nullable(string),
+                    "payment_method_last4": nullable(string),
+                    "receipt_number": nullable(string),
+                    "initiated_via": nullable(string),
+                },
+            )
+        ),
+        "next_cursor": nullable(string),
+    }
+)
+
+LEDGER: Final[Shape] = object_of(
+    {
+        "entries": array_of(
+            object_of(
+                {"id": integer, "delta_seconds": integer, "kind": string, "created_at": timestamp},
+                {"job_id": nullable(string), "note": nullable(string)},
+            )
+        ),
+        "next_cursor": nullable(string),
+    }
+)
+
+HOLDS: Final[Shape] = object_of(
+    {
+        "holds": array_of(
+            object_of({"id": string, "kind": string, "seconds": count, "created_at": timestamp})
+        ),
+        "next_cursor": nullable(string),
+    }
+)
+
+AGENT_SIGNUP: Final[Shape] = object_of(
+    {
+        "signup_id": string,
+        "claim_secret": string,
+        "checkout_url": string,
+        "amount": integer,
+        "currency": string,
+        "expires_at": timestamp,
+    }
+)

hushscript/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"  # x-release-please-version