[Documentation][backup] Add and standarize docstrings on module-utils/backup.py (#1384)

* Modify google style docstrings to numpy

* Add changelog fragment

* Update backup.py

Added ending linefeed to address pep8 issue

* Update backup.py

fix pep8 (extra whitespace at end of file)

* modified docstring

---------

Co-authored-by: Rich Parker <[email protected]>
Co-authored-by: Fernando Flores <[email protected]>

Author: 3 people

changelogs/fragments/1384-update-docstring-backup.yml

@@ -0,0 +1,3 @@
+trivial:
+  - backup - Updated docstrings to numpy style for visual aid to developers.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1384).

plugins/module_utils/backup.py

@@ -51,23 +51,46 @@
 
 
 def _validate_data_set_name(ds):
+    """Validate data set name.
+
+    Parameters
+    ----------
+    ds : str
+        The source dataset.
+
+    Returns
+    -------
+    str
+        Parsed dataset.
+    """
     arg_defs = dict(ds=dict(arg_type="data_set"))
     parser = BetterArgParser(arg_defs)
     parsed_args = parser.parse_args({"ds": ds})
     return parsed_args.get("ds")
 
 
 def mvs_file_backup(dsn, bk_dsn=None, tmphlq=None):
-    """Create a backup data set for an MVS data set
-
-    Arguments:
-        dsn {str} -- The name of the data set to backup.
-                        It could be an MVS PS/PDS/PDSE/VSAM(KSDS), etc.
-        bk_dsn {str} -- The name of the backup data set.
-
-    Raises:
-        BackupError: When backup data set exists.
-        BackupError: When creation of backup data set fails.
+    """Create a backup data set for an MVS data set.
+
+    Parameters
+    ----------
+    dsn : str
+        The name of the data set to backup.
+        It could be an MVS PS/PDS/PDSE/VSAM(KSDS), etc.
+    bk_dsn : str
+        The name of the backup data set.
+
+    Returns
+    -------
+    str
+        The backup dataset
+
+    Raises
+    ------
+    BackupError
+        When backup data set exists.
+    BackupError
+        When creation of backup data set fails.
     """
     dsn = _validate_data_set_name(dsn).upper()
     if is_member(dsn):
@@ -98,7 +121,7 @@ def mvs_file_backup(dsn, bk_dsn=None, tmphlq=None):
 
         # In case the backup ds is a member we trust that the PDS attributes are ok to fit the src content.
         # This should not delete a PDS just to create a backup member.
-        # Otherwise, we allocate the appropiate space for the backup ds based on src.
+        # Otherwise, we allocate the appropriate space for the backup ds based on src.
         if is_member(bk_dsn):
             try:
                 cp_rc = datasets.copy(dsn, bk_dsn)
@@ -122,20 +145,29 @@ def mvs_file_backup(dsn, bk_dsn=None, tmphlq=None):
 
 
 def uss_file_backup(path, backup_name=None, compress=False):
-    """Create a backup file for a USS file or path
-
-    Arguments:
-        path {str} -- The name of the USS file or path to backup.
-        backup_name {str} -- The name of the backup file.
-
-    Keyword Arguments:
-        compress {bool} -- Determines if the backup be compressed. (default: {False})
-
-    Raises:
-        BackupError: When creating compressed backup fails.
-
-    Returns:
-        str -- Name of the backup file.
+    """Create a backup file for a USS file or path.
+
+    Parameters
+    ----------
+    path : str
+        The name of the USS file or path to backup.
+    backup_name : str
+        The name of the backup file.
+
+    Keyword Parameters
+    ------------------
+    compress : bool
+        Determines if the backup be compressed. (default: {False})
+
+    Returns
+    -------
+    str
+        Name of the backup file.
+
+    Raises
+    ------
+    BackupError
+        When creating compressed backup fails.
     """
     abs_path = os.path.abspath(path)
 
@@ -188,14 +220,24 @@ def uss_file_backup(path, backup_name=None, compress=False):
 
 
 def _copy_ds(ds, bk_ds):
-    """Copy the contents of a data set to another
-
-    Arguments:
-        ds {str} -- The source data set to be copied from. Should be SEQ or VSAM
-        bk_dsn {str} -- The destination data set to copy to.
-
-    Raises:
-        BackupError: When copying data fails
+    """Copy the contents of a data set to another.
+
+    Parameters
+    ----------
+    ds : str
+        The source data set to be copied from. Should be SEQ or VSAM.
+    bk_dsn : str
+        The destination data set to copy to.
+
+    Returns
+    -------
+    int
+        Return code.
+
+    Raises
+    ------
+    BackupError
+        When copying data fails.
     """
     module = AnsibleModuleHelper(argument_spec={})
     _allocate_model(bk_ds, ds)
@@ -220,14 +262,24 @@ def _copy_ds(ds, bk_ds):
 
 
 def _allocate_model(ds, model):
-    """Allocate a data set using allocation information of a model data set
-
-    Arguments:
-        ds {str} -- The name of the data set to be allocated.
-        model {str} -- The name of the data set whose allocation parameters should be used.
-
-    Raises:
-        BackupError: When allocation fails
+    """Allocate a data set using allocation information of a model data set.
+
+    Parameters
+    ----------
+    ds : str
+        The name of the data set to be allocated.
+    model : str
+        The name of the data set whose allocation parameters should be used.
+
+    Returns
+    -------
+    int
+        Return code.
+
+    Raises
+    ------
+    BackupError
+        When allocation fails.
     """
     module = AnsibleModuleHelper(argument_spec={})
     alloc_cmd = """  ALLOC -
@@ -247,13 +299,51 @@ def _allocate_model(ds, model):
 
 
 def _copy_pds(ds, bk_dsn):
+    """Copy a dataset.
+
+    Parameters
+    ----------
+    ds : str
+        The name of the data set to be allocated.
+    bk_dsn : str
+        The destination data set to copy to.
+
+    Returns
+    -------
+    str
+        Copied dataset.
+    """
     dds = dict(OUTPUT=bk_dsn, INPUT=ds)
     copy_cmd = "   COPY OUTDD=OUTPUT,INDD=((INPUT,R))"
     return iebcopy(copy_cmd, dds=dds)
 
 
 class BackupError(Exception):
     def __init__(self, message, rc=None, stdout=None, stderr=None):
+        """Error during backup.
+
+        Parameters
+        ----------
+        message : str
+            Human readable string describing the exception.
+        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 backup: "{0}"'.format(message)
         self.rc = rc
         self.stdout = stdout