transcodely 0.2.0__py3-none-any.whl

transcodely/__init__.py

@@ -0,0 +1,175 @@
+"""Official Python SDK for the Transcodely video transcoding API.
+
+Quick start:
+
+.. code-block:: python
+
+    import os
+    from transcodely import Transcodely
+
+    with Transcodely(api_key=os.environ["TRANSCODELY_API_KEY"]) as client:
+        job = client.jobs.create(
+            input_url="https://example.com/source.mp4",
+            outputs=[{
+                "type": "hls",
+                "video": [
+                    {"codec": "h264", "resolution": "1080p"},
+                    {"codec": "h264", "resolution": "720p"},
+                ],
+            }],
+        )
+        print(job.id)
+
+        for event in client.jobs.watch(job.id):
+            print(event.job.status, event.job.progress)
+
+Headline message and enum classes are re-exported here for ergonomics. Every
+public proto class is reachable via :mod:`transcodely.types`. Generated
+modules also remain available at ``transcodely.v1.{name}_pb2`` for power users.
+"""
+
+from .client import Transcodely
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    FieldViolation,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    PreconditionError,
+    RateLimitError,
+    TranscodelyError,
+    WebhookError,
+    WebhookPayloadError,
+    WebhookSignatureError,
+    WebhookTimestampError,
+)
+from .pagination import Page, PageContents
+from .version import API_VERSION, DEFAULT_BASE_URL, SDK_VERSION
+from .webhooks import (
+    DEFAULT_TOLERANCE_SECONDS,
+    EVENT_ID_HEADER,
+    SIGNATURE_HEADER,
+    Event,
+    EventRequest,
+    EventType,
+    WebhookEvent,
+    Webhooks,
+    construct_event,
+    verify_signature,
+)
+
+# Headline message classes — most callers reach for these. Everything else lives
+# in :mod:`transcodely.types`.
+from .types import (
+    APIKey,
+    App,
+    AudioTrackConfig,
+    AutoABRConfig,
+    ContentAwareConfig,
+    DASHConfig,
+    DRMConfig,
+    HDRConfig,
+    HLSConfig,
+    Job,
+    JobOutput,
+    JobPriority,
+    JobStatus,
+    Membership,
+    Organization,
+    Origin,
+    OutputFormat,
+    OutputSpec,
+    OutputStatus,
+    Preset,
+    PresetVariant,
+    Resolution,
+    StreamingConfig,
+    SubtitleTrack,
+    ThumbnailResult,
+    ThumbnailSpec,
+    User,
+    UserWithOrganizations,
+    Video,
+    VideoCodec,
+    VideoRendition,
+    VideoVariant,
+    WatchEventType,
+    WatchJobResponse,
+    WatchVideoResponse,
+    WebhookDelivery,
+    WebhookEndpoint,
+)
+
+__all__ = [
+    "API_VERSION",
+    "APIConnectionError",
+    "APIError",
+    "APIKey",
+    "App",
+    "AudioTrackConfig",
+    "AuthenticationError",
+    "AutoABRConfig",
+    "ConflictError",
+    "construct_event",
+    "ContentAwareConfig",
+    "DASHConfig",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "DRMConfig",
+    "Event",
+    "EVENT_ID_HEADER",
+    "EventRequest",
+    "EventType",
+    "FieldViolation",
+    "HDRConfig",
+    "HLSConfig",
+    "InvalidRequestError",
+    "Job",
+    "JobOutput",
+    "JobPriority",
+    "JobStatus",
+    "Membership",
+    "NotFoundError",
+    "Organization",
+    "Origin",
+    "OutputFormat",
+    "OutputSpec",
+    "OutputStatus",
+    "Page",
+    "PageContents",
+    "PermissionError",
+    "PreconditionError",
+    "Preset",
+    "PresetVariant",
+    "RateLimitError",
+    "Resolution",
+    "SDK_VERSION",
+    "SIGNATURE_HEADER",
+    "StreamingConfig",
+    "SubtitleTrack",
+    "ThumbnailResult",
+    "ThumbnailSpec",
+    "Transcodely",
+    "TranscodelyError",
+    "User",
+    "UserWithOrganizations",
+    "verify_signature",
+    "Video",
+    "VideoCodec",
+    "VideoRendition",
+    "VideoVariant",
+    "WatchEventType",
+    "WatchJobResponse",
+    "WatchVideoResponse",
+    "WebhookDelivery",
+    "WebhookEndpoint",
+    "WebhookError",
+    "WebhookEvent",
+    "WebhookPayloadError",
+    "Webhooks",
+    "WebhookSignatureError",
+    "WebhookTimestampError",
+]

transcodely/_codec/json_codec.py

@@ -0,0 +1,193 @@
+"""JSON serialization for the Transcodely wire format.
+
+Wraps protobuf's ``MessageToDict`` / ``ParseDict`` with snake_case field names
+and lowercase simplified enum values, mirroring ``internal/connect/codec.go``
+on the server. Behavior must stay bit-identical with the TypeScript and Go
+codecs — see the cross-language conformance suite.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, TypeVar
+
+from google.protobuf import json_format
+from google.protobuf.descriptor import EnumDescriptor, FieldDescriptor
+from google.protobuf.message import Message
+
+T = TypeVar("T", bound=Message)
+
+_CAMEL_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def camel_to_screaming_snake(name: str) -> str:
+    """``"JobStatus" → "JOB_STATUS"``; ``"HLSSegmentFormat" → "HLS_SEGMENT_FORMAT"``."""
+    out: list[str] = []
+    for i, ch in enumerate(name):
+        if i > 0 and ch.isupper():
+            prev = name[i - 1]
+            nxt = name[i + 1] if i + 1 < len(name) else ""
+            if prev.islower() or (nxt and nxt.islower()):
+                out.append("_")
+        out.append(ch.upper())
+    return "".join(out)
+
+
+def enum_prefix(enum_desc: EnumDescriptor) -> str:
+    """``"JobStatus" → "JOB_STATUS_"`` — the prefix the server strips/restores."""
+    return camel_to_screaming_snake(enum_desc.name) + "_"
+
+
+def simplify_enum_value(value: str, enum_desc: EnumDescriptor) -> str:
+    """``"JOB_STATUS_PENDING" → "pending"``."""
+    prefix = enum_prefix(enum_desc)
+    if value.startswith(prefix):
+        return value[len(prefix) :].lower()
+    return value.lower()
+
+
+def expand_enum_value(value: str, enum_desc: EnumDescriptor) -> str:
+    """``"pending" → "JOB_STATUS_PENDING"`` (using the enum's full-name set)."""
+    if enum_desc.values_by_name.get(value) is not None:
+        return value
+    candidate = enum_prefix(enum_desc) + value.upper()
+    if enum_desc.values_by_name.get(candidate) is not None:
+        return candidate
+    return value
+
+
+def transform_enums_in_dict(
+    obj: Any,
+    msg_desc: Any,
+    *,
+    mode: str,
+) -> None:
+    """Recursively walk a JSON dict/list tree and translate every enum string.
+
+    ``mode`` is ``"simplify"`` (outbound) or ``"expand"`` (inbound).
+    """
+    if not isinstance(obj, dict):
+        return
+
+    for field in msg_desc.fields:
+        key = _pick_key(obj, field)
+        if key is None:
+            continue
+        v = obj[key]
+        if v is None:
+            continue
+        _transform_field(obj, key, v, field, mode)
+
+
+def _pick_key(obj: dict[str, Any], field: FieldDescriptor) -> str | None:
+    # camelCase JSON name (default protobuf JSON) takes precedence; proto name
+    # accepted as fallback for tolerant parsing.
+    if field.json_name in obj:
+        return field.json_name
+    if field.name in obj:
+        return field.name
+    return None
+
+
+def _transform_field(
+    parent: dict[str, Any],
+    key: str,
+    v: Any,
+    field: FieldDescriptor,
+    mode: str,
+) -> None:
+    # Map fields: protobuf models them as repeated message of generated entry types.
+    if field.message_type and field.message_type.GetOptions().map_entry:
+        if not isinstance(v, dict):
+            return
+        value_field = field.message_type.fields_by_name["value"]
+        if value_field.type == FieldDescriptor.TYPE_ENUM:
+            enum_desc = value_field.enum_type
+            for k, item in list(v.items()):
+                if isinstance(item, str):
+                    v[k] = _apply_enum(item, enum_desc, mode)
+        elif value_field.type == FieldDescriptor.TYPE_MESSAGE:
+            for k, item in list(v.items()):
+                if isinstance(item, dict):
+                    transform_enums_in_dict(item, value_field.message_type, mode=mode)
+        return
+
+    if field.is_repeated:
+        if not isinstance(v, list):
+            return
+        if field.type == FieldDescriptor.TYPE_ENUM:
+            enum_desc = field.enum_type
+            for i, item in enumerate(v):
+                if isinstance(item, str):
+                    v[i] = _apply_enum(item, enum_desc, mode)
+        elif field.type == FieldDescriptor.TYPE_MESSAGE:
+            for item in v:
+                if isinstance(item, dict):
+                    transform_enums_in_dict(item, field.message_type, mode=mode)
+        return
+
+    if field.type == FieldDescriptor.TYPE_ENUM:
+        if isinstance(v, str):
+            parent[key] = _apply_enum(v, field.enum_type, mode)
+        return
+
+    if field.type == FieldDescriptor.TYPE_MESSAGE:
+        if isinstance(v, dict):
+            transform_enums_in_dict(v, field.message_type, mode=mode)
+
+
+def _apply_enum(value: str, enum_desc: EnumDescriptor, mode: str) -> str:
+    return (
+        simplify_enum_value(value, enum_desc)
+        if mode == "simplify"
+        else expand_enum_value(value, enum_desc)
+    )
+
+
+def _message_to_dict(msg: Message) -> dict[str, Any]:
+    """``MessageToDict`` with the right kwarg for both protobuf v5 and v6."""
+    try:
+        return json_format.MessageToDict(  # type: ignore[call-arg]
+            msg,
+            preserving_proto_field_name=True,
+            always_print_fields_with_no_presence=True,
+            use_integers_for_enums=False,
+        )
+    except TypeError:
+        # protobuf < 5.27 used `including_default_value_fields`
+        return json_format.MessageToDict(  # type: ignore[call-arg]
+            msg,
+            preserving_proto_field_name=True,
+            including_default_value_fields=True,
+            use_integers_for_enums=False,
+        )
+
+
+def serialize(msg: Message) -> bytes:
+    """Encode a proto message as Transcodely-wire JSON bytes."""
+    obj = _message_to_dict(msg)
+    transform_enums_in_dict(obj, msg.DESCRIPTOR, mode="simplify")
+    return json.dumps(obj).encode("utf-8")
+
+
+def deserialize(data: bytes, msg: T) -> T:
+    """Decode Transcodely-wire JSON bytes into ``msg`` (mutated in place, returned for chaining)."""
+    if not data:
+        return msg
+    parsed = json.loads(data.decode("utf-8"))
+    if isinstance(parsed, dict):
+        transform_enums_in_dict(parsed, msg.DESCRIPTOR, mode="expand")
+    json_format.ParseDict(parsed, msg, ignore_unknown_fields=True)
+    return msg
+
+
+__all__ = [
+    "camel_to_screaming_snake",
+    "deserialize",
+    "enum_prefix",
+    "expand_enum_value",
+    "serialize",
+    "simplify_enum_value",
+    "transform_enums_in_dict",
+]

transcodely/_transport/error_mapping.py

@@ -0,0 +1,102 @@
+"""Map a Connect-RPC error response (HTTP status + JSON body) to a typed exception."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional
+
+from ..errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    FieldViolation,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    PreconditionError,
+    RateLimitError,
+    TranscodelyError,
+)
+
+
+def map_http_error(*, status: int, body: Any, headers: Mapping[str, str]) -> TranscodelyError:
+    request_id = _header(headers, "x-request-id")
+    parsed = _parse_body(body)
+    message = parsed.get("message") or f"HTTP {status}"
+    detail = (parsed.get("details") or [{}])[0].get("debug") or {}
+    code = detail.get("code")
+    raw_violations = detail.get("field_violations") or detail.get("fieldViolations") or []
+    violations = [
+        FieldViolation(field=v.get("field", ""), description=v.get("description", ""))
+        for v in raw_violations
+        if isinstance(v, dict)
+    ]
+    kwargs = {
+        "code": code,
+        "type": parsed.get("code"),
+        "errors": violations,
+        "http_status": status,
+        "request_id": request_id,
+        "raw": body,
+    }
+
+    if status == 401:
+        return AuthenticationError(message, **kwargs)
+    if status == 403:
+        return PermissionError(message, **kwargs)
+    if status == 404:
+        return NotFoundError(message, **kwargs)
+    if status == 409:
+        return ConflictError(message, **kwargs)
+    if status == 412:
+        return PreconditionError(message, **kwargs)
+    if status == 422:
+        return InvalidRequestError(message, **kwargs)
+    if status == 429:
+        retry_after = _header(headers, "retry-after")
+        retry_after_ms: Optional[int] = None
+        if retry_after:
+            try:
+                retry_after_ms = max(0, int(retry_after) * 1000)
+            except ValueError:
+                retry_after_ms = None
+        return RateLimitError(message, retry_after_ms=retry_after_ms, **kwargs)
+    if status >= 500:
+        return APIError(message, **kwargs)
+    if status >= 400:
+        return InvalidRequestError(message, **kwargs)
+    return APIError(message, **kwargs)
+
+
+def connection_error(cause: BaseException, message: Optional[str] = None) -> APIConnectionError:
+    msg = message or str(cause) or "network request failed"
+    err = APIConnectionError(msg)
+    err.__cause__ = cause
+    return err
+
+
+def _parse_body(body: Any) -> dict[str, Any]:
+    if isinstance(body, dict):
+        return body
+    if isinstance(body, (bytes, bytearray)):
+        try:
+            return json.loads(body.decode("utf-8"))
+        except Exception:
+            return {"message": body.decode("utf-8", errors="replace")}
+    if isinstance(body, str):
+        try:
+            return json.loads(body)
+        except Exception:
+            return {"message": body}
+    return {}
+
+
+def _header(headers: Mapping[str, str], key: str) -> Optional[str]:
+    # httpx headers are case-insensitive but expose .get with the lowercase form.
+    if hasattr(headers, "get"):
+        try:
+            return headers.get(key) or headers.get(key.title())
+        except Exception:
+            return None
+    return None

transcodely/_transport/headers.py

@@ -0,0 +1,31 @@
+"""HTTP header helpers — user-agent, idempotency keys, structured client metadata."""
+
+from __future__ import annotations
+
+import json
+import platform
+import sys
+import uuid
+
+from ..version import SDK_VERSION
+
+
+def user_agent() -> str:
+    return f"Transcodely/{SDK_VERSION} python/{sys.version_info.major}.{sys.version_info.minor}"
+
+
+def client_user_agent_json() -> str:
+    return json.dumps(
+        {
+            "lang": "python",
+            "lang_version": platform.python_version(),
+            "platform": f"{platform.system()} {platform.release()} {platform.machine()}",
+            "publisher": "transcodely",
+            "version": SDK_VERSION,
+        },
+        separators=(",", ":"),
+    )
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())