ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__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/arg_spec.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 from copy import deepcopy
 
+from ansible.module_utils.datatag import deprecator_from_collection_name
 from ansible.module_utils.common.parameters import (
     _ADDITIONAL_CHECKS,
     _get_legal_inputs,
@@ -300,9 +301,13 @@ class ModuleArgumentSpecValidator(ArgumentSpecValidator):
         result = super(ModuleArgumentSpecValidator, self).validate(parameters)
 
         for d in result._deprecations:
-            deprecate(d['msg'],
-                      version=d.get('version'), date=d.get('date'),
-                      collection_name=d.get('collection_name'))
+            # DTFIX-FUTURE: pass an actual deprecator instead of one derived from collection_name
+            deprecate(  # pylint: disable=ansible-deprecated-date-not-permitted,ansible-deprecated-unnecessary-collection-name
+                msg=d['msg'],
+                version=d.get('version'),
+                date=d.get('date'),
+                deprecator=deprecator_from_collection_name(d.get('collection_name')),
+            )
 
         for w in result._warnings:
             warn('Both option {option} and its alias {alias} are set.'.format(option=w['option'], alias=w['alias']))

ansible/module_utils/common/collections.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 
+from ansible.module_utils.common import warnings as _warnings
 from ansible.module_utils.six import binary_type, text_type
 from ansible.module_utils.six.moves.collections_abc import Hashable, Mapping, MutableMapping, Sequence  # pylint: disable=unused-import
 
@@ -66,8 +67,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):
@@ -103,6 +103,11 @@ def count(seq):
     code is run on Python 2.6.* where collections.Counter is not available. It should be
     deprecated and replaced when support for Python < 2.7 is dropped.
     """
+    _warnings.deprecate(
+        msg="The `ansible.module_utils.common.collections.count` function is deprecated.",
+        version="2.23",
+        help_text="Use `collections.Counter` from the Python standard library instead.",
+    )
     if not is_iterable(seq):
         raise Exception('Argument provided  is not an iterable')
     counters = dict()

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-FUTURE: 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-FUTURE: 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/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,12 +24,11 @@ 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.",
             version="2.21",
-            collection_name="ansible.builtin",
         )
 
     paths = []

ansible/module_utils/common/respawn.py

@@ -7,8 +7,10 @@ import os
 import pathlib
 import subprocess
 import sys
+import typing as t
 
 from ansible.module_utils.common.text.converters import to_bytes
+from ansible.module_utils._internal._ansiballz import _respawn
 
 _ANSIBLE_PARENT_PATH = pathlib.Path(__file__).parents[3]
 
@@ -17,7 +19,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.
 
@@ -38,7 +40,7 @@ def respawn_module(interpreter_path):
         raise Exception('module has already been respawned')
 
     # FUTURE: we need a safe way to log that a respawn has occurred for forensic/debug purposes
-    payload = _create_payload()
+    payload = _respawn.create_payload()
     stdin_read, stdin_write = os.pipe()
     os.write(stdin_write, to_bytes(payload))
     os.close(stdin_write)
@@ -55,10 +57,15 @@ 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
@@ -77,32 +84,3 @@ def probe_interpreters_for_module(interpreter_paths, module_name):
             continue
 
     return None
-
-
-def _create_payload():
-    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}
-
-if __name__ == '__main__':
-    sys.path.insert(0, modlib_path)
-
-    from ansible.module_utils import basic
-    basic._ANSIBLE_ARGS = smuggled_args
-
-    runpy.run_module(module_fqn, init_globals=dict(_respawned=True), run_name='__main__', alter_sys=True)
-    '''
-
-    respawn_code = respawn_code_template.format(module_fqn=module_fqn, modlib_path=modlib_path, smuggled_args=smuggled_args.strip())
-
-    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