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

ansible/plugins/action/validate_argument_spec.py

@@ -10,13 +10,13 @@ from ansible.utils.vars import combine_vars
 
 
 class ActionModule(ActionBase):
-    ''' Validate an arg spec'''
+    """ Validate an arg spec"""
 
     TRANSFERS_FILES = False
     _requires_connection = False
 
     def get_args_from_task_vars(self, argument_spec, task_vars):
-        '''
+        """
         Get any arguments that may come from `task_vars`.
 
         Expand templated variables so we can validate the actual values.
@@ -25,7 +25,7 @@ class ActionModule(ActionBase):
         :param task_vars: A dict of task variables.
 
         :returns: A dict of values that can be validated against the arg spec.
-        '''
+        """
         args = {}
 
         for argument_name, argument_attrs in argument_spec.items():
@@ -35,7 +35,7 @@ class ActionModule(ActionBase):
         return args
 
     def run(self, tmp=None, task_vars=None):
-        '''
+        """
         Validate an argument specification against a provided set of data.
 
         The `validate_argument_spec` module expects to receive the arguments:
@@ -48,7 +48,7 @@ class ActionModule(ActionBase):
         :param task_vars: A dict of task variables.
         :return: An action result dict, including a 'argument_errors' key with a
             list of validation errors found.
-        '''
+        """
         if task_vars is None:
             task_vars = dict()
 

ansible/plugins/action/wait_for_connection.py

@@ -76,7 +76,7 @@ class ActionModule(ActionBase):
         del tmp  # tmp no longer has any effect
 
         def ping_module_test(connect_timeout):
-            ''' Test ping module, if available '''
+            """ Test ping module, if available """
             display.vvv("wait_for_connection: attempting ping module test")
             # re-run interpreter discovery if we ran it in the first iteration
             if self._discovered_interpreter_key:

ansible/plugins/become/__init__.py

@@ -3,6 +3,7 @@
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 from __future__ import annotations
 
+import re
 import shlex
 
 from abc import abstractmethod
@@ -13,10 +14,11 @@ from gettext import dgettext
 from ansible.errors import AnsibleError
 from ansible.module_utils.common.text.converters import to_bytes
 from ansible.plugins import AnsiblePlugin
+from ansible.utils import display as _display
 
 
 def _gen_id(length=32):
-    ''' return random string used to identify the current privilege escalation '''
+    """ return random string used to identify the current privilege escalation """
     return ''.join(choice(ascii_lowercase) for x in range(length))
 
 
@@ -32,6 +34,9 @@ class BecomeBase(AnsiblePlugin):
     # plugin requires a tty, i.e su
     require_tty = False
 
+    # plugin allows for pipelining execution
+    pipelining = True
+
     # prompt to match
     prompt = ''
 
@@ -53,11 +58,11 @@ class BecomeBase(AnsiblePlugin):
 
             return getattr(playcontext, option, None)
 
-    def expect_prompt(self):
+    def expect_prompt(self) -> bool:
         """This function assists connection plugins in determining if they need to wait for
         a prompt. Both a prompt and a password are required.
         """
-        return self.prompt and self.get_option('become_pass')
+        return bool(self.prompt and self.get_option('become_pass'))
 
     def _build_success_command(self, cmd, shell, noexe=False):
         if not all((cmd, shell, self.success)):
@@ -65,9 +70,8 @@ class BecomeBase(AnsiblePlugin):
 
         try:
             cmd = shlex.quote('%s %s %s %s' % (shell.ECHO, self.success, shell.COMMAND_SEP, cmd))
-        except AttributeError:
-            # TODO: This should probably become some more robust functionality used to detect incompat
-            raise AnsibleError('The %s shell family is incompatible with the %s become plugin' % (shell.SHELL_FAMILY, self.name))
+        except AttributeError as ex:
+            raise AnsibleError(f'The {shell._load_name!r} shell plugin does not support become. It is missing the {ex.name!r} attribute.')
         exe = getattr(shell, 'executable', None)
         if exe and not noexe:
             cmd = '%s -c %s' % (exe, cmd)
@@ -78,19 +82,38 @@ class BecomeBase(AnsiblePlugin):
         self._id = _gen_id()
         self.success = 'BECOME-SUCCESS-%s' % self._id
 
+    def strip_become_prompt(self, data: bytes) -> bytes:
+        """
+        Strips the first found configured become prompt from `data`, trailing whitespace and anything that precedes the prompt, then returns the result.
+        If no prompt is expected, or the prompt is not `str` or `bytes`, `data` will be returned as-is.
+        """
+        if not self.prompt or not isinstance(self.prompt, (str, bytes)) or not self.expect_prompt():
+            return data
+
+        return self._strip_through_prefix(self.prompt, data)
+
+    def strip_become_success(self, data: bytes) -> bytes:
+        """Strips the first found success marker from `data`, trailing whitespace and anything that precedes the success marker, then returns the result."""
+        return self._strip_through_prefix(self.success, data)
+
+    @staticmethod
+    def _strip_through_prefix(match: str | bytes, data: bytes) -> bytes:
+        """Strips the first occurrence of `match` from `data`, trailing whitespace and anything that precedes `match`, then returns the result."""
+        return re.sub(br'^.*?' + re.escape(to_bytes(match)) + br'\s*', b'', data, count=1, flags=re.DOTALL)
+
     def check_success(self, b_output):
         b_success = to_bytes(self.success)
         return any(b_success in l.rstrip() for l in b_output.splitlines(True))
 
     def check_password_prompt(self, b_output):
-        ''' checks if the expected password prompt exists in b_output '''
+        """ checks if the expected password prompt exists in b_output """
         if self.prompt:
             b_prompt = to_bytes(self.prompt).strip()
             return any(l.strip().startswith(b_prompt) for l in b_output.splitlines())
         return False
 
     def _check_password_error(self, b_out, msg):
-        ''' returns True/False if domain specific i18n version of msg is found in b_out '''
+        """ returns True/False if domain specific i18n version of msg is found in b_out """
         b_fail = to_bytes(dgettext(self.name, msg))
         return b_fail and b_fail in b_out
 

ansible/plugins/become/runas.py

@@ -61,6 +61,8 @@ DOCUMENTATION = """
         - The Secondary Logon service (seclogon) must be running to use runas
 """
 
+from ansible.errors import AnsibleError
+from ansible.parsing.splitter import split_args
 from ansible.plugins.become import BecomeBase
 
 
@@ -72,3 +74,72 @@ class BecomeModule(BecomeBase):
         # this is a noop, the 'real' runas is implemented
         # inside the windows powershell execution subsystem
         return cmd
+
+    def _build_powershell_wrapper_action(self) -> tuple[str, dict[str, object], dict[str, object]]:
+        # See ansible.executor.powershell.become_wrapper.ps1 for the
+        # parameter names
+        params = {
+            'BecomeUser': self.get_option('become_user'),
+        }
+        secure_params = {}
+
+        password = self.get_option('become_pass')
+        if password:
+            secure_params['BecomePassword'] = password
+
+        flags = self.get_option('become_flags')
+        if flags:
+            split_flags = split_args(flags)
+            for flag in split_flags:
+                if '=' not in flag:
+                    raise ValueError(f"become_flags entry '{flag}' is in an invalid format, must be a key=value pair")
+
+                k, v = flag.split('=', 1)
+
+                param_name, param_value = self._parse_flag(k, v)
+                params[param_name] = param_value
+
+        return 'become_wrapper.ps1', params, secure_params
+
+    def _parse_flag(self, name: str, value: str) -> tuple[str, str]:
+        logon_types = {
+            'interactive': 'Interactive',
+            'network': 'Network',
+            'batch': 'Batch',
+            'service': 'Service',
+            'unlock': 'Unlock',
+            'network_cleartext': 'NetworkCleartext',
+            'new_credentials': 'NewCredentials',
+        }
+        logon_flags = {
+            'none': 'None',
+            'with_profile': 'WithProfile',
+            'netcredentials_only': 'NetCredentialsOnly',
+        }
+
+        match name.lower():
+            case 'logon_type':
+                param_name = 'LogonType'
+                if param_value := logon_types.get(value.lower(), None):
+                    return param_name, param_value
+                else:
+                    raise AnsibleError(f"become_flags logon_type value '{value}' is not valid, valid values are: {', '.join(logon_types.keys())}")
+
+            case 'logon_flags':
+                param_name = 'LogonFlags'
+                flags = value.split(',')
+
+                param_values: list[str] = []
+                for flag in flags:
+                    if not flag:
+                        continue
+
+                    if flag_value := logon_flags.get(flag.lower(), None):
+                        param_values.append(flag_value)
+                    else:
+                        raise AnsibleError(f"become_flags logon_flags value '{flag}' is not valid, valid values are: {', '.join(logon_flags.keys())}")
+
+                return param_name, ", ".join(param_values)
+
+            case _:
+                raise AnsibleError(f"become_flags key '{name}' is not a valid runas flag, must be 'logon_type' or 'logon_flags'")

ansible/plugins/become/su.py

@@ -93,7 +93,7 @@ DOCUMENTATION = """
 import re
 import shlex
 
-from ansible.module_utils.common.text.converters import to_bytes
+from ansible.module_utils.common.text.converters import to_text
 from ansible.plugins.become import BecomeBase
 
 
@@ -101,6 +101,8 @@ class BecomeModule(BecomeBase):
 
     name = 'su'
 
+    pipelining = False
+
     # messages for detecting prompted password issues
     fail = ('Authentication failure',)
 
@@ -139,15 +141,18 @@ class BecomeModule(BecomeBase):
         '口令',
     ]
 
-    def check_password_prompt(self, b_output):
-        ''' checks if the expected password prompt exists in b_output '''
-
+    def check_password_prompt(self, b_output: bytes) -> bool:
+        """ checks if the expected password prompt exists in b_output """
         prompts = self.get_option('prompt_l10n') or self.SU_PROMPT_LOCALIZATIONS
-        b_password_string = b"|".join((br'(\w+\'s )?' + to_bytes(p)) for p in prompts)
+        password_prompt_strings = "|".join(re.escape(p) for p in prompts)
         # Colon or unicode fullwidth colon
-        b_password_string = b_password_string + to_bytes(u' ?(:|：) ?')
-        b_su_prompt_localizations_re = re.compile(b_password_string, flags=re.IGNORECASE)
-        return bool(b_su_prompt_localizations_re.match(b_output))
+        prompt_pattern = rf"(?:{password_prompt_strings})\s*[:：]"
+        match = re.search(prompt_pattern, to_text(b_output), flags=re.IGNORECASE)
+
+        if match:
+            self.prompt = match.group(0)  # preserve the actual matched string so we can scrub the output
+
+        return bool(match)
 
     def build_become_command(self, cmd, shell):
         super(BecomeModule, self).build_become_command(cmd, shell)

ansible/plugins/become/sudo.py

@@ -72,12 +72,25 @@ DOCUMENTATION = """
             ini:
               - section: sudo_become_plugin
                 key: password
+        sudo_chdir:
+            description: Directory to change to before invoking sudo; can avoid permission errors when dropping privileges.
+            type: string
+            required: False
+            version_added: '2.19'
+            vars:
+              - name: ansible_sudo_chdir
+            env:
+              - name: ANSIBLE_SUDO_CHDIR
+            ini:
+              - section: sudo_become_plugin
+                key: chdir
 """
 
 import re
 import shlex
 
 from ansible.plugins.become import BecomeBase
+from ansible.errors import AnsibleError
 
 
 class BecomeModule(BecomeBase):
@@ -117,4 +130,10 @@ class BecomeModule(BecomeBase):
         if user:
             user = '-u %s' % (user)
 
+        if chdir := self.get_option('sudo_chdir'):
+            try:
+                becomecmd = f'{shell.CD} {shlex.quote(chdir)} {shell._SHELL_AND} {becomecmd}'
+            except AttributeError as ex:
+                raise AnsibleError(f'The {shell._load_name!r} shell plugin does not support sudo chdir. It is missing the {ex.name!r} attribute.')
+
         return ' '.join([becomecmd, flags, prompt, user, self._build_success_command(cmd, shell)])

ansible/plugins/cache/__init__.py

@@ -18,18 +18,18 @@
 from __future__ import annotations
 
 import copy
-import errno
 import os
 import tempfile
 import time
+import typing as t
 
 from abc import abstractmethod
-from collections.abc import MutableMapping
+from collections import abc as c
 
 from ansible import constants as C
 from ansible.errors import AnsibleError
 from ansible.module_utils.common.file import S_IRWU_RG_RO
-from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.module_utils.common.text.converters import to_bytes
 from ansible.plugins import AnsiblePlugin
 from ansible.plugins.loader import cache_loader
 from ansible.utils.collection_loader import resource_from_fqcr
@@ -42,37 +42,36 @@ class BaseCacheModule(AnsiblePlugin):
 
     # Backwards compat only.  Just import the global display instead
     _display = display
+    _persistent = True
+    """Plugins that do not persist data between runs can set False to bypass schema-version key munging and JSON serialization wrapper."""
 
-    def __init__(self, *args, **kwargs):
-        super(BaseCacheModule, self).__init__()
-        self.set_options(var_options=args, direct=kwargs)
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__()
 
-    @abstractmethod
-    def get(self, key):
-        pass
+        self.set_options(var_options=args, direct=kwargs)
 
     @abstractmethod
-    def set(self, key, value):
+    def get(self, key: str) -> dict[str, object]:
         pass
 
     @abstractmethod
-    def keys(self):
+    def set(self, key: str, value: dict[str, object]) -> None:
         pass
 
     @abstractmethod
-    def contains(self, key):
+    def keys(self) -> t.Sequence[str]:
         pass
 
     @abstractmethod
-    def delete(self, key):
+    def contains(self, key: object) -> bool:
         pass
 
     @abstractmethod
-    def flush(self):
+    def delete(self, key: str) -> None:
         pass
 
     @abstractmethod
-    def copy(self):
+    def flush(self) -> None:
         pass
 
 
@@ -108,15 +107,15 @@ class BaseFileCacheModule(BaseCacheModule):
         if not os.path.exists(self._cache_dir):
             try:
                 os.makedirs(self._cache_dir)
-            except (OSError, IOError) as e:
-                raise AnsibleError("error in '%s' cache plugin while trying to create cache dir %s : %s" % (self.plugin_name, self._cache_dir, to_bytes(e)))
+            except OSError as ex:
+                raise AnsibleError(f"Error in {self.plugin_name!r} cache plugin while trying to create cache dir {self._cache_dir!r}.") from ex
         else:
             for x in (os.R_OK, os.W_OK, os.X_OK):
                 if not os.access(self._cache_dir, x):
                     raise AnsibleError("error in '%s' cache, configured path (%s) does not have necessary permissions (rwx), disabling plugin" % (
                         self.plugin_name, self._cache_dir))
 
-    def _get_cache_file_name(self, key):
+    def _get_cache_file_name(self, key: str) -> str:
         prefix = self.get_option('_prefix')
         if prefix:
             cachefile = "%s/%s%s" % (self._cache_dir, prefix, key)
@@ -144,11 +143,10 @@ class BaseFileCacheModule(BaseCacheModule):
                 self.delete(key)
                 raise AnsibleError("The cache file %s was corrupt, or did not otherwise contain valid data. "
                                    "It has been removed, so you can re-run your command now." % cachefile)
-            except (OSError, IOError) as e:
-                display.warning("error in '%s' cache plugin while trying to read %s : %s" % (self.plugin_name, cachefile, to_bytes(e)))
+            except FileNotFoundError:
                 raise KeyError
-            except Exception as e:
-                raise AnsibleError("Error while decoding the cache file %s: %s" % (cachefile, to_bytes(e)))
+            except Exception as ex:
+                raise AnsibleError(f"Error while accessing the cache file {cachefile!r}.") from ex
 
         return self._cache.get(key)
 
@@ -161,13 +159,13 @@ class BaseFileCacheModule(BaseCacheModule):
         try:
             try:
                 self._dump(value, tmpfile_path)
-            except (OSError, IOError) as e:
-                display.warning("error in '%s' cache plugin while trying to write to '%s' : %s" % (self.plugin_name, tmpfile_path, to_bytes(e)))
+            except OSError as ex:
+                display.error_as_warning(f"Error in {self.plugin_name!r} cache plugin while trying to write to {tmpfile_path!r}.", exception=ex)
             try:
                 os.rename(tmpfile_path, cachefile)
                 os.chmod(cachefile, mode=S_IRWU_RG_RO)
-            except (OSError, IOError) as e:
-                display.warning("error in '%s' cache plugin while trying to move '%s' to '%s' : %s" % (self.plugin_name, tmpfile_path, cachefile, to_bytes(e)))
+            except OSError as ex:
+                display.error_as_warning(f"Error in {self.plugin_name!r} cache plugin while trying to move {tmpfile_path!r} to {cachefile!r}.", exception=ex)
         finally:
             try:
                 os.unlink(tmpfile_path)
@@ -182,12 +180,12 @@ class BaseFileCacheModule(BaseCacheModule):
         cachefile = self._get_cache_file_name(key)
         try:
             st = os.stat(cachefile)
-        except (OSError, IOError) as e:
-            if e.errno == errno.ENOENT:
-                return False
-            else:
-                display.warning("error in '%s' cache plugin while trying to stat %s : %s" % (self.plugin_name, cachefile, to_bytes(e)))
-                return False
+        except FileNotFoundError:
+            return False
+        except OSError as ex:
+            display.error_as_warning(f"Error in {self.plugin_name!r} cache plugin while trying to stat {cachefile!r}.", exception=ex)
+
+            return False
 
         if time.time() - st.st_mtime <= self._timeout:
             return False
@@ -224,11 +222,10 @@ class BaseFileCacheModule(BaseCacheModule):
         try:
             os.stat(cachefile)
             return True
-        except (OSError, IOError) as e:
-            if e.errno == errno.ENOENT:
-                return False
-            else:
-                display.warning("error in '%s' cache plugin while trying to stat %s : %s" % (self.plugin_name, cachefile, to_bytes(e)))
+        except FileNotFoundError:
+            return False
+        except OSError as ex:
+            display.error_as_warning(f"Error in {self.plugin_name!r} cache plugin while trying to stat {cachefile!r}.", exception=ex)
 
     def delete(self, key):
         try:
@@ -237,7 +234,7 @@ class BaseFileCacheModule(BaseCacheModule):
             pass
         try:
             os.remove(self._get_cache_file_name(key))
-        except (OSError, IOError):
+        except OSError:
             pass  # TODO: only pass on non existing?
 
     def flush(self):
@@ -245,14 +242,8 @@ class BaseFileCacheModule(BaseCacheModule):
         for key in self.keys():
             self.delete(key)
 
-    def copy(self):
-        ret = dict()
-        for key in self.keys():
-            ret[key] = self.get(key)
-        return ret
-
     @abstractmethod
-    def _load(self, filepath):
+    def _load(self, filepath: str) -> object:
         """
         Read data from a filepath and return it as a value
 
@@ -271,7 +262,7 @@ class BaseFileCacheModule(BaseCacheModule):
         pass
 
     @abstractmethod
-    def _dump(self, value, filepath):
+    def _dump(self, value: object, filepath: str) -> None:
         """
         Write data to a filepath
 
@@ -281,19 +272,13 @@ class BaseFileCacheModule(BaseCacheModule):
         pass
 
 
-class CachePluginAdjudicator(MutableMapping):
-    """
-    Intermediary between a cache dictionary and a CacheModule
-    """
+class CachePluginAdjudicator(c.MutableMapping):
+    """Batch update wrapper around a cache plugin."""
+
     def __init__(self, plugin_name='memory', **kwargs):
         self._cache = {}
         self._retrieved = {}
-
         self._plugin = cache_loader.get(plugin_name, **kwargs)
-        if not self._plugin:
-            raise AnsibleError('Unable to load the cache plugin (%s).' % plugin_name)
-
-        self._plugin_name = plugin_name
 
     def update_cache_if_changed(self):
         if self._retrieved != self._cache:
@@ -302,6 +287,7 @@ class CachePluginAdjudicator(MutableMapping):
     def set_cache(self):
         for top_level_cache_key in self._cache.keys():
             self._plugin.set(top_level_cache_key, self._cache[top_level_cache_key])
+
         self._retrieved = copy.deepcopy(self._cache)
 
     def load_whole_cache(self):
@@ -309,7 +295,7 @@ class CachePluginAdjudicator(MutableMapping):
             self._cache[key] = self._plugin.get(key)
 
     def __repr__(self):
-        return to_text(self._cache)
+        return repr(self._cache)
 
     def __iter__(self):
         return iter(self.keys())
@@ -319,13 +305,10 @@ class CachePluginAdjudicator(MutableMapping):
 
     def _do_load_key(self, key):
         load = False
-        if all([
-            key not in self._cache,
-            key not in self._retrieved,
-            self._plugin_name != 'memory',
-            self._plugin.contains(key),
-        ]):
+
+        if key not in self._cache and key not in self._retrieved and self._plugin._persistent and self._plugin.contains(key):
             load = True
+
         return load
 
     def __getitem__(self, key):
@@ -336,16 +319,18 @@ class CachePluginAdjudicator(MutableMapping):
                 pass
             else:
                 self._retrieved[key] = self._cache[key]
+
         return self._cache[key]
 
     def get(self, key, default=None):
         if self._do_load_key(key):
             try:
                 self._cache[key] = self._plugin.get(key)
-            except KeyError as e:
+            except KeyError:
                 pass
             else:
                 self._retrieved[key] = self._cache[key]
+
         return self._cache.get(key, default)
 
     def items(self):
@@ -360,6 +345,7 @@ class CachePluginAdjudicator(MutableMapping):
     def pop(self, key, *args):
         if args:
             return self._cache.pop(key, args[0])
+
         return self._cache.pop(key)
 
     def __delitem__(self, key):
@@ -368,6 +354,9 @@ class CachePluginAdjudicator(MutableMapping):
     def __setitem__(self, key, value):
         self._cache[key] = value
 
+    def clear(self):
+        self.flush()
+
     def flush(self):
         self._plugin.flush()
         self._cache = {}

ansible/plugins/cache/base.py

@@ -18,3 +18,11 @@ from __future__ import annotations
 
 # moved actual classes to __init__ kept here for backward compat with 3rd parties
 from ansible.plugins.cache import BaseCacheModule, BaseFileCacheModule  # pylint: disable=unused-import
+
+from ansible.utils.display import Display as _Display
+
+_Display().deprecated(
+    msg="The `ansible.plugins.cache.base` Python module is deprecated.",
+    help_text="Import from `ansible.plugins.cache` instead.",
+    version="2.23",
+)

ansible/plugins/cache/jsonfile.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: jsonfile
     short_description: JSON formatted files.
     description:
@@ -38,25 +38,19 @@ DOCUMENTATION = '''
           - key: fact_caching_timeout
             section: defaults
         type: integer
-'''
+"""
 
-import codecs
 import json
+import pathlib
 
-from ansible.parsing.ajson import AnsibleJSONEncoder, AnsibleJSONDecoder
 from ansible.plugins.cache import BaseFileCacheModule
 
 
 class CacheModule(BaseFileCacheModule):
-    """
-    A caching module backed by json files.
-    """
-
-    def _load(self, filepath):
-        # Valid JSON is always UTF-8 encoded.
-        with codecs.open(filepath, 'r', encoding='utf-8') as f:
-            return json.load(f, cls=AnsibleJSONDecoder)
-
-    def _dump(self, value, filepath):
-        with codecs.open(filepath, 'w', encoding='utf-8') as f:
-            f.write(json.dumps(value, cls=AnsibleJSONEncoder, sort_keys=True, indent=4))
+    """A caching module backed by json files."""
+
+    def _load(self, filepath: str) -> object:
+        return json.loads(pathlib.Path(filepath).read_text())
+
+    def _dump(self, value: object, filepath: str) -> None:
+        pathlib.Path(filepath).write_text(json.dumps(value))