From c1115710c776a51eb1bbe16a2e20c009b3c98400 Mon Sep 17 00:00:00 2001 From: "Gael Chamoulaud (Strider)" Date: Fri, 13 Nov 2020 15:29:10 +0100 Subject: [PATCH] Add Docstrings to validations_libs/validation_action.py file Change-Id: I69fc8bc37ff0009e9bbc4d0fe32ea444174ca9e7 Signed-off-by: Gael Chamoulaud (Strider) --- validations_libs/validation_actions.py | 272 ++++++++++++++++++++++++- 1 file changed, 267 insertions(+), 5 deletions(-) diff --git a/validations_libs/validation_actions.py b/validations_libs/validation_actions.py index f08353f8..9d9aa615 100644 --- a/validations_libs/validation_actions.py +++ b/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)