FFDC SSH lib and plugins code documentation
Changes:
- Add code documentation for the functions
Tested:
- Checked with pyflake, pycodesyle and tested
the changes on local sandbox
Change-Id: Ia82edfffe51caa7ca0cd8059f4565660376c0d51
Signed-off-by: George Keishing <gkeishin@in.ibm.com>
diff --git a/ffdc/lib/ssh_utility.py b/ffdc/lib/ssh_utility.py
index 73cdd9c..0f10207 100644
--- a/ffdc/lib/ssh_utility.py
+++ b/ffdc/lib/ssh_utility.py
@@ -24,13 +24,23 @@
def __init__(self, hostname, username, password, port_ssh):
r"""
- Description of argument(s):
+ Initialize the FFDCCollector object with the provided remote host
+ details.
- hostname Name/IP of the remote (targeting) host
- username User on the remote host with access to FFCD files
- password Password for user on remote host
+ This method initializes an FFDCCollector object with the given
+ attributes, which represent the details of the remote (targeting)
+ host. The attributes include the hostname, username, password, and
+ SSH port.
+
+ Parameters:
+ hostname (str): Name or IP address of the remote (targeting) host.
+ username (str): User on the remote host with access to FFDC files.
+ password (str): Password for the user on the remote host.
+ port_ssh (int): SSH port value. By default, 22.
+
+ Returns:
+ None
"""
-
self.ssh_output = None
self.ssh_error = None
self.sshclient = None
@@ -42,9 +52,11 @@
def ssh_remoteclient_login(self):
r"""
- Method to create a ssh connection to remote host.
- """
+ Connect to remote host using the SSH client.
+ Returns:
+ bool: The method return True on success and False in failure.
+ """
is_ssh_login = True
try:
# SSHClient to make connections to the remote server
@@ -78,9 +90,15 @@
def ssh_remoteclient_disconnect(self):
r"""
- Clean up.
- """
+ Disconnect from the remote host using the SSH client.
+ This method disconnects from the remote host using the SSH client
+ established during the FFDC collection process. The method does not
+ return any value.
+
+ Returns:
+ None
+ """
if self.sshclient:
self.sshclient.close()
@@ -88,14 +106,25 @@
self.scpclient.close()
def execute_command(self, command, default_timeout=60):
+ r"""
+ Execute a command on the remote host using the SSH client.
+
+ This method executes a provided command on the remote host using the
+ SSH client. The method takes the command string as an argument and an
+ optional default_timeout parameter of 60 seconds, which specifies the
+ timeout for the command execution.
+
+ The method returns the output of the executed command as a string.
+
+ Parameters:
+ command (str): The command string to be executed
+ on the remote host.
+ default_timeout (int, optional): The timeout for the command
+ execution. Defaults to 60 seconds.
+
+ Returns:
+ str: The output of the executed command as a string.
"""
- Execute command on the remote host.
-
- Description of argument(s):
- command Command string sent to remote host
-
- """
-
empty = ""
cmd_start = time.time()
try:
@@ -147,7 +176,13 @@
def scp_connection(self):
r"""
- Create a scp connection for file transfer.
+ Establish an SCP connection for file transfer.
+
+ This method creates an SCP connection for file transfer using the SSH
+ client established during the FFDC collection process.
+
+ Returns:
+ None
"""
try:
self.scpclient = SCPClient(
@@ -172,16 +207,21 @@
def scp_file_from_remote(self, remote_file, local_file):
r"""
- scp file in remote system to local with date-prefixed filename.
+ SCP a file from the remote host to the local host with a filename.
- Description of argument(s):
- remote_file Full path filename on the remote host
+ This method copies a file from the remote host to the local host using
+ the SCP protocol. The method takes the remote_file and local_file as
+ arguments, which represent the full paths of the files on the remote
+ and local hosts, respectively.
- local_file Full path filename on the local host
- local filename = date-time_remote filename
+ Parameters:
+ remote_file (str): The full path filename on the remote host.
+ local_file (str): The full path filename on the local host.
+
+ Returns:
+ bool: The method return True on success and False in failure.
"""
-
try:
self.scpclient.get(remote_file, local_file, recursive=True)
except (SCPException, SocketTimeout, PipeTimeout, SSHException) as e:
diff --git a/ffdc/plugins/scp_execution.py b/ffdc/plugins/scp_execution.py
index 302936f..c33d61f 100644
--- a/ffdc/plugins/scp_execution.py
+++ b/ffdc/plugins/scp_execution.py
@@ -21,14 +21,25 @@
def scp_remote_file(hostname, username, password, filename, local_dir_path):
r"""
- Description of argument(s):
+ Copy a file from a remote host to the local host using SCP.
- hostname Name/IP of the remote (targeting) host
- username User on the remote host with access to files
- password Password for user on remote host
- filename Filename with full path on remote host
- Filename can contain wild cards for multiple files
- local_dir_path Location to store file on local host
+ This function copies a file from a remote host to the local host using the
+ SCP protocol. The function takes the remote host details (hostname,
+ username, password), the filename with its full path on the remote host,
+ and the local directory path as arguments.
+
+ The function uses wildcards to support copying multiple files if needed.
+
+ Parameters:
+ hostname (str): Name or IP address of the remote host.
+ username (str): User on the remote host with access to files.
+ password (str): Password for the user on the remote host.
+ filename (str): Filename with full path on the remote host.
+ Can contain wildcards for multiple files.
+ local_dir_path (str): Location to store the file on the local host.
+
+ Returns:
+ None
"""
ssh_remoteclient = SSHRemoteclient(hostname, username, password)
diff --git a/ffdc/plugins/ssh_execution.py b/ffdc/plugins/ssh_execution.py
index 3daa1be..4a35c23 100644
--- a/ffdc/plugins/ssh_execution.py
+++ b/ffdc/plugins/ssh_execution.py
@@ -23,15 +23,33 @@
hostname, username, password, port_ssh, command, timeout=60, type=None
):
r"""
- Description of argument(s):
+ Execute a command on the remote host using SSH and return the output.
- hostname Name/IP of the remote (targeting) host
- username User on the remote host with access to FFCD files
- password Password for user on remote host
- port_ssh SSH port value. By default 22.
- command Command to run on remote host
- timeout Time, in second, to wait for command completion
- type Data type return as list or others.
+ This function executes a provided command on the remote host using SSH.
+ The function takes the remote host details (hostname, username, password,
+ and SSH port) and the command to be executed as arguments.
+
+ The function also accepts an optional timeout parameter, which specifies
+ the time in seconds to wait for the command to complete.
+
+ The function returns the output of the executed command as a string or
+ list
+
+ Parameters:
+ hostname (str): Name or IP address of the remote host.
+ username (str): User on the remote host.
+ password (str): Password for the user on the remote host.
+ port_ssh (int): SSH port value. By default, 22.
+ command (str): The command to be executed on the remote host.
+ timeout (int, optional): The time in seconds to wait for the command
+ to complete. Defaults to 60 seconds.
+ type (str, optional): The data type to return. If set to list,
+ the function returns a list of lines from the
+ command output. Defaults to None.
+
+ Returns:
+ str or list: The output of the executed command as a string or a list
+ of lines, depending on the type parameter.
"""
ssh_remoteclient = SSHRemoteclient(hostname, username, password, port_ssh)