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

ansible/module_utils/common/respawn.py

@@ -3,11 +3,14 @@
 
 from __future__ import annotations
 
+import dataclasses
 import os
 import pathlib
 import subprocess
 import sys
+import typing as t
 
+from ansible.module_utils._internal import _plugin_exec_context
 from ansible.module_utils.common.text.converters import to_bytes
 
 _ANSIBLE_PARENT_PATH = pathlib.Path(__file__).parents[3]
@@ -17,7 +20,7 @@ def has_respawned():
     return hasattr(sys.modules['__main__'], '_respawned')
 
 
-def respawn_module(interpreter_path):
+def respawn_module(interpreter_path) -> t.NoReturn:
     """
     Respawn the currently-running Ansible Python module under the specified Python interpreter.
 
@@ -55,10 +58,13 @@ def probe_interpreters_for_module(interpreter_paths, module_name):
     :arg interpreter_paths: iterable of paths to Python interpreters. The paths will be probed
     in order, and the first path that exists and can successfully import the named module will
     be returned (or ``None`` if probing fails for all supplied paths).
-    :arg module_name: fully-qualified Python module name to probe for (eg, ``selinux``)
+    :arg module_name: fully-qualified Python module name to probe for (for example, ``selinux``)
     """
     PYTHONPATH = os.getenv('PYTHONPATH', '')
-    env = os.environ | {'PYTHONPATH': f'{_ANSIBLE_PARENT_PATH}:{PYTHONPATH}'.rstrip(': ')}
+    env = os.environ.copy()
+    env.update({
+        'PYTHONPATH': f'{_ANSIBLE_PARENT_PATH}:{PYTHONPATH}'.rstrip(': ')
+    })
     for interpreter_path in interpreter_paths:
         if not os.path.exists(interpreter_path):
             continue
@@ -80,29 +86,45 @@ def probe_interpreters_for_module(interpreter_paths, module_name):
 
 
 def _create_payload():
+    # FIXME: move this into _ansiballz and skip the template
     from ansible.module_utils import basic
-    smuggled_args = getattr(basic, '_ANSIBLE_ARGS')
-    if not smuggled_args:
-        raise Exception('unable to access ansible.module_utils.basic._ANSIBLE_ARGS (not launched by AnsiballZ?)')
+
     module_fqn = sys.modules['__main__']._module_fqn
     modlib_path = sys.modules['__main__']._modlib_path
-    respawn_code_template = '''
-import runpy
-import sys
-
-module_fqn = {module_fqn!r}
-modlib_path = {modlib_path!r}
-smuggled_args = {smuggled_args!r}
 
+    respawn_code_template = """
 if __name__ == '__main__':
-    sys.path.insert(0, modlib_path)
+    import runpy
+    import sys
 
-    from ansible.module_utils import basic
-    basic._ANSIBLE_ARGS = smuggled_args
+    json_params = {json_params!r}
+    profile = {profile!r}
+    plugin_info_dict = {plugin_info_dict!r}
+    module_fqn = {module_fqn!r}
+    modlib_path = {modlib_path!r}
 
-    runpy.run_module(module_fqn, init_globals=dict(_respawned=True), run_name='__main__', alter_sys=True)
-    '''
+    sys.path.insert(0, modlib_path)
 
-    respawn_code = respawn_code_template.format(module_fqn=module_fqn, modlib_path=modlib_path, smuggled_args=smuggled_args.strip())
+    from ansible.module_utils._internal import _ansiballz
+
+    _ansiballz.run_module(
+        json_params=json_params,
+        profile=profile,
+        plugin_info_dict=plugin_info_dict,
+        module_fqn=module_fqn,
+        modlib_path=modlib_path,
+        init_globals=dict(_respawned=True),
+    )
+"""
+
+    plugin_info = _plugin_exec_context.PluginExecContext.get_current_plugin_info()
+
+    respawn_code = respawn_code_template.format(
+        json_params=basic._ANSIBLE_ARGS,
+        profile=basic._ANSIBLE_PROFILE,
+        plugin_info_dict=dataclasses.asdict(plugin_info),
+        module_fqn=module_fqn,
+        modlib_path=modlib_path,
+    )
 
     return respawn_code

ansible/module_utils/common/sentinel.py

@@ -0,0 +1,66 @@
+# Copyright (c) 2019 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+
+class Sentinel:
+    """
+    Object which can be used to mark whether an entry as being special
+
+    A sentinel value demarcates a value or marks an entry as having a special meaning.  In C, the
+    Null byte is used as a sentinel for the end of a string.  In Python, None is often used as
+    a Sentinel in optional parameters to mean that the parameter was not set by the user.
+
+    You should use None as a Sentinel value any Python code where None is not a valid entry.  If
+    None is a valid entry, though, then you need to create a different value, which is the purpose
+    of this class.
+
+    Example of using Sentinel as a default parameter value::
+
+        def confirm_big_red_button(tristate=Sentinel):
+            if tristate is Sentinel:
+                print('You must explicitly press the big red button to blow up the base')
+            elif tristate is True:
+                print('Countdown to destruction activated')
+            elif tristate is False:
+                print('Countdown stopped')
+            elif tristate is None:
+                print('Waiting for more input')
+
+    Example of using Sentinel to tell whether a dict which has a default value has been changed::
+
+        values = {'one': Sentinel, 'two': Sentinel}
+        defaults = {'one': 1, 'two': 2}
+
+        # [.. Other code which does things including setting a new value for 'one' ..]
+        values['one'] = None
+        # [..]
+
+        print('You made changes to:')
+        for key, value in values.items():
+            if value is Sentinel:
+                continue
+            print('%s: %s' % (key, value)
+    """
+
+    def __new__(cls):
+        """
+        Return the cls itself.  This makes both equality and identity True for comparing the class
+        to an instance of the class, preventing common usage errors.
+
+        Preferred usage::
+
+            a = Sentinel
+            if a is Sentinel:
+                print('Sentinel value')
+
+        However, these are True as well, eliminating common usage errors::
+
+            if Sentinel is Sentinel():
+                print('Sentinel value')
+
+            if Sentinel == Sentinel():
+                print('Sentinel value')
+        """
+        return cls

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-RELEASE: 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-RELEASE: 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-RELEASE: 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-RELEASE: 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,99 @@
 # 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 datetime as _datetime
+import typing as _t
 
-_global_warnings = []
-_global_deprecations = []
+from ansible.module_utils._internal import _traceback, _plugin_exec_context
+from ansible.module_utils.common import messages as _messages
+from ansible.module_utils import _internal
 
+_UNSET = _t.cast(_t.Any, object())
 
-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) -> None:
+    """Record a warning to be returned with the module result."""
+    # DTFIX-RELEASE: shim to controller display warning like `deprecate`
+    _global_warnings[_messages.WarningSummary(
+        details=(
+            _messages.Detail(msg=warning),
+        ),
+        formatted_traceback=_traceback.maybe_capture_traceback(_traceback.TracebackEvent.WARNING),
+    )] = None
 
-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))
 
+def deprecate(
+    msg: str,
+    version: str | None = None,
+    date: str | _datetime.date | None = None,
+    collection_name: str | None = _UNSET,
+    *,
+    help_text: str | None = None,
+    obj: object | None = None,
+) -> None:
+    """
+    Record a deprecation warning to be returned with the module result.
+    The `obj` argument is only useful in a controller context; it is ignored for target-side callers.
+    """
+    if isinstance(date, _datetime.date):
+        date = str(date)
 
-def get_warning_messages():
-    """Return a tuple of warning messages accumulated over this run"""
-    return tuple(_global_warnings)
+    # deprecated: description='enable the deprecation message for collection_name' core_version='2.23'
+    # if collection_name is not _UNSET:
+    #     deprecate('The `collection_name` argument to `deprecate` is deprecated.', version='2.27')
 
+    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,
+        )
 
-def get_deprecation_messages():
-    """Return a tuple of deprecations accumulated over this run"""
-    return tuple(_global_deprecations)
+        return
+
+    _global_deprecations[_messages.DeprecationSummary(
+        details=(
+            _messages.Detail(msg=msg, help_text=help_text),
+        ),
+        formatted_traceback=_traceback.maybe_capture_traceback(_traceback.TracebackEvent.DEPRECATED),
+        version=version,
+        date=date,
+        plugin=_plugin_exec_context.PluginExecContext.get_current_plugin_info(),
+    )] = None
+
+
+def get_warning_messages() -> tuple[str, ...]:
+    """Return a tuple of warning messages accumulated over this run."""
+    # DTFIX-RELEASE: add future deprecation comment
+    return tuple(item._format() for item in _global_warnings)
+
+
+_DEPRECATION_MESSAGE_KEYS = frozenset({'msg', 'date', 'version', 'collection_name'})
+
+
+def get_deprecation_messages() -> tuple[dict[str, _t.Any], ...]:
+    """Return a tuple of deprecation warning messages accumulated over this run."""
+    # DTFIX-RELEASE: add future deprecation comment
+    return tuple({key: value for key, value in item._as_simple_dict().items() if key in _DEPRECATION_MESSAGE_KEYS} 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-deplicated storage of acculumated warnings for the current module run."""
+
+_global_deprecations: dict[_messages.DeprecationSummary, object] = {}
+"""Global, ordered, de-deplicated storage of acculumated 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-RELEASE: 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 intead 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]