sprocket-systems.coda.sdk 1.3.2__py3-none-any.whl → 2.0.5__py3-none-any.whl

coda/sdk/preset.py

@@ -0,0 +1,215 @@
+import requests
+import sys
+
+from typing import ClassVar, Dict, Any, List
+from .enums import PresetType
+from .utils import make_request, validate_group_id
+
+
+class Preset:
+    """A client for interacting with Coda's preset API endpoints.
+
+    This class provides methods to create, update, and retrieve various
+    types of presets, such as those for loudness, naming conventions, and
+    encoding profiles.
+
+    Attributes:
+        routes (ClassVar[Dict[PresetType, str]]): A mapping of preset types
+            to their corresponding API endpoint routes.
+
+    """
+
+    group_path = "groups/:group_id/"
+
+    routes: ClassVar[Dict[PresetType, str]] = {
+        PresetType.JOBS: group_path + "jobs",
+        PresetType.WORKFLOWS: group_path + "workflows",
+        PresetType.LOUDNESS: group_path + "presets/loudness",
+        PresetType.TIMECODE: group_path + "presets/timecode",
+        PresetType.GROUPS: "groups",
+        PresetType.NAMING: "naming-conventions",
+        PresetType.DOLBY: "presets/encoding/dolby",
+        PresetType.DTS: "presets/encoding/dts",
+        PresetType.SUPER_SESSION: "presets/super-session",
+        PresetType.IO_LOCATIONS: "io-locations",
+    }
+
+    def __init__(self, preset_type: PresetType, value: dict[str, Any]) -> None:
+        """Initialize the Preset object.
+
+        This constructor prepares a preset object that can be sent to the Coda
+        API to either create a new preset or update an existing one.
+
+        Args:
+            preset_type (PresetType): The type of preset being handled (e.g.,
+                LOUDNESS, NAMING).
+            value (dict[str, Any]): The dictionary containing the preset's
+                definition and name.
+
+        Attributes:
+            preset (PresetType): Stores the type of the preset.
+            value (dict[str, Any]): Stores the definition payload for the preset.
+            group_id (None): An initialized placeholder for the group ID.
+
+        """
+        self.preset = preset_type
+        self.value = value
+        self.group_id = None
+
+    def register(self) ->  requests.Response:
+        """Register (creates or updates) a preset in Coda.
+
+        If a preset with the same name already exists, it will be updated.
+        Otherwise, a new preset will be created.
+
+        Raises:
+            ValueError: If the preset type is invalid, or if a preset name
+                is ambiguous (matches multiple existing presets).
+
+        Returns:
+            requests.Response: The Response object from the `requests` library.
+
+        """
+        if self.preset not in Preset.routes:
+            raise ValueError(f"Invalid preset type provided: {self.preset}")
+
+        presets = Preset.get_presets(self.preset)
+        found_id = None
+        if presets and len(presets) > 0:
+            pf = [p for p in presets if p["name"] == self.value["name"]]
+            if len(pf) > 1:
+                raise ValueError(
+                    f"Found multiple presets of type '{self.preset.value}' with the name '{self.value['name']}'. "
+                    "Preset names must be unique."
+                )
+            if len(pf) == 1:
+                # Map preset type to its specific ID key
+                key_map = {
+                    PresetType.DOLBY: "encoding_preset_id",
+                    PresetType.DTS: "encoding_preset_id",
+                    PresetType.LOUDNESS: "loudness_preset_id",
+                    PresetType.TIMECODE: "timecode_preset_id",
+                    PresetType.NAMING: "id",
+                    PresetType.SUPER_SESSION: "super_session_preset_id",
+                    PresetType.GROUPS: "group_id",
+                }
+                id_key = key_map.get(self.preset)
+                if id_key:
+                    found_id = pf[0][id_key]
+
+        route = Preset.routes[self.preset]
+        if ":group_id" in route:
+            route = route.replace(":group_id", str(validate_group_id()))
+
+        if not found_id:
+            # Add preset with that name for the first time
+            print(f"creating new preset {self.value['name']}", file=sys.stderr)
+            ret = make_request(requests.post, f"/interface/v2/{route}", self.value)
+        else:
+            request_type = requests.patch
+            if self.preset in [PresetType.TIMECODE, PresetType.LOUDNESS]:
+                request_type = requests.put
+
+            # Update found preset
+            print(f"updating preset {self.value['name']}, id={found_id}", file=sys.stderr)
+            ret = make_request(request_type, f"/interface/v2/{route}/{found_id}", self.value)
+
+        return ret
+
+    @staticmethod
+    def get_presets(preset_type: PresetType) -> List[dict]:
+        """Fetch a list of all existing presets of a specific type.
+
+        Args:
+            preset_type (PresetType): The type of presets to retrieve from Coda.
+
+        Raises:
+            ValueError: If the API call returns an error, indicating the presets
+                could not be fetched.
+
+        Returns:
+            List[dict]: A list of dictionaries, where each dictionary represents a preset.
+
+        """
+        group_id = ""
+        if preset_type in (PresetType.LOUDNESS, PresetType.TIMECODE, PresetType.JOBS, PresetType.WORKFLOWS):
+            group_id = validate_group_id()
+
+        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
+
+    @staticmethod
+    def get_group_id_by_name(group_name: str) -> str:
+        """Get a group ID by its name.
+
+        Args:
+            group_name (str): The name of the group to search for.
+
+        Returns:
+            str: The group ID (group_id field).
+
+        Raises:
+            ValueError: If no group with the given name is found, or if multiple groups match.
+
+        """
+        groups = Preset.get_presets(PresetType.GROUPS)
+        matches = [g["group_id"] for g in groups if g["name"] == group_name]
+
+        if len(matches) == 0:
+            raise ValueError(f"No group found with name '{group_name}'")
+        if len(matches) > 1:
+            raise ValueError(f"Multiple groups found with name '{group_name}': {matches}")
+
+        return matches[0]
+
+    @staticmethod
+    def get_io_location_id_by_name(io_location_name: str) -> str:
+        """Get an IO Location ID by its name.
+
+        Args:
+            io_location_name (str): The name of the IO location to search for.
+
+        Returns:
+            str: The IO location ID (id field).
+
+        Raises:
+            ValueError: If no IO location with the given name is found, or if multiple match.
+
+        """
+        io_locations = Preset.get_presets(PresetType.IO_LOCATIONS)
+        matches = [loc["id"] for loc in io_locations if loc["name"] == io_location_name]
+
+        if len(matches) == 0:
+            raise ValueError(f"No IO location found with name '{io_location_name}'")
+        if len(matches) > 1:
+            raise ValueError(f"Multiple IO locations found with name '{io_location_name}': {matches}")
+
+        return matches[0]
+
+    @staticmethod
+    def get_workflow_by_name(workflow_name: str) -> dict:
+        """Get a workflow by its name.
+
+        Args:
+            workflow_name (str): The name of the workflow to search for.
+
+        Returns:
+            dict: The complete workflow object.
+
+        Raises:
+            ValueError: If no workflow with the given name is found, or if multiple match.
+
+        """
+        workflows = Preset.get_presets(PresetType.WORKFLOWS)
+        matches = [w for w in workflows if w["name"] == workflow_name]
+
+        if len(matches) == 0:
+            raise ValueError(f"No workflow found with name '{workflow_name}'")
+        if len(matches) > 1:
+            raise ValueError(f"Multiple workflows found with name '{workflow_name}': {[w['id'] for w in matches]}")
+
+        return matches[0]

coda/sdk/utils.py

@@ -0,0 +1,282 @@
+import os
+import requests
+import re
+import urllib3
+
+from typing import TYPE_CHECKING, List, Dict, Any, Callable
+
+from .constants import (
+    ENV_CODA_API_GROUP_ID,
+    ENV_CODA_API_URL,
+    ENV_CODA_API_TOKEN,
+    ENV_CODA_API_INSECURE_SKIP_VERIFY,
+    DEFAULT_API_URL,
+    INSECURE_SKIP_VERIFY_VALUES,
+)
+
+if TYPE_CHECKING:
+    from ..tc_tools import (
+        time_seconds_to_vid_frames,
+        vid_frames_to_tc,
+        tc_to_time_seconds,
+    )
+
+_CHANNEL_CONFIGURATIONS: dict = {
+    "MONO": ["C"],
+    "2.0": ["L", "R"],
+    "3.0": ["L", "C", "R"],
+    "LCRS": ["L", "C", "R", "S"],
+    "5.0": ["L", "C", "R", "Ls", "Rs"],
+    "5.0.2": ["L", "C", "R", "Ls", "Rs", "Ltm", "Rtm"],
+    "7.0": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr"],
+    "7.1": ["L", "R", "C", "LFE", "Lss", "Rss", "Lsr", "Rsr"],
+    "5.1": ["L", "R", "C", "LFE", "Ls", "Rs"],
+    "5.1.2": ["L", "C", "R", "Ls", "Rs", "Ltm", "Rtm", "LFE"],
+    "5.0.4": ["L", "C", "R", "Ls", "Rs", "Ltf", "Rtf", "Ltr", "Rtr"],
+    "7.0.2": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Lts", "Rts"],
+    "5.1.4": ["L", "C", "R", "Ls", "Rs", "Ltf", "Rtf", "Ltr", "Rtr", "LFE"],
+    "7.1.2": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Lts", "Rts", "LFE"],
+    "7.0.4": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltr", "Rtr"],
+    "7.1.4": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltr", "Rtr", "LFE"],
+    "7.0.6": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltm", "Rtm", "Ltr", "Rtr"],
+    "9.0.4": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltr", "Rtr", "Lw", "Rw"],
+    "7.1.6": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltm", "Rtm", "Ltr", "Rtr", "LFE"],
+    "9.1.4": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltr", "Rtr", "Lw", "Rw", "LFE"],
+    "9.0.6": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltm", "Rtm", "Ltr", "Rtr", "Lw", "Rw"],
+    "9.1.6": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltm", "Rtm", "Ltr", "Rtr", "Lw", "Rw", "LFE"],
+    "IMAX5": ["L", "C", "R", "Ls", "Rs"],
+    "IMAX6": ["L", "C", "R", "Ls", "Rs", "Ctf"],
+    "IMAX12": ["L", "C", "R", "Lss", "Rss", "Lsr", "Rsr", "Ltf", "Rtf", "Ltr", "Rtr", "Ctf"],
+}
+
+
+def get_channels(channel_format: str) -> List[str] | None:
+    """Get the standard channel labels for a given audio format.
+
+    This function looks up a channel format string (e.g., "5.1") in a
+    predefined dictionary and returns the corresponding list of standard
+    channel labels (e.g., ["L", "R", "C", "LFE", "Ls", "Rs"]).
+
+    Args:
+        channel_format (str): The audio format (e.g., "5.1", "7.1").
+
+    Returns:
+        List[str] | None: A list of channel labels, or None if the format is unknown.
+
+    """
+    return _CHANNEL_CONFIGURATIONS.get(channel_format)
+
+
+def user_info() -> str:
+    """Retrieve information about the authenticated user.
+
+    Makes an authenticated GET request to the Coda API's '/interface/v2/users/me'
+    endpoint to fetch details for the current user, determined by the API token.
+
+    Returns:
+        str: The JSON response from the API as a string.
+
+    """
+    ret = make_request(requests.get, "/interface/v2/users/me")
+    return ret.json()
+
+
+def validate_group_id() -> str:
+    """Get the Coda Group ID from environment variables.
+
+    Retrieves the Coda Group ID from the 'CODA_API_GROUP_ID' environment
+    variable. This ID is required for most API operations that are scoped
+    to a specific group.
+
+    Raises:
+        ValueError: If the 'CODA_API_GROUP_ID' environment variable is not set.
+
+    Returns:
+        str: The Coda Group ID.
+
+    """
+    group_id = os.getenv(ENV_CODA_API_GROUP_ID)
+    if group_id is not None:
+        return group_id
+    raise ValueError("Error: CODA_API_GROUP_ID is not set.")
+
+
+def make_request(
+    func: Callable[..., requests.Response],
+    route: str,
+    payload: Dict[str, Any] | None = None,
+) -> requests.Response:
+    """Make an authenticated request to the Coda API.
+
+    This is a general-purpose helper function for interacting with the Coda API.
+    It constructs the full request URL, adds the necessary authentication
+    headers, and executes the request using the provided function (e.g.,
+    requests.get, requests.post).
+
+    Args:
+        func (Callable[..., requests.Response]): The requests function to call
+            (e.g., requests.get, requests.post, requests.put).
+        route (str): The API endpoint route (e.g., "/interface/v2/users/me").
+        payload (Dict[str, Any], optional): A JSON serializable dictionary to
+            be sent as the request body. Defaults to None.
+
+    Raises:
+        ValueError: If the 'CODA_API_TOKEN' environment variable is not set.
+
+    Returns:
+        requests.Response: The Response object from the `requests` library.
+
+    """
+    url = os.getenv(ENV_CODA_API_URL, DEFAULT_API_URL)
+    url += route
+    token = os.getenv(ENV_CODA_API_TOKEN)
+    if token:
+        verify = True
+        if os.getenv(ENV_CODA_API_INSECURE_SKIP_VERIFY, '').lower() in INSECURE_SKIP_VERIFY_VALUES:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+            verify = False
+        auth = {"Authorization": f"Bearer {token}"}
+        return func(url, json=payload, headers=auth, verify=verify)
+    raise ValueError("Error: CODA_API_TOKEN is not set.")
+
+
+def timing_info(
+    inputs: Dict[str, Any],
+    venue: str | None = None,
+    fps: str | None = None,
+    ffoa: str | None = None,
+    lfoa: str | None = None,
+    start_time: str | None = None,
+) -> Dict[str, Any] | None:
+    """Calculate various timing-related values for a set of inputs.
+
+    This function processes a job's input definition to extract or calculate
+    key timing metrics. It determines start time, duration, frame rate, and other
+    values from the source essence definitions. It can also accept overrides for
+    these values. The results are returned in a dictionary, including both
+    second-based and timecode-based representations.
+
+    Note:
+        This function dynamically imports from `..tc_tools` for timecode
+        conversions.
+
+    Args:
+        inputs (Dict[str, Any]): The workflow input dictionary, typically containing
+            keys like 'sources', 'venue', and 'source_frame_rate'.
+        venue (str, optional): Overrides the venue specified in the inputs. Defaults to None.
+        fps (str, optional): Overrides the frame rate specified in the inputs. Defaults to None.
+        ffoa (str, optional): Overrides the FFOA timecode specified in the inputs. Defaults to None.
+        lfoa (str, optional): Overrides the LFOA timecode specified in the inputs. Defaults to None.
+        start_time (str, optional): Overrides the start time. Not currently used in the function.
+
+    Returns:
+        Dict[str, Any] | None: A dictionary containing calculated timing information,
+        or None if the input dictionary is empty.
+
+    """
+    from ..tc_tools import (
+        time_seconds_to_vid_frames,
+        vid_frames_to_tc,
+        tc_to_time_seconds,
+    )
+
+    if not inputs:
+        return None
+    tinfo = {}
+    if venue:
+        tinfo["venue"] = venue
+    else:
+        tinfo["venue"] = inputs["venue"]
+    if not fps:
+        tinfo["source_frame_rate"] = inputs["source_frame_rate"]
+        fps = tinfo["source_frame_rate"]
+    else:
+        tinfo["source_frame_rate"] = fps
+    if not ffoa:
+        tinfo["ffoa_timecode"] = inputs["ffoa_timecode"]
+    else:
+        tinfo["ffoa_timecode"] = ffoa
+    if not lfoa:
+        tinfo["lfoa_timecode"] = inputs["lfoa_timecode"]
+    else:
+        tinfo["lfoa_timecode"] = lfoa
+    startt = -1
+    srate = -1
+    filelen = -1
+    sources = inputs["sources"]
+    for s in sources:
+        definition = s.get("definition", {})
+        if definition:
+            if "programme_timing" in definition:
+                srate = definition["sample_rate"]
+                filelen = definition["frames"] / srate
+                startt = (
+                    definition["programme_timing"][
+                        "audio_programme_start_time_reference"
+                    ]
+                    / srate
+                )
+                break
+            if "resources" in definition:
+                startt = (
+                    definition["resources"][0]["bext_time_reference"]
+                    / definition["resources"][0]["sample_rate"]
+                )
+                srate = definition["resources"][0]["sample_rate"]
+                filelen = definition["resources"][0]["frames"] / srate
+                break
+
+    tinfo["start_time_sec"] = startt
+    tinfo["file_duration_sec"] = filelen
+    tinfo["file_duration"] = ""
+    if fps != "":
+        tinfo["file_duration"] = vid_frames_to_tc(
+            time_seconds_to_vid_frames(filelen, fps), fps
+        )
+        tinfo["start_timecode"] = ""
+    if fps != "":
+        tinfo["start_timecode"] = vid_frames_to_tc(
+            time_seconds_to_vid_frames(startt, fps), fps
+        )
+    tinfo["end_timecode"] = ""
+    if fps != "":
+        tinfo["end_timecode"] = vid_frames_to_tc(
+            time_seconds_to_vid_frames(startt + filelen, fps) - 1, fps
+        )
+    tinfo["ffoa_seconds"] = -1
+    tinfo["lfoa_seconds"] = -1
+    if fps != "":
+        tinfo["ffoa_seconds"] = tc_to_time_seconds(tinfo["ffoa_timecode"], fps)
+        tinfo["lfoa_seconds"] = tc_to_time_seconds(tinfo["lfoa_timecode"], fps)
+    tinfo["sample_rate"] = srate
+
+    return tinfo
+
+
+def is_key_value_comma_string(s: str) -> bool:
+    """Validate a string formatted as KEY=VALUE,KEY=VALUE,...
+
+    The pattern expects:
+    - Uppercase letters, numbers, and underscores for KEYS.
+    - Letters, numbers, hyphens, and underscores for VALUES.
+    - Key-value pairs separated by a single comma.
+    - No leading/trailing commas, and no empty keys or values.
+
+    Returns:
+        bool: true if matched
+
+    """
+    # Regex breakdown:
+    # ^                 # Start of the string
+    # ([A-Z0-9_]+)      # Group 1: KEY - one or more uppercase letters, numbers, or underscores
+    # =                 # Literal equals sign
+    # ([a-zA-Z0-9_-]+)  # Group 2: VALUE - one or more letters, numbers, hyphens, or underscores
+    # (                 # Start of non-capturing group for subsequent pairs
+    #   ,[A-Z0-9_]+=    # Comma followed by KEY=
+    #   [a-zA-Z0-9_-]+  # VALUE
+    # )*                # Zero or more of the subsequent pairs
+    # $                 # End of the string
+
+    pattern = r"^([A-Z0-9_]+=[a-zA-Z0-9_-]+)(,[A-Z0-9_]+=[a-zA-Z0-9_-]+)*$"
+
+    return re.fullmatch(pattern, s) is not None