ansible-core 2.18.4rc1__py3-none-any.whl → 2.19.0b1__py3-none-any.whl

ansible/plugins/callback/__init__.py

@@ -18,27 +18,28 @@
 from __future__ import annotations
 
 import difflib
+import functools
 import json
 import re
 import sys
 import textwrap
+import typing as t
+
 from typing import TYPE_CHECKING
 
-from collections import OrderedDict
 from collections.abc import MutableMapping
 from copy import deepcopy
 
 from ansible import constants as C
-from ansible.module_utils.common.text.converters import to_text
-from ansible.module_utils.six import text_type
-from ansible.parsing.ajson import AnsibleJSONEncoder
-from ansible.parsing.yaml.dumper import AnsibleDumper
-from ansible.parsing.yaml.objects import AnsibleUnicode
+from ansible.module_utils._internal import _datatag
+from ansible.module_utils.common.messages import ErrorSummary
+from ansible._internal._yaml import _dumper
 from ansible.plugins import AnsiblePlugin
 from ansible.utils.color import stringc
 from ansible.utils.display import Display
-from ansible.utils.unsafe_proxy import AnsibleUnsafeText, NativeJinjaUnsafeText, _is_unsafe
 from ansible.vars.clean import strip_internal_keys, module_response_deepcopy
+from ansible.module_utils._internal._json._profiles import _fallback_to_str
+from ansible._internal._templating import _engine
 
 import yaml
 
@@ -52,23 +53,41 @@ __all__ = ["CallbackBase"]
 
 
 _DEBUG_ALLOWED_KEYS = frozenset(('msg', 'exception', 'warnings', 'deprecations'))
-_YAML_TEXT_TYPES = (text_type, AnsibleUnicode, AnsibleUnsafeText, NativeJinjaUnsafeText)
 # Characters that libyaml/pyyaml consider breaks
 _YAML_BREAK_CHARS = '\n\x85\u2028\u2029'  # NL, NEL, LS, PS
 # regex representation of libyaml/pyyaml of a space followed by a break character
 _SPACE_BREAK_RE = re.compile(fr' +([{_YAML_BREAK_CHARS}])')
 
 
-class _AnsibleCallbackDumper(AnsibleDumper):
-    def __init__(self, lossy=False):
+class _AnsibleCallbackDumper(_dumper.AnsibleDumper):
+    def __init__(self, *args, lossy: bool = False, **kwargs):
+        super().__init__(*args, **kwargs)
+
         self._lossy = lossy
 
-    def __call__(self, *args, **kwargs):
-        # pyyaml expects that we are passing an object that can be instantiated, but to
-        # smuggle the ``lossy`` configuration, we do that in ``__init__`` and then
-        # define this ``__call__`` that will mimic the ability for pyyaml to instantiate class
-        super().__init__(*args, **kwargs)
-        return self
+    def _pretty_represent_str(self, data):
+        """Uses block style for multi-line strings"""
+        data = _datatag.AnsibleTagHelper.as_native_type(data)
+
+        if _should_use_block(data):
+            style = '|'
+            if self._lossy:
+                data = _munge_data_for_lossy_yaml(data)
+        else:
+            style = self.default_style
+
+        node = yaml.representer.ScalarNode('tag:yaml.org,2002:str', data, style=style)
+
+        if self.alias_key is not None:
+            self.represented_objects[self.alias_key] = node
+
+        return node
+
+    @classmethod
+    def _register_representers(cls) -> None:
+        super()._register_representers()
+
+        cls.add_multi_representer(str, cls._pretty_represent_str)
 
 
 def _should_use_block(scalar):
@@ -77,6 +96,7 @@ def _should_use_block(scalar):
     for ch in _YAML_BREAK_CHARS:
         if ch in scalar:
             return True
+
     return False
 
 
@@ -95,12 +115,12 @@ class _SpecialCharacterTranslator:
         return None
 
 
-def _filter_yaml_special(scalar):
+def _filter_yaml_special(scalar: str) -> str:
     """Filter a string removing any character that libyaml/pyyaml declare as special"""
     return scalar.translate(_SpecialCharacterTranslator())
 
 
-def _munge_data_for_lossy_yaml(scalar):
+def _munge_data_for_lossy_yaml(scalar: str) -> str:
     """Modify a string so that analyze_scalar in libyaml/pyyaml will allow block formatting"""
     # we care more about readability than accuracy, so...
     # ...libyaml/pyyaml does not permit trailing spaces for block scalars
@@ -113,38 +133,12 @@ def _munge_data_for_lossy_yaml(scalar):
     return _SPACE_BREAK_RE.sub(r'\1', scalar)
 
 
-def _pretty_represent_str(self, data):
-    """Uses block style for multi-line strings"""
-    if _is_unsafe(data):
-        data = data._strip_unsafe()
-    data = text_type(data)
-    if _should_use_block(data):
-        style = '|'
-        if self._lossy:
-            data = _munge_data_for_lossy_yaml(data)
-    else:
-        style = self.default_style
-
-    node = yaml.representer.ScalarNode('tag:yaml.org,2002:str', data, style=style)
-    if self.alias_key is not None:
-        self.represented_objects[self.alias_key] = node
-    return node
-
-
-for data_type in _YAML_TEXT_TYPES:
-    _AnsibleCallbackDumper.add_representer(
-        data_type,
-        _pretty_represent_str
-    )
-
-
 class CallbackBase(AnsiblePlugin):
-
-    '''
+    """
     This is a base ansible callback class that does nothing. New callbacks should
     use this class as a base and override any callback methods they wish to execute
     custom actions.
-    '''
+    """
 
     def __init__(self, display=None, options=None):
         if display:
@@ -165,7 +159,10 @@ class CallbackBase(AnsiblePlugin):
         if options is not None:
             self.set_options(options)
 
-        self._hide_in_debug = ('changed', 'failed', 'skipped', 'invocation', 'skip_reason')
+        self._hide_in_debug = (
+            'changed', 'failed', 'skipped', 'invocation', 'skip_reason',
+            'ansible_loop_var', 'ansible_index_var', 'ansible_loop',
+        )
 
     # helper for callbacks, so they don't all have to include deepcopy
     _copy_result = deepcopy
@@ -173,13 +170,16 @@ class CallbackBase(AnsiblePlugin):
     def set_option(self, k, v):
         self._plugin_options[k] = C.config.get_config_value(k, plugin_type=self.plugin_type, plugin_name=self._load_name, direct={k: v})
 
-    def get_option(self, k):
+    def get_option(self, k, hostvars=None):
         return self._plugin_options[k]
 
+    def has_option(self, option):
+        return (option in self._plugin_options)
+
     def set_options(self, task_keys=None, var_options=None, direct=None):
-        ''' This is different than the normal plugin method as callbacks get called early and really don't accept keywords.
+        """ This is different than the normal plugin method as callbacks get called early and really don't accept keywords.
             Also _options was already taken for CLI args and callbacks use _plugin_options instead.
-        '''
+        """
 
         # load from config
         self._plugin_options = C.config.get_plugin_options(self.plugin_type, self._load_name, keys=task_keys, variables=var_options, direct=direct)
@@ -240,9 +240,12 @@ class CallbackBase(AnsiblePlugin):
         if self._display.verbosity < 3 and 'diff' in result:
             del abridged_result['diff']
 
-        # remove exception from screen output
-        if 'exception' in abridged_result:
-            del abridged_result['exception']
+        # remove error/warning values; the stdout callback should have already handled them
+        abridged_result.pop('exception', None)
+        abridged_result.pop('warnings', None)
+        abridged_result.pop('deprecations', None)
+
+        abridged_result = _engine.TemplateEngine().transform(abridged_result)  # ensure the dumped view matches the transformed view a playbook sees
 
         if not serialize:
             # Just return ``abridged_result`` without going through serialization
@@ -251,17 +254,8 @@ class CallbackBase(AnsiblePlugin):
             return abridged_result
 
         if result_format == 'json':
-            try:
-                return json.dumps(abridged_result, cls=AnsibleJSONEncoder, indent=indent, ensure_ascii=False, sort_keys=sort_keys)
-            except TypeError:
-                # Python3 bug: throws an exception when keys are non-homogenous types:
-                # https://bugs.python.org/issue25457
-                # sort into an OrderedDict and then json.dumps() that instead
-                if not OrderedDict:
-                    raise
-                return json.dumps(OrderedDict(sorted(abridged_result.items(), key=to_text)),
-                                  cls=AnsibleJSONEncoder, indent=indent,
-                                  ensure_ascii=False, sort_keys=False)
+            return json.dumps(abridged_result, cls=_fallback_to_str.Encoder, indent=indent, ensure_ascii=False, sort_keys=sort_keys)
+
         elif result_format == 'yaml':
             # None is a sentinel in this case that indicates default behavior
             # default behavior for yaml is to prettify results
@@ -279,7 +273,7 @@ class CallbackBase(AnsiblePlugin):
                 yaml.dump(
                     abridged_result,
                     allow_unicode=True,
-                    Dumper=_AnsibleCallbackDumper(lossy=lossy),
+                    Dumper=functools.partial(_AnsibleCallbackDumper, lossy=lossy),
                     default_flow_style=False,
                     indent=indent,
                     # sort_keys=sort_keys  # This requires PyYAML>=5.1
@@ -287,32 +281,31 @@ class CallbackBase(AnsiblePlugin):
                 ' ' * (indent or 4)
             )
 
-    def _handle_warnings(self, res):
-        ''' display warnings, if enabled and any exist in the result '''
-        if C.ACTION_WARNINGS:
-            if 'warnings' in res and res['warnings']:
-                for warning in res['warnings']:
-                    self._display.warning(warning)
-                del res['warnings']
-            if 'deprecations' in res and res['deprecations']:
-                for warning in res['deprecations']:
-                    self._display.deprecated(**warning)
-                del res['deprecations']
-
-    def _handle_exception(self, result, use_stderr=False):
-
-        if 'exception' in result:
-            msg = "An exception occurred during task execution. "
-            exception_str = to_text(result['exception'])
-            if self._display.verbosity < 3:
-                # extract just the actual error message from the exception text
-                error = exception_str.strip().split('\n')[-1]
-                msg += "To see the full traceback, use -vvv. The error was: %s" % error
-            else:
-                msg = "The full traceback is:\n" + exception_str
-                del result['exception']
+    def _handle_warnings(self, res: dict[str, t.Any]) -> None:
+        """Display warnings and deprecation warnings sourced by task execution."""
+        for warning in res.pop('warnings', []):
+            # DTFIX-RELEASE: what to do about propagating wrap_text from the original display.warning call?
+            self._display._warning(warning, wrap_text=False)
+
+        for warning in res.pop('deprecations', []):
+            self._display._deprecated(warning)
+
+    def _handle_exception(self, result: dict[str, t.Any], use_stderr: bool = False) -> None:
+        error_summary: ErrorSummary | None
 
-            self._display.display(msg, color=C.COLOR_ERROR, stderr=use_stderr)
+        if error_summary := result.pop('exception', None):
+            self._display._error(error_summary, wrap_text=False, stderr=use_stderr)
+
+    def _handle_warnings_and_exception(self, result: TaskResult) -> None:
+        """Standardized handling of warnings/deprecations and exceptions from a task/item result."""
+        # DTFIX-RELEASE: make/doc/porting-guide a public version of this method?
+        try:
+            use_stderr = self.get_option('display_failed_stderr')
+        except KeyError:
+            use_stderr = False
+
+        self._handle_warnings(result._result)
+        self._handle_exception(result._result, use_stderr=use_stderr)
 
     def _serialize_diff(self, diff):
         try:
@@ -337,7 +330,7 @@ class CallbackBase(AnsiblePlugin):
                 yaml.dump(
                     diff,
                     allow_unicode=True,
-                    Dumper=_AnsibleCallbackDumper(lossy=lossy),
+                    Dumper=functools.partial(_AnsibleCallbackDumper, lossy=lossy),
                     default_flow_style=False,
                     indent=4,
                     # sort_keys=sort_keys  # This requires PyYAML>=5.1
@@ -406,7 +399,7 @@ class CallbackBase(AnsiblePlugin):
         return u''.join(ret)
 
     def _get_item_label(self, result):
-        ''' retrieves the value to be displayed as a label for an item entry from a result object'''
+        """ retrieves the value to be displayed as a label for an item entry from a result object"""
         if result.get('_ansible_no_log', False):
             item = "(censored due to no_log)"
         else:
@@ -418,9 +411,10 @@ class CallbackBase(AnsiblePlugin):
         del result._result['results']
 
     def _clean_results(self, result, task_name):
-        ''' removes data from results for display '''
+        """ removes data from results for display """
 
         # mostly controls that debug only outputs what it was meant to
+        # FIXME: this is a terrible heuristic to format debug's output- it masks exception detail
         if task_name in C._ACTION_DEBUG:
             if 'msg' in result:
                 # msg should be alone
@@ -508,67 +502,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.)
-
-        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.
+        """Process results of a failed task.
 
-        Customization note: For more information about the attributes and methods of the
-        TaskResult class, see lib/ansible/executor/task_result.py.
+        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.
 
-        :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)
@@ -631,13 +649,13 @@ class CallbackBase(AnsiblePlugin):
     def v2_playbook_on_include(self, included_file):
         pass  # no v1 correspondence
 
-    def v2_runner_item_on_ok(self, result):
+    def v2_runner_item_on_ok(self, result: TaskResult) -> None:
         pass
 
-    def v2_runner_item_on_failed(self, result):
+    def v2_runner_item_on_failed(self, result: TaskResult) -> None:
         pass
 
-    def v2_runner_item_on_skipped(self, result):
+    def v2_runner_item_on_skipped(self, result: TaskResult) -> None:
         pass
 
     def v2_runner_retry(self, result):

ansible/plugins/callback/default.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: default
     type: stdout
     short_description: default Ansible screen output
@@ -16,11 +16,12 @@ DOCUMENTATION = '''
       - result_format_callback
     requirements:
       - set as stdout in configuration
-'''
+"""
 
 
 from ansible import constants as C
 from ansible import context
+from ansible.executor.task_result import TaskResult
 from ansible.playbook.task_include import TaskInclude
 from ansible.plugins.callback import CallbackBase
 from ansible.utils.color import colorize, hostcolor
@@ -29,10 +30,10 @@ from ansible.utils.fqcn import add_internal_fqcns
 
 class CallbackModule(CallbackBase):
 
-    '''
+    """
     This is the default callback interface, which simply prints messages
     to stdout when new callback events are received.
-    '''
+    """
 
     CALLBACK_VERSION = 2.0
     CALLBACK_TYPE = 'stdout'
@@ -46,20 +47,20 @@ class CallbackModule(CallbackBase):
         self._task_type_cache = {}
         super(CallbackModule, self).__init__()
 
-    def v2_runner_on_failed(self, result, ignore_errors=False):
-
+    def v2_runner_on_failed(self, result: TaskResult, ignore_errors: bool = False) -> None:
         host_label = self.host_label(result)
-        self._clean_results(result._result, result._task.action)
 
         if self._last_task_banner != result._task._uuid:
             self._print_task_banner(result._task)
 
-        self._handle_exception(result._result, use_stderr=self.get_option('display_failed_stderr'))
-        self._handle_warnings(result._result)
+        self._handle_warnings_and_exception(result)
+
+        # FIXME: this method should not exist, delegate "suggested keys to display" to the plugin or something... As-is, the placement of this
+        #          call obliterates `results`, which causes a task summary to be printed on loop failures, which we don't do anywhere else.
+        self._clean_results(result._result, result._task.action)
 
         if result._task.loop and 'results' in result._result:
             self._process_items(result)
-
         else:
             if self._display.verbosity < 2 and self.get_option('show_task_path_on_failure'):
                 self._print_task_path(result._task)
@@ -69,8 +70,7 @@ class CallbackModule(CallbackBase):
         if ignore_errors:
             self._display.display("...ignoring", color=C.COLOR_SKIP)
 
-    def v2_runner_on_ok(self, result):
-
+    def v2_runner_on_ok(self, result: TaskResult) -> None:
         host_label = self.host_label(result)
 
         if isinstance(result._task, TaskInclude):
@@ -93,7 +93,7 @@ class CallbackModule(CallbackBase):
             msg = "ok: [%s]" % (host_label,)
             color = C.COLOR_OK
 
-        self._handle_warnings(result._result)
+        self._handle_warnings_and_exception(result)
 
         if result._task.loop and 'results' in result._result:
             self._process_items(result)
@@ -104,8 +104,7 @@ class CallbackModule(CallbackBase):
                 msg += " => %s" % (self._dump_results(result._result),)
             self._display.display(msg, color=color)
 
-    def v2_runner_on_skipped(self, result):
-
+    def v2_runner_on_skipped(self, result: TaskResult) -> None:
         if self.get_option('display_skipped_hosts'):
 
             self._clean_results(result._result, result._task.action)
@@ -113,6 +112,8 @@ class CallbackModule(CallbackBase):
             if self._last_task_banner != result._task._uuid:
                 self._print_task_banner(result._task)
 
+            self._handle_warnings_and_exception(result)
+
             if result._task.loop is not None and 'results' in result._result:
                 self._process_items(result)
 
@@ -121,10 +122,12 @@ class CallbackModule(CallbackBase):
                 msg += " => %s" % self._dump_results(result._result)
             self._display.display(msg, color=C.COLOR_SKIP)
 
-    def v2_runner_on_unreachable(self, result):
+    def v2_runner_on_unreachable(self, result: TaskResult) -> None:
         if self._last_task_banner != result._task._uuid:
             self._print_task_banner(result._task)
 
+        self._handle_warnings_and_exception(result)
+
         host_label = self.host_label(result)
         msg = "fatal: [%s]: UNREACHABLE! => %s" % (host_label, self._dump_results(result._result))
         self._display.display(msg, color=C.COLOR_UNREACHABLE, stderr=self.get_option('display_failed_stderr'))
@@ -171,6 +174,7 @@ class CallbackModule(CallbackBase):
         # that they can secure this if they feel that their stdout is insecure
         # (shoulder surfing, logging stdout straight to a file, etc).
         args = ''
+        # FIXME: the no_log value is not templated at this point, so any template will be considered truthy
         if not task.no_log and C.DISPLAY_ARGS_TO_STDOUT:
             args = u', '.join(u'%s=%s' % a for a in task.args.items())
             args = u' %s' % args
@@ -234,8 +238,7 @@ class CallbackModule(CallbackBase):
                     self._print_task_banner(result._task)
                 self._display.display(diff)
 
-    def v2_runner_item_on_ok(self, result):
-
+    def v2_runner_item_on_ok(self, result: TaskResult) -> None:
         host_label = self.host_label(result)
         if isinstance(result._task, TaskInclude):
             return
@@ -255,33 +258,37 @@ class CallbackModule(CallbackBase):
             msg = 'ok'
             color = C.COLOR_OK
 
+        self._handle_warnings_and_exception(result)
+
         msg = "%s: [%s] => (item=%s)" % (msg, host_label, self._get_item_label(result._result))
         self._clean_results(result._result, result._task.action)
         if self._run_is_verbose(result):
             msg += " => %s" % self._dump_results(result._result)
         self._display.display(msg, color=color)
 
-    def v2_runner_item_on_failed(self, result):
+    def v2_runner_item_on_failed(self, result: TaskResult) -> None:
         if self._last_task_banner != result._task._uuid:
             self._print_task_banner(result._task)
 
+        self._handle_warnings_and_exception(result)
+
         host_label = self.host_label(result)
-        self._clean_results(result._result, result._task.action)
-        self._handle_exception(result._result, use_stderr=self.get_option('display_failed_stderr'))
 
         msg = "failed: [%s]" % (host_label,)
-        self._handle_warnings(result._result)
+        self._clean_results(result._result, result._task.action)
         self._display.display(
             msg + " (item=%s) => %s" % (self._get_item_label(result._result), self._dump_results(result._result)),
             color=C.COLOR_ERROR,
             stderr=self.get_option('display_failed_stderr')
         )
 
-    def v2_runner_item_on_skipped(self, result):
+    def v2_runner_item_on_skipped(self, result: TaskResult) -> None:
         if self.get_option('display_skipped_hosts'):
             if self._last_task_banner != result._task._uuid:
                 self._print_task_banner(result._task)
 
+            self._handle_warnings_and_exception(result)
+
             self._clean_results(result._result, result._task.action)
             msg = "skipping: [%s] => (item=%s) " % (result._host.get_name(), self._get_item_label(result._result))
             if self._run_is_verbose(result):