transcodely 0.2.0__py3-none-any.whl

transcodely/_transport/transport.py

@@ -0,0 +1,312 @@
+"""Hand-rolled Connect-RPC HTTP transport over httpx.
+
+Why not a Connect-Python client library? The ecosystem is sparse and none
+expose hooks for swapping the JSON codec, but Transcodely's wire format
+requires snake_case + simplified-enum JSON. Owning the transport gives us
+end-to-end control with ~250 LoC.
+
+Wire format reference:
+  - Unary: POST {base_url}/{service.full_name}/{method.name}
+           Content-Type: application/json
+           body: JSON-encoded request
+  - Server-streaming: same URL, Content-Type: application/connect+json
+           body: 5-byte envelope header + JSON payload, repeated
+           stream ends with an end-stream frame (flag bit 0x02)
+"""
+
+from __future__ import annotations
+
+import random
+import struct
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Generator, Iterable, Optional, TypeVar
+
+import httpx
+from google.protobuf.message import Message
+
+from .._codec import json_codec
+from ..errors import RateLimitError, TranscodelyError
+from ..version import API_VERSION, DEFAULT_BASE_URL
+from .error_mapping import connection_error, map_http_error
+from .headers import client_user_agent_json, new_idempotency_key, user_agent
+
+TReq = TypeVar("TReq", bound=Message)
+TRes = TypeVar("TRes", bound=Message)
+
+
+@dataclass
+class CallOptions:
+    """Per-call overrides for timeout, retries, idempotency, headers."""
+
+    timeout: Optional[float] = None
+    max_retries: Optional[int] = None
+    idempotency_key: Optional[str] = None
+    api_version: Optional[str] = None
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class LogEvent:
+    service: str
+    method: str
+    duration_ms: int
+    attempt: int
+    status: Optional[int] = None
+    request_id: Optional[str] = None
+    error: Optional[TranscodelyError] = None
+
+
+_WRITE_PREFIXES = ("Create", "Update", "Delete", "Cancel", "Confirm", "Revoke", "Archive", "Enable")
+
+
+def _is_write(method_name: str) -> bool:
+    return any(method_name.startswith(p) for p in _WRITE_PREFIXES)
+
+
+class Transport:
+    """Synchronous transport. ``client.jobs.*`` calls go through this."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        api_version: Optional[str] = None,
+        default_headers: Optional[dict[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+        logger: Optional[Callable[[LogEvent], None]] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Transcodely: api_key is required")
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.api_version = api_version or API_VERSION
+        self.default_headers = default_headers or {}
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+        self._logger = logger
+        #: ID of the most recent successful or failed request, Stripe-style.
+        self.last_request_id: Optional[str] = None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "Transport":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ---------- unary ----------
+
+    def unary(
+        self,
+        service_name: str,
+        method_name: str,
+        request: Message,
+        response: TRes,
+        opts: Optional[CallOptions] = None,
+    ) -> TRes:
+        opts = opts or CallOptions()
+        url = f"{self.base_url}/{service_name}/{method_name}"
+        body = json_codec.serialize(request)
+        idempotency_key = (
+            opts.idempotency_key or new_idempotency_key() if _is_write(method_name) else None
+        )
+
+        def attempt_call(attempt: int) -> TRes:
+            headers = self._build_headers(opts, "application/json", idempotency_key)
+            started = time.monotonic()
+            try:
+                resp = self._client.post(
+                    url,
+                    content=body,
+                    headers=headers,
+                    timeout=opts.timeout if opts.timeout is not None else self.timeout,
+                )
+            except httpx.HTTPError as exc:
+                raise connection_error(exc) from exc
+            self.last_request_id = resp.headers.get("x-request-id") or self.last_request_id
+            self._emit(
+                LogEvent(
+                    service=service_name,
+                    method=method_name,
+                    attempt=attempt,
+                    duration_ms=int((time.monotonic() - started) * 1000),
+                    status=resp.status_code,
+                    request_id=self.last_request_id,
+                )
+            )
+            if not (200 <= resp.status_code < 300):
+                raise map_http_error(
+                    status=resp.status_code,
+                    body=_try_json(resp.content),
+                    headers=resp.headers,
+                )
+            return json_codec.deserialize(resp.content, response)
+
+        return self._with_retry(service_name, method_name, opts, attempt_call)
+
+    # ---------- server-streaming ----------
+
+    def stream(
+        self,
+        service_name: str,
+        method_name: str,
+        request: Message,
+        response_factory: Callable[[], TRes],
+        opts: Optional[CallOptions] = None,
+    ) -> Generator[TRes, None, None]:
+        opts = opts or CallOptions()
+        url = f"{self.base_url}/{service_name}/{method_name}"
+        headers = self._build_headers(opts, "application/connect+json")
+        body = _encode_envelope(0, json_codec.serialize(request))
+        try:
+            with self._client.stream(
+                "POST",
+                url,
+                content=body,
+                headers=headers,
+                timeout=opts.timeout if opts.timeout is not None else None,
+            ) as resp:
+                self.last_request_id = resp.headers.get("x-request-id") or self.last_request_id
+                if not (200 <= resp.status_code < 300):
+                    text = resp.read()
+                    raise map_http_error(
+                        status=resp.status_code,
+                        body=_try_json(text),
+                        headers=resp.headers,
+                    )
+                for frame in _read_envelopes(resp.iter_bytes()):
+                    flags, payload = frame
+                    if flags & 0x02:
+                        # End-stream frame: payload may carry a JSON `error` block.
+                        if not payload:
+                            return
+                        end = _try_json(payload)
+                        if isinstance(end, dict) and end.get("error"):
+                            raise map_http_error(
+                                status=400,
+                                body=end["error"],
+                                headers=resp.headers,
+                            )
+                        return
+                    yield json_codec.deserialize(payload, response_factory())
+        except httpx.HTTPError as exc:
+            raise connection_error(exc) from exc
+
+    # ---------- helpers ----------
+
+    def _build_headers(
+        self,
+        opts: CallOptions,
+        content_type: str,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, str]:
+        headers = {
+            "content-type": content_type,
+            "connect-protocol-version": "1",
+            "authorization": f"Bearer {self.api_key}",
+            "user-agent": user_agent(),
+            "x-transcodely-client-user-agent": client_user_agent_json(),
+            "transcodely-version": opts.api_version or self.api_version,
+            "accept": content_type,
+        }
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        headers.update(self.default_headers)
+        headers.update(opts.headers)
+        return headers
+
+    def _emit(self, event: LogEvent) -> None:
+        if self._logger is not None:
+            try:
+                self._logger(event)
+            except Exception:
+                pass
+
+    def _with_retry(
+        self,
+        service: str,
+        method: str,
+        opts: CallOptions,
+        fn: Callable[[int], TRes],
+    ) -> TRes:
+        max_retries = opts.max_retries if opts.max_retries is not None else self.max_retries
+        last_error: Optional[BaseException] = None
+        for attempt in range(1, max_retries + 2):
+            try:
+                return fn(attempt)
+            except Exception as exc:
+                last_error = exc
+                if attempt > max_retries or not _is_retryable(exc):
+                    raise
+                _sleep_backoff(attempt, exc)
+        if last_error is not None:
+            raise last_error
+        raise RuntimeError("unreachable")
+
+
+def _is_retryable(exc: BaseException) -> bool:
+    if not isinstance(exc, TranscodelyError):
+        return False
+    if isinstance(exc, RateLimitError):
+        return True
+    if exc.__class__.__name__ == "APIConnectionError":
+        return True
+    if exc.http_status is not None and exc.http_status >= 500:
+        return True
+    return False
+
+
+def _sleep_backoff(attempt: int, exc: BaseException) -> None:
+    if isinstance(exc, RateLimitError) and exc.retry_after_ms is not None:
+        time.sleep(max(0.0, exc.retry_after_ms / 1000.0))
+        return
+    base = 0.25
+    cap = 2.0
+    expo = min(cap, base * 2 ** (attempt - 1))
+    jitter = expo * (0.5 + random.random() * 0.5)
+    time.sleep(jitter)
+
+
+# ---------- Connect envelope helpers ----------
+
+
+def _encode_envelope(flags: int, payload: bytes) -> bytes:
+    return struct.pack(">BI", flags & 0xFF, len(payload)) + payload
+
+
+def _read_envelopes(stream: Iterable[bytes]) -> Generator[tuple[int, bytes], None, None]:
+    buf = bytearray()
+    for chunk in stream:
+        if chunk:
+            buf.extend(chunk)
+        while len(buf) >= 5:
+            flags = buf[0]
+            length = struct.unpack(">I", bytes(buf[1:5]))[0]
+            if len(buf) < 5 + length:
+                break
+            payload = bytes(buf[5 : 5 + length])
+            del buf[: 5 + length]
+            yield flags, payload
+    if buf:
+        # Trailing bytes that didn't make a complete frame
+        raise connection_error(RuntimeError("stream ended with partial frame"))
+
+
+def _try_json(data: bytes) -> Any:
+    if not data:
+        return None
+    try:
+        import json
+
+        return json.loads(data.decode("utf-8"))
+    except Exception:
+        return data.decode("utf-8", errors="replace")

transcodely/client.py

@@ -0,0 +1,160 @@
+"""Transcodely root client (synchronous)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+import httpx
+
+from ._transport.transport import LogEvent, Transport
+from .resources.api_keys import ApiKeys
+from .resources.apps import Apps
+from .resources.events import Events
+from .resources.health import Health
+from .resources.jobs import Jobs
+from .resources.memberships import Memberships
+from .resources.organizations import Organizations
+from .resources.origins import Origins
+from .resources.presets import Presets
+from .resources.users import Users
+from .resources.videos import Videos
+from .resources.webhook_endpoints import WebhookEndpoints
+from .version import API_VERSION, SDK_VERSION
+from .webhooks import Webhooks
+
+
+class Transcodely:
+    """Synchronous Transcodely API client.
+
+    Use as a context manager (``with Transcodely(api_key=...) as client:``) to
+    make sure the underlying HTTP client is closed cleanly.
+    """
+
+    API_VERSION: str = API_VERSION
+    SDK_VERSION: str = SDK_VERSION
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        api_version: Optional[str] = None,
+        default_headers: Optional[dict[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+        logger: Optional[Callable[[LogEvent], None]] = None,
+    ) -> None:
+        self._transport = Transport(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            api_version=api_version,
+            default_headers=default_headers,
+            http_client=http_client,
+            logger=logger,
+        )
+        self._jobs: Optional[Jobs] = None
+        self._videos: Optional[Videos] = None
+        self._presets: Optional[Presets] = None
+        self._origins: Optional[Origins] = None
+        self._apps: Optional[Apps] = None
+        self._api_keys: Optional[ApiKeys] = None
+        self._organizations: Optional[Organizations] = None
+        self._memberships: Optional[Memberships] = None
+        self._users: Optional[Users] = None
+        self._health: Optional[Health] = None
+        self._webhook_endpoints: Optional[WebhookEndpoints] = None
+        self._events: Optional[Events] = None
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "Transcodely":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    @property
+    def last_request_id(self) -> Optional[str]:
+        """Stripe-style: ID of the most recent successful or failed request."""
+        return self._transport.last_request_id
+
+    @property
+    def jobs(self) -> Jobs:
+        if self._jobs is None:
+            self._jobs = Jobs(self._transport)
+        return self._jobs
+
+    @property
+    def videos(self) -> Videos:
+        if self._videos is None:
+            self._videos = Videos(self._transport)
+        return self._videos
+
+    @property
+    def presets(self) -> Presets:
+        if self._presets is None:
+            self._presets = Presets(self._transport)
+        return self._presets
+
+    @property
+    def origins(self) -> Origins:
+        if self._origins is None:
+            self._origins = Origins(self._transport)
+        return self._origins
+
+    @property
+    def apps(self) -> Apps:
+        if self._apps is None:
+            self._apps = Apps(self._transport)
+        return self._apps
+
+    @property
+    def api_keys(self) -> ApiKeys:
+        if self._api_keys is None:
+            self._api_keys = ApiKeys(self._transport)
+        return self._api_keys
+
+    @property
+    def organizations(self) -> Organizations:
+        if self._organizations is None:
+            self._organizations = Organizations(self._transport)
+        return self._organizations
+
+    @property
+    def memberships(self) -> Memberships:
+        if self._memberships is None:
+            self._memberships = Memberships(self._transport)
+        return self._memberships
+
+    @property
+    def users(self) -> Users:
+        if self._users is None:
+            self._users = Users(self._transport)
+        return self._users
+
+    @property
+    def health(self) -> Health:
+        if self._health is None:
+            self._health = Health(self._transport)
+        return self._health
+
+    @property
+    def webhook_endpoints(self) -> WebhookEndpoints:
+        if self._webhook_endpoints is None:
+            self._webhook_endpoints = WebhookEndpoints(self._transport)
+        return self._webhook_endpoints
+
+    @property
+    def events(self) -> Events:
+        if self._events is None:
+            self._events = Events(self._transport)
+        return self._events
+
+    @property
+    def webhooks(self) -> type[Webhooks]:
+        """Stripe-style facade: ``client.webhooks.construct_event(body, sig, secret)``."""
+        return Webhooks

transcodely/errors.py

@@ -0,0 +1,115 @@
+"""Typed exception hierarchy for the Transcodely SDK.
+
+Every exception raised by SDK methods inherits from :class:`TranscodelyError`,
+so ``except TranscodelyError`` plus ``isinstance`` checks is enough for typed
+error handling. Mirrors the TypeScript and Go SDK error classes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass(frozen=True)
+class FieldViolation:
+    """A field-level validation violation from an :class:`InvalidRequestError`."""
+
+    field: str
+    description: str
+
+
+class TranscodelyError(Exception):
+    """Base class for every Transcodely SDK exception."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        type: Optional[str] = None,
+        errors: Optional[list[FieldViolation]] = None,
+        http_status: Optional[int] = None,
+        request_id: Optional[str] = None,
+        raw: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.code: Optional[str] = code
+        self.type: Optional[str] = type
+        self.errors: list[FieldViolation] = errors or []
+        self.http_status: Optional[int] = http_status
+        self.request_id: Optional[str] = request_id
+        self.raw: Any = raw
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(message={super().__str__()!r}, code={self.code!r}, "
+            f"http_status={self.http_status!r}, request_id={self.request_id!r})"
+        )
+
+
+class APIConnectionError(TranscodelyError):
+    """Network failure: DNS, TLS, connection refused, no HTTP response."""
+
+
+class APIError(TranscodelyError):
+    """5xx server-side error."""
+
+
+class AuthenticationError(TranscodelyError):
+    """401 — invalid, missing, revoked, or expired API key."""
+
+
+class PermissionError(TranscodelyError):
+    """403 — authenticated but lacking permission."""
+
+
+class NotFoundError(TranscodelyError):
+    """404 — entity not found."""
+
+
+class ConflictError(TranscodelyError):
+    """409 — already exists, idempotency conflict, slug taken."""
+
+
+class RateLimitError(TranscodelyError):
+    """429 — rate-limited. ``retry_after_ms`` reflects the ``Retry-After`` header."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_ms: Optional[int] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after_ms: Optional[int] = retry_after_ms
+
+
+class InvalidRequestError(TranscodelyError):
+    """400 / 422 — request body or parameters were invalid."""
+
+
+class PreconditionError(TranscodelyError):
+    """412 — preconditions not met (e.g. job not cancelable in current state)."""
+
+
+class WebhookError(TranscodelyError):
+    """Base class for webhook signature-verification failures.
+
+    Raised by :func:`transcodely.construct_event` /
+    :func:`transcodely.verify_signature`. Catch this to handle any verification
+    failure, or one of its subclasses to distinguish the cause.
+    """
+
+
+class WebhookSignatureError(WebhookError):
+    """The signature header was malformed or no signature matched the body."""
+
+
+class WebhookTimestampError(WebhookError):
+    """The signature timestamp fell outside the allowed tolerance window."""
+
+
+class WebhookPayloadError(WebhookError):
+    """The body was not valid JSON or did not match the event-envelope shape."""

transcodely/pagination.py

@@ -0,0 +1,53 @@
+"""Cursor pagination helper.
+
+Every ``list`` method returns a :class:`Page` you can iterate manually or via
+``.auto_paging_iter()`` to walk every result lazily.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Generator, Generic, Iterator, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class PageContents(Generic[T]):
+    items: list[T]
+    next_cursor: Optional[str]
+
+
+class Page(Generic[T]):
+    """A single page of results plus an opt-in iterator across all pages."""
+
+    def __init__(self, fetcher: Callable[[Optional[str]], PageContents[T]]) -> None:
+        self._fetcher = fetcher
+        self._first: Optional[PageContents[T]] = None
+
+    @property
+    def items(self) -> list[T]:
+        return self._first_page().items
+
+    @property
+    def next_cursor(self) -> Optional[str]:
+        return self._first_page().next_cursor
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self._first_page().items)
+
+    def auto_paging_iter(self) -> Generator[T, None, None]:
+        """Yield every item, transparently fetching subsequent pages."""
+        cursor: Optional[str] = None
+        while True:
+            page = self._fetcher(cursor)
+            for item in page.items:
+                yield item
+            if not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    def _first_page(self) -> PageContents[T]:
+        if self._first is None:
+            self._first = self._fetcher(None)
+        return self._first

transcodely/resources/_helpers.py

@@ -0,0 +1,29 @@
+"""Internal helpers shared by resource modules."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from google.protobuf import json_format
+from google.protobuf.message import Message
+
+from .._codec.json_codec import transform_enums_in_dict
+
+
+def fill_from_dict(msg: Message, data: Mapping[str, Any]) -> Message:
+    """Populate ``msg`` from a plain dict, accepting simplified-enum strings.
+
+    The codec's enum-expand pass lets callers pass ``{"codec": "h264"}`` while
+    the proto stores ``VIDEO_CODEC_H264`` (an int after parse).
+    """
+    payload = dict(data)
+    transform_enums_in_dict(payload, msg.DESCRIPTOR, mode="expand")
+    json_format.ParseDict(payload, msg, ignore_unknown_fields=True)
+    return msg
+
+
+def assign_pagination(req_pagination: Any, *, limit: Optional[int], cursor: Optional[str]) -> None:
+    if limit is not None:
+        req_pagination.limit = limit
+    if cursor is not None:
+        req_pagination.cursor = cursor