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

ansible/module_utils/_internal/_datatag/_tags.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from ansible.module_utils._internal import _datatag, _messages
+
+
+@dataclasses.dataclass(**_datatag._tag_dataclass_kwargs)
+class Deprecated(_datatag.AnsibleDatatagBase):
+    msg: str
+    help_text: t.Optional[str] = None
+    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/_debugging.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+
+
+def load_params() -> tuple[bytes, str]:
+    """Load module arguments and profile when debugging an Ansible module."""
+    parser = argparse.ArgumentParser(description="Directly invoke an Ansible module for debugging.")
+    parser.add_argument('args', nargs='?', help='module args JSON (file path or inline string)')
+    parser.add_argument('--profile', default='legacy', help='profile for JSON decoding/encoding of args/response')
+
+    parsed_args = parser.parse_args()
+
+    args: str | None = parsed_args.args
+    profile: str = parsed_args.profile
+
+    if args:
+        if (args_path := pathlib.Path(args)).is_file():
+            buffer = args_path.read_bytes()
+        else:
+            buffer = args.encode(errors='surrogateescape')
+    else:
+        if sys.stdin.isatty():
+            sys.stderr.write('Waiting for Ansible module JSON on STDIN...\n')
+            sys.stderr.flush()
+
+        buffer = sys.stdin.buffer.read()
+
+    return buffer, profile

ansible/module_utils/_internal/_deprecator.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import re
+import pathlib
+import sys
+import typing as t
+
+from ansible.module_utils._internal import _stack, _messages, _validation, _plugin_info
+
+
+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.
+
+    if not collection_name:
+        return None
+
+    _validation.validate_collection_name(collection_name)
+
+    return _messages.PluginInfo(
+        resolved_name=collection_name,
+        type=None,
+    )
+
+
+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 deprecator_from_collection_name(collection_name) or get_caller_plugin_info() or INDETERMINATE_DEPRECATOR
+
+
+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 := _stack.caller_frame():
+        return _path_as_plugininfo(frame_info.filename)
+
+    return None  # pragma: nocover
+
+
+def _path_as_plugininfo(path: str) -> _messages.PluginInfo | None:
+    """Return a `PluginInfo` instance if the provided `path` refers to a plugin."""
+    return _path_as_core_plugininfo(path) or _path_as_collection_plugininfo(path)
+
+
+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))
+    except ValueError:
+        return None  # not ansible-core
+
+    namespace = 'ansible.builtin'
+
+    if match := re.match(r'plugins/(?P<plugin_type>\w+)/(?P<plugin_name>\w+)', relpath):
+        plugin_name = match.group("plugin_name")
+        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.
+            # We have no way of knowing if the intermediate code is deprecating its own feature, or acting on behalf of another plugin.
+            # Callers in this case need to identify the deprecating plugin name, otherwise only ansible-core will be reported.
+            # Reporting ansible-core is never wrong, it just may be missing an additional detail (plugin name) in the "on behalf of" case.
+            return ANSIBLE_CORE_DEPRECATOR
+
+        if plugin_name == '__init__':
+            # The plugin type is known, but the caller isn't a specific plugin -- instead, it's core plugin infrastructure (the base class).
+            return _messages.PluginInfo(resolved_name=namespace, type=plugin_type)
+    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 = _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 = _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 _messages.PluginInfo(resolved_name=name, type=plugin_type)
+
+
+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 = _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 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.
+        # We have no way of knowing if the intermediate code is deprecating its own feature, or acting on behalf of another plugin.
+        # Callers in this case need to identify the deprecator to avoid ambiguity, since it could be the same collection or another collection.
+        return INDETERMINATE_DEPRECATOR
+
+    name = '.'.join((match.group('ns'), match.group('coll'), match.group('plugin_name')))
+
+    # DTFIX-FUTURE: deprecations from __init__ will be incorrectly attributed to a plugin of that name
+
+    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

@@ -0,0 +1,101 @@
+# Copyright (c) 2024 Ansible Project
+# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
+
+"""Internal error handling logic for targets. Not for use on the controller."""
+
+from __future__ import annotations as _annotations
+
+import traceback as _sys_traceback
+import typing as _t
+
+from . import _messages
+
+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:'
+
+
+class EventFactory:
+    """Factory for creating `Event` instances from `BaseException` instances on targets."""
+
+    _MAX_DEPTH = 10
+    """Maximum exception chain depth. Exceptions beyond this depth will be omitted."""
+
+    @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/__init__.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import types
+
+import typing as t
+
+from ansible.module_utils._internal._json._profiles import AnsibleProfileJSONEncoder, AnsibleProfileJSONDecoder, _JSONSerializationProfile
+from ansible.module_utils import _internal
+
+_T = t.TypeVar('_T', AnsibleProfileJSONEncoder, AnsibleProfileJSONDecoder)
+
+
+def get_encoder_decoder(profile: str | types.ModuleType, return_type: type[_T]) -> type[_T]:
+    class_name = 'Encoder' if return_type is AnsibleProfileJSONEncoder else 'Decoder'
+
+    return getattr(get_serialization_module(profile), class_name)
+
+
+def get_module_serialization_profile_name(name: str, controller_to_module: bool) -> str:
+    if controller_to_module:
+        name = f'module_{name}_c2m'
+    else:
+        name = f'module_{name}_m2c'
+
+    return name
+
+
+def get_module_serialization_profile_module_name(name: str, controller_to_module: bool) -> str:
+    return get_serialization_module_name(get_module_serialization_profile_name(name, controller_to_module))
+
+
+def get_serialization_profile(name: str | types.ModuleType) -> _JSONSerializationProfile:
+    return getattr(get_serialization_module(name), '_Profile')
+
+
+def get_serialization_module(name: str | types.ModuleType) -> types.ModuleType:
+    return importlib.import_module(get_serialization_module_name(name))
+
+
+def get_serialization_module_name(name: str | types.ModuleType) -> str:
+    if isinstance(name, str):
+        if '.' in name:
+            return name  # name is already fully qualified
+
+        target_name = f'{__name__}._profiles._{name}'
+    elif isinstance(name, types.ModuleType):
+        return name.__name__
+    else:
+        raise TypeError(f'Name is {type(name)} instead of {str} or {types.ModuleType}.')
+
+    if importlib.util.find_spec(target_name):
+        return target_name
+
+    # the value of is_controller can change after import; always pick it up from the module
+    if _internal.is_controller:
+        controller_name = f'ansible._internal._json._profiles._{name}'
+
+        if importlib.util.find_spec(controller_name):
+            return controller_name
+
+    raise ValueError(f'Unknown profile name {name!r}.')

ansible/module_utils/_internal/_json/_legacy_encoder.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from ansible.module_utils._internal._json import _profiles
+from ansible.module_utils._internal._json._profiles import _tagless
+
+
+class LegacyTargetJSONEncoder(_tagless.Encoder):
+    """Compatibility wrapper over `legacy` profile JSON encoder to support trust stripping and vault value plaintext conversion."""
+
+    def __init__(self, preprocess_unsafe: bool = False, vault_to_text: bool = False, _decode_bytes: bool = False, **kwargs) -> None:
+        self._decode_bytes = _decode_bytes
+
+        # NOTE: The preprocess_unsafe and vault_to_text arguments are features of LegacyControllerJSONEncoder.
+        #       They are implemented here to allow callers to pass them without raising an error, but they have no effect.
+
+        super().__init__(**kwargs)
+
+    def default(self, o: object) -> object:
+        if self._decode_bytes:
+            if type(o) is _profiles._WrappedValue:  # pylint: disable=unidiomatic-typecheck
+                o = o.wrapped
+
+            if isinstance(o, bytes):
+                return o.decode(errors='surrogateescape')  # backward compatibility with `ansible.module_utils.basic.jsonify`
+
+        return super().default(o)