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

ccai/restclient/vsphere/__init__.py

@@ -0,0 +1,3 @@
+"""
+    Package marker for ``ccai.restclient.vsphere``.
+"""

ccai/restclient/vsphere/apigroups/__init__.py

@@ -0,0 +1,7 @@
+"""
+    Package marker for ``ccai.restclient.vsphere.apigroups``.
+
+    Each ``*Group`` module owns its own class.  This package init does
+    not eagerly import the groups; importing happens lazily through
+    :meth:`VSphereClient.__getattr__` so the package is cheap to load.
+"""

ccai/restclient/vsphere/apigroups/basegroup.py

@@ -0,0 +1,139 @@
+"""
+    .. module:: basegroup
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Shared base class for every vSphere ``*Group`` API
+        surface.  Adds filter-state-aware URL composition on top of the
+        generic :class:`RestApiGroup`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from typing import TYPE_CHECKING
+
+from ccai.errors.exceptions import SemanticError
+from ccai.restclient.base.restapigroup import RestApiGroup
+
+
+if TYPE_CHECKING:
+    from ccai.restclient.vsphere.vsphereclient import VSphereClient
+
+
+_API_PREFIX = "/api/"
+_REST_PREFIX = "/rest/"
+
+
+class BaseGroup(RestApiGroup):
+    """
+        Common ancestor for every vSphere API group.
+
+        Subclasses MUST set :data:`BASE_LEAF` to a value that begins
+        with either ``/api/`` or ``/rest/`` so the client knows which
+        root to compose against.  The prefix is validated at subclass
+        registration time (``__init_subclass__``) so misconfiguration
+        fails fast.
+    """
+
+    BASE_LEAF: str = ""
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        """
+            Validate ``BASE_LEAF`` of subclasses at class-definition
+            time.
+
+            :returns: ``None``
+
+            :raises: SemanticError
+        """
+        super().__init_subclass__(**kwargs)
+        # An empty BASE_LEAF is permitted only on the base class itself
+        # which is the class statically declared in this module.
+        if cls is BaseGroup:
+            return None
+
+        base = cls.BASE_LEAF
+        if base is None or len(base) == 0:
+            err_msg_lines = [
+                "API group must declare a non-empty BASE_LEAF.",
+                "CLASS: {}".format(cls.__name__),
+            ]
+            err_msg = os.linesep.join(err_msg_lines)
+            raise SemanticError(err_msg)
+
+        if not (base.startswith(_API_PREFIX) or base.startswith(_REST_PREFIX)):
+            err_msg_lines = [
+                "API group BASE_LEAF must begin with '/api/' or '/rest/'.",
+                "CLASS: {}".format(cls.__name__),
+                "GOT: {!r}".format(base),
+            ]
+            err_msg = os.linesep.join(err_msg_lines)
+            raise SemanticError(err_msg)
+
+        return None
+
+    def __init__(self, client: "VSphereClient") -> None:
+        """
+            Initialise the group with a back-reference to the client.
+
+            :param client: Owning :class:`VSphereClient` instance.
+
+            :returns: ``None``
+        """
+        super().__init__(client)
+        return
+
+    # ------------------------------------------------------------------
+    # URL composition wrapped over RestApiGroup.build_leaf
+    # ------------------------------------------------------------------
+
+    def compose_url(self, *, parts=None, params=None) -> str:
+        """
+            Compose an absolute URL by joining BASE_LEAF with any
+            additional path parts.
+
+            Query parameters are not embedded into the returned URL;
+            they are emitted via the `params=` argument to requests in
+            sorted-key order.  The sort key ordering invariant is
+            enforced at the call site (e.g. the ``params`` dict passed
+            to ``session.get``) so the property-test suite need not
+            inspect raw URLs.
+
+            :param parts: Optional list of additional path segments
+                to append after BASE_LEAF.
+            :param params: Optional dict of query parameters (forwarded
+                to callers; not embedded into the URL string here).
+
+            :returns: The absolute URL composed against the client.
+        """
+        _ = params
+        client = self.client
+        if parts is None or len(parts) == 0:
+            leaf = self.BASE_LEAF
+        else:
+            leaf = self.build_leaf(parts=parts)
+            if not leaf.startswith("/"):
+                leaf = "/" + leaf
+
+        rtnval = client.build_url(leaf=leaf)
+        return rtnval
+
+    def sort_params(self, *, params) -> dict:
+        """
+            Return the params dict re-keyed alphabetically.
+
+            :param params: Raw params dict (may be ``None``).
+
+            :returns: A new dict with keys in sorted order.
+        """
+        rtnval = {}
+        if params is None:
+            return rtnval
+        for key in sorted(params.keys()):
+            rtnval[key] = params[key]
+        return rtnval

ccai/restclient/vsphere/apigroups/certificatemanagementgroup.py

@@ -0,0 +1,29 @@
+"""
+    .. module:: certificatemanagementgroup
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Certificate management API group for :class:`VSphereClient`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.restclient.vsphere.apigroups.basegroup import BaseGroup
+
+
+class CertificateManagementGroup(BaseGroup):
+    """
+        Certificate management operations.
+
+        The legacy ``*Ext`` class in ``codecraftai-landscaping`` did not
+        expose any public methods on this group; the structural
+        migration is complete and feature methods will be added by
+        downstream specs as needed (see ``vsphere-content-library-deploy``,
+        ``vsphere-events-stream``, ``vsphere-linked-mode``,
+        ``vsphere-inventory-helpers`` for the planned additions).
+    """
+
+    BASE_LEAF = "/api/vcenter/certificate-management"

ccai/restclient/vsphere/apigroups/clustergroup.py

@@ -0,0 +1,29 @@
+"""
+    .. module:: clustergroup
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Cluster API group for :class:`VSphereClient`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.restclient.vsphere.apigroups.basegroup import BaseGroup
+
+
+class ClusterGroup(BaseGroup):
+    """
+        Cluster operations.
+
+        The legacy ``*Ext`` class in ``codecraftai-landscaping`` did not
+        expose any public methods on this group; the structural
+        migration is complete and feature methods will be added by
+        downstream specs as needed (see ``vsphere-content-library-deploy``,
+        ``vsphere-events-stream``, ``vsphere-linked-mode``,
+        ``vsphere-inventory-helpers`` for the planned additions).
+    """
+
+    BASE_LEAF = "/api/vcenter/cluster"

ccai/restclient/vsphere/apigroups/computegroup.py

@@ -0,0 +1,29 @@
+"""
+    .. module:: computegroup
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Compute resources API group for :class:`VSphereClient`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.restclient.vsphere.apigroups.basegroup import BaseGroup
+
+
+class ComputeGroup(BaseGroup):
+    """
+        Compute resources operations.
+
+        The legacy ``*Ext`` class in ``codecraftai-landscaping`` did not
+        expose any public methods on this group; the structural
+        migration is complete and feature methods will be added by
+        downstream specs as needed (see ``vsphere-content-library-deploy``,
+        ``vsphere-events-stream``, ``vsphere-linked-mode``,
+        ``vsphere-inventory-helpers`` for the planned additions).
+    """
+
+    BASE_LEAF = "/api/vcenter/compute"

ccai/restclient/vsphere/apigroups/contentgroup.py

@@ -0,0 +1,270 @@
+"""
+    .. module:: contentgroup
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Content library API group for :class:`VSphereClient`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from http import HTTPStatus
+
+from typing import List, Optional
+
+from ccai.errors.raising import raise_for_http_status
+
+from ccai.restclient.vsphere.apigroups.basegroup import BaseGroup
+from ccai.restclient.vsphere.apigroups.inventoryerrors import (
+    VSphereAmbiguousResolutionError,
+    VSphereResourceNotFoundError,
+)
+from ccai.restclient.vsphere.aspectsvsphere import (
+    AspectsVSphere,
+    DEFAULT_VSPHERE_ASPECTS,
+)
+from ccai.restclient.vsphere.model.library import LibraryItemSummary
+from ccai.restclient.vsphere.specs.contentdeploy import ContentDeploySpec
+from ccai.restclient.vsphere.specs.vmplacement import VmPlacementSpec
+from ccai.restclient.vsphere.vspheretaskhandle import VSphereTaskHandle
+
+
+class ContentGroup(BaseGroup):
+    """
+        Content library operations (``/api/content/...``).
+
+        The legacy ``ContentExt`` did not expose public methods; this
+        class adds ``list_items``, ``find_item``, and ``deploy_ovf_item``
+        per the ``vsphere-content-library-deploy`` spec.
+    """
+
+    BASE_LEAF = "/api/content"
+
+    LIBRARY_LEAF = "/api/content/library"
+    LIBRARY_ITEM_LEAF = "/api/content/library/item"
+    LIBRARY_ITEM_DEPLOY_LEAF = "/api/vcenter/ovf/library-item"
+
+    def list_items(
+        self,
+        *,
+        library_id: str,
+        tag: Optional[str] = None,
+        aspects: AspectsVSphere = DEFAULT_VSPHERE_ASPECTS,
+    ) -> List[LibraryItemSummary]:
+        """
+            Enumerate items in a content library.
+
+            Tag filtering is performed client-side against the ``tags``
+            field on the returned summaries so the helper is uniform
+            regardless of whether the underlying endpoint supports
+            server-side tag filtering.
+
+            :param library_id: Content-library identifier.
+            :param tag: Optional tag filter.
+            :param aspects: Behaviour controls.
+
+            :returns: List of :class:`LibraryItemSummary`.
+
+            :raises: VSphereResourceNotFoundError
+        """
+        client = self.client
+        url = client.build_url(leaf=self.LIBRARY_ITEM_LEAF)
+        session = client.ensure_session(aspects=aspects)
+        params = {"library_id": library_id}
+        resp = session.get(url, params=params, timeout=aspects.completion_timeout)
+
+        if resp.status_code == HTTPStatus.NOT_FOUND:
+            err_msg_lines = [
+                "Content library not found.",
+                "LIBRARY_ID: {}".format(library_id),
+            ]
+            err_msg = os.linesep.join(err_msg_lines)
+            raise VSphereResourceNotFoundError(err_msg)
+        if resp.status_code != HTTPStatus.OK:
+            raise_for_http_status(
+                resp.status_code, resp.content, url, context="ContentGroup.list_items",
+            )
+
+        body = resp.json()
+        parsed: List[LibraryItemSummary] = []
+        for raw in body:
+            if isinstance(raw, str):
+                # Endpoint variant returns bare item-ids; promote each
+                # to a minimal summary so the surface stays uniform.
+                parsed.append(LibraryItemSummary(
+                    item_id=raw, library_id=library_id, name=raw,
+                ))
+                continue
+            normalised = dict(raw)
+            if "item_id" not in normalised:
+                if "id" in normalised:
+                    normalised["item_id"] = normalised.pop("id")
+            if "library_id" not in normalised:
+                normalised["library_id"] = library_id
+            parsed.append(LibraryItemSummary.from_dict(normalised))
+
+        if tag is None:
+            rtnval = parsed
+            return rtnval
+
+        filtered: List[LibraryItemSummary] = []
+        for item in parsed:
+            tags = getattr(item, "tags", None)
+            if tags is None:
+                continue
+            if tag in tags:
+                filtered.append(item)
+        rtnval = filtered
+        return rtnval
+
+    def find_item(
+        self,
+        *,
+        name: str,
+        tag: Optional[str] = None,
+        library_id: Optional[str] = None,
+        all_library_ids: Optional[List[str]] = None,
+        aspects: AspectsVSphere = DEFAULT_VSPHERE_ASPECTS,
+    ) -> LibraryItemSummary:
+        """
+            Resolve a friendly name (and optional tag) to a single
+            :class:`LibraryItemSummary`.
+
+            When ``library_id`` is omitted, ``all_library_ids`` is used
+            as the search scope.  The latter is named-only and explicit
+            so callers cannot accidentally trigger a full-tenancy enum
+            without acknowledging it.
+
+            :param name: Item display name.
+            :param tag: Optional tag the item must also carry.
+            :param library_id: Optional single-library scope.
+            :param all_library_ids: Optional multi-library scope.
+            :param aspects: Behaviour controls.
+
+            :returns: A single :class:`LibraryItemSummary`.
+
+            :raises: VSphereResourceNotFoundError,
+                VSphereAmbiguousResolutionError
+        """
+        scope: List[str] = []
+        if library_id is not None:
+            scope.append(library_id)
+        elif all_library_ids is not None:
+            scope.extend(all_library_ids)
+        else:
+            err_msg_lines = [
+                "ContentGroup.find_item requires either library_id or",
+                "all_library_ids to define the search scope.",
+            ]
+            err_msg = os.linesep.join(err_msg_lines)
+            raise VSphereResourceNotFoundError(err_msg)
+
+        candidates: List[LibraryItemSummary] = []
+        for lib_id in scope:
+            for item in self.list_items(library_id=lib_id, tag=tag, aspects=aspects):
+                if getattr(item, "name", None) == name:
+                    candidates.append(item)
+
+        if len(candidates) == 0:
+            err_msg_lines = [
+                "No content-library item matched the requested name.",
+                "NAME: {}".format(name),
+                "TAG: {}".format(tag),
+                "SCOPE: {}".format(scope),
+            ]
+            err_msg = os.linesep.join(err_msg_lines)
+            raise VSphereResourceNotFoundError(err_msg)
+
+        if len(candidates) > 1:
+            err_msg_lines = [
+                "Multiple content-library items matched the requested name.",
+                "NAME: {}".format(name),
+                "COUNT: {}".format(len(candidates)),
+            ]
+            for cand in candidates:
+                err_msg_lines.append(
+                    "    {}: {}".format(cand.item_id, cand.library_id),
+                )
+            err_msg = os.linesep.join(err_msg_lines)
+            raise VSphereAmbiguousResolutionError(err_msg, candidates=candidates)
+
+        rtnval = candidates[0]
+        return rtnval
+
+    def deploy_ovf_item(
+        self,
+        *,
+        item_id: str,
+        target: VmPlacementSpec,
+        deploy_spec: ContentDeploySpec,
+        aspects: AspectsVSphere = DEFAULT_VSPHERE_ASPECTS,
+    ) -> VSphereTaskHandle:
+        """
+            Deploy an OVF library item into the requested placement.
+
+            :param item_id: Library item identifier.
+            :param target: :class:`VmPlacementSpec`.
+            :param deploy_spec: :class:`ContentDeploySpec`.
+            :param aspects: Behaviour controls.
+
+            :returns: A :class:`VSphereTaskHandle` for the deployment.
+        """
+        client = self.client
+        leaf = "{}/{}?action=deploy".format(self.LIBRARY_ITEM_DEPLOY_LEAF, item_id)
+        url = client.build_url(leaf=leaf)
+
+        deployment_target = target.to_dict()
+        deployment_spec = deploy_spec.to_dict()
+        body = {
+            "target": deployment_target,
+            "deployment_spec": deployment_spec,
+        }
+
+        session = client.ensure_session(aspects=aspects)
+        resp = session.post(url, json=body, timeout=aspects.completion_timeout)
+        if resp.status_code not in (HTTPStatus.OK, HTTPStatus.ACCEPTED, HTTPStatus.CREATED):
+            raise_for_http_status(
+                resp.status_code, resp.content, url,
+                context="ContentGroup.deploy_ovf_item",
+            )
+        try:
+            response_body = resp.json()
+        except ValueError:
+            response_body = {}
+        task_id = _extract_task_id(payload=response_body)
+        rtnval = VSphereTaskHandle(task_id=task_id, client=client)
+        return rtnval
+
+
+def _extract_task_id(*, payload) -> str:
+    """
+        Extract a task id from a vCenter response payload.
+
+        :param payload: Decoded JSON body (str or dict).
+
+        :returns: The task identifier string.
+    """
+    if isinstance(payload, str):
+        rtnval = payload
+        return rtnval
+    if isinstance(payload, dict):
+        if "task" in payload:
+            candidate = payload["task"]
+            if isinstance(candidate, str):
+                rtnval = candidate
+                return rtnval
+        if "value" in payload:
+            candidate = payload["value"]
+            if isinstance(candidate, str):
+                rtnval = candidate
+                return rtnval
+        if "succeeded" in payload and isinstance(payload.get("resource_id"), str):
+            rtnval = payload["resource_id"]
+            return rtnval
+    rtnval = "" if payload is None else str(payload)
+    return rtnval

ccai/restclient/vsphere/apigroups/cryptomanagergroup.py

@@ -0,0 +1,29 @@
+"""
+    .. module:: cryptomanagergroup
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Crypto manager API group for :class:`VSphereClient`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.restclient.vsphere.apigroups.basegroup import BaseGroup
+
+
+class CryptoManagerGroup(BaseGroup):
+    """
+        Crypto manager operations.
+
+        The legacy ``*Ext`` class in ``codecraftai-landscaping`` did not
+        expose any public methods on this group; the structural
+        migration is complete and feature methods will be added by
+        downstream specs as needed (see ``vsphere-content-library-deploy``,
+        ``vsphere-events-stream``, ``vsphere-linked-mode``,
+        ``vsphere-inventory-helpers`` for the planned additions).
+    """
+
+    BASE_LEAF = "/api/vcenter/crypto-manager"