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

ansible/module_utils/_internal/_ansiballz/_extensions/_pydevd.py

@@ -0,0 +1,62 @@
+"""
+Remote debugging support for AnsiballZ modules.
+
+To use with PyCharm:
+
+1) Choose an available port for PyCharm to listen on (e.g. 5678).
+2) Create a Python Debug Server using that port.
+3) Start the Python Debug Server.
+4) Ensure the correct version of `pydevd-pycharm` is installed for the interpreter(s) which will run the code being debugged.
+5) Configure Ansible with the `_ANSIBALLZ_DEBUGGER_CONFIG` option.
+   See `Options` below for the structure of the debugger configuration.
+   Example configuration using an environment variable:
+     export _ANSIBLE_ANSIBALLZ_DEBUGGER_CONFIG='{"module": "pydevd_pycharm", "settrace": {"host": "localhost", "port": 5678, "suspend": false}}'
+6) Set any desired breakpoints.
+7) Run Ansible commands.
+
+A similar process should work for other pydevd based debuggers, such as Visual Studio Code, but they have not been tested.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib
+import json
+import os
+import pathlib
+
+import typing as t
+
+
+@dataclasses.dataclass(frozen=True)
+class Options:
+    """Debugger options for pydevd and its derivatives."""
+
+    module: str = 'pydevd'
+    """The Python module which will be imported and which provides the `settrace` method."""
+    settrace: dict[str, object] = dataclasses.field(default_factory=dict)
+    """The options to pass to the `{module}.settrace` method."""
+    source_mapping: dict[str, str] = dataclasses.field(default_factory=dict)
+    """
+    A mapping of source paths to provide to pydevd.
+    This setting is used internally by AnsiballZ and is not required unless Ansible CLI commands are run from a different system than your IDE.
+    In that scenario, use this setting instead of configuring source mapping in your IDE.
+    The key is a path known to the IDE.
+    The value is the same path as known to the Ansible CLI.
+    Both file paths and directories are supported.
+    """
+
+
+def run(args: dict[str, t.Any]) -> None:  # pragma: nocover
+    """Enable remote debugging."""
+
+    options = Options(**args)
+    temp_dir = pathlib.Path(__file__).parent.parent.parent.parent.parent.parent
+    path_mapping = [[key, str(temp_dir / value)] for key, value in options.source_mapping.items()]
+
+    os.environ['PATHS_FROM_ECLIPSE_TO_PYTHON'] = json.dumps(path_mapping)
+
+    debugging_module = importlib.import_module(options.module)
+    debugging_module.settrace(**options.settrace)
+
+    pass  # when suspend is True, execution pauses here -- it's also a convenient place to put a breakpoint

ansible/module_utils/_internal/{_ansiballz.py → _ansiballz/_loader.py}

@@ -5,17 +5,15 @@
 
 from __future__ import annotations
 
-import atexit
-import importlib.util
+import importlib
 import json
-import os
 import runpy
 import sys
 import typing as t
 
-from . import _errors
-from .. import basic
-from ..common.json import get_module_encoder, Direction
+from ansible.module_utils import basic
+from ansible.module_utils._internal import _errors, _traceback, _messages, _ansiballz
+from ansible.module_utils.common.json import get_module_encoder, Direction
 
 
 def run_module(
@@ -24,13 +22,16 @@ def run_module(
     profile: str,
     module_fqn: str,
     modlib_path: str,
+    extensions: dict[str, dict[str, object]],
     init_globals: dict[str, t.Any] | None = None,
-    coverage_config: str | None = None,
-    coverage_output: str | None = None,
 ) -> None:  # pragma: nocover
     """Used internally by the AnsiballZ wrapper to run an Ansible module."""
     try:
-        _enable_coverage(coverage_config, coverage_output)
+        for extension, args in extensions.items():
+            # importing _ansiballz instead of _extensions avoids an unnecessary import when extensions are not in use
+            extension_module = importlib.import_module(f'{_ansiballz.__name__}._extensions.{extension}')
+            extension_module.run(args)
+
         _run_module(
             json_params=json_params,
             profile=profile,
@@ -42,35 +43,6 @@ def run_module(
         _handle_exception(ex, profile)
 
 
-def _enable_coverage(coverage_config: str | None, coverage_output: str | None) -> None:  # pragma: nocover
-    """Bootstrap `coverage` for the current Ansible module invocation."""
-    if not coverage_config:
-        return
-
-    if coverage_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'{coverage_output}=python-{python_version_string}=coverage'
-
-        import coverage
-
-        cov = coverage.Coverage(config_file=coverage_config)
-
-        def atexit_coverage():
-            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.')
-
-
 def _run_module(
     *,
     json_params: bytes,
@@ -97,7 +69,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/_ansiballz/_respawn.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import inspect
+import sys
+
+from ... import basic
+from . import _respawn_wrapper
+
+
+def create_payload() -> str:
+    """Create and return an AnsiballZ payload for respawning a module."""
+    main = sys.modules['__main__']
+    code = inspect.getsource(_respawn_wrapper)
+
+    args = dict(
+        module_fqn=main._module_fqn,
+        modlib_path=main._modlib_path,
+        profile=basic._ANSIBLE_PROFILE,
+        json_params=basic._ANSIBLE_ARGS,
+    )
+
+    args_string = '\n'.join(f'{key}={value!r},' for key, value in args.items())
+
+    wrapper = f"""{code}
+
+if __name__ == "__main__":
+    _respawn_main(
+{args_string}
+)
+"""
+
+    return wrapper

ansible/module_utils/_internal/_ansiballz/_respawn_wrapper.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+
+def _respawn_main(
+    json_params: bytes,
+    profile: str,
+    module_fqn: str,
+    modlib_path: str,
+) -> None:
+    import sys
+
+    sys.path.insert(0, modlib_path)
+
+    from ansible.module_utils._internal._ansiballz import _loader
+
+    _loader.run_module(
+        json_params=json_params,
+        profile=profile,
+        module_fqn=module_fqn,
+        modlib_path=modlib_path,
+        extensions={},
+        init_globals=dict(_respawned=True),
+    )

ansible/module_utils/_internal/_datatag/__init__.py

@@ -5,6 +5,7 @@ import collections.abc as c
 import copy
 import dataclasses
 import datetime
+import enum
 import inspect
 import sys
 
@@ -37,15 +38,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 +107,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
@@ -215,7 +217,7 @@ class AnsibleTagHelper:
             return value
 
 
-class AnsibleSerializable(metaclass=abc.ABCMeta):
+class AnsibleSerializable:
     __slots__ = _NO_INSTANCE_STORAGE
 
     _known_type_map: t.ClassVar[t.Dict[str, t.Type['AnsibleSerializable']]] = {}
@@ -273,6 +275,27 @@ class AnsibleSerializable(metaclass=abc.ABCMeta):
         return f'{name}({arg_string})'
 
 
+class AnsibleSerializableEnum(AnsibleSerializable, enum.Enum):
+    """Base class for serializable enumerations."""
+
+    def _as_dict(self) -> t.Dict[str, t.Any]:
+        return dict(value=self.value)
+
+    @classmethod
+    def _from_dict(cls, d: t.Dict[str, t.Any]) -> t.Self:
+        return cls(d['value'].lower())
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__}.{self.name}>'
+
+    @staticmethod
+    def _generate_next_value_(name, start, count, last_values):
+        return name.lower()
+
+
 class AnsibleSerializableWrapper(AnsibleSerializable, t.Generic[_T], metaclass=abc.ABCMeta):
     __slots__ = ('_value',)
 
@@ -339,10 +362,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 +375,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 +392,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 +552,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 +905,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 +940,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

ansible/module_utils/_internal/_deprecator.py

@@ -1,79 +1,52 @@
 from __future__ import annotations
 
-import inspect
 import re
 import pathlib
 import sys
 import typing as t
 
-from ansible.module_utils.common.messages import PluginInfo
+from ansible.module_utils._internal import _stack, _messages, _validation, _plugin_info
 
-_ansible_module_base_path: t.Final = pathlib.Path(sys.modules['ansible'].__file__).parent
-"""Runtime-detected base path of the `ansible` Python package to distinguish between Ansible-owned and external code."""
 
-ANSIBLE_CORE_DEPRECATOR: t.Final = PluginInfo._from_collection_name('ansible.builtin')
-"""Singleton `PluginInfo` instance for ansible-core callers where the plugin can/should not be identified in messages."""
+def deprecator_from_collection_name(collection_name: str | None) -> _messages.PluginInfo | None:
+    """Returns an instance with the special `collection` type to refer to a non-plugin or ambiguous caller within a collection."""
+    # CAUTION: This function is exposed in public API as ansible.module_utils.datatag.deprecator_from_collection_name.
 
-INDETERMINATE_DEPRECATOR: t.Final = PluginInfo(resolved_name='indeterminate', type='indeterminate')
-"""Singleton `PluginInfo` instance for indeterminate deprecator."""
+    if not collection_name:
+        return None
 
-_DEPRECATOR_PLUGIN_TYPES = frozenset(
-    {
-        'action',
-        'become',
-        'cache',
-        'callback',
-        'cliconf',
-        'connection',
-        # doc_fragments - no code execution
-        # filter - basename inadequate to identify plugin
-        'httpapi',
-        'inventory',
-        'lookup',
-        'module',  # only for collections
-        'netconf',
-        'shell',
-        'strategy',
-        'terminal',
-        # test - basename inadequate to identify plugin
-        'vars',
-    }
-)
-"""Plugin types which are valid for identifying a deprecator for deprecation purposes."""
+    _validation.validate_collection_name(collection_name)
 
-_AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES = frozenset(
-    {
-        'filter',
-        'test',
-    }
-)
-"""Plugin types for which basename cannot be used to identify the plugin name."""
+    return _messages.PluginInfo(
+        resolved_name=collection_name,
+        type=None,
+    )
 
 
-def get_best_deprecator(*, deprecator: PluginInfo | None = None, collection_name: str | None = None) -> PluginInfo:
+def get_best_deprecator(*, deprecator: _messages.PluginInfo | None = None, collection_name: str | None = None) -> _messages.PluginInfo:
     """Return the best-available `PluginInfo` for the caller of this method."""
     _skip_stackwalk = True
 
     if deprecator and collection_name:
         raise ValueError('Specify only one of `deprecator` or `collection_name`.')
 
-    return deprecator or PluginInfo._from_collection_name(collection_name) or get_caller_plugin_info() or INDETERMINATE_DEPRECATOR
+    return deprecator or deprecator_from_collection_name(collection_name) or get_caller_plugin_info() or INDETERMINATE_DEPRECATOR
 
 
-def get_caller_plugin_info() -> PluginInfo | None:
+def get_caller_plugin_info() -> _messages.PluginInfo | None:
     """Try to get `PluginInfo` for the caller of this method, ignoring marked infrastructure stack frames."""
     _skip_stackwalk = True
 
-    if frame_info := next((frame_info for frame_info in inspect.stack() if '_skip_stackwalk' not in frame_info.frame.f_locals), None):
+    if frame_info := _stack.caller_frame():
         return _path_as_core_plugininfo(frame_info.filename) or _path_as_collection_plugininfo(frame_info.filename)
 
     return None  # pragma: nocover
 
 
-def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
+def _path_as_core_plugininfo(path: str) -> _messages.PluginInfo | None:
     """Return a `PluginInfo` instance if the provided `path` refers to a core plugin."""
     try:
-        relpath = str(pathlib.Path(path).relative_to(_ansible_module_base_path))
+        relpath = str(pathlib.Path(path).relative_to(_ANSIBLE_MODULE_BASE_PATH))
     except ValueError:
         return None  # not ansible-core
 
@@ -81,7 +54,7 @@ def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
 
     if match := re.match(r'plugins/(?P<plugin_type>\w+)/(?P<plugin_name>\w+)', relpath):
         plugin_name = match.group("plugin_name")
-        plugin_type = match.group("plugin_type")
+        plugin_type = _plugin_info.normalize_plugin_type(match.group("plugin_type"))
 
         if plugin_type not in _DEPRECATOR_PLUGIN_TYPES:
             # The plugin type isn't a known deprecator type, so we have to assume the caller is intermediate code.
@@ -92,36 +65,33 @@ def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
     elif match := re.match(r'modules/(?P<module_name>\w+)', relpath):
         # AnsiballZ Python package for core modules
         plugin_name = match.group("module_name")
-        plugin_type = "module"
+        plugin_type = _messages.PluginType.MODULE
     elif match := re.match(r'legacy/(?P<module_name>\w+)', relpath):
         # AnsiballZ Python package for non-core library/role modules
         namespace = 'ansible.legacy'
 
         plugin_name = match.group("module_name")
-        plugin_type = "module"
+        plugin_type = _messages.PluginType.MODULE
     else:
         return ANSIBLE_CORE_DEPRECATOR  # non-plugin core path, safe to use ansible-core for the same reason as the non-deprecator plugin type case above
 
     name = f'{namespace}.{plugin_name}'
 
-    return PluginInfo(resolved_name=name, type=plugin_type)
+    return _messages.PluginInfo(resolved_name=name, type=plugin_type)
 
 
-def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
+def _path_as_collection_plugininfo(path: str) -> _messages.PluginInfo | None:
     """Return a `PluginInfo` instance if the provided `path` refers to a collection plugin."""
     if not (match := re.search(r'/ansible_collections/(?P<ns>\w+)/(?P<coll>\w+)/plugins/(?P<plugin_type>\w+)/(?P<plugin_name>\w+)', path)):
         return None
 
-    plugin_type = match.group('plugin_type')
+    plugin_type = _plugin_info.normalize_plugin_type(match.group('plugin_type'))
 
     if plugin_type in _AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES:
         # We're able to detect the namespace, collection and plugin type -- but we have no way to identify the plugin name currently.
         # To keep things simple we'll fall back to just identifying the namespace and collection.
         # In the future we could improve the detection and/or make it easier for a caller to identify the plugin name.
-        return PluginInfo._from_collection_name('.'.join((match.group('ns'), match.group('coll'))))
-
-    if plugin_type == 'modules':
-        plugin_type = 'module'
+        return deprecator_from_collection_name('.'.join((match.group('ns'), match.group('coll'))))
 
     if plugin_type not in _DEPRECATOR_PLUGIN_TYPES:
         # The plugin type isn't a known deprecator type, so we have to assume the caller is intermediate code.
@@ -131,4 +101,46 @@ def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
 
     name = '.'.join((match.group('ns'), match.group('coll'), match.group('plugin_name')))
 
-    return PluginInfo(resolved_name=name, type=plugin_type)
+    return _messages.PluginInfo(resolved_name=name, type=plugin_type)
+
+
+_ANSIBLE_MODULE_BASE_PATH: t.Final = pathlib.Path(sys.modules['ansible'].__file__).parent
+"""Runtime-detected base path of the `ansible` Python package to distinguish between Ansible-owned and external code."""
+
+ANSIBLE_CORE_DEPRECATOR: t.Final = deprecator_from_collection_name('ansible.builtin')
+"""Singleton `PluginInfo` instance for ansible-core callers where the plugin can/should not be identified in messages."""
+
+INDETERMINATE_DEPRECATOR: t.Final = _messages.PluginInfo(resolved_name=None, type=None)
+"""Singleton `PluginInfo` instance for indeterminate deprecator."""
+
+_DEPRECATOR_PLUGIN_TYPES: t.Final = frozenset(
+    {
+        _messages.PluginType.ACTION,
+        _messages.PluginType.BECOME,
+        _messages.PluginType.CACHE,
+        _messages.PluginType.CALLBACK,
+        _messages.PluginType.CLICONF,
+        _messages.PluginType.CONNECTION,
+        # DOC_FRAGMENTS - no code execution
+        # FILTER - basename inadequate to identify plugin
+        _messages.PluginType.HTTPAPI,
+        _messages.PluginType.INVENTORY,
+        _messages.PluginType.LOOKUP,
+        _messages.PluginType.MODULE,  # only for collections
+        _messages.PluginType.NETCONF,
+        _messages.PluginType.SHELL,
+        _messages.PluginType.STRATEGY,
+        _messages.PluginType.TERMINAL,
+        # TEST - basename inadequate to identify plugin
+        _messages.PluginType.VARS,
+    }
+)
+"""Plugin types which are valid for identifying a deprecator for deprecation purposes."""
+
+_AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES: t.Final = frozenset(
+    {
+        _messages.PluginType.FILTER,
+        _messages.PluginType.TEST,
+    }
+)
+"""Plugin types for which basename cannot be used to identify the plugin name."""

ansible/module_utils/_internal/_errors.py

@@ -3,28 +3,99 @@
 
 """Internal error handling logic for targets. Not for use on the controller."""
 
-from __future__ import annotations
+from __future__ import annotations as _annotations
 
-from . import _traceback
-from ..common.messages import Detail, ErrorSummary
+import traceback as _sys_traceback
+import typing as _t
 
+from . import _messages
 
-def create_error_summary(exception: BaseException) -> ErrorSummary:
-    """Return an `ErrorDetail` created from the given exception."""
-    return ErrorSummary(
-        details=_create_error_details(exception),
-        formatted_traceback=_traceback.maybe_extract_traceback(exception, _traceback.TracebackEvent.ERROR),
-    )
+MSG_REASON_DIRECT_CAUSE: _t.Final[str] = '<<< caused by >>>'
+MSG_REASON_HANDLING_CAUSE: _t.Final[str] = '<<< while handling >>>'
 
+TRACEBACK_REASON_EXCEPTION_DIRECT_WARNING: _t.Final[str] = 'The above exception was the direct cause of the following warning:'
 
-def _create_error_details(exception: BaseException) -> tuple[Detail, ...]:
-    """Return an `ErrorMessage` tuple created from the given exception."""
-    target_exception: BaseException | None = exception
-    error_details: list[Detail] = []
 
-    while target_exception:
-        error_details.append(Detail(msg=str(target_exception).strip()))
+class EventFactory:
+    """Factory for creating `Event` instances from `BaseException` instances on targets."""
 
-        target_exception = target_exception.__cause__
+    _MAX_DEPTH = 10
+    """Maximum exception chain depth. Exceptions beyond this depth will be omitted."""
 
-    return tuple(error_details)
+    @classmethod
+    def from_exception(cls, exception: BaseException, include_traceback: bool) -> _messages.Event:
+        return cls(include_traceback)._convert_exception(exception)
+
+    def __init__(self, include_traceback: bool) -> None:
+        self._include_traceback = include_traceback
+        self._depth = 0
+
+    def _convert_exception(self, exception: BaseException) -> _messages.Event:
+        if self._depth > self._MAX_DEPTH:
+            return _messages.Event(
+                msg="Maximum depth exceeded, omitting further events.",
+            )
+
+        self._depth += 1
+
+        try:
+            return _messages.Event(
+                msg=self._get_msg(exception),
+                formatted_traceback=self._get_formatted_traceback(exception),
+                formatted_source_context=self._get_formatted_source_context(exception),
+                help_text=self._get_help_text(exception),
+                chain=self._get_chain(exception),
+                events=self._get_events(exception),
+            )
+        finally:
+            self._depth -= 1
+
+    def _get_msg(self, exception: BaseException) -> str | None:
+        return str(exception).strip()
+
+    def _get_formatted_traceback(self, exception: BaseException) -> str | None:
+        if self._include_traceback:
+            return ''.join(_sys_traceback.format_exception(type(exception), exception, exception.__traceback__, chain=False))
+
+        return None
+
+    def _get_formatted_source_context(self, exception: BaseException) -> str | None:
+        return None
+
+    def _get_help_text(self, exception: BaseException) -> str | None:
+        return None
+
+    def _get_chain(self, exception: BaseException) -> _messages.EventChain | None:
+        if cause := self._get_cause(exception):
+            return _messages.EventChain(
+                msg_reason=MSG_REASON_DIRECT_CAUSE,
+                traceback_reason='The above exception was the direct cause of the following exception:',
+                event=self._convert_exception(cause),
+                follow=self._follow_cause(exception),
+            )
+
+        if context := self._get_context(exception):
+            return _messages.EventChain(
+                msg_reason=MSG_REASON_HANDLING_CAUSE,
+                traceback_reason='During handling of the above exception, another exception occurred:',
+                event=self._convert_exception(context),
+                follow=False,
+            )
+
+        return None
+
+    def _follow_cause(self, exception: BaseException) -> bool:
+        return True
+
+    def _get_cause(self, exception: BaseException) -> BaseException | None:
+        return exception.__cause__
+
+    def _get_context(self, exception: BaseException) -> BaseException | None:
+        if exception.__suppress_context__:
+            return None
+
+        return exception.__context__
+
+    def _get_events(self, exception: BaseException) -> tuple[_messages.Event, ...] | None:
+        # deprecated: description='move BaseExceptionGroup support here from ControllerEventFactory' python_version='3.10'
+        return None