add method to issue ssh commands

Signed-off-by: Olamide Ojo <[email protected]>

Author: olamidepeterojo

.vscode/settings.json

@@ -12,7 +12,8 @@
         "./src/zos_files",
         "./src/zos_jobs",
         "./src/zos_tso",
-        "./src/zosmf"
+        "./src/zosmf",
+        "./src/zos_uss"
     ],
     "python.testing.pytestArgs": ["tests"],
     "python.testing.pytestEnabled": true,

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the Zowe Client Python SDK will be documented in this file.
 
+## Recent Changes
+
+- Added execute_command method to issue SSH commands. [#253](https://github.com/zowe/zowe-client-python-sdk/issues/253)
+
 ## `1.0.0-dev22`
 
 ### Enhancements

docs/source/_ext/zowe_autodoc.py

@@ -58,7 +58,11 @@ def main():
             if len(class_names) == 1:
                 rst_name = f"{py_name[:-3]}.rst"
                 rst_contents = render_template(
-                    CLASS_TEMPLATE, {"fullname": f"{sdk_name}.{pkg_name}.{class_names[0]}", "header": class_names[0]}
+                    CLASS_TEMPLATE,
+                    {
+                        "fullname": f"{sdk_name}.{pkg_name}.{class_names[0]}",
+                        "header": class_names[0],
+                    },
                 )
                 with open(f"docs/source/classes/{sdk_name}/{rst_name}", "w", encoding="utf-8") as f:
                     f.write(rst_contents)
@@ -71,9 +75,16 @@ def main():
                     rst_name = f"{class_name.lower()}.rst"
                     rst_contents = render_template(
                         CLASS_TEMPLATE,
-                        {"fullname": f"{sdk_name}.{pkg_name}.{module_name}.{class_name}", "header": class_name},
+                        {
+                            "fullname": f"{sdk_name}.{pkg_name}.{module_name}.{class_name}",
+                            "header": class_name,
+                        },
                     )
-                    with open(f"docs/source/classes/{sdk_name}/{module_name}/{rst_name}", "w", encoding="utf-8") as f:
+                    with open(
+                        f"docs/source/classes/{sdk_name}/{module_name}/{rst_name}",
+                        "w",
+                        encoding="utf-8",
+                    ) as f:
                         f.write(rst_contents)
                     child_rst_names.append(rst_name)
                 rst_name = f"{module_name}/index.rst"
@@ -104,7 +115,11 @@ def main():
 
     rst_contents = render_template(
         INDEX_TEMPLATE,
-        {"filelist": "\n   ".join(f"{name}/index" for name in sdk_names), "header": "Classes", "maxdepth": 3},
+        {
+            "filelist": "\n   ".join(f"{name}/index" for name in sdk_names),
+            "header": "Classes",
+            "maxdepth": 3,
+        },
     )
     with open(f"docs/source/classes/index.rst", "w", encoding="utf-8") as f:
         f.write(rst_contents)

docs/source/packages/files.rst

@@ -18,3 +18,27 @@ Reference
    :maxdepth: 2
 
    ../classes/zos_files/index
+
+Interaction with USS via z/OSMF
+===============================
+
+The Zowe Client Python SDK leverages the z/OS Management Facility (z/OSMF) REST interface to interact with Unix System Services (USS) on z/OS. 
+Rather than connecting directly to USS, our implementation uses z/OSMF as a standardized conduit for file operations and other USS functionalities. 
+This design offers several benefits:
+
+- **Standardization:** z/OSMF provides a consistent REST API for interacting with various z/OS components, including USS.
+- **Security & Maintainability:** By utilizing z/OSMF, we benefit from its built-in authentication, logging, and error-handling mechanisms, making integration more robust.
+- **Simplified Integration:** The REST-based approach reduces the complexity of direct USS interactions, allowing for easier maintenance and future enhancements.
+
+In summary, while it might appear that all USS functionality is routed through z/OSMF, this approach is intentional, providing a secure and manageable interface to z/OS USS.
+
+Paramiko and Encoding Considerations
+======================================
+
+When using Paramiko to interact with z/OS UNIX System Services (USS), it is important to consider encoding and the handling of special characters. 
+By default, Paramiko decodes responses using UTF-8, but z/OS USS may return data in an EBCDIC codepage (e.g., IBM-1047, IBM-037, etc.). 
+This mismatch can result in unexpected output, particularly with special characters like ``ööö``, ``👍``, or ``🔟``.
+
+If you experience unexpected characters in your output, please check your terminal's encoding settings (for example, using ``locale`` on Linux). 
+Note that certain commands may change the terminal's codepage, which can affect subsequent outputs. 
+In such cases, resetting the terminal's encoding after command execution is recommended.

requirements.txt

@@ -3,6 +3,7 @@ deepmerge==1.1.0
 jsonschema==4.17.3
 PyYAML==6.0.1
 requests==2.32.0
+paramiko==3.5.0
 
 # Dev deps
 black
@@ -24,3 +25,4 @@ wheel
 -e ./src/zos_jobs
 -e ./src/zos_tso
 -e ./src/zosmf
+-e ./src/zos_uss

src/core/zowe/core_for_zowe_sdk/config_file.py

@@ -9,6 +9,7 @@
 
 Copyright Contributors to the Zowe Project.
 """
+
 import json
 import os.path
 import re

src/core/zowe/core_for_zowe_sdk/credential_manager.py

@@ -79,7 +79,9 @@ def save_secure_props() -> None:
                 # Delete the existing credential
                 CredentialManager._delete_credential(constants["ZoweServiceName"], constants["ZoweAccountName"])
             CredentialManager._set_credential(
-                constants["ZoweServiceName"], constants["ZoweAccountName"], encoded_credential
+                constants["ZoweServiceName"],
+                constants["ZoweAccountName"],
+                encoded_credential,
             )
 
     @staticmethod

src/core/zowe/core_for_zowe_sdk/logger.py

@@ -39,7 +39,10 @@ class Log:
     file_handler: logging.FileHandler = logging.FileHandler(os.path.join(dirname, "python_sdk_logs.log"))
     file_handler.setLevel(logging.INFO)
     file_handler.setFormatter(
-        logging.Formatter("[%(asctime)s] [%(levelname)s] [%(name)s] - %(message)s", "%m/%d/%Y %I:%M:%S %p")
+        logging.Formatter(
+            "[%(asctime)s] [%(levelname)s] [%(name)s] - %(message)s",
+            "%m/%d/%Y %I:%M:%S %p",
+        )
     )
     console_handler: logging.StreamHandler = logging.StreamHandler()
 

src/core/zowe/core_for_zowe_sdk/profile_manager.py

@@ -17,29 +17,14 @@
 from typing import Optional
 
 from deepmerge import always_merger
-from jsonschema.exceptions import (
-    FormatError,
-    SchemaError,
-    UndefinedTypeCheck,
-    UnknownType,
-    ValidationError,
-)
+from jsonschema.exceptions import FormatError, SchemaError, UndefinedTypeCheck, UnknownType, ValidationError
 
 from .config_file import ConfigFile, Profile
 from .credential_manager import CredentialManager
-from .custom_warnings import (
-    ConfigNotFoundWarning,
-    ProfileNotFoundWarning,
-    SecurePropsNotFoundWarning,
-)
+from .custom_warnings import ConfigNotFoundWarning, ProfileNotFoundWarning, SecurePropsNotFoundWarning
 from .exceptions import ProfileNotFound, SecureProfileLoadFailed, SecureValuesNotFound
 from .logger import Log
-from .profile_constants import (
-    BASE_PROFILE,
-    GLOBAL_CONFIG_NAME,
-    TEAM_CONFIG,
-    USER_CONFIG,
-)
+from .profile_constants import BASE_PROFILE, GLOBAL_CONFIG_NAME, TEAM_CONFIG, USER_CONFIG
 
 HAS_KEYRING = True
 
@@ -272,7 +257,9 @@ def get_profile(
         cfg_profile = Profile()
         try:
             cfg_profile = cfg.get_profile(
-                profile_name=profile_name, profile_type=profile_type, validate_schema=validate_schema
+                profile_name=profile_name,
+                profile_type=profile_type,
+                validate_schema=validate_schema,
             )
         except ValidationError as exc:
             logger.error(f"Instance was invalid under the provided $schema property, {exc}")
@@ -485,7 +472,12 @@ def get_highest_priority_layer(self, json_path: str) -> Optional[ConfigFile]:
         """
         highest_layer = None
         longest_match = ""
-        layers = [self.__project_user_config, self.__project_config, self.__global_user_config, self.__global_config]
+        layers = [
+            self.__project_user_config,
+            self.__project_config,
+            self.__global_user_config,
+            self.__global_config,
+        ]
 
         original_name = layers[0].get_profile_name_from_path(json_path)
 
@@ -556,7 +548,12 @@ def set_profile(self, profile_path: str, profile_data: dict) -> None:
 
     def save(self) -> None:
         """Save the layers (configuration files) to disk."""
-        layers = [self.__project_user_config, self.__project_config, self.__global_user_config, self.__global_config]
+        layers = [
+            self.__project_user_config,
+            self.__project_config,
+            self.__global_user_config,
+            self.__global_config,
+        ]
 
         for layer in layers:
             layer.save(False)

src/core/zowe/core_for_zowe_sdk/request_handler.py

@@ -44,7 +44,11 @@ def __handle_ssl_warnings(self):
             urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
 
     def perform_request(
-        self, method: str, request_arguments: dict, expected_code: list = [200], stream: bool = False
+        self,
+        method: str,
+        request_arguments: dict,
+        expected_code: list = [200],
+        stream: bool = False,
     ) -> Union[str, bytes, dict, None]:
         """Execute an HTTP/HTTPS requests from given arguments and return validated response (JSON).
 
@@ -99,7 +103,11 @@ def __send_request(self, stream: bool = False):
             Flag indicates whether it is a streaming requests.
         """
         self.__response = self.session.request(
-            method=self.__method, stream=stream, **self.session_arguments, **self.__request_arguments)
+            method=self.__method,
+            stream=stream,
+            **self.session_arguments,
+            **self.__request_arguments,
+        )
 
     def __del__(self):
         """Clean up the REST session object once it is no longer needed anymore."""
@@ -123,7 +131,11 @@ def __validate_response(self):
                     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)
+                raise UnexpectedStatus(
+                    self.__expected_code,
+                    self.__response.status_code,
+                    self.__response.text,
+                )
         else:
             output_str = str(self.__response.request.url)
             output_str += "\n" + str(self.__response.request.headers)