ansible-core 2.19.0b4__py3-none-any.whl → 2.19.0b6__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()
@@ -142,8 +138,8 @@ class WorkerProcess(multiprocessing_context.Process):  # type: ignore[name-defin
         try:
             display.debug(u"WORKER HARD EXIT: %s" % to_text(e))
         except BaseException:
-            # If the cause of the fault is IOError being generated by stdio,
-            # attempting to log a debug message may trigger another IOError.
+            # If the cause of the fault is OSError being generated by stdio,
+            # attempting to log a debug message may trigger another OSError.
             # Try printing once then give up.
             pass
 
@@ -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/api.py

@@ -337,10 +337,7 @@ class GalaxyAPI:
         if not isinstance(other_galaxy_api, self.__class__):
             return NotImplemented
 
-        return (
-            self._priority > other_galaxy_api._priority or
-            self.name < self.name
-        )
+        return self._priority > other_galaxy_api._priority
 
     @property  # type: ignore[misc]  # https://github.com/python/mypy/issues/1362
     @g_connect(['v1', 'v2', 'v3'])

ansible/galaxy/collection/__init__.py

@@ -5,7 +5,6 @@
 
 from __future__ import annotations
 
-import errno
 import fnmatch
 import functools
 import glob
@@ -31,6 +30,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 +85,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 +1432,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):
@@ -1692,11 +1688,7 @@ def _extract_tar_dir(tar, dirname, b_dest):
     b_dir_path = os.path.join(b_dest, to_bytes(dirname, errors='surrogate_or_strict'))
 
     b_parent_path = os.path.dirname(b_dir_path)
-    try:
-        os.makedirs(b_parent_path, mode=S_IRWXU_RXG_RXO)
-    except OSError as e:
-        if e.errno != errno.EEXIST:
-            raise
+    os.makedirs(b_parent_path, mode=S_IRWXU_RXG_RXO, exist_ok=True)
 
     if tar_member.type == tarfile.SYMTYPE:
         b_link_path = to_bytes(tar_member.linkname, errors='surrogate_or_strict')

ansible/galaxy/collection/concrete_artifact_manager.py

@@ -656,14 +656,8 @@ def _get_json_from_installed_dir(
     try:
         with open(b_json_filepath, 'rb') as manifest_fd:
             b_json_text = manifest_fd.read()
-    except (IOError, OSError):
-        raise LookupError(
-            "The collection {manifest!s} path '{path!s}' does not exist.".
-            format(
-                manifest=filename,
-                path=to_native(b_json_filepath),
-            )
-        )
+    except OSError as ex:
+        raise LookupError(f"The collection {filename!r} path {to_text(b_json_filepath)!r} does not exist.") from ex
 
     manifest_txt = to_text(b_json_text, errors='surrogate_or_strict')
 

ansible/galaxy/role.py

@@ -438,8 +438,8 @@ class GalaxyRole(object):
                 if not (self.src and os.path.isfile(self.src)):
                     try:
                         os.unlink(tmp_file)
-                    except (OSError, IOError) as e:
-                        display.warning(u"Unable to remove tmp file (%s): %s" % (tmp_file, to_text(e)))
+                    except OSError as ex:
+                        display.error_as_warning(f"Unable to remove tmp file {tmp_file!r}.", exception=ex)
                 return True
 
         return False

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

@@ -4,8 +4,10 @@ import collections.abc as c
 
 import typing as t
 
+if t.TYPE_CHECKING:
+    from ansible.module_utils.compat.typing import TypeGuard
+
 
-# 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.
@@ -19,20 +21,18 @@ These will be converted to a simple Python `list` before serialization or storag
 CAUTION: Scalar types which are sequences should be excluded when using this.
 """
 
-ITERABLE_SCALARS_NOT_TO_ITERATE_FIXME = (str, bytes)
+ITERABLE_SCALARS_NOT_TO_ITERATE = (str, bytes)
 """Scalars which are also iterable, and should thus be excluded from iterable checks."""
 
 
-def is_intermediate_mapping(value: object) -> bool:
+def is_intermediate_mapping(value: object) -> TypeGuard[c.Mapping]:
     """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:
+def is_intermediate_iterable(value: object) -> TypeGuard[c.Iterable]:
     """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)
+    return isinstance(value, INTERMEDIATE_ITERABLE_TYPES) and not isinstance(value, ITERABLE_SCALARS_NOT_TO_ITERATE)
 
 
 is_controller: bool = False

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/_extensions/_coverage.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import atexit
+import dataclasses
+import importlib.util
+import os
+import sys
+
+import typing as t
+
+
+@dataclasses.dataclass(frozen=True)
+class Options:
+    """Code coverage options."""
+
+    config: str
+    output: str | None
+
+
+def run(args: dict[str, t.Any]) -> None:  # pragma: nocover
+    """Bootstrap `coverage` for the current Ansible module invocation."""
+    options = Options(**args)
+
+    if options.output:
+        # Enable code coverage analysis of the module.
+        # This feature is for internal testing and may change without notice.
+        python_version_string = '.'.join(str(v) for v in sys.version_info[:2])
+        os.environ['COVERAGE_FILE'] = f'{options.output}=python-{python_version_string}=coverage'
+
+        import coverage
+
+        cov = coverage.Coverage(config_file=options.config)
+
+        def atexit_coverage() -> None:
+            cov.stop()
+            cov.save()
+
+        atexit.register(atexit_coverage)
+
+        cov.start()
+    else:
+        # Verify coverage is available without importing it.
+        # This will detect when a module would fail with coverage enabled with minimal overhead.
+        if importlib.util.find_spec('coverage') is None:
+            raise RuntimeError('Could not find the `coverage` Python module.')