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

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,9 @@ For controller-to-module, type behavior is profile dependent.
 _common_module_response_types: frozenset[type[AnsibleSerializable]] = frozenset(
     {
         _messages.PluginInfo,
-        _messages.Detail,
+        _messages.PluginType,
+        _messages.Event,
+        _messages.EventChain,
         _messages.ErrorSummary,
         _messages.WarningSummary,
         _messages.DeprecationSummary,
@@ -203,11 +205,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 +391,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,12 @@ A future release will remove the provisional status.
 
 from __future__ import annotations as _annotations
 
-import sys as _sys
 import dataclasses as _dataclasses
+import enum as _enum
+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.
@@ -23,56 +22,79 @@ else:
     _dataclass_kwargs = dict(frozen=True)
 
 
+class PluginType(_datatag.AnsibleSerializableEnum):
+    """Enum of Ansible plugin types."""
+
+    ACTION = _enum.auto()
+    BECOME = _enum.auto()
+    CACHE = _enum.auto()
+    CALLBACK = _enum.auto()
+    CLICONF = _enum.auto()
+    CONNECTION = _enum.auto()
+    DOC_FRAGMENTS = _enum.auto()
+    FILTER = _enum.auto()
+    HTTPAPI = _enum.auto()
+    INVENTORY = _enum.auto()
+    LOOKUP = _enum.auto()
+    MODULE = _enum.auto()
+    NETCONF = _enum.auto()
+    SHELL = _enum.auto()
+    STRATEGY = _enum.auto()
+    TERMINAL = _enum.auto()
+    TEST = _enum.auto()
+    VARS = _enum.auto()
+
+
 @_dataclasses.dataclass(**_dataclass_kwargs)
 class PluginInfo(_datatag.AnsibleSerializableDataclass):
     """Information about a loaded plugin."""
 
-    resolved_name: str
+    resolved_name: _t.Optional[str]
     """The resolved canonical plugin name; always fully-qualified for collection plugins."""
-    type: str
+
+    type: _t.Optional[PluginType]
     """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_auto_enabled = False
 
-        _validation.validate_collection_name(collection_name)
+    def __post_init__(self): ...  # required for deferred dataclass validation
 
-        return cls(
-            resolved_name=collection_name,
-            type=cls._COLLECTION_ONLY_TYPE,
-        )
+    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 +128,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):
@@ -21,5 +21,18 @@ def get_plugin_info(value: HasPluginInfo) -> _messages.PluginInfo:
     """Utility method that returns a `PluginInfo` from an object implementing the `HasPluginInfo` protocol."""
     return _messages.PluginInfo(
         resolved_name=value.ansible_name,
-        type=value.plugin_type,
+        type=normalize_plugin_type(value.plugin_type),
     )
+
+
+def normalize_plugin_type(value: str) -> _messages.PluginType | None:
+    """Normalize value and return it as a PluginType, or None if the value does match any known plugin type."""
+    value = value.lower()
+
+    if value == 'modules':
+        value = 'module'
+
+    try:
+        return _messages.PluginType(value)
+    except ValueError:
+        return None

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}'

ansible/module_utils/_internal/_traceback.py

@@ -6,9 +6,10 @@
 from __future__ import annotations
 
 import enum
-import inspect
 import traceback
 
+from . import _stack
+
 
 class TracebackEvent(enum.Enum):
     """The events for which tracebacks can be enabled."""
@@ -16,6 +17,7 @@ class TracebackEvent(enum.Enum):
     ERROR = enum.auto()
     WARNING = enum.auto()
     DEPRECATED = enum.auto()
+    DEPRECATED_VALUE = enum.auto()  # implies DEPRECATED
 
 
 def traceback_for() -> list[str]:
@@ -28,24 +30,25 @@ def is_traceback_enabled(event: TracebackEvent) -> bool:
     return _is_traceback_enabled(event)
 
 
-def maybe_capture_traceback(event: TracebackEvent) -> str | None:
+def maybe_capture_traceback(msg: str, event: TracebackEvent) -> str | None:
     """
     Optionally capture a traceback for the current call stack, formatted as a string, if the specified traceback event is enabled.
-    The current and previous frames are omitted to mask the expected call pattern from error/warning handlers.
+    Frames marked with the `_skip_stackwalk` local are omitted.
     """
+    _skip_stackwalk = True
+
     if not is_traceback_enabled(event):
         return None
 
     tb_lines = []
 
-    if current_frame := inspect.currentframe():
+    if frame_info := _stack.caller_frame():
         # DTFIX-FUTURE: rewrite target-side tracebacks to point at controller-side paths?
-        frames = inspect.getouterframes(current_frame)
-        ignore_frame_count = 2  # ignore this function and its caller
         tb_lines.append('Traceback (most recent call last):\n')
-        tb_lines.extend(traceback.format_stack(frames[ignore_frame_count].frame))
+        tb_lines.extend(traceback.format_stack(frame_info.frame))
+        tb_lines.append(f'Message: {msg}\n')
     else:
-        tb_lines.append('Traceback unavailable.\n')
+        tb_lines.append('(frame not found)\n')  # pragma: nocover
 
     return ''.join(tb_lines)
 

ansible/module_utils/ansible_release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.19.0b4'
+__version__ = '2.19.0b6'
 __author__ = 'Ansible, Inc.'
 __codename__ = "What Is and What Should Never Be"