Add Docstrings to validations_libs/validation_action.py file

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

validations_libs/validation_actions.py

@@ -27,6 +27,18 @@ LOG = logging.getLogger(__name__ + ".validation_actions")
 
 
 class ValidationActions(object):
+    """An object for encapsulating the Validation Actions
+
+    This class allows the possibility to execute the following actions:
+
+    - List the available validations
+    - Show detailed information about one validation
+    - Show the available parameters for one or multiple validations
+    - Show the list of the validation groups
+    - Run one or multiple validations, by name(s) or by group(s)
+    - Show the history of the validations executions
+
+    """
 
     def __init__(self, validation_path=None, group=None):
         self.log = logging.getLogger(__name__ + ".ValidationActions")
@@ -35,7 +47,33 @@ class ValidationActions(object):
         self.group = group
 
     def list_validations(self):
-        """List the available validations"""
+        """Get a list of the available validations
+
+        This is used to print table from python ``Tuple`` with ``PrettyTable``.
+
+        .. code:: text
+
+            ----------------+--------------------------+----------------------+
+            | ID            | Name                     | Groups               |
+            +---------------+--------------------------+----------------------+
+            | validation1   | Name of the validation1  | ['group1']           |
+            | validation2   | Name of the validation2  | ['group1', 'group2'] |
+            | validation3   | Name of the validation3  | ['group4]            |
+            +---------------+--------------------------+----------------------+
+
+        :return: The list of the available validations
+        :rtype: `tuple`
+
+        :Example:
+
+        >>> path = "/foo/bar"
+        >>> action = ValidationActions(validation_path=path)
+        >>> results = action.list_validations()
+        >>> print(results)
+        (('ID', 'Name', 'Groups'),
+         [('validation1', 'Name of the validation1', ['group1']),
+          ('validation2', 'Name of the validation2', ['group1', 'group2'])])
+        """
         self.log = logging.getLogger(__name__ + ".list_validations")
         validations = v_utils.parse_all_validations_on_disk(
             self.validation_path, self.group)
@@ -50,7 +88,33 @@ class ValidationActions(object):
 
     def show_validations(self, validation,
                          log_path=constants.VALIDATIONS_LOG_BASEDIR):
-        """Display detailed information about a Validation"""
+        """Display detailed information about a Validation
+
+        :param validation: The name of the validation
+        :type validation: `string`
+        :param log_path: The absolute path of the validations logs
+        :type log_path: `string`
+
+        :return: The detailed information for a validation
+        :rtype: `dict`
+
+        :Example:
+
+        >>> path = "/foo/bar"
+        >>> validation = 'foo'
+        >>> action = ValidationActions(validation_path=path)
+        >>> results = action.show_validations(validation=validation)
+        >>> print(results)
+        {
+         'Description': 'Description of the foo validation',
+         'Groups': ['group1', 'group2'],
+         'ID': 'foo',
+         'Last execution date': None,
+         'Name': 'Name of the validation foo',
+         'Number of execution': 'Total: 0, Passed: 0, Failed: 0',
+         'Parameters': {'foo1': bar1}
+        }
+        """
         self.log = logging.getLogger(__name__ + ".show_validations")
         # Get validation data:
         vlog = ValidationLogs(log_path)
@@ -71,6 +135,78 @@ class ValidationActions(object):
                         workdir=None, limit_hosts=None, run_async=False,
                         base_dir=constants.DEFAULT_VALIDATIONS_BASEDIR,
                         log_path=None, python_interpreter=None):
+        """Run one or multiple validations by name(s) or by group(s)
+
+        :param validation_name: A list of validation names
+        :type validation_name: ``list``
+        :param inventory: Either proper inventory file, or a comma-separated
+                          list. (Defaults to ``localhost``)
+        :type inventory: ``string``
+        :param group: A list of group names
+        :type group: ``list``
+        :param extra_vars: Set additional variables as a Dict or the absolute
+                           path of a JSON or YAML file type.
+        :type extra_vars: Either a Dict or the absolute path of JSON or YAML
+        :param validations_dir: The absolute path of the validations playbooks
+        :type validations_dir: ``string``
+        :param extra_env_vars: Set additional ansible variables using an
+                                extravar dictionary.
+        :type extra_env_vars: ``dict``
+        :param ansible_cfg: Path to an ansible configuration file. One will be
+                            generated in the artifact path if this option is
+                            None.
+        :type ansible_cfg: ``string``
+        :param quiet: Disable all output (Defaults to ``True``)
+        :type quiet: ``Boolean``
+        :param workdir: Location of the working directory
+        :type workdir: ``string``
+        :param limit_hosts: Limit the execution to the hosts.
+        :type limit_hosts: ``string``
+        :param run_async: Enable the Ansible asynchronous mode
+                          (Defaults to ``False``)
+        :type run_async: ``boolean``
+        :param base_dir: The absolute path of the validations base directory
+                         (Defaults to
+                         ``constants.DEFAULT_VALIDATIONS_BASEDIR``)
+        :type base_dir: ``string``
+        :param log_path: The absolute path of the validations logs directory
+        :type log_path: ``string``
+        :param python_interpreter: Path to the Python interpreter to be
+                                   used for module execution on remote targets,
+                                   or an automatic discovery mode (``auto``,
+                                   ``auto_silent`` or the default one
+                                   ``auto_legacy``)
+        :type python_interpreter: ``string``
+
+        :return: A list of dictionary containing the informations of the
+                 validations executions (Validations, Duration, Host_Group,
+                 Status, Status_by_Host, UUID and Unreachable_Hosts)
+        :rtype: ``list``
+
+        :Example:
+
+        >>> path = "/u/s/a"
+        >>> validation_name = ['foo', 'bar']
+        >>> actions = ValidationActions(validation_path=path)
+        >>> results = actions.run_validations(inventory='localhost',
+                                              validation_name=validation_name,
+                                              quiet=True)
+        >>> print(results)
+        [{'Duration': '0:00:02.285',
+          'Host_Group': 'all',
+          'Status': 'PASSED',
+          'Status_by_Host': 'localhost,PASSED',
+          'UUID': '62d4d54c-7cce-4f38-9091-292cf49268d7',
+          'Unreachable_Hosts': '',
+          'Validations': 'foo'},
+         {'Duration': '0:00:02.237',
+          'Host_Group': 'all',
+          'Status': 'PASSED',
+          'Status_by_Host': 'localhost,PASSED',
+          'UUID': '04e6165c-7c33-4881-bac7-73ff3f909c24',
+          'Unreachable_Hosts': '',
+          'Validations': 'bar'}]
+        """
         self.log = logging.getLogger(__name__ + ".run_validations")
         playbooks = []
         validations_dir = (validations_dir if validations_dir
@@ -143,7 +279,38 @@ class ValidationActions(object):
         return vlog.get_results(uuid)
 
     def group_information(self, groups):
-        """Get Information about Validation Groups"""
+        """Get Information about Validation Groups
+
+        This is used to print table from python ``Tuple`` with ``PrettyTable``.
+
+        .. code:: text
+
+            +----------+--------------------------+-----------------------+
+            | Groups   | Description              | Number of Validations |
+            +----------+--------------------------+-----------------------+
+            | group1   | Description of group1    |                     3 |
+            | group2   | Description of group2    |                    12 |
+            | group3   | Description of group3    |                     1 |
+            +----------+--------------------------+-----------------------+
+
+        :param groups: The absolute path of the groups.yaml file
+        :type groups: ``string``
+
+        :return: The list of the available groups with their description and
+                 the numbers of validation belonging to them.
+        :rtype: ``tuple``
+
+        :Example:
+
+        >>> groups = "/foo/bar/groups.yaml"
+        >>> actions = ValidationActions(constants.ANSIBLE_VALIDATION_DIR)
+        >>> group_info = actions.group_information(groups)
+        >>> print(group_info)
+        (('Groups', 'Desciption', 'Number of Validations'),
+         [('group1', 'Description of group1', 3),
+          ('group2', 'Description of group2', 12),
+          ('group3', 'Description of group3', 1)])
+        """
         val_gp = Group(groups)
         group = val_gp.get_formated_group
 
@@ -240,7 +407,58 @@ class ValidationActions(object):
 
     def show_history(self, validation_id=None, extension='json',
                      log_path=constants.VALIDATIONS_LOG_BASEDIR):
-        """Return validations history"""
+        """Return validation executions history
+
+        :param validation_id: The validation id
+        :type validation_id: ``string``
+        :param extension: The log file extension (Defaults to ``json``)
+        :type extension: ``string``
+        :param log_path: The absolute path of the validations logs directory
+        :type log_path: ``string``
+
+        :return: Returns the information about the validation executions
+                 history
+        :rtype: ``tuple``
+
+        :Example:
+
+        >>> actions = ValidationActions(constants.ANSIBLE_VALIDATION_DIR)
+        >>> print(actions.show_history())
+        (('UUID', 'Validations', 'Status', 'Execution at', 'Duration'),
+         [('5afb1597-e2a1-4635-b2df-7afe21d00de6',
+         'foo',
+         'PASSED',
+         '2020-11-13T11:47:04.740442Z',
+         '0:00:02.388'),
+         ('32a5e217-d7a9-49a5-9838-19e5f9b82a77',
+         'foo2',
+         'PASSED',
+         '2020-11-13T11:47:07.931184Z',
+         '0:00:02.455'),
+         ('62d4d54c-7cce-4f38-9091-292cf49268d7',
+         'foo',
+         'PASSED',
+         '2020-11-13T11:47:47.188876Z',
+         '0:00:02.285'),
+         ('04e6165c-7c33-4881-bac7-73ff3f909c24',
+         'foo3',
+         'PASSED',
+         '2020-11-13T11:47:50.279662Z',
+         '0:00:02.237')])
+        >>> actions = ValidationActions(constants.ANSIBLE_VALIDATION_DIR)
+        >>> print(actions.show_history(validation_id='foo'))
+        (('UUID', 'Validations', 'Status', 'Execution at', 'Duration'),
+         [('5afb1597-e2a1-4635-b2df-7afe21d00de6',
+         'foo',
+         'PASSED',
+         '2020-11-13T11:47:04.740442Z',
+         '0:00:02.388'),
+         ('04e6165c-7c33-4881-bac7-73ff3f909c24',
+         'foo',
+         'PASSED',
+         '2020-11-13T11:47:50.279662Z',
+         '0:00:02.237')])
+        """
         vlogs = ValidationLogs(log_path)
         logs = (vlogs.get_logfile_by_validation(validation_id)
                 if validation_id else vlogs.get_all_logfiles(extension))
@@ -261,7 +479,51 @@ class ValidationActions(object):
 
     def get_status(self, validation_id=None, uuid=None, status='FAILED',
                    log_path=constants.VALIDATIONS_LOG_BASEDIR):
-        """Return validations execution details by status"""
+        """Return validations execution details by status
+
+        :param validation_id: The validation id
+        :type validation_id: ``string``
+        :param uuid: The UUID of the execution
+        :type uuid: ``string``
+        :param status: The status of the execution (Defaults to FAILED)
+        :type status: ``string``
+        :param log_path: The absolute path of the validations logs directory
+        :type log_path: ``string``
+
+        :return: A list of validations execution with details and by status
+        :rtype: ``tuple``
+
+        :Example:
+
+        >>> actions = ValidationActions(validation_path='/foo/bar')
+        >>> status = actions.get_status(validation_id='foo'))
+        >>> print(status)
+        (['name', 'host', 'status', 'task_data'],
+         [('Check if debug mode is disabled.',
+         'localhost',
+         'FAILED',
+         {'_ansible_no_log': False,
+             'action': 'fail',
+             'changed': False,
+             'failed': True,
+             'msg': 'Debug mode is not disabled.'}),
+         ('Check if debug mode is disabled.',
+         'localhost',
+         'FAILED',
+         {'_ansible_no_log': False,
+             'action': 'fail',
+             'changed': False,
+             'failed': True,
+             'msg': 'Debug mode is not disabled.'}),
+         ('Check if debug mode is disabled.',
+         'localhost',
+         'FAILED',
+         {'_ansible_no_log': False,
+             'action': 'fail',
+             'changed': False,
+             'failed': True,
+             'msg': 'Debug mode is not disabled.'})])
+        """
         vlogs = ValidationLogs(log_path)
         if validation_id:
             logs = vlogs.get_logfile_by_validation(validation_id)