transcodely 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

transcodely/__init__.py

@@ -47,19 +47,6 @@ from .errors import (
     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`.
@@ -68,11 +55,18 @@ from .types import (
     App,
     AudioTrackConfig,
     AutoABRConfig,
+    ChapterPoint,
+    ChapterResult,
+    ClipConfig,
     ContentAwareConfig,
     DASHConfig,
     DRMConfig,
     HDRConfig,
     HLSConfig,
+    Invoice,
+    InvoiceLineItem,
+    InvoiceLineType,
+    InvoiceStatus,
     Job,
     JobOutput,
     JobPriority,
@@ -87,6 +81,7 @@ from .types import (
     PresetVariant,
     Resolution,
     StreamingConfig,
+    SubtitleResult,
     SubtitleTrack,
     ThumbnailResult,
     ThumbnailSpec,
@@ -95,16 +90,36 @@ from .types import (
     Video,
     VideoCodec,
     VideoRendition,
+    VideoTextTrack,
     VideoVariant,
     WatchEventType,
     WatchJobResponse,
     WatchVideoResponse,
+    WatermarkConfig,
     WebhookDelivery,
     WebhookEndpoint,
 )
+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,
+)
 
 __all__ = [
     "API_VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "EVENT_ID_HEADER",
+    "SDK_VERSION",
+    "SIGNATURE_HEADER",
     "APIConnectionError",
     "APIError",
     "APIKey",
@@ -112,21 +127,24 @@ __all__ = [
     "AudioTrackConfig",
     "AuthenticationError",
     "AutoABRConfig",
+    "ChapterPoint",
+    "ChapterResult",
+    "ClipConfig",
     "ConflictError",
-    "construct_event",
     "ContentAwareConfig",
     "DASHConfig",
-    "DEFAULT_BASE_URL",
-    "DEFAULT_TOLERANCE_SECONDS",
     "DRMConfig",
     "Event",
-    "EVENT_ID_HEADER",
     "EventRequest",
     "EventType",
     "FieldViolation",
     "HDRConfig",
     "HLSConfig",
     "InvalidRequestError",
+    "Invoice",
+    "InvoiceLineItem",
+    "InvoiceLineType",
+    "InvoiceStatus",
     "Job",
     "JobOutput",
     "JobPriority",
@@ -146,9 +164,8 @@ __all__ = [
     "PresetVariant",
     "RateLimitError",
     "Resolution",
-    "SDK_VERSION",
-    "SIGNATURE_HEADER",
     "StreamingConfig",
+    "SubtitleResult",
     "SubtitleTrack",
     "ThumbnailResult",
     "ThumbnailSpec",
@@ -156,20 +173,23 @@ __all__ = [
     "TranscodelyError",
     "User",
     "UserWithOrganizations",
-    "verify_signature",
     "Video",
     "VideoCodec",
     "VideoRendition",
+    "VideoTextTrack",
     "VideoVariant",
     "WatchEventType",
     "WatchJobResponse",
     "WatchVideoResponse",
+    "WatermarkConfig",
     "WebhookDelivery",
     "WebhookEndpoint",
     "WebhookError",
     "WebhookEvent",
     "WebhookPayloadError",
-    "Webhooks",
     "WebhookSignatureError",
     "WebhookTimestampError",
+    "Webhooks",
+    "construct_event",
+    "verify_signature",
 ]

transcodely/_codec/json_codec.py

@@ -132,9 +132,8 @@ def _transform_field(
             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)
+    if field.type == FieldDescriptor.TYPE_MESSAGE and isinstance(v, dict):
+        transform_enums_in_dict(v, field.message_type, mode=mode)
 
 
 def _apply_enum(value: str, enum_desc: EnumDescriptor, mode: str) -> str:

transcodely/_transport/error_mapping.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
 
 from ..errors import (
     APIConnectionError,
@@ -55,7 +56,7 @@ def map_http_error(*, status: int, body: Any, headers: Mapping[str, str]) -> Tra
         return InvalidRequestError(message, **kwargs)
     if status == 429:
         retry_after = _header(headers, "retry-after")
-        retry_after_ms: Optional[int] = None
+        retry_after_ms: int | None = None
         if retry_after:
             try:
                 retry_after_ms = max(0, int(retry_after) * 1000)
@@ -69,7 +70,7 @@ def map_http_error(*, status: int, body: Any, headers: Mapping[str, str]) -> Tra
     return APIError(message, **kwargs)
 
 
-def connection_error(cause: BaseException, message: Optional[str] = None) -> APIConnectionError:
+def connection_error(cause: BaseException, message: str | None = None) -> APIConnectionError:
     msg = message or str(cause) or "network request failed"
     err = APIConnectionError(msg)
     err.__cause__ = cause
@@ -82,21 +83,21 @@ def _parse_body(body: Any) -> dict[str, Any]:
     if isinstance(body, (bytes, bytearray)):
         try:
             return json.loads(body.decode("utf-8"))
-        except Exception:
+        except (UnicodeDecodeError, json.JSONDecodeError):
             return {"message": body.decode("utf-8", errors="replace")}
     if isinstance(body, str):
         try:
             return json.loads(body)
-        except Exception:
+        except json.JSONDecodeError:
             return {"message": body}
     return {}
 
 
-def _header(headers: Mapping[str, str], key: str) -> Optional[str]:
+def _header(headers: Mapping[str, str], key: str) -> str | None:
     # 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:
+        except Exception:  # noqa: BLE001 — headers may be any duck-typed mapping
             return None
     return None

transcodely/_transport/transport.py

@@ -19,11 +19,13 @@ from __future__ import annotations
 import random
 import struct
 import time
+from collections.abc import Callable, Generator, Iterable
 from dataclasses import dataclass, field
-from typing import Any, Callable, Generator, Iterable, Optional, TypeVar
+from typing import Any, TypeVar
 
 import httpx
 from google.protobuf.message import Message
+from typing_extensions import Self
 
 from .._codec import json_codec
 from ..errors import RateLimitError, TranscodelyError
@@ -39,10 +41,10 @@ TRes = TypeVar("TRes", bound=Message)
 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
+    timeout: float | None = None
+    max_retries: int | None = None
+    idempotency_key: str | None = None
+    api_version: str | None = None
     headers: dict[str, str] = field(default_factory=dict)
 
 
@@ -52,9 +54,9 @@ class LogEvent:
     method: str
     duration_ms: int
     attempt: int
-    status: Optional[int] = None
-    request_id: Optional[str] = None
-    error: Optional[TranscodelyError] = None
+    status: int | None = None
+    request_id: str | None = None
+    error: TranscodelyError | None = None
 
 
 _WRITE_PREFIXES = ("Create", "Update", "Delete", "Cancel", "Confirm", "Revoke", "Archive", "Enable")
@@ -71,17 +73,19 @@ class Transport:
         self,
         api_key: str,
         *,
-        base_url: Optional[str] = None,
+        organization_id: str | None = None,
+        base_url: str | None = 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,
+        api_version: str | None = None,
+        default_headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+        logger: Callable[[LogEvent], None] | None = None,
     ) -> None:
         if not api_key:
             raise ValueError("Transcodely: api_key is required")
         self.api_key = api_key
+        self.organization_id = organization_id
         self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
         self.timeout = timeout
         self.max_retries = max_retries
@@ -91,16 +95,16 @@ class Transport:
         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
+        self.last_request_id: str | None = None
 
     def close(self) -> None:
         if self._owns_client:
             self._client.close()
 
-    def __enter__(self) -> "Transport":
+    def __enter__(self) -> Self:
         return self
 
-    def __exit__(self, *args: Any) -> None:
+    def __exit__(self, *args: object) -> None:
         self.close()
 
     # ---------- unary ----------
@@ -111,7 +115,7 @@ class Transport:
         method_name: str,
         request: Message,
         response: TRes,
-        opts: Optional[CallOptions] = None,
+        opts: CallOptions | None = None,
     ) -> TRes:
         opts = opts or CallOptions()
         url = f"{self.base_url}/{service_name}/{method_name}"
@@ -161,7 +165,7 @@ class Transport:
         method_name: str,
         request: Message,
         response_factory: Callable[[], TRes],
-        opts: Optional[CallOptions] = None,
+        opts: CallOptions | None = None,
     ) -> Generator[TRes, None, None]:
         opts = opts or CallOptions()
         url = f"{self.base_url}/{service_name}/{method_name}"
@@ -207,7 +211,7 @@ class Transport:
         self,
         opts: CallOptions,
         content_type: str,
-        idempotency_key: Optional[str] = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, str]:
         headers = {
             "content-type": content_type,
@@ -218,6 +222,8 @@ class Transport:
             "transcodely-version": opts.api_version or self.api_version,
             "accept": content_type,
         }
+        if self.organization_id:
+            headers["x-organization-id"] = self.organization_id
         if idempotency_key:
             headers["idempotency-key"] = idempotency_key
         headers.update(self.default_headers)
@@ -228,7 +234,7 @@ class Transport:
         if self._logger is not None:
             try:
                 self._logger(event)
-            except Exception:
+            except Exception:  # noqa: BLE001, S110 — a caller's logger must never break requests
                 pass
 
     def _with_retry(
@@ -239,7 +245,7 @@ class Transport:
         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
+        last_error: BaseException | None = None
         for attempt in range(1, max_retries + 2):
             try:
                 return fn(attempt)
@@ -260,9 +266,7 @@ def _is_retryable(exc: BaseException) -> bool:
         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
+    return exc.http_status is not None and exc.http_status >= 500
 
 
 def _sleep_backoff(attempt: int, exc: BaseException) -> None:
@@ -308,5 +312,5 @@ def _try_json(data: bytes) -> Any:
         import json
 
         return json.loads(data.decode("utf-8"))
-    except Exception:
+    except (UnicodeDecodeError, json.JSONDecodeError):
         return data.decode("utf-8", errors="replace")

transcodely/client.py

@@ -2,13 +2,15 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Optional
+from collections.abc import Callable
 
 import httpx
+from typing_extensions import Self
 
 from ._transport.transport import LogEvent, Transport
 from .resources.api_keys import ApiKeys
 from .resources.apps import Apps
+from .resources.billing import Billing
 from .resources.events import Events
 from .resources.health import Health
 from .resources.jobs import Jobs
@@ -37,16 +39,18 @@ class Transcodely:
         self,
         api_key: str,
         *,
-        base_url: Optional[str] = None,
+        organization_id: str | None = None,
+        base_url: str | None = 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,
+        api_version: str | None = None,
+        default_headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+        logger: Callable[[LogEvent], None] | None = None,
     ) -> None:
         self._transport = Transport(
             api_key,
+            organization_id=organization_id,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -55,30 +59,31 @@ class Transcodely:
             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
+        self._jobs: Jobs | None = None
+        self._videos: Videos | None = None
+        self._presets: Presets | None = None
+        self._origins: Origins | None = None
+        self._apps: Apps | None = None
+        self._api_keys: ApiKeys | None = None
+        self._organizations: Organizations | None = None
+        self._memberships: Memberships | None = None
+        self._users: Users | None = None
+        self._health: Health | None = None
+        self._webhook_endpoints: WebhookEndpoints | None = None
+        self._events: Events | None = None
+        self._billing: Billing | None = None
 
     def close(self) -> None:
         self._transport.close()
 
-    def __enter__(self) -> "Transcodely":
+    def __enter__(self) -> Self:
         return self
 
-    def __exit__(self, *args: Any) -> None:
+    def __exit__(self, *args: object) -> None:
         self.close()
 
     @property
-    def last_request_id(self) -> Optional[str]:
+    def last_request_id(self) -> str | None:
         """Stripe-style: ID of the most recent successful or failed request."""
         return self._transport.last_request_id
 
@@ -154,6 +159,18 @@ class Transcodely:
             self._events = Events(self._transport)
         return self._events
 
+    @property
+    def billing(self) -> Billing:
+        """The organization's invoices.
+
+        Needs a dashboard session token for an organization owner plus
+        ``organization_id`` on the client; API keys are rejected. See
+        :class:`~transcodely.resources.billing.Billing`.
+        """
+        if self._billing is None:
+            self._billing = Billing(self._transport)
+        return self._billing
+
     @property
     def webhooks(self) -> type[Webhooks]:
         """Stripe-style facade: ``client.webhooks.construct_event(body, sig, secret)``."""

transcodely/errors.py

@@ -8,7 +8,7 @@ error handling. Mirrors the TypeScript and Go SDK error classes.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Optional
+from typing import Any
 
 
 @dataclass(frozen=True)
@@ -26,19 +26,19 @@ class TranscodelyError(Exception):
         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,
+        code: str | None = None,
+        type: str | None = None,
+        errors: list[FieldViolation] | None = None,
+        http_status: int | None = None,
+        request_id: str | None = None,
         raw: Any = None,
     ) -> None:
         super().__init__(message)
-        self.code: Optional[str] = code
-        self.type: Optional[str] = type
+        self.code: str | None = code
+        self.type: str | None = type
         self.errors: list[FieldViolation] = errors or []
-        self.http_status: Optional[int] = http_status
-        self.request_id: Optional[str] = request_id
+        self.http_status: int | None = http_status
+        self.request_id: str | None = request_id
         self.raw: Any = raw
 
     def __repr__(self) -> str:
@@ -79,11 +79,11 @@ class RateLimitError(TranscodelyError):
         self,
         message: str,
         *,
-        retry_after_ms: Optional[int] = None,
+        retry_after_ms: int | None = None,
         **kwargs: Any,
     ) -> None:
         super().__init__(message, **kwargs)
-        self.retry_after_ms: Optional[int] = retry_after_ms
+        self.retry_after_ms: int | None = retry_after_ms
 
 
 class InvalidRequestError(TranscodelyError):

transcodely/pagination.py

@@ -6,8 +6,9 @@ Every ``list`` method returns a :class:`Page` you can iterate manually or via
 
 from __future__ import annotations
 
+from collections.abc import Callable, Generator, Iterator
 from dataclasses import dataclass
-from typing import Callable, Generator, Generic, Iterator, Optional, TypeVar
+from typing import Generic, TypeVar
 
 T = TypeVar("T")
 
@@ -15,22 +16,22 @@ T = TypeVar("T")
 @dataclass
 class PageContents(Generic[T]):
     items: list[T]
-    next_cursor: Optional[str]
+    next_cursor: str | None
 
 
 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:
+    def __init__(self, fetcher: Callable[[str | None], PageContents[T]]) -> None:
         self._fetcher = fetcher
-        self._first: Optional[PageContents[T]] = None
+        self._first: PageContents[T] | None = None
 
     @property
     def items(self) -> list[T]:
         return self._first_page().items
 
     @property
-    def next_cursor(self) -> Optional[str]:
+    def next_cursor(self) -> str | None:
         return self._first_page().next_cursor
 
     def __iter__(self) -> Iterator[T]:
@@ -38,11 +39,10 @@ class Page(Generic[T]):
 
     def auto_paging_iter(self) -> Generator[T, None, None]:
         """Yield every item, transparently fetching subsequent pages."""
-        cursor: Optional[str] = None
+        cursor: str | None = None
         while True:
             page = self._fetcher(cursor)
-            for item in page.items:
-                yield item
+            yield from page.items
             if not page.next_cursor:
                 return
             cursor = page.next_cursor

transcodely/resources/_helpers.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Mapping, Optional, Union
+from collections.abc import Mapping
+from typing import Any
 
 from google.protobuf import json_format
 from google.protobuf.descriptor import EnumDescriptor
@@ -23,7 +24,7 @@ def fill_from_dict(msg: Message, data: Mapping[str, Any]) -> Message:
     return msg
 
 
-def resolve_enum(value: Union[int, str], enum_desc: EnumDescriptor) -> int:
+def resolve_enum(value: int | str, enum_desc: EnumDescriptor) -> int:
     """Resolve an enum value from either the raw proto int or a string.
 
     Strings may be the simplified lowercase wire form (``"standard"``,
@@ -54,9 +55,9 @@ def resolve_enum(value: Union[int, str], enum_desc: EnumDescriptor) -> int:
 def assign_pagination(
     req_pagination: Any,
     *,
-    limit: Optional[int] = None,
-    cursor: Optional[str] = None,
-    offset: Optional[int] = None,
+    limit: int | None = None,
+    cursor: str | None = None,
+    offset: int | None = None,
 ) -> None:
     if limit is not None:
         req_pagination.limit = limit

transcodely/resources/api_keys.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Optional
+from typing import Any
 
 from .._transport.transport import CallOptions, Transport
 from ..pagination import Page, PageContents
@@ -21,17 +21,17 @@ class ApiKeys:
         req = fill_from_dict(api_key_pb2.CreateAPIKeyRequest(), kwargs)
         return self._t.unary(_SERVICE, "Create", req, api_key_pb2.CreateAPIKeyResponse())
 
-    def get(self, id: str, opts: Optional[CallOptions] = None) -> api_key_pb2.APIKey:
+    def get(self, id: str, opts: CallOptions | None = None) -> api_key_pb2.APIKey:
         req = api_key_pb2.GetAPIKeyRequest(id=id)
         return self._t.unary(_SERVICE, "Get", req, api_key_pb2.GetAPIKeyResponse(), opts).api_key
 
     def list(
         self,
         *,
-        limit: Optional[int] = None,
-        opts: Optional[CallOptions] = None,
+        limit: int | None = None,
+        opts: CallOptions | None = None,
     ) -> Page[api_key_pb2.APIKey]:
-        def fetch(cursor: Optional[str]) -> PageContents[api_key_pb2.APIKey]:
+        def fetch(cursor: str | None) -> PageContents[api_key_pb2.APIKey]:
             req = api_key_pb2.ListAPIKeysRequest()
             assign_pagination(req.pagination, limit=limit, cursor=cursor)
             res = self._t.unary(_SERVICE, "List", req, api_key_pb2.ListAPIKeysResponse(), opts)
@@ -41,7 +41,7 @@ class ApiKeys:
 
         return Page(fetch)
 
-    def revoke(self, id: str, opts: Optional[CallOptions] = None) -> api_key_pb2.APIKey:
+    def revoke(self, id: str, opts: CallOptions | None = None) -> api_key_pb2.APIKey:
         req = api_key_pb2.RevokeAPIKeyRequest(id=id)
         return self._t.unary(
             _SERVICE, "Revoke", req, api_key_pb2.RevokeAPIKeyResponse(), opts