codecraftai-restclient-runpod 1.2.0__py3-none-any.whl

ccai/restclient/runpod/apigroups/datacentersgroup.py

@@ -0,0 +1,82 @@
+"""
+    .. module:: datacentersgroup
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains the :class:`DataCentersGroup` api
+                   group exposing the RunPod data-center catalog endpoint.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Any, Dict, List
+
+from ccai.restclient.base.restapigroup import RestApiGroup
+
+from ccai.restclient.runpod.aspectsrunpod import (
+    AspectsRunpod, DEFAULT_RUNPOD_ASPECTS
+)
+from ccai.restclient.runpod.apigroups.groupsupport import raise_for_status
+from ccai.restclient.runpod.model.runpoddatacenter import RunpodDataCenter
+
+
+class DataCentersGroup(RestApiGroup):
+    """
+        :class:`DataCentersGroup` exposes the RunPod data-center catalog
+        endpoint. The catalog is a small, non-paged collection.
+    """
+
+    BASE_LEAF = "/v1"
+
+    def list(self, *,
+             aspects: AspectsRunpod = DEFAULT_RUNPOD_ASPECTS) -> List[RunpodDataCenter]:
+        """
+            List every RunPod data center.
+
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`RunpodDataCenter` records.
+        """
+        client = self.client
+        leaf = self.build_leaf(parts=["datacenters"])
+        response = client.request(method="GET", leaf=leaf, aspects=aspects)
+        raise_for_status(response=response, action="list data centers")
+
+        payload = response.json()
+        raw_entries = self._extract_entries(payload=payload)
+
+        rtnval: List[RunpodDataCenter] = []
+        for entry in raw_entries:
+            rtnval.append(RunpodDataCenter.from_dict(entry))
+
+        return rtnval
+
+    def _extract_entries(self, *, payload: Any) -> List[Dict[str, Any]]:
+        """
+            Extract the data-center entry list from a response payload.
+
+            :param payload: The decoded response payload.
+
+            :returns: The list of raw data-center dictionaries.
+        """
+        if isinstance(payload, list):
+            rtnval: List[Dict[str, Any]] = list(payload)
+            return rtnval
+
+        if isinstance(payload, dict):
+            entries = payload.get("dataCenters")
+            if entries is None:
+                entries = payload.get("datacenters")
+            if entries is None:
+                entries = payload.get("items", [])
+            rtnval = list(entries)
+            return rtnval
+
+        rtnval = []
+        return rtnval
+
+
+__all__ = ["DataCentersGroup"]

ccai/restclient/runpod/apigroups/gputypesgroup.py

@@ -0,0 +1,80 @@
+"""
+    .. module:: gputypesgroup
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains the :class:`GpuTypesGroup` api group
+                   exposing the RunPod GPU-type catalog endpoint.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Any, Dict, List
+
+from ccai.restclient.base.restapigroup import RestApiGroup
+
+from ccai.restclient.runpod.aspectsrunpod import (
+    AspectsRunpod, DEFAULT_RUNPOD_ASPECTS
+)
+from ccai.restclient.runpod.apigroups.groupsupport import raise_for_status
+from ccai.restclient.runpod.model.runpodgputype import RunpodGpuType
+
+
+class GpuTypesGroup(RestApiGroup):
+    """
+        :class:`GpuTypesGroup` exposes the RunPod GPU-type catalog endpoint.
+        The catalog is a small, non-paged collection.
+    """
+
+    BASE_LEAF = "/v1"
+
+    def list(self, *,
+             aspects: AspectsRunpod = DEFAULT_RUNPOD_ASPECTS) -> List[RunpodGpuType]:
+        """
+            List every GPU type RunPod offers.
+
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`RunpodGpuType` records.
+        """
+        client = self.client
+        leaf = self.build_leaf(parts=["gpuTypes"])
+        response = client.request(method="GET", leaf=leaf, aspects=aspects)
+        raise_for_status(response=response, action="list gpu types")
+
+        payload = response.json()
+        raw_entries = self._extract_entries(payload=payload)
+
+        rtnval: List[RunpodGpuType] = []
+        for entry in raw_entries:
+            rtnval.append(RunpodGpuType.from_dict(entry))
+
+        return rtnval
+
+    def _extract_entries(self, *, payload: Any) -> List[Dict[str, Any]]:
+        """
+            Extract the GPU-type entry list from a response payload.
+
+            :param payload: The decoded response payload.
+
+            :returns: The list of raw GPU-type dictionaries.
+        """
+        if isinstance(payload, list):
+            rtnval: List[Dict[str, Any]] = list(payload)
+            return rtnval
+
+        if isinstance(payload, dict):
+            entries = payload.get("gpuTypes")
+            if entries is None:
+                entries = payload.get("items", [])
+            rtnval = list(entries)
+            return rtnval
+
+        rtnval = []
+        return rtnval
+
+
+__all__ = ["GpuTypesGroup"]

ccai/restclient/runpod/apigroups/groupsupport.py

@@ -0,0 +1,182 @@
+"""
+    .. module:: groupsupport
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains shared helpers used by the RunPod
+                   api-group classes — URL composition and HTTP-error
+                   reclassification.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from typing import Any, Callable, Dict, Iterator, List, Optional
+from urllib.parse import quote
+
+from requests import Response
+
+from ccai.errors.exceptions import SemanticError
+
+from ccai.restclient.runpod.exceptions.runpoderrors import (
+    RunpodAuthenticationError, RunpodError
+)
+
+
+def encode_segment(*, segment: str) -> str:
+    """
+        Percent-encode a single URL path segment.
+
+        :param segment: The path segment to encode. Must be a non-empty
+            string.
+
+        :returns: The percent-encoded segment.
+
+        :raises: :class:`SemanticError` when ``segment`` is ``None`` or
+            empty.
+    """
+    if segment is None:
+        raise SemanticError("A RunPod URL path segment must not be None.")
+    if not isinstance(segment, str):
+        raise SemanticError("A RunPod URL path segment must be a string.")
+    if len(segment) == 0:
+        raise SemanticError("A RunPod URL path segment must not be empty.")
+
+    rtnval = quote(segment, safe="")
+    return rtnval
+
+
+def compose_leaf(*, base: str, parts: List[str]) -> str:
+    """
+        Compose a REST leaf path by joining ``base`` with per-segment
+        percent-encoded ``parts``.
+
+        :param base: The base leaf path (e.g. ``"/v1"``).
+        :param parts: The path segments to append. Each segment is
+            percent-encoded; empty / ``None`` segments are rejected.
+
+        :returns: The composed leaf path.
+
+        :raises: :class:`SemanticError` when ``parts`` is ``None`` or holds
+            an empty / ``None`` segment.
+    """
+    if parts is None:
+        raise SemanticError("compose_leaf requires a non-None parts list.")
+
+    encoded_parts: List[str] = []
+    for part in parts:
+        encoded_parts.append(encode_segment(segment=part))
+
+    trimmed_base = base
+    if trimmed_base.endswith("/"):
+        trimmed_base = trimmed_base[:-1]
+
+    joined = "/".join(encoded_parts)
+    rtnval = "{}/{}".format(trimmed_base, joined)
+    return rtnval
+
+
+def raise_for_status(*, response: Response, action: str) -> None:
+    """
+        Reclassify a non-2xx RunPod response into a typed exception.
+
+        :param response: The :class:`Response` to inspect.
+        :param action: A short description of the attempted action.
+
+        :returns: ``None``.
+
+        :raises: :class:`RunpodAuthenticationError` on HTTP 401 / 403;
+            :class:`RunpodError` on every other non-2xx status.
+    """
+    status = response.status_code
+    if 200 <= status < 300:
+        return
+
+    err_msg_lines = ["RunPod API call failed: {}.".format(action)]
+    err_msg_lines.append("STATUS: {}".format(status))
+    err_msg_lines.append("RESPONSE:")
+    err_msg_lines.append(response.text)
+    err_msg = os.linesep.join(err_msg_lines)
+
+    if status == 401 or status == 403:
+        raise RunpodAuthenticationError(err_msg)
+
+    raise RunpodError(err_msg)
+
+
+def safe_json(*, response: Response) -> Dict[str, Any]:
+    """
+        Parse a response body as a JSON object, degrading to an empty dict.
+
+        :param response: The :class:`Response` to parse.
+
+        :returns: The decoded object, or an empty dict.
+    """
+    try:
+        payload = response.json()
+    except ValueError:
+        rtnval: Dict[str, Any] = {}
+        return rtnval
+
+    if not isinstance(payload, dict):
+        rtnval = {}
+        return rtnval
+
+    rtnval = payload
+    return rtnval
+
+
+def iter_cursor_pages(*, fetch_page: Callable[[Optional[str]], Dict[str, Any]],
+                       items_field: str = "items",
+                       cursor_field: str = "next") -> Iterator[Dict[str, Any]]:
+    """
+        Iterate a cursor-paginated RunPod endpoint, yielding each raw item
+        dictionary across every page.
+
+        :param fetch_page: Callable accepting the current cursor token
+            (``None`` on the first call) and returning a page dictionary.
+        :param items_field: Name of the field holding the page item list.
+        :param cursor_field: Name of the field holding the next-page cursor
+            token (``None`` / absent / empty-string indicates the final
+            page).
+
+        :returns: An iterator over the raw item dictionaries.
+
+        :raises: :class:`RunpodError` when the endpoint returns a cursor
+            token that has already been seen (cursor cycle).
+    """
+    cursor: Optional[str] = None
+    seen_cursors: List[str] = []
+    while True:
+        page = fetch_page(cursor)
+
+        items = page.get(items_field)
+        if items is None:
+            items = []
+        for item in items:
+            yield item
+
+        next_cursor = page.get(cursor_field)
+        if next_cursor is None:
+            break
+        if not isinstance(next_cursor, str):
+            break
+        if len(next_cursor) == 0:
+            break
+        if next_cursor in seen_cursors:
+            err_msg_lines = ["RunPod cursor pagination detected a cursor cycle."]
+            err_msg_lines.append("REPEATED CURSOR: {}".format(next_cursor))
+            err_msg = os.linesep.join(err_msg_lines)
+            raise RunpodError(err_msg)
+
+        seen_cursors.append(next_cursor)
+        cursor = next_cursor
+    return
+
+
+__all__ = ["encode_segment", "compose_leaf", "raise_for_status", "safe_json",
+           "iter_cursor_pages"]

ccai/restclient/runpod/apigroups/networkvolumesgroup.py

@@ -0,0 +1,156 @@
+"""
+    .. module:: networkvolumesgroup
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains the :class:`NetworkVolumesGroup` api
+                   group exposing the RunPod network-volume endpoints.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Any, Dict, List, Optional
+
+from ccai.errors.exceptions import SemanticError
+
+from ccai.restclient.base.restapigroup import RestApiGroup
+
+from ccai.restclient.runpod.aspectsrunpod import (
+    AspectsRunpod, DEFAULT_RUNPOD_ASPECTS
+)
+from ccai.restclient.runpod.apigroups.groupsupport import (
+    iter_cursor_pages, raise_for_status, safe_json
+)
+from ccai.restclient.runpod.model.runpodnetworkvolume import (
+    RunpodNetworkVolume
+)
+from ccai.restclient.runpod.specs.runpodnetworkvolumespec import (
+    RunpodNetworkVolumeSpec
+)
+
+
+class NetworkVolumesGroup(RestApiGroup):
+    """
+        :class:`NetworkVolumesGroup` exposes the RunPod network-volume
+        endpoints — idempotent create, cursor-paged list, and idempotent
+        delete.
+    """
+
+    BASE_LEAF = "/v1"
+
+    def create(self, *, spec: RunpodNetworkVolumeSpec,
+               aspects: AspectsRunpod = DEFAULT_RUNPOD_ASPECTS) -> RunpodNetworkVolume:
+        """
+            Create a network volume. An existing volume carrying the same
+            name in the same data center is returned unchanged (idempotent
+            create).
+
+            :param spec: The :class:`RunpodNetworkVolumeSpec` to realise.
+            :param aspects: Behaviour control for the call.
+
+            :returns: A :class:`RunpodNetworkVolume` record.
+
+            :raises: :class:`SemanticError` when ``spec`` is ``None``.
+        """
+        if spec is None:
+            raise SemanticError("NetworkVolumesGroup.create requires a spec.")
+
+        existing = self._find_by_name(name=spec.name,
+                                      data_center_id=spec.data_center_id,
+                                      aspects=aspects)
+        if existing is not None:
+            rtnval = existing
+            return rtnval
+
+        client = self.client
+        leaf = self.build_leaf(parts=["networkvolumes"])
+        response = client.request(method="POST", leaf=leaf,
+                                  json_body=spec.to_payload(),
+                                  aspects=aspects)
+        raise_for_status(response=response, action="create network volume")
+
+        rtnval = RunpodNetworkVolume.from_dict(safe_json(response=response))
+        return rtnval
+
+    def list(self, *,
+             aspects: AspectsRunpod = DEFAULT_RUNPOD_ASPECTS) -> List[RunpodNetworkVolume]:
+        """
+            List every network volume, following cursor pages transparently.
+
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`RunpodNetworkVolume` records.
+        """
+        client = self.client
+        leaf = self.build_leaf(parts=["networkvolumes"])
+
+        def fetch_page(cursor: Optional[str]) -> Dict[str, Any]:
+            params: Dict[str, str] = {"limit": str(aspects.page_size)}
+            if cursor is not None:
+                params["cursor"] = cursor
+            response = client.request(method="GET", leaf=leaf,
+                                      params=params, aspects=aspects)
+            raise_for_status(response=response, action="list network volumes")
+            page = safe_json(response=response)
+            return page
+
+        rtnval: List[RunpodNetworkVolume] = []
+        for entry in iter_cursor_pages(fetch_page=fetch_page):
+            rtnval.append(RunpodNetworkVolume.from_dict(entry))
+
+        return rtnval
+
+    def delete(self, *, volume_id: str,
+               aspects: AspectsRunpod = DEFAULT_RUNPOD_ASPECTS) -> None:
+        """
+            Delete a network volume. Deleting an unknown id is a no-op.
+
+            :param volume_id: The network-volume identifier to delete.
+            :param aspects: Behaviour control for the call.
+
+            :returns: ``None``.
+
+            :raises: :class:`SemanticError` when ``volume_id`` is empty.
+        """
+        if volume_id is None or len(volume_id) == 0:
+            raise SemanticError("'volume_id' must be a non-empty string.")
+
+        client = self.client
+        leaf = self.build_leaf(parts=["networkvolumes", volume_id])
+        response = client.request(method="DELETE", leaf=leaf, aspects=aspects)
+
+        status = response.status_code
+        if 200 <= status < 300:
+            return
+        if status == 404:
+            return
+
+        raise_for_status(response=response, action="delete network volume")
+        return
+
+    def _find_by_name(self, *, name: str, data_center_id: str,
+                       aspects: AspectsRunpod) -> Optional[RunpodNetworkVolume]:
+        """
+            Find an existing network volume by name and data center.
+
+            :param name: The volume name to match.
+            :param data_center_id: The data center to match.
+            :param aspects: Behaviour control for the call.
+
+            :returns: The matching :class:`RunpodNetworkVolume`, or ``None``.
+        """
+        volumes = self.list(aspects=aspects)
+        for volume in volumes:
+            if volume.name == name:
+                if volume.data_center_id == data_center_id:
+                    rtnval: Optional[RunpodNetworkVolume] = volume
+                    return rtnval
+
+        rtnval = None
+        return rtnval
+
+
+__all__ = ["NetworkVolumesGroup"]