Added get_log_messages console REST API function, added exec-data and status query parameters to list_jobs, corrected members parsing, list_members enhancement

Signed-off-by: Uladzislau <leksilonchikk@gmail.com>

Author: KUGDev

src/core/zowe/core_for_zowe_sdk/request_handler.py

@@ -10,11 +10,11 @@
 Copyright Contributors to the Zowe Project.
 """
 
-from typing import Union, Any
-from requests import Response
+from typing import Any, Union
 
 import requests
 import urllib3
+from requests import Response
 
 from .exceptions import InvalidRequestMethod, RequestFailed, UnexpectedStatus
 from .logger import Log
@@ -115,27 +115,23 @@ def __validate_response(self) -> None:
         ------
         UnexpectedStatus
             If the response status code is not in the expected code list
-        RequestFailed
-            If the HTTP/HTTPS request fails
         """
-        # Automatically checks if status code is between 200 and 400
-        if self.__response.ok:
-            if self.__response.status_code not in self.__expected_code:
-                self.__logger.error(
-                    f"The status code from z/OSMF was: {self.__expected_code}\n"
-                    f"Expected: {self.__response.status_code}\n"
-                    f"Request output: {self.__response.text}"
-                )
-                raise UnexpectedStatus(self.__expected_code, self.__response.status_code, self.__response.text)
+        if self.__response.status_code in self.__expected_code:
+            return
         else:
-            output_str = str(self.__response.request.url)
-            output_str += "\n" + str(self.__response.request.headers)
-            output_str += "\n" + str(self.__response.request.body)
-            output_str += "\n" + str(self.__response.text)
-            self.__logger.error(
-                f"HTTP Request has failed with status code {self.__response.status_code}. \n {output_str}"
+            diagnostics = (
+                f"The status code from z/OSMF was: {self.__response.status_code}\n"
+                f"Expected: {self.__expected_code}\n"
+                f"Request URL: {self.__response.request.url}\n"
+                f"Request headers: {self.__response.request.headers}\n"
+                f"Request body: {self.__response.request.body}\n"
+                f"Request output: {self.__response.text}"
             )
-            raise RequestFailed(self.__response.status_code, output_str)
+            if self.__response.ok:
+                self.__logger.warning(diagnostics)
+            else:
+                self.__logger.error(diagnostics)
+                raise UnexpectedStatus(self.__expected_code, self.__response.status_code, self.__response.text)     
 
     def __normalize_response(self) -> Union[str, bytes, dict[str, Any], None]:
         """

src/zos_console/zowe/zos_console_for_zowe_sdk/console.py

@@ -10,11 +10,17 @@
 Copyright Contributors to the Zowe Project.
 """
 
-from typing import Optional, Any
+from datetime import datetime, timezone
+from typing import Any, Literal, Optional
 
 from zowe.core_for_zowe_sdk import SdkApi
 
-from .response import ConsoleResponse, IssueCommandResponse
+from .response import (
+    ConsoleResponse,
+    GetLogMessagesResponse,
+    IssueCommandResponse,
+    UnsuccessfulGetLogMessagesResponse,
+)
 
 
 class Console(SdkApi):  # type: ignore
@@ -30,9 +36,14 @@ class Console(SdkApi):  # type: ignore
     """
 
     def __init__(self, connection: dict[str, Any], log: bool = True):
-        super().__init__(connection, "/zosmf/restconsoles/consoles/defcn", logger_name=__name__, log=log)
-
-    def issue_command(self, command: str, console: Optional[str] = None) -> IssueCommandResponse:
+        super().__init__(connection, "/zosmf/restconsoles/", logger_name=__name__, log=log)
+
+    def issue_command(
+        self,
+        command: str,
+        console: Optional[str] = None,
+        system: Optional[str] = None
+    ) -> IssueCommandResponse:
         """Issues a command on z/OS Console.
 
         Parameters
@@ -41,15 +52,20 @@ def issue_command(self, command: str, console: Optional[str] = None) -> IssueCom
             The z/OS command to be executed
         console : Optional[str]
             Name of the console that should be used to execute the command (default is None)
+        system : Optional[str]
+            Name of the system in the same sysplex that the command is routed to
+            (default is None, that means the local system)
 
         Returns
         -------
         IssueCommandResponse
             A JSON containing the response from the console command
         """
         custom_args = self._create_custom_request_arguments()
-        custom_args["url"] = self._request_endpoint.replace("defcn", console or "defcn")
-        request_body = {"cmd": command}
+        custom_args["url"] = "{}consoles/{}".format(self._request_endpoint, console or "defcn")
+        request_body = {"cmd":command}
+        if system is not None:
+            request_body["system"] = system
         custom_args["json"] = request_body
         response_json = self.request_handler.perform_request("PUT", custom_args)
         return IssueCommandResponse(response_json)
@@ -71,7 +87,88 @@ def get_response(self, response_key: str, console: Optional[str] = None) -> Cons
             A JSON containing the response to the command
         """
         custom_args = self._create_custom_request_arguments()
-        request_url = "{}/solmsgs/{}".format(console or "defcn", response_key)
-        custom_args["url"] = self._request_endpoint.replace("defcn", request_url)
+        request_url = "{}consoles/{}/solmsgs/{}".format(self._request_endpoint, console or "defcn", response_key)
+        custom_args["url"] = request_url
         response_json = self.request_handler.perform_request("GET", custom_args)
         return ConsoleResponse(response_json)
+    
+    def get_log_messages(
+        self,
+        time: Optional[datetime] = None,
+        timestamp: Optional[int] = None,
+        time_range: Optional[str] = None,
+        hardcopy: Optional[Literal["OPERLOG", "SYSLOG"]] = None,
+        sys_name: Optional[str] = None,
+        direction: Optional[Literal["backward", "forward"]] = None
+    ) -> GetLogMessagesResponse | UnsuccessfulGetLogMessagesResponse:
+        """
+        Retrieve messages from hardcopy logs on the system.
+        
+        The maximum return size of the log is 10000.
+        If more than 10000 logs exist in the timeframe, the system returns the first 10000 logs.
+
+        See more at: `Get messages from a hardcopy log`_
+        .. _Get messages from a hardcopy log:
+           https://www.ibm.com/docs/en/zos/3.2.0?topic=services-get-messages-from-hardcopy-log
+        
+        Parameters
+        ----------
+        time : Optional[datetime]
+            Specifies when z/OSMF starts to retrieve messages.
+            This value is used if the timestamp parameter is not specified.
+        timestamp : Optional[int]
+            Specifies the UNIX timestamp, which is the number of milliseconds since 1970-01-01 UTC.
+            This parameter is specified, the "time" parameter is ignored.
+        time_range : Optional[str]
+            Specifies the time range for which the log is to be retrieved.
+            Supported time units include s, m, and h for seconds, minutes, and hours.
+            The format is nnnu, where nnn is a number 1-999 and u is one of the time units "s", "m", or "h".
+            For example, 999s of 20m.
+            The default is 10m.
+        hardcopy : Optional[Literal['OPERLOG', 'SYSLOG']]
+            Specify the source where the logs come from.
+            If not specified, the API tries OPERLOG first.
+            If the OPERLOG is not enabled on the system, the API returns the SYSLOG.
+        sys_name : Optional[str]
+            The name of the system on which the SYSLOG resides.
+        direction : Optional[Literal['backward', 'forward']]
+            Specifies the direction (from a specified time) in which messages are retrieved.
+            The default is "backward", meaning that messages are retrieved backward from the specified time.
+
+        Returns
+        -------
+        GetLogMessagesResponse | UnsuccessfulGetLogMessagesResponse
+            A response content for a successful/unsuccessful get messages request response
+        """
+        custom_args = self._create_custom_request_arguments()
+        custom_args["url"] = "{}v1/log".format(self._request_endpoint)
+        params = {}
+        if time is not None and timestamp is not None:
+            self.logger.warning(
+                'Both "time" and "timestamp" query parameters are provided. "time" parameter is ignored'
+            )
+            time = None
+        if time is not None:
+            if time.tzinfo is not None and time.tzinfo != timezone.utc:
+                self.logger.warning(
+                    f'"time" query parameter is not in UTC timezone ({time.tzinfo}). Conversion to UTC will occur'
+                )
+                time = time.astimezone(timezone.utc)
+            params["time"] = time
+        if timestamp:
+            params["timestamp"] = timestamp
+        if time_range:
+            params["timeRange"] = time_range
+        if hardcopy:
+            params["hardcopy"] = hardcopy
+        if sys_name:
+            params["sysName"] = sys_name
+        if direction:
+            params["direction"] = direction
+        custom_args["params"] = params
+        response_json = self.request_handler.perform_request("GET", custom_args, expected_code=[200, 400, 500])
+        return (
+            GetLogMessagesResponse(response_json)
+            if "returnCode" not in response_json.keys()
+            else UnsuccessfulGetLogMessagesResponse(response_json)
+        )

src/zos_console/zowe/zos_console_for_zowe_sdk/response/__init__.py

@@ -10,4 +10,9 @@
 Copyright Contributors to the Zowe Project.
 """
 
-from .console import ConsoleResponse, IssueCommandResponse
+from .console import (
+    ConsoleResponse,
+    GetLogMessagesResponse,
+    IssueCommandResponse,
+    UnsuccessfulGetLogMessagesResponse,
+)

src/zos_console/zowe/zos_console_for_zowe_sdk/response/console.py

@@ -10,9 +10,31 @@
 Copyright Contributors to the Zowe Project.
 """
 
+import re
 from dataclasses import dataclass
+from datetime import datetime, timedelta
+from datetime import timezone as tz
 from typing import Any, Optional
 
+CAMEL_TO_SNAKE_CASE_PATTERN = re.compile(r'(?<!^)(?=[A-Z])')
+
+
+def to_snake_case(src_str: str) -> str:
+    """
+    Convert camel case string (cameCaseString) to a snake case string (snake_case_string).
+
+    Parameters
+    ----------
+    src_str : str
+        The string to convert
+
+    Returns
+    -------
+    str
+        The converted string
+    """
+    return CAMEL_TO_SNAKE_CASE_PATTERN.sub('_', src_str).lower()
+
 
 @dataclass
 class IssueCommandResponse:
@@ -48,3 +70,139 @@ def __getitem__(self, key: str) -> Any:
 
     def __setitem__(self, key: str, value: Any) -> None:
         self.__dict__[key.replace("-", "_")] = value
+
+
+@dataclass
+class LogMessageResponse:
+    """
+    Log message response object.
+    See more at [Messages JSON object](https://www.ibm.com/docs/en/zos/3.2.0?topic=services-get-messages-from-hardcopy-log#IZUHPINFO_API_GetMessagesandLogs.dita__table_qby_q2x_ypb)
+
+    Parameters
+    ----------
+    cart : Optional[str]
+        Eight character command and response token (CART).
+    color : Optional[str]
+        The color of the message.
+    job_name : Optional[str]
+        The name of the job that generates the message.
+    message : Optional[str]
+        The content of the message.
+    message_id : Optional[str]
+        The message ID.
+    reply_id : Optional[str]
+        Reply ID, in decimal.
+    system : Optional[str]
+        Original eight character system name.
+    type : Optional[str]
+        HARDCOPY.
+    sub_type : Optional[str]
+        Indicate whether the message is a DOM, WTOR, or HOLD message.
+    time : Optional[datetime]
+        For example, “Thu Feb 03 03:00 GMT 2021”.
+    timestamp : Optional[int]
+        UNIX timestamp (milliseconds since epoch). For example, 1621920830109.
+    """
+    
+    cart: Optional[str] = None
+    color: Optional[str] = None
+    job_name: Optional[str] = None
+    message: Optional[str] = None
+    message_id: Optional[str] = None
+    reply_id: Optional[str] = None
+    system: Optional[str] = None
+    type: Optional[str] = None
+    sub_type: Optional[str] = None
+    time: Optional[datetime] = None
+    timestamp: Optional[int] = None
+
+    def __init__(self, raw_data: dict[str, Any]) -> None:
+        for raw_key, raw_value in raw_data.items():
+            key = to_snake_case(raw_key)
+            match(key):
+                case "time":
+                    value = datetime.strptime(raw_value, "%a %b %d %H:%M:%S %Z %Y")
+                case _:
+                    value = raw_value
+            super().__setattr__(key, value)
+    
+    def __getitem__(self, key: str) -> Any:
+        return self.__dict__[to_snake_case(key)]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.__dict__[to_snake_case(key)] = value
+
+
+@dataclass
+class GetLogMessagesResponse:
+    """
+    Get log messages response object.
+    See more at [Response content for a successful Get Messages request](https://www.ibm.com/docs/en/zos/3.2.0?topic=services-get-messages-from-hardcopy-log#IZUHPINFO_API_GetMessagesandLogs.dita__getcmdresponse)
+
+    Parameters
+    ----------
+    timezone : Optional[tz]
+        The timezone of the z/OS system.
+    total_items : Optional[int]
+        Total number of messages returned in the response.
+    next_timestamp : Optional[int]
+        The UNIX timestamp (milliseconds).
+    items : Optional[list[LogMessageResponse]]
+        Array of log messages.
+    source : Optional[str]
+        Indicates the source of the messages.
+    """
+    timezone: Optional[tz] = None
+    total_items: Optional[int] = None
+    next_timestamp: Optional[int] = None
+    items: Optional[list[LogMessageResponse]] = None
+    source: Optional[str] = None
+    
+    def __init__(self, response: dict[str, Any]) -> None:
+        for raw_key, raw_value in response.items():
+            key = to_snake_case(raw_key)
+            match(key):
+                case "timezone":
+                    value = tz(timedelta(hours=raw_value if raw_value is not None else 0))
+                case "items":
+                    value = [LogMessageResponse(x) for x in raw_value] if not raw_value == None else None
+                case _:
+                    value = raw_value
+            super().__setattr__(key, value)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.__dict__[to_snake_case(key)]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.__dict__[to_snake_case(key)] = value
+
+
+@dataclass
+class UnsuccessfulGetLogMessagesResponse:
+    """
+    Get log messages response object for an unsuccessful request.
+    See more at [Response content for an unsuccessful Get Messages request](https://www.ibm.com/docs/en/zos/3.2.0?topic=services-get-messages-from-hardcopy-log#IZUHPINFO_API_GetMessagesandLogs.dita__table_b2g_sgx_ypb)
+
+    Parameters
+    ----------
+    return_code : Optional[int]
+        Identifies the category of error.
+    reason_code : Optional[int]
+        Identifies the specific error.
+    reason : Optional[str]
+        Text that describes the cause of the error.
+    """
+    return_code: Optional[int] = None
+    reason_code: Optional[int] = None
+    reason: Optional[str] = None
+    
+    def __init__(self, response: dict[str, Any]) -> None:
+        for raw_key, value in response.items():
+            key = to_snake_case(raw_key)
+        super().__setattr__(key, value)
+
+    def __getitem__(self, key):
+        return self.__dict__[to_snake_case(key)]
+    
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.__dict__[to_snake_case(key)] = value