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

ansible/module_utils/common/_utils.py

@@ -1,38 +1,34 @@
 # Copyright (c) 2018, Ansible Project
 # Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
-
-
 """
 Modules in _utils are waiting to find a better home.  If you need to use them, be prepared for them
 to move to a different location in the future.
 """
+
 from __future__ import annotations
 
+import inspect
+import typing as t
+
+_Type = t.TypeVar('_Type')
+
+
+def get_all_subclasses(cls: type[_Type], *, include_abstract: bool = True, consider_self: bool = False) -> set[type[_Type]]:
+    """Recursively find all subclasses of a given type, including abstract classes by default."""
+    subclasses: set[type[_Type]] = {cls} if consider_self else set()
+    queue: list[type[_Type]] = [cls]
+
+    while queue:
+        parent = queue.pop()
+
+        for child in parent.__subclasses__():
+            if child in subclasses:
+                continue
+
+            queue.append(child)
+            subclasses.add(child)
+
+    if not include_abstract:
+        subclasses = {sc for sc in subclasses if not inspect.isabstract(sc)}
 
-def get_all_subclasses(cls):
-    '''
-    Recursively search and find all subclasses of a given class
-
-    :arg cls: A python class
-    :rtype: set
-    :returns: The set of python classes which are the subclasses of `cls`.
-
-    In python, you can use a class's :py:meth:`__subclasses__` method to determine what subclasses
-    of a class exist.  However, `__subclasses__` only goes one level deep.  This function searches
-    each child class's `__subclasses__` method to find all of the descendent classes.  It then
-    returns an iterable of the descendent classes.
-    '''
-    # Retrieve direct subclasses
-    subclasses = set(cls.__subclasses__())
-    to_visit = list(subclasses)
-    # Then visit all subclasses
-    while to_visit:
-        for sc in to_visit:
-            # The current class is now visited, so remove it from list
-            to_visit.remove(sc)
-            # Appending all subclasses to visit and keep a reference of available class
-            for ssc in sc.__subclasses__():
-                if ssc not in subclasses:
-                    to_visit.append(ssc)
-                    subclasses.add(ssc)
     return subclasses

ansible/module_utils/common/collections.py

@@ -66,8 +66,7 @@ class ImmutableDict(Hashable, Mapping):
 
 def is_string(seq):
     """Identify whether the input has a string-like type (including bytes)."""
-    # AnsibleVaultEncryptedUnicode inherits from Sequence, but is expected to be a string like object
-    return isinstance(seq, (text_type, binary_type)) or getattr(seq, '__ENCRYPTED__', False)
+    return isinstance(seq, (text_type, binary_type))
 
 
 def is_iterable(seq, include_strings=False):

ansible/module_utils/common/dict_transformations.py

@@ -109,9 +109,9 @@ def _camel_to_snake(name, reversible=False):
 
 
 def dict_merge(a, b):
-    '''recursively merges dicts. not just simple a['key'] = b['key'], if
+    """recursively merges dicts. not just simple a['key'] = b['key'], if
     both a and b have a key whose value is a dict then dict_merge is called
-    on both values and the result stored in the returned dictionary.'''
+    on both values and the result stored in the returned dictionary."""
     if not isinstance(b, dict):
         return b
     result = deepcopy(a)

ansible/module_utils/common/file.py

@@ -55,7 +55,7 @@ def is_executable(path):
     # This method is reused by the basic module,
     # the repetition helps the basic module's html documentation come out right.
     # http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_docstring_signature
-    '''is_executable(path)
+    """is_executable(path)
 
     is the given path executable?
 
@@ -66,7 +66,7 @@ def is_executable(path):
     * Does not account for FSACLs.
     * Most times we really want to know "Can the current user execute this
       file".  This function does not tell us that, only if any execute bit is set.
-    '''
+    """
     # These are all bitfields so first bitwise-or all the permissions we're
     # looking for, then bitwise-and with the file's mode to determine if any
     # execute bits are set.

ansible/module_utils/common/json.py

@@ -1,84 +1,90 @@
-# -*- coding: utf-8 -*-
-# Copyright (c) 2019 Ansible Project
-# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
-
-from __future__ import annotations
-
-import json
-
-import datetime
-
-from ansible.module_utils.common.text.converters import to_text
-from ansible.module_utils.six.moves.collections_abc import Mapping
-from ansible.module_utils.common.collections import is_sequence
-
-
-def _is_unsafe(value):
-    return getattr(value, '__UNSAFE__', False) and not getattr(value, '__ENCRYPTED__', False)
-
-
-def _is_vault(value):
-    return getattr(value, '__ENCRYPTED__', False)
-
-
-def _preprocess_unsafe_encode(value):
-    """Recursively preprocess a data structure converting instances of ``AnsibleUnsafe``
-    into their JSON dict representations
-
-    Used in ``AnsibleJSONEncoder.iterencode``
-    """
-    if _is_unsafe(value):
-        value = {'__ansible_unsafe': to_text(value._strip_unsafe(), errors='surrogate_or_strict', nonstring='strict')}
-    elif is_sequence(value):
-        value = [_preprocess_unsafe_encode(v) for v in value]
-    elif isinstance(value, Mapping):
-        value = dict((k, _preprocess_unsafe_encode(v)) for k, v in value.items())
-
-    return value
-
-
-def json_dump(structure):
-    return json.dumps(structure, cls=AnsibleJSONEncoder, sort_keys=True, indent=4)
-
-
-class AnsibleJSONEncoder(json.JSONEncoder):
-    '''
-    Simple encoder class to deal with JSON encoding of Ansible internal types
-    '''
-
-    def __init__(self, preprocess_unsafe=False, vault_to_text=False, **kwargs):
-        self._preprocess_unsafe = preprocess_unsafe
-        self._vault_to_text = vault_to_text
-        super(AnsibleJSONEncoder, self).__init__(**kwargs)
-
-    # NOTE: ALWAYS inform AWS/Tower when new items get added as they consume them downstream via a callback
-    def default(self, o):
-        if getattr(o, '__ENCRYPTED__', False):
-            # vault object
-            if self._vault_to_text:
-                value = to_text(o, errors='surrogate_or_strict')
-            else:
-                value = {'__ansible_vault': to_text(o._ciphertext, errors='surrogate_or_strict', nonstring='strict')}
-        elif getattr(o, '__UNSAFE__', False):
-            # unsafe object, this will never be triggered, see ``AnsibleJSONEncoder.iterencode``
-            value = {'__ansible_unsafe': to_text(o._strip_unsafe(), errors='surrogate_or_strict', nonstring='strict')}
-        elif isinstance(o, Mapping):
-            # hostvars and other objects
-            value = dict(o)
-        elif isinstance(o, (datetime.date, datetime.datetime)):
-            # date object
-            value = o.isoformat()
-        else:
-            # use default encoder
-            value = super(AnsibleJSONEncoder, self).default(o)
-        return value
-
-    def iterencode(self, o, **kwargs):
-        """Custom iterencode, primarily design to handle encoding ``AnsibleUnsafe``
-        as the ``AnsibleUnsafe`` subclasses inherit from string types and
-        ``json.JSONEncoder`` does not support custom encoders for string types
-        """
-        if self._preprocess_unsafe:
-            o = _preprocess_unsafe_encode(o)
-
-        return super(AnsibleJSONEncoder, self).iterencode(o, **kwargs)
+from __future__ import annotations as _annotations
+
+import enum as _enum
+import json as _stdlib_json
+import types as _types
+
+from ansible.module_utils import _internal
+from ansible.module_utils._internal import _json
+from ansible.module_utils._internal._json import _legacy_encoder
+from ansible.module_utils._internal._json import _profiles
+from ansible.module_utils._internal._json._profiles import _tagless
+from ansible.module_utils.common import warnings as _warnings
+
+
+def __getattr__(name: str) -> object:
+    """Handle dynamic module members which are or will be deprecated."""
+    if name in ('AnsibleJSONEncoder', '_AnsibleJSONEncoder'):
+        # deprecated: description='deprecate legacy encoder' core_version='2.23'
+        # if not name.startswith('_'):  # avoid duplicate deprecation warning for imports from ajson
+        #     _warnings.deprecate(
+        #         msg="The `AnsibleJSONEncoder` type is deprecated.",
+        #         version="2.27",
+        #         help_text="Use a profile-based encoder instead.",  # DTFIX-RELEASE: improve this help text
+        #     )
+
+        return _get_legacy_encoder()
+
+    if name in ('AnsibleJSONDecoder', '_AnsibleJSONDecoder'):
+        # deprecated: description='deprecate legacy decoder' core_version='2.23'
+        # if not name.startswith('_'):  # avoid duplicate deprecation warning for imports from ajson
+        #     _warnings.deprecate(
+        #         msg="The `AnsibleJSONDecoder` type is deprecated.",
+        #         version="2.27",
+        #         help_text="Use a profile-based decoder instead.",  # DTFIX-RELEASE: improve this help text
+        #     )
+
+        return _tagless.Decoder
+
+    if name == 'json_dump':
+        _warnings.deprecate(
+            msg="The `json_dump` function is deprecated.",
+            version="2.23",
+            help_text="Use `json.dumps` with the appropriate `cls` instead.",
+        )
+
+        return _json_dump
+
+    raise AttributeError(name)
+
+
+def _get_legacy_encoder() -> type[_stdlib_json.JSONEncoder]:
+    """Compatibility hack: previous module_utils AnsibleJSONEncoder impl did controller-side work, controller plugins require a more fully-featured impl."""
+    if _internal.is_controller:
+        return _internal.import_controller_module('ansible._internal._json._legacy_encoder').LegacyControllerJSONEncoder
+
+    return _legacy_encoder.LegacyTargetJSONEncoder
+
+
+def _json_dump(structure):
+    """JSON dumping function maintained for temporary backward compatibility."""
+    return _stdlib_json.dumps(structure, cls=_get_legacy_encoder(), sort_keys=True, indent=4)
+
+
+class Direction(_enum.Enum):
+    """Enumeration used to select a contextually-appropriate JSON profile for module messaging."""
+
+    CONTROLLER_TO_MODULE = _enum.auto()
+    """Encode/decode messages from the Ansible controller to an Ansible module."""
+    MODULE_TO_CONTROLLER = _enum.auto()
+    """Encode/decode messages from an Ansible module to the Ansible controller."""
+
+
+def get_encoder(profile: str | _types.ModuleType, /) -> type[_stdlib_json.JSONEncoder]:
+    """Return a `JSONEncoder` for the given `profile`."""
+    return _json.get_encoder_decoder(profile, _profiles.AnsibleProfileJSONEncoder)
+
+
+def get_decoder(profile: str | _types.ModuleType, /) -> type[_stdlib_json.JSONDecoder]:
+    """Return a `JSONDecoder` for the given `profile`."""
+    return _json.get_encoder_decoder(profile, _profiles.AnsibleProfileJSONDecoder)
+
+
+def get_module_encoder(name: str, direction: Direction, /) -> type[_stdlib_json.JSONEncoder]:
+    """Return a `JSONEncoder` for the module profile specified by `name` and `direction`."""
+    return get_encoder(_json.get_module_serialization_profile_name(name, direction == Direction.CONTROLLER_TO_MODULE))
+
+
+def get_module_decoder(name: str, direction: Direction, /) -> type[_stdlib_json.JSONDecoder]:
+    """Return a `JSONDecoder` for the module profile specified by `name` and `direction`."""
+    return get_decoder(_json.get_module_serialization_profile_name(name, direction == Direction.CONTROLLER_TO_MODULE))

ansible/module_utils/common/locale.py

@@ -7,7 +7,7 @@ from ansible.module_utils.common.text.converters import to_native
 
 
 def get_best_parsable_locale(module, preferences=None, raise_on_locale=False):
-    '''
+    """
         Attempts to return the best possible locale for parsing output in English
         useful for scraping output with i18n tools. When this raises an exception
         and the caller wants to continue, it should use the 'C' locale.
@@ -17,7 +17,7 @@ def get_best_parsable_locale(module, preferences=None, raise_on_locale=False):
         :param raise_on_locale: boolean that determines if we raise exception or not
                                 due to locale CLI issues
         :returns: The first matched preferred locale or 'C' which is the default
-    '''
+    """
 
     found = 'C'  # default posix, its ascii but always there
     try:

ansible/module_utils/common/messages.py

@@ -0,0 +1,108 @@
+"""
+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 sys as _sys
+import dataclasses as _dataclasses
+
+# 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
+
+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)
+
+
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class PluginInfo(_datatag.AnsibleSerializableDataclass):
+    """Information about a loaded plugin."""
+
+    requested_name: str
+    """The plugin name as requested, before resolving, which may be partially or fully qualified."""
+    resolved_name: str
+    """The resolved canonical plugin name; always fully-qualified for collection plugins."""
+    type: str
+    """The plugin type."""
+
+
+@_dataclasses.dataclass(**_dataclass_kwargs)
+class Detail(_datatag.AnsibleSerializableDataclass):
+    """Message detail with optional source context and help text."""
+
+    msg: str
+    formatted_source_context: _t.Optional[str] = None
+    help_text: _t.Optional[str] = None
+
+
+@_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')
+
+
+@_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."""
+
+    version: _t.Optional[str] = None
+    date: _t.Optional[str] = None
+    plugin: _t.Optional[PluginInfo] = None
+
+    @property
+    def collection_name(self) -> _t.Optional[str]:
+        if not self.plugin:
+            return None
+
+        parts = self.plugin.resolved_name.split('.')
+
+        if len(parts) < 2:
+            return None
+
+        collection_name = '.'.join(parts[:2])
+
+        # deprecated: description='enable the deprecation message for collection_name' core_version='2.23'
+        # from ansible.module_utils.datatag import deprecate_value
+        # collection_name = deprecate_value(collection_name, 'The `collection_name` property is deprecated.', removal_version='2.27')
+
+        return collection_name
+
+    def _as_simple_dict(self) -> _t.Dict[str, _t.Any]:
+        """Returns a dictionary representation of the deprecation object in the format exposed to playbooks."""
+        result = self._as_dict()
+        result.update(
+            msg=self._format(),
+            collection_name=self.collection_name,
+        )
+
+        return result

ansible/module_utils/common/parameters.py

@@ -6,13 +6,16 @@ from __future__ import annotations
 
 import datetime
 import os
+import typing as t
 
 from collections import deque
 from itertools import chain
 
 from ansible.module_utils.common.collections import is_iterable
+from ansible.module_utils._internal._datatag import AnsibleSerializable, AnsibleTagHelper
 from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.module_utils.common.warnings import warn
+from ansible.module_utils.datatag import native_type_name
 from ansible.module_utils.errors import (
     AliasError,
     AnsibleFallbackNotFound,
@@ -83,7 +86,7 @@ _ADDITIONAL_CHECKS = (
 # if adding boolean attribute, also add to PASS_BOOL
 # some of this dupes defaults from controller config
 # keep in sync with copy in lib/ansible/module_utils/csharp/Ansible.Basic.cs
-PASS_VARS = {
+PASS_VARS: dict[str, t.Any] = {
     'check_mode': ('check_mode', False),
     'debug': ('_debug', False),
     'diff': ('_diff', False),
@@ -96,9 +99,9 @@ PASS_VARS = {
     'selinux_special_fs': ('_selinux_special_fs', ['fuse', 'nfs', 'vboxsf', 'ramfs', '9p', 'vfat']),
     'shell_executable': ('_shell', '/bin/sh'),
     'socket': ('_socket_path', None),
-    'string_conversion_action': ('_string_conversion_action', 'warn'),
     'syslog_facility': ('_syslog_facility', 'INFO'),
     'tmpdir': ('_tmpdir', None),
+    'tracebacks_for': ('_tracebacks_for', frozenset()),
     'verbosity': ('_verbosity', 0),
     'version': ('ansible_version', '0.0'),
 }
@@ -408,6 +411,8 @@ def _remove_values_conditions(value, no_log_strings, deferred_removals):
         dictionary for ``level1``, then the dict for ``level2``, and finally
         the list for ``level3``.
     """
+    original_value = value
+
     if isinstance(value, (text_type, binary_type)):
         # Need native str type
         native_str_value = value
@@ -432,31 +437,25 @@ def _remove_values_conditions(value, no_log_strings, deferred_removals):
         else:
             value = native_str_value
 
+    elif value is True or value is False or value is None:
+        return value
+
     elif isinstance(value, Sequence):
-        if isinstance(value, MutableSequence):
-            new_value = type(value)()
-        else:
-            new_value = []  # Need a mutable value
+        new_value = AnsibleTagHelper.tag_copy(original_value, [])
         deferred_removals.append((value, new_value))
-        value = new_value
+        return new_value
 
     elif isinstance(value, Set):
-        if isinstance(value, MutableSet):
-            new_value = type(value)()
-        else:
-            new_value = set()  # Need a mutable value
+        new_value = AnsibleTagHelper.tag_copy(original_value, set())
         deferred_removals.append((value, new_value))
-        value = new_value
+        return new_value
 
     elif isinstance(value, Mapping):
-        if isinstance(value, MutableMapping):
-            new_value = type(value)()
-        else:
-            new_value = {}  # Need a mutable value
+        new_value = AnsibleTagHelper.tag_copy(original_value, {})
         deferred_removals.append((value, new_value))
-        value = new_value
+        return new_value
 
-    elif isinstance(value, tuple(chain(integer_types, (float, bool, NoneType)))):
+    elif isinstance(value, (int, float)):
         stringy_value = to_native(value, encoding='utf-8', errors='surrogate_or_strict')
         if stringy_value in no_log_strings:
             return 'VALUE_SPECIFIED_IN_NO_LOG_PARAMETER'
@@ -464,11 +463,15 @@ def _remove_values_conditions(value, no_log_strings, deferred_removals):
             if omit_me in stringy_value:
                 return 'VALUE_SPECIFIED_IN_NO_LOG_PARAMETER'
 
-    elif isinstance(value, (datetime.datetime, datetime.date)):
-        value = value.isoformat()
+    elif isinstance(value, (datetime.datetime, datetime.date, datetime.time)):
+        return value
+    elif isinstance(value, AnsibleSerializable):
+        return value
     else:
         raise TypeError('Value of unknown type: %s, %s' % (type(value), value))
 
+    value = AnsibleTagHelper.tag_copy(original_value, value)
+
     return value
 
 
@@ -541,7 +544,7 @@ def _sanitize_keys_conditions(value, no_log_strings, ignore_keys, deferred_remov
     if isinstance(value, tuple(chain(integer_types, (float, bool, NoneType)))):
         return value
 
-    if isinstance(value, (datetime.datetime, datetime.date)):
+    if isinstance(value, (datetime.datetime, datetime.date, datetime.time)):
         return value
 
     raise TypeError('Value of unknown type: %s, %s' % (type(value), value))
@@ -570,7 +573,7 @@ def _validate_elements(wanted_type, parameter, values, options_context=None, err
             msg = "Elements value for option '%s'" % parameter
             if options_context:
                 msg += " found in '%s'" % " -> ".join(options_context)
-            msg += " is of type %s and we were unable to convert to %s: %s" % (type(value), wanted_element_type, to_native(e))
+            msg += " is of type %s and we were unable to convert to %s: %s" % (native_type_name(value), wanted_element_type, to_native(e))
             errors.append(ElementError(msg))
     return validated_parameters
 
@@ -629,7 +632,7 @@ def _validate_argument_types(argument_spec, parameters, prefix='', options_conte
             elements_wanted_type = spec.get('elements', None)
             if elements_wanted_type:
                 elements = parameters[param]
-                if wanted_type != 'list' or not isinstance(elements, list):
+                if not isinstance(parameters[param], list) or not isinstance(elements, list):
                     msg = "Invalid type %s for option '%s'" % (wanted_name, elements)
                     if options_context:
                         msg += " found in '%s'." % " -> ".join(options_context)
@@ -638,7 +641,7 @@ def _validate_argument_types(argument_spec, parameters, prefix='', options_conte
                 parameters[param] = _validate_elements(elements_wanted_type, param, elements, options_context, errors)
 
         except (TypeError, ValueError) as e:
-            msg = "argument '%s' is of type %s" % (param, type(value))
+            msg = "argument '%s' is of type %s" % (param, native_type_name(value))
             if options_context:
                 msg += " found in '%s'." % " -> ".join(options_context)
             msg += " and we were unable to convert to %s: %s" % (wanted_name, to_native(e))

ansible/module_utils/common/process.py

@@ -10,7 +10,7 @@ from ansible.module_utils.common.warnings import deprecate
 
 
 def get_bin_path(arg, opt_dirs=None, required=None):
-    '''
+    """
     Find system executable in PATH. Raises ValueError if the executable is not found.
 
     :param arg: the executable to find
@@ -24,7 +24,7 @@ def get_bin_path(arg, opt_dirs=None, required=None):
 
     In addition to PATH and opt_dirs, this function also looks through /sbin, /usr/sbin and /usr/local/sbin. A lot of
     modules, especially for gathering facts, depend on this behaviour.
-    '''
+    """
     if required is not None:
         deprecate(
             msg="The `required` parameter in `get_bin_path` API is deprecated.",