ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__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/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,7 +41,7 @@ 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

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,16 @@ 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):
+    display.deprecated(
+        msg='"listify_lookup_plugin_terms" is obsolete and in most cases unnecessary',
+        version='2.23',
+    )
 
-    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

@@ -28,7 +28,7 @@ __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 +44,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 +65,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,7 +77,7 @@ 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)

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()
 
@@ -160,7 +163,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 +295,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 +321,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 +328,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 +339,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/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()