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

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

@@ -0,0 +1,31 @@
+"""Legacy wire format for controller to module communication."""
+
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+
+from .. import _profiles
+
+
+class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
+    @classmethod
+    def post_init(cls) -> None:
+        cls.serialize_map = {}
+        cls.serialize_map.update(cls._common_discard_tags)
+        cls.serialize_map.update(
+            {
+                set: cls.serialize_as_list,  # legacy _json_encode_fallback behavior
+                tuple: cls.serialize_as_list,  # JSONEncoder built-in behavior
+                _datetime.date: cls.serialize_as_isoformat,
+                _datetime.time: cls.serialize_as_isoformat,  # always failed pre-2.18, so okay to include for consistency
+                _datetime.datetime: cls.serialize_as_isoformat,
+            }
+        )
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

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

@@ -0,0 +1,35 @@
+"""Legacy wire format for module to controller communication."""
+
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+
+from .. import _profiles
+from ansible.module_utils.common.text.converters import to_text as _to_text
+
+
+class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
+    @classmethod
+    def bytes_to_text(cls, value: bytes) -> str:
+        return _to_text(value, errors='surrogateescape')
+
+    @classmethod
+    def post_init(cls) -> None:
+        cls.allowed_ansible_serializable_types = _profiles._common_module_types | _profiles._common_module_response_types
+
+        cls.serialize_map = {
+            bytes: cls.bytes_to_text,  # legacy behavior from jsonify and container_to_text
+            set: cls.serialize_as_list,  # legacy _json_encode_fallback behavior
+            tuple: cls.serialize_as_list,  # JSONEncoder built-in behavior
+            _datetime.date: cls.serialize_as_isoformat,  # legacy parameters.py does this before serialization
+            _datetime.time: cls.serialize_as_isoformat,  # always failed pre-2.18, so okay to include for consistency
+            _datetime.datetime: cls.serialize_as_isoformat,  # legacy _json_encode_fallback behavior *and* legacy parameters.py does this before serialization
+        }
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

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

@@ -0,0 +1,35 @@
+"""Data tagging aware wire format for controller to module communication."""
+
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+
+from ... import _datatag
+from .. import _profiles
+
+
+class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
+    encode_strings_as_utf8 = True
+
+    @classmethod
+    def post_init(cls) -> None:
+        cls.serialize_map = {}
+        cls.serialize_map.update(cls._common_discard_tags)
+        cls.serialize_map.update(
+            {
+                # The bytes type is not supported, use str instead (future module profiles may support a bytes wrapper distinct from `bytes`).
+                set: cls.serialize_as_list,  # legacy _json_encode_fallback behavior
+                tuple: cls.serialize_as_list,  # JSONEncoder built-in behavior
+                _datetime.date: _datatag.AnsibleSerializableDate,
+                _datetime.time: _datatag.AnsibleSerializableTime,
+                _datetime.datetime: _datatag.AnsibleSerializableDateTime,
+            }
+        )
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

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

@@ -0,0 +1,33 @@
+"""Data tagging aware wire format for module to controller communication."""
+
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+
+from ... import _datatag
+from .. import _profiles
+
+
+class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
+    encode_strings_as_utf8 = True
+
+    @classmethod
+    def post_init(cls) -> None:
+        cls.allowed_ansible_serializable_types = _profiles._common_module_types | _profiles._common_module_response_types
+
+        cls.serialize_map = {
+            # The bytes type is not supported, use str instead (future module profiles may support a bytes wrapper distinct from `bytes`).
+            set: cls.serialize_as_list,  # legacy _json_encode_fallback behavior
+            tuple: cls.serialize_as_list,  # JSONEncoder built-in behavior
+            _datetime.date: _datatag.AnsibleSerializableDate,
+            _datetime.time: _datatag.AnsibleSerializableTime,
+            _datetime.datetime: _datatag.AnsibleSerializableDateTime,
+        }
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

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

@@ -0,0 +1,50 @@
+"""
+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 = {
+            # DTFIX-RELEASE: 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'),
+        }
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

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,55 @@
+"""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
+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-RELEASE: add link to CPython bug report to-be-filed (or update associated deprecation comments if we don't)
+            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_exec_context.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import typing as t
+
+from ._ambient_context import AmbientContextBase
+from ..common.messages import PluginInfo
+
+
+class HasPluginInfo(t.Protocol):
+    """Protocol to type-annotate and expose PluginLoader-set values."""
+
+    @property
+    def _load_name(self) -> str:
+        """The requested name used to load the plugin."""
+
+    @property
+    def ansible_name(self) -> str:
+        """Fully resolved plugin name."""
+
+    @property
+    def plugin_type(self) -> str:
+        """Plugin type name."""
+
+
+class PluginExecContext(AmbientContextBase):
+    """Execution context that wraps all plugin invocations to allow infrastructure introspection of the currently-executing plugin instance."""
+
+    def __init__(self, executing_plugin: HasPluginInfo) -> None:
+        self._executing_plugin = executing_plugin
+
+    @property
+    def executing_plugin(self) -> HasPluginInfo:
+        return self._executing_plugin
+
+    @property
+    def plugin_info(self) -> PluginInfo:
+        return PluginInfo(
+            requested_name=self._executing_plugin._load_name,
+            resolved_name=self._executing_plugin.ansible_name,
+            type=self._executing_plugin.plugin_type,
+        )
+
+    @classmethod
+    def get_current_plugin_info(cls) -> PluginInfo | None:
+        """Utility method to extract a PluginInfo for the currently executing plugin (or None if no plugin is executing)."""
+        if ctx := cls.current(optional=True):
+            return ctx.plugin_info
+
+        return None

ansible/module_utils/_internal/_traceback.py

@@ -0,0 +1,89 @@
+# 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 inspect
+import traceback
+
+
+class TracebackEvent(enum.Enum):
+    """The events for which tracebacks can be enabled."""
+
+    ERROR = enum.auto()
+    WARNING = enum.auto()
+    DEPRECATED = enum.auto()
+
+
+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(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.
+    """
+    if not is_traceback_enabled(event):
+        return None
+
+    tb_lines = []
+
+    if current_frame := inspect.currentframe():
+        # 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))
+    else:
+        tb_lines.append('Traceback unavailable.\n')
+
+    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/ansible_release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.18.5rc1'
+__version__ = '2.19.0b2'
 __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):