sprocket-systems.coda.sdk 2.0.8__py3-none-any.whl → 2.0.11__py3-none-any.whl

coda/__init__.py

@@ -1,5 +1,5 @@
 # The versions below will be replaced automatically in CI.
 # You do not need to modify any of the versions below.
-__version__ = "2.0.8"
-CODA_APP_SUITE_VERSION = "+coda-2.0.13"
+__version__ = "2.0.11"
+CODA_APP_SUITE_VERSION = "+coda-2.0.14"
 FINAL_VERSION = __version__ + CODA_APP_SUITE_VERSION

coda/sdk/__init__.py

@@ -4,6 +4,15 @@ from .workflow import WorkflowDefinition, WorkflowDefinitionBuilder
 from .preset import Preset
 from .enums import PresetType, SourceType, VenueType, InputFilter, Language, Format, StemType, FrameRate, InputStemType
 from .utils import user_info, timing_info, get_channels
+from .exceptions import (
+    CodaAPIError,
+    CodaAuthenticationError,
+    CodaForbiddenError,
+    CodaBadRequestError,
+    CodaNotFoundError,
+    CodaClientError,
+    CodaServerError,
+)
 
 __all__ = [
     "Job",
@@ -24,4 +33,11 @@ __all__ = [
     "user_info",
     "get_channels",
     "timing_info",
+    "CodaAPIError",
+    "CodaAuthenticationError",
+    "CodaForbiddenError",
+    "CodaBadRequestError",
+    "CodaNotFoundError",
+    "CodaClientError",
+    "CodaServerError",
 ]

coda/sdk/essence.py

@@ -1,3 +1,4 @@
+from numbers import Number
 import os
 import sys
 import json
@@ -5,8 +6,8 @@ import shutil
 import subprocess
 
 from pathlib import Path
-from typing import List, Dict
-from .enums import Format, SourceType, InputStemType
+from typing import List, Dict, Any
+from .enums import Format, SourceType, InputStemType, FrameRate, Language
 from .constants import (
     ENV_CODA_CLI_EXE,
     ENV_NO_CODA_EXE,
@@ -58,17 +59,26 @@ class Essence:
         if not format or not isinstance(format, str):
             raise ValueError("format must not be an empty string and must be a string type.")
 
-        self.payload = {
+        self.payload: Dict[str, Any] = {
             "type": "",
             "definition": {
                 "format": format,
                 "program": program,
                 "description": description,
                 "type": stem_type,
-            },
-            "timing_info": timing_info
+            }
         }
 
+        if timing_info is not None:
+            if timing_info.get("frame_rate"):
+                self.payload["definition"]["frame_rate"] = timing_info.get("frame_rate")
+            if timing_info.get("ffoa_timecode"):
+                self.payload["definition"]["ffoa_timecode"] = timing_info.get("ffoa_timecode")
+            if timing_info.get("lfoa_timecode"):
+                self.payload["definition"]["lfoa_timecode"] = timing_info.get("lfoa_timecode")
+            if timing_info.get("file_start_timecode"):
+                self.payload["definition"]["file_start_timecode"] = timing_info.get("file_start_timecode")
+
     def add_interleaved_resource(
         self,
         file: str | dict,
@@ -119,7 +129,7 @@ class Essence:
                 raise ValueError("IO Location ID is required for non-S3 file sources.")
             url = f"{URL_PREFIX_IO}{io_location_id}{url}"
 
-        resource_dict = {"url": url}
+        resource_dict: Dict[str, Any] = {"url": url}
         if auth is not None:
             resource_dict["auth"] = auth
         if opts is not None:
@@ -206,7 +216,7 @@ class Essence:
                     raise ValueError("IO Location ID is required for non-S3 file sources.")
                 url = f"{URL_PREFIX_IO}{io_location_id}{url}"
 
-            res = {
+            res: Dict[str, Any] = {
                 "resource": {"url": url},
                 "bit_depth": bit_depth,
                 "sample_rate": sample_rate,
@@ -249,7 +259,7 @@ class Essence:
         """
         self.payload["definition"]["format"] = format
 
-    def override_language(self, language) -> None:
+    def override_language(self, language: Language) -> None:
         """Override the language of the essence.
 
         Args:
@@ -261,31 +271,115 @@ class Essence:
 
     def override_timing_info(
         self,
-        source_frame_rate=None,
+        frame_rate: FrameRate | None = None,
         ffoa_timecode: str | None = None,
-        lfoa_timecode: str | None = None
+        lfoa_timecode: str | None = None,
+        file_start_timecode: str | None = None,
+        head_leader_length: int | None = None,
+        tail_leader_length: int | None = None
     ) -> None:
         """Override timing information for the essence.
 
-        All parameters are optional. Only provided values will be set.
+        Timing parameters come in two mutually exclusive groups. When using either group,
+        ALL parameters in that group must be provided:
+        - Timecode-based: frame_rate, ffoa_timecode, lfoa_timecode, file_start_timecode (all four required together)
+        - Offset-based: frame_rate, head_leader_length, tail_leader_length (all three required together)
 
         Args:
-            source_frame_rate: The source frame rate (e.g., FrameRate.TWENTY_FOUR).
+            frame_rate (FrameRate, optional): The source frame rate. Required with all timing groups.
             ffoa_timecode (str, optional): First frame of action timecode.
             lfoa_timecode (str, optional): Last frame of action timecode.
+            file_start_timecode (str, optional): File start timecode.
+            head_leader_length (int, optional): Head leader length in frames.
+            tail_leader_length (int, optional): Tail leader length in frames.
+
+        Raises:
+            ValueError: If both timecode-based and offset-based parameters are provided.
+            ValueError: If only some parameters from a group are provided.
 
         """
-        # Initialize timing_info if it's None
-        if self.payload["timing_info"] is None:
-            self.payload["timing_info"] = {}
+        # Define parameter groups (excluding frame_rate from the "other params" check)
+        timecode_other_params = {
+            "ffoa_timecode": ffoa_timecode,
+            "lfoa_timecode": lfoa_timecode,
+            "file_start_timecode": file_start_timecode
+        }
+
+        offset_other_params = {
+            "head_leader_length": head_leader_length,
+            "tail_leader_length": tail_leader_length
+        }
 
-        if source_frame_rate is not None:
-            fr_value = source_frame_rate.value if hasattr(source_frame_rate, 'value') else source_frame_rate
-            self.payload["timing_info"]["source_frame_rate"] = fr_value
+        timecode_other_set = [k for k, v in timecode_other_params.items() if v is not None]
+        offset_other_set = [k for k, v in offset_other_params.items() if v is not None]
+
+        # Check if parameters from both groups are provided
+        if timecode_other_set and offset_other_set:
+            raise ValueError(
+                "Timecode-based parameters (frame_rate, ffoa_timecode, lfoa_timecode, file_start_timecode) "
+                "and offset-based parameters (frame_rate, head_leader_length, tail_leader_length) are mutually exclusive. "
+                "Please provide only one type of timing parameter."
+            )
+
+        # Validate timecode group - if any timecode param is provided, all must be provided (including frame_rate)
+        if timecode_other_set:
+            full_timecode_params = {
+                "frame_rate": frame_rate,
+                "ffoa_timecode": ffoa_timecode,
+                "lfoa_timecode": lfoa_timecode,
+                "file_start_timecode": file_start_timecode
+            }
+            complete_timecode_set = [k for k, v in full_timecode_params.items() if v is not None]
+            if len(complete_timecode_set) != len(full_timecode_params):
+                missing = [k for k, v in full_timecode_params.items() if v is None]
+                raise ValueError(
+                    f"When using timecode-based parameters, all must be provided. "
+                    f"Missing: {', '.join(missing)}"
+                )
+
+        # Validate offset group - if any offset param is provided, all must be provided (including frame_rate)
+        if offset_other_set:
+            full_offset_params = {
+                "frame_rate": frame_rate,
+                "head_leader_length": head_leader_length,
+                "tail_leader_length": tail_leader_length
+            }
+            complete_offset_set = [k for k, v in full_offset_params.items() if v is not None]
+            if len(complete_offset_set) != len(full_offset_params):
+                missing = [k for k, v in full_offset_params.items() if v is None]
+                raise ValueError(
+                    f"When using offset-based parameters, all must be provided. "
+                    f"Missing: {', '.join(missing)}"
+                )
+
+        # Check if frame_rate is provided alone (without any other timing params)
+        if frame_rate is not None and not timecode_other_set and not offset_other_set:
+            raise ValueError(
+                "frame_rate cannot be used alone. It must be provided as part of either: "
+                "timecode-based parameters (frame_rate, ffoa_timecode, lfoa_timecode, file_start_timecode) or "
+                "offset-based parameters (frame_rate, head_leader_length, tail_leader_length)."
+            )
+
+        if frame_rate is not None:
+            fr_value = frame_rate.value if hasattr(frame_rate, 'value') else frame_rate
+            self.payload["definition"]["frame_rate"] = fr_value
+
+        # For timecode based settings
         if ffoa_timecode is not None:
-            self.payload["timing_info"]["ffoa_timecode"] = ffoa_timecode
-        if lfoa_timecode is not None:
-            self.payload["timing_info"]["lfoa_timecode"] = lfoa_timecode
+            self.payload["definition"]["ffoa_timecode"] = ffoa_timecode
+            self.payload["definition"]["lfoa_timecode"] = lfoa_timecode
+            self.payload["definition"]["file_start_timecode"] = file_start_timecode
+
+        # For offset based settings
+        if head_leader_length is not None:
+            # Remove any set timecode settings just in case
+            self.payload["definition"].pop("ffoa_timecode", None)
+            self.payload["definition"].pop("lfoa_timecode", None)
+            self.payload["definition"].pop("file_start_timecode", None)
+
+            # Set the offest values
+            self.payload["definition"]["head_leader_length"] = head_leader_length
+            self.payload["definition"]["tail_leader_length"] = tail_leader_length
 
     def override_bext_time_reference(self, bext_time_reference: int) -> None:
         """Set BEXT time reference on all resources.
@@ -401,23 +495,27 @@ class Essence:
                     )
 
                     j = json.loads(ret.stdout)
-                    print(json.dumps(j, indent=2))
                     if not j.get("sources"):
                         raise ValueError("`coda inspect` was unable to retrieve the sources information.")
 
                     timing_info = {
-                        "source_frame_rate": j.get("source_frame_rate"),
+                        "frame_rate": j.get("source_frame_rate"),
                         "ffoa_timecode": j.get("ffoa_timecode"),
-                        "lfoa_timecode": j.get("lfoa_timecode")
+                        "lfoa_timecode": j.get("lfoa_timecode"),
+                        "file_start_timecode": j.get("file_start_timecode")
                     }
 
                     for source in j.get("sources", []):
                         source_type = source.get("type")
-                        if source_type in [SourceType.ADM, SourceType.IAB_MXF]:
-                            format = Format.ATMOS
                         source_def = source.get("definition")
+
+                        # Determine the format with explicit type handling
+                        format_value: str | Format = source_def.get("format", "")
+                        if not format_value and source_type in [SourceType.ADM, SourceType.IAB_MXF]:
+                            format_value = Format.ATMOS
+
                         essence = Essence(
-                            format=source_def.get("format") or format,
+                            format=format_value,
                             stem_type=source_def.get("type"),
                             program=source_def.get("program", program),
                             description=source_def.get("description"),

coda/sdk/exceptions.py

@@ -0,0 +1,49 @@
+"""Exception classes for Coda API errors."""
+
+import requests
+
+
+class CodaAPIError(Exception):
+    """Base exception for Coda API errors.
+
+    Attributes:
+        status_code: HTTP status code
+        response: The full requests.Response object
+        endpoint: The API endpoint that was called
+    """
+
+    def __init__(self, message: str, status_code: int, response: requests.Response, endpoint: str):
+        self.status_code = status_code
+        self.response = response
+        self.endpoint = endpoint
+        super().__init__(message)
+
+
+class CodaAuthenticationError(CodaAPIError):
+    """401 Unauthorized - Invalid or expired API token."""
+    pass
+
+
+class CodaForbiddenError(CodaAPIError):
+    """403 Forbidden - Insufficient permissions for this resource."""
+    pass
+
+
+class CodaBadRequestError(CodaAPIError):
+    """400 Bad Request - Invalid request payload or parameters."""
+    pass
+
+
+class CodaNotFoundError(CodaAPIError):
+    """404 Not Found - Resource does not exist."""
+    pass
+
+
+class CodaClientError(CodaAPIError):
+    """4XX Client Error (other than 400, 401, 403, 404)."""
+    pass
+
+
+class CodaServerError(CodaAPIError):
+    """5XX Server Error - Coda API server error."""
+    pass

coda/sdk/job.py

@@ -10,6 +10,7 @@ from coda.sdk.enums import Format, FrameRate, Language, VenueType
 from .constants import DEFAULT_PROGRAM_ID
 from .essence import Essence
 from .utils import validate_group_id, make_request
+from .exceptions import CodaServerError, CodaClientError
 from ..tc_tools import tc_to_time_seconds
 
 if TYPE_CHECKING:
@@ -73,25 +74,114 @@ class JobPayloadBuilder:
         return self
 
     def with_input_timing(
-        self, frame_rate: FrameRate | None = None, ffoa: str | None = None, lfoa: str | None = None, start_time: str | None = None
+        self,
+        frame_rate: FrameRate | None = None,
+        ffoa: str | None = None,
+        lfoa: str | None = None,
+        start_time: str | None = None,
+        head_leader_length: int | None = None,
+        tail_leader_length: int | None = None
     ) -> "JobPayloadBuilder":
         """Set the input timing information for the source files.
 
+        Note: This will override the timing info for every defined essence.
+
+        Timing parameters come in two mutually exclusive groups. When using either group,
+        ALL parameters in that group must be provided:
+        - Timecode-based: frame_rate, ffoa, lfoa, start_time (all four required together)
+        - Offset-based: frame_rate, head_leader_length, tail_leader_length (all three required together)
+
         Args:
-            frame_rate (FrameRate, optional): The frame rate enum. Defaults to None.
-            ffoa (str, optional): The first frame of audio timecode. Defaults to None.
-            lfoa (str, optional): The last frame of audio timecode. Defaults to None.
-            start_time (str, optional): The start time in timecode format. Defaults to None.
+            frame_rate (FrameRate, optional): The frame rate enum. Required with all timing groups.
+            ffoa (str, optional): The first frame of action timecode. Defaults to None.
+            lfoa (str, optional): The last frame of action timecode. Defaults to None.
+            start_time (str, optional): The file start timecode. When provided with frame_rate,
+                also used to calculate bext_time_reference for resources. Defaults to None.
+            head_leader_length (int, optional): Head leader length in frames. Defaults to None.
+            tail_leader_length (int, optional): Tail leader length in frames. Defaults to None.
 
         Returns:
             JobPayloadBuilder: The builder instance for fluent chaining.
 
+        Raises:
+            ValueError: If both timecode-based and offset-based parameters are provided.
+            ValueError: If only some parameters from a group are provided.
+
         """
+        # Define parameter groups (excluding frame_rate from the "other params" check)
+        timecode_other_params = {
+            "ffoa": ffoa,
+            "lfoa": lfoa,
+            "start_time": start_time
+        }
+
+        offset_other_params = {
+            "head_leader_length": head_leader_length,
+            "tail_leader_length": tail_leader_length
+        }
+
+        timecode_other_set = [k for k, v in timecode_other_params.items() if v is not None]
+        offset_other_set = [k for k, v in offset_other_params.items() if v is not None]
+
+        # Check mutual exclusivity between timecode and offset groups
+        if timecode_other_set and offset_other_set:
+            raise ValueError(
+                "Timecode-based parameters (frame_rate, ffoa, lfoa, start_time) "
+                "and offset-based parameters (frame_rate, head_leader_length, tail_leader_length) are mutually exclusive. "
+                "Please provide only one type of timing parameter."
+            )
+
+        # Validate timecode group - if any timecode param is provided, all must be provided (including frame_rate)
+        if timecode_other_set:
+            full_timecode_params = {
+                "frame_rate": frame_rate,
+                "ffoa": ffoa,
+                "lfoa": lfoa,
+                "start_time": start_time
+            }
+            complete_timecode_set = [k for k, v in full_timecode_params.items() if v is not None]
+            if len(complete_timecode_set) != len(full_timecode_params):
+                missing = [k for k, v in full_timecode_params.items() if v is None]
+                raise ValueError(
+                    f"When using timecode-based parameters, all must be provided. "
+                    f"Missing: {', '.join(missing)}"
+                )
+
+        # Validate offset group - if any offset param is provided, all must be provided (including frame_rate)
+        if offset_other_set:
+            full_offset_params = {
+                "frame_rate": frame_rate,
+                "head_leader_length": head_leader_length,
+                "tail_leader_length": tail_leader_length
+            }
+            complete_offset_set = [k for k, v in full_offset_params.items() if v is not None]
+            if len(complete_offset_set) != len(full_offset_params):
+                missing = [k for k, v in full_offset_params.items() if v is None]
+                raise ValueError(
+                    f"When using offset-based parameters, all must be provided. "
+                    f"Missing: {', '.join(missing)}"
+                )
+
+        # Check if frame_rate is provided alone (without any other timing params)
+        if frame_rate is not None and not timecode_other_set and not offset_other_set:
+            raise ValueError(
+                "frame_rate cannot be used alone. It must be provided as part of either: "
+                "timecode-based parameters (frame_rate, ffoa, lfoa, start_time) or "
+                "offset-based parameters (frame_rate, head_leader_length, tail_leader_length)."
+            )
+
         self._time_options["frame_rate"] = frame_rate
         self._time_options["ffoa"] = ffoa
         self._time_options["lfoa"] = lfoa
         if start_time is not None:
-            self._time_options["start_time"] = tc_to_time_seconds(start_time, frame_rate)
+            self._time_options["file_start_timecode"] = start_time
+            if frame_rate is not None:
+                self._time_options["start_time"] = tc_to_time_seconds(start_time, frame_rate)
+
+        if head_leader_length is not None:
+            self._time_options["head_leader_length"] = head_leader_length
+            self._time_options["tail_leader_length"] = tail_leader_length
+
         return self
 
     def with_essences(self, essences: List[Essence]) -> "JobPayloadBuilder":
@@ -357,27 +447,34 @@ class JobPayloadBuilder:
         if not self._venue:
             raise ValueError("Cannot build job payload: A venue must be set.")
 
-        ffoa = None
-        lfoa = None
-        fr = None
-
-        if self._time_options.get("frame_rate"):
-            fr = self._time_options.get("frame_rate")
-        if self._time_options.get("ffoa"):
-            ffoa = self._time_options.get("ffoa")
-        if self._time_options.get("lfoa"):
-            lfoa = self._time_options.get("lfoa")
-
-        for e in self._essences:
-            current_timing = e.payload.get("timing_info") or {}
-            new_timing = dict(current_timing)
-            if not new_timing.get("ffoa_timecode"):
-                new_timing["ffoa_timecode"] = ffoa
-            if not new_timing.get("lfoa_timecode"):
-                new_timing["lfoa_timecode"] = lfoa
-            if not new_timing.get("source_frame_rate"):
-                new_timing["source_frame_rate"] = fr
-            e.payload["timing_info"] = new_timing
+        # Apply timing overrides to all essences BEFORE serialization
+        for essence in self._essences:
+            # Apply frame rate if set (can be independent of other params)
+            if self._time_options.get("frame_rate"):
+                frame_rate = self._time_options["frame_rate"]
+                essence.payload["definition"]["frame_rate"] = frame_rate.value if hasattr(frame_rate, 'value') else frame_rate
+
+            # Apply timecode-based params (mutually exclusive with offset)
+            if self._time_options.get("ffoa"):
+                # Remove offset params if they exist
+                essence.payload["definition"].pop("head_leader_length", None)
+                essence.payload["definition"].pop("tail_leader_length", None)
+
+                # Set timecode params
+                essence.payload["definition"]["ffoa_timecode"] = self._time_options["ffoa"]
+                essence.payload["definition"]["lfoa_timecode"] = self._time_options["lfoa"]
+                essence.payload["definition"]["file_start_timecode"] = self._time_options["file_start_timecode"]
+
+            # Apply offset-based params (mutually exclusive with timecode)
+            elif self._time_options.get("head_leader_length") is not None:
+                # Remove timecode params if they exist
+                essence.payload["definition"].pop("ffoa_timecode", None)
+                essence.payload["definition"].pop("lfoa_timecode", None)
+                essence.payload["definition"].pop("file_start_timecode", None)
+
+                # Set offset params
+                essence.payload["definition"]["head_leader_length"] = self._time_options["head_leader_length"]
+                essence.payload["definition"]["tail_leader_length"] = self._time_options["tail_leader_length"]
 
         sources = [e.dict() for e in self._essences]
 
@@ -397,9 +494,6 @@ class JobPayloadBuilder:
             },
             "venue": self._venue,
             "sources": sources,
-            "source_frame_rate": fr,
-            "ffoa_timecode": ffoa,
-            "lfoa_timecode": lfoa,
         }
 
         if self._edits:
@@ -456,6 +550,9 @@ class Job:
         Returns:
             requests.Response: The validation response object.
 
+        Raises:
+            CodaAPIError: If validation fails (HTTP 4XX or 5XX response).
+
         """
         endpoint = f"/interface/v2/groups/{self.group_id}/jobs/validate?skip_cloud_validation={skip_cloud_validation}"
         return make_request(requests.post, endpoint, self.payload)
@@ -466,15 +563,13 @@ class Job:
         Returns:
             int | None: The job ID if successful, otherwise None.
 
+        Raises:
+            CodaAPIError: If validation or job execution fails (HTTP 4XX or 5XX response).
+
         """
         print("Validating job payload.", file=sys.stderr)
         validation_result = self.validate()
 
-        if validation_result.status_code != 200:
-            print("Job validation failed. Cannot run job.", file=sys.stderr)
-            print(validation_result.json(), file=sys.stderr)
-            return None
-
         print("Launching job.", file=sys.stderr)
         endpoint = f"/interface/v2/groups/{self.group_id}/jobs"
         response = make_request(requests.post, endpoint, self.payload)
@@ -497,20 +592,14 @@ class Job:
             dict: The coda edge payload.
 
         Raises:
-            RuntimeError: If job validation fails or edge payload retrieval fails.
+            CodaAPIError: If job validation or edge payload retrieval fails.
 
         """
         validation_result = self.validate(skip_cloud_validation=skip_cloud_validation)
 
-        if validation_result.status_code != 200:
-            raise RuntimeError(f"Edge job validation failed. \nStatus: {validation_result.status_code}\n Resp: {validation_result.json()}")
-
         endpoint = f"/interface/v2/groups/{self.group_id}/edge?skip_cloud_validation={skip_cloud_validation}"
         response = make_request(requests.post, endpoint, self.payload)
 
-        if response.status_code != 200:
-            raise RuntimeError(f"Edge payload retrieval failed with status code: {response.json()}")
-
         try:
             edge_payload = response.json()
         except Exception as err:
@@ -531,6 +620,9 @@ class Job:
         Returns:
             requests.Response: The raw payload validation response object.
 
+        Raises:
+            CodaAPIError: If validation fails (HTTP 4XX or 5XX response).
+
         """
         group_id = validate_group_id()
         endpoint = f"/interface/v2/groups/{group_id}/jobs/validate"
@@ -548,14 +640,13 @@ class Job:
         Returns:
             int | None: The job ID if successful, otherwise None.
 
+        Raises:
+            CodaAPIError: If validation or job execution fails (HTTP 4XX or 5XX response).
+
         """
         group_id = validate_group_id()
 
         validation_result = Job.validate_raw_payload(json_payload)
-        if validation_result.status_code != 200:
-            print("Raw payload validation failed. Cannot run job.", file=sys.stderr)
-            print(validation_result.json(), file=sys.stderr)
-            return None
 
         endpoint = f"/interface/v2/groups/{group_id}/jobs"
         response = make_request(requests.post, endpoint, json_payload)
@@ -572,7 +663,8 @@ class Job:
         """Get the status of a job.
 
         This method polls the API for the job's status and will retry up to 3 times
-        if an error is encountered during the request.
+        if a server or client error (5XX or certain 4XX responses) is encountered.
+        Returns None if all retries are exhausted.
 
         Args:
             job_id (int): The ID of the job.
@@ -580,24 +672,30 @@ class Job:
         Returns:
             dict | None: The job status and progress if successful, otherwise None.
 
+        Raises:
+            CodaAuthenticationError: If API returns 401 (unauthorized).
+            CodaForbiddenError: If API returns 403 (insufficient permissions).
+            CodaNotFoundError: If API returns 404 (job not found).
+
         """
         group_id = validate_group_id()
-        ret = make_request(
-            requests.get, f"/interface/v2/groups/{group_id}/jobs/{job_id}"
-        )
-        j = ret.json()
         error_count = 0
-        while "error" in j and error_count < 3:
-            print("error in get_status: ", ret.status_code, j["error"], file=sys.stderr)
-            time.sleep(1)
-            ret = make_request(
-                requests.get, f"/interface/v2/groups/{group_id}/jobs/{job_id}"
-            )
-            j = ret.json()
-            error_count += 1
-        if "error" in j:
-            return None
-        return {"status": j["status"], "progress": j["progress"]}
+        max_retries = 3
+
+        while error_count < max_retries:
+            try:
+                ret = make_request(
+                    requests.get, f"/interface/v2/groups/{group_id}/jobs/{job_id}"
+                )
+                j = ret.json()
+                return {"status": j["status"], "progress": j["progress"]}
+            except (CodaServerError, CodaClientError) as e:
+                error_count += 1
+                if error_count >= max_retries:
+                    print(f"error in get_status (attempt {error_count}): {e}", file=sys.stderr)
+                    return None
+                print(f"error in get_status (attempt {error_count}): {e}", file=sys.stderr)
+                time.sleep(1)
 
     @staticmethod
     def get_report(job_id: int) -> dict:
@@ -609,6 +707,9 @@ class Job:
         Returns:
             dict: The job report JSON.
 
+        Raises:
+            CodaAPIError: If report retrieval fails (HTTP 4XX or 5XX response).
+
         """
         ret = make_request(requests.get, f"/interface/v2/report/{job_id}/raw")
         return ret.json()
@@ -624,6 +725,9 @@ class Job:
         Returns:
             list: List of jobs within the date range.
 
+        Raises:
+            CodaAPIError: If query fails (HTTP 4XX or 5XX response).
+
         """
         ret = make_request(requests.get, f"/interface/v1/jobs?sort=asc&start_date={start_date}&end_date={end_date}")
         return ret.json()

coda/sdk/preset.py

@@ -137,10 +137,7 @@ class Preset:
 
         route = Preset.routes[preset_type].replace(":group_id", str(group_id))
         ret = make_request(requests.get, f"/interface/v2/{route}")
-        j = ret.json()
-        if "error" in j:
-            raise ValueError(f"Unable to find preset '{preset_type}': {j}")
-        return j
+        return ret.json()
 
     @staticmethod
     def get_group_id_by_name(group_name: str) -> str:

coda/sdk/utils.py

@@ -3,7 +3,7 @@ import requests
 import re
 import urllib3
 
-from typing import TYPE_CHECKING, List, Dict, Any, Callable
+from typing import TYPE_CHECKING, List, Dict, Any, Callable, cast
 
 from .constants import (
     ENV_CODA_API_GROUP_ID,
@@ -13,6 +13,15 @@ from .constants import (
     DEFAULT_API_URL,
     INSECURE_SKIP_VERIFY_VALUES,
 )
+from .exceptions import (
+    CodaAPIError,
+    CodaAuthenticationError,
+    CodaForbiddenError,
+    CodaBadRequestError,
+    CodaNotFoundError,
+    CodaClientError,
+    CodaServerError,
+)
 
 if TYPE_CHECKING:
     from ..tc_tools import (
@@ -81,6 +90,7 @@ def user_info() -> str:
     return ret.json()
 
 
+
 def validate_group_id() -> str:
     """Get the Coda Group ID from environment variables.
 
@@ -113,6 +123,8 @@ def make_request(
     headers, and executes the request using the provided function (e.g.,
     requests.get, requests.post).
 
+    HTTP errors are automatically detected and converted to informative exceptions.
+
     Args:
         func (Callable[..., requests.Response]): The requests function to call
             (e.g., requests.get, requests.post, requests.put).
@@ -122,9 +134,17 @@ def make_request(
 
     Raises:
         ValueError: If the 'CODA_API_TOKEN' environment variable is not set.
+        CodaAuthenticationError: If the API returns 401 Unauthorized.
+        CodaForbiddenError: If the API returns 403 Forbidden.
+        CodaBadRequestError: If the API returns 400 Bad Request.
+        CodaNotFoundError: If the API returns 404 Not Found.
+        CodaClientError: If the API returns other 4XX errors.
+        CodaServerError: If the API returns 5XX server errors.
+        CodaAPIError: If the API returns an unexpected status code (e.g., 3XX).
 
     Returns:
         requests.Response: The Response object from the `requests` library.
+            Only returned for successful 2XX status codes.
 
     """
     url = os.getenv(ENV_CODA_API_URL, DEFAULT_API_URL)
@@ -136,7 +156,12 @@ def make_request(
             urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
             verify = False
         auth = {"Authorization": f"Bearer {token}"}
-        return func(url, json=payload, headers=auth, verify=verify)
+        response = func(url, json=payload, headers=auth, verify=verify)
+
+        # Check HTTP status and raise appropriate exception for errors
+        _check_response_status(response, route)
+
+        return response
     raise ValueError("Error: CODA_API_TOKEN is not set.")
 
 
@@ -280,3 +305,133 @@ def is_key_value_comma_string(s: str) -> bool:
     pattern = r"^([A-Z0-9_]+=[a-zA-Z0-9_-]+)(,[A-Z0-9_]+=[a-zA-Z0-9_-]+)*$"
 
     return re.fullmatch(pattern, s) is not None
+
+def _extract_error_detail(response: requests.Response) -> str:
+    """Extract error detail from response body.
+
+    Tries multiple strategies to get meaningful error info:
+    1. Check for 'error' key in JSON
+    2. Check for 'message' key in JSON
+    3. Check for 'errors' array in JSON
+    4. Fall back to response.text (truncated)
+
+    Args:
+        response: The requests Response object
+
+    Returns:
+        str: Error detail string, or empty string if none found
+    """
+    try:
+        response_json = response.json()
+        if isinstance(response_json, dict):
+            # Check common error keys
+            if "error" in response_json:
+                error = response_json["error"]
+                # Handle nested error objects
+                if isinstance(error, dict) and "message" in error:
+                    return error["message"]
+                return str(error)
+            elif "message" in response_json:
+                return response_json["message"]
+            elif "errors" in response_json:
+                errors = response_json["errors"]
+                if isinstance(errors, list) and errors:
+                    return "; ".join(str(e) for e in errors[:3])  # First 3 errors
+                return str(errors)
+    except Exception:
+        pass
+
+    # Fall back to text response, truncated
+    if response.text:
+        text = response.text.strip()
+        if len(text) > 200:
+            return text[:200] + "..."
+        return text
+
+    return ""
+
+
+def _check_response_status(response: requests.Response, endpoint: str) -> None:
+    """Check response status code and raise exception for HTTP errors.
+
+    Raises specific exception types based on the HTTP status code to enable
+    targeted error handling. All exceptions include the status code, endpoint,
+    and extracted error details from the response body.
+
+    Args:
+        response: The requests Response object to check
+        endpoint: The API endpoint being called (for error messages)
+
+    Raises:
+        CodaAuthenticationError: For 401 status
+        CodaForbiddenError: For 403 status
+        CodaBadRequestError: For 400 status
+        CodaNotFoundError: For 404 status
+        CodaClientError: For other 4XX statuses
+        CodaServerError: For 5XX statuses
+    """
+    status_code: int = cast(int, response.status_code)
+
+    # Success - no exception needed
+    if 200 <= status_code < 300:
+        return
+
+    error_detail = _extract_error_detail(response)
+    base_message = f"HTTP {status_code} error for endpoint '{endpoint}'"
+    if error_detail:
+        full_message = f"{base_message}: {error_detail}"
+    else:
+        full_message = base_message
+
+    # Raise specific exception based on status code
+    if status_code == 401:
+        raise CodaAuthenticationError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+    elif status_code == 403:
+        raise CodaForbiddenError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+    elif status_code == 400:
+        raise CodaBadRequestError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+    elif status_code == 404:
+        raise CodaNotFoundError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+    elif 400 <= status_code < 500:
+        raise CodaClientError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+    elif 500 <= status_code < 600:
+        raise CodaServerError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+    else:
+        # Unexpected status code (3XX, 1XX, etc.)
+        raise CodaAPIError(
+            full_message,
+            status_code=status_code,
+            response=response,
+            endpoint=endpoint
+        )
+

coda/sdk/workflow.py

@@ -180,7 +180,7 @@ class WorkflowDefinitionBuilder:
 
         if isinstance(loudness_preset, dict) and "tolerances" not in loudness_preset:
             loudness_preset["tolerances"] = _DEFAULT_LOUDNESS_TOLERANCES.copy()
-        process_block_config = {
+        process_block_config: Dict[str, Any] = {
             "name": name,
             "input_filter": input_filter,
             "output_settings": {
@@ -1151,7 +1151,7 @@ class WorkflowDefinitionBuilder:
             if s3_auth:
                 dest_def["auth"] = s3_auth
             if options:
-                dest_def["url_options"] = options
+                dest_def["opts"] = options
 
         if io_location_id is not None and s3_url is None:
             dest_type = "io_location"
@@ -1214,7 +1214,7 @@ class WorkflowDefinitionBuilder:
             WorkflowDefinition: A new Workflow instance containing the built definition.
 
         """
-        definition = {
+        definition: Dict[str, Any] = {
             "name": self._name,
             "process_blocks": copy.deepcopy(self._process_blocks),
             "packages": copy.deepcopy(self._packages),

coda/sdk.py

@@ -0,0 +1 @@
+

{sprocket_systems_coda_sdk-2.0.8.dist-info → sprocket_systems_coda_sdk-2.0.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sprocket-systems.coda.sdk
-Version: 2.0.8
+Version: 2.0.11
 Summary: The Coda SDK provides a Python interface to define Coda workflows, create jobs and run them.
 Keywords: python,coda,sdk
 Author-Email: Sprocket Systems <support@sprocket.systems>

sprocket_systems_coda_sdk-2.0.11.dist-info/RECORD

@@ -0,0 +1,17 @@
+coda/__init__.py,sha256=ko0iicXLw6_xgFxn-3Y8m5XFFkU6JKTSCNM1m9m6aic,230
+coda/sdk.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+coda/sdk/__init__.py,sha256=1qAK6kMsLo7kt14vI2XIZGv-lX8JcceVuARuevNaz6o,1055
+coda/sdk/constants.py,sha256=DW-goGI4vTlt8KeR4z0sf89Duov4TgZdsjv1VJDuAQI,596
+coda/sdk/enums.py,sha256=1l4pK8pNofV56WVAiQXitlY6m9iTfEv9I159GWkTZKE,6582
+coda/sdk/essence.py,sha256=8E8oA6QctCS9wzsxyf0UKtx_XpZc44rfpGxXZTvbrw0,26161
+coda/sdk/exceptions.py,sha256=H_FAbKlTj_i_sRA66VHFp33Qu0ReFcup8_WMrJG9huE,1208
+coda/sdk/job.py,sha256=CaSrxK7QvkThx_ZVWslLC363xbgoWKTTIjIfDPOk1h4,27034
+coda/sdk/preset.py,sha256=WG2T51HIffcYS_TUwqWGNmRv-3_2etM8YBoka2-ztbM,8819
+coda/sdk/utils.py,sha256=tGM3mTYfkafZ925G_Z6jIUsz91DyevwVytKB8xH7hIM,15651
+coda/sdk/workflow.py,sha256=ipAiiZ-NV7yFrbyBo2xni-57fzbkl5J0lkH8XwxZkd4,63196
+coda/tc_tools.py,sha256=hEtVE6xtPqg93WfJ-lQdRQroPdQTkH5HkMLWCIkwIlo,22010
+sprocket_systems_coda_sdk-2.0.11.dist-info/METADATA,sha256=xH0LcwvlFfdVJxYyhf2P7jzB0JomYYFh9LY6UQbOnOg,1107
+sprocket_systems_coda_sdk-2.0.11.dist-info/WHEEL,sha256=tsUv_t7BDeJeRHaSrczbGeuK-TtDpGsWi_JfpzD255I,90
+sprocket_systems_coda_sdk-2.0.11.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+sprocket_systems_coda_sdk-2.0.11.dist-info/licenses/LICENSE,sha256=wrFjizFlraIAPW8JIteGftNH2laAZBBRhdEnPVUsKTM,10198
+sprocket_systems_coda_sdk-2.0.11.dist-info/RECORD,,

sprocket_systems_coda_sdk-2.0.8.dist-info/RECORD

@@ -1,15 +0,0 @@
-coda/__init__.py,sha256=vE1LP8NOlIPcHtFGopI2SkUBTkwyY8XPWQmGfz4PEzo,229
-coda/sdk/__init__.py,sha256=wOCrh1piLbgLVOMhKuLFYA62n60IN89eXGHpFKwFAE4,691
-coda/sdk/constants.py,sha256=DW-goGI4vTlt8KeR4z0sf89Duov4TgZdsjv1VJDuAQI,596
-coda/sdk/enums.py,sha256=1l4pK8pNofV56WVAiQXitlY6m9iTfEv9I159GWkTZKE,6582
-coda/sdk/essence.py,sha256=vSx2lp1I0yJvFNMcAWqF-I3BV9q_bRnZbtSEf_QArHg,20764
-coda/sdk/job.py,sha256=WArS06ufJUZLDdx6wJHgwk2olYjtX3w_sJqPF_XEu6A,21538
-coda/sdk/preset.py,sha256=OtaRVJU6luBBD_6Ehd8ZkcjXL_YVoXfziI14E-GS4Xw,8934
-coda/sdk/utils.py,sha256=uC9hHJtMkGu3pLvJOwq9kIdf6r7KxMRAbzaRyf95EdQ,10565
-coda/sdk/workflow.py,sha256=QpGvjkNuFKh5XyawC7HXyx-nmC4EKbdRc-6eIjaQ79Q,63171
-coda/tc_tools.py,sha256=hEtVE6xtPqg93WfJ-lQdRQroPdQTkH5HkMLWCIkwIlo,22010
-sprocket_systems_coda_sdk-2.0.8.dist-info/METADATA,sha256=AoA1LH1gdh3NEvIAWqWRYcWObwRLwVCXjwaHpR_LRvw,1106
-sprocket_systems_coda_sdk-2.0.8.dist-info/WHEEL,sha256=tsUv_t7BDeJeRHaSrczbGeuK-TtDpGsWi_JfpzD255I,90
-sprocket_systems_coda_sdk-2.0.8.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-sprocket_systems_coda_sdk-2.0.8.dist-info/licenses/LICENSE,sha256=wrFjizFlraIAPW8JIteGftNH2laAZBBRhdEnPVUsKTM,10198
-sprocket_systems_coda_sdk-2.0.8.dist-info/RECORD,,