ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__py3-none-any.whl

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

@@ -0,0 +1,52 @@
+"""
+Lossy best-effort serialization for Ansible variables.
+Default profile for the `to_json` filter.
+Deserialization behavior is identical to JSONDecoder, except known Ansible custom serialization markers will raise an error.
+"""
+
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+import functools as _functools
+
+from ... import _datatag
+from .. import _profiles
+
+
+class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
+    @classmethod
+    def post_init(cls) -> None:
+        cls.serialize_map = {
+            # 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,
+            _datetime.time: cls.serialize_as_isoformat,
+            _datetime.datetime: cls.serialize_as_isoformat,
+            # bytes intentionally omitted as they are not a supported variable type, they were not originally supported by the old AnsibleJSONEncoder
+            _datatag._AnsibleTaggedDate: cls.discard_tags,
+            _datatag._AnsibleTaggedTime: cls.discard_tags,
+            _datatag._AnsibleTaggedDateTime: cls.discard_tags,
+            _datatag._AnsibleTaggedStr: cls.discard_tags,
+            _datatag._AnsibleTaggedInt: cls.discard_tags,
+            _datatag._AnsibleTaggedFloat: cls.discard_tags,
+            _datatag._AnsibleTaggedSet: cls.discard_tags,
+            _datatag._AnsibleTaggedList: cls.discard_tags,
+            _datatag._AnsibleTaggedTuple: cls.discard_tags,
+            _datatag._AnsibleTaggedDict: cls.discard_tags,
+        }
+
+        cls.deserialize_map = {
+            '__ansible_unsafe': _functools.partial(cls.unsupported_target_type_error, '__ansible_unsafe'),
+            '__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
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

ansible/module_utils/_internal/_messages.py

@@ -0,0 +1,130 @@
+"""
+Message contract definitions for various target-side types.
+
+These types and the wire format they implement are currently considered provisional and subject to change without notice.
+A future release will remove the provisional status.
+"""
+
+from __future__ import annotations as _annotations
+
+import dataclasses as _dataclasses
+import enum as _enum
+import sys as _sys
+import typing as _t
+
+from ansible.module_utils._internal import _datatag, _dataclass_validation
+
+if _sys.version_info >= (3, 10):
+    # Using slots for reduced memory usage and improved performance.
+    _dataclass_kwargs = dict(frozen=True, kw_only=True, slots=True)
+else:
+    # deprecated: description='always use dataclass slots and keyword-only args' python_version='3.9'
+    _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: _t.Optional[str]
+    """The resolved canonical plugin name; always fully-qualified for collection plugins."""
+
+    type: _t.Optional[PluginType]
+    """The plugin type."""
+
+
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class EventChain(_datatag.AnsibleSerializableDataclass):
+    """A chain used to link one event to another."""
+
+    _validation_auto_enabled = False
+
+    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 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."""
+
+    event: Event
+
+
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class ErrorSummary(SummaryBase):
+    """Error summary with details (possibly derived from an exception __cause__ chain) and an optional traceback."""
+
+
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class WarningSummary(SummaryBase):
+    """Warning summary with details (possibly derived from an exception __cause__ chain) and an optional traceback."""
+
+
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class DeprecationSummary(WarningSummary):
+    """Deprecation summary with details (possibly derived from an exception __cause__ chain) and an optional traceback."""
+
+    deprecator: _t.Optional[PluginInfo] = None
+    """
+    The identifier for the content which is being deprecated.
+    """
+
+    date: _t.Optional[str] = None
+    """
+    The date after which a new release of `deprecator` will remove the feature described by `msg`.
+    Ignored if `deprecator` is not provided.
+    """
+
+    version: _t.Optional[str] = None
+    """
+    The version of `deprecator` which will remove the feature described by `msg`.
+    Ignored if `deprecator` is not provided.
+    Ignored if `date` is provided.
+    """

ansible/module_utils/_internal/_patches/__init__.py

@@ -0,0 +1,66 @@
+"""Infrastructure for patching callables with alternative implementations as needed based on patch-specific test criteria."""
+
+from __future__ import annotations
+
+import abc
+import typing as t
+
+
+@t.runtime_checkable
+class PatchedTarget(t.Protocol):
+    """Runtime-checkable protocol that allows identification of a patched function via `isinstance`."""
+
+    unpatched_implementation: t.Callable
+
+
+class CallablePatch(abc.ABC):
+    """Base class for patches that provides abstractions for validation of broken behavior, installation of patches, and validation of fixed behavior."""
+
+    target_container: t.ClassVar
+    """The module object containing the function to be patched."""
+
+    target_attribute: t.ClassVar[str]
+    """The attribute name on the target module to patch."""
+
+    unpatched_implementation: t.ClassVar[t.Callable]
+    """The unpatched implementation. Available only after the patch has been applied."""
+
+    @classmethod
+    @abc.abstractmethod
+    def is_patch_needed(cls) -> bool:
+        """Returns True if the patch is currently needed. Returns False if the original target does not need the patch or the patch has already been applied."""
+
+    @abc.abstractmethod
+    def __call__(self, *args, **kwargs) -> t.Any:
+        """Invoke the patched or original implementation, depending on whether the patch has been applied or not."""
+
+    @classmethod
+    def is_patched(cls) -> bool:
+        """Returns True if the patch has been applied, otherwise returns False."""
+        return isinstance(cls.get_current_implementation(), PatchedTarget)  # using a protocol lets us be more resilient to module unload weirdness
+
+    @classmethod
+    def get_current_implementation(cls) -> t.Any:
+        """Get the current (possibly patched) implementation from the patch target container."""
+        return getattr(cls.target_container, cls.target_attribute)
+
+    @classmethod
+    def patch(cls) -> None:
+        """Idempotently apply this patch (if needed)."""
+        if cls.is_patched():
+            return
+
+        cls.unpatched_implementation = cls.get_current_implementation()
+
+        if not cls.is_patch_needed():
+            return
+
+        # __call__ requires an instance (otherwise it'll be __new__)
+        setattr(cls.target_container, cls.target_attribute, cls())
+
+        if not cls.is_patch_needed():
+            return
+
+        setattr(cls.target_container, cls.target_attribute, cls.unpatched_implementation)
+
+        raise RuntimeError(f"Validation of '{cls.target_container.__name__}.{cls.target_attribute}' failed after patching.")

ansible/module_utils/_internal/_patches/_dataclass_annotation_patch.py

@@ -0,0 +1,53 @@
+"""Patches for builtin `dataclasses` module."""
+
+from __future__ import annotations
+
+import dataclasses
+import sys
+import typing as t
+
+from . import CallablePatch
+
+# trigger the bug by exposing typing.ClassVar via a module reference that is not `typing`
+_ts = sys.modules[__name__]
+ClassVar = t.ClassVar
+
+
+class DataclassesIsTypePatch(CallablePatch):
+    """Patch broken ClassVar support in dataclasses when ClassVar is accessed via a module other than `typing`."""
+
+    target_container: t.ClassVar = dataclasses
+    target_attribute = '_is_type'
+
+    @classmethod
+    def is_patch_needed(cls) -> bool:
+        @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-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
+
+        return len(dataclasses.fields(CheckClassVar)) != 1
+
+    def __call__(self, annotation, cls, a_module, a_type, is_type_predicate) -> bool:
+        """
+        This is a patched copy of `_is_type` from dataclasses.py in Python 3.13.
+        It eliminates the redundant source module reference equality check for the ClassVar type that triggers the bug.
+        """
+        match = dataclasses._MODULE_IDENTIFIER_RE.match(annotation)  # type: ignore[attr-defined]
+        if match:
+            ns = None
+            module_name = match.group(1)
+            if not module_name:
+                # No module name, assume the class's module did
+                # "from dataclasses import InitVar".
+                ns = sys.modules.get(cls.__module__).__dict__
+            else:
+                # Look up module_name in the class's module.
+                module = sys.modules.get(cls.__module__)
+                if module and module.__dict__.get(module_name):  # this is the patched line; removed `is a_module`
+                    ns = sys.modules.get(a_type.__module__).__dict__
+            if ns and is_type_predicate(ns.get(match.group(2)), a_module):
+                return True
+        return False

ansible/module_utils/_internal/_patches/_socket_patch.py

@@ -0,0 +1,34 @@
+"""Patches for builtin socket module."""
+
+from __future__ import annotations
+
+import contextlib
+import socket
+import typing as t
+
+from . import CallablePatch
+
+
+class _CustomInt(int):
+    """Wrapper around `int` to test if subclasses are accepted."""
+
+
+class GetAddrInfoPatch(CallablePatch):
+    """Patch `socket.getaddrinfo` so that its `port` arg works with `int` subclasses."""
+
+    target_container: t.ClassVar = socket
+    target_attribute = 'getaddrinfo'
+
+    @classmethod
+    def is_patch_needed(cls) -> bool:
+        with contextlib.suppress(OSError):
+            socket.getaddrinfo('127.0.0.1', _CustomInt(22))
+            return False
+
+        return True
+
+    def __call__(self, host, port, *args, **kwargs) -> t.Any:
+        if type(port) is not int and isinstance(port, int):  # pylint: disable=unidiomatic-typecheck
+            port = int(port)
+
+        return type(self).unpatched_implementation(host, port, *args, **kwargs)

ansible/module_utils/_internal/_patches/_sys_intern_patch.py

@@ -0,0 +1,34 @@
+"""Patches for the builtin `sys` module."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import typing as t
+
+from . import CallablePatch
+
+
+class _CustomStr(str):
+    """Wrapper around `str` to test if subclasses are accepted."""
+
+
+class SysInternPatch(CallablePatch):
+    """Patch `sys.intern` so that subclasses of `str` are accepted."""
+
+    target_container: t.ClassVar = sys
+    target_attribute = 'intern'
+
+    @classmethod
+    def is_patch_needed(cls) -> bool:
+        with contextlib.suppress(TypeError):
+            sys.intern(_CustomStr("x"))
+            return False
+
+        return True
+
+    def __call__(self, value: str):
+        if type(value) is not str and isinstance(value, str):  # pylint: disable=unidiomatic-typecheck
+            value = str(value)
+
+        return type(self).unpatched_implementation(value)

ansible/module_utils/_internal/_plugin_info.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import typing as t
+
+from . import _messages
+
+
+class HasPluginInfo(t.Protocol):
+    """Protocol to type-annotate and expose PluginLoader-set values."""
+
+    @property
+    def ansible_name(self) -> str | None:
+        """Fully resolved plugin name."""
+
+    @property
+    def plugin_type(self) -> str:
+        """Plugin type name."""
+
+
+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=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

@@ -0,0 +1,92 @@
+# Copyright (c) 2024 Ansible Project
+# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
+
+"""Internal utility code for supporting traceback reporting."""
+
+from __future__ import annotations
+
+import enum
+import traceback
+
+from . import _stack
+
+
+class TracebackEvent(enum.Enum):
+    """The events for which tracebacks can be enabled."""
+
+    ERROR = enum.auto()
+    WARNING = enum.auto()
+    DEPRECATED = enum.auto()
+    DEPRECATED_VALUE = enum.auto()  # implies DEPRECATED
+
+
+def traceback_for() -> list[str]:
+    """Return a list of traceback event names (not enums) which are enabled."""
+    return [value.name.lower() for value in TracebackEvent if is_traceback_enabled(value)]
+
+
+def is_traceback_enabled(event: TracebackEvent) -> bool:
+    """Return True if tracebacks are enabled for the specified event, otherwise return False."""
+    return _is_traceback_enabled(event)
+
+
+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.
+    Frames marked with the `_skip_stackwalk` local are omitted.
+    """
+    _skip_stackwalk = True
+
+    if not is_traceback_enabled(event):
+        return None
+
+    tb_lines = []
+
+    if frame_info := _stack.caller_frame():
+        # DTFIX-FUTURE: rewrite target-side tracebacks to point at controller-side paths?
+        tb_lines.append('Traceback (most recent call last):\n')
+        tb_lines.extend(traceback.format_stack(frame_info.frame))
+        tb_lines.append(f'Message: {msg}\n')
+    else:
+        tb_lines.append('(frame not found)\n')  # pragma: nocover
+
+    return ''.join(tb_lines)
+
+
+def maybe_extract_traceback(exception: BaseException, event: TracebackEvent) -> str | None:
+    """Optionally extract a formatted traceback from the given exception, if the specified traceback event is enabled."""
+
+    if not is_traceback_enabled(event):
+        return None
+
+    # deprecated: description='use the single-arg version of format_traceback' python_version='3.9'
+    tb_lines = traceback.format_exception(type(exception), exception, exception.__traceback__)
+
+    return ''.join(tb_lines)
+
+
+_module_tracebacks_enabled_events: frozenset[TracebackEvent] | None = None
+"""Cached enabled TracebackEvent values extracted from `_ansible_tracebacks_for` module arg."""
+
+
+def _is_module_traceback_enabled(event: TracebackEvent) -> bool:
+    """Module utility function to lazily load traceback config and determine if traceback collection is enabled for the specified event."""
+    global _module_tracebacks_enabled_events
+
+    if _module_tracebacks_enabled_events is None:
+        try:
+            # Suboptimal error handling, but since import order can matter, and this is a critical error path, better to fail silently
+            # than to mask the triggering error by issuing a new error/warning here.
+            from ..basic import _PARSED_MODULE_ARGS
+
+            _module_tracebacks_enabled_events = frozenset(
+                TracebackEvent[value.upper()] for value in _PARSED_MODULE_ARGS.get('_ansible_tracebacks_for')
+            )  # type: ignore[union-attr]
+        except BaseException:
+            return True  # if things failed early enough that we can't figure this out, assume we want a traceback for troubleshooting
+
+    return event in _module_tracebacks_enabled_events
+
+
+_is_traceback_enabled = _is_module_traceback_enabled
+"""Callable to determine if tracebacks are enabled. Overridden on the controller by display. Use `is_traceback_enabled` instead of calling this directly."""

ansible/module_utils/_internal/_validation.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import keyword
+
+
+def validate_collection_name(collection_name: object, name: str = 'collection_name') -> None:
+    """Validate a collection name."""
+    if not isinstance(collection_name, str):
+        raise TypeError(f"{name} must be {str} instead of {type(collection_name)}")
+
+    parts = collection_name.split('.')
+
+    if len(parts) != 2 or not all(part.isidentifier() and not keyword.iskeyword(part) for part in parts):
+        raise ValueError(f"{name} must consist of two non-keyword identifiers separated by '.'")

ansible/module_utils/ansible_release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.18.7rc1'
+__version__ = '2.19.0'
 __author__ = 'Ansible, Inc.'
-__codename__ = "Fool in the Rain"
+__codename__ = "What Is and What Should Never Be"

ansible/module_utils/api.py

@@ -31,8 +31,7 @@ import itertools
 import secrets
 import sys
 import time
-
-import ansible.module_utils.compat.typing as t
+import typing as t
 
 
 def rate_limit_argument_spec(spec=None):