From d11ef8bcc64227b90f5f1ffa44e26216e0e3a86b Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Wed, 27 Mar 2024 14:44:28 -0600 Subject: [PATCH 1/4] Add and standarize docstrings on modules/zos_find.py --- plugins/modules/zos_find.py | 87 +++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 3 deletions(-) diff --git a/plugins/modules/zos_find.py b/plugins/modules/zos_find.py index b49d65f04..bf7f9aaac 100644 --- a/plugins/modules/zos_find.py +++ b/plugins/modules/zos_find.py @@ -288,6 +288,9 @@ def content_filter(module, patterns, content): a set of matched "PS" data sets, a dictionary containing "PDS" data sets and members corresponding to each PDS, an int representing number of total data sets examined. + + Raises: + fail_json: Non-zero return code received while executing ZOAU shell command 'dgrep' """ filtered_data_sets = dict(ps=set(), pds=dict(), searched=0) for pattern in patterns: @@ -329,6 +332,9 @@ def data_set_filter(module, pds_paths, patterns): a set of matched "PS" data sets, a dictionary containing "PDS" data sets and members corresponding to each PDS, an int representing number of total data sets examined. + + Raises: + fail_json: Non-zero return code received while executing ZOAU shell command 'dls' """ filtered_data_sets = dict(ps=set(), pds=dict(), searched=0) patterns = pds_paths or patterns @@ -417,6 +423,9 @@ def vsam_filter(module, patterns, resource_type, age=None): Returns: set[str]-- Matched VSAM data sets + + Raises: + fail_json: Non-zero return code received while executing ZOAU shell command 'vls' """ filtered_data_sets = set() now = time.time() @@ -454,6 +463,9 @@ def data_set_attribute_filter( Returns: set[str] -- Matched data sets filtered by age and size + + Raises: + fail_json: Non-zero return code received while executing ZOAU shell command 'dls' """ filtered_data_sets = set() now = time.time() @@ -500,6 +512,9 @@ def volume_filter(module, data_sets, volumes): Returns: set[str] -- The filtered data sets + + Raises: + fail_json: Unable to retrieve VTOC information """ filtered_data_sets = set() for volume in volumes: @@ -568,6 +583,9 @@ def _get_creation_date(module, ds): Returns: str -- The data set creation date in the format "YYYY/MM/DD" + + Raises: + fail_json: Non-zero return code received while retrieving data set age """ rc, out, err = mvs_cmd.idcams( " LISTCAT ENT('{0}') HISTORY".format(ds), authorized=True @@ -621,6 +639,9 @@ def _match_regex(module, pattern, string): Returns: re.Match -- A Match object that matches the pattern to string + + Raises: + fail_json: Invalid regular expression """ try: return fullmatch(pattern, string, re.IGNORECASE) @@ -639,7 +660,19 @@ def _dgrep_wrapper( verbose=False, context=None ): - """A wrapper for ZOAU 'dgrep' shell command""" + """A wrapper for ZOAU 'dgrep' shell command + + Arguments: + data_set_pattern {str} -- Data set pattern + content {str} -- Content + ignore_case {bool} -- If ignore case + line_num {bool} -- If line num + verbose {bool} -- If verbose + context {bool} -- If context + + Returns: + tuple[int,str,str] -- Return code, standard output and standard error + """ dgrep_cmd = "dgrep" if ignore_case: dgrep_cmd += " -i" @@ -662,7 +695,20 @@ def _dls_wrapper( verbose=False, migrated=False ): - """A wrapper for ZOAU 'dls' shell command""" + """A wrapper for ZOAU 'dls' shell command + + Arguments: + data_set_pattern {str} -- Data set pattern + content {str} -- Content + list_details {bool} -- If list details + u_time {bool} -- If u time + size {bool} -- If size + verbose {bool} -- If verbose + migrated {bool} -- If migrated + + Returns: + tuple[int,str,str] -- Return code, standard output and standard error + """ dls_cmd = "dls" if migrated: dls_cmd += " -m" @@ -681,7 +727,16 @@ def _dls_wrapper( def _vls_wrapper(pattern, details=False, verbose=False): - """A wrapper for ZOAU 'vls' shell command""" + """A wrapper for ZOAU 'vls' shell command + + Arguments: + pattern {str} -- Data set pattern + details {bool} -- If details + verbose {bool} -- If verbose + + Returns: + tuple[int,str,str] -- Return code, standard output and standard error + """ vls_cmd = "vls" if details: vls_cmd += " -l" @@ -693,6 +748,15 @@ def _vls_wrapper(pattern, details=False, verbose=False): def _match_resource_type(type1, type2): + """Compare that the two types match + + Arguments: + type1 {str} -- One of the types that are expected to match + type2 {str} -- One of the types that are expected to match + + Returns: + bool -- If the types match + """ if type1 == type2: return True if type1 == "CLUSTER" and type2 not in ("DATA", "INDEX"): @@ -720,6 +784,18 @@ def _ds_type(ds_name): def run_module(module): + """Initialize parameters + + Arguments: + module {AnsibleModule} -- Ansible Module + + Returns: + dict -- Arguments + + Raises: + fail_json: Failed to process age + fail_json: Failed to process size + """ # Parameter initialization age = module.params.get('age') age_stamp = module.params.get('age_stamp') @@ -816,6 +892,11 @@ def run_module(module): def main(): + """Initialize module when it's run as main + + Raises: + fail_json: Parameter verification failed + """ module = AnsibleModule( argument_spec=dict( age=dict(type="str", required=False), From 5f9e52a05cc6ead4939798061dac02f04c7e0130 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Fri, 29 Mar 2024 15:54:00 -0600 Subject: [PATCH 2/4] Create changelog fragment --- changelogs/fragments/1350-update-docstring-zos_find.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelogs/fragments/1350-update-docstring-zos_find.yml diff --git a/changelogs/fragments/1350-update-docstring-zos_find.yml b/changelogs/fragments/1350-update-docstring-zos_find.yml new file mode 100644 index 000000000..138608e7c --- /dev/null +++ b/changelogs/fragments/1350-update-docstring-zos_find.yml @@ -0,0 +1,3 @@ +trivial: + - zos_find - Updated docstrings to google style for visual aid to developers. + (https://github.com/ansible-collections/ibm_zos_core/pull/1350). \ No newline at end of file From ad0dfa2d33db94ee2e8fdd525d6a082d175f8d77 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Tue, 2 Apr 2024 13:55:38 -0600 Subject: [PATCH 3/4] Modify google style to numpy --- .../1350-update-docstring-zos_find.yml | 2 +- plugins/modules/zos_find.py | 455 +++++++++++------- 2 files changed, 288 insertions(+), 169 deletions(-) diff --git a/changelogs/fragments/1350-update-docstring-zos_find.yml b/changelogs/fragments/1350-update-docstring-zos_find.yml index 138608e7c..48c1fbce1 100644 --- a/changelogs/fragments/1350-update-docstring-zos_find.yml +++ b/changelogs/fragments/1350-update-docstring-zos_find.yml @@ -1,3 +1,3 @@ trivial: - - zos_find - Updated docstrings to google style for visual aid to developers. + - zos_find - Updated docstrings to numpy style for visual aid to developers. (https://github.com/ansible-collections/ibm_zos_core/pull/1350). \ No newline at end of file diff --git a/plugins/modules/zos_find.py b/plugins/modules/zos_find.py index bf7f9aaac..2bfd953d3 100644 --- a/plugins/modules/zos_find.py +++ b/plugins/modules/zos_find.py @@ -276,21 +276,28 @@ def content_filter(module, patterns, content): """ Find data sets that match any pattern in a list of patterns and - contains the given content - - Arguments: - module {AnsibleModule} -- The Ansible module object being used in the module - patterns {list[str]} -- A list of data set patterns - content {str} -- The content string to search for within matched data sets - - Returns: - dict[ps=set, pds=dict[str, str], searched=int] -- A dictionary containing + contains the given content. + + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used in the module. + patterns : list[str] + A list of data set patterns. + content : str + The content string to search for within matched data sets. + + Returns + ------- + dict[ps=set, pds=dict[str, str], searched=int] + A dictionary containing a set of matched "PS" data sets, a dictionary containing "PDS" data sets and members corresponding to each PDS, an int representing number of total data sets examined. - Raises: - fail_json: Non-zero return code received while executing ZOAU shell command 'dgrep' + Raises + ------ + fail_json: Non-zero return code received while executing ZOAU shell command 'dgrep'. """ filtered_data_sets = dict(ps=set(), pds=dict(), searched=0) for pattern in patterns: @@ -323,18 +330,25 @@ def content_filter(module, patterns, content): def data_set_filter(module, pds_paths, patterns): """ Find data sets that match any pattern in a list of patterns. - Arguments: - module {AnsibleModule} -- The Ansible module object being used - patterns {list[str]} -- A list of data set patterns - - Returns: - dict[ps=set, pds=dict[str, str], searched=int] -- A dictionary containing + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used. + patterns : list[str] + A list of data set patterns. + + Returns + ------- + dict[ps=set, pds=dict[str, str], searched=int] + A dictionary containing a set of matched "PS" data sets, a dictionary containing "PDS" data sets and members corresponding to each PDS, an int representing number of total data sets examined. - Raises: - fail_json: Non-zero return code received while executing ZOAU shell command 'dls' + Raises + ------ + fail_json + Non-zero return code received while executing ZOAU shell command 'dls'. """ filtered_data_sets = dict(ps=set(), pds=dict(), searched=0) patterns = pds_paths or patterns @@ -377,15 +391,21 @@ def pds_filter(module, pds_dict, member_patterns, excludes=None): """ Return all PDS/PDSE data sets whose members match any of the patterns in the given list of member patterns. - Arguments: - module {AnsibleModule} -- The Ansible module object being used in the module - pds_dict {dict[str, str]} -- A dictionary where each key is the name of - of the PDS/PDSE and the value is a list of - members belonging to the PDS/PDSE - member_patterns {list} -- A list of member patterns to search for - - Returns: - dict[str, set[str]] -- Filtered PDS/PDSE with corresponding members + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used in the module. + pds_dict : dict[str, str] + A dictionary where each key is the name of + of the PDS/PDSE and the value is a list of + members belonging to the PDS/PDSE. + member_patterns : list + A list of member patterns to search for. + + Returns + ------- + dict[str, set[str]] + Filtered PDS/PDSE with corresponding members. """ filtered_pds = dict() for pds, members in pds_dict.items(): @@ -417,15 +437,22 @@ def vsam_filter(module, patterns, resource_type, age=None): """ Return all VSAM data sets that match any of the patterns in the given list of patterns. - Arguments: - module {AnsibleModule} -- The Ansible module object being used - patterns {list[str]} -- A list of data set patterns - - Returns: - set[str]-- Matched VSAM data sets - - Raises: - fail_json: Non-zero return code received while executing ZOAU shell command 'vls' + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used. + patterns : list[str] + A list of data set patterns. + + Returns + ------- + set[str] + Matched VSAM data sets. + + Raises + ------ + fail_json + Non-zero return code received while executing ZOAU shell command 'vls'. """ filtered_data_sets = set() now = time.time() @@ -455,17 +482,26 @@ def data_set_attribute_filter( ): """ Filter data sets based on attributes such as age or size. - Arguments: - module {AnsibleModule} -- The Ansible module object being used - data_sets {set[str]} -- A set of data set names - size {int} -- The size, in bytes, that should be used to filter data sets - age {int} -- The age, in days, that should be used to filter data sets - - Returns: - set[str] -- Matched data sets filtered by age and size - - Raises: - fail_json: Non-zero return code received while executing ZOAU shell command 'dls' + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used. + data_sets : set[str] + A set of data set names. + size : int + The size, in bytes, that should be used to filter data sets. + age : int + The age, in days, that should be used to filter data sets. + + Returns + ------- + set[str] + Matched data sets filtered by age and size. + + Raises + ------ + fail_json + Non-zero return code received while executing ZOAU shell command 'dls'. """ filtered_data_sets = set() now = time.time() @@ -505,16 +541,24 @@ def volume_filter(module, data_sets, volumes): """Return only the data sets that are allocated in one of the volumes from the list of input volumes. - Arguments: - module {AnsibleModule} -- The Ansible module object - data_sets {set[str]} -- A set of data sets to be filtered - volumes {list[str]} -- A list of input volumes - - Returns: - set[str] -- The filtered data sets - - Raises: - fail_json: Unable to retrieve VTOC information + Parameters + ---------- + module : AnsibleModule + The Ansible module object. + data_sets : set[str] + A set of data sets to be filtered. + volumes : list[str] + A list of input volumes. + + Returns + ------- + set[str] + The filtered data sets. + + Raises + ------ + fail_json + Unable to retrieve VTOC information. """ filtered_data_sets = set() for volume in volumes: @@ -532,15 +576,21 @@ def volume_filter(module, data_sets, volumes): def exclude_data_sets(module, data_set_list, excludes): - """Remove data sets that match any pattern in a list of patterns - - Arguments: - module {AnsibleModule} -- The Ansible module object being used - data_set_list {set[str]} -- A set of data sets to be filtered - excludes {list[str]} -- A list of data set patterns to be excluded - - Returns: - set[str] -- The remaining data sets that have not been excluded + """Remove data sets that match any pattern in a list of patterns. + + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used. + data_set_list : set[str] + A set of data sets to be filtered. + excludes : list[str] + A list of data set patterns to be excluded. + + Returns + ------- + set[str] + The remaining data sets that have not been excluded. """ for ds in set(data_set_list): for ex_pat in excludes: @@ -551,15 +601,21 @@ def exclude_data_sets(module, data_set_list, excludes): def _age_filter(ds_date, now, age): - """Determine whether a given date is older than 'age' - - Arguments: - ds_date {str} -- The input date in the format YYYY/MM/DD - now {float} -- The time elapsed since the last epoch - age {int} -- The age, in days, to compare against - - Returns: - bool -- Whether 'ds_date' is older than 'age' + """Determine whether a given date is older than 'age'. + + Parameters + ---------- + ds_date : str + The input date in the format YYYY/MM/DD. + now : float + The time elapsed since the last epoch. + age : int + The age, in days, to compare against. + + Returns + ------- + bool + Whether 'ds_date' is older than 'age'. """ year, month, day = list(map(int, ds_date.split("/"))) if year == "0000": @@ -575,17 +631,24 @@ def _age_filter(ds_date, now, age): def _get_creation_date(module, ds): - """Retrieve the creation date for a given data set - - Arguments: - module {AnsibleModule} -- The Ansible module object being used - ds {str} -- The name of the data set - - Returns: - str -- The data set creation date in the format "YYYY/MM/DD" - - Raises: - fail_json: Non-zero return code received while retrieving data set age + """Retrieve the creation date for a given data set. + + Arguments + --------- + module : AnsibleModule + The Ansible module object being used. + ds : str + The name of the data set. + + Returns + ------- + str + The data set creation date in the format "YYYY/MM/DD". + + Raises + ------ + fail_json + Non-zero return code received while retrieving data set age. """ rc, out, err = mvs_cmd.idcams( " LISTCAT ENT('{0}') HISTORY".format(ds), authorized=True @@ -613,14 +676,19 @@ def _get_creation_date(module, ds): def _size_filter(ds_size, size): - """ Determine whether a given size is greater than the input size - - Arguments: - ds_size {int} -- The input size, in bytes - size {int} -- The size, in bytes, to compare against - - Returns: - bool -- Whether 'ds_size' is greater than 'age' + """Determine whether a given size is greater than the input size. + + Parameters + ---------- + ds_size : int + The input size, in bytes. + size : int + The size, in bytes, to compare against. + + Returns + ------- + bool + Whether 'ds_size' is greater than 'age'. """ if size >= 0 and ds_size >= abs(size): return True @@ -630,18 +698,26 @@ def _size_filter(ds_size, size): def _match_regex(module, pattern, string): - """ Determine whether the input regex pattern matches the string - - Arguments: - module {AnsibleModule} -- The Ansible module object being used - pattern {str} -- The regular expression to match - string {str} -- The string to match - - Returns: - re.Match -- A Match object that matches the pattern to string - - Raises: - fail_json: Invalid regular expression + """Determine whether the input regex pattern matches the string. + + Parameters + ---------- + module : AnsibleModule + The Ansible module object being used. + pattern : str + The regular expression to match. + string : str + The string to match. + + Returns + ------- + re.Match + A Match object that matches the pattern to string. + + Raises + ------ + fail_json + Invalid regular expression. """ try: return fullmatch(pattern, string, re.IGNORECASE) @@ -660,18 +736,27 @@ def _dgrep_wrapper( verbose=False, context=None ): - """A wrapper for ZOAU 'dgrep' shell command - - Arguments: - data_set_pattern {str} -- Data set pattern - content {str} -- Content - ignore_case {bool} -- If ignore case - line_num {bool} -- If line num - verbose {bool} -- If verbose - context {bool} -- If context - - Returns: - tuple[int,str,str] -- Return code, standard output and standard error + """A wrapper for ZOAU 'dgrep' shell command. + + Parameters + ---------- + data_set_pattern : str + Data set pattern. + content : str + Content. + ignore_case : bool + If ignore case. + line_num : bool + If line num. + verbose : bool + If verbose. + context : bool + If context. + + Returns + ------- + tuple(int,str,str) + Return code, standard output and standard error. """ dgrep_cmd = "dgrep" if ignore_case: @@ -695,19 +780,29 @@ def _dls_wrapper( verbose=False, migrated=False ): - """A wrapper for ZOAU 'dls' shell command - - Arguments: - data_set_pattern {str} -- Data set pattern - content {str} -- Content - list_details {bool} -- If list details - u_time {bool} -- If u time - size {bool} -- If size - verbose {bool} -- If verbose - migrated {bool} -- If migrated - - Returns: - tuple[int,str,str] -- Return code, standard output and standard error + """A wrapper for ZOAU 'dls' shell command. + + Parameters + ---------- + data_set_pattern : str + Data set pattern. + content : str + Content. + list_details : bool + If list details. + u_time : bool + If u time. + size : bool + If size. + verbose : bool + If verbose. + migrated : bool + If migrated. + + Returns + ------- + tuple(int,str,str) + Return code, standard output and standard error. """ dls_cmd = "dls" if migrated: @@ -727,15 +822,21 @@ def _dls_wrapper( def _vls_wrapper(pattern, details=False, verbose=False): - """A wrapper for ZOAU 'vls' shell command - - Arguments: - pattern {str} -- Data set pattern - details {bool} -- If details - verbose {bool} -- If verbose - - Returns: - tuple[int,str,str] -- Return code, standard output and standard error + """A wrapper for ZOAU 'vls' shell command. + + Parameters + ---------- + pattern : str + Data set pattern. + details : bool + If details. + verbose : bool + If verbose. + + Returns + ------- + tuple(int,str,str) + Return code, standard output and standard error. """ vls_cmd = "vls" if details: @@ -748,14 +849,19 @@ def _vls_wrapper(pattern, details=False, verbose=False): def _match_resource_type(type1, type2): - """Compare that the two types match - - Arguments: - type1 {str} -- One of the types that are expected to match - type2 {str} -- One of the types that are expected to match - - Returns: - bool -- If the types match + """Compare that the two types match. + + Parameters + ---------- + type1 : str + One of the types that are expected to match. + type2 : str + One of the types that are expected to match. + + Returns + ------- + bool + If the types match. """ if type1 == type2: return True @@ -765,13 +871,17 @@ def _match_resource_type(type1, type2): def _ds_type(ds_name): - """Utility function to determine the DSORG of a data set + """Utility function to determine the DSORG of a data set. - Arguments: - ds_name {str} -- The name of the data set + Parameters + ---------- + ds_name : str + The name of the data set. - Returns: - str -- The DSORG of the data set + Returns + ------- + str + The DSORG of the data set. """ rc, out, err = mvs_cmd.ikjeft01( " LISTDS '{0}'".format(ds_name), @@ -784,17 +894,24 @@ def _ds_type(ds_name): def run_module(module): - """Initialize parameters - - Arguments: - module {AnsibleModule} -- Ansible Module - - Returns: - dict -- Arguments - - Raises: - fail_json: Failed to process age - fail_json: Failed to process size + """Initialize parameters. + + Parameters + ---------- + module : AnsibleModule + Ansible Module. + + Returns + ------- + dict + Arguments. + + Raises + ------ + fail_json + Failed to process age. + fail_json + Failed to process size. """ # Parameter initialization age = module.params.get('age') @@ -892,10 +1009,12 @@ def run_module(module): def main(): - """Initialize module when it's run as main + """Initialize module when it's run as main. - Raises: - fail_json: Parameter verification failed + Raises + ------ + fail_json + Parameter verification failed. """ module = AnsibleModule( argument_spec=dict( From 3b8174b0990dcb77cc010a1fcaf6d2c48bd08039 Mon Sep 17 00:00:00 2001 From: Fernando Flores Date: Mon, 15 Apr 2024 13:05:28 -0600 Subject: [PATCH 4/4] Updated docstrings --- plugins/modules/zos_find.py | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/plugins/modules/zos_find.py b/plugins/modules/zos_find.py index 2bfd953d3..5056cc893 100644 --- a/plugins/modules/zos_find.py +++ b/plugins/modules/zos_find.py @@ -741,17 +741,17 @@ def _dgrep_wrapper( Parameters ---------- data_set_pattern : str - Data set pattern. + Data set pattern where to search for content. content : str - Content. + Content to search across the data sets specified in data_set_pattern. ignore_case : bool - If ignore case. + Whether to ignore case or not. line_num : bool - If line num. + Whether to display line numbers. verbose : bool - If verbose. - context : bool - If context. + Extra verbosity, prints names of datasets being searched. + context : int + If context lines are requested, then up to lines before and after the matching line are also printed. Returns ------- @@ -786,18 +786,16 @@ def _dls_wrapper( ---------- data_set_pattern : str Data set pattern. - content : str - Content. list_details : bool - If list details. + Display detailed information based on the dataset type. u_time : bool - If u time. + Display last usage time. size : bool - If size. + Display size in list. verbose : bool - If verbose. + Display verbose information. migrated : bool - If migrated. + Display migrated data sets. Returns ------- @@ -829,9 +827,9 @@ def _vls_wrapper(pattern, details=False, verbose=False): pattern : str Data set pattern. details : bool - If details. + Display detailed information based on the dataset type. verbose : bool - If verbose. + Display verbose information. Returns -------