Add docstrings to utils.py

This patch also adds new unittests for the following functions:
- from validations_libs.utils import get_validations_data
  > test_get_validations_data_wrong_type(..)
- from validations_libs.utils import get_validations_details
  > test_get_validations_details_wrong_type(..)

Change-Id: Iac9ba971a73ed09b26d3e41efb38ad72dd942bbc
Signed-off-by: Gael Chamoulaud (Strider) <gchamoul@redhat.com>

validations_libs/tests/test_utils.py

@@ -40,6 +40,13 @@ class TestUtils(TestCase):
         res = utils.get_validations_data('512e')
         self.assertEqual(res, output)
 
+    @mock.patch('os.path.exists', return_value=True)
+    def test_get_validations_data_wrong_type(self, mock_exists):
+        validation = ['val1']
+        self.assertRaises(TypeError,
+                          utils.get_validations_data,
+                          validation)
+
     @mock.patch('validations_libs.utils.current_time',
                 return_value='2020-04-02T06:58:20.352272Z')
     @mock.patch('os.makedirs')
@@ -146,6 +153,13 @@ class TestUtils(TestCase):
         result = utils.get_validations_details('foo')
         self.assertEqual(result, fakes.FAKE_METADATA)
 
+    @mock.patch('six.moves.builtins.open')
+    def test_get_validations_details_wrong_type(self, mock_open):
+        validation = ['foo']
+        self.assertRaises(TypeError,
+                          utils.get_validations_details,
+                          validation=validation)
+
     @mock.patch('yaml.safe_load', return_value=fakes.FAKE_PLAYBOOK2)
     @mock.patch('six.moves.builtins.open')
     def test_get_validations_parameters_no_group(self, mock_open, mock_load):

validations_libs/utils.py

@@ -33,7 +33,15 @@ def current_time():
 
 
 def create_artifacts_dir(dir_path=None, prefix=None):
-    """Create Ansible artifacts directory"""
+    """Create Ansible artifacts directory
+
+    :param dir_path: Directory asbolute path
+    :type dir_path: `string`
+    :param prefix: Playbook name
+    :type prefix: `string`
+    :return: The UUID of the validation and the absolute Path of the log file
+    :rtype: `string`, `string`
+    """
     dir_path = (dir_path if dir_path else
                 constants.VALIDATION_ANSIBLE_ARTIFACT_PATH)
     validation_uuid = str(uuid.uuid4())
@@ -48,9 +56,27 @@ def create_artifacts_dir(dir_path=None, prefix=None):
 
 
 def parse_all_validations_on_disk(path, groups=None):
-    """
-        Return a list of validations metadata
-        Can be sorted by Groups
+    """Return a list of validations metadata which can be sorted by Groups
+
+    :param path: The absolute path of the validations directory
+    :type path: `string`
+    :param groups: Groups of validations. Could be a `list` or a
+                   comma-separated `string` of groups
+    :return: A list of validations metadata.
+    :rtype: `list`
+
+    :Example:
+
+    >>> path = '/foo/bar'
+    >>> parse_all_validations_on_disk(path)
+    [{'description': 'Detect whether the node disks use Advanced Format.',
+      'groups': ['prep', 'pre-deployment'],
+      'id': '512e',
+      'name': 'Advanced Format 512e Support'},
+     {'description': 'Make sure that the server has enough CPU cores.',
+      'groups': ['prep', 'pre-introspection'],
+      'id': 'check-cpu',
+      'name': 'Verify if the server fits the CPU core requirements'}]
     """
     results = []
     if not groups:
@@ -68,22 +94,19 @@ def parse_all_validations_on_disk(path, groups=None):
 
 
 def get_validations_playbook(path, validation_id=None, groups=None):
-    """
-    Get a list of validations playbooks paths either by their names
+    """Get a list of validations playbooks paths either by their names
     or their groups
 
     :param path: Path of the validations playbooks
     :type path: `string`
-
     :param validation_id: List of validation name
     :type validation_id: `list` or a `string` of comma-separated validations
-
     :param groups: List of validation group
     :type groups: `list` or a `string` of comma-separated groups
-
     :return: A list of absolute validations playbooks path
+    :rtype: `list`
 
-    :exemple:
+    :Example:
 
     >>> path = '/usr/share/validation-playbooks'
     >>> validation_id = ['512e','check-cpu']
@@ -123,21 +146,66 @@ def get_validation_parameters(validation):
 
 
 def read_validation_groups_file(groups_path=None):
-    """Load groups.yaml file and return a dictionary with its contents"""
+    """Load groups.yaml file and return a dictionary with its contents
+
+    :params groups_path: The path the groups.yaml file
+    :type groups_path: `string`
+    :return: The group list with their descriptions
+    :rtype: `dict`
+
+    :Example:
+
+    >>> read_validation_groups_file()
+    {'group1': [{'description': 'Group1 description.'}],
+     'group2': [{'description': 'Group2 description.'}]}
+    """
     gp = Group((groups_path if groups_path else
                 constants.VALIDATION_GROUPS_INFO))
     return gp.get_data
 
 
 def get_validation_group_name_list(groups_path=None):
-    """Get the validation group name list only"""
+    """Get the validation group name list only
+
+    :params groups_path: The path the groups.yaml file
+    :type groups_path: `string`
+    :return: The group name list
+    :rtype: `list`
+
+    :Example:
+
+    >>> get_validation_group_name_list()
+    ['group1',
+     'group2',
+     'group3',
+     'group4']
+    """
     gp = Group((groups_path if groups_path else
                 constants.VALIDATION_GROUPS_INFO))
     return gp.get_groups_keys_list
 
 
 def get_validations_details(validation):
-    """Return validations information"""
+    """Return information details for a validation
+
+    :param validation: Name of the validation
+    :type validation: `string`
+    :return: The information of the validation
+    :rtype: `dict`
+    :raises: a `TypeError` exception if `validation` is not a string
+
+    :Example:
+
+    >>> validation = "check-something"
+    >>> get_validations_details(validation)
+    {'description': 'Verify that the server has enough something.',
+     'groups': ['group1', 'group2'],
+     'id': 'check-something',
+     'name': 'Verify the server fits the something requirements'}
+    """
+    if not isinstance(validation, six.string_types):
+        raise TypeError("The input data should be a String")
+
     results = parse_all_validations_on_disk(constants.ANSIBLE_VALIDATION_DIR)
     for r in results:
         if r['id'] == validation:
@@ -146,10 +214,32 @@ def get_validations_details(validation):
 
 
 def get_validations_data(validation, path=constants.ANSIBLE_VALIDATION_DIR):
+    """Return validation data with format:
+
+    ID, Name, Description, Groups, Parameters
+
+    :param validation: Name of the validation without the `yaml` extension.
+                       Defaults to `constants.ANSIBLE_VALIDATION_DIR`
+    :type validation: `string`
+    :param path: The path to the validations directory
+    :type path: `string`
+    :return: The validation data with the format
+             (ID, Name, Description, Groups, Parameters)
+    :rtype: `dict`
+
+    :Example:
+
+    >>> validation = 'check-something'
+    >>> get_validations_data(validation)
+    {'Description': 'Verify that the server has enough something',
+     'Groups': ['group1', 'group2'],
+     'ID': 'check-something',
+     'Name': 'Verify the server fits the something requirements',
+     'Parameters': {'param1': 24}}
     """
-    Return validations data with format:
-    ID, Name, Description, Groups, Other param
-    """
+    if not isinstance(validation, six.string_types):
+        raise TypeError("The input data should be a String")
+
     data = {}
     val_path = "{}/{}.yaml".format(path, validation)
     if os.path.exists(val_path):
@@ -161,9 +251,27 @@ def get_validations_data(validation, path=constants.ANSIBLE_VALIDATION_DIR):
 
 def get_validations_parameters(validations_data, validation_name=[],
                                groups=[]):
-    """
-    Return parameters for a list of validations
-    The return format can be in json or yaml
+    """Return parameters for a list of validations
+
+
+    :param validations_data: A list of absolute validations playbooks path
+    :type validations_data: `list`
+    :param validation_name: A list of validation name
+    :type validation_name: `list`
+    :param groups: A list of validation groups
+    :type groups: `list`
+    :return: a dictionary containing the current parameters for
+             each `validation_name` or `groups`
+    :rtype: `dict`
+
+    :Example:
+
+    >>> validations_data = ['/foo/bar/check-ram.yaml',
+                            '/foo/bar/check-cpu.yaml']
+    >>> validation_name = ['check-ram', 'check-cpu']
+    >>> get_validations_parameters(validations_data, validation_name)
+    {'check-cpu': {'parameters': {'minimal_cpu_count': 8}},
+     'check-ram': {'parameters': {'minimal_ram_gb': 24}}}
     """
     params = {}
     for val in validations_data:
@@ -177,31 +285,29 @@ def get_validations_parameters(validations_data, validation_name=[],
 
 
 def convert_data(data=''):
-    """
-    Transform a string containing comma-separated validation or group name
+    """Transform a string containing comma-separated validation or group name
     into a list. If `data` is already a list, it will simply return `data`.
 
-    It will raise an exception if `data` is not a list or a string.
-
     :param data: A string or a list
     :type data: `string` or `list`
-
     :return: A list of data
+    :rtype: `list`
+    :raises: a `TypeError` exception if `data` is not a list or a string
 
-    :exemple:
+    :Example:
 
     >>> data = "check-cpu,check-ram,check-disk-space"
     >>> convert_data(data)
     ['check-cpu', 'check-ram', 'check-disk-space']
-
+    ...
     >>> data = "check-cpu , check-ram , check-disk-space"
     >>> convert_data(data)
     ['check-cpu', 'check-ram', 'check-disk-space']
-
+    ...
     >>> data = "check-cpu,"
     >>> convert_data(data)
     ['check-cpu']
-
+    ...
     >>> data = ['check-cpu', 'check-ram', 'check-disk-space']
     >>> convert_data(data)
     ['check-cpu', 'check-ram', 'check-disk-space']