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

ansible/module_utils/common/sys_info.py

@@ -14,7 +14,7 @@ __all__ = ('get_distribution', 'get_distribution_version', 'get_platform_subclas
 
 
 def get_distribution():
-    '''
+    """
     Return the name of the distribution the module is running on.
 
     :rtype: NativeString or None
@@ -23,7 +23,7 @@ def get_distribution():
     This function attempts to determine what distribution the code is running
     on and return a string representing that value. If the platform is Linux
     and the distribution cannot be determined, it returns ``OtherLinux``.
-    '''
+    """
     distribution = distro.id().capitalize()
 
     if platform.system() == 'Linux':
@@ -38,14 +38,14 @@ def get_distribution():
 
 
 def get_distribution_version():
-    '''
+    """
     Get the version of the distribution the code is running on
 
     :rtype: NativeString or None
     :returns: A string representation of the version of the distribution. If it
     cannot determine the version, it returns an empty string. If this is not run on
     a Linux machine it returns None.
-    '''
+    """
     version = None
 
     needs_best_version = frozenset((
@@ -79,12 +79,12 @@ def get_distribution_version():
 
 
 def get_distribution_codename():
-    '''
+    """
     Return the code name for this Linux Distribution
 
     :rtype: NativeString or None
     :returns: A string representation of the distribution's codename or None if not a Linux distro
-    '''
+    """
     codename = None
     if platform.system() == 'Linux':
         # Until this gets merged and we update our bundled copy of distro:
@@ -109,7 +109,7 @@ def get_distribution_codename():
 
 
 def get_platform_subclass(cls):
-    '''
+    """
     Finds a subclass implementing desired functionality on the platform the code is running on
 
     :arg cls: Class to find an appropriate subclass for
@@ -135,7 +135,7 @@ def get_platform_subclass(cls):
             def __new__(cls, *args, **kwargs):
                 new_cls = get_platform_subclass(User)
                 return super(cls, new_cls).__new__(new_cls)
-    '''
+    """
     this_platform = platform.system()
     distribution = get_distribution()
 

ansible/module_utils/common/text/converters.py

@@ -6,12 +6,9 @@
 from __future__ import annotations
 
 import codecs
-import datetime
 import json
 
-from ansible.module_utils.six.moves.collections_abc import Set
 from ansible.module_utils.six import (
-    PY3,
     binary_type,
     iteritems,
     text_type,
@@ -237,49 +234,30 @@ def to_text(obj, encoding='utf-8', errors=None, nonstring='simplerepr'):
     return to_text(value, encoding, errors)
 
 
-#: :py:func:`to_native`
-#:      Transform a variable into the native str type for the python version
-#:
-#:      On Python2, this is an alias for
-#:      :func:`~ansible.module_utils.to_bytes`.  On Python3 it is an alias for
-#:      :func:`~ansible.module_utils.to_text`.  It makes it easier to
-#:      transform a variable into the native str type for the python version
-#:      the code is running on.  Use this when constructing the message to
-#:      send to exceptions or when dealing with an API that needs to take
-#:      a native string.  Example::
-#:
-#:          try:
-#:              1//0
-#:          except ZeroDivisionError as e:
-#:              raise MyException('Encountered and error: %s' % to_native(e))
-if PY3:
-    to_native = to_text
-else:
-    to_native = to_bytes
-
-
-def _json_encode_fallback(obj):
-    if isinstance(obj, Set):
-        return list(obj)
-    elif isinstance(obj, datetime.datetime):
-        return obj.isoformat()
-    raise TypeError("Cannot json serialize %s" % to_native(obj))
+to_native = to_text
 
 
 def jsonify(data, **kwargs):
-    try:
-        new_data = container_to_text(data, encoding='utf-8')
-    except UnicodeDecodeError:
-        raise UnicodeError('Invalid unicode encoding encountered')
-    return json.dumps(new_data, default=_json_encode_fallback, **kwargs)
+    from ansible.module_utils.common import json as _common_json
+    # from ansible.module_utils.common.warnings import deprecate
+
+    # deprecated: description='deprecate jsonify()' core_version='2.23'
+    # deprecate(
+    #     msg="The `jsonify` function is deprecated.",
+    #     version="2.27",
+    #     # help_text="",  # DTFIX-FUTURE: fill in this help text
+    # )
+
+    return json.dumps(data, cls=_common_json._get_legacy_encoder(), _decode_bytes=True, **kwargs)
 
 
 def container_to_bytes(d, encoding='utf-8', errors='surrogate_or_strict'):
-    ''' Recursively convert dict keys and values to byte str
+    """ Recursively convert dict keys and values to byte str
 
         Specialized for json return because this only handles, lists, tuples,
         and dict container types (the containers that the json module returns)
-    '''
+    """
+    # DTFIX-FUTURE: deprecate
 
     if isinstance(d, text_type):
         return to_bytes(d, encoding=encoding, errors=errors)
@@ -299,6 +277,7 @@ def container_to_text(d, encoding='utf-8', errors='surrogate_or_strict'):
     Specialized for json return because this only handles, lists, tuples,
     and dict container types (the containers that the json module returns)
     """
+    # DTFIX-FUTURE: deprecate
 
     if isinstance(d, binary_type):
         # Warning, can traceback

ansible/module_utils/common/validation.py

@@ -10,16 +10,14 @@ import os
 import re
 
 from ast import literal_eval
+from ansible.module_utils.common import json as _common_json
 from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.common.collections import is_iterable
-from ansible.module_utils.common.text.converters import jsonify
 from ansible.module_utils.common.text.formatters import human_to_bytes
 from ansible.module_utils.common.warnings import deprecate
 from ansible.module_utils.parsing.convert_bool import boolean
 from ansible.module_utils.six import (
-    binary_type,
     string_types,
-    text_type,
 )
 
 
@@ -185,7 +183,7 @@ def check_required_by(requirements, parameters, options_context=None):
     :kwarg options_context: List of strings of parent key names if ``requirements`` are
         in a sub spec.
 
-    :returns: Empty dictionary or raises :class:`TypeError` if the
+    :returns: Empty dictionary or raises :class:`TypeError` if the check fails.
     """
 
     result = {}
@@ -195,22 +193,15 @@ def check_required_by(requirements, parameters, options_context=None):
     for (key, value) in requirements.items():
         if key not in parameters or parameters[key] is None:
             continue
-        result[key] = []
         # Support strings (single-item lists)
         if isinstance(value, string_types):
             value = [value]
-        for required in value:
-            if required not in parameters or parameters[required] is None:
-                result[key].append(required)
-
-    if result:
-        for key, missing in result.items():
-            if len(missing) > 0:
-                msg = "missing parameter(s) required by '%s': %s" % (key, ', '.join(missing))
-                if options_context:
-                    msg = "{0} found in {1}".format(msg, " -> ".join(options_context))
-                raise TypeError(to_native(msg))
 
+        if missing := [required for required in value if required not in parameters or parameters[required] is None]:
+            msg = f"missing parameter(s) required by '{key}': {', '.join(missing)}"
+            if options_context:
+                msg = f"{msg} found in {' -> '.join(options_context)}"
+            raise TypeError(to_native(msg))
     return result
 
 
@@ -392,6 +383,10 @@ def check_type_str(value, allow_conversion=True, param=None, prefix=''):
     raise TypeError(to_native(msg))
 
 
+def _check_type_str_no_conversion(value) -> str:
+    return check_type_str(value, allow_conversion=False)
+
+
 def check_type_list(value):
     """Verify that the value is a list or convert to a list
 
@@ -407,6 +402,7 @@ def check_type_list(value):
     if isinstance(value, list):
         return value
 
+    # DTFIX-FUTURE: deprecate legacy comma split functionality, eventually replace with `_check_type_list_strict`
     if isinstance(value, string_types):
         return value.split(",")
     elif isinstance(value, int) or isinstance(value, float):
@@ -415,6 +411,14 @@ def check_type_list(value):
     raise TypeError('%s cannot be converted to a list' % type(value))
 
 
+def _check_type_list_strict(value):
+    # FUTURE: this impl should replace `check_type_list`
+    if isinstance(value, list):
+        return value
+
+    return [value]
+
+
 def check_type_dict(value):
     """Verify that value is a dict or convert it to a dict and return it.
 
@@ -572,14 +576,21 @@ def check_type_bits(value):
 
 
 def check_type_jsonarg(value):
-    """Return a jsonified string. Sometimes the controller turns a json string
-    into a dict/list so transform it back into json here
-
-    Raises :class:`TypeError` if unable to convert the value
-
     """
-    if isinstance(value, (text_type, binary_type)):
+    JSON serialize dict/list/tuple, strip str and bytes.
+    Previously required for cases where Ansible/Jinja classic-mode literal eval pass could inadvertently deserialize objects.
+    """
+    # deprecated: description='deprecate jsonarg type support' core_version='2.23'
+    # deprecate(
+    #     msg="The `jsonarg` type is deprecated.",
+    #     version="2.27",
+    #     help_text="JSON string arguments should use `str`; structures can be explicitly serialized as JSON with the `to_json` filter.",
+    # )
+
+    if isinstance(value, (str, bytes)):
         return value.strip()
-    elif isinstance(value, (list, tuple, dict)):
-        return jsonify(value)
+
+    if isinstance(value, (list, tuple, dict)):
+        return json.dumps(value, cls=_common_json._get_legacy_encoder(), _decode_bytes=True)
+
     raise TypeError('%s cannot be converted to a json string' % type(value))

ansible/module_utils/common/warnings.py

@@ -2,38 +2,156 @@
 # 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
+from __future__ import annotations as _annotations
 
-from ansible.module_utils.six import string_types
+import typing as _t
 
-_global_warnings = []
-_global_deprecations = []
+from ansible.module_utils._internal import _traceback, _deprecator, _event_utils, _messages, _errors
+from ansible.module_utils import _internal
 
 
-def warn(warning):
-    if isinstance(warning, string_types):
-        _global_warnings.append(warning)
-    else:
-        raise TypeError("warn requires a string not a %s" % type(warning))
+def warn(
+    warning: str,
+    *,
+    help_text: str | None = None,
+    obj: object | None = None,
+) -> None:
+    """Record a warning to be returned with the module result."""
+    _skip_stackwalk = True
 
+    if _internal.is_controller:
+        _display = _internal.import_controller_module('ansible.utils.display').Display()
+        _display.warning(
+            msg=warning,
+            help_text=help_text,
+            obj=obj,
+        )
 
-def deprecate(msg, version=None, date=None, collection_name=None):
-    if isinstance(msg, string_types):
-        # For compatibility, we accept that neither version nor date is set,
-        # and treat that the same as if version would haven been set
-        if date is not None:
-            _global_deprecations.append({'msg': msg, 'date': date, 'collection_name': collection_name})
-        else:
-            _global_deprecations.append({'msg': msg, 'version': version, 'collection_name': collection_name})
-    else:
-        raise TypeError("deprecate requires a string not a %s" % type(msg))
+        return
 
+    warning = _messages.WarningSummary(
+        event=_messages.Event(
+            msg=warning,
+            help_text=help_text,
+            formatted_traceback=_traceback.maybe_capture_traceback(warning, _traceback.TracebackEvent.WARNING),
+        ),
+    )
 
-def get_warning_messages():
-    """Return a tuple of warning messages accumulated over this run"""
-    return tuple(_global_warnings)
+    _global_warnings[warning] = None
 
 
-def get_deprecation_messages():
-    """Return a tuple of deprecations accumulated over this run"""
-    return tuple(_global_deprecations)
+def error_as_warning(
+    msg: str | None,
+    exception: BaseException,
+    *,
+    help_text: str | None = None,
+    obj: object = None,
+) -> None:
+    """Display an exception as a warning."""
+    _skip_stackwalk = True
+
+    if _internal.is_controller:
+        _display = _internal.import_controller_module('ansible.utils.display').Display()
+        _display.error_as_warning(
+            msg=msg,
+            exception=exception,
+            help_text=help_text,
+            obj=obj,
+        )
+
+        return
+
+    event = _errors.EventFactory.from_exception(exception, _traceback.is_traceback_enabled(_traceback.TracebackEvent.WARNING))
+
+    warning = _messages.WarningSummary(
+        event=_messages.Event(
+            msg=msg,
+            help_text=help_text,
+            formatted_traceback=_traceback.maybe_capture_traceback(msg, _traceback.TracebackEvent.WARNING),
+            chain=_messages.EventChain(
+                msg_reason=_errors.MSG_REASON_DIRECT_CAUSE,
+                traceback_reason=_errors.TRACEBACK_REASON_EXCEPTION_DIRECT_WARNING,
+                event=event,
+            ),
+        ),
+    )
+
+    _global_warnings[warning] = None
+
+
+def deprecate(
+    msg: str,
+    version: str | None = None,
+    date: str | None = None,
+    collection_name: str | None = None,
+    *,
+    deprecator: _messages.PluginInfo | None = None,
+    help_text: str | None = None,
+    obj: object | None = None,
+) -> None:
+    """
+    Record a deprecation warning.
+    The `obj` argument is only useful in a controller context; it is ignored for target-side callers.
+    Most callers do not need to provide `collection_name` or `deprecator` -- but provide only one if needed.
+    Specify `version` or `date`, but not both.
+    If `date` is a string, it must be in the form `YYYY-MM-DD`.
+    """
+    _skip_stackwalk = True
+
+    deprecator = _deprecator.get_best_deprecator(deprecator=deprecator, collection_name=collection_name)
+
+    if _internal.is_controller:
+        _display = _internal.import_controller_module('ansible.utils.display').Display()
+        _display.deprecated(
+            msg=msg,
+            version=version,
+            date=date,
+            help_text=help_text,
+            obj=obj,
+            # skip passing collection_name; get_best_deprecator already accounted for it when present
+            deprecator=deprecator,
+        )
+
+        return
+
+    warning = _messages.DeprecationSummary(
+        event=_messages.Event(
+            msg=msg,
+            help_text=help_text,
+            formatted_traceback=_traceback.maybe_capture_traceback(msg, _traceback.TracebackEvent.DEPRECATED),
+        ),
+        version=version,
+        date=date,
+        deprecator=deprecator,
+    )
+
+    _global_deprecations[warning] = None
+
+
+def get_warning_messages() -> tuple[str, ...]:
+    """Return a tuple of warning messages accumulated over this run."""
+    # DTFIX7: add future deprecation comment
+    return tuple(_event_utils.format_event_brief_message(item.event) for item in _global_warnings)
+
+
+def get_deprecation_messages() -> tuple[dict[str, _t.Any], ...]:
+    """Return a tuple of deprecation warning messages accumulated over this run."""
+    # DTFIX7: add future deprecation comment
+    return tuple(_event_utils.deprecation_as_dict(item) for item in _global_deprecations)
+
+
+def get_warnings() -> list[_messages.WarningSummary]:
+    """Return a list of warning messages accumulated over this run."""
+    return list(_global_warnings)
+
+
+def get_deprecations() -> list[_messages.DeprecationSummary]:
+    """Return a list of deprecations accumulated over this run."""
+    return list(_global_deprecations)
+
+
+_global_warnings: dict[_messages.WarningSummary, object] = {}
+"""Global, ordered, de-duplicated storage of accumulated warnings for the current module run."""
+
+_global_deprecations: dict[_messages.DeprecationSummary, object] = {}
+"""Global, ordered, de-duplicated storage of accumulated deprecations for the current module run."""

ansible/module_utils/common/yaml.py

@@ -6,10 +6,15 @@ This file provides ease of use shortcuts for loading and dumping YAML,
 preferring the YAML compiled C extensions to reduce duplicated code.
 """
 
-from __future__ import annotations
+from __future__ import annotations as _annotations
+
+import collections.abc as _c
+import typing as _t
 
 from functools import partial as _partial
 
+from .._internal import _datatag
+
 HAS_LIBYAML = False
 
 try:
@@ -19,23 +24,44 @@ except ImportError:
 else:
     HAS_YAML = True
 
+# DTFIX-FUTURE: refactor this to share the implementation with the controller version
+#              use an abstract base class, with __init_subclass__ for representer registration, and instance methods for overridable representers
+#              then tests can be consolidated instead of having two nearly identical copies
+
 if HAS_YAML:
     try:
         from yaml import CSafeLoader as SafeLoader
         from yaml import CSafeDumper as SafeDumper
+        from yaml.representer import SafeRepresenter
         from yaml.cyaml import CParser as Parser  # type: ignore[attr-defined]  # pylint: disable=unused-import
 
         HAS_LIBYAML = True
     except (ImportError, AttributeError):
         from yaml import SafeLoader  # type: ignore[assignment]
         from yaml import SafeDumper  # type: ignore[assignment]
+        from yaml.representer import SafeRepresenter  # type: ignore[assignment]
         from yaml.parser import Parser  # type: ignore[assignment]  # pylint: disable=unused-import
 
+    class _AnsibleDumper(SafeDumper):
+        pass
+
+    def _represent_ansible_tagged_object(self, data: _datatag.AnsibleTaggedObject) -> _t.Any:
+        return self.represent_data(_datatag.AnsibleTagHelper.as_native_type(data))
+
+    def _represent_tripwire(self, data: _datatag.Tripwire) -> _t.NoReturn:
+        data.trip()
+
+    _AnsibleDumper.add_multi_representer(_datatag.AnsibleTaggedObject, _represent_ansible_tagged_object)
+
+    _AnsibleDumper.add_multi_representer(_datatag.Tripwire, _represent_tripwire)
+    _AnsibleDumper.add_multi_representer(_c.Mapping, SafeRepresenter.represent_dict)
+    _AnsibleDumper.add_multi_representer(_c.Sequence, SafeRepresenter.represent_list)
+
     yaml_load = _partial(_yaml.load, Loader=SafeLoader)
     yaml_load_all = _partial(_yaml.load_all, Loader=SafeLoader)
 
-    yaml_dump = _partial(_yaml.dump, Dumper=SafeDumper)
-    yaml_dump_all = _partial(_yaml.dump_all, Dumper=SafeDumper)
+    yaml_dump = _partial(_yaml.dump, Dumper=_AnsibleDumper)
+    yaml_dump_all = _partial(_yaml.dump_all, Dumper=_AnsibleDumper)
 else:
     SafeLoader = object  # type: ignore[assignment,misc]
     SafeDumper = object  # type: ignore[assignment,misc]

ansible/module_utils/compat/datetime.py

@@ -3,36 +3,48 @@
 
 from __future__ import annotations
 
-from ansible.module_utils.six import PY3
+import datetime as _datetime
+import typing as t
 
-import datetime
+from ansible.module_utils.common.warnings import deprecate
 
 
-if PY3:
-    UTC = datetime.timezone.utc
-else:
-    _ZERO = datetime.timedelta(0)
+_UTC = _datetime.timezone.utc
 
-    class _UTC(datetime.tzinfo):
-        __slots__ = ()
 
-        def utcoffset(self, dt):
-            return _ZERO
+def _utcfromtimestamp(timestamp: float) -> _datetime.datetime:
+    """Construct an aware UTC datetime from a POSIX timestamp."""
+    return _datetime.datetime.fromtimestamp(timestamp, _UTC)
 
-        def dst(self, dt):
-            return _ZERO
 
-        def tzname(self, dt):
-            return "UTC"
+def _utcnow() -> _datetime.datetime:
+    """Construct an aware UTC datetime from time.time()."""
+    return _datetime.datetime.now(_UTC)
 
-    UTC = _UTC()
 
+_deprecated_shims_map: dict[str, t.Callable[..., object] | _datetime.timezone] = {
+    'UTC': _UTC,
+    'utcfromtimestamp': _utcfromtimestamp,
+    'utcnow': _utcnow,
+}
 
-def utcfromtimestamp(timestamp):  # type: (float) -> datetime.datetime
-    """Construct an aware UTC datetime from a POSIX timestamp."""
-    return datetime.datetime.fromtimestamp(timestamp, UTC)
+__all__ = tuple(_deprecated_shims_map)
 
 
-def utcnow():  # type: () -> datetime.datetime
-    """Construct an aware UTC datetime from time.time()."""
-    return datetime.datetime.now(UTC)
+def __getattr__(importable_name: str) -> t.Callable[..., object] | _datetime.timezone:
+    """Inject import-time deprecation warnings.
+
+    Specifically, for ``UTC``, ``utcfromtimestamp()`` and ``utcnow()``.
+    """
+    try:
+        importable = _deprecated_shims_map[importable_name]
+    except KeyError as key_err:
+        raise AttributeError(f"module {__name__!r} has no attribute {key_err}") from None
+
+    deprecate(
+        msg=f'The `ansible.module_utils.compat.datetime.{importable_name}` '
+        'function is deprecated.',
+        version='2.21',
+    )
+
+    return importable

ansible/module_utils/compat/paramiko.py

@@ -2,25 +2,36 @@
 # 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
+from __future__ import annotations as _annotations
 
-import types  # pylint: disable=unused-import
-import warnings
+import warnings as _warnings
 
-PARAMIKO_IMPORT_ERR = None
+from ansible.module_utils.common.warnings import deprecate as _deprecate
+
+_PARAMIKO_IMPORT_ERR = None
 
 try:
-    with warnings.catch_warnings():
+    with _warnings.catch_warnings():
         # Blowfish has been moved, but the deprecated import is used by paramiko versions older than 2.9.5.
         # See: https://github.com/paramiko/paramiko/pull/2039
-        warnings.filterwarnings('ignore', message='Blowfish has been ', category=UserWarning)
+        _warnings.filterwarnings('ignore', message='Blowfish has been ', category=UserWarning)
         # TripleDES has been moved, but the deprecated import is used by paramiko versions older than 3.3.2 and 3.4.1.
         # See: https://github.com/paramiko/paramiko/pull/2421
-        warnings.filterwarnings('ignore', message='TripleDES has been ', category=UserWarning)
-        import paramiko  # pylint: disable=unused-import
+        _warnings.filterwarnings('ignore', message='TripleDES has been ', category=UserWarning)
+        import paramiko as _paramiko
 # paramiko and gssapi are incompatible and raise AttributeError not ImportError
 # When running in FIPS mode, cryptography raises InternalError
 # https://bugzilla.redhat.com/show_bug.cgi?id=1778939
 except Exception as err:
-    paramiko = None  # type: types.ModuleType | None  # type: ignore[no-redef]
-    PARAMIKO_IMPORT_ERR = err
+    _paramiko = None  # type: ignore[no-redef]
+    _PARAMIKO_IMPORT_ERR = err
+
+
+def __getattr__(name: str) -> object:
+    """Dynamic lookup to issue deprecation warnings for external import of deprecated items."""
+    if (res := globals().get(f'_{name}', ...)) is not ...:
+        _deprecate(f'The {name!r} compat import is deprecated.', version='2.21')
+
+        return res
+
+    raise AttributeError(name)

ansible/module_utils/compat/typing.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 # catch *all* exceptions to prevent type annotation support module bugs causing runtime failures
 # (eg, https://github.com/ansible/ansible/issues/77857)
 
+TYPE_CHECKING = False
+
 try:
     from typing_extensions import *
 except Exception:  # pylint: disable=broad-except
@@ -17,8 +19,7 @@ except Exception:  # pylint: disable=broad-except
     pass
 
 
-try:
-    cast  # type: ignore[used-before-def]
-except NameError:
-    def cast(typ, val):  # type: ignore[no-redef]
-        return val
+# this import and patch occur after typing_extensions/typing imports since the presence of those modules affects dataclasses behavior
+from .._internal._patches import _dataclass_annotation_patch
+
+_dataclass_annotation_patch.DataclassesIsTypePatch.patch()