ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/_internal/__init__.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import importlib
+import typing as t
+
+from ansible.module_utils import _internal
+from ansible.module_utils._internal._json import _profiles
+
+
+def get_controller_serialize_map() -> dict[type, t.Callable]:
+    """
+    Injected into module_utils code to augment serialization maps with controller-only types.
+    This implementation replaces the no-op version in module_utils._internal in controller contexts.
+    """
+    from ansible._internal._templating import _lazy_containers
+    from ansible.parsing.vault import EncryptedString
+
+    return {
+        _lazy_containers._AnsibleLazyTemplateDict: _profiles._JSONSerializationProfile.discard_tags,
+        _lazy_containers._AnsibleLazyTemplateList: _profiles._JSONSerializationProfile.discard_tags,
+        EncryptedString: str,  # preserves tags since this is an intance of EncryptedString; if tags should be discarded from str, another entry will handle it
+    }
+
+
+def import_controller_module(module_name: str, /) -> t.Any:
+    """
+    Injected into module_utils code to import and return the specified module.
+    This implementation replaces the no-op version in module_utils._internal in controller contexts.
+    """
+    return importlib.import_module(module_name)
+
+
+_T = t.TypeVar('_T')
+
+
+def experimental(obj: _T) -> _T:
+    """
+    Decorator for experimental types and methods outside the `_internal` package which accept or expose internal types.
+    As with internal APIs, these are subject to change at any time without notice.
+    """
+    return obj
+
+
+def setup() -> None:
+    """No-op function to ensure that side-effect only imports of this module are not flagged/removed as 'unused'."""
+
+
+# DTFIX-RELEASE: this is really fragile- disordered/incorrect imports (among other things) can mess it up. Consider a hosting-env-managed context
+#  with an enum with at least Controller/Target/Unknown values, and possibly using lazy-init module shims or some other mechanism to allow controller-side
+#  notification/augmentation of this kind of metadata.
+_internal.get_controller_serialize_map = get_controller_serialize_map
+_internal.import_controller_module = import_controller_module
+_internal.is_controller = True

ansible/_internal/_ansiballz.py

@@ -0,0 +1,265 @@
+# shebang placeholder
+
+from __future__ import annotations
+
+import datetime
+
+# For test-module.py script to tell this is a ANSIBALLZ_WRAPPER
+_ANSIBALLZ_WRAPPER = True
+
+# This code is part of Ansible, but is an independent component.
+# The code in this particular templatable string, and this templatable string
+# only, is BSD licensed.  Modules which end up using this snippet, which is
+# dynamically combined together by Ansible still belong to the author of the
+# module, and they may assign their own license to the complete work.
+#
+# Copyright (c), James Cammarata, 2016
+# Copyright (c), Toshio Kuratomi, 2016
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright
+#      notice, this list of conditions and the following disclaimer.
+#    * Redistributions in binary form must reproduce the above copyright notice,
+#      this list of conditions and the following disclaimer in the documentation
+#      and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+def _ansiballz_main(
+    zipdata: str,
+    ansible_module: str,
+    module_fqn: str,
+    params: str,
+    profile: str,
+    plugin_info_dict: dict[str, object],
+    date_time: datetime.datetime,
+    coverage_config: str | None,
+    coverage_output: str | None,
+    rlimit_nofile: int,
+) -> None:
+    import os
+    import os.path
+
+    # Access to the working directory is required by Python when using pipelining, as well as for the coverage module.
+    # Some platforms, such as macOS, may not allow querying the working directory when using become to drop privileges.
+    try:
+        os.getcwd()
+    except OSError:
+        try:
+            os.chdir(os.path.expanduser('~'))
+        except OSError:
+            os.chdir('/')
+
+    if rlimit_nofile:
+        import resource
+
+        existing_soft, existing_hard = resource.getrlimit(resource.RLIMIT_NOFILE)
+
+        # adjust soft limit subject to existing hard limit
+        requested_soft = min(existing_hard, rlimit_nofile)
+
+        if requested_soft != existing_soft:
+            try:
+                resource.setrlimit(resource.RLIMIT_NOFILE, (requested_soft, existing_hard))
+            except ValueError:
+                # some platforms (eg macOS) lie about their hard limit
+                pass
+
+    import sys
+    import __main__
+
+    # For some distros and python versions we pick up this script in the temporary
+    # directory.  This leads to problems when the ansible module masks a python
+    # library that another import needs.  We have not figured out what about the
+    # specific distros and python versions causes this to behave differently.
+    #
+    # Tested distros:
+    # Fedora23 with python3.4  Works
+    # Ubuntu15.10 with python2.7  Works
+    # Ubuntu15.10 with python3.4  Fails without this
+    # Ubuntu16.04.1 with python3.5  Fails without this
+    # To test on another platform:
+    # * use the copy module (since this shadows the stdlib copy module)
+    # * Turn off pipelining
+    # * Make sure that the destination file does not exist
+    # * ansible ubuntu16-test -m copy -a 'src=/etc/motd dest=/var/tmp/m'
+    # This will traceback in shutil.  Looking at the complete traceback will show
+    # that shutil is importing copy which finds the ansible module instead of the
+    # stdlib module
+    scriptdir = None
+    try:
+        scriptdir = os.path.dirname(os.path.realpath(__main__.__file__))
+    except (AttributeError, OSError):
+        # Some platforms don't set __file__ when reading from stdin
+        # OSX raises OSError if using abspath() in a directory we don't have
+        # permission to read (realpath calls abspath)
+        pass
+
+    # Strip cwd from sys.path to avoid potential permissions issues
+    excludes = {'', '.', scriptdir}
+    sys.path = [p for p in sys.path if p not in excludes]
+
+    import base64
+    import shutil
+    import tempfile
+    import zipfile
+
+    def invoke_module(modlib_path: str, json_params: bytes) -> None:
+        # When installed via setuptools (including python setup.py install),
+        # ansible may be installed with an easy-install.pth file.  That file
+        # may load the system-wide install of ansible rather than the one in
+        # the module.  sitecustomize is the only way to override that setting.
+        z = zipfile.ZipFile(modlib_path, mode='a')
+
+        # py3: modlib_path will be text, py2: it's bytes.  Need bytes at the end
+        sitecustomize = u'import sys\\nsys.path.insert(0,"%s")\\n' % modlib_path
+        sitecustomize = sitecustomize.encode('utf-8')
+        # Use a ZipInfo to work around zipfile limitation on hosts with
+        # clocks set to a pre-1980 year (for instance, Raspberry Pi)
+        zinfo = zipfile.ZipInfo()
+        zinfo.filename = 'sitecustomize.py'
+        zinfo.date_time = date_time.utctimetuple()[:6]
+        z.writestr(zinfo, sitecustomize)
+        z.close()
+
+        # Put the zipped up module_utils we got from the controller first in the python path so that we
+        # can monkeypatch the right basic
+        sys.path.insert(0, modlib_path)
+
+        from ansible.module_utils._internal._ansiballz import run_module
+
+        run_module(
+            json_params=json_params,
+            profile=profile,
+            plugin_info_dict=plugin_info_dict,
+            module_fqn=module_fqn,
+            modlib_path=modlib_path,
+            coverage_config=coverage_config,
+            coverage_output=coverage_output,
+        )
+
+    def debug(command: str, modlib_path: str, json_params: bytes) -> None:
+        # The code here normally doesn't run.  It's only used for debugging on the
+        # remote machine.
+        #
+        # The subcommands in this function make it easier to debug ansiballz
+        # modules.  Here's the basic steps:
+        #
+        # Run ansible with the environment variable: ANSIBLE_KEEP_REMOTE_FILES=1 and -vvv
+        # to save the module file remotely::
+        #   $ ANSIBLE_KEEP_REMOTE_FILES=1 ansible host1 -m ping -a 'data=october' -vvv
+        #
+        # Part of the verbose output will tell you where on the remote machine the
+        # module was written to::
+        #   [...]
+        #   <host1> SSH: EXEC ssh -C -q -o ControlMaster=auto -o ControlPersist=60s -o KbdInteractiveAuthentication=no -o
+        #   PreferredAuthentications=gssapi-with-mic,gssapi-keyex,hostbased,publickey -o PasswordAuthentication=no -o ConnectTimeout=10 -o
+        #   ControlPath=/home/badger/.ansible/cp/ansible-ssh-%h-%p-%r -tt rhel7 '/bin/sh -c '"'"'LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8
+        #   LC_MESSAGES=en_US.UTF-8 /usr/bin/python /home/badger/.ansible/tmp/ansible-tmp-1461173013.93-9076457629738/ping'"'"''
+        #   [...]
+        #
+        # Login to the remote machine and run the module file via from the previous
+        # step with the explode subcommand to extract the module payload into
+        # source files::
+        #   $ ssh host1
+        #   $ /usr/bin/python /home/badger/.ansible/tmp/ansible-tmp-1461173013.93-9076457629738/ping explode
+        #   Module expanded into:
+        #   /home/badger/.ansible/tmp/ansible-tmp-1461173408.08-279692652635227/ansible
+        #
+        # You can now edit the source files to instrument the code or experiment with
+        # different parameter values.  When you're ready to run the code you've modified
+        # (instead of the code from the actual zipped module), use the execute subcommand like this::
+        #   $ /usr/bin/python /home/badger/.ansible/tmp/ansible-tmp-1461173013.93-9076457629738/ping execute
+
+        # Okay to use __file__ here because we're running from a kept file
+        basedir = os.path.join(os.path.abspath(os.path.dirname(__file__)), 'debug_dir')
+        args_path = os.path.join(basedir, 'args')
+
+        if command == 'explode':
+            # transform the ZIPDATA into an exploded directory of code and then
+            # print the path to the code.  This is an easy way for people to look
+            # at the code on the remote machine for debugging it in that
+            # environment
+            z = zipfile.ZipFile(modlib_path)
+            for filename in z.namelist():
+                if filename.startswith('/'):
+                    raise Exception('Something wrong with this module zip file: should not contain absolute paths')
+
+                dest_filename = os.path.join(basedir, filename)
+                if dest_filename.endswith(os.path.sep) and not os.path.exists(dest_filename):
+                    os.makedirs(dest_filename)
+                else:
+                    directory = os.path.dirname(dest_filename)
+                    if not os.path.exists(directory):
+                        os.makedirs(directory)
+                    with open(dest_filename, 'wb') as writer:
+                        writer.write(z.read(filename))
+
+            # write the args file
+            with open(args_path, 'wb') as writer:
+                writer.write(json_params)
+
+            print('Module expanded into:')
+            print(basedir)
+
+        elif command == 'execute':
+            # Execute the exploded code instead of executing the module from the
+            # embedded ZIPDATA.  This allows people to easily run their modified
+            # code on the remote machine to see how changes will affect it.
+
+            # Set pythonpath to the debug dir
+            sys.path.insert(0, basedir)
+
+            # read in the args file which the user may have modified
+            with open(args_path, 'rb') as reader:
+                json_params = reader.read()
+
+            from ansible.module_utils._internal._ansiballz import run_module
+
+            run_module(
+                json_params=json_params,
+                profile=profile,
+                plugin_info_dict=plugin_info_dict,
+                module_fqn=module_fqn,
+                modlib_path=modlib_path,
+            )
+
+        else:
+            print('WARNING: Unknown debug command.  Doing nothing.')
+
+    #
+    # See comments in the debug() method for information on debugging
+    #
+
+    encoded_params = params.encode()
+
+    # There's a race condition with the controller removing the
+    # remote_tmpdir and this module executing under async.  So we cannot
+    # store this in remote_tmpdir (use system tempdir instead)
+    # Only need to use [ansible_module]_payload_ in the temp_path until we move to zipimport
+    # (this helps ansible-test produce coverage stats)
+    temp_path = tempfile.mkdtemp(prefix='ansible_' + ansible_module + '_payload_')
+
+    try:
+        zipped_mod = os.path.join(temp_path, 'ansible_' + ansible_module + '_payload.zip')
+
+        with open(zipped_mod, 'wb') as modlib:
+            modlib.write(base64.b64decode(zipdata))
+
+        if len(sys.argv) == 2:
+            debug(sys.argv[1], zipped_mod, encoded_params)
+        else:
+            invoke_module(zipped_mod, encoded_params)
+    finally:
+        shutil.rmtree(temp_path, ignore_errors=True)

ansible/_internal/_collection_proxy.py

@@ -0,0 +1,47 @@
+from __future__ import annotations as _annotations
+
+import collections.abc as _c
+import typing as _t
+
+_T_co = _t.TypeVar('_T_co', covariant=True)
+
+
+class SequenceProxy(_c.Sequence[_T_co]):
+    """A read-only sequence proxy."""
+
+    # DTFIX-RELEASE: needs unit test coverage
+
+    __slots__ = ('__value',)
+
+    def __init__(self, value: _c.Sequence[_T_co]) -> None:
+        self.__value = value
+
+    @_t.overload
+    def __getitem__(self, index: int) -> _T_co: ...
+
+    @_t.overload
+    def __getitem__(self, index: slice) -> _c.Sequence[_T_co]: ...
+
+    def __getitem__(self, index: int | slice) -> _T_co | _c.Sequence[_T_co]:
+        if isinstance(index, slice):
+            return self.__class__(self.__value[index])
+
+        return self.__value[index]
+
+    def __len__(self) -> int:
+        return len(self.__value)
+
+    def __contains__(self, item: object) -> bool:
+        return item in self.__value
+
+    def __iter__(self) -> _t.Iterator[_T_co]:
+        yield from self.__value
+
+    def __reversed__(self) -> _c.Iterator[_T_co]:
+        return reversed(self.__value)
+
+    def index(self, *args) -> int:
+        return self.__value.index(*args)
+
+    def count(self, value: object) -> int:
+        return self.__value.count(value)

ansible/_internal/_datatag/_tags.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+import types
+import typing as t
+
+from ansible.module_utils._internal._datatag import _tag_dataclass_kwargs, AnsibleDatatagBase, AnsibleSingletonTagBase
+
+
+@dataclasses.dataclass(**_tag_dataclass_kwargs)
+class Origin(AnsibleDatatagBase):
+    """
+    A tag that stores origin metadata for a tagged value, intended for forensic/diagnostic use.
+    Origin metadata should not be used to make runtime decisions, as it is not guaranteed to be present or accurate.
+    Setting both `path` and `line_num` can result in diagnostic display of referenced file contents.
+    Either `path` or `description` must be present.
+    """
+
+    path: str | None = None
+    """The path from which the tagged content originated."""
+    description: str | None = None
+    """A description of the origin, for display to users."""
+    line_num: int | None = None
+    """An optional line number, starting at 1."""
+    col_num: int | None = None
+    """An optional column number, starting at 1."""
+
+    UNKNOWN: t.ClassVar[t.Self]
+
+    @classmethod
+    def get_or_create_tag(cls, value: t.Any, path: str | os.PathLike | None) -> Origin:
+        """Return the tag from the given value, creating a tag from the provided path if no tag was found."""
+        if not (origin := cls.get_tag(value)):
+            if path:
+                origin = Origin(path=str(path))  # convert tagged strings and path-like values to a native str
+            else:
+                origin = Origin.UNKNOWN
+
+        return origin
+
+    def replace(
+        self,
+        path: str | types.EllipsisType = ...,
+        description: str | types.EllipsisType = ...,
+        line_num: int | None | types.EllipsisType = ...,
+        col_num: int | None | types.EllipsisType = ...,
+    ) -> t.Self:
+        """Return a new origin based on an existing one, with the given fields replaced."""
+        return dataclasses.replace(
+            self,
+            **{
+                key: value
+                for key, value in dict(
+                    path=path,
+                    description=description,
+                    line_num=line_num,
+                    col_num=col_num,
+                ).items()
+                if value is not ...
+            },  # type: ignore[arg-type]
+        )
+
+    def _post_validate(self) -> None:
+        if self.path:
+            if not self.path.startswith('/'):
+                raise RuntimeError('The `src` field must be an absolute path.')
+        elif not self.description:
+            raise RuntimeError('The `src` or `description` field must be specified.')
+
+    def __str__(self) -> str:
+        """Renders the origin in the form of path:line_num:col_num, omitting missing/invalid elements from the right."""
+        if self.path:
+            value = self.path
+        else:
+            value = self.description
+
+        if self.line_num and self.line_num > 0:
+            value += f':{self.line_num}'
+
+            if self.col_num and self.col_num > 0:
+                value += f':{self.col_num}'
+
+        if self.path and self.description:
+            value += f' ({self.description})'
+
+        return value
+
+
+Origin.UNKNOWN = Origin(description='<unknown>')
+
+
+@dataclasses.dataclass(**_tag_dataclass_kwargs)
+class VaultedValue(AnsibleDatatagBase):
+    """Tag for vault-encrypted strings that carries the original ciphertext for round-tripping."""
+
+    ciphertext: str
+
+    def _get_tag_to_propagate(self, src: t.Any, value: object, *, value_type: t.Optional[type] = None) -> t.Self | None:
+        # Since VaultedValue stores the encrypted representation of the value on which it is tagged,
+        # it is incorrect to propagate the tag to a value which is not equal to the original.
+        # If the tag were copied to another value and subsequently serialized as the original encrypted value,
+        # the result would then differ from the value on which the tag was applied.
+
+        # Comparisons which can trigger an exception are indicative of a bug and should not be handled here.
+        # For example:
+        # * When `src` is an undecryptable `EncryptedString` -- it is not valid to apply this tag to that type.
+        # * When `value` is a `Marker` -- this requires a templating, but vaulted values do not support templating.
+
+        if src == value:  # assume the tag was correctly applied to src
+            return self  # same plaintext value, tag propagation with same ciphertext is safe
+
+        return self.get_tag(value)  # different value, preserve the existing tag, if any
+
+
+@dataclasses.dataclass(**_tag_dataclass_kwargs)
+class TrustedAsTemplate(AnsibleSingletonTagBase):
+    """
+    Indicates the tagged string is trusted to parse and render as a template.
+    Do *NOT* apply this tag to data from untrusted sources, as this would allow code injection during templating.
+    """
+
+
+@dataclasses.dataclass(**_tag_dataclass_kwargs)
+class SourceWasEncrypted(AnsibleSingletonTagBase):
+    """
+    For internal use only.
+    Indicates the tagged value was sourced from an encrypted file.
+    Currently applied only by DataLoader.get_text_file_contents() and by extension DataLoader.load_from_file().
+    """

ansible/_internal/_datatag/_utils.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from ansible.module_utils._internal._datatag import AnsibleTagHelper
+
+
+def str_problematic_strip(value: str) -> str:
+    """
+    Return a copy of `value` with leading and trailing whitespace removed.
+    Used where `str.strip` is needed, but tags must be preserved *AND* the stripping behavior likely shouldn't exist.
+    If the stripping behavior is non-problematic, use `AnsibleTagHelper.tag_copy` around `str.strip` instead.
+    """
+    if (stripped_value := value.strip()) == value:
+        return value
+
+    # FUTURE: consider deprecating some/all usages of this method; they generally imply a code smell or pattern we shouldn't be supporting
+
+    stripped_value = AnsibleTagHelper.tag_copy(value, stripped_value)
+
+    return stripped_value

ansible/_internal/_datatag/_wrappers.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import io
+import typing as _t
+
+from .._wrapt import ObjectProxy
+from ...module_utils._internal import _datatag
+
+
+class TaggedStreamWrapper(ObjectProxy):
+    """
+    Janky proxy around IOBase to allow streams to carry tags and support basic interrogation by the tagging API.
+    Most tagging operations will have undefined behavior for this type.
+    """
+
+    _self__ansible_tags_mapping: _datatag._AnsibleTagsMapping
+
+    def __init__(self, stream: io.IOBase, tags: _datatag.AnsibleDatatagBase | _t.Iterable[_datatag.AnsibleDatatagBase]) -> None:
+        super().__init__(stream)
+
+        tag_list: list[_datatag.AnsibleDatatagBase]
+
+        # noinspection PyProtectedMember
+        if type(tags) in _datatag._known_tag_types:
+            tag_list = [tags]  # type: ignore[list-item]
+        else:
+            tag_list = list(tags)  # type: ignore[arg-type]
+
+        self._self__ansible_tags_mapping = _datatag._AnsibleTagsMapping((type(tag), tag) for tag in tag_list)
+
+    @property
+    def _ansible_tags_mapping(self) -> _datatag._AnsibleTagsMapping:
+        return self._self__ansible_tags_mapping

ansible/_internal/_errors/_captured.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from ansible.errors import AnsibleRuntimeError
+from ansible.module_utils.common.messages import ErrorSummary, Detail, _dataclass_kwargs
+
+
+class AnsibleCapturedError(AnsibleRuntimeError):
+    """An exception representing error detail captured in another context where the error detail must be serialized to be preserved."""
+
+    context: t.ClassVar[str]
+
+    def __init__(
+        self,
+        *,
+        obj: t.Any = None,
+        error_summary: ErrorSummary,
+    ) -> None:
+        super().__init__(
+            obj=obj,
+        )
+
+        self._error_summary = error_summary
+
+    @property
+    def error_summary(self) -> ErrorSummary:
+        return self._error_summary
+
+
+class AnsibleResultCapturedError(AnsibleCapturedError):
+    """An exception representing error detail captured in a foreign context where an action/module result dictionary is involved."""
+
+    def __init__(self, error_summary: ErrorSummary, result: dict[str, t.Any]) -> None:
+        super().__init__(error_summary=error_summary)
+
+        self._result = result
+
+    @classmethod
+    def maybe_raise_on_result(cls, result: dict[str, t.Any]) -> None:
+        """Normalize the result and raise an exception if the result indicated failure."""
+        if error_summary := cls.normalize_result_exception(result):
+            raise error_summary.error_type(error_summary, result)
+
+    @classmethod
+    def find_first_remoted_error(cls, exception: BaseException) -> t.Self | None:
+        """Find the first captured module error in the cause chain, starting with the given exception, returning None if not found."""
+        while exception:
+            if isinstance(exception, cls):
+                return exception
+
+            exception = exception.__cause__
+
+        return None
+
+    @classmethod
+    def normalize_result_exception(cls, result: dict[str, t.Any]) -> CapturedErrorSummary | None:
+        """
+        Normalize the result `exception`, if any, to be a `CapturedErrorSummary` instance.
+        If a new `CapturedErrorSummary` was created, the `error_type` will be `cls`.
+        The `exception` key will be removed if falsey.
+        A `CapturedErrorSummary` instance will be returned if `failed` is truthy.
+        """
+        if type(cls) is AnsibleResultCapturedError:  # pylint: disable=unidiomatic-typecheck
+            raise TypeError('The normalize_result_exception method cannot be called on the AnsibleCapturedError base type, use a derived type.')
+
+        if not isinstance(result, dict):
+            raise TypeError(f'Malformed result. Received {type(result)} instead of {dict}.')
+
+        failed = result.get('failed')  # DTFIX-FUTURE: warn if failed is present and not a bool, or exception is present without failed being True
+        exception = result.pop('exception', None)
+
+        if not failed and not exception:
+            return None
+
+        if isinstance(exception, CapturedErrorSummary):
+            error_summary = exception
+        elif isinstance(exception, ErrorSummary):
+            error_summary = CapturedErrorSummary(
+                details=exception.details,
+                formatted_traceback=cls._normalize_traceback(exception.formatted_traceback),
+                error_type=cls,
+            )
+        else:
+            # translate non-ErrorDetail errors
+            error_summary = CapturedErrorSummary(
+                details=(Detail(msg=str(result.get('msg', 'Unknown error.'))),),
+                formatted_traceback=cls._normalize_traceback(exception),
+                error_type=cls,
+            )
+
+        result.update(exception=error_summary)
+
+        return error_summary if failed else None  # even though error detail was normalized, only return it if the result indicated failure
+
+    @classmethod
+    def _normalize_traceback(cls, value: object | None) -> str | None:
+        """Normalize the provided traceback value, returning None if it is falsey."""
+        if not value:
+            return None
+
+        value = str(value).rstrip()
+
+        if not value:
+            return None
+
+        return value + '\n'
+
+
+class AnsibleActionCapturedError(AnsibleResultCapturedError):
+    """An exception representing error detail sourced directly by an action in its result dictionary."""
+
+    _default_message = 'Action failed.'
+    context = 'action'
+
+
+class AnsibleModuleCapturedError(AnsibleResultCapturedError):
+    """An exception representing error detail captured in a module context and returned from an action's result dictionary."""
+
+    _default_message = 'Module failed.'
+    context = 'target'
+
+
+@dataclasses.dataclass(**_dataclass_kwargs)
+class CapturedErrorSummary(ErrorSummary):
+    # DTFIX-RELEASE: where to put this, name, etc. since it shows up in results, it's not exactly private (and contains a type ref to an internal type)
+    error_type: type[AnsibleResultCapturedError] | None = None