From bdeae62b3b85458c303d7e3b08189e6658bc211c Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Tue, 26 Mar 2024 10:59:23 -0600 Subject: [PATCH 1/4] Standarize doc-strings on modules/zos_backup_restore.py --- plugins/modules/zos_backup_restore.py | 173 ++++++++++++++------------ 1 file changed, 90 insertions(+), 83 deletions(-) diff --git a/plugins/modules/zos_backup_restore.py b/plugins/modules/zos_backup_restore.py index 3185652e1..2a10c6dea 100644 --- a/plugins/modules/zos_backup_restore.py +++ b/plugins/modules/zos_backup_restore.py @@ -333,7 +333,11 @@ def main(): - """Run the zos_backup_restore module core functions.""" + """Run the zos_backup_restore module core functions. + + Raises: + fail_json: Any error ocurred during execution. + """ result = dict(changed=False, message="", backup_name="") module_args = dict( operation=dict(type="str", required=True, choices=["backup", "restore"]), @@ -420,11 +424,11 @@ def main(): def parse_and_validate_args(params): """Parse and validate arguments to be used by remainder of module. - Args: - params (dict): The params as returned from AnsibleModule instantiation. + Arguments: + params {dict} -- The params as returned from AnsibleModule instantiation. Returns: - dict: The updated params after additional parsing and validation. + dict -- The updated params after additional parsing and validation. """ arg_defs = dict( operation=dict(type="str", required=True, choices=["backup", "restore"]), @@ -484,20 +488,20 @@ def backup( ): """Backup data sets or a volume to a new data set or unix file. - Args: - backup_name (str): The data set or UNIX path to place the backup. - include_data_sets (list): A list of data set patterns to include in the backup. - exclude_data_sets (list): A list of data set patterns to exclude from the backup. - volume (str): The volume that contains the data sets to backup. - full_volume (bool): Specifies if a backup will be made of the entire volume. - temp_volume (bool): Specifies the volume that should be used to store temporary files. - overwrite (bool): Specifies if existing data set or UNIX file matching I(backup_name) should be deleted. - recover (bool): Specifies if potentially recoverable errors should be ignored. - space (int): Specifies the amount of space to allocate for the backup. - space_type (str): The unit of measurement to use when defining data set space. - sms_storage_class (str): Specifies the storage class to use. - sms_management_class (str): Specifies the management class to use. - tmp_hlq (str): Specifies the tmp hlq to temporary datasets + Arguments: + backup_name {str} -- The data set or UNIX path to place the backup. + include_data_sets {list} -- A list of data set patterns to include in the backup. + exclude_data_sets {list} -- A list of data set patterns to exclude from the backup. + volume {str} -- The volume that contains the data sets to backup. + full_volume {bool} -- Specifies if a backup will be made of the entire volume. + temp_volume {bool} -- Specifies the volume that should be used to store temporary files. + overwrite {bool} -- Specifies if existing data set or UNIX file matching I(backup_name) should be deleted. + recover {bool} -- Specifies if potentially recoverable errors should be ignored. + space {int} -- Specifies the amount of space to allocate for the backup. + space_type {str} -- The unit of measurement to use when defining data set space. + sms_storage_class {str} -- Specifies the storage class to use. + sms_management_class {str} -- Specifies the management class to use. + tmp_hlq {str} -- Specifies the tmp hlq to temporary datasets """ args = locals() zoau_args = to_dzip_args(**args) @@ -520,27 +524,30 @@ def restore( sms_management_class, tmp_hlq, ): - """[summary] + """Restore data sets or a volume from the backup. - Args: - backup_name (str): The data set or UNIX path containing the backup. - include_data_sets (list): A list of data set patterns to include in the restore + Arguments: + backup_name {str} -- The data set or UNIX path containing the backup. + include_data_sets {list} -- A list of data set patterns to include in the restore that are present in the backup. - exclude_data_sets (list): A list of data set patterns to exclude from the restore + exclude_data_sets {list} -- A list of data set patterns to exclude from the restore that are present in the backup. - volume (str): The volume that contains the data sets to backup. - full_volume (bool): Specifies if a backup will be made of the entire volume. - temp_volume (bool): Specifies the volume that should be used to store temporary files. - overwrite (bool): Specifies if module should overwrite existing data sets with + volume {str} -- The volume that contains the data sets to backup. + full_volume {bool} -- Specifies if a backup will be made of the entire volume. + temp_volume {bool} -- Specifies the volume that should be used to store temporary files. + overwrite {bool} -- Specifies if module should overwrite existing data sets with matching name on the target device. - recover (bool): Specifies if potentially recoverable errors should be ignored. - hlq (str): Specifies the new HLQ to use for the data sets being restored. - space (int): Specifies the amount of space to allocate for data sets temporarily + recover {bool} -- Specifies if potentially recoverable errors should be ignored. + hlq {str} -- Specifies the new HLQ to use for the data sets being restored. + space {int} -- Specifies the amount of space to allocate for data sets temporarily created during the restore process. - space_type (str): The unit of measurement to use when defining data set space. - sms_storage_class (str): Specifies the storage class to use. - sms_management_class (str): Specifies the management class to use. - tmp_hlq (str): : Specifies the tmp hlq to temporary datasets + space_type {str} -- The unit of measurement to use when defining data set space. + sms_storage_class {str} -- Specifies the storage class to use. + sms_management_class {str} -- Specifies the management class to use. + tmp_hlq {str} -- Specifies the tmp hlq to temporary datasets + + Raises: + ZOAUException: When any exception is raised during the data set allocation """ args = locals() zoau_args = to_dunzip_args(**args) @@ -566,11 +573,11 @@ def restore( def get_real_rc(output): """Parse out the final RC from MVS program output. - Args: - output (str): The MVS program output. + Arguments: + output {str} -- The MVS program output. Returns: - int: The true program RC. + int -- The true program RC. """ true_rc = None match = search( @@ -585,16 +592,16 @@ def get_real_rc(output): def data_set_pattern_type(contents, dependencies): """Validates provided data set patterns. - Args: - contents (Union[str, list[str]]): One or more data set patterns - dependencies (dict): Any dependent arguments + Arguments: + contents {Union[str, list[str]} --: One or more data set patterns + dependencies {dict} -- Any dependent arguments + + Returns: + list[str] -- A list of uppercase data set patterns Raises: ValueError: When provided argument is not a string or a list ValueError: When provided argument is an invalid data set pattern - - Returns: - list[str]: A list of uppercase data set patterns """ if contents is None: return None @@ -619,16 +626,16 @@ def data_set_pattern_type(contents, dependencies): def hlq_type(contents, dependencies): """Validates provided HLQ is valid and is not specified for a backup operation. - Args: - contents (str): The HLQ to use - dependencies (dict): Any dependent arguments + Arguments: + contents {str} -- The HLQ to use + dependencies {dict} -- Any dependent arguments + + Returns: + str -- The HLQ to use Raises: ValueError: When operation is restore and HLQ is provided ValueError: When an invalid HLQ is provided - - Returns: - str: The HLQ to use """ if contents is None: return None @@ -642,12 +649,12 @@ def hlq_type(contents, dependencies): def hlq_default(contents, dependencies): """Sets the default HLQ to use if none is provided. - Args: - contents (str): The HLQ to use - dependencies (dict): Any dependent arguments + Arguments: + contents {str} -- The HLQ to use + dependencies {dict} -- Any dependent arguments Returns: - str: The HLQ to use + str -- The HLQ to use """ hlq = None if dependencies.get("operation") == "restore": @@ -658,15 +665,15 @@ def hlq_default(contents, dependencies): def sms_type(contents, dependencies): """Validates the SMS class provided matches a valid format. - Args: - contents (str): The SMS class name - dependencies (dict): Any dependent arguments + Arguments: + contents {str} -- The SMS class name + dependencies {dict} -- Any dependent arguments + + Returns: + str -- The uppercase SMS class name Raises: ValueError: When invalid argument provided for SMS class. - - Returns: - str: The uppercase SMS class name """ if contents is None: return None @@ -678,12 +685,12 @@ def sms_type(contents, dependencies): def space_type(contents, dependencies): """Validates amount of space provided. - Args: - contents (str): The amount of space - dependencies (dict): Any dependent arguments + Arguments: + contents {str} -- The amount of space + dependencies {dict} -- Any dependent arguments Returns: - int: The amount of space + int -- The amount of space """ if contents is None: if dependencies.get("full_volume"): @@ -697,15 +704,15 @@ def space_type_type(contents, dependencies): """Validates provided data set unit of space. Returns the unit of space. - Args: - contents (str): The space type to use - dependencies (dict): Any dependent arguments + Arguments: + contents {str} -- The space type to use + dependencies {dict} -- Any dependent arguments + + Returns: + str -- The unit of space Raises: ValueError: When an invalid space unit is provided - - Returns: - str: The unit of space """ if contents is None: if dependencies.get("full_volume"): @@ -724,15 +731,15 @@ def space_type_type(contents, dependencies): def backup_name_type(contents, dependencies): """Validates provided backup name. - Args: - contents (str): The backup name to use - dependencies (dict): Any dependent arguments + Arguments: + contents {str} -- The backup name to use + dependencies {dict} -- Any dependent arguments + + Returns: + str -- The backup name to use Raises: ValueError: When an invalid backup name is provided - - Returns: - str: The backup name to use """ if contents is None: return None @@ -751,15 +758,15 @@ def backup_name_type(contents, dependencies): def full_volume_type(contents, dependencies): """Validates dependent arguments are also specified for full_volume argument. - Args: - contents (bool): Whether we are making a full volume backup or not - dependencies (dict): Any dependent arguments + Arguments: + contents {bool} -- Whether we are making a full volume backup or not + dependencies {dict} -- Any dependent arguments + + Returns: + bool -- Whether we are making a full volume backup or not Raises: ValueError: When volume argument is not provided - - Returns: - bool: Whether we are making a full volume backup or not """ if contents is True and dependencies.get("volume") is None: raise ValueError("full_volume=True is only valid when volume is specified.") @@ -770,7 +777,7 @@ def to_dzip_args(**kwargs): """API adapter for ZOAU dzip method. Returns: - dict: The arguments for ZOAU dzip method translated from module arguments + dict -- The arguments for ZOAU dzip method translated from module arguments """ zoau_args = {} if kwargs.get("backup_name"): @@ -822,7 +829,7 @@ def to_dunzip_args(**kwargs): """API adapter for ZOAU dunzip method. Returns: - dict: The arguments for ZOAU dunzip method translated from module arguments + dict -- The arguments for ZOAU dunzip method translated from module arguments """ zoau_args = {} if kwargs.get("backup_name"): From 872eae94dfa6ad32d428351febeb75e61132c189 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Fri, 29 Mar 2024 14:40:28 -0600 Subject: [PATCH 2/4] Create changelog fragment --- .../fragments/1342-update-docstring-zos_backup_restore.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelogs/fragments/1342-update-docstring-zos_backup_restore.yml diff --git a/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml b/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml new file mode 100644 index 000000000..e6828870c --- /dev/null +++ b/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml @@ -0,0 +1,3 @@ +trivial: + - zos_backup_restore - Updated docstrings to google style for visual aid to developers. + (https://github.com/ansible-collections/ibm_zos_core/pull/1342). \ No newline at end of file From f4d4f11ef68bf0fb8e8742856012d8c6144b44a8 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Mon, 1 Apr 2024 14:57:54 -0600 Subject: [PATCH 3/4] Modify google style to numpy --- ...42-update-docstring-zos_backup_restore.yml | 2 +- plugins/modules/zos_backup_restore.py | 337 +++++++++++------- 2 files changed, 219 insertions(+), 120 deletions(-) diff --git a/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml b/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml index e6828870c..07e529c72 100644 --- a/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml +++ b/changelogs/fragments/1342-update-docstring-zos_backup_restore.yml @@ -1,3 +1,3 @@ trivial: - - zos_backup_restore - Updated docstrings to google style for visual aid to developers. + - zos_backup_restore - Updated docstrings to numpy style for visual aid to developers. (https://github.com/ansible-collections/ibm_zos_core/pull/1342). \ No newline at end of file diff --git a/plugins/modules/zos_backup_restore.py b/plugins/modules/zos_backup_restore.py index 2a10c6dea..900e3843d 100644 --- a/plugins/modules/zos_backup_restore.py +++ b/plugins/modules/zos_backup_restore.py @@ -334,9 +334,11 @@ def main(): """Run the zos_backup_restore module core functions. - - Raises: - fail_json: Any error ocurred during execution. + + Raises + ------ + fail_json + Any error ocurred during execution. """ result = dict(changed=False, message="", backup_name="") module_args = dict( @@ -424,11 +426,15 @@ def main(): def parse_and_validate_args(params): """Parse and validate arguments to be used by remainder of module. - Arguments: - params {dict} -- The params as returned from AnsibleModule instantiation. + Parameters + ---------- + params : dict + The params as returned from AnsibleModule instantiation. - Returns: - dict -- The updated params after additional parsing and validation. + Returns + ------- + dict + The updated params after additional parsing and validation. """ arg_defs = dict( operation=dict(type="str", required=True, choices=["backup", "restore"]), @@ -488,20 +494,34 @@ def backup( ): """Backup data sets or a volume to a new data set or unix file. - Arguments: - backup_name {str} -- The data set or UNIX path to place the backup. - include_data_sets {list} -- A list of data set patterns to include in the backup. - exclude_data_sets {list} -- A list of data set patterns to exclude from the backup. - volume {str} -- The volume that contains the data sets to backup. - full_volume {bool} -- Specifies if a backup will be made of the entire volume. - temp_volume {bool} -- Specifies the volume that should be used to store temporary files. - overwrite {bool} -- Specifies if existing data set or UNIX file matching I(backup_name) should be deleted. - recover {bool} -- Specifies if potentially recoverable errors should be ignored. - space {int} -- Specifies the amount of space to allocate for the backup. - space_type {str} -- The unit of measurement to use when defining data set space. - sms_storage_class {str} -- Specifies the storage class to use. - sms_management_class {str} -- Specifies the management class to use. - tmp_hlq {str} -- Specifies the tmp hlq to temporary datasets + Parameters + ---------- + backup_name : str + The data set or UNIX path to place the backup. + include_data_sets : list + A list of data set patterns to include in the backup. + exclude_data_sets : list + A list of data set patterns to exclude from the backup. + volume : str + The volume that contains the data sets to backup. + full_volume : bool + Specifies if a backup will be made of the entire volume. + temp_volume : bool + Specifies the volume that should be used to store temporary files. + overwrite : bool + Specifies if existing data set or UNIX file matching I(backup_name) should be deleted. + recover : bool + Specifies if potentially recoverable errors should be ignored. + space : int + Specifies the amount of space to allocate for the backup. + space_type : str + The unit of measurement to use when defining data set space. + sms_storage_class : str + Specifies the storage class to use. + sms_management_class : str + Specifies the management class to use. + tmp_hlq : str + Specifies the tmp hlq to temporary datasets """ args = locals() zoau_args = to_dzip_args(**args) @@ -526,28 +546,45 @@ def restore( ): """Restore data sets or a volume from the backup. - Arguments: - backup_name {str} -- The data set or UNIX path containing the backup. - include_data_sets {list} -- A list of data set patterns to include in the restore - that are present in the backup. - exclude_data_sets {list} -- A list of data set patterns to exclude from the restore - that are present in the backup. - volume {str} -- The volume that contains the data sets to backup. - full_volume {bool} -- Specifies if a backup will be made of the entire volume. - temp_volume {bool} -- Specifies the volume that should be used to store temporary files. - overwrite {bool} -- Specifies if module should overwrite existing data sets with - matching name on the target device. - recover {bool} -- Specifies if potentially recoverable errors should be ignored. - hlq {str} -- Specifies the new HLQ to use for the data sets being restored. - space {int} -- Specifies the amount of space to allocate for data sets temporarily - created during the restore process. - space_type {str} -- The unit of measurement to use when defining data set space. - sms_storage_class {str} -- Specifies the storage class to use. - sms_management_class {str} -- Specifies the management class to use. - tmp_hlq {str} -- Specifies the tmp hlq to temporary datasets - - Raises: - ZOAUException: When any exception is raised during the data set allocation + Parameters + ---------- + backup_name : str + The data set or UNIX path containing the backup. + include_data_sets : list + A list of data set patterns to include in the restore + that are present in the backup. + exclude_data_sets : list + A list of data set patterns to exclude from the restore + that are present in the backup. + volume : str + The volume that contains the data sets to backup. + full_volume : bool + Specifies if a backup will be made of the entire volume. + temp_volume : bool + Specifies the volume that should be used to store temporary files. + overwrite : bool + Specifies if module should overwrite existing data sets with + matching name on the target device. + recover : bool + Specifies if potentially recoverable errors should be ignored. + hlq : str + Specifies the new HLQ to use for the data sets being restored. + space : int + Specifies the amount of space to allocate for data sets temporarily + created during the restore process. + space_type : str + The unit of measurement to use when defining data set space. + sms_storage_class : str + Specifies the storage class to use. + sms_management_class : str + Specifies the management class to use. + tmp_hlq : str + Specifies the tmp hlq to temporary datasets + + Raises + ------ + ZOAUException + When any exception is raised during the data set allocation """ args = locals() zoau_args = to_dunzip_args(**args) @@ -573,11 +610,15 @@ def restore( def get_real_rc(output): """Parse out the final RC from MVS program output. - Arguments: - output {str} -- The MVS program output. + Parameters + ---------- + output : str + The MVS program output. - Returns: - int -- The true program RC. + Returns + ------- + int + The true program RC. """ true_rc = None match = search( @@ -592,16 +633,24 @@ def get_real_rc(output): def data_set_pattern_type(contents, dependencies): """Validates provided data set patterns. - Arguments: - contents {Union[str, list[str]} --: One or more data set patterns - dependencies {dict} -- Any dependent arguments - - Returns: - list[str] -- A list of uppercase data set patterns - - Raises: - ValueError: When provided argument is not a string or a list - ValueError: When provided argument is an invalid data set pattern + Parameters + ---------- + contents : Union[str, list[str] + One or more data set patterns + dependencies : dict + Any dependent arguments + + Returns + ------- + list[str] + A list of uppercase data set patterns + + Raises + ------ + ValueError + When provided argument is not a string or a list + ValueError + When provided argument is an invalid data set pattern """ if contents is None: return None @@ -626,16 +675,24 @@ def data_set_pattern_type(contents, dependencies): def hlq_type(contents, dependencies): """Validates provided HLQ is valid and is not specified for a backup operation. - Arguments: - contents {str} -- The HLQ to use - dependencies {dict} -- Any dependent arguments - - Returns: - str -- The HLQ to use - - Raises: - ValueError: When operation is restore and HLQ is provided - ValueError: When an invalid HLQ is provided + Parameters + ---------- + contents : str + The HLQ to use + dependencies : dict + Any dependent arguments + + Returns + ------- + str + The HLQ to use + + Raises + ------ + ValueError + When operation is restore and HLQ is provided + ValueError + When an invalid HLQ is provided """ if contents is None: return None @@ -649,12 +706,17 @@ def hlq_type(contents, dependencies): def hlq_default(contents, dependencies): """Sets the default HLQ to use if none is provided. - Arguments: - contents {str} -- The HLQ to use - dependencies {dict} -- Any dependent arguments - - Returns: - str -- The HLQ to use + Parameters + ---------- + contents : str + The HLQ to use + dependencies : dict + Any dependent arguments + + Returns + ------- + str + The HLQ to use """ hlq = None if dependencies.get("operation") == "restore": @@ -665,15 +727,22 @@ def hlq_default(contents, dependencies): def sms_type(contents, dependencies): """Validates the SMS class provided matches a valid format. - Arguments: - contents {str} -- The SMS class name - dependencies {dict} -- Any dependent arguments - - Returns: - str -- The uppercase SMS class name - - Raises: - ValueError: When invalid argument provided for SMS class. + Parameters + ---------- + contents : str + The SMS class name + dependencies : dict + Any dependent arguments + + Returns + ------- + str + The uppercase SMS class name + + Raises + ------ + ValueError + When invalid argument provided for SMS class. """ if contents is None: return None @@ -685,12 +754,17 @@ def sms_type(contents, dependencies): def space_type(contents, dependencies): """Validates amount of space provided. - Arguments: - contents {str} -- The amount of space - dependencies {dict} -- Any dependent arguments - - Returns: - int -- The amount of space + Parameters + ---------- + contents : str + The amount of space + dependencies : dict + Any dependent arguments + + Returns + ------- + int + The amount of space """ if contents is None: if dependencies.get("full_volume"): @@ -704,15 +778,22 @@ def space_type_type(contents, dependencies): """Validates provided data set unit of space. Returns the unit of space. - Arguments: - contents {str} -- The space type to use - dependencies {dict} -- Any dependent arguments - - Returns: - str -- The unit of space - - Raises: - ValueError: When an invalid space unit is provided + Parameters + ---------- + contents : str + The space type to use + dependencies : dict + Any dependent arguments + + Returns + ------- + str + The unit of space + + Raises + ------ + ValueError + When an invalid space unit is provided """ if contents is None: if dependencies.get("full_volume"): @@ -731,15 +812,22 @@ def space_type_type(contents, dependencies): def backup_name_type(contents, dependencies): """Validates provided backup name. - Arguments: - contents {str} -- The backup name to use - dependencies {dict} -- Any dependent arguments - - Returns: - str -- The backup name to use - - Raises: - ValueError: When an invalid backup name is provided + Parameters + ---------- + contents : str + The backup name to use + dependencies : dict + Any dependent arguments + + Returns + ------- + str + The backup name to use + + Raises + ------ + ValueError + When an invalid backup name is provided """ if contents is None: return None @@ -758,15 +846,22 @@ def backup_name_type(contents, dependencies): def full_volume_type(contents, dependencies): """Validates dependent arguments are also specified for full_volume argument. - Arguments: - contents {bool} -- Whether we are making a full volume backup or not - dependencies {dict} -- Any dependent arguments - - Returns: - bool -- Whether we are making a full volume backup or not - - Raises: - ValueError: When volume argument is not provided + Parameters + ---------- + contents : bool + Whether we are making a full volume backup or not + dependencies : dict + Any dependent arguments + + Returns + ------- + bool + Whether we are making a full volume backup or not + + Raises + ------ + ValueError + When volume argument is not provided """ if contents is True and dependencies.get("volume") is None: raise ValueError("full_volume=True is only valid when volume is specified.") @@ -776,8 +871,10 @@ def full_volume_type(contents, dependencies): def to_dzip_args(**kwargs): """API adapter for ZOAU dzip method. - Returns: - dict -- The arguments for ZOAU dzip method translated from module arguments + Returns + ------- + dict + The arguments for ZOAU dzip method translated from module arguments """ zoau_args = {} if kwargs.get("backup_name"): @@ -828,8 +925,10 @@ def to_dzip_args(**kwargs): def to_dunzip_args(**kwargs): """API adapter for ZOAU dunzip method. - Returns: - dict -- The arguments for ZOAU dunzip method translated from module arguments + Returns + ------- + dict + The arguments for ZOAU dunzip method translated from module arguments """ zoau_args = {} if kwargs.get("backup_name"): From d55726b518ab1117af481f36f89c95072e8f8168 Mon Sep 17 00:00:00 2001 From: IsaacVRey Date: Wed, 3 Apr 2024 11:04:34 -0600 Subject: [PATCH 4/4] Standarize numpy style --- plugins/modules/zos_backup_restore.py | 260 +++++++++++++------------- 1 file changed, 130 insertions(+), 130 deletions(-) diff --git a/plugins/modules/zos_backup_restore.py b/plugins/modules/zos_backup_restore.py index 900e3843d..e0486d994 100644 --- a/plugins/modules/zos_backup_restore.py +++ b/plugins/modules/zos_backup_restore.py @@ -337,8 +337,8 @@ def main(): Raises ------ - fail_json - Any error ocurred during execution. + fail_json + Any error ocurred during execution. """ result = dict(changed=False, message="", backup_name="") module_args = dict( @@ -428,13 +428,13 @@ def parse_and_validate_args(params): Parameters ---------- - params : dict - The params as returned from AnsibleModule instantiation. + params : dict + The params as returned from AnsibleModule instantiation. Returns ------- - dict - The updated params after additional parsing and validation. + dict + The updated params after additional parsing and validation. """ arg_defs = dict( operation=dict(type="str", required=True, choices=["backup", "restore"]), @@ -496,32 +496,32 @@ def backup( Parameters ---------- - backup_name : str - The data set or UNIX path to place the backup. - include_data_sets : list - A list of data set patterns to include in the backup. - exclude_data_sets : list - A list of data set patterns to exclude from the backup. - volume : str - The volume that contains the data sets to backup. - full_volume : bool - Specifies if a backup will be made of the entire volume. - temp_volume : bool - Specifies the volume that should be used to store temporary files. - overwrite : bool - Specifies if existing data set or UNIX file matching I(backup_name) should be deleted. - recover : bool - Specifies if potentially recoverable errors should be ignored. - space : int - Specifies the amount of space to allocate for the backup. - space_type : str - The unit of measurement to use when defining data set space. - sms_storage_class : str - Specifies the storage class to use. - sms_management_class : str - Specifies the management class to use. - tmp_hlq : str - Specifies the tmp hlq to temporary datasets + backup_name : str + The data set or UNIX path to place the backup. + include_data_sets : list + A list of data set patterns to include in the backup. + exclude_data_sets : list + A list of data set patterns to exclude from the backup. + volume : str + The volume that contains the data sets to backup. + full_volume : bool + Specifies if a backup will be made of the entire volume. + temp_volume : bool + Specifies the volume that should be used to store temporary files. + overwrite : bool + Specifies if existing data set or UNIX file matching I(backup_name) should be deleted. + recover : bool + Specifies if potentially recoverable errors should be ignored. + space : int + Specifies the amount of space to allocate for the backup. + space_type : str + The unit of measurement to use when defining data set space. + sms_storage_class : str + Specifies the storage class to use. + sms_management_class : str + Specifies the management class to use. + tmp_hlq : str + Specifies the tmp hlq to temporary datasets. """ args = locals() zoau_args = to_dzip_args(**args) @@ -548,43 +548,43 @@ def restore( Parameters ---------- - backup_name : str - The data set or UNIX path containing the backup. - include_data_sets : list - A list of data set patterns to include in the restore - that are present in the backup. - exclude_data_sets : list - A list of data set patterns to exclude from the restore - that are present in the backup. - volume : str - The volume that contains the data sets to backup. - full_volume : bool - Specifies if a backup will be made of the entire volume. - temp_volume : bool - Specifies the volume that should be used to store temporary files. - overwrite : bool - Specifies if module should overwrite existing data sets with - matching name on the target device. - recover : bool - Specifies if potentially recoverable errors should be ignored. - hlq : str - Specifies the new HLQ to use for the data sets being restored. - space : int - Specifies the amount of space to allocate for data sets temporarily - created during the restore process. - space_type : str - The unit of measurement to use when defining data set space. - sms_storage_class : str - Specifies the storage class to use. - sms_management_class : str - Specifies the management class to use. - tmp_hlq : str - Specifies the tmp hlq to temporary datasets + backup_name : str + The data set or UNIX path containing the backup. + include_data_sets : list + A list of data set patterns to include in the restore + that are present in the backup. + exclude_data_sets : list + A list of data set patterns to exclude from the restore + that are present in the backup. + volume : str + The volume that contains the data sets to backup. + full_volume : bool + Specifies if a backup will be made of the entire volume. + temp_volume : bool + Specifies the volume that should be used to store temporary files. + overwrite : bool + Specifies if module should overwrite existing data sets with + matching name on the target device. + recover : bool + Specifies if potentially recoverable errors should be ignored. + hlq : str + Specifies the new HLQ to use for the data sets being restored. + space : int + Specifies the amount of space to allocate for data sets temporarily + created during the restore process. + space_type : str + The unit of measurement to use when defining data set space. + sms_storage_class : str + Specifies the storage class to use. + sms_management_class : str + Specifies the management class to use. + tmp_hlq : str + Specifies the tmp hlq to temporary datasets. Raises ------ - ZOAUException - When any exception is raised during the data set allocation + ZOAUException + When any exception is raised during the data set allocation. """ args = locals() zoau_args = to_dunzip_args(**args) @@ -612,13 +612,13 @@ def get_real_rc(output): Parameters ---------- - output : str - The MVS program output. + output : str + The MVS program output. Returns ------- - int - The true program RC. + int + The true program RC. """ true_rc = None match = search( @@ -635,22 +635,22 @@ def data_set_pattern_type(contents, dependencies): Parameters ---------- - contents : Union[str, list[str] - One or more data set patterns - dependencies : dict - Any dependent arguments + contents : Union[str, list[str] + One or more data set patterns. + dependencies : dict + Any dependent arguments. Returns ------- - list[str] - A list of uppercase data set patterns + Union[str] + A list of uppercase data set patterns. Raises ------ - ValueError - When provided argument is not a string or a list - ValueError - When provided argument is an invalid data set pattern + ValueError + When provided argument is not a string or a list. + ValueError + When provided argument is an invalid data set pattern. """ if contents is None: return None @@ -677,22 +677,22 @@ def hlq_type(contents, dependencies): Parameters ---------- - contents : str - The HLQ to use - dependencies : dict - Any dependent arguments + contents : str + The HLQ to use. + dependencies : dict + Any dependent arguments. Returns ------- - str - The HLQ to use + str + The HLQ to use. Raises ------ - ValueError - When operation is restore and HLQ is provided - ValueError - When an invalid HLQ is provided + ValueError + When operation is restore and HLQ is provided. + ValueError + When an invalid HLQ is provided. """ if contents is None: return None @@ -708,15 +708,15 @@ def hlq_default(contents, dependencies): Parameters ---------- - contents : str - The HLQ to use - dependencies : dict - Any dependent arguments + contents : str + The HLQ to use. + dependencies : dict + Any dependent arguments. Returns ------- - str - The HLQ to use + str + The HLQ to use. """ hlq = None if dependencies.get("operation") == "restore": @@ -729,20 +729,20 @@ def sms_type(contents, dependencies): Parameters ---------- - contents : str - The SMS class name - dependencies : dict - Any dependent arguments + contents : str + The SMS class name. + dependencies : dict + Any dependent arguments. Returns ------- - str - The uppercase SMS class name + str + The uppercase SMS class name. Raises ------ - ValueError - When invalid argument provided for SMS class. + ValueError + When invalid argument provided for SMS class. """ if contents is None: return None @@ -756,15 +756,15 @@ def space_type(contents, dependencies): Parameters ---------- - contents : str - The amount of space - dependencies : dict - Any dependent arguments + contents : str + The amount of space. + dependencies : dict + Any dependent arguments. Returns ------- - int - The amount of space + int + The amount of space. """ if contents is None: if dependencies.get("full_volume"): @@ -780,20 +780,20 @@ def space_type_type(contents, dependencies): Parameters ---------- - contents : str - The space type to use - dependencies : dict - Any dependent arguments + contents : str + The space type to use. + dependencies : dict + Any dependent arguments. Returns ------- - str - The unit of space + str + The unit of space. Raises ------ - ValueError - When an invalid space unit is provided + ValueError + When an invalid space unit is provided. """ if contents is None: if dependencies.get("full_volume"): @@ -848,20 +848,20 @@ def full_volume_type(contents, dependencies): Parameters ---------- - contents : bool - Whether we are making a full volume backup or not - dependencies : dict - Any dependent arguments + contents : bool + Whether we are making a full volume backup or not. + dependencies : dict + Any dependent arguments. Returns ------- - bool - Whether we are making a full volume backup or not + bool + Whether we are making a full volume backup or not. Raises ------ - ValueError - When volume argument is not provided + ValueError + When volume argument is not provided. """ if contents is True and dependencies.get("volume") is None: raise ValueError("full_volume=True is only valid when volume is specified.") @@ -873,8 +873,8 @@ def to_dzip_args(**kwargs): Returns ------- - dict - The arguments for ZOAU dzip method translated from module arguments + dict + The arguments for ZOAU dzip method translated from module arguments. """ zoau_args = {} if kwargs.get("backup_name"): @@ -927,8 +927,8 @@ def to_dunzip_args(**kwargs): Returns ------- - dict - The arguments for ZOAU dunzip method translated from module arguments + dict + The arguments for ZOAU dunzip method translated from module arguments. """ zoau_args = {} if kwargs.get("backup_name"):