From db44fc58ecc61528aed04eb85a27a700c90f1afd Mon Sep 17 00:00:00 2001 From: Rob Garcia Date: Mon, 30 Dec 2024 15:58:10 -0500 Subject: Added docstrings to V2 methods in the CallbackBase Class (4 & 5 of 27) (#83507) * Added docstrings to V2 methods in the CallbackBase Class (4 & 5 of 27) * Made corrections as requested by webknjaz. * Cleaned up whitespace issues. * Corrections to customization note for review by webknjaz. * Added rtype to return in docstrings. * Simplified docstrings. Co-authored-by: Brian Coca Co-authored-by: Sviatoslav Sydorenko --- lib/ansible/plugins/callback/__init__.py | 78 +++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/lib/ansible/plugins/callback/__init__.py b/lib/ansible/plugins/callback/__init__.py index c88fbd5572..aa75ac5fa3 100644 --- a/lib/ansible/plugins/callback/__init__.py +++ b/lib/ansible/plugins/callback/__init__.py @@ -506,67 +506,91 @@ class CallbackBase(AnsiblePlugin): self.on_any(args, kwargs) def v2_runner_on_failed(self, result: TaskResult, ignore_errors: bool = False) -> None: - """Get details about a failed task and whether or not Ansible should continue - running tasks on the host where the failure occurred, then process the details - as required by the callback (output, profiling, logging, notifications, etc.) + """Process results of a failed task. - Note: The 'ignore_errors' directive only works when the task can run and returns - a value of 'failed'. It does not make Ansible ignore undefined variable errors, - connection failures, execution issues (for example, missing packages), or syntax errors. + Note: The value of 'ignore_errors' tells Ansible whether to + continue running tasks on the host where this task failed. + But the 'ignore_errors' directive only works when the task can + run and returns a value of 'failed'. It does not make Ansible + ignore undefined variable errors, connection failures, execution + issues (for example, missing packages), or syntax errors. - Customization note: For more information about the attributes and methods of the - TaskResult class, see lib/ansible/executor/task_result.py. - - :param TaskResult result: An object that contains details about the task - :param bool ignore_errors: Whether or not Ansible should continue running tasks on the host - where the failure occurred + :param result: The parameters of the task and its results. + :type result: TaskResult + :param ignore_errors: Whether Ansible should continue \ + running tasks on the host where the task failed. + :type ignore_errors: bool :return: None + :rtype: None """ host = result._host.get_name() self.runner_on_failed(host, result._result, ignore_errors) def v2_runner_on_ok(self, result: TaskResult) -> None: - """Get details about a successful task and process them as required by the callback - (output, profiling, logging, notifications, etc.) - - Customization note: For more information about the attributes and methods of the - TaskResult class, see lib/ansible/executor/task_result.py. + """Process results of a successful task. - :param TaskResult result: An object that contains details about the task + :param result: The parameters of the task and its results. + :type result: TaskResult :return: None + :rtype: None """ host = result._host.get_name() self.runner_on_ok(host, result._result) def v2_runner_on_skipped(self, result: TaskResult) -> None: - """Get details about a skipped task and process them as required by the callback - (output, profiling, logging, notifications, etc.) + """Process results of a skipped task. - Customization note: For more information about the attributes and methods of the - TaskResult class, see lib/ansible/executor/task_result.py. - - :param TaskResult result: An object that contains details about the task + :param result: The parameters of the task and its results. + :type result: TaskResult :return: None + :rtype: None """ if C.DISPLAY_SKIPPED_HOSTS: host = result._host.get_name() self.runner_on_skipped(host, self._get_item_label(getattr(result._result, 'results', {}))) - def v2_runner_on_unreachable(self, result): + def v2_runner_on_unreachable(self, result: TaskResult) -> None: + """Process results of a task if a target node is unreachable. + + :param result: The parameters of the task and its results. + :type result: TaskResult + + :return: None + :rtype: None + """ host = result._host.get_name() self.runner_on_unreachable(host, result._result) - def v2_runner_on_async_poll(self, result): + def v2_runner_on_async_poll(self, result: TaskResult) -> None: + """Get details about an unfinished task running in async mode. + + Note: The value of the `poll` keyword in the task determines + the interval at which polling occurs and this method is run. + + :param result: The parameters of the task and its status. + :type result: TaskResult + + :rtype: None + :rtype: None + """ host = result._host.get_name() jid = result._result.get('ansible_job_id') # FIXME, get real clock clock = 0 self.runner_on_async_poll(host, result._result, jid, clock) - def v2_runner_on_async_ok(self, result): + def v2_runner_on_async_ok(self, result: TaskResult) -> None: + """Process results of a successful task that ran in async mode. + + :param result: The parameters of the task and its results. + :type result: TaskResult + + :return: None + :rtype: None + """ host = result._host.get_name() jid = result._result.get('ansible_job_id') self.runner_on_async_ok(host, result._result, jid) -- cgit v1.2.3