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

ansible/utils/encrypt.py

@@ -5,25 +5,31 @@ from __future__ import annotations
 
 import random
 import string
+import warnings
 
 from collections import namedtuple
 
 from ansible import constants as C
 from ansible.errors import AnsibleError, AnsibleAssertionError
-from ansible.module_utils.six import text_type
 from ansible.module_utils.common.text.converters import to_text, to_bytes
 from ansible.utils.display import Display
 
 PASSLIB_E = None
 PASSLIB_AVAILABLE = False
+
 try:
-    import passlib
-    import passlib.hash
-    from passlib.utils.handlers import HasRawSalt, PrefixWrapper
-    try:
-        from passlib.utils.binary import bcrypt64
-    except ImportError:
-        from passlib.utils import bcrypt64
+    # deprecated: description='warning suppression only required for Python 3.12 and earlier' python_version='3.12'
+    with warnings.catch_warnings():
+        warnings.filterwarnings('ignore', message="'crypt' is deprecated and slated for removal in Python 3.13", category=DeprecationWarning)
+
+        import passlib
+        import passlib.hash
+        from passlib.utils.handlers import HasRawSalt, PrefixWrapper
+        try:
+            from passlib.utils.binary import bcrypt64
+        except ImportError:
+            from passlib.utils import bcrypt64
+
     PASSLIB_AVAILABLE = True
 except Exception as e:
     PASSLIB_E = e
@@ -37,14 +43,14 @@ DEFAULT_PASSWORD_LENGTH = 20
 
 
 def random_password(length=DEFAULT_PASSWORD_LENGTH, chars=C.DEFAULT_PASSWORD_CHARS, seed=None):
-    '''Return a random password string of length containing only chars
+    """Return a random password string of length containing only chars
 
     :kwarg length: The number of characters in the new password.  Defaults to 20.
     :kwarg chars: The characters to choose from.  The default is all ascii
         letters, ascii digits, and these symbols ``.,:-_``
-    '''
-    if not isinstance(chars, text_type):
-        raise AnsibleAssertionError('%s (%s) is not a text_type' % (chars, type(chars)))
+    """
+    if not isinstance(chars, str):
+        raise AnsibleAssertionError(f'{chars=!r} ({type(chars)}) is not a {type(str)}.')
 
     if seed is None:
         random_generator = random.SystemRandom()
@@ -80,13 +86,14 @@ class PasslibHash(BaseHash):
         super(PasslibHash, self).__init__(algorithm)
 
         if not PASSLIB_AVAILABLE:
-            raise AnsibleError("passlib must be installed and usable to hash with '%s'" % algorithm, orig_exc=PASSLIB_E)
+            raise AnsibleError(f"The passlib Python package must be installed to hash with the {algorithm!r} algorithm.") from PASSLIB_E
+
         display.vv("Using passlib to hash input with '%s'" % algorithm)
 
         try:
             self.crypt_algo = getattr(passlib.hash, algorithm)
         except Exception:
-            raise AnsibleError("passlib does not support '%s' algorithm" % algorithm)
+            raise AnsibleError(f"Installed passlib version {passlib.__version__} does not support the {algorithm!r} algorithm.") from None
 
     def hash(self, secret, salt=None, salt_size=None, rounds=None, ident=None):
         salt = self._clean_salt(salt)
@@ -150,15 +157,15 @@ class PasslibHash(BaseHash):
             elif hasattr(self.crypt_algo, 'encrypt'):
                 result = self.crypt_algo.encrypt(secret, **settings)
             else:
-                raise AnsibleError("installed passlib version %s not supported" % passlib.__version__)
-        except ValueError as e:
-            raise AnsibleError("Could not hash the secret.", orig_exc=e)
+                raise ValueError(f"Installed passlib version {passlib.__version__} is not supported.")
+        except ValueError as ex:
+            raise AnsibleError("Could not hash the secret.") from ex
 
         # passlib.hash should always return something or raise an exception.
         # Still ensure that there is always a result.
         # Otherwise an empty password might be assumed by some modules, like the user module.
         if not result:
-            raise AnsibleError("failed to hash with algorithm '%s'" % self.algorithm)
+            raise AnsibleError(f"Failed to hash with passlib using the {self.algorithm!r} algorithm.")
 
         # Hashes from passlib.hash should be represented as ascii strings of hex
         # digits so this should not traceback.  If it's not representable as such
@@ -175,4 +182,5 @@ def passlib_or_crypt(secret, algorithm, salt=None, salt_size=None, rounds=None,
 def do_encrypt(result, encrypt, salt_size=None, salt=None, ident=None, rounds=None):
     if PASSLIB_AVAILABLE:
         return PasslibHash(encrypt).hash(result, salt=salt, salt_size=salt_size, rounds=rounds, ident=ident)
-    raise AnsibleError("Unable to encrypt nor hash, passlib must be installed", orig_exc=PASSLIB_E)
+
+    raise AnsibleError("Unable to encrypt nor hash, passlib must be installed.") from PASSLIB_E

ansible/utils/fqcn.py

@@ -18,11 +18,11 @@ from __future__ import annotations
 
 
 def add_internal_fqcns(names):
-    '''
+    """
     Given a sequence of action/module names, returns a list of these names
     with the same names with the prefixes `ansible.builtin.` and
     `ansible.legacy.` added for all names that are not already FQCNs.
-    '''
+    """
     result = []
     for name in names:
         result.append(name)

ansible/utils/galaxy.py

@@ -57,8 +57,8 @@ def scm_archive_resource(src, scm='git', name=None, version='HEAD', keep_scm_met
 
     try:
         scm_path = get_bin_path(scm)
-    except (ValueError, OSError, IOError):
-        raise AnsibleError("could not find/use %s, it is required to continue with installing %s" % (scm, src))
+    except (ValueError, OSError) as ex:
+        raise AnsibleError(f"Could not find/use {scm!r}, it is required to continue with installing {src!r}.") from ex
 
     tempdir = tempfile.mkdtemp(dir=C.DEFAULT_LOCAL_TMP)
     clone_cmd = [scm_path, 'clone']

ansible/utils/hashing.py

@@ -32,7 +32,7 @@ from ansible.module_utils.common.text.converters import to_bytes
 
 
 def secure_hash_s(data, hash_func=sha1):
-    ''' Return a secure hash hex digest of data. '''
+    """ Return a secure hash hex digest of data. """
 
     digest = hash_func()
     data = to_bytes(data, errors='surrogate_or_strict')
@@ -41,25 +41,23 @@ def secure_hash_s(data, hash_func=sha1):
 
 
 def secure_hash(filename, hash_func=sha1):
-    ''' Return a secure hash hex digest of local file, None if file is not present or a directory. '''
+    """ Return a secure hash hex digest of local file, None if file is not present or a directory. """
 
     if not os.path.exists(to_bytes(filename, errors='surrogate_or_strict')) or os.path.isdir(to_bytes(filename, errors='strict')):
         return None
     digest = hash_func()
     blocksize = 64 * 1024
     try:
-        infile = open(to_bytes(filename, errors='surrogate_or_strict'), 'rb')
-        block = infile.read(blocksize)
-        while block:
-            digest.update(block)
+        with open(filename, 'rb') as infile:
             block = infile.read(blocksize)
-        infile.close()
-    except IOError as e:
-        raise AnsibleError("error while accessing the file %s, error was: %s" % (filename, e))
+            while block:
+                digest.update(block)
+                block = infile.read(blocksize)
+    except OSError as ex:
+        raise AnsibleError(f"Error while accessing the file {filename!r}.") from ex
     return digest.hexdigest()
 
 
-# The checksum algorithm must match with the algorithm in ShellModule.checksum() method
 checksum = secure_hash
 checksum_s = secure_hash_s
 

ansible/utils/helpers.py

@@ -21,10 +21,10 @@ from ansible.module_utils.six import string_types
 
 
 def pct_to_int(value, num_items, min_value=1):
-    '''
+    """
     Converts a given value to a percentage if specified as "x%",
     otherwise converts the given value to an integer.
-    '''
+    """
     if isinstance(value, string_types) and value.endswith('%'):
         value_pct = int(value.replace("%", ""))
         return int((value_pct / 100.0) * num_items) or min_value

ansible/utils/listify.py

@@ -14,12 +14,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
 from __future__ import annotations
 
 from collections.abc import Iterable
 
-from ansible.module_utils.six import string_types
 from ansible.utils.display import Display
 
 display = Display()
@@ -27,14 +25,18 @@ display = Display()
 __all__ = ['listify_lookup_plugin_terms']
 
 
-def listify_lookup_plugin_terms(terms, templar, fail_on_undefined=True, convert_bare=False):
+def listify_lookup_plugin_terms(terms, templar=None, fail_on_undefined=True):
+    # deprecated: description="Calling listify_lookup_plugin_terms function is not necessary; the function should be deprecated." core_version="2.23"
+    # display.deprecated(
+    #     msg='The "listify_lookup_plugin_terms" function is not required for lookup terms to be templated.',
+    #     version='2.27',
+    #     help_text='If needed, implement custom `strip` or list-wrapping in the caller.',
+    # )
 
-    if isinstance(terms, string_types):
-        terms = templar.template(terms.strip(), convert_bare=convert_bare, fail_on_undefined=fail_on_undefined)
-    else:
-        terms = templar.template(terms, fail_on_undefined=fail_on_undefined)
+    if isinstance(terms, str):
+        terms = terms.strip()
 
-    if isinstance(terms, string_types) or not isinstance(terms, Iterable):
+    if isinstance(terms, str) or not isinstance(terms, Iterable):
         terms = [terms]
 
     return terms

ansible/utils/lock.py

@@ -7,7 +7,7 @@ from functools import wraps
 
 
 def lock_decorator(attr='missing_lock_attr', lock=None):
-    '''This decorator is a generic implementation that allows you
+    """This decorator is a generic implementation that allows you
     to either use a pre-defined instance attribute as the location
     of the lock, or to explicitly pass a lock object.
 
@@ -25,7 +25,7 @@ def lock_decorator(attr='missing_lock_attr', lock=None):
 
         @lock_decorator(lock=threading.Lock())
         def some_method(...):
-    '''
+    """
     def outer(func):
         @wraps(func)
         def inner(*args, **kwargs):

ansible/utils/path.py

@@ -19,16 +19,15 @@ from __future__ import annotations
 import os
 import shutil
 
-from errno import EEXIST
 from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_text
 
 
 __all__ = ['unfrackpath', 'makedirs_safe']
 
 
 def unfrackpath(path, follow=True, basedir=None):
-    '''
+    """
     Returns a path that is free of symlinks (if follow=True), environment variables, relative path traversals and symbols (~)
 
     :arg path: A byte or text string representing a path to be canonicalized
@@ -44,7 +43,7 @@ def unfrackpath(path, follow=True, basedir=None):
 
     example::
         '$HOME/../../var/mail' becomes '/var/spool/mail'
-    '''
+    """
 
     b_basedir = to_bytes(basedir, errors='surrogate_or_strict', nonstring='passthru')
 
@@ -65,7 +64,7 @@ def unfrackpath(path, follow=True, basedir=None):
 
 
 def makedirs_safe(path, mode=None):
-    '''
+    """
     A *potentially insecure* way to ensure the existence of a directory chain. The "safe" in this function's name
     refers only to its ability to ignore `EEXIST` in the case of multiple callers operating on the same part of
     the directory chain. This function is not safe to use under world-writable locations when the first level of the
@@ -77,19 +76,18 @@ def makedirs_safe(path, mode=None):
     :kwarg mode: If given, the mode to set the directory to
     :raises AnsibleError: If the directory cannot be created and does not already exist.
     :raises UnicodeDecodeError: if the path is not decodable in the utf-8 encoding.
-    '''
+    """
 
     rpath = unfrackpath(path)
     b_rpath = to_bytes(rpath)
     if not os.path.exists(b_rpath):
         try:
             if mode:
-                os.makedirs(b_rpath, mode)
+                os.makedirs(b_rpath, mode, exist_ok=True)
             else:
-                os.makedirs(b_rpath)
-        except OSError as e:
-            if e.errno != EEXIST:
-                raise AnsibleError("Unable to create local directories(%s): %s" % (to_native(rpath), to_native(e)))
+                os.makedirs(b_rpath, exist_ok=True)
+        except OSError as ex:
+            raise AnsibleError(f"Unable to create local directories {rpath!r}.") from ex
 
 
 def basedir(source):
@@ -104,7 +102,7 @@ def basedir(source):
         dname = os.path.dirname(source)
 
     if dname:
-        # don't follow symlinks for basedir, enables source re-use
+        # don't follow symlinks for basedir, enables source reuse
         dname = os.path.abspath(dname)
 
     return to_text(dname, errors='surrogate_or_strict')

ansible/utils/plugin_docs.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 from collections.abc import MutableMapping, MutableSet, MutableSequence
 from pathlib import Path
 
+import yaml
+
 from ansible import constants as C
 from ansible.release import __version__ as ansible_version
 from ansible.errors import AnsibleError, AnsibleParserError, AnsiblePluginNotFound
@@ -14,6 +16,7 @@ from ansible.module_utils.common.text.converters import to_native
 from ansible.parsing.plugin_docs import read_docstring
 from ansible.parsing.yaml.loader import AnsibleLoader
 from ansible.utils.display import Display
+from ansible._internal._datatag import _tags
 
 display = Display()
 
@@ -151,7 +154,8 @@ def add_fragments(doc, filename, fragment_loader, is_module=False):
             unknown_fragments.append(fragment_slug)
             continue
 
-        fragment_yaml = getattr(fragment_class, fragment_var, None)
+        # trust-tagged source propagates to loaded values; expressions and templates in config require trust
+        fragment_yaml = _tags.TrustedAsTemplate().tag(getattr(fragment_class, fragment_var, None))
         if fragment_yaml is None:
             if fragment_var != 'DOCUMENTATION':
                 # if it's asking for something specific that's missing, that's an error
@@ -160,7 +164,7 @@ def add_fragments(doc, filename, fragment_loader, is_module=False):
             else:
                 fragment_yaml = '{}'  # TODO: this is still an error later since we require 'options' below...
 
-        fragment = AnsibleLoader(fragment_yaml, file_name=filename).get_single_data()
+        fragment = yaml.load(_tags.Origin(path=filename).tag(fragment_yaml), Loader=AnsibleLoader)
 
         real_fragment_name = getattr(fragment_class, 'ansible_name')
         real_collection_name = '.'.join(real_fragment_name.split('.')[0:2]) if '.' in real_fragment_name else ''
@@ -292,7 +296,7 @@ def _find_adjacent(path, plugin, extensions):
 
 
 def find_plugin_docfile(plugin, plugin_type, loader):
-    '''  if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding 'sidecar' file for docs '''
+    """  if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding 'sidecar' file for docs """
 
     context = loader.find_plugin_with_context(plugin, ignore_deprecated=False, check_aliases=True)
     if (not context or not context.resolved) and plugin_type in ('filter', 'test'):
@@ -318,8 +322,6 @@ def find_plugin_docfile(plugin, plugin_type, loader):
 
 def get_plugin_docs(plugin, plugin_type, loader, fragment_loader, verbose):
 
-    docs = []
-
     # find plugin doc file, if it doesn't exist this will throw error, we let it through
     # can raise exception and short circuit when 'not found'
     filename, context = find_plugin_docfile(plugin, plugin_type, loader)
@@ -327,8 +329,8 @@ def get_plugin_docs(plugin, plugin_type, loader, fragment_loader, verbose):
 
     try:
         docs = get_docstring(filename, fragment_loader, verbose=verbose, collection_name=collection_name, plugin_type=plugin_type)
-    except Exception as e:
-        raise AnsibleParserError('%s did not contain a DOCUMENTATION attribute (%s)' % (plugin, filename), orig_exc=e)
+    except Exception as ex:
+        raise AnsibleParserError(f'{plugin_type} plugin {plugin!r} did not contain a DOCUMENTATION attribute in {filename!r}.') from ex
 
     # no good? try adjacent
     if not docs[0]:
@@ -338,15 +340,15 @@ def get_plugin_docs(plugin, plugin_type, loader, fragment_loader, verbose):
                 filename = newfile
                 if docs[0] is not None:
                     break
-            except Exception as e:
-                raise AnsibleParserError('Adjacent file %s did not contain a DOCUMENTATION attribute (%s)' % (plugin, filename), orig_exc=e)
+            except Exception as ex:
+                raise AnsibleParserError(f'{plugin_type} plugin {plugin!r} adjacent file did not contain a DOCUMENTATION attribute in {filename!r}.') from ex
 
     # add extra data to docs[0] (aka 'DOCUMENTATION')
     if docs[0] is None:
-        raise AnsibleParserError('No documentation available for %s (%s)' % (plugin, filename))
-    else:
-        docs[0]['filename'] = filename
-        docs[0]['collection'] = collection_name
-        docs[0]['plugin_name'] = context.resolved_fqcn
+        raise AnsibleParserError(f'No documentation available for {plugin_type} plugin {plugin!r} in {filename!r}.')
+
+    docs[0]['filename'] = filename
+    docs[0]['collection'] = collection_name
+    docs[0]['plugin_name'] = context.resolved_fqcn
 
     return docs

ansible/utils/py3compat.py

@@ -6,7 +6,6 @@
 
 from __future__ import annotations
 
-import inspect
 import os
 
 from ansible.utils.display import Display
@@ -19,14 +18,10 @@ def __getattr__(name):
     if name != 'environ':
         raise AttributeError(name)
 
-    caller = inspect.stack()[1]
-
     display.deprecated(
-        (
-            'ansible.utils.py3compat.environ is deprecated in favor of os.environ. '
-            f'Accessed by {caller.filename} line number {caller.lineno}'
-        ),
+        msg='`ansible.utils.py3compat.environ` is deprecated.',
         version='2.20',
+        help_text='Use `os.environ` from the Python standard library instead.',
     )
 
     return os.environ

ansible/utils/sentinel.py

@@ -1,66 +1,8 @@
-# Copyright (c) 2019 Ansible Project
+# -*- coding: utf-8 -*-
+# Copyright: Contributors to the 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
+# For Backward compatibility
+from ansible.module_utils.common.sentinel import Sentinel  # pylint: disable=unused-import

ansible/utils/singleton.py

@@ -11,6 +11,8 @@ class Singleton(type):
     functionality.  If an instance of the class exists, it's returned,
     otherwise a single instance is instantiated and returned.
     """
+
+    # FIXME: object identity/singleton-ness does not appear to survive pickle roundtrip (eg, copy.copy, copy.deepcopy), implement __reduce_ex__ and __copy__?
     def __init__(cls, name, bases, dct):
         super(Singleton, cls).__init__(name, bases, dct)
         cls.__instance = None

ansible/utils/ssh_functions.py

@@ -22,7 +22,7 @@ import subprocess
 
 from ansible import constants as C
 from ansible.module_utils.common.text.converters import to_bytes
-from ansible.module_utils.compat.paramiko import paramiko
+from ansible.module_utils.compat.paramiko import _paramiko as paramiko
 from ansible.utils.display import Display
 
 display = Display()
@@ -56,7 +56,11 @@ def set_default_transport():
 
     # deal with 'smart' connection .. one time ..
     if C.DEFAULT_TRANSPORT == 'smart':
-        display.deprecated("The 'smart' option for connections is deprecated. Set the connection plugin directly instead.", version='2.20')
+        display.deprecated(
+            msg="The `smart` option for connections is deprecated.",
+            version="2.20",
+            help_text="Set the connection plugin directly instead.",
+        )
 
         # see if SSH can support ControlPersist if not use paramiko
         if not check_for_controlpersist('ssh') and paramiko is not None: