ansible-core 2.19.0b1__py3-none-any.whl → 2.19.0b3__py3-none-any.whl

ansible/errors/__init__.py

@@ -18,6 +18,9 @@ from ..module_utils.datatag import native_type_name
 from ansible._internal._datatag import _tags
 from .._internal._errors import _utils
 
+if t.TYPE_CHECKING:
+    from ansible.plugins import loader as _t_loader
+
 
 class ExitCode(enum.IntEnum):
     SUCCESS = 0  # used by TQM, must be bit-flag safe
@@ -374,8 +377,9 @@ class _AnsibleActionDone(AnsibleAction):
 class AnsiblePluginError(AnsibleError):
     """Base class for Ansible plugin-related errors that do not need AnsibleError contextual data."""
 
-    def __init__(self, message=None, plugin_load_context=None):
-        super(AnsiblePluginError, self).__init__(message)
+    def __init__(self, message: str | None = None, plugin_load_context: _t_loader.PluginLoadContext | None = None, help_text: str | None = None) -> None:
+        super(AnsiblePluginError, self).__init__(message, help_text=help_text)
+
         self.plugin_load_context = plugin_load_context
 
 

ansible/executor/module_common.py

@@ -39,7 +39,6 @@ from io import BytesIO
 from ansible._internal import _locking
 from ansible._internal._datatag import _utils
 from ansible.module_utils._internal import _dataclass_validation
-from ansible.module_utils.common.messages import PluginInfo
 from ansible.module_utils.common.yaml import yaml_load
 from ansible._internal._datatag._tags import Origin
 from ansible.module_utils.common.json import Direction, get_module_encoder
@@ -56,6 +55,7 @@ from ansible.template import Templar
 from ansible.utils.collection_loader._collection_finder import _get_collection_metadata, _nested_dict_get
 from ansible.module_utils._internal import _json, _ansiballz
 from ansible.module_utils import basic as _basic
+from ansible.module_utils.common import messages as _messages
 
 if t.TYPE_CHECKING:
     from ansible import template as _template
@@ -434,7 +434,13 @@ class ModuleUtilLocatorBase:
             else:
                 msg += '.'
 
-            display.deprecated(msg, removal_version, removed, removal_date, self._collection_name)
+            display.deprecated(  # pylint: disable=ansible-deprecated-date-not-permitted,ansible-deprecated-unnecessary-collection-name
+                msg=msg,
+                version=removal_version,
+                removed=removed,
+                date=removal_date,
+                deprecator=_messages.PluginInfo._from_collection_name(self._collection_name),
+            )
         if 'redirect' in routing_entry:
             self.redirected = True
             source_pkg = '.'.join(name_parts)
@@ -944,7 +950,6 @@ class _CachedModule:
 def _find_module_utils(
         *,
         module_name: str,
-        plugin: PluginInfo,
         b_module_data: bytes,
         module_path: str,
         module_args: dict[object, object],
@@ -1020,7 +1025,9 @@ def _find_module_utils(
         # People should start writing collections instead of modules in roles so we
         # may never fix this
         display.debug('ANSIBALLZ: Could not determine module FQN')
-        remote_module_fqn = 'ansible.modules.%s' % module_name
+        # FIXME: add integration test to validate that builtins and legacy modules with the same name are tracked separately by the caching mechanism
+        # FIXME: surrogate FQN should be unique per source path- role-packaged modules with name collisions can still be aliased
+        remote_module_fqn = 'ansible.legacy.%s' % module_name
 
     if module_substyle == 'python':
         date_time = datetime.datetime.now(datetime.timezone.utc)
@@ -1126,7 +1133,6 @@ def _find_module_utils(
             module_fqn=remote_module_fqn,
             params=encoded_params,
             profile=module_metadata.serialization_profile,
-            plugin_info_dict=dataclasses.asdict(plugin),
             date_time=date_time,
             coverage_config=coverage_config,
             coverage_output=coverage_output,
@@ -1236,7 +1242,6 @@ def _extract_interpreter(b_module_data):
 def modify_module(
         *,
         module_name: str,
-        plugin: PluginInfo,
         module_path,
         module_args,
         templar,
@@ -1277,7 +1282,6 @@ def modify_module(
 
     module_bits = _find_module_utils(
         module_name=module_name,
-        plugin=plugin,
         b_module_data=b_module_data,
         module_path=module_path,
         module_args=module_args,

ansible/executor/process/worker.py

@@ -32,6 +32,7 @@ from ansible._internal import _task
 from ansible.errors import AnsibleConnectionFailure, AnsibleError
 from ansible.executor.task_executor import TaskExecutor
 from ansible.executor.task_queue_manager import FinalQueue, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO
+from ansible.executor.task_result import _RawTaskResult
 from ansible.inventory.host import Host
 from ansible.module_utils.common.collections import is_sequence
 from ansible.module_utils.common.text.converters import to_text
@@ -226,7 +227,7 @@ class WorkerProcess(multiprocessing_context.Process):  # type: ignore[name-defin
             init_plugin_loader(cli_collections_path)
 
         try:
-            # execute the task and build a TaskResult from the result
+            # execute the task and build a _RawTaskResult from the result
             display.debug("running TaskExecutor() for %s/%s" % (self._host, self._task))
             executor_result = TaskExecutor(
                 self._host,
@@ -256,48 +257,52 @@ class WorkerProcess(multiprocessing_context.Process):  # type: ignore[name-defin
             # put the result on the result queue
             display.debug("sending task result for task %s" % self._task._uuid)
             try:
-                self._final_q.send_task_result(
-                    self._host.name,
-                    self._task._uuid,
-                    executor_result,
+                self._final_q.send_task_result(_RawTaskResult(
+                    host=self._host,
+                    task=self._task,
+                    return_data=executor_result,
                     task_fields=self._task.dump_attrs(),
-                )
+                ))
             except Exception as ex:
                 try:
                     raise AnsibleError("Task result omitted due to queue send failure.") from ex
                 except Exception as ex_wrapper:
-                    self._final_q.send_task_result(
-                        self._host.name,
-                        self._task._uuid,
-                        ActionBase.result_dict_from_exception(ex_wrapper),  # Overriding the task result, to represent the failure
-                        {},  # The failure pickling may have been caused by the task attrs, omit for safety
-                    )
+                    self._final_q.send_task_result(_RawTaskResult(
+                        host=self._host,
+                        task=self._task,
+                        return_data=ActionBase.result_dict_from_exception(ex_wrapper),  # Overriding the task result, to represent the failure
+                        task_fields={},  # The failure pickling may have been caused by the task attrs, omit for safety
+                    ))
 
             display.debug("done sending task result for task %s" % self._task._uuid)
 
-        except AnsibleConnectionFailure:
+        except AnsibleConnectionFailure as ex:
+            return_data = ActionBase.result_dict_from_exception(ex)
+            return_data.pop('failed')
+            return_data.update(unreachable=True)
+
             self._host.vars = dict()
             self._host.groups = []
-            self._final_q.send_task_result(
-                self._host.name,
-                self._task._uuid,
-                dict(unreachable=True),
+            self._final_q.send_task_result(_RawTaskResult(
+                host=self._host,
+                task=self._task,
+                return_data=return_data,
                 task_fields=self._task.dump_attrs(),
-            )
+            ))
 
-        except Exception as e:
-            if not isinstance(e, (IOError, EOFError, KeyboardInterrupt, SystemExit)) or isinstance(e, TemplateNotFound):
+        except Exception as ex:
+            if not isinstance(ex, (IOError, EOFError, KeyboardInterrupt, SystemExit)) or isinstance(ex, TemplateNotFound):
                 try:
                     self._host.vars = dict()
                     self._host.groups = []
-                    self._final_q.send_task_result(
-                        self._host.name,
-                        self._task._uuid,
-                        dict(failed=True, exception=to_text(traceback.format_exc()), stdout=''),
+                    self._final_q.send_task_result(_RawTaskResult(
+                        host=self._host,
+                        task=self._task,
+                        return_data=ActionBase.result_dict_from_exception(ex),
                         task_fields=self._task.dump_attrs(),
-                    )
+                    ))
                 except Exception:
-                    display.debug(u"WORKER EXCEPTION: %s" % to_text(e))
+                    display.debug(u"WORKER EXCEPTION: %s" % to_text(ex))
                     display.debug(u"WORKER TRACEBACK: %s" % to_text(traceback.format_exc()))
                 finally:
                     self._clean_up()

ansible/executor/task_executor.py

@@ -20,10 +20,9 @@ from ansible.errors import (
     AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleConnectionFailure, AnsibleActionFail, AnsibleActionSkip, AnsibleTaskError,
     AnsibleValueOmittedError,
 )
-from ansible.executor.task_result import TaskResult
+from ansible.executor.task_result import _RawTaskResult
 from ansible._internal._datatag import _utils
-from ansible.module_utils._internal._plugin_exec_context import PluginExecContext
-from ansible.module_utils.common.messages import Detail, WarningSummary, DeprecationSummary
+from ansible.module_utils.common.messages import Detail, WarningSummary, DeprecationSummary, PluginInfo
 from ansible.module_utils.datatag import native_type_name
 from ansible._internal._datatag._tags import TrustedAsTemplate
 from ansible.module_utils.parsing.convert_bool import boolean
@@ -44,6 +43,9 @@ from ansible.vars.clean import namespace_facts, clean_facts
 from ansible.vars.manager import _deprecate_top_level_fact
 from ansible._internal._errors import _captured
 
+if t.TYPE_CHECKING:
+    from ansible.executor.task_queue_manager import FinalQueue
+
 display = Display()
 
 
@@ -79,7 +81,7 @@ class TaskExecutor:
     class.
     """
 
-    def __init__(self, host, task: Task, job_vars, play_context, loader, shared_loader_obj, final_q, variable_manager):
+    def __init__(self, host, task: Task, job_vars, play_context, loader, shared_loader_obj, final_q: FinalQueue, variable_manager):
         self._host = host
         self._task = task
         self._job_vars = job_vars
@@ -361,10 +363,10 @@ class TaskExecutor:
             if self._connection and not isinstance(self._connection, string_types):
                 task_fields['connection'] = getattr(self._connection, 'ansible_name')
 
-            tr = TaskResult(
-                self._host.name,
-                self._task._uuid,
-                res,
+            tr = _RawTaskResult(
+                host=self._host,
+                task=self._task,
+                return_data=res,
                 task_fields=task_fields,
             )
 
@@ -637,8 +639,8 @@ class TaskExecutor:
                 if self._task.timeout:
                     old_sig = signal.signal(signal.SIGALRM, task_timeout)
                     signal.alarm(self._task.timeout)
-                with PluginExecContext(self._handler):
-                    result = self._handler.run(task_vars=vars_copy)
+
+                result = self._handler.run(task_vars=vars_copy)
 
             # DTFIX-RELEASE: nuke this, it hides a lot of error detail- remove the active exception propagation hack from AnsibleActionFail at the same time
             except (AnsibleActionFail, AnsibleActionSkip) as e:
@@ -666,17 +668,23 @@ class TaskExecutor:
                     if result.get('failed'):
                         self._final_q.send_callback(
                             'v2_runner_on_async_failed',
-                            TaskResult(self._host.name,
-                                       self._task._uuid,
-                                       result,
-                                       task_fields=self._task.dump_attrs()))
+                            _RawTaskResult(
+                                host=self._host,
+                                task=self._task,
+                                return_data=result,
+                                task_fields=self._task.dump_attrs(),
+                            ),
+                        )
                     else:
                         self._final_q.send_callback(
                             'v2_runner_on_async_ok',
-                            TaskResult(self._host.name,
-                                       self._task._uuid,
-                                       result,
-                                       task_fields=self._task.dump_attrs()))
+                            _RawTaskResult(
+                                host=self._host,
+                                task=self._task,
+                                return_data=result,
+                                task_fields=self._task.dump_attrs(),
+                            ),
+                        )
 
             if 'ansible_facts' in result and self._task.action not in C._ACTION_DEBUG:
                 if self._task.action in C._ACTION_WITH_CLEAN_FACTS:
@@ -756,12 +764,12 @@ class TaskExecutor:
                         display.debug('Retrying task, attempt %d of %d' % (attempt, retries))
                         self._final_q.send_callback(
                             'v2_runner_retry',
-                            TaskResult(
-                                self._host.name,
-                                self._task._uuid,
-                                result,
+                            _RawTaskResult(
+                                host=self._host,
+                                task=self._task,
+                                return_data=result,
                                 task_fields=self._task.dump_attrs()
-                            )
+                            ),
                         )
                         time.sleep(delay)
                         self._handler = self._get_action_handler(templar=templar)
@@ -835,13 +843,12 @@ class TaskExecutor:
                     if not isinstance(deprecation, DeprecationSummary):
                         # translate non-DeprecationMessageDetail message dicts
                         try:
-                            if deprecation.pop('collection_name', ...) is not ...:
+                            if (collection_name := deprecation.pop('collection_name', ...)) is not ...:
                                 # deprecated: description='enable the deprecation message for collection_name' core_version='2.23'
+                                # CAUTION: This deprecation cannot be enabled until the replacement (deprecator) has been documented, and the schema finalized.
                                 # self.deprecated('The `collection_name` key in the `deprecations` dictionary is deprecated.', version='2.27')
-                                pass
+                                deprecation.update(deprecator=PluginInfo._from_collection_name(collection_name))
 
-                            # DTFIX-RELEASE: when plugin isn't set, do it at the boundary where we receive the module/action results
-                            #                that may even allow us to never set it in modules/actions directly and to populate it at the boundary
                             deprecation = DeprecationSummary(
                                 details=(
                                     Detail(msg=deprecation.pop('msg')),
@@ -926,10 +933,10 @@ class TaskExecutor:
                 time_left -= self._task.poll
                 self._final_q.send_callback(
                     'v2_runner_on_async_poll',
-                    TaskResult(
-                        self._host.name,
-                        async_task._uuid,
-                        async_result,
+                    _RawTaskResult(
+                        host=self._host,
+                        task=async_task,
+                        return_data=async_result,
                         task_fields=async_task.dump_attrs(),
                     ),
                 )

ansible/executor/task_queue_manager.py

@@ -17,6 +17,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import os
 import sys
 import tempfile
@@ -31,7 +32,7 @@ from ansible.errors import AnsibleError, ExitCode, AnsibleCallbackError
 from ansible._internal._errors._handler import ErrorHandler
 from ansible.executor.play_iterator import PlayIterator
 from ansible.executor.stats import AggregateStats
-from ansible.executor.task_result import TaskResult
+from ansible.executor.task_result import _RawTaskResult, _WireTaskResult
 from ansible.inventory.data import InventoryData
 from ansible.module_utils.six import string_types
 from ansible.module_utils.common.text.converters import to_native
@@ -47,7 +48,8 @@ from ansible.utils.display import Display
 from ansible.utils.lock import lock_decorator
 from ansible.utils.multiprocessing import context as multiprocessing_context
 
-from dataclasses import dataclass
+if t.TYPE_CHECKING:
+    from ansible.executor.process.worker import WorkerProcess
 
 __all__ = ['TaskQueueManager']
 
@@ -57,12 +59,13 @@ STDERR_FILENO = 2
 
 display = Display()
 
+_T = t.TypeVar('_T')
 
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
 class CallbackSend:
-    def __init__(self, method_name, *args, **kwargs):
-        self.method_name = method_name
-        self.args = args
-        self.kwargs = kwargs
+    method_name: str
+    wire_task_result: _WireTaskResult
 
 
 class DisplaySend:
@@ -72,7 +75,7 @@ class DisplaySend:
         self.kwargs = kwargs
 
 
-@dataclass
+@dataclasses.dataclass
 class PromptSend:
     worker_id: int
     prompt: str
@@ -87,19 +90,11 @@ class FinalQueue(multiprocessing.queues.SimpleQueue):
         kwargs['ctx'] = multiprocessing_context
         super().__init__(*args, **kwargs)
 
-    def send_callback(self, method_name, *args, **kwargs):
-        self.put(
-            CallbackSend(method_name, *args, **kwargs),
-        )
+    def send_callback(self, method_name: str, task_result: _RawTaskResult) -> None:
+        self.put(CallbackSend(method_name=method_name, wire_task_result=task_result.as_wire_task_result()))
 
-    def send_task_result(self, *args, **kwargs):
-        if isinstance(args[0], TaskResult):
-            tr = args[0]
-        else:
-            tr = TaskResult(*args, **kwargs)
-        self.put(
-            tr,
-        )
+    def send_task_result(self, task_result: _RawTaskResult) -> None:
+        self.put(task_result.as_wire_task_result())
 
     def send_display(self, method, *args, **kwargs):
         self.put(
@@ -194,11 +189,8 @@ class TaskQueueManager:
         # plugins for inter-process locking.
         self._connection_lockfile = tempfile.TemporaryFile()
 
-    def _initialize_processes(self, num):
-        self._workers = []
-
-        for i in range(num):
-            self._workers.append(None)
+    def _initialize_processes(self, num: int) -> None:
+        self._workers: list[WorkerProcess | None] = [None] * num
 
     def load_callbacks(self):
         """
@@ -438,54 +430,72 @@ class TaskQueueManager:
                 defunct = True
         return defunct
 
+    @staticmethod
+    def _first_arg_of_type(value_type: t.Type[_T], args: t.Sequence) -> _T | None:
+        return next((arg for arg in args if isinstance(arg, value_type)), None)
+
     @lock_decorator(attr='_callback_lock')
     def send_callback(self, method_name, *args, **kwargs):
         # We always send events to stdout callback first, rest should follow config order
         for callback_plugin in [self._stdout_callback] + self._callback_plugins:
             # a plugin that set self.disabled to True will not be called
             # see osx_say.py example for such a plugin
-            if getattr(callback_plugin, 'disabled', False):
+            if callback_plugin.disabled:
                 continue
 
             # a plugin can opt in to implicit tasks (such as meta). It does this
             # by declaring self.wants_implicit_tasks = True.
-            wants_implicit_tasks = getattr(callback_plugin, 'wants_implicit_tasks', False)
+            if not callback_plugin.wants_implicit_tasks and (task_arg := self._first_arg_of_type(Task, args)) and task_arg.implicit:
+                continue
 
             # try to find v2 method, fallback to v1 method, ignore callback if no method found
             methods = []
+
             for possible in [method_name, 'v2_on_any']:
-                gotit = getattr(callback_plugin, possible, None)
-                if gotit is None:
-                    gotit = getattr(callback_plugin, possible.removeprefix('v2_'), None)
-                if gotit is not None:
-                    methods.append(gotit)
-
-            # send clean copies
-            new_args = []
-
-            # If we end up being given an implicit task, we'll set this flag in
-            # the loop below. If the plugin doesn't care about those, then we
-            # check and continue to the next iteration of the outer loop.
-            is_implicit_task = False
-
-            for arg in args:
-                # FIXME: add play/task cleaners
-                if isinstance(arg, TaskResult):
-                    new_args.append(arg.clean_copy())
-                # elif isinstance(arg, Play):
-                # elif isinstance(arg, Task):
-                else:
-                    new_args.append(arg)
+                method = getattr(callback_plugin, possible, None)
 
-                if isinstance(arg, Task) and arg.implicit:
-                    is_implicit_task = True
+                if method is None:
+                    method = getattr(callback_plugin, possible.removeprefix('v2_'), None)
 
-            if is_implicit_task and not wants_implicit_tasks:
-                continue
+                    if method is not None:
+                        display.deprecated(
+                            msg='The v1 callback API is deprecated.',
+                            version='2.23',
+                            help_text='Use `v2_` prefixed callback methods instead.',
+                        )
+
+                if method is not None and not getattr(method, '_base_impl', False):  # don't bother dispatching to the base impls
+                    if possible == 'v2_on_any':
+                        display.deprecated(
+                            msg='The `v2_on_any` callback method is deprecated.',
+                            version='2.23',
+                            help_text='Use event-specific callback methods instead.',
+                        )
+
+                    methods.append(method)
 
             for method in methods:
+                # send clean copies
+                new_args = []
+
+                for arg in args:
+                    # FIXME: add play/task cleaners
+                    if isinstance(arg, _RawTaskResult):
+                        copied_tr = arg.as_callback_task_result()
+                        new_args.append(copied_tr)
+                        # this state hack requires that no callback ever accepts > 1 TaskResult object
+                        callback_plugin._current_task_result = copied_tr
+                    else:
+                        new_args.append(arg)
+
                 with self._callback_dispatch_error_handler.handle(AnsibleCallbackError):
                     try:
                         method(*new_args, **kwargs)
+                    except AssertionError:
+                        # Using an `assert` in integration tests is useful.
+                        # Production code should never use `assert` or raise `AssertionError`.
+                        raise
                     except Exception as ex:
                         raise AnsibleCallbackError(f"Callback dispatch {method_name!r} failed for plugin {callback_plugin._load_name!r}.") from ex
+
+            callback_plugin._current_task_result = None