From d8b87a42117c99144bedd93e4f0b5f7964fc112c Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Fri, 5 Apr 2024 11:20:49 -0600 Subject: [PATCH] [Documentation][encode] Add and standarize docstring to encode.py (#1322) * Add and estandarize docstring to encode.py * Create changelog fragment * Modified the google style to numpy * Update changelog fragment * Standarize numpy style * Update encode.py added newline to address pep8 error * Fixed some dcostrings * Modified docstrings --------- Co-authored-by: Rich Parker Co-authored-by: Fernando Flores --- .../1322-update-docstring-encode.yml | 3 + plugins/module_utils/encode.py | 357 +++++++++++++----- 2 files changed, 269 insertions(+), 91 deletions(-) create mode 100644 changelogs/fragments/1322-update-docstring-encode.yml diff --git a/changelogs/fragments/1322-update-docstring-encode.yml b/changelogs/fragments/1322-update-docstring-encode.yml new file mode 100644 index 000000000..dd5eb5389 --- /dev/null +++ b/changelogs/fragments/1322-update-docstring-encode.yml @@ -0,0 +1,3 @@ +trivial: + - encode - Updated docstrings to numpy style for visual aid to developers. + (https://github.com/ansible-collections/ibm_zos_core/pull/1322). \ No newline at end of file diff --git a/plugins/module_utils/encode.py b/plugins/module_utils/encode.py index 195802583..f68a8ab77 100644 --- a/plugins/module_utils/encode.py +++ b/plugins/module_utils/encode.py @@ -56,10 +56,12 @@ class Defaults: @staticmethod def get_default_system_charset(): - """Get the default encoding of the current machine + """Get the default encoding of the current machine. - Returns: - str -- The encoding of the current machine + Returns + ------- + str + The encoding of the current machine. """ system_charset = locale.getdefaultlocale()[1] if system_charset is None: @@ -80,15 +82,24 @@ def get_default_system_charset(): class EncodeUtils(object): def __init__(self): """Call the coded character set conversion utility iconv - to convert a USS file from one coded character set to another - - Arguments: - module {AnsibleModule} -- The AnsibleModule object from currently running module + to convert a USS file from one coded character set to another. """ self.module = AnsibleModuleHelper(argument_spec={}) self.tmphlq = None def _validate_data_set_name(self, ds): + """Validate data set name using BetterArgParser. + + Parameters + ---------- + ds : str + The source data set name. + + Returns + ------- + str + Parsed data set name. + """ arg_defs = dict( ds=dict(arg_type="data_set"), ) @@ -97,6 +108,18 @@ def _validate_data_set_name(self, ds): return parsed_args.get("ds") def _validate_path(self, path): + """Validate path using BetterArgParser. + + Parameters + ---------- + path : str + The path. + + Returns + ------- + str + Parsed path. + """ arg_defs = dict( path=dict(arg_type="path"), ) @@ -105,6 +128,18 @@ def _validate_path(self, path): return parsed_args.get("path") def _validate_data_set_or_path(self, path): + """Validate data set or path using BetterArgParser. + + Parameters + ---------- + path : str + The path. + + Returns + ------- + str + Parsed path. + """ arg_defs = dict( path=dict(arg_type="data_set_or_path"), ) @@ -113,6 +148,18 @@ def _validate_data_set_or_path(self, path): return parsed_args.get("path") def _validate_encoding(self, encoding): + """Validate encoding using BetterArgParser. + + Parameters + --------- + encoding : str + The encoding. + + Returns + ------- + str + Parsed encoding. + """ arg_defs = dict( encoding=dict(arg_type="encoding"), ) @@ -122,16 +169,24 @@ def _validate_encoding(self, encoding): def listdsi_data_set(self, ds): """Invoke IDCAMS LISTCAT command to get the record length and space used - to estimate the space used by the VSAM data set - - Arguments: - ds: {str} -- The VSAM data set to be checked. - - Raises: - EncodeError: When any exception is raised during the conversion. - Returns: - int -- The maximum record length of the VSAM data set. - int -- The space used by the VSAM data set(KB). + to estimate the space used by the VSAM data set. + + Parameters + ---------- + ds : str + The VSAM data set to be checked. + + Returns + ------- + int + The maximum record length of the VSAM data set. + int + The space used by the VSAM data set(KB). + + Raises + ------ + EncodeError + When any exception is raised during the conversion. """ ds = self._validate_data_set_name(ds) reclen = 80 @@ -179,17 +234,24 @@ def listdsi_data_set(self, ds): return reclen, space_u def temp_data_set(self, reclen, space_u): - """Creates a temporary data set with the given record length and size - - Arguments: - size {str} -- The size of the data set - lrecl {int} -- The record length of the data set - - Returns: - str -- Name of the allocated data set - - Raises: - ZOAUException: When any exception is raised during the data set allocation. + """Creates a temporary data set with the given record length and size. + + Parameters + ---------- + lrecl : int + The record length of the data set. + space_u : str + The size of the data set. + + Returns + ------- + str + Name of the allocated data set. + + Raises + ------ + ZOAUException + When any exception is raised during the data set allocation. DatasetVerificationError: When the data set creation could not be verified. """ size = str(space_u * 2) + "K" @@ -208,12 +270,17 @@ def temp_data_set(self, reclen, space_u): return temporary_data_set.name def get_codeset(self): - """Get the list of supported encodings from the USS command 'iconv -l' + """Get the list of supported encodings from the USS command 'iconv -l'. + + Returns + ------- + Union[str] + The code set list supported in current USS platform. - Raises: - EncodeError: When any exception is raised during the conversion - Returns: - list -- The code set list supported in current USS platform + Raises + ------ + EncodeError + When any exception is raised during the conversion. """ code_set = None iconv_list_cmd = ["iconv", "-l"] @@ -226,17 +293,26 @@ def get_codeset(self): return code_set def string_convert_encoding(self, src, from_encoding, to_encoding): - """Convert the encoding of the data when the src is a normal string - - Arguments: - from_code_set: {str} -- The source code set of the string - to_code_set: {str} -- The destination code set for the string - src: {str} -- The input string content - - Raises: - EncodeError: When any exception is raised during the conversion - Returns: - str -- The string content after the encoding + """Convert the encoding of the data when the src is a normal string. + + Parameters + ---------- + src : str + The input string content. + from_encoding : str + The source code set of the string. + to_encoding : str + The destination code set for the string. + + Returns + ------- + str + The string content after the encoding. + + Raises + ------ + EncodeError + When any exception is raised during the conversion. """ from_encoding = self._validate_encoding(from_encoding) to_encoding = self._validate_encoding(to_encoding) @@ -249,19 +325,30 @@ def string_convert_encoding(self, src, from_encoding, to_encoding): return out def uss_convert_encoding(self, src, dest, from_code, to_code): - """Convert the encoding of the data in a USS file - - Arguments: - from_code: {str} -- The source code set of the input file - to_code: {str} -- The destination code set for the output file - src: {str} -- The input file name, it should be a uss file - dest: {str} -- The output file name, it should be a uss file - - Raises: - EncodeError: When any exception is raised during the conversion. - MoveFileError: When any exception is raised during moving files. - Returns: - boolean -- Indicate whether the conversion is successful or not. + """Convert the encoding of the data in a USS file. + + Parameters + ---------- + src : str + The input file name, it should be a uss file. + dest : str + The output file name, it should be a uss file. + from_code : str + The source code set of the input file. + to_code : str + The destination code set for the output file. + + Returns + ------- + bool + Indicate whether the conversion is successful or not. + + Raises + ------ + EncodeError + When any exception is raised during the conversion. + MoveFileError + When any exception is raised during moving files. """ src = self._validate_path(src) dest = self._validate_path(dest) @@ -306,18 +393,28 @@ def uss_convert_encoding(self, src, dest, from_code, to_code): def uss_convert_encoding_prev(self, src, dest, from_code, to_code): """For multiple files conversion, such as a USS path or MVS PDS data set, - use this method to split then do the conversion - - Arguments: - from_code: {str} -- The source code set of the input path - to_code: {str} -- The destination code set for the output path - src: {str} -- The input uss path or a file - dest: {str} -- The output uss path or a file - - Raises: - EncodeError: When direcotry is empty or copy multiple files to a single file - Returns: - boolean -- Indicate whether the conversion is successful or not + use this method to split then do the conversion. + + Parameters + ---------- + src : str + The input uss path or a file. + dest : str + The output uss path or a file. + from_code : str + The source code set of the input path. + to_code : str + The destination code set for the output path. + + Returns + ------- + bool + Indicate whether the conversion is successful or not. + + Raises + ------ + EncodeError + When directory is empty or copy multiple files to a single file. """ src = self._validate_path(src) dest = self._validate_path(dest) @@ -375,18 +472,28 @@ def mvs_convert_encoding( 2) MVS to USS 3) MVS to MVS - Arguments: - src: {str} -- The input MVS data set or USS path to be converted - dest: {str} -- The output MVS data set or USS path to be converted - from_code: {str} -- The source code set of the input MVS data set - to_code: {str} -- The destination code set of the output MVS data set - - Keyword Arguments: - src_type {[type]} -- The input MVS data set or type: PS, PDS, PDSE, VSAM(KSDS) (default: {None}) - dest_type {[type]} -- The output MVS data set type (default: {None}) - - Returns: - boolean -- Indicate whether the conversion is successful or not + Parameters + ---------- + src : str + The input MVS data set or USS path to be converted. + dest : str + The output MVS data set or USS path to be converted. + from_code : str + The source code set of the input MVS data set. + to_code : str + The destination code set of the output MVS data set. + + Keyword Parameters + ----------------- + src_type : str + The input MVS data set or type: PS, PDS, PDSE, VSAM(KSDS). + dest_type : str + The output MVS data set type. + + Returns + ------- + bool + Indicate whether the conversion is successful or not. """ src = self._validate_data_set_or_path(src) dest = self._validate_data_set_or_path(dest) @@ -458,11 +565,18 @@ def uss_tag_encoding(self, file_path, tag): """Tag the file/directory specified with the given code set. If `file_path` is a directory, all of the files and subdirectories will be tagged recursively. - Arguments: - file_path {str} -- Absolute file path to tag. - tag {str} -- Code set to tag the file/directory. - Raises: - TaggingError: When the chtag command fails. + + Parameters + ---------- + file_path : str + Absolute file path to tag. + tag : str + Code set to tag the file/directory. + + Raises + ------ + TaggingError + When the chtag command fails. """ is_dir = os.path.isdir(file_path) @@ -473,11 +587,18 @@ def uss_tag_encoding(self, file_path, tag): def uss_file_tag(self, file_path): """Returns the current tag set for a file. - Arguments: - file_path {str} -- USS path to the file. - Returns: - str -- Current tag set for the file, as returned by 'ls -T' - None -- If the file does not exist or the command fails. + + Parameters + ---------- + file_path : str + USS path to the file. + + Returns + ------- + str + Current tag set for the file, as returned by 'ls -T'. + None + If the file does not exist or the command fails. """ if not os.path.exists(file_path): return None @@ -500,12 +621,50 @@ def uss_file_tag(self, file_path): class EncodeError(Exception): def __init__(self, message): + """Error during encoding. + + Parameters + ---------- + message : str + Human readable string describing the exception. + + Attributes + ---------- + msg : str + Human readable string describing the exception. + """ self.msg = 'An error occurred during encoding: "{0}"'.format(message) super(EncodeError, self).__init__(self.msg) class TaggingError(Exception): def __init__(self, file_path, tag, rc, stdout, stderr): + """Error during tagging. + + Parameters + ---------- + file_path : str + File to tag. + tag : str + Tag to put in the file. + rc : int + Return code. + stdout : str + Standard output. + stderr : str + Standard error. + + Attributes + ---------- + msg : str + Human readable string describing the exception. + rc : int + Return code. + stdout : str + Standard output. + stderr : str + Standard error. + """ self.msg = 'An error occurred during tagging of {0} to {1}'.format( file_path, tag @@ -518,5 +677,21 @@ def __init__(self, file_path, tag, rc, stdout, stderr): class MoveFileError(Exception): def __init__(self, src, dest, e): + """Error while moving a file. + + Parameters + ---------- + src : str + From where the file moves. + dest : str + To where the file moves. + e : str + Exception message. + + Attributes + ---------- + msg : str + Human readable string describing the exception. + """ self.msg = "Failed when moving {0} to {1}: {2}".format(src, dest, e) super().__init__(self.msg)