zosmfrestapi 0.2.0__py3-none-any.whl

zosmfrestapi/models/workflow.py

@@ -0,0 +1,114 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class WorkflowAutomationStatus:
+    """Automation progress and current-step details for a workflow."""
+
+    startUser: str | None = None
+    startedTime: int | str | None = None
+    stoppedTime: int | str | None = None
+    currentStepName: str | None = None
+    currentStepNumber: str | None = None
+    currentStepTitle: str | None = None
+    messageID: str | None = None
+    messageText: str | None = None
+
+
+@dataclass
+class WorkflowInstance:
+    """Current state and optional detailed data for a workflow instance."""
+
+    name: str = field(metadata={"json_name": "workflowName"})
+    owner: str
+    system: str
+    scope: str = ""
+    percentComplete: int | None = None
+    workflowDefinitionFileMD5Value: str | None = None
+    workflowArchiveSAFID: str | None = None
+    jobStatement: str | list[str] | None = None
+    globalVariableGroup: str | None = None
+    jobsOutputDirectory: str | None = None
+    status: str | None = field(default="", metadata={"json_name": "statusName"})
+    vendor: str | None = None
+    deleteCompletedJobs: bool | None = None
+    autoDeleteOnCompletion: bool | None = None
+    isInstanceVariableWithoutPrefix: bool | None = None
+    workflowVersion: str | None = None
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    access: str | None = None
+    productVersion: str | None = None
+    productID: str | None = None
+    variables: list[dict[str, Any]] = field(default_factory=list)
+    category: str | None = None
+    workflowDescription: str | None = None
+    workflowID: str | None = None
+    accountInfo: str | None = None
+    automationStatus: WorkflowAutomationStatus | None = None
+    containsParallelSteps: bool | None = None
+    isCallable: bool | None = None
+    workflowKey: str | None = None
+    productName: str | None = None
+
+
+@dataclass
+class WorkflowListItem:
+    """Summary record returned when listing active workflow instances."""
+
+    instanceURI: str | None = None
+    owner: str | None = None
+    vendor: str | None = None
+    workflowDefinitionFileMD5Value: str | None = None
+    workflowDescription: str | None = None
+    workflowID: str | None = None
+    workflowKey: str | None = None
+    workflowName: str | None = None
+    workflowVersion: str | None = None
+
+
+@dataclass
+class WorkflowArchivedListItem:
+    """Summary record returned when listing archived workflow instances."""
+
+    archivedInstanceURI: str | None = None
+    workflowKey: str | None = None
+    workflowName: str | None = None
+
+
+@dataclass
+class WorkflowVariableItem:
+    """Name and value of a workflow input variable."""
+
+    name: str | None = None
+    value: str | None = None
+
+
+@dataclass
+class WorkflowItem:
+    """Request data used to create a z/OSMF workflow instance."""
+
+    name: str = field(metadata={"json_name": "workflowName"})
+    definition: str = field(metadata={"json_name": "workflowDefinitionFile"})
+    system: str
+    owner: str
+    system_definition: str | None = field(
+        default=None,
+        metadata={
+            "json_name": "workflowDefinitionFileSystem",
+        },
+    )
+    variableInputFile: str | None = None
+    variables: list[WorkflowVariableItem] = field(default_factory=list)
+    resolveGlobalConflictByUsing: str | None = None
+    workflowArchiveSAFID: str | None = None
+    comments: str | None = None
+    assignToOwner: bool | None = None
+    accessType: str | None = None
+    accountInfo: str | None = None
+    jobStatement: str | list[str] | None = None
+    deleteCompletedJobs: bool | None = None
+    autoDeleteOnCompletion: bool | None = None
+    jobsOutputDirectory: str | None = None
+    targetSystemuid: str | None = None
+    targetSystempwd: str | None = field(default=None, repr=False)

zosmfrestapi/services/__init__.py

@@ -0,0 +1,176 @@
+import logging
+import ssl
+from types import TracebackType
+from typing import Literal, Self
+
+import httpx2
+from zosmfrestapi.exceptions import ZosmfAuthError, ZosmfError
+
+logger = logging.getLogger(__name__)
+
+
+class ZosmfBase:
+    """Shared HTTP client and request handling for the service mixins.
+
+    :class:`ZosmfClient` inherits the operations provided by the service mixins;
+    this base class configures their shared ``httpx2.Client`` and manages its
+    lifetime. Use a client as a context manager when possible so the connection
+    pool is closed deterministically.
+    """
+
+    def __init__(
+        self,
+        server: str,
+        username: str | None = None,
+        password: str | None = None,
+        cert: str | tuple[str, str] | None = None,
+        key_password: str | None = None,
+        ltpa_token: str | None = None,
+        jwt_token: str | None = None,
+        jwt_cookie_name: str = "jwtToken",
+        proxy: str | None = None,
+        proxyusername: str = "",
+        proxypassword: str = "",
+        insecure: bool = False,
+        cafile: None | str = None,
+        encoding: str | None = None,
+    ) -> None:
+        """Create an HTTP client for communicating with z/OSMF.
+
+        Args:
+            server: Base URL of the z/OSMF server, including its scheme and
+                optional port or base path.
+            username: Optional user ID for HTTP basic authentication. Basic
+                authentication is configured only when both ``username`` and
+                ``password`` are non-empty.
+            password: Password paired with ``username`` for basic
+                authentication.
+            cert: Optional client certificate configuration. Pass a path to a
+                PEM file containing both the certificate and private key, or
+                a ``(certificate_path, private_key_path)`` tuple for separate
+                files.
+            key_password: Optional private key password. Pass the private key
+                password if the key is password protected.
+            ltpa_token: Optional LTPA token sent as the ``LtpaToken2`` cookie.
+            jwt_token: Optional JWT sent as the cookie named by
+                ``jwt_cookie_name``. If both token types are provided, both
+                cookies are sent.
+            jwt_cookie_name: Cookie name used for ``jwt_token``. Defaults to
+                ``"jwtToken"``.
+            proxy: Optional proxy URL used for HTTP requests.
+            proxyusername: Optional proxy user ID. Used with
+                ``proxypassword`` when proxy authentication is configured.
+            proxypassword: Optional proxy password.
+            insecure: Disable TLS certificate verification when true. This
+                cannot be combined with ``cert`` or ``cafile``.
+            cafile: Optional CA certificate file added to the default trust
+                store. It can be combined with ``cert``.
+            encoding: Reserved compatibility parameter; currently unused.
+
+        Raises:
+            ZosmfError: If ``insecure`` is combined with ``cert`` or ``cafile``.
+        """
+        if insecure and (cafile or cert):
+            raise ZosmfError("Cannot set insecure mode when cafile or cert is provided.")
+
+        verify: bool | ssl.SSLContext
+        if insecure:
+            logger.debug("Insecure mode enabled, TLS certificate verification is disabled.")
+            verify = False
+        else:
+            ctx = ssl.create_default_context()
+            if isinstance(cert, tuple):
+                certfile, keyfile = cert
+                ctx.load_cert_chain(certfile=certfile, keyfile=keyfile, password=key_password)
+            elif cert:
+                ctx.load_cert_chain(certfile=cert)
+            if cafile:
+                ctx.load_verify_locations(cafile=cafile)
+            verify = ctx  # <------ linea 88
+
+        proxy_config: str | httpx2.Proxy | None = proxy
+        if proxy:
+            proxy_config = httpx2.Proxy(proxy)
+            proxy_config.auth = (
+                (proxyusername, proxypassword) if proxyusername or proxypassword else None
+            )
+        auth = (username, password) if username and password else None
+        headers = {}
+        if ltpa_token:
+            headers = {"Cookie": f"LtpaToken2={ltpa_token}"}
+        if jwt_token:
+            headers = {"Cookie": f"{jwt_cookie_name}={jwt_token}"}
+        if ltpa_token and jwt_token:
+            headers = {"Cookie": f"LtpaToken2={ltpa_token}; {jwt_cookie_name}={jwt_token}"}
+        self.http = httpx2.Client(
+            base_url=server,
+            proxy=proxy_config,
+            verify=verify,
+            auth=auth,
+            headers=headers,
+        )
+
+        self.base_url = server
+        self.username = username
+        self.password = password
+        self.insecure = insecure
+        self.cert = cert
+        self.cafile = cafile
+        self.ltpa_token = ltpa_token
+        self.jwt_token = jwt_token
+        self.jwt_cookie_name = jwt_cookie_name
+        self.proxy = proxy_config
+        self.proxyusername = proxyusername
+        self.proxypassword = proxypassword
+
+    def _raise_for_status(
+        self,
+        response: httpx2.Response,
+        exc_handler: type[ZosmfError] = ZosmfError,
+    ) -> None:
+        """Raise a package exception for an unsuccessful HTTP response.
+
+        HTTP 401 responses are translated to :class:`ZosmfAuthError`; other
+        HTTP status errors are wrapped using ``exc_handler``.
+
+        Args:
+            response: Response returned by the shared HTTP client.
+            exc_handler: Exception class used for non-authentication status
+                errors. Defaults to :class:`ZosmfError`.
+
+        Raises:
+            ZosmfAuthError: If the response status is 401.
+            ZosmfError: Or ``exc_handler`` for another unsuccessful status.
+        """
+        try:
+            response.raise_for_status()
+        except httpx2.HTTPStatusError as exc:
+            if exc.response.status_code == 401:
+                raise ZosmfAuthError(exc) from exc
+            raise exc_handler(exc) from exc
+
+    def close(self) -> None:
+        """Close the shared HTTP client and release its connection resources.
+
+        Call this when the client is no longer needed. Exiting a ``with`` block
+        also calls this method.
+        """
+        self.http.close()
+
+    def __enter__(self) -> Self:
+        """Return this client for use in a ``with`` statement."""
+        return self
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> Literal[False]:
+        """Close the HTTP client without suppressing an exception from the block.
+
+        The exception arguments follow the context-manager protocol; they are
+        not inspected by this implementation.
+        """
+        self.close()
+        return False

zosmfrestapi/services/authentication.py

@@ -0,0 +1,52 @@
+import logging
+
+from zosmfrestapi.exceptions import ZosmfAuthError
+from zosmfrestapi.exceptions.authentication import ZosmfLoginError
+from zosmfrestapi.models.authentication import LoginOk
+
+from . import ZosmfBase
+
+logger = logging.getLogger(__name__)
+
+
+class AuthenticationServices(ZosmfBase):
+    """Authentication operations for the shared z/OSMF client.
+
+    The configured credentials and tokens are sent by the shared HTTP client.
+    The client certificate, basic authentication, and token cookies are all
+    configured during :class:`ZosmfBase` initialization.
+    """
+
+    def authenticate(self) -> LoginOk | None:
+        """Authenticate against the z/OSMF authentication endpoint.
+
+        This method posts to ``/zosmf/services/authenticate`` using the
+        authentication configured when the client was created. It does not
+        perform a separate credential negotiation or clear the configured
+        token cookies.
+
+        Returns:
+            A ``LoginOk`` containing the response return/reason codes and
+            message, plus any LTPA or JWT tokens returned as response cookies.
+
+        Raises:
+            ZosmfLoginError: If z/OSMF responds with HTTP 401.
+            ZosmfAuthError: If another unsuccessful HTTP status is returned.
+            httpx2.RequestError: If the request fails before an HTTP response
+            is received.
+        """
+        logger.debug("Authenticating with z/OSMF using all available methods")
+        resp = self.http.post("/zosmf/services/authenticate")
+        if resp.status_code == 200:
+            logger.debug("Authentication succeeded with z/OSMF")
+            return LoginOk(
+                **resp.json(),
+                ltpa_token=resp.cookies.get("LtpaToken2", self.ltpa_token),
+                jwt_token=resp.cookies.get(self.jwt_cookie_name, self.jwt_token),
+            )
+        elif resp.status_code == 401:
+            logger.debug("Authentication failed with z/OSMF")
+            raise ZosmfLoginError(resp)
+        logger.debug("Unexpected authentication failure with z/OSMF")
+        self._raise_for_status(resp, exc_handler=ZosmfAuthError)
+        raise AssertionError("Unreachable")  # pragma: no cover

zosmfrestapi/services/dataset.py

@@ -0,0 +1,42 @@
+import logging
+
+from zosmfrestapi.exceptions.dataset import ZosmfDatasetError, ZosmfDatasetNotFoundError
+
+from . import ZosmfBase
+
+logger = logging.getLogger(__name__)
+
+
+class DatasetServices(ZosmfBase):
+    """Read sequential or partitioned data sets through z/OSMF Files REST APIs."""
+
+    def _read_dataset(self, path: str) -> str:
+        resp = self.http.get(path)
+        if resp.status_code == 404:
+            raise ZosmfDatasetNotFoundError(resp)
+        self._raise_for_status(resp, exc_handler=ZosmfDatasetError)
+        return resp.text
+
+    def read_dataset(self, dataset: str, volser: str | None = None) -> str:
+        """Read a dataset or dataset member through the z/OSMF Files REST API.
+
+        Args:
+            dataset: Fully qualified data set name, optionally including a
+                member in parentheses, for example ``USER.PDS(MEMBER)``.
+            volser: Optional volume serial for a data set that is not cataloged.
+                When supplied, it is included in the z/OSMF request path.
+
+        Returns:
+            The contents returned by z/OSMF as text.
+
+        Raises:
+            ZosmfDatasetNotFoundError: If z/OSMF returns HTTP 404 for the data
+                set request.
+            ZosmfAuthError: If z/OSMF rejects the request with HTTP 401.
+            ZosmfDatasetError: If z/OSMF returns another unsuccessful HTTP
+                status.
+            httpx2.HTTPError: If a transport-level HTTP error occurs.
+        """
+        if volser:
+            return self._read_dataset(f"/zosmf/restfiles/ds/-({volser})/{dataset}")
+        return self._read_dataset(f"/zosmf/restfiles/ds/{dataset}")