zosmfrestapi 0.2.0__py3-none-any.whl

zosmfrestapi/__init__.py

@@ -0,0 +1,93 @@
+"""Synchronous Python client for the z/OSMF REST API.
+
+The package root re-exports :class:`ZosmfClient`, :class:`ZosmfZcryptoClient`,
+response models, and public exceptions. Create one client per server/configuration and
+use it as a context manager to close the shared HTTP session when finished.
+"""
+
+from zosmfrestapi.client import ZosmfClient
+from zosmfrestapi.exceptions import ZosmfAuthError, ZosmfError
+from zosmfrestapi.exceptions.authentication import ZosmfLoginError
+from zosmfrestapi.exceptions.dataset import ZosmfDatasetNotFoundError
+from zosmfrestapi.exceptions.software import (
+    ZosmfSoftwareInstanceNotFoundError,
+    ZosmfSoftwareManagementError,
+    ZosmfSoftwareManagementRequestError,
+)
+from zosmfrestapi.exceptions.workflow import ZosmfWorkflowBaseError, ZosmfWorkflowError
+from zosmfrestapi.models.authentication import LoginOk
+from zosmfrestapi.models.software import (
+    CsiEntry,
+    DataSet,
+    Feature,
+    Fmid,
+    NonSmpeManagedDataset,
+    Product,
+    SmpeManagedDataset,
+    SmpeManagedDatasetZoneDddef,
+    SmpeManagedUnixDataset,
+    SoftwareInstance,
+    SoftwareInstanceWorkflow,
+    WorkflowLocation,
+)
+from zosmfrestapi.models.software_updates import (
+    MissingFixcat,
+    MissingUpdate,
+    MissingUpdateResolver,
+    SoftwareUpdate,
+    SoftwareUpdateZone,
+    UpdateErrorResults,
+    UpdateProcess,
+    UpdateResult,
+    UpdateSelection,
+)
+from zosmfrestapi.models.topology import Group, System
+from zosmfrestapi.models.workflow import (
+    WorkflowArchivedListItem,
+    WorkflowInstance,
+    WorkflowItem,
+    WorkflowListItem,
+)
+from zosmfrestapi.zcrypto_client import ZosmfZcryptoClient
+
+__all__ = [
+    "ZosmfClient",
+    "ZosmfZcryptoClient",
+    "LoginOk",
+    "ZosmfDatasetNotFoundError",
+    "ZosmfError",
+    "ZosmfAuthError",
+    "ZosmfLoginError",
+    "System",
+    "Group",
+    "CsiEntry",
+    "DataSet",
+    "Feature",
+    "Fmid",
+    "NonSmpeManagedDataset",
+    "Product",
+    "SmpeManagedDataset",
+    "SmpeManagedDatasetZoneDddef",
+    "SmpeManagedUnixDataset",
+    "SoftwareInstance",
+    "SoftwareInstanceWorkflow",
+    "WorkflowLocation",
+    "ZosmfSoftwareManagementError",
+    "ZosmfSoftwareInstanceNotFoundError",
+    "ZosmfSoftwareManagementRequestError",
+    "MissingFixcat",
+    "MissingUpdate",
+    "MissingUpdateResolver",
+    "SoftwareUpdate",
+    "SoftwareUpdateZone",
+    "UpdateErrorResults",
+    "UpdateProcess",
+    "UpdateResult",
+    "UpdateSelection",
+    "WorkflowArchivedListItem",
+    "WorkflowInstance",
+    "WorkflowItem",
+    "WorkflowListItem",
+    "ZosmfWorkflowBaseError",
+    "ZosmfWorkflowError",
+]

zosmfrestapi/client.py

@@ -0,0 +1,47 @@
+from zosmfrestapi.services.authentication import AuthenticationServices
+from zosmfrestapi.services.dataset import DatasetServices
+from zosmfrestapi.services.software import SoftwareServices
+from zosmfrestapi.services.software_updates import SoftwareUpdatesServices
+from zosmfrestapi.services.topology import TopologyServices
+from zosmfrestapi.services.workflow import WorkflowServices
+
+
+class ZosmfClient(
+    AuthenticationServices,
+    DatasetServices,
+    TopologyServices,
+    WorkflowServices,
+    SoftwareServices,
+    SoftwareUpdatesServices,
+):
+    """Synchronous client for the z/OSMF REST APIs.
+
+    The client combines authentication, datasets, topology, workflows,
+    software-instance management, and software-update operations around one
+    reusable HTTP session. Update-start and resume methods can change the
+    selected target zone; use them only when those changes are intended.
+
+    Use it as a context manager to close the underlying HTTP session reliably.
+
+    Examples:
+        Use a context manager when making requests:
+
+            with ZosmfClient("https://zosmf.example",
+                             username="demouser", password="DEMOPASS") as client:
+                systems = client.get_systems()
+
+        Use a client without using a context manager:
+
+            client = ZosmfClient("https://zosmf.example",
+                                 username="demouser", password="DEMOPASS")
+            systems = client.get_systems()
+            client.close()
+
+        Use a client with mTLS authentication:
+
+            with ZosmfClient("https://zosmf.example",
+                             username="demouser", password="DEMOPASS",
+                             cert=("/path/to/cert", "/path/to/key"),
+                             key_password="secret") as client:
+                systems = client.get_systems()
+    """

zosmfrestapi/exceptions/__init__.py

@@ -0,0 +1,18 @@
+import httpx2
+
+
+class ZosmfError(Exception):
+    """Base exception for errors raised by the z/OSMF REST API client."""
+
+    pass
+
+
+class ZosmfAuthError(ZosmfError):
+    """Raised when z/OSMF rejects a request with HTTP 401.
+
+    The triggering ``httpx2.HTTPStatusError`` is available as
+    :attr:`http_exception`.
+    """
+
+    def __init__(self, exc: httpx2.HTTPStatusError) -> None:
+        self.http_exception = exc

zosmfrestapi/exceptions/authentication.py

@@ -0,0 +1,17 @@
+import httpx2
+
+from . import ZosmfError
+
+
+class ZosmfLoginError(ZosmfError):
+    """Raised when the authentication endpoint rejects a login request.
+
+    The response's return code, reason code, and message are exposed as
+    ``return_code``, ``reason_code``, and ``message``.
+    """
+
+    def __init__(self, response: httpx2.Response) -> None:
+        self.http_exception = None
+        self.return_code = response.json()["returnCode"]
+        self.reason_code = response.json()["reasonCode"]
+        self.message = response.json()["message"]

zosmfrestapi/exceptions/dataset.py

@@ -0,0 +1,17 @@
+import logging
+
+import httpx2
+from zosmfrestapi.exceptions import ZosmfError
+
+logger = logging.getLogger(__name__)
+
+
+class ZosmfDatasetError(ZosmfError):
+    """Raised when a data set REST request fails with an HTTP status error."""
+
+
+class ZosmfDatasetNotFoundError(ZosmfDatasetError):
+    """Raised when z/OSMF reports that the requested data set is not found."""
+
+    def __init__(self, response: httpx2.Response) -> None:
+        pass

zosmfrestapi/exceptions/software.py

@@ -0,0 +1,34 @@
+from . import ZosmfError
+
+
+class ZosmfSoftwareManagementError(ZosmfError):
+    """Base exception for z/OSMF Software Management operations."""
+
+
+class ZosmfSoftwareManagementRequestError(ZosmfSoftwareManagementError):
+    """Raised when a Software Management request fails with an HTTP status.
+
+    When the response includes the corresponding fields, ``status_code``,
+    ``reason_code``, ``messages``, and ``body`` provide response details.
+    """
+
+    def __init__(self, error=None) -> None:
+        self.status_code = error.response.status_code if error else None
+        self.reason_code = error.response.json()["reason"] if error else None
+        self.messages = error.response.json()["messages"] if error else None
+        self.body = error.response.text if error else None
+
+
+class ZosmfSoftwareInstanceNotFoundError(ZosmfSoftwareManagementError):
+    """Raised when a requested software instance does not exist."""
+
+    def __init__(self, response) -> None:
+        super().__init__(response)
+        self.messages = (
+            response.json().get("messages", [])
+            if response.headers.get("Content-Type").startswith("application/json")
+            else [response.text]
+        )
+
+    def __str__(self) -> str:
+        return ", ".join(self.messages) if self.messages else ""

zosmfrestapi/exceptions/workflow.py

@@ -0,0 +1,30 @@
+import httpx2
+
+from . import ZosmfError
+
+
+class ZosmfWorkflowBaseError(ZosmfError):
+    """Base exception for z/OSMF workflow operations."""
+
+    pass
+
+
+class ZosmfWorkflowError(ZosmfWorkflowBaseError):
+    """Raised when a workflow REST request fails with an HTTP status.
+
+    When present in the response, ``status_code``, ``message_id``, ``message``,
+    and ``body`` expose the z/OSMF error details.
+    """
+
+    def __init__(self, error: httpx2.HTTPStatusError | None = None) -> None:
+        self.exc = error
+        self.status_code = error.response.status_code if error else None
+        self.message_id = error.response.json()["messageID"] if error else None
+        self.message = error.response.json()["messageText"] if error else None
+        self.body = error.response.text if error else None
+
+
+class ZosmfWorkflowCanceledError(ZosmfWorkflowBaseError):
+    """Reserved for workflow-specific cancellation failures."""
+
+    pass

zosmfrestapi/models/authentication.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class LoginOk:
+    """Successful response from the z/OSMF authentication endpoint.
+
+    The endpoint return fields are preserved alongside any LTPA or JWT token
+    cookies returned by the server.
+    """
+
+    returnCode: int
+    reasonCode: int
+    message: str
+    ltpa_token: str | None = None
+    jwt_token: str | None = None

zosmfrestapi/models/software.py

@@ -0,0 +1,231 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+import pendulum
+
+
+@dataclass
+class DataSet:
+    """Reference to a data set and, optionally, the volume that contains it."""
+
+    dsname: str | None = None
+    volume: str | None = None
+
+
+@dataclass
+class SmpeManagedDatasetZoneDddef:
+    """DDDEF names associated with an SMP/E zone."""
+
+    zone: str | None = None
+    dddefs: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SmpeManagedDataset:
+    """Inventory details for an SMP/E-managed MVS data set."""
+
+    dsname: str | None = None
+    volumes: list[str] | None = field(default_factory=list)
+    dstype: str | None = None
+    recfm: str | None = None
+    lrecl: str | None = None
+    blksize: str | None = None
+    tracks: str | None = None
+    used: str | None = None
+    extents: str | None = None
+    dscategory: list[str] = field(default_factory=list)
+    zones: list[str] = field(default_factory=list)
+    zonedddefs: list[SmpeManagedDatasetZoneDddef] | None = field(default_factory=list)
+    msgs: Any = None
+
+
+@dataclass
+class SmpeManagedUnixDataset:
+    """Inventory details for an SMP/E-managed UNIX file-system data set."""
+
+    dsname: str | None = None
+    unixdirs: list[str] | None = field(default_factory=list)
+    volumes: list[str] | None = field(default_factory=list)
+    dstype: str | None = None
+    recfm: str | None = None
+    lrecl: str | None = None
+    blksize: str | None = None
+    tracks: str | None = None
+    used: str | None = None
+    extents: str | None = None
+    dscategory: list[str] | None = field(default_factory=list)
+    zones: list[str] | None = field(default_factory=list)
+    zonedddefs: list[SmpeManagedDatasetZoneDddef] | None = field(default_factory=list)
+    msgs: list[str] | None = field(default_factory=list)
+
+
+@dataclass
+class NonSmpeManagedDataset:
+    """Inventory details for a data set not managed by SMP/E."""
+
+    dsname: str | None = None
+    volumes: list[str] | None = field(default_factory=list)
+    dstype: str | None = None
+    recfm: str | None = None
+    lrecl: str | None = None
+    blksize: str | None = None
+    tracks: str | None = None
+    used: str | None = None
+    extents: str | None = None
+    dscategory: list[str] | None = field(default_factory=list)
+    unixdirs: list[str] | None = field(default_factory=list)
+    msgs: list[str] | None = field(default_factory=list)
+
+
+@dataclass
+class CsiSubEntry:
+    """Arbitrary values returned for one CSI subentry."""
+
+    values: dict[str, Any]
+
+
+@dataclass
+class CsiEntry:
+    """CSI entry identity and its returned subentry values."""
+
+    entryname: str | None = None
+    entrytype: str | None = None
+    zonename: str | None = None
+    subentries: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class Fmid:
+    """Function modification identifier and its description/target zones."""
+
+    fmid: str | None = None
+    description: str | None = None
+    targetzones: list[str] | None = field(default_factory=list)
+
+
+@dataclass
+class Feature:
+    """Software product feature and the FMIDs that implement it."""
+
+    feature: str | None = None
+    fmids: list[Fmid] = field(default_factory=list)
+
+
+@dataclass
+class Product:
+    """SMP/E-managed product metadata and service lifecycle dates."""
+
+    prodname: str | None = None
+    productid: str | None = None
+    release: str | None = None
+    vendor: str | None = None
+    generalavailability: pendulum.DateTime | None = None
+    endofservice: pendulum.DateTime | None = None
+    url: str | None = None
+    productinfofileversion: str | None = None
+    features: list[Feature] = field(default_factory=list)
+
+
+@dataclass
+class NonSmpeProduct:
+    """Product metadata for a product not managed by SMP/E."""
+
+    prodname: str | None = None
+    productid: str | None = None
+    release: str | None = None
+    vendor: str | None = None
+    url: str | None = None
+    features: list[str] = field(default_factory=list)
+    generalavailability: pendulum.DateTime | None = None
+    endofservice: pendulum.DateTime | None = None
+
+
+@dataclass
+class WorkflowLocation:
+    """Location details for a workflow associated with a software instance."""
+
+    smptype: str | None = None
+    smpname: str | None = None
+    dsname: str | None = None
+    path: str | None = None
+
+
+@dataclass
+class SoftwareInstanceWorkflow:
+    """Workflow definition associated with a software instance."""
+
+    name: str | None = None
+    description: str | None = None
+    location: WorkflowLocation = field(default_factory=WorkflowLocation)
+    performonhostsystem: bool | None = None
+
+
+@dataclass
+class DataSetProperty:
+    """Property values for a data set DDDEF in a software instance."""
+
+    dddefname: str | None = None
+    zone: str | None = None
+    dsname: str | None = None
+    volume: str | None = None
+    dstype: str | None = None
+    properties: list[dict[str, str]] = field(default_factory=list)
+
+
+@dataclass
+class DataSetPropertyLabel:
+    """Display label associated with a data set property name."""
+
+    propertyname: str | None = None
+    label: str | None = None
+
+
+@dataclass
+class ProductProperty:
+    """Property values associated with a product and release."""
+
+    prodid: str | None = None
+    release: str | None = None
+    prodname: str | None = None
+    properties: list[dict[str, str]] = field(default_factory=list)
+
+
+@dataclass
+class SoftwareInstance:
+    """A z/OSMF software instance and its associated inventory.
+
+    Construction requires either a global zone with at least one target zone,
+    or data-set references when no global zone is configured.
+
+    Raises:
+        ValueError: If neither a global zone nor data sets are provided, or if
+            a global zone is provided without target zones.
+    """
+
+    name: str
+    system: str
+    description: str | None = ""
+    uuid: str | None = field(default="", metadata={"json_name": "swiuuid"})
+    globalzone: str | None = None
+    targetzones: list[str] = field(default_factory=list)
+    categories: list[str] = field(default_factory=list)
+    productinforetrieved: pendulum.DateTime | None = None
+    lastmodified: pendulum.DateTime | None = None
+    modifiedby: str | None = None
+    created: pendulum.DateTime | None = None
+    createdby: str | None = None
+    locked: pendulum.DateTime | None = None
+    lockedby: str | None = None
+    datasets: list[DataSet] = field(default_factory=list)
+    products: list[Product] = field(default_factory=list)
+    nonsmpeproducts: list[NonSmpeProduct] = field(default_factory=list)
+    workflows: list[SoftwareInstanceWorkflow] = field(default_factory=list)
+    datasetproperties: list[DataSetProperty] = field(default_factory=list)
+    datasetpropertylabels: list[DataSetPropertyLabel] = field(default_factory=list)
+    productproperties: list[ProductProperty] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.globalzone and not self.datasets:
+            raise ValueError("Either globalzone or datasets must be specified")
+        elif self.globalzone and not self.targetzones:
+            raise ValueError("Target zones must be specified when globalzone is set")

zosmfrestapi/models/software_updates.py

@@ -0,0 +1,99 @@
+from dataclasses import dataclass, field
+
+import pendulum
+
+
+@dataclass
+class UpdateSelection:
+    """SYSMOD updates selected for a software-update process."""
+
+    updates: list[str] = field(default_factory=list)
+
+
+@dataclass
+class UpdateResult:
+    """Selection and application result for one update in a process."""
+
+    fmid: str | None = None
+    selectStatus: str | None = field(default=None)
+    name: str | None = None
+
+
+@dataclass
+class UpdateErrorResults:
+    """SMP/E return code and messages associated with a failed update."""
+
+    smpe_rc: int
+    message: str
+    detailedMessage: str
+
+
+@dataclass
+class UpdateProcess:
+    """Status, selection, timing, and results for a software-update process."""
+
+    targetzone: str
+    selection: UpdateSelection
+    notes: str
+    processid: int
+    started: pendulum.DateTime
+    status: str
+    step: str
+    lastmodified: pendulum.DateTime | None = None
+    completed: pendulum.DateTime | None = None
+    error_results: UpdateErrorResults | None = None
+    updates: list[UpdateResult] = field(default_factory=list)
+    holds: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SoftwareUpdateZone:
+    """Installation status of a software update in one zone."""
+
+    zone: str
+    status: str
+    installed: pendulum.DateTime | None
+
+
+@dataclass
+class SoftwareUpdate:
+    """Software-update metadata and its status across zones."""
+
+    name: str | None = None
+    type: str | None = None
+    fmid: str | None = None
+    zones: list[SoftwareUpdateZone] = field(default_factory=list)
+
+
+@dataclass
+class MissingUpdateResolver:
+    """Update that can resolve a hold on a missing update."""
+
+    name: str | None = None
+    received: bool | None = None
+
+
+@dataclass
+class MissingUpdate:
+    """Critical missing update, its hold details, and resolving updates."""
+
+    name: str | None = None
+    holdclass: str | None = None
+    holdsymptom: str | None = None
+    heldsysmod: str | None = None
+    fmid: str | None = None
+    fmiddesc: str | None = None
+    resolvers: list[MissingUpdateResolver] | None = field(default_factory=list)
+    tgtzones: list[str] = field(default_factory=list)
+
+
+@dataclass
+class MissingFixcat:
+    """Fix category missing from an instance and its resolving updates."""
+
+    name: str | None = None
+    fixcats: list[str] = field(default_factory=list)
+    fmid: str | None = None
+    fmiddesc: str | None = None
+    resolvers: list[MissingUpdateResolver] | None = field(default_factory=list)
+    tgtzones: list[str] = field(default_factory=list)

zosmfrestapi/models/topology.py

@@ -0,0 +1,28 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class System:
+    """System record returned by the z/OSMF topology API."""
+
+    name: str = field(metadata={"json_name": "systemName"})
+    nickName: str = field(metadata={"json_name": "systemNickName"})
+    sysplex: str = field(metadata={"json_name": "sysplexName"})
+    groups: str = field(default="", metadata={"json_name": "groupNames"})
+    cpcSerial: str = ""
+    zosVR: str = ""
+    jesType: str = ""
+    jesMemberName: str = ""
+    httpProxyName: str = ""
+    ftpDestinationName: str = ""
+    url: str = ""
+    cpcName: str = ""
+
+
+@dataclass
+class Group:
+    """Group record and the system nicknames that belong to it."""
+
+    name: str
+    systems: str = field(metadata={"json_name": "systemNickNames"})
+    description: str = ""