FFDC lib and plugins code documentation
Changes:
- Update function code documentation
- Add missing shebang in the files
Tested: - Checked with pyflake, pycodesyle and tested
the changes on local sandbox
Change-Id: Ice2231e3bd3dbe2f00f5cf758e11b23fe3ca475e
Signed-off-by: George Keishing <gkeishin@in.ibm.com>
diff --git a/ffdc/lib/telnet_utility.py b/ffdc/lib/telnet_utility.py
index 03f7983..2a462ac 100644
--- a/ffdc/lib/telnet_utility.py
+++ b/ffdc/lib/telnet_utility.py
@@ -17,14 +17,32 @@
self, hostname, username, password, port=23, read_timeout=None
):
r"""
- Description of argument(s):
+ Initialize the TelnetRemoteClient 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
- read_timeout New read timeout value to override default one
+ This method initializes a TelnetRemoteClient object with the given
+ attributes, which represent the details of the remote (targeting) host.
+
+ The attributes include the hostname, username, password, and Telnet
+ port.
+
+ The method also accepts an optional read_timeout parameter, which
+ specifies a new read timeout value to override the default one.
+
+ 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.
+ port (int, optional): Telnet port value. Defaults to 23.
+ read_timeout (int, optional): New read timeout value to override
+ the default one. Defaults to None.
+
+ Returns:
+ None
"""
-
self.hostname = hostname
self.username = username
self.password = password
@@ -33,6 +51,21 @@
self.read_timeout = read_timeout
def tn_remoteclient_login(self):
+ r"""
+ Establish a Telnet connection to the remote host and log in.
+
+ This method establishes a Telnet connection to the remote host using
+ the provided hostname, username, and password. If the connection and
+ login are successful, the method returns True. Otherwise, it returns
+ False.
+
+ Parameters:
+ None
+
+ Returns:
+ bool: True if the Telnet connection and login are successful,
+ False otherwise.
+ """
is_telnet = True
try:
self.tnclient = telnetlib.Telnet(
@@ -79,9 +112,24 @@
return is_telnet
def __del__(self):
+ r"""
+ Disconnect from the remote host when the object is deleted.
+
+ This method disconnects from the remote host when the
+ TelnetRemoteClient object is deleted.
+ """
self.tn_remoteclient_disconnect()
def tn_remoteclient_disconnect(self):
+ r"""
+ Disconnect from the remote host using the Telnet client.
+
+ This method disconnects from the remote host using the Telnet client
+ established during the FFDC collection process.
+
+ The method attempts to close the Telnet connection. If the Telnet
+ client does not exist, the method ignores the exception.
+ """
try:
self.tnclient.close()
except Exception:
@@ -90,14 +138,25 @@
def execute_command(self, cmd, i_timeout=120):
r"""
- Executes commands on the remote host
+ Executes a command on the remote host using Telnet and returns the
+ output.
- Description of argument(s):
- cmd Command to run on remote host
- i_timeout Timeout for command output
- default is 120 seconds
+ This method executes a provided command on the remote host using
+ Telnet. The method takes the cmd argument, which is expected to be a
+ valid command to execute, and an optional i_timeout parameter, which
+ specifies the timeout for the command output.
+
+ The method returns the output of the executed command as a string.
+
+ Parameters:
+ cmd (str): The command to be executed on the
+ remote host.
+ i_timeout (int, optional): The timeout for the command output.
+ Defaults to 120 seconds.
+
+ Returns:
+ str: The output of the executed command as a string.
"""
-
# Wait time for command execution before reading the output.
# Use user input wait time for command execution if one exists.
# Else use the default 120 sec,
diff --git a/ffdc/plugins/date_time_utils.py b/ffdc/plugins/date_time_utils.py
index f3787bd..bee0085 100644
--- a/ffdc/plugins/date_time_utils.py
+++ b/ffdc/plugins/date_time_utils.py
@@ -9,16 +9,28 @@
def convert_string_dateime(date_str, date_format, desired_format):
r"""
- Return a date time formatted from a string datetime.
+ Convert a date time string to the desired format.
- Description of arguments(s):
- date_str Date time string e.g 2021072418161
- or list ["2021072418161", "20210723163401"]
- date_format Date time pattern of the string date time
- e.g '%Y%m%d%H%M%S'
- desired_format User define format e.g '%m/%d/%Y - %H:%M:%S'
+ This function converts a date time string to the desired format.
+ The function takes the date_str argument, which can be a single date time
+ string or a list of date time strings.
+
+ The function also accepts date_format and desired_format arguments, which
+ specify the input date time pattern and the desired output format,
+ respectively.
+
+ The function returns a list of date time strings in the desired format.
+
+ Parameters:
+ date_str (str or list): A date time string or a list of date time
+ strings.
+ date_format (str): The date time pattern of the input string(s).
+ desired_format (str): The desired output format for the date time
+ strings.
+
+ Returns:
+ list: A list of date time strings in the desired format.
"""
-
if isinstance(date_str, list):
tmp_date = []
for date in date_str:
diff --git a/ffdc/plugins/redfish.py b/ffdc/plugins/redfish.py
index 257ef4f..ebde145 100644
--- a/ffdc/plugins/redfish.py
+++ b/ffdc/plugins/redfish.py
@@ -22,11 +22,28 @@
def execute_redfish_cmd(parms, json_type="json"):
r"""
- Run CLI standard redfish tool.
+ Execute a Redfish command and return the output in the specified JSON
+ format.
- Description of variable:
- parms_string Command to execute from the current SHELL.
- quiet do not print tool error message if True
+ This function executes a provided Redfish command using the redfishtool
+ and returns the output in the specified JSON format. The function takes
+ the parms argument, which is expected to be a qualified string containing
+ the redfishtool command line URI and required parameters.
+
+ The function also accepts an optional json_type parameter, which specifies
+ the desired JSON format for the output (either "json" or "yaml").
+
+ The function returns the output of the executed command as a string in the
+ specified JSON format.
+
+ Parameters:
+ parms (str): A qualified Redfish command line string.
+ json_type (str, optional): The desired JSON format for the output.
+ Defaults to "json".
+
+ Returns:
+ str: The output of the executed command as a string in the specified
+ JSON format.
"""
resp = subprocess.run(
[parms],
@@ -51,12 +68,29 @@
r"""
Perform a GET enumerate request and return available resource paths.
- Description of argument(s):
- url URI resource absolute path (e.g.
- "/redfish/v1/SessionService/Sessions").
- return_json Indicates whether the result should be
- returned as a json string or as a
- dictionary.
+ This function performs a GET enumerate request on the specified URI
+ resource and returns the available resource paths.
+
+ The function takes the remote host details (hostname, username, password)
+ and the URI resource absolute path as arguments. The function also accepts
+ an optional return_json parameter, which specifies whether the result
+ should be returned as a JSON string or as a dictionary.
+
+ The function returns the available resource paths as a list of strings.
+
+ 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.
+ url (str): URI resource absolute path e.g.
+ /redfish/v1/SessionService/Sessions
+ return_json (str, optional): Indicates whether the result should be
+ returned as a JSON string or as a
+ dictionary. Defaults to "json".
+
+ Returns:
+ list: A list of available resource paths as strings.
"""
parms = (
"redfishtool -u "
@@ -114,11 +148,26 @@
def walk_nested_dict(data, url=""):
r"""
- Parse through the nested dictionary and get the resource id paths.
+ Parse through the nested dictionary and extract resource ID paths.
- Description of argument(s):
- data Nested dictionary data from response message.
- url Resource for which the response is obtained in data.
+ This function traverses a nested dictionary and extracts resource ID paths.
+ The function takes the data argument, which is expected to be a nested
+ dictionary containing resource information.
+
+ The function also accepts an optional url argument, which specifies the
+ resource for which the response is obtained in the data dictionary.
+
+ The function returns a list of resource ID paths as strings.
+
+ Parameters:
+ data (dict): A nested dictionary containing resource
+ information.
+ url (str, optional): The resource for which the response is obtained
+ in the data dictionary. Defaults to an empty
+ string.
+
+ Returns:
+ list: A list of resource ID paths as strings.
"""
url = url.rstrip("/")
@@ -148,13 +197,27 @@
def get_key_value_nested_dict(data, key):
r"""
- Parse through the nested dictionary and get the searched key value.
+ Parse through the nested dictionary and retrieve the value associated with
+ the searched key.
- Description of argument(s):
- data Nested dictionary data from response message.
- key Search dictionary key element.
+ This function traverses a nested dictionary and retrieves the value
+ associated with the searched key. The function takes the data argument,
+ which is expected to be a nested dictionary containing resource
+ information.
+
+ The function also accepts a key argument, which specifies the key to
+ search for in the nested dictionary.
+
+ The function returns the value associated with the searched key as a
+ string.
+
+ Parameters:
+ data (dict): A nested dictionary containing resource information.
+ key (str): The key to search for in the nested dictionary.
+
+ Returns:
+ str: The value associated with the searched key as a string.
"""
-
for k, v in data.items():
if isinstance(v, dict):
get_key_value_nested_dict(v, key)
diff --git a/ffdc/plugins/shell_execution.py b/ffdc/plugins/shell_execution.py
index 91a42b2..2c5c163 100644
--- a/ffdc/plugins/shell_execution.py
+++ b/ffdc/plugins/shell_execution.py
@@ -1,15 +1,29 @@
+#!/usr/bin/env python3
+
import subprocess
def execute_cmd(parms_string, quiet=False):
r"""
- Run CLI standard tool or scripts.
+ Execute a CLI standard tool or script with the provided command string.
- Description of variable:
- parms_string Command to execute from the current SHELL.
- quiet do not print tool error message if True
+ This function executes a provided command string using the current SHELL.
+ The function takes the parms_string as an argument, which is expected
+ to be a valid command to execute.
+
+ The function also accepts an optional quiet parameter, which, if set to
+ True, suppresses the output of the command.
+
+ The function returns the output of the executed command as a string.
+
+ Parameters:
+ parms_string (str): The command to execute from the current SHELL.
+ quiet (bool, optional): If True, suppresses the output of the command.
+ Defaults to False.
+
+ Returns:
+ str: The output of the executed command as a string.
"""
-
result = subprocess.run(
[parms_string],
stdout=subprocess.PIPE,
diff --git a/ffdc/plugins/telnet_execution.py b/ffdc/plugins/telnet_execution.py
index 8318337..ca2aabe 100644
--- a/ffdc/plugins/telnet_execution.py
+++ b/ffdc/plugins/telnet_execution.py
@@ -20,13 +20,27 @@
def telnet_execute_cmd(hostname, username, password, command, timeout=60):
r"""
- Description of argument(s):
+ Execute a command on the remote host using Telnet 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
- command Command to run on remote host
- timeout Time, in second, to wait for command completion
+ This function executes a provided command on the remote host using Telnet.
+ The function takes the remote host details (hostname, username, password)
+ 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.
+
+ 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.
+ 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.
+
+ Returns:
+ str: The output of the executed command as a string.
"""
telnet_remoteclient = TelnetRemoteclient(hostname, username, password)
result = ""