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

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
 
-_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=_COLLECTION_ONLY_TYPE,
+    )
 
 
-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
 
@@ -104,10 +77,10 @@ def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
 
     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
@@ -118,7 +91,7 @@ def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
         # 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'))))
+        return deprecator_from_collection_name('.'.join((match.group('ns'), match.group('coll'))))
 
     if plugin_type == 'modules':
         plugin_type = 'module'
@@ -131,4 +104,49 @@ 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)
+
+
+_COLLECTION_ONLY_TYPE: t.Final = 'collection'
+"""Ersatz placeholder plugin type for use by a `PluginInfo` instance that references only a collection."""
+
+_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='indeterminate', type='indeterminate')
+"""Singleton `PluginInfo` instance for indeterminate deprecator."""
+
+_DEPRECATOR_PLUGIN_TYPES: t.Final = 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."""
+
+_AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES: t.Final = frozenset(
+    {
+        'filter',
+        '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

ansible/module_utils/_internal/_event_utils.py

@@ -0,0 +1,61 @@
+from __future__ import annotations as _annotations
+
+import typing as _t
+
+from ansible.module_utils._internal import _text_utils, _messages
+
+
+def deduplicate_message_parts(message_parts: list[str]) -> str:
+    """Format the given list of messages into a brief message, while deduplicating repeated elements."""
+    message_parts = list(reversed(message_parts))
+
+    message = message_parts.pop(0)
+
+    for message_part in message_parts:
+        # avoid duplicate messages where the cause was already concatenated to the exception message
+        if message_part.endswith(message):
+            message = message_part
+        else:
+            message = _text_utils.concat_message(message_part, message)
+
+    return message
+
+
+def format_event_brief_message(event: _messages.Event) -> str:
+    """
+    Format an event into a brief message.
+    Help text, contextual information and sub-events will be omitted.
+    """
+    message_parts: list[str] = []
+
+    while True:
+        message_parts.append(event.msg)
+
+        if not event.chain or not event.chain.follow:
+            break
+
+        event = event.chain.event
+
+    return deduplicate_message_parts(message_parts)
+
+
+def deprecation_as_dict(deprecation: _messages.DeprecationSummary) -> _t.Dict[str, _t.Any]:
+    """Returns a dictionary representation of the deprecation object in the format exposed to playbooks."""
+    from ansible.module_utils._internal._deprecator import INDETERMINATE_DEPRECATOR  # circular import from messages
+
+    if deprecation.deprecator and deprecation.deprecator != INDETERMINATE_DEPRECATOR:
+        collection_name = '.'.join(deprecation.deprecator.resolved_name.split('.')[:2])
+    else:
+        collection_name = None
+
+    result = dict(
+        msg=format_event_brief_message(deprecation.event),
+        collection_name=collection_name,
+    )
+
+    if deprecation.date:
+        result.update(date=deprecation.date)
+    else:
+        result.update(version=deprecation.version)
+
+    return result

ansible/module_utils/_internal/_json/_profiles/__init__.py

@@ -6,7 +6,7 @@ import json
 import typing as t
 
 from ansible.module_utils import _internal
-from ansible.module_utils.common import messages as _messages
+from ansible.module_utils._internal import _messages
 from ansible.module_utils._internal._datatag import (
     AnsibleSerializable,
     AnsibleSerializableWrapper,
@@ -87,7 +87,8 @@ For controller-to-module, type behavior is profile dependent.
 _common_module_response_types: frozenset[type[AnsibleSerializable]] = frozenset(
     {
         _messages.PluginInfo,
-        _messages.Detail,
+        _messages.Event,
+        _messages.EventChain,
         _messages.ErrorSummary,
         _messages.WarningSummary,
         _messages.DeprecationSummary,
@@ -203,11 +204,27 @@ class _JSONSerializationProfile(t.Generic[_T_encoder, _T_decoder]):
 
     @classmethod
     def handle_key(cls, k: t.Any) -> t.Any:
+        """Validation/conversion hook before a dict key is serialized. The default implementation only accepts str-typed keys."""
+        # NOTE: Since JSON requires string keys, there is no support for preserving tags on dictionary keys during serialization.
+
         if not isinstance(k, str):  # DTFIX-FUTURE: optimize this to use all known str-derived types in type map / allowed types
             raise TypeError(f'Key of type {type(k).__name__!r} is not JSON serializable by the {cls.profile_name!r} profile.')
 
         return k
 
+    @classmethod
+    def _handle_key_str_fallback(cls, k: t.Any) -> t.Any:
+        """Legacy implementations should use this key handler for backward compatibility with stdlib JSON key conversion quirks."""
+        # DTFIX-FUTURE: optimized exact-type table lookup first
+
+        if isinstance(k, str):
+            return k
+
+        if k is None or isinstance(k, (int, float)):
+            return json.dumps(k)
+
+        raise TypeError(f'Key of type {type(k).__name__!r} is not JSON serializable by the {cls.profile_name!r} profile.')
+
     @classmethod
     def default(cls, o: t.Any) -> t.Any:
         # Preserve the built-in JSON encoder support for subclasses of scalar types.
@@ -373,8 +390,8 @@ Future code changes should further restrict bytes to string conversions to elimi
 Additional warnings at other boundaries may be needed to give users an opportunity to resolve the issues before they become errors.
 """
 # DTFIX-FUTURE: add strict UTF8 string encoding checking to serialization profiles (to match the checks performed during deserialization)
-# DTFIX-RELEASE: the surrogateescape note above isn't quite right, for encoding use surrogatepass, which does work
-# DTFIX-RELEASE: this config setting should probably be deprecated
+# DTFIX3: the surrogateescape note above isn't quite right, for encoding use surrogatepass, which does work
+# DTFIX-FUTURE: this config setting should probably be deprecated
 
 
 def _create_encoding_check_error() -> Exception:

ansible/module_utils/_internal/_json/_profiles/_module_legacy_c2m.py

@@ -22,6 +22,8 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
             }
         )
 
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
 
 class Encoder(_profiles.AnsibleProfileJSONEncoder):
     _profile = _Profile

ansible/module_utils/_internal/_json/_profiles/_module_legacy_m2c.py

@@ -26,6 +26,8 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
             _datetime.datetime: cls.serialize_as_isoformat,  # legacy _json_encode_fallback behavior *and* legacy parameters.py does this before serialization
         }
 
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
 
 class Encoder(_profiles.AnsibleProfileJSONEncoder):
     _profile = _Profile

ansible/module_utils/_internal/_json/_profiles/_tagless.py

@@ -17,7 +17,7 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
     @classmethod
     def post_init(cls) -> None:
         cls.serialize_map = {
-            # DTFIX-RELEASE: support serialization of every type that is supported in the Ansible variable type system
+            # DTFIX5: support serialization of every type that is supported in the Ansible variable type system
             set: cls.serialize_as_list,
             tuple: cls.serialize_as_list,
             _datetime.date: cls.serialize_as_isoformat,
@@ -41,6 +41,8 @@ class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
             '__ansible_vault': _functools.partial(cls.unsupported_target_type_error, '__ansible_vault'),
         }
 
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
 
 class Encoder(_profiles.AnsibleProfileJSONEncoder):
     _profile = _Profile

ansible/module_utils/{common/messages.py → _internal/_messages.py}

@@ -7,13 +7,11 @@ A future release will remove the provisional status.
 
 from __future__ import annotations as _annotations
 
-import sys as _sys
 import dataclasses as _dataclasses
+import sys as _sys
+import typing as _t
 
-# deprecated: description='typing.Self exists in Python 3.11+' python_version='3.10'
-from ..compat import typing as _t
-
-from ansible.module_utils._internal import _datatag, _validation
+from ansible.module_utils._internal import _datatag, _dataclass_validation
 
 if _sys.version_info >= (3, 10):
     # Using slots for reduced memory usage and improved performance.
@@ -29,50 +27,50 @@ class PluginInfo(_datatag.AnsibleSerializableDataclass):
 
     resolved_name: str
     """The resolved canonical plugin name; always fully-qualified for collection plugins."""
+
     type: str
     """The plugin type."""
 
-    _COLLECTION_ONLY_TYPE: _t.ClassVar[str] = 'collection'
-    """This is not a real plugin type. It's a placeholder for use by a `PluginInfo` instance which references a collection without a plugin."""
 
-    @classmethod
-    def _from_collection_name(cls, collection_name: str | None) -> _t.Self | None:
-        """Returns an instance with the special `collection` type to refer to a non-plugin or ambiguous caller within a collection."""
-        if not collection_name:
-            return None
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class EventChain(_datatag.AnsibleSerializableDataclass):
+    """A chain used to link one event to another."""
 
-        _validation.validate_collection_name(collection_name)
+    _validation_auto_enabled = False
 
-        return cls(
-            resolved_name=collection_name,
-            type=cls._COLLECTION_ONLY_TYPE,
-        )
+    def __post_init__(self): ...  # required for deferred dataclass validation
+
+    msg_reason: str
+    traceback_reason: str
+    event: Event
+    follow: bool = True
 
 
 @_dataclasses.dataclass(**_dataclass_kwargs)
-class Detail(_datatag.AnsibleSerializableDataclass):
-    """Message detail with optional source context and help text."""
+class Event(_datatag.AnsibleSerializableDataclass):
+    """Base class for an error/warning/deprecation event with optional chain (from an exception __cause__ chain) and an optional traceback."""
+
+    _validation_auto_enabled = False
+
+    def __post_init__(self): ...  # required for deferred dataclass validation
 
     msg: str
     formatted_source_context: _t.Optional[str] = None
+    formatted_traceback: _t.Optional[str] = None
     help_text: _t.Optional[str] = None
+    chain: _t.Optional[EventChain] = None
+    events: _t.Optional[_t.Tuple[Event, ...]] = None
+
+
+_dataclass_validation.inject_post_init_validation(EventChain, EventChain._validation_allow_subclasses)
+_dataclass_validation.inject_post_init_validation(Event, Event._validation_allow_subclasses)
 
 
 @_dataclasses.dataclass(**_dataclass_kwargs)
 class SummaryBase(_datatag.AnsibleSerializableDataclass):
     """Base class for an error/warning/deprecation summary with details (possibly derived from an exception __cause__ chain) and an optional traceback."""
 
-    details: _t.Tuple[Detail, ...]
-    formatted_traceback: _t.Optional[str] = None
-
-    def _format(self) -> str:
-        """Returns a string representation of the details."""
-        # DTFIX-RELEASE: eliminate this function and use a common message squashing utility such as get_chained_message on instances of this type
-        return ': '.join(detail.msg for detail in self.details)
-
-    def _post_validate(self) -> None:
-        if not self.details:
-            raise ValueError(f'{type(self).__name__}.details cannot be empty')
+    event: Event
 
 
 @_dataclasses.dataclass(**_dataclass_kwargs)
@@ -106,20 +104,3 @@ class DeprecationSummary(WarningSummary):
     Ignored if `deprecator` is not provided.
     Ignored if `date` is provided.
     """
-
-    def _as_simple_dict(self) -> _t.Dict[str, _t.Any]:
-        """Returns a dictionary representation of the deprecation object in the format exposed to playbooks."""
-        from ansible.module_utils._internal._deprecator import INDETERMINATE_DEPRECATOR  # circular import from messages
-
-        if self.deprecator and self.deprecator != INDETERMINATE_DEPRECATOR:
-            collection_name = '.'.join(self.deprecator.resolved_name.split('.')[:2])
-        else:
-            collection_name = None
-
-        result = self._as_dict()
-        result.update(
-            msg=self._format(),
-            collection_name=collection_name,
-        )
-
-        return result

ansible/module_utils/_internal/_patches/_dataclass_annotation_patch.py

@@ -1,7 +1,5 @@
 """Patches for builtin `dataclasses` module."""
 
-# deprecated: description='verify ClassVar support in dataclasses has been fixed in Python before removing this patching code', python_version='3.13'
-
 from __future__ import annotations
 
 import dataclasses
@@ -26,7 +24,7 @@ class DataclassesIsTypePatch(CallablePatch):
         @dataclasses.dataclass
         class CheckClassVar:
             # this is the broken case requiring patching: ClassVar dot-referenced from a module that is not `typing` is treated as an instance field
-            # DTFIX-RELEASE: add link to CPython bug report to-be-filed (or update associated deprecation comments if we don't)
+            # DTFIX-FUTURE: file/link CPython bug report, deprecate this patch if/when it's fixed in CPython
             a_classvar: _ts.ClassVar[int]  # type: ignore[name-defined]
             a_field: int
 

ansible/module_utils/_internal/_plugin_info.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import typing as t
 
-from ..common import messages as _messages
+from . import _messages
 
 
 class HasPluginInfo(t.Protocol):

ansible/module_utils/_internal/_stack.py

@@ -0,0 +1,22 @@
+from __future__ import annotations as _annotations
+
+import inspect as _inspect
+import typing as _t
+
+
+def caller_frame() -> _inspect.FrameInfo | None:
+    """Return the caller stack frame, skipping any marked with the `_skip_stackwalk` local."""
+    _skip_stackwalk = True
+
+    return next(iter_stack(), None)
+
+
+def iter_stack() -> _t.Generator[_inspect.FrameInfo]:
+    """Iterate over stack frames, skipping any marked with the `_skip_stackwalk` local."""
+    _skip_stackwalk = True
+
+    for frame_info in _inspect.stack():
+        if '_skip_stackwalk' in frame_info.frame.f_locals:
+            continue
+
+        yield frame_info

ansible/module_utils/_internal/_text_utils.py

@@ -0,0 +1,6 @@
+from __future__ import annotations as _annotations
+
+
+def concat_message(left: str, right: str) -> str:
+    """Normalize `left` by removing trailing punctuation and spaces before appending new punctuation and `right`."""
+    return f'{left.rstrip(". ")}: {right}'