add method to issue ssh commands

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

Author: olamidepeterojo

CHANGELOG.md

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

README.md

@@ -54,6 +54,7 @@ jsonschema
 pyyaml
 requests>=2.22
 urllib3
+paramiko
 ```
 
 It also has an optional dependency on the Zowe Secrets SDK for storing client secrets which can be installed with the `secrets` extra:

docs/README.md

@@ -26,3 +26,13 @@ These steps should help you to build the documentation
     - `npm run doc:install`
 5. Build and open the documentation:
     - `npm run doc:dev`
+
+## Best practices
+
+When using paramiko to interact with z/OS UNIX System Services (USS), it's important to consider encoding and special character handling. 
+Since z/OS uses EBCDIC-based encodings (e.g., IBM-1047, IBM-037, etc.), some commands may return unexpected results when processed in a UTF-8 environment. This is because by default, paramiko reads responses in UTF-8, but z/OS USS may return data in an EBCDIC codepage.
+Certain special characters, such as ööö, 👍, or 🔟, may not be correctly interpreted if the encoding is mismatched.
+If you experience unexpected characters in output, check the terminal's encoding settings (local command on Linux).
+Some commands may alter the terminal's codepage, affecting subsequent outputs.
+For example, switching between ASCII and EBCDIC on mainframes can impact character interpretation.
+If a command affects encoding, reset it after execution.

docs/source/_ext/zowe_autodoc.py

@@ -58,9 +58,15 @@ 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:
+                with open(
+                    f"docs/source/classes/{sdk_name}/{rst_name}", "w", encoding="utf-8"
+                ) as f:
                     f.write(rst_contents)
                 rst_names.append(rst_name)
             elif len(class_names) > 1:
@@ -71,9 +77,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"
@@ -85,26 +98,36 @@ def main():
                         "maxdepth": 2,
                     },
                 )
-                with open(f"docs/source/classes/{sdk_name}/{rst_name}", "w", encoding="utf-8") as f:
+                with open(
+                    f"docs/source/classes/{sdk_name}/{rst_name}", "w", encoding="utf-8"
+                ) as f:
                     f.write(rst_contents)
                 parent_rst_names.append(rst_name)
 
         rst_contents = render_template(
             INDEX_TEMPLATE,
             {
-                "filelist": "\n   ".join(name[:-4] for name in rst_names + parent_rst_names),
+                "filelist": "\n   ".join(
+                    name[:-4] for name in rst_names + parent_rst_names
+                ),
                 "header": pkg_name,
                 "maxdepth": 2,
             },
         )
-        with open(f"docs/source/classes/{sdk_name}/index.rst", "w", encoding="utf-8") as f:
+        with open(
+            f"docs/source/classes/{sdk_name}/index.rst", "w", encoding="utf-8"
+        ) as f:
             f.write(rst_contents)
         sdk_names.append(sdk_name)
         print("done")
 
     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)

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
@@ -29,7 +30,9 @@
 
 HOME = os.path.expanduser("~")
 GLOBAL_CONFIG_LOCATION = os.path.join(HOME, ".zowe")
-GLOBAL_CONFIG_PATH = os.path.join(GLOBAL_CONFIG_LOCATION, f"{GLOBAL_CONFIG_NAME}.config.json")
+GLOBAL_CONFIG_PATH = os.path.join(
+    GLOBAL_CONFIG_LOCATION, f"{GLOBAL_CONFIG_NAME}.config.json"
+)
 CURRENT_DIR = os.getcwd()
 
 # Profile datatype is used by ConfigFile to return Profile Data along with
@@ -193,7 +196,9 @@ def schema_list(self, cwd: str = None) -> list:
         profile_props: dict = {}
         schema_json = dict(schema_json)
 
-        for props in schema_json["properties"]["profiles"]["patternProperties"]["^\\S*$"]["allOf"]:
+        for props in schema_json["properties"]["profiles"]["patternProperties"][
+            "^\\S*$"
+        ]["allOf"]:
             props = props["then"]
 
             while "properties" in props:
@@ -234,14 +239,18 @@ def get_profile(
             self.init_from_file(validate_schema)
 
         if profile_name is None and profile_type is None:
-            self.__logger.error(f"Failed to load profile: profile_name and profile_type were not provided.")
+            self.__logger.error(
+                f"Failed to load profile: profile_name and profile_type were not provided."
+            )
             raise ProfileNotFound(
                 profile_name=profile_name,
                 error_msg="Could not find profile as both profile_name and profile_type is not set.",
             )
 
         if profile_name is None:
-            profile_name = self.get_profilename_from_profiletype(profile_type=profile_type)
+            profile_name = self.get_profilename_from_profiletype(
+                profile_type=profile_type
+            )
         props: dict = self.load_profile_properties(profile_name=profile_name)
 
         return Profile(props, profile_name, self._missing_secure_props)
@@ -296,7 +305,9 @@ def get_profilename_from_profiletype(self, profile_type: str) -> str:
         try:
             profilename = self.defaults[profile_type]
         except KeyError:
-            self.__logger.warn(f"Given profile type '{profile_type}' has no default profile name")
+            self.__logger.warn(
+                f"Given profile type '{profile_type}' has no default profile name"
+            )
             warnings.warn(
                 f"Given profile type '{profile_type}' has no default profile name",
                 ProfileParsingWarning,
@@ -318,7 +329,9 @@ def get_profilename_from_profiletype(self, profile_type: str) -> str:
                 )
 
         # if no profile with matching type found, we raise an exception
-        self.__logger.error(f"No profile with matching profile_type '{profile_type}' found")
+        self.__logger.error(
+            f"No profile with matching profile_type '{profile_type}' found"
+        )
         raise ProfileNotFound(
             profile_name=profile_type,
             error_msg=f"No profile with matching profile_type '{profile_type}' found",
@@ -378,7 +391,9 @@ def load_profile_properties(self, profile_name: str) -> dict:
                 secure_fields.extend(profile.get("secure", []))
             else:
                 self.__logger.warning(f"Profile {profile_name} not found")
-                warnings.warn(f"Profile {profile_name} not found", ProfileNotFoundWarning)
+                warnings.warn(
+                    f"Profile {profile_name} not found", ProfileNotFoundWarning
+                )
             lst.pop()
 
         return props
@@ -399,7 +414,9 @@ def __load_secure_properties(self):
                 else:
                     break
 
-    def __extract_secure_properties(self, profiles_obj: dict, json_path: Optional[str] = "profiles") -> dict:
+    def __extract_secure_properties(
+        self, profiles_obj: dict, json_path: Optional[str] = "profiles"
+    ) -> dict:
         """
         Extract secure properties from the profiles object for storage in the vault.
 
@@ -420,11 +437,15 @@ def __extract_secure_properties(self, profiles_obj: dict, json_path: Optional[st
         for key, value in profiles_obj.items():
             for property_name in value.get("secure", []):
                 if property_name in value.get("properties", {}):
-                    secure_props[f"{json_path}.{key}.properties.{property_name}"] = value["properties"].pop(
-                        property_name
+                    secure_props[f"{json_path}.{key}.properties.{property_name}"] = (
+                        value["properties"].pop(property_name)
                     )
             if value.get("profiles"):
-                secure_props.update(self.__extract_secure_properties(value["profiles"], f"{json_path}.{key}.profiles"))
+                secure_props.update(
+                    self.__extract_secure_properties(
+                        value["profiles"], f"{json_path}.{key}.profiles"
+                    )
+                )
         return secure_props
 
     def __set_or_create_nested_profile(self, profile_name: str, profile_data: dict):
@@ -466,7 +487,9 @@ def __is_secure(self, json_path: str, property_name: str) -> bool:
             return property_name in profile["secure"]
         return False
 
-    def set_property(self, json_path: str, value: str, secure: Optional[bool] = None) -> None:
+    def set_property(
+        self, json_path: str, value: str, secure: Optional[bool] = None
+    ) -> None:
         """
         Set a property in the profile, storing it securely if necessary.
 
@@ -521,7 +544,9 @@ def set_profile(self, profile_path: str, profile_data: dict) -> None:
             secure_fields = profile_data["secure"]
             current_profile = self.find_profile(profile_name, self.profiles) or {}
             existing_secure_fields = current_profile.get("secure", [])
-            new_secure_fields = [field for field in secure_fields if field not in existing_secure_fields]
+            new_secure_fields = [
+                field for field in secure_fields if field not in existing_secure_fields
+            ]
 
             # Updating the 'secure' field of the profile with the combined list of secure fields
             profile_data["secure"] = existing_secure_fields + new_secure_fields
@@ -569,7 +594,11 @@ def get_profile_name_from_path(self, path: str) -> str:
             Returns the profile name
         """
         segments = path.split(".")
-        profile_name = ".".join(segments[i] for i in range(1, len(segments), 2) if segments[i - 1] != "properties")
+        profile_name = ".".join(
+            segments[i]
+            for i in range(1, len(segments), 2)
+            if segments[i - 1] != "properties"
+        )
         return profile_name
 
     def get_profile_path_from_name(self, short_path: str) -> str:

src/core/zowe/core_for_zowe_sdk/connection.py

@@ -35,7 +35,9 @@ class ApiConnection:
         Missing connection argument.
     """
 
-    def __init__(self, host_url: str, user: str, password: str, ssl_verification: bool = True):
+    def __init__(
+        self, host_url: str, user: str, password: str, ssl_verification: bool = True
+    ):
         __logger = Log.register_logger(__name__)
         if not host_url or not user or not password:
             __logger.error("Missing connection argument")

src/core/zowe/core_for_zowe_sdk/credential_manager.py

@@ -50,14 +50,20 @@ def load_secure_props() -> None:
             return
 
         try:
-            secret_value = CredentialManager._get_credential(constants["ZoweServiceName"], constants["ZoweAccountName"])
+            secret_value = CredentialManager._get_credential(
+                constants["ZoweServiceName"], constants["ZoweAccountName"]
+            )
             # Handle the case when secret_value is None
             if secret_value is None:
                 return
 
         except Exception as exc:
-            CredentialManager.__logger.error(f"Fail to load secure profile {constants['ZoweServiceName']}")
-            raise SecureProfileLoadFailed(constants["ZoweServiceName"], error_msg=str(exc)) from exc
+            CredentialManager.__logger.error(
+                f"Fail to load secure profile {constants['ZoweServiceName']}"
+            )
+            raise SecureProfileLoadFailed(
+                constants["ZoweServiceName"], error_msg=str(exc)
+            ) from exc
 
         secure_config: str
         secure_config = secret_value.encode()
@@ -74,12 +80,18 @@ def save_secure_props() -> None:
         credential = CredentialManager.secure_props
         # Check if credential is a non-empty string
         if credential:
-            encoded_credential = base64.b64encode(commentjson.dumps(credential).encode()).decode()
+            encoded_credential = base64.b64encode(
+                commentjson.dumps(credential).encode()
+            ).decode()
             if sys.platform == "win32":
                 # Delete the existing credential
-                CredentialManager._delete_credential(constants["ZoweServiceName"], constants["ZoweAccountName"])
+                CredentialManager._delete_credential(
+                    constants["ZoweServiceName"], constants["ZoweAccountName"]
+                )
             CredentialManager._set_credential(
-                constants["ZoweServiceName"], constants["ZoweAccountName"], encoded_credential
+                constants["ZoweServiceName"],
+                constants["ZoweAccountName"],
+                encoded_credential,
             )
 
     @staticmethod
@@ -110,21 +122,31 @@ def _get_credential(service_name: str, account_name: str) -> Optional[str]:
                 else:
                     encoded_credential += temp_value
                 index += 1
-                temp_value = keyring.get_password(service_name, f"{account_name}-{index}")
+                temp_value = keyring.get_password(
+                    service_name, f"{account_name}-{index}"
+                )
 
             if encoded_credential is not None and encoded_credential.endswith("\0"):
                 encoded_credential = encoded_credential[:-1]
 
         return encoded_credential
 
     @staticmethod
-    def _set_credential(service_name: str, account_name: str, encoded_credential: str) -> None:
+    def _set_credential(
+        service_name: str, account_name: str, encoded_credential: str
+    ) -> None:
         # Check if the encoded credential exceeds the maximum length for win32
-        if sys.platform == "win32" and len(encoded_credential) > constants["WIN32_CRED_MAX_STRING_LENGTH"]:
+        if (
+            sys.platform == "win32"
+            and len(encoded_credential) > constants["WIN32_CRED_MAX_STRING_LENGTH"]
+        ):
             # Split the encoded credential string into chunks of maximum length
             chunk_size = constants["WIN32_CRED_MAX_STRING_LENGTH"]
             encoded_credential += "\0"
-            chunks = [encoded_credential[i : i + chunk_size] for i in range(0, len(encoded_credential), chunk_size)]
+            chunks = [
+                encoded_credential[i : i + chunk_size]
+                for i in range(0, len(encoded_credential), chunk_size)
+            ]
             # Set the individual chunks as separate keyring entries
             for index, chunk in enumerate(chunks, start=1):
                 field_name = f"{account_name}-{index}"