hushscript 1.0.0__py3-none-any.whl

hushscript/_log.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import logging
+import re
+import sys
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Final
+
+import httpx
+
+from ._redact import redact
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+LOG_LEVELS: Final = ("off", "debug")
+_LOGGER: Final = logging.getLogger("hushscript")
+
+# The label of the signed R2 request this thread or task is sending, or None. httpx logs every
+# request's full URL at INFO on its own logger ("HTTP Request: PUT <url>"), httpcore traces its
+# connection and request events at DEBUG on its own, and a signed part URL carries the signature in
+# its query (spec 10: R2 URLs only ever appear as `r2:part/{n}`).
+_SIGNED_REQUEST: ContextVar[str | None] = ContextVar("hushscript_signed_request", default=None)
+
+
+_URL_TEXT: Final = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*://[^\s'\"<>]+")
+# The query keys that make a URL signed: S3/R2 presigned (X-Amz-*), the mock's `sig`, and the
+# generic names other signers use.
+_SIGNED_QUERY: Final = re.compile(
+    r"[?&](?:sig|signature|token|expires|x-amz-[a-z0-9-]+|x-goog-[a-z0-9-]+)=", re.IGNORECASE
+)
+
+
+def _looks_signed(url: str) -> bool:
+    return _SIGNED_QUERY.search(url) is not None
+
+
+def _hide_text(text: str, label: str) -> str:
+    return _URL_TEXT.sub(lambda m: label if _looks_signed(m.group(0)) else m.group(0), text)
+
+
+def _hide(value: object, label: str) -> object:
+    """`value` with every signed-looking URL in it swapped for `label`. An object that is neither
+    text nor a number (an httpx.Request, a URL object of either library) is swapped for its hidden
+    text when its own text shows a signed URL."""
+    if isinstance(value, str):
+        return _hide_text(value, label)
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, bytes):
+        return _hide_text(value.decode("latin-1"), label).encode("latin-1")
+    try:
+        shown = f"{value}"
+        shown_repr = repr(value)
+    except Exception:  # noqa: BLE001  # a log call must not fail on a hostile __str__
+        return value
+    if _looks_signed(shown) or _looks_signed(shown_repr):
+        return _hide_text(shown_repr if _looks_signed(shown_repr) else shown, label)
+    return value
+
+
+def _hide_arg(arg: object, label: str) -> object:
+    if isinstance(arg, (str, httpx.URL)) and "://" in str(arg):
+        return label
+    return _hide(arg, label)
+
+
+class _SignedUrlFilter(logging.Filter):
+    """Swaps the URL in an httpx record for the request's label while a signed request is out.
+
+    It only rewrites records logged by the thread or task that is sending the signed request, so
+    other httpx users in the process keep their log lines, and it never touches a level. A URL
+    that httpx has already formatted into the message, or put in a mapping argument, goes too.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        label = _SIGNED_REQUEST.get()
+        if label is None:
+            return True
+        if isinstance(record.msg, str):
+            record.msg = _hide(record.msg, label)
+        if isinstance(record.args, tuple):
+            record.args = tuple(_hide_arg(arg, label) for arg in record.args)
+        elif isinstance(record.args, dict):
+            record.args = {key: _hide(item, label) for key, item in record.args.items()}
+        return True
+
+
+_SIGNED_URL_FILTER: Final = _SignedUrlFilter()
+_THIRD_PARTY_LOGGERS: Final = (
+    "httpx",
+    "httpcore",
+    "httpcore.connection",
+    "httpcore.http11",
+    "httpcore.http2",
+    "httpcore.proxy",
+    "httpcore.socks",
+)
+
+
+@contextmanager
+def hiding_signed_url(label: str) -> Generator[None]:
+    """Within the block, httpx's own request log shows `label` where the signed URL would be."""
+    token = _SIGNED_REQUEST.set(label)
+    try:
+        yield
+    finally:
+        _SIGNED_REQUEST.reset(token)
+
+
+class RequestLog:
+    """One line per attempt: method, path, status, attempt, duration and retry delay (spec 10).
+
+    Never headers, query strings, bodies, titles or transcript text; the caller passes a path
+    without a query and direct-to-R2 URLs arrive as `r2:part/{n}`.
+    """
+
+    def __init__(self, level: str = "off") -> None:
+        # httpx and httpcore log on their own, whatever our level; the filter is a no-op until a
+        # signed request is out. Adding it twice is harmless. A logger's filters see only the
+        # records it creates, so each httpcore logger carries it.
+        for name in _THIRD_PARTY_LOGGERS:
+            logging.getLogger(name).addFilter(_SIGNED_URL_FILTER)
+        self.enabled = level == "debug"
+        if self.enabled:
+            _LOGGER.setLevel(logging.DEBUG)
+            if not _LOGGER.handlers:
+                handler = logging.StreamHandler(sys.stderr)
+                handler.setFormatter(logging.Formatter("%(message)s"))
+                _LOGGER.addHandler(handler)
+
+    def note(self, message: str) -> None:
+        """A line outside the request/attempt shape, such as a heartbeat that failed; redacted."""
+        if self.enabled:
+            _LOGGER.debug(redact(f"hushscript {message}"))
+
+    def attempt(  # one call site per field of the line
+        self,
+        method: str,
+        path: str,
+        status: int | None,
+        attempt: int,
+        duration_ms: float,
+        retry_delay: float | None,
+    ) -> None:
+        if not self.enabled:
+            return
+        outcome = "error" if status is None else str(status)
+        delay = "" if retry_delay is None else f" retry_in={retry_delay:g}s"
+        _LOGGER.debug(
+            redact(
+                f"hushscript {method} {path} {outcome} attempt={attempt} {duration_ms:.0f}ms{delay}"
+            )
+        )

hushscript/_models.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from ._json import ExtraFields, as_dict, as_list, extra_fields
+from ._shape import (
+    as_flag,
+    as_text,
+    check_shape,
+    maybe_flag,
+    maybe_text,
+    maybe_whole,
+    to_datetime,
+)
+from ._shapes import JOB
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class UploadingProgress:
+    """Bytes the API has acknowledged; `percent` is 0 while the call waits for a create slot."""
+
+    percent: int
+    bytes_sent: int
+    bytes_total: int
+    stage: Literal["uploading"] = "uploading"
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessingProgress:
+    """The job's state while it is queued or processing."""
+
+    state: str
+    stage: Literal["processing"] = "processing"
+
+
+Progress = UploadingProgress | ProcessingProgress
+
+
+@dataclass(frozen=True, slots=True)
+class JobOptions(ExtraFields):
+    """What the job was submitted with, from the API's content-free summary: it says whether
+    keyterms and a prompt were set, never what they were. Unknown API keys remain available
+    in `extra`."""
+
+    language_code: str | None
+    """The forced language, or None when it was auto-detected."""
+    speaker_detection: bool
+    medical_mode: bool
+    multichannel: bool
+    translation_targets: list[str]
+    keyterms: bool
+    prompt: bool
+    auto_generate_insights: bool | None
+    """The upload's insights override, or None when it used the account default."""
+
+    __hash__ = None  # type: ignore[assignment]  # holds a list, so it is unhashable by design
+
+
+@dataclass(frozen=True, slots=True)
+class Job(ExtraFields):
+    """A processing job (spec 6.4). Fields without friendly attributes remain in `extra`."""
+
+    id: str
+    state: str
+    """`uploading`, `fetching`, `queued`, `processing`, `done` or `failed`; a state the SDK does
+    not know yet passes through as the API's own string."""
+    transcript_id: str | None
+    error: str | None
+    """The failure text of a failed job; opaque."""
+    failure_kind: str | None
+    """`media_unreadable` or `media_undecodable` when the file itself could not be read."""
+    mode: str
+    declared_seconds: int | None
+    verified_seconds: int | None
+    actual_seconds: int | None
+    billable_seconds: int | None
+    retry_of: str | None
+    created_at: datetime
+    options: JobOptions
+
+    __hash__ = None  # type: ignore[assignment]  # holds a JobOptions, which is unhashable
+
+    @classmethod
+    def from_body(cls, body: object) -> Job:
+        check_shape(body, JOB, "job response")
+        fields = as_dict(body) or {}
+        options = as_dict(fields["options"]) or {}
+        return cls(
+            _extra=extra_fields(
+                fields,
+                "id",
+                "state",
+                "transcript_id",
+                "error",
+                "failure_kind",
+                "mode",
+                "declared_seconds",
+                "verified_seconds",
+                "actual_seconds",
+                "billable_seconds",
+                "retry_of",
+                "created_at",
+                "options",
+            ),
+            id=as_text(fields["id"]),
+            state=as_text(fields["state"]),
+            transcript_id=maybe_text(fields["transcript_id"]),
+            error=maybe_text(fields["error"]),
+            failure_kind=maybe_text(fields["failure_kind"]),
+            mode=as_text(fields["mode"]),
+            declared_seconds=maybe_whole(fields["declared_seconds"]),
+            verified_seconds=maybe_whole(fields["verified_seconds"]),
+            actual_seconds=maybe_whole(fields["actual_seconds"]),
+            billable_seconds=maybe_whole(fields["billable_seconds"]),
+            retry_of=maybe_text(fields["retry_of"]),
+            created_at=to_datetime(fields["created_at"]),
+            options=JobOptions(
+                _extra=extra_fields(
+                    options,
+                    "language_code",
+                    "speaker_detection",
+                    "medical_mode",
+                    "multichannel",
+                    "translation_targets",
+                    "keyterms",
+                    "prompt",
+                    "auto_generate_insights",
+                ),
+                language_code=maybe_text(options["language_code"]),
+                speaker_detection=as_flag(options["speaker_detection"]),
+                medical_mode=as_flag(options["medical_mode"]),
+                multichannel=as_flag(options["multichannel"]),
+                translation_targets=[
+                    as_text(t) for t in as_list(options["translation_targets"]) or []
+                ],
+                keyterms=as_flag(options["keyterms"]),
+                prompt=as_flag(options["prompt"]),
+                auto_generate_insights=maybe_flag(options["auto_generate_insights"]),
+            ),
+        )

hushscript/_pacing.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from ._clock import Clock
+
+CREATES_PER_WINDOW: Final = 4
+WINDOW_SECONDS: Final = 60.0
+CREATE_RATE_LIMIT_BACKOFF: Final = (15.0, 30.0, 60.0)
+ACTIVE_JOBS_WAIT: Final = 30.0
+ACTIVE_JOBS_MAX_TRIES: Final = 10
+ACTIVE_JOBS_RETRIES: Final = ACTIVE_JOBS_MAX_TRIES - 1
+
+
+class TokenBucket:
+    """Paces `POST /v1/uploads` to 4 per 60 s per client (spec 7.5).
+
+    `reserve()` books the next slot and says how long the caller must wait before using it, so the
+    sync and async callers sleep on their own clock method.
+    """
+
+    def __init__(
+        self,
+        clock: Clock,
+        capacity: int = CREATES_PER_WINDOW,
+        window: float = WINDOW_SECONDS,
+    ) -> None:
+        self._clock = clock
+        self._capacity = capacity
+        self._window = window
+        self._slots: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def reserve(self) -> float:
+        with self._lock:
+            return self._reserve()
+
+    def _reserve(self) -> float:
+        now = self._clock.now()
+        while self._slots and self._slots[0] <= now - self._window:
+            self._slots.popleft()
+        if len(self._slots) < self._capacity:
+            self._slots.append(now)
+            return 0.0
+        wait = self._slots[0] + self._window - now
+        self._slots.popleft()
+        self._slots.append(now + wait)
+        return wait

hushscript/_redact.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import re
+from typing import Final
+from urllib.parse import quote
+
+from ._json import as_dict, as_list
+
+REDACTED: Final = "hsr…[redacted]"
+TOKEN_PATTERN: Final = re.compile(r"hsr\d+:[a-z]+:pat\.[0-9a-f]+\.[0-9a-f]+")
+MIN_SECRET_TAIL: Final = 16
+_WHOLE_TOKEN_FORMS: Final = 2
+"""A shorter echoed piece of a token is an ordinary substring, not worth redacting everywhere."""
+
+
+def _patterns(token: str) -> list[re.Pattern[str]]:
+    """What an API could echo of `token`, most specific first: the whole token as it is and
+    percent-encoded, then what follows `pat.` and the bare secret after the last dot. Matching
+    ignores case. A later piece is only ever a substring of an earlier one, so the order keeps the
+    id from being left behind."""
+    # surrogatepass: a lone surrogate in a registered secret still has a percent-encoded form
+    pieces = [token, quote(token, safe="", errors="surrogatepass")]
+    _, found, tail = token.partition("pat.")
+    if found:
+        pieces.append(tail)
+    pieces.append(token.rpartition(".")[2])
+    return [
+        re.compile(re.escape(piece), re.IGNORECASE)
+        for index, piece in enumerate(pieces)
+        if piece and (index < _WHOLE_TOKEN_FORMS or len(piece) >= MIN_SECRET_TAIL)
+    ]
+
+
+def redact(text: str) -> str:
+    return TOKEN_PATTERN.sub(REDACTED, text)
+
+
+QUERY_REDACTED: Final = "?[redacted]"
+_URL_QUERY: Final = re.compile(
+    # a URL with any scheme, or a path at the start of the text or after a space, quote, bracket
+    # or `=`; a query stops at a space, quote, angle bracket, `#` or `)`
+    r"((?:\b[a-z][a-z0-9+.-]*://[^\s\"'<>?#]+)|(?:(?<![^\s\"'(\[<=])/[^\s\"'<>?#]*))"
+    r"\?[^\s\"'<>#)]+",
+    re.IGNORECASE,
+)
+
+
+def redact_queries(text: str) -> str:
+    """R96: every URL or path in `text` keeps its scheme, host and path; its query string, which
+    holds a signed URL's signature, becomes `?[redacted]`."""
+    return _URL_QUERY.sub(lambda match: match.group(1) + QUERY_REDACTED, text)
+
+
+class Secret:
+    """A token or a signed URL held at rest: nothing prints, pickles or copies its text.
+
+    `repr`, `str`, `format`, `pprint`, `vars` and logging show the redaction marker. A pickle holds
+    an empty secret, and a copy is the same holder (it is immutable). `reveal()` is the one way to
+    the text.
+    """
+
+    __slots__ = ("_text",)
+
+    def __init__(self, text: str = "") -> None:
+        self._text = text
+
+    def reveal(self) -> str:
+        return self._text
+
+    def __bool__(self) -> bool:
+        return bool(self._text)
+
+    def __repr__(self) -> str:
+        return "Secret(<redacted>)"
+
+    def __str__(self) -> str:
+        return REDACTED
+
+    def __format__(self, format_spec: str) -> str:
+        return format(REDACTED, format_spec)
+
+    def __reduce__(self) -> tuple[type[Secret], tuple[str]]:
+        return (Secret, ("",))
+
+    def __copy__(self) -> Secret:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, object]) -> Secret:
+        return self
+
+
+class Credentials:
+    """The API token and every earlier one, kept out of every representation.
+
+    The token is held here and nowhere else in the client: not in a header on the httpx client, not
+    in a dataclass field. The transport reads it per request.
+    """
+
+    __slots__ = ("_known", "_tokens")
+
+    def __init__(self, token: str | None = None) -> None:
+        self._tokens: list[str] = []
+        self._known: list[str] = []
+        if token:
+            self._tokens.append(token)
+
+    @property
+    def token(self) -> str | None:
+        return self._tokens[-1] if self._tokens else None
+
+    def replace(self, token: str) -> None:
+        self._tokens.append(token)
+
+    def remember(self, token: str) -> None:
+        """Scrubs `token` from every text from now on without making it the one the client sends."""
+        if token and token not in self._known:
+            self._known.append(token)
+
+    def scrub(self, text: str) -> str:
+        for token in (*self._tokens, *self._known):
+            for pattern in _patterns(token):
+                text = pattern.sub(REDACTED, text)
+        return redact(text)
+
+    def scrub_value(self, value: object) -> object:
+        if isinstance(value, str):
+            return self.scrub(value)
+        mapping = as_dict(value)
+        if mapping is not None:
+            return {self.scrub(key): self.scrub_value(item) for key, item in mapping.items()}
+        items = as_list(value)
+        if items is not None:
+            return [self.scrub_value(item) for item in items]
+        return value
+
+    def __repr__(self) -> str:
+        return "Credentials(<redacted>)"
+
+    def __reduce__(self) -> str | tuple[object, ...]:
+        raise TypeError("credentials cannot be pickled")

hushscript/_response.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+from ._errors import ApiError, describe_failure, forget_body, raise_for_response, redacted_cause
+from ._json import loads
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import httpx
+
+    from ._redact import Credentials
+
+T = TypeVar("T")
+
+
+class BadBodyError(ValueError):
+    """A 2xx body that parses as JSON but not into the shape the SDK needs."""
+
+
+def bad_response(response: httpx.Response, what: str) -> ApiError:
+    """Spec 9.2: an unusable 2xx body, with the actual status and no numeric code."""
+    return ApiError(
+        f"The API's {what} could not be used.", code="bad_response", status=response.status_code
+    )
+
+
+def unreadable_response(
+    response: httpx.Response, failure: BaseException, credentials: Credentials | None
+) -> ApiError:
+    """`bad_response` for a body the SDK could not read, naming the original's type and redacted
+    message (R86). Its cause is a stand-in: a JSON error keeps the whole body it read, which may
+    hold a token or a claim secret."""
+    error = ApiError(
+        f"The API's response could not be used ({describe_failure(failure, credentials)}).",
+        code="bad_response",
+        status=response.status_code,
+    )
+    error.__cause__ = redacted_cause(failure, credentials)
+    forget_body(response)
+    return error
+
+
+def json_body(response: httpx.Response, credentials: Credentials) -> object:
+    """The JSON of a 2xx response; a non-2xx one raises the spec 9.2 error."""
+    raise_for_response(response, credentials=credentials)
+    try:
+        return loads(response.content)
+    except (
+        ValueError,
+        RecursionError,
+    ) as failure:  # a deeply nested body is not JSON the SDK reads
+        # Raised once the handler has ended, so the JSON error is not its context either.
+        failed = unreadable_response(response, failure, credentials)
+    raise failed
+
+
+def parsed(response: httpx.Response, credentials: Credentials, parse: Callable[[object], T]) -> T:
+    """`parse` of the JSON of a 2xx response; a body it cannot use is `bad_response`."""
+    body = json_body(response, credentials)
+    try:
+        return parse(body)
+    except BadBodyError as failure:
+        failed = unreadable_response(response, failure, credentials)
+    del body
+    raise failed