ansible-core 2.19.0b4__py3-none-any.whl → 2.19.0b5__py3-none-any.whl

ansible/executor/process/worker.py

@@ -25,29 +25,25 @@ import textwrap
 import traceback
 import types
 import typing as t
+
 from multiprocessing.queues import Queue
 
-from ansible import context
 from ansible._internal import _task
-from ansible.errors import AnsibleConnectionFailure, AnsibleError
+from ansible._internal._errors import _error_utils
+from ansible.errors import 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
 from ansible.parsing.dataloader import DataLoader
 from ansible.playbook.task import Task
 from ansible.playbook.play_context import PlayContext
-from ansible.plugins.loader import init_plugin_loader
 from ansible.utils.context_objects import CLIArgs
-from ansible.plugins.action import ActionBase
 from ansible.utils.display import Display
 from ansible.utils.multiprocessing import context as multiprocessing_context
 from ansible.vars.manager import VariableManager
 
-from jinja2.exceptions import TemplateNotFound
-
 __all__ = ['WorkerProcess']
 
 display = Display()
@@ -204,120 +200,49 @@ class WorkerProcess(multiprocessing_context.Process):  # type: ignore[name-defin
         signify that they are ready for their next task.
         """
 
-        # import cProfile, pstats, StringIO
-        # pr = cProfile.Profile()
-        # pr.enable()
-
         global current_worker
+
         current_worker = self
 
-        if multiprocessing_context.get_start_method() != 'fork':
-            # This branch is unused currently, as we hardcode fork
-            # TODO
-            # * move into a setup func run in `run`, before `_detach`
-            # * playbook relative content
-            # * display verbosity
-            # * ???
-            context.CLIARGS = self._cliargs
-            # Initialize plugin loader after parse, so that the init code can utilize parsed arguments
-            cli_collections_path = context.CLIARGS.get('collections_path') or []
-            if not is_sequence(cli_collections_path):
-                # In some contexts ``collections_path`` is singular
-                cli_collections_path = [cli_collections_path]
-            init_plugin_loader(cli_collections_path)
+        executor_result = TaskExecutor(
+            self._host,
+            self._task,
+            self._task_vars,
+            self._play_context,
+            self._loader,
+            self._shared_loader_obj,
+            self._final_q,
+            self._variable_manager,
+        ).run()
+
+        self._host.vars = dict()
+        self._host.groups = []
+
+        for name, stdio in (('stdout', sys.stdout), ('stderr', sys.stderr)):
+            if data := stdio.getvalue():  # type: ignore[union-attr]
+                display.warning(
+                    (
+                        f'WorkerProcess for [{self._host}/{self._task}] errantly sent data directly to {name} instead of using Display:\n'
+                        f'{textwrap.indent(data[:256], "    ")}\n'
+                    ),
+                    formatted=True
+                )
 
         try:
-            # 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,
-                self._task,
-                self._task_vars,
-                self._play_context,
-                self._loader,
-                self._shared_loader_obj,
-                self._final_q,
-                self._variable_manager,
-            ).run()
-
-            display.debug("done running TaskExecutor() for %s/%s [%s]" % (self._host, self._task, self._task._uuid))
-            self._host.vars = dict()
-            self._host.groups = []
-
-            for name, stdio in (('stdout', sys.stdout), ('stderr', sys.stderr)):
-                if data := stdio.getvalue():  # type: ignore[union-attr]
-                    display.warning(
-                        (
-                            f'WorkerProcess for [{self._host}/{self._task}] errantly sent data directly to {name} instead of using Display:\n'
-                            f'{textwrap.indent(data[:256], "    ")}\n'
-                        ),
-                        formatted=True
-                    )
-
-            # 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(_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(_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 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(_RawTaskResult(
                 host=self._host,
                 task=self._task,
-                return_data=return_data,
+                return_data=executor_result,
                 task_fields=self._task.dump_attrs(),
             ))
-
         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(_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(ex))
-                    display.debug(u"WORKER TRACEBACK: %s" % to_text(traceback.format_exc()))
-                finally:
-                    self._clean_up()
-
-        display.debug("WORKER PROCESS EXITING")
-
-        # pr.disable()
-        # s = StringIO.StringIO()
-        # sortby = 'time'
-        # ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
-        # ps.print_stats()
-        # with open('worker_%06d.stats' % os.getpid(), 'w') as f:
-        #     f.write(s.getvalue())
-
-    def _clean_up(self) -> None:
-        # NOTE: see note in init about forks
-        # ensure we cleanup all temp files for this worker
-        self._loader.cleanup_all_tmp_files()
+            try:
+                raise AnsibleError("Task result omitted due to queue send failure.") from ex
+            except Exception as ex_wrapper:
+                self._final_q.send_task_result(_RawTaskResult(
+                    host=self._host,
+                    task=self._task,
+                    # ignore the real task result and don't allow result object contribution from the exception (in case the pickling error was related)
+                    return_data=_error_utils.result_dict_from_exception(ex_wrapper),
+                    task_fields={},  # The failure pickling may have been caused by the task attrs, omit for safety
+                ))

ansible/executor/task_executor.py

@@ -7,7 +7,6 @@ import os
 import time
 import json
 import pathlib
-import signal
 import subprocess
 import sys
 
@@ -17,13 +16,13 @@ import typing as t
 from ansible import constants as C
 from ansible.cli import scripts
 from ansible.errors import (
-    AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleConnectionFailure, AnsibleActionFail, AnsibleActionSkip, AnsibleTaskError,
+    AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleTaskError,
     AnsibleValueOmittedError,
 )
 from ansible.executor.task_result import _RawTaskResult
 from ansible._internal._datatag import _utils
-from ansible.module_utils.common.messages import Detail, WarningSummary, DeprecationSummary, PluginInfo
-from ansible.module_utils.datatag import native_type_name
+from ansible.module_utils._internal import _messages
+from ansible.module_utils.datatag import native_type_name, deprecator_from_collection_name
 from ansible._internal._datatag._tags import TrustedAsTemplate
 from ansible.module_utils.parsing.convert_bool import boolean
 from ansible.module_utils.common.text.converters import to_text, to_native
@@ -31,7 +30,6 @@ from ansible.module_utils.connection import write_to_stream
 from ansible.module_utils.six import string_types
 from ansible.playbook.task import Task
 from ansible.plugins import get_plugin_class
-from ansible.plugins.action import ActionBase
 from ansible.plugins.loader import become_loader, cliconf_loader, connection_loader, httpapi_loader, netconf_loader, terminal_loader
 from ansible._internal._templating._jinja_plugins import _invoke_lookup, _DirectCall
 from ansible._internal._templating._engine import TemplateEngine
@@ -41,7 +39,7 @@ from ansible.utils.display import Display, _DeferredWarningContext
 from ansible.utils.vars import combine_vars
 from ansible.vars.clean import namespace_facts, clean_facts
 from ansible.vars.manager import _deprecate_top_level_fact
-from ansible._internal._errors import _captured
+from ansible._internal._errors import _captured, _task_timeout, _error_utils
 
 if t.TYPE_CHECKING:
     from ansible.executor.task_queue_manager import FinalQueue
@@ -54,24 +52,6 @@ RETURN_VARS = [x for x in C.MAGIC_VARIABLE_MAPPING.items() if 'become' not in x
 __all__ = ['TaskExecutor']
 
 
-class TaskTimeoutError(BaseException):
-    def __init__(self, message="", frame=None):
-
-        if frame is not None:
-            orig = frame
-            root = pathlib.Path(__file__).parent
-            while not pathlib.Path(frame.f_code.co_filename).is_relative_to(root):
-                frame = frame.f_back
-
-            self.frame = 'Interrupted at %s called from %s' % (orig, frame)
-
-        super(TaskTimeoutError, self).__init__(message)
-
-
-def task_timeout(signum, frame):
-    raise TaskTimeoutError(frame=frame)
-
-
 class TaskExecutor:
 
     """
@@ -176,7 +156,7 @@ class TaskExecutor:
 
             return res
         except Exception as ex:
-            result = ActionBase.result_dict_from_exception(ex)
+            result = _error_utils.result_dict_from_exception(ex)
 
             self._task.update_result_no_log(self._task_templar, result)
 
@@ -442,11 +422,11 @@ class TaskExecutor:
                 result = self._execute_internal(templar, variables)
                 self._apply_task_result_compat(result, warning_ctx)
                 _captured.AnsibleActionCapturedError.maybe_raise_on_result(result)
-            except Exception as ex:
+            except (Exception, _task_timeout.TaskTimeoutError) as ex:  # TaskTimeoutError is BaseException
                 try:
                     raise AnsibleTaskError(obj=self._task.get_ds()) from ex
                 except AnsibleTaskError as atex:
-                    result = ActionBase.result_dict_from_exception(atex)
+                    result = _error_utils.result_dict_from_exception(atex, accept_result_contribution=True)
                     result.setdefault('changed', False)
 
             self._task.update_result_no_log(templar, result)
@@ -530,7 +510,7 @@ class TaskExecutor:
         # if we ran into an error while setting up the PlayContext, raise it now, unless is known issue with delegation
         # and undefined vars (correct values are in cvars later on and connection plugins, if still error, blows up there)
 
-        # DTFIX-RELEASE: this should probably be declaratively handled in post_validate (or better, get rid of play_context)
+        # DTFIX-FUTURE: this should probably be declaratively handled in post_validate (or better, get rid of play_context)
         if context_validation_error is not None:
             raiseit = True
             if self._task.delegate_to:
@@ -539,7 +519,7 @@ class TaskExecutor:
                     if isinstance(context_validation_error.__cause__, AnsibleUndefinedVariable):
                         raiseit = False
                 elif isinstance(context_validation_error, AnsibleUndefinedVariable):
-                    # DTFIX-RELEASE: should not be possible to hit this now (all are AnsibleFieldAttributeError)?
+                    # DTFIX-FUTURE: should not be possible to hit this now (all are AnsibleFieldAttributeError)?
                     raiseit = False
             if raiseit:
                 raise context_validation_error  # pylint: disable=raising-bad-type
@@ -636,24 +616,9 @@ class TaskExecutor:
         for attempt in range(1, retries + 1):
             display.debug("running the handler")
             try:
-                if self._task.timeout:
-                    old_sig = signal.signal(signal.SIGALRM, task_timeout)
-                    signal.alarm(self._task.timeout)
-
-                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:
-                return e.result
-            except AnsibleConnectionFailure as e:
-                return dict(unreachable=True, msg=to_text(e))
-            except TaskTimeoutError as e:
-                msg = 'The %s action failed to execute in the expected time frame (%d) and was terminated' % (self._task.action, self._task.timeout)
-                return dict(failed=True, msg=msg, timedout={'frame': e.frame, 'period': self._task.timeout})
+                with _task_timeout.TaskTimeoutError.alarm_timeout(self._task.timeout):
+                    result = self._handler.run(task_vars=vars_copy)
             finally:
-                if self._task.timeout:
-                    signal.alarm(0)
-                    old_sig = signal.signal(signal.SIGALRM, old_sig)
                 self._handler.cleanup()
             display.debug("handler run complete")
 
@@ -731,7 +696,7 @@ class TaskExecutor:
             if 'skipped' not in result:
                 condname = 'changed'
 
-                # DTFIX-RELEASE: error normalization has not yet occurred; this means that the expressions used for until/failed_when/changed_when/break_when
+                # DTFIX-FUTURE: error normalization has not yet occurred; this means that the expressions used for until/failed_when/changed_when/break_when
                 #  and when (for loops on the second and later iterations) cannot see the normalized error shapes. This, and the current impl of the expression
                 #  handling here causes a number of problems:
                 #  * any error in one of the post-task exec expressions is silently ignored and detail lost (eg: `failed_when: syntax ERROR @$123`)
@@ -825,11 +790,11 @@ class TaskExecutor:
         if warnings := result.get('warnings'):
             if isinstance(warnings, list):
                 for warning in warnings:
-                    if not isinstance(warning, WarningSummary):
+                    if not isinstance(warning, _messages.WarningSummary):
                         # translate non-WarningMessageDetail messages
-                        warning = WarningSummary(
-                            details=(
-                                Detail(msg=str(warning)),
+                        warning = _messages.WarningSummary(
+                            event=_messages.Event(
+                                msg=str(warning),
                             ),
                         )
 
@@ -840,18 +805,18 @@ class TaskExecutor:
         if deprecations := result.get('deprecations'):
             if isinstance(deprecations, list):
                 for deprecation in deprecations:
-                    if not isinstance(deprecation, DeprecationSummary):
-                        # translate non-DeprecationMessageDetail message dicts
+                    if not isinstance(deprecation, _messages.DeprecationSummary):
+                        # translate non-DeprecationSummary message dicts
                         try:
                             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')
-                                deprecation.update(deprecator=PluginInfo._from_collection_name(collection_name))
+                                deprecation.update(deprecator=deprecator_from_collection_name(collection_name))
 
-                            deprecation = DeprecationSummary(
-                                details=(
-                                    Detail(msg=deprecation.pop('msg')),
+                            deprecation = _messages.DeprecationSummary(
+                                event=_messages.Event(
+                                    msg=deprecation.pop('msg'),
                                 ),
                                 **deprecation,
                             )
@@ -910,9 +875,9 @@ class TaskExecutor:
                 # have issues which result in a half-written/unparseable result
                 # file on disk, which manifests to the user as a timeout happening
                 # before it's time to timeout.
-                if (int(async_result.get('finished', 0)) == 1 or
-                        ('failed' in async_result and async_result.get('_ansible_parsed', False)) or
-                        'skipped' in async_result):
+                if (async_result.get('finished', False) or
+                   (async_result.get('failed', False) and async_result.get('_ansible_parsed', False)) or
+                   async_result.get('skipped', False)):
                     break
             except Exception as e:
                 # Connections can raise exceptions during polling (eg, network bounce, reboot); these should be non-fatal.
@@ -941,7 +906,7 @@ class TaskExecutor:
                     ),
                 )
 
-        if int(async_result.get('finished', 0)) != 1:
+        if not async_result.get('finished', False):
             if async_result.get('_ansible_parsed'):
                 return dict(failed=True, msg="async task did not complete within the requested time - %ss" % self._task.async_val, async_result=async_result)
             else:

ansible/executor/task_result.py

@@ -12,7 +12,7 @@ import typing as t
 from ansible import constants
 from ansible.utils import vars as _vars
 from ansible.vars.clean import module_response_deepcopy, strip_internal_keys
-from ansible.module_utils.common import messages as _messages
+from ansible.module_utils._internal import _messages
 from ansible._internal import _collection_proxy
 
 if t.TYPE_CHECKING:
@@ -20,7 +20,7 @@ if t.TYPE_CHECKING:
     from ansible.playbook.task import Task
 
 _IGNORE = ('failed', 'skipped')
-_PRESERVE = {'attempts', 'changed', 'retries', '_ansible_no_log'}
+_PRESERVE = {'attempts', 'changed', 'retries', '_ansible_no_log', 'exception', 'warnings', 'deprecations'}
 _SUB_PRESERVE = {'_ansible_delegated_vars': {'ansible_host', 'ansible_port', 'ansible_user', 'ansible_connection'}}
 
 # stuff callbacks need
@@ -230,8 +230,6 @@ class _RawTaskResult(_BaseTaskResult):
 class CallbackTaskResult(_BaseTaskResult):
     """Public contract of TaskResult """
 
-    # DTFIX-RELEASE: find a better home for this since it's public API
-
     @property
     def _result(self) -> _c.MutableMapping[str, t.Any]:
         """Use the `result` property when supporting only ansible-core 2.19 or later."""

ansible/galaxy/collection/__init__.py

@@ -31,6 +31,7 @@ from dataclasses import dataclass
 from hashlib import sha256
 from io import BytesIO
 from importlib.metadata import distribution
+from importlib.resources import files
 from itertools import chain
 
 try:
@@ -85,7 +86,6 @@ if t.TYPE_CHECKING:
     FilesManifestType = t.Dict[t.Literal['files', 'format'], t.Union[t.List[FileManifestEntryType], int]]
 
 import ansible.constants as C
-from ansible.compat.importlib_resources import files
 from ansible.errors import AnsibleError
 from ansible.galaxy.api import GalaxyAPI
 from ansible.galaxy.collection.concrete_artifact_manager import (
@@ -1433,9 +1433,6 @@ def find_existing_collections(path_filter, artifacts_manager, namespace_filter=N
     :param path: Collection dirs layout search path.
     :param artifacts_manager: Artifacts manager.
     """
-    if files is None:
-        raise AnsibleError('importlib_resources is not installed and is required')
-
     if path_filter and not is_sequence(path_filter):
         path_filter = [path_filter]
     if namespace_filter and not is_sequence(namespace_filter):

ansible/inventory/manager.py

@@ -313,7 +313,7 @@ class InventoryManager(object):
                             ex.obj = origin
                         failures.append({'src': source, 'plugin': plugin_name, 'exc': ex})
                     except Exception as ex:
-                        # DTFIX-RELEASE: fix this error handling to correctly deal with messaging
+                        # DTFIX-FUTURE: fix this error handling to correctly deal with messaging
                         try:
                             # omit line number to prevent contextual display of script or possibly sensitive info
                             raise AnsibleError(str(ex), obj=origin) from ex

ansible/module_utils/_internal/__init__.py

@@ -5,7 +5,6 @@ import collections.abc as c
 import typing as t
 
 
-# DTFIX-RELEASE: bikeshed "intermediate"
 INTERMEDIATE_MAPPING_TYPES = (c.Mapping,)
 """
 Mapping types which are supported for recursion and runtime usage, such as in serialization and templating.
@@ -25,13 +24,11 @@ ITERABLE_SCALARS_NOT_TO_ITERATE_FIXME = (str, bytes)
 
 def is_intermediate_mapping(value: object) -> bool:
     """Returns `True` if `value` is a type supported for projection to a Python `dict`, otherwise returns `False`."""
-    # DTFIX-RELEASE: bikeshed name
     return isinstance(value, INTERMEDIATE_MAPPING_TYPES)
 
 
 def is_intermediate_iterable(value: object) -> bool:
     """Returns `True` if `value` is a type supported for projection to a Python `list`, otherwise returns `False`."""
-    # DTFIX-RELEASE: bikeshed name
     return isinstance(value, INTERMEDIATE_ITERABLE_TYPES) and not isinstance(value, ITERABLE_SCALARS_NOT_TO_ITERATE_FIXME)
 
 

ansible/module_utils/_internal/_ambient_context.py

@@ -19,9 +19,9 @@ class AmbientContextBase:
     __slots__ = ('_contextvar_token',)
 
     # DTFIX-FUTURE: subclasses need to be able to opt-in to blocking nested contexts of the same type (basically optional per-callstack singleton behavior)
-    # DTFIX-RELEASE: this class should enforce strict nesting of contexts; overlapping context lifetimes leads to incredibly difficult to
+    # DTFIX-FUTURE: this class should enforce strict nesting of contexts; overlapping context lifetimes leads to incredibly difficult to
     #        debug situations with undefined behavior, so it should fail fast.
-    # DTFIX-RELEASE: make frozen=True dataclass subclasses work (fix the mutability of the contextvar instance)
+    # DTFIX-FUTURE: make frozen=True dataclass subclasses work (fix the mutability of the contextvar instance)
 
     _contextvar: t.ClassVar[contextvars.ContextVar]  # pylint: disable=declare-non-slot  # pylint bug, see https://github.com/pylint-dev/pylint/issues/9950
     _contextvar_token: contextvars.Token
@@ -49,7 +49,7 @@ class AmbientContextBase:
             raise ReferenceError(f"A required {cls.__name__} context is not active.") from None
 
     def __enter__(self) -> t.Self:
-        # DTFIX-RELEASE: actively block multiple entry
+        # DTFIX-FUTURE: actively block multiple entry
         self._contextvar_token = self.__class__._contextvar.set(self)
         return self
 

ansible/module_utils/_internal/_ansiballz.py

@@ -13,7 +13,7 @@ import runpy
 import sys
 import typing as t
 
-from . import _errors
+from . import _errors, _traceback, _messages
 from .. import basic
 from ..common.json import get_module_encoder, Direction
 
@@ -97,7 +97,9 @@ def _handle_exception(exception: BaseException, profile: str) -> t.NoReturn:
     """Handle the given exception."""
     result = dict(
         failed=True,
-        exception=_errors.create_error_summary(exception),
+        exception=_messages.ErrorSummary(
+            event=_errors.EventFactory.from_exception(exception, _traceback.is_traceback_enabled(_traceback.TracebackEvent.ERROR)),
+        ),
     )
 
     encoder = get_module_encoder(profile, Direction.MODULE_TO_CONTROLLER)

ansible/module_utils/_internal/_datatag/__init__.py

@@ -37,15 +37,16 @@ _ANSIBLE_TAGGED_OBJECT_SLOTS = tuple(('_ansible_tags_mapping',))
 # shared empty frozenset for default values
 _empty_frozenset: t.FrozenSet = frozenset()
 
+# Technical Notes
+#
+# Tagged values compare (and thus hash) the same as their base types, so a value that differs only by its tags will appear identical to non-tag-aware code.
+# This will affect storage and update of tagged values in dictionary keys, sets, etc. While tagged values can be used as keys in hashable collections,
+# updating a key usually requires removal and re-addition.
+
 
 class AnsibleTagHelper:
     """Utility methods for working with Ansible data tags."""
 
-    # DTFIX-RELEASE: bikeshed the name and location of this class, also, related, how much more of it should be exposed as public API?
-    #        it may make sense to move this into another module, but the implementations should remain here (so they can be used without circular imports here)
-    #        if they're in a separate module, is a class even needed, or should they be globals?
-    # DTFIX-RELEASE: add docstrings to all non-override methods in this class
-
     @staticmethod
     def untag(value: _T, *tag_types: t.Type[AnsibleDatatagBase]) -> _T:
         """
@@ -105,7 +106,7 @@ class AnsibleTagHelper:
         if issubclass(the_type, AnsibleTaggedObject):
             the_type = type_or_value._native_type
 
-        # DTFIX-RELEASE: provide a way to report the real type for debugging purposes
+        # DTFIX-FUTURE: provide a knob to optionally report the real type for debugging purposes
         return the_type
 
     @staticmethod
@@ -339,10 +340,11 @@ class AnsibleSerializableDateTime(AnsibleSerializableWrapper[datetime.datetime])
 @dataclasses.dataclass(**_tag_dataclass_kwargs)
 class AnsibleSerializableDataclass(AnsibleSerializable, metaclass=abc.ABCMeta):
     _validation_allow_subclasses = True
+    _validation_auto_enabled = True
 
     def _as_dict(self) -> t.Dict[str, t.Any]:
         # omit None values when None is the field default
-        # DTFIX-RELEASE: this implementation means we can never change the default on fields which have None for their default
+        # DTFIX-FUTURE: this implementation means we can never change the default on fields which have None for their default
         #          other defaults can be changed -- but there's no way to override this behavior either way for other default types
         #          it's a trip hazard to have the default logic here, rather than per field (or not at all)
         #          consider either removing the filtering or requiring it to be explicitly set per field using dataclass metadata
@@ -351,7 +353,7 @@ class AnsibleSerializableDataclass(AnsibleSerializable, metaclass=abc.ABCMeta):
 
     @classmethod
     def _from_dict(cls, d: t.Dict[str, t.Any]) -> t.Self:
-        # DTFIX-RELEASE: optimize this to avoid the dataclasses fields metadata and get_origin stuff at runtime
+        # DTFIX-FUTURE: optimize this to avoid the dataclasses fields metadata and get_origin stuff at runtime
         type_hints = t.get_type_hints(cls)
         mutated_dict: dict[str, t.Any] | None = None
 
@@ -368,7 +370,11 @@ class AnsibleSerializableDataclass(AnsibleSerializable, metaclass=abc.ABCMeta):
     def __init_subclass__(cls, **kwargs) -> None:
         super(AnsibleSerializableDataclass, cls).__init_subclass__(**kwargs)  # cannot use super() without arguments when using slots
 
-        _dataclass_validation.inject_post_init_validation(cls, cls._validation_allow_subclasses)  # code gen a real __post_init__ method
+        if cls._validation_auto_enabled:
+            try:
+                _dataclass_validation.inject_post_init_validation(cls, cls._validation_allow_subclasses)  # code gen a real __post_init__ method
+            except Exception as ex:
+                raise Exception(f'Validation code generation failed on {cls}.') from ex
 
 
 class Tripwire:
@@ -524,7 +530,6 @@ class CollectionWithMro(c.Collection, t.Protocol):
     __mro__: tuple[type, ...]
 
 
-# DTFIX-RELEASE: This should probably reside elsewhere.
 def is_non_scalar_collection_type(value: type) -> t.TypeGuard[type[CollectionWithMro]]:
     """Returns True if the value is a non-scalar collection type, otherwise returns False."""
     return issubclass(value, c.Collection) and not issubclass(value, str) and not issubclass(value, bytes)
@@ -878,7 +883,6 @@ class _AnsibleTaggedList(list, AnsibleTaggedObject):
     # Propagation of tags in these cases is left to the caller, based on needs specific to their use case.
 
 
-# DTFIX-RELEASE: do we want frozenset too?
 class _AnsibleTaggedSet(set, AnsibleTaggedObject):
     __slots__ = _ANSIBLE_TAGGED_OBJECT_SLOTS
 
@@ -914,10 +918,12 @@ class _AnsibleTaggedTuple(tuple, AnsibleTaggedObject):
         return super()._copy_collection()
 
 
-# This set gets augmented with additional types when some controller-only types are imported.
-# While we could proxy or subclass builtin singletons, they're idiomatically compared with "is" reference
-# equality, which we can't customize.
 _untaggable_types = {type(None), bool}
+"""
+Attempts to apply tags to values of these types will be silently ignored.
+While we could proxy or subclass builtin singletons, they're idiomatically compared with "is" reference equality, which we can't customize.
+This set gets augmented with additional types when some controller-only types are imported.
+"""
 
 # noinspection PyProtectedMember
 _ANSIBLE_ALLOWED_VAR_TYPES = frozenset({type(None), bool}) | set(AnsibleTaggedObject._tagged_type_map) | set(AnsibleTaggedObject._tagged_type_map.values())

ansible/module_utils/_internal/_datatag/_tags.py

@@ -3,8 +3,7 @@ from __future__ import annotations
 import dataclasses
 import typing as t
 
-from ansible.module_utils.common import messages as _messages
-from ansible.module_utils._internal import _datatag
+from ansible.module_utils._internal import _datatag, _messages
 
 
 @dataclasses.dataclass(**_datatag._tag_dataclass_kwargs)
@@ -14,3 +13,4 @@ class Deprecated(_datatag.AnsibleDatatagBase):
     date: t.Optional[str] = None
     version: t.Optional[str] = None
     deprecator: t.Optional[_messages.PluginInfo] = None
+    formatted_traceback: t.Optional[str] = None