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
+
+- 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,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()