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

ccai/restclient/nutanix/__init__.py

@@ -0,0 +1,12 @@
+"""
+    .. module:: nutanix
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: The ``ccai.restclient.nutanix`` package — the typed,
+                   aspect-driven Nutanix Prism REST client.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2026, Code Craft AI LLC"
+__credits__ = []

ccai/restclient/nutanix/apigroups/clustersgroup.py

@@ -0,0 +1,125 @@
+"""
+    .. module:: clustersgroup
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains the :class:`ClustersGroup` and
+                   :class:`HostsGroup` api groups exposing the Prism Central
+                   cluster and host enumeration 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
+
+from ccai.restclient.base.restapigroup import RestApiGroup
+
+from ccai.restclient.nutanix.aspectsnutanix import (
+    AspectsNutanix, DEFAULT_NUTANIX_ASPECTS
+)
+from ccai.restclient.nutanix.apigroups.groupsupport import iter_list_entities
+from ccai.restclient.nutanix.model.nutanixcluster import NutanixCluster
+from ccai.restclient.nutanix.model.nutanixhost import NutanixHost
+from ccai.restclient.nutanix.model.nutanixstoragecontainer import (
+    NutanixStorageContainer
+)
+
+
+class ClustersGroup(RestApiGroup):
+    """
+        :class:`ClustersGroup` exposes the Prism Central cluster and
+        storage-container enumeration endpoints.
+    """
+
+    def list(self, *,
+             aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+             ) -> List[NutanixCluster]:
+        """
+            Enumerate every cluster managed by Prism Central.
+
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`NutanixCluster` records.
+        """
+        client = self.client
+
+        def _fetch_page(offset: int, length: int) -> Dict[str, Any]:
+            page = client.post_list(entity="clusters", offset=offset,
+                                    length=length, action="list clusters",
+                                    aspects=aspects)
+            return page
+
+        entities = iter_list_entities(fetch_page=_fetch_page, aspects=aspects)
+        rtnval: List[NutanixCluster] = []
+        for entity in entities:
+            rtnval.append(NutanixCluster.from_dict(entity))
+        return rtnval
+
+    def list_storage_containers(self, *,
+                                aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+                                ) -> List[NutanixStorageContainer]:
+        """
+            Enumerate every storage container known to Prism Central.
+
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`NutanixStorageContainer` records.
+        """
+        client = self.client
+
+        def _fetch_page(offset: int, length: int) -> Dict[str, Any]:
+            page = client.post_list(entity="storage_containers",
+                                    offset=offset, length=length,
+                                    action="list storage containers",
+                                    aspects=aspects)
+            return page
+
+        entities = iter_list_entities(fetch_page=_fetch_page, aspects=aspects)
+        rtnval: List[NutanixStorageContainer] = []
+        for entity in entities:
+            rtnval.append(NutanixStorageContainer.from_dict(entity))
+        return rtnval
+
+
+class HostsGroup(RestApiGroup):
+    """
+        :class:`HostsGroup` exposes the Prism Central host enumeration
+        endpoint.
+    """
+
+    def list(self, *, cluster_uuid: str,
+             aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+             ) -> List[NutanixHost]:
+        """
+            Enumerate the hosts belonging to a cluster.
+
+            :param cluster_uuid: The cluster uuid to filter hosts by.
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`NutanixHost` records.
+        """
+        client = self.client
+
+        def _fetch_page(offset: int, length: int) -> Dict[str, Any]:
+            page = client.post_list(entity="hosts", offset=offset,
+                                    length=length, action="list hosts",
+                                    aspects=aspects)
+            return page
+
+        entities = iter_list_entities(fetch_page=_fetch_page, aspects=aspects)
+        rtnval: List[NutanixHost] = []
+        for entity in entities:
+            host = NutanixHost.from_dict(entity)
+            status = entity.get("status", {})
+            cluster_ref = status.get("cluster_reference", {})
+            host_cluster = cluster_ref.get("uuid", None)
+            if cluster_uuid is None or len(cluster_uuid) == 0:
+                rtnval.append(host)
+            elif host_cluster == cluster_uuid:
+                rtnval.append(host)
+            elif host_cluster is None:
+                rtnval.append(host)
+        return rtnval

ccai/restclient/nutanix/apigroups/groupsupport.py

@@ -0,0 +1,161 @@
+"""
+    .. module:: groupsupport
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains shared helpers used by the Nutanix
+                   Prism Central api-group classes.
+
+    .. 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, List
+from urllib.parse import quote
+
+from requests import Response
+
+from ccai.errors.exceptions import SemanticError
+
+from ccai.restclient.nutanix.aspectsnutanix import AspectsNutanix
+from ccai.restclient.nutanix.exceptions.nutanixexceptions import (
+    NutanixAuthenticationError
+)
+
+
+def encode_segment(*, segment: str) -> str:
+    """
+        Percent-encode a single URL path segment.
+
+        Empty or ``None`` identifiers are rejected — a missing identifier
+        is an API-misuse condition, not a runtime error.
+
+        :param segment: The raw path segment.
+
+        :returns: The percent-encoded segment.
+
+        :raises: :class:`SemanticError` when the segment is empty/None.
+    """
+    if segment is None:
+        raise SemanticError("URL path segment must not be None.")
+    if len(segment) == 0:
+        raise SemanticError("URL path segment must not be empty.")
+
+    rtnval = quote(segment, safe="")
+    return rtnval
+
+
+def compose_leaf(*, base: str, parts: List[str]) -> str:
+    """
+        Compose a Prism Central API leaf from a base prefix and per-segment
+        identifiers.  Each identifier is percent-encoded independently.
+
+        :param base: The base leaf (e.g. ``/api/nutanix/v3/vms``).
+        :param parts: Trailing path identifiers (uuids, action names).
+
+        :returns: The composed leaf path beginning with ``/``.
+
+        :raises: :class:`SemanticError` when ``parts`` carries an empty
+            identifier.
+    """
+    if base is None or len(base) == 0:
+        raise SemanticError("compose_leaf requires a non-empty base.")
+
+    leaf = base
+    if parts is not None:
+        for part in parts:
+            encoded = encode_segment(segment=part)
+            leaf = leaf + "/" + encoded
+
+    rtnval = leaf
+    return rtnval
+
+
+def raise_for_status(*, response: Response, action: str) -> None:
+    """
+        Raise a descriptive error for a non-2xx Prism Central response.
+
+        HTTP 401 / 403 are reclassified into
+        :class:`NutanixAuthenticationError`; every other non-2xx becomes a
+        :class:`SemanticError`.
+
+        :param response: The :class:`Response` to inspect.
+        :param action: A short description of the attempted action.
+
+        :returns: ``None``.
+
+        :raises: :class:`NutanixAuthenticationError`,
+            :class:`SemanticError`.
+    """
+    status = response.status_code
+    if 200 <= status < 300:
+        return
+
+    if status in (401, 403):
+        err_msg_lines = ["Nutanix Prism Central rejected the credential."]
+        err_msg_lines.append("ACTION: {}".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)
+        raise NutanixAuthenticationError(err_msg)
+
+    err_msg_lines = ["Nutanix Prism Central 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)
+    raise SemanticError(err_msg)
+
+
+def iter_list_entities(*, fetch_page: Callable[[int, int], Dict[str, Any]],
+                        aspects: AspectsNutanix) -> List[Dict[str, Any]]:
+    """
+        Walk a Prism Central ``*/list`` endpoint, following the offset
+        cursor until every entity has been collected.
+
+        Prism v3 ``*/list`` endpoints accept an offset/length body and
+        return ``{"metadata": {"total_matches": N, "offset": O, ...},
+        "entities": [...]}``.  This helper pages by offset using the page
+        length from ``aspects`` until the collected count reaches
+        ``total_matches`` (or a page returns no entities).
+
+        :param fetch_page: Callable accepting ``(offset, length)`` and
+            returning the parsed page dict.
+        :param aspects: Behaviour control supplying the page length.
+
+        :returns: A list of raw entity dicts in traversal order.
+    """
+    page_length = aspects.page_length
+    if page_length <= 0:
+        raise SemanticError("AspectsNutanix.page_length must be > 0.")
+
+    collected: List[Dict[str, Any]] = []
+    offset = 0
+    while True:
+        page = fetch_page(offset, page_length)
+
+        entities = page.get("entities", None)
+        if entities is None:
+            entities = []
+        for entity in entities:
+            collected.append(entity)
+
+        page_metadata = page.get("metadata", {})
+        total_matches = page_metadata.get("total_matches", None)
+
+        if len(entities) == 0:
+            break
+        if total_matches is not None and len(collected) >= total_matches:
+            break
+
+        offset = offset + page_length
+
+    rtnval = collected
+    return rtnval

ccai/restclient/nutanix/apigroups/imagesgroup.py

@@ -0,0 +1,117 @@
+"""
+    .. module:: imagesgroup
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains the :class:`ImagesGroup` api group
+                   for the Prism Central image catalog.
+
+    .. 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.restclient.base.restapigroup import RestApiGroup
+
+from ccai.restclient.nutanix.aspectsnutanix import (
+    AspectsNutanix, DEFAULT_NUTANIX_ASPECTS
+)
+from ccai.restclient.nutanix.apigroups.groupsupport import iter_list_entities
+from ccai.restclient.nutanix.model.nutaniximage import NutanixImage
+from ccai.restclient.nutanix.model.nutanixtaskhandle import NutanixTaskHandle
+from ccai.restclient.nutanix.specs.nutanixspecs import ImageSpec
+
+
+class ImagesGroup(RestApiGroup):
+    """
+        :class:`ImagesGroup` exposes the Prism Central image-catalog
+        endpoints — upload, list (paged), and idempotent delete.
+    """
+
+    def list(self, *,
+             aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+             ) -> List[NutanixImage]:
+        """
+            Enumerate every image in the Prism Central catalog.
+
+            :param aspects: Behaviour control for the call.
+
+            :returns: A list of :class:`NutanixImage` records.
+        """
+        client = self.client
+
+        def _fetch_page(offset: int, length: int) -> Dict[str, Any]:
+            page = client.post_list(entity="images", offset=offset,
+                                    length=length, action="list images",
+                                    aspects=aspects)
+            return page
+
+        entities = iter_list_entities(fetch_page=_fetch_page, aspects=aspects)
+        rtnval: List[NutanixImage] = []
+        for entity in entities:
+            rtnval.append(NutanixImage.from_dict(entity))
+        return rtnval
+
+    def find_by_name(self, *, name: str,
+                     aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+                     ) -> Optional[NutanixImage]:
+        """
+            Return the image with the given name, or ``None``.
+
+            :param name: The image name to match.
+            :param aspects: Behaviour control for the call.
+
+            :returns: A :class:`NutanixImage` or ``None``.
+        """
+        for image in self.list(aspects=aspects):
+            if image.name == name:
+                rtnval: Optional[NutanixImage] = image
+                return rtnval
+        rtnval = None
+        return rtnval
+
+    def upload(self, *, spec: ImageSpec,
+               aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+               ) -> NutanixTaskHandle:
+        """
+            Upload (register) an image from an intent spec.
+
+            Read-before-create: when an image of the same name already
+            exists, an already-completed task handle wrapping its uuid is
+            returned.
+
+            :param spec: The :class:`ImageSpec` intent spec.
+            :param aspects: Behaviour control for the call.
+
+            :returns: A :class:`NutanixTaskHandle`.
+        """
+        existing = self.find_by_name(name=spec.name, aspects=aspects)
+        client = self.client
+        if existing is not None:
+            rtnval = client.completed_handle_for_entity(
+                entity_uuid=existing.uuid
+            )
+            return rtnval
+
+        payload = spec.to_payload()
+        rtnval = client.post_intent(entity="images", payload=payload,
+                                    action="upload image", aspects=aspects)
+        return rtnval
+
+    def delete(self, *, image_uuid: str,
+               aspects: AspectsNutanix = DEFAULT_NUTANIX_ASPECTS
+               ) -> None:
+        """
+            Delete an image by uuid; an unknown uuid is a no-op.
+
+            :param image_uuid: The image uuid.
+            :param aspects: Behaviour control for the call.
+
+            :returns: ``None``.
+        """
+        self.client.delete_intent(entity="images", entity_uuid=image_uuid,
+                                  action="delete image", aspects=aspects)
+        return