ansible-core 2.19.0b3__py3-none-any.whl → 2.19.0b5__py3-none-any.whl

ansible/plugins/lookup/csvfile.py

@@ -103,76 +103,26 @@ RETURN = """
     elements: str
 """
 
-import codecs
 import csv
 
 from collections.abc import MutableSequence
 
-from ansible.errors import AnsibleError, AnsibleAssertionError
+from ansible.errors import AnsibleError
 from ansible.parsing.splitter import parse_kv
 from ansible.plugins.lookup import LookupBase
-from ansible.module_utils.six import PY2
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
-
-
-class CSVRecoder:
-    """
-    Iterator that reads an encoded stream and encodes the input to UTF-8
-    """
-    def __init__(self, f, encoding='utf-8'):
-        self.reader = codecs.getreader(encoding)(f)
-
-    def __iter__(self):
-        return self
-
-    def __next__(self):
-        return next(self.reader).encode("utf-8")
-
-    next = __next__   # For Python 2
-
-
-class CSVReader:
-    """
-    A CSV reader which will iterate over lines in the CSV file "f",
-    which is encoded in the given encoding.
-    """
-
-    def __init__(self, f, dialect=csv.excel, encoding='utf-8', **kwds):
-        if PY2:
-            f = CSVRecoder(f, encoding)
-        else:
-            f = codecs.getreader(encoding)(f)
-
-        self.reader = csv.reader(f, dialect=dialect, **kwds)
-
-    def __next__(self):
-        row = next(self.reader)
-        return [to_text(s) for s in row]
-
-    next = __next__  # For Python 2
-
-    def __iter__(self):
-        return self
 
 
 class LookupModule(LookupBase):
 
     def read_csv(self, filename, key, delimiter, encoding='utf-8', dflt=None, col=1, keycol=0):
-
-        try:
-            f = open(to_bytes(filename), 'rb')
-            creader = CSVReader(f, delimiter=to_native(delimiter), encoding=encoding)
-
-            for row in creader:
-                if len(row) and row[keycol] == key:
+        with open(filename, encoding=encoding) as f:
+            for row in csv.reader(f, dialect=csv.excel, delimiter=delimiter):
+                if row and row[keycol] == key:
                     return row[col]
-        except Exception as e:
-            raise AnsibleError("csvfile: %s" % to_native(e))
 
         return dflt
 
     def run(self, terms, variables=None, **kwargs):
-
         ret = []
 
         self.set_options(var_options=variables, direct=kwargs)
@@ -192,23 +142,19 @@ class LookupModule(LookupBase):
             key = kv['_raw_params']
 
             # parameters override per term using k/v
-            try:
-                reset_params = False
-                for name, value in kv.items():
-                    if name == '_raw_params':
-                        continue
-                    if name not in paramvals:
-                        raise AnsibleAssertionError('%s is not a valid option' % name)
-
-                    self._deprecate_inline_kv()
-                    self.set_option(name, value)
-                    reset_params = True
+            reset_params = False
+            for name, value in kv.items():
+                if name == '_raw_params':
+                    continue
+                if name not in paramvals:
+                    raise ValueError(f'{name!r} is not a valid option')
 
-                if reset_params:
-                    paramvals = self.get_options()
+                self._deprecate_inline_kv()
+                self.set_option(name, value)
+                reset_params = True
 
-            except (ValueError, AssertionError) as e:
-                raise AnsibleError(e)
+            if reset_params:
+                paramvals = self.get_options()
 
             # default is just placeholder for real tab
             if paramvals['delimiter'] == 'TAB':
@@ -218,8 +164,7 @@ class LookupModule(LookupBase):
             var = self.read_csv(lookupfile, key, paramvals['delimiter'], paramvals['encoding'], paramvals['default'], paramvals['col'], paramvals['keycol'])
             if var is not None:
                 if isinstance(var, MutableSequence):
-                    for v in var:
-                        ret.append(v)
+                    ret.extend(var)
                 else:
                     ret.append(var)
 

ansible/plugins/lookup/first_found.py

@@ -149,6 +149,7 @@ from ansible.errors import AnsibleError
 from ansible.plugins.lookup import LookupBase
 from ansible._internal._templating import _jinja_common
 from ansible._internal._templating import _jinja_plugins
+from ansible import template as _template
 from ansible.utils.path import unfrackpath
 from ansible.utils.display import Display
 from ansible.module_utils.datatag import native_type_name
@@ -222,7 +223,7 @@ class LookupModule(LookupBase):
         return total_search
 
     def run(self, terms: list, variables=None, **kwargs):
-        if (first_marker := _jinja_common.get_first_marker_arg((), kwargs)) is not None:
+        if (first_marker := _template.get_first_marker_arg((), kwargs)) is not None:
             first_marker.trip()
 
         if _jinja_plugins._LookupContext.current().invoked_as_with:

ansible/plugins/shell/__init__.py

@@ -16,6 +16,7 @@
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 from __future__ import annotations
 
+import dataclasses
 import os
 import os.path
 import re
@@ -33,6 +34,13 @@ from ansible.plugins import AnsiblePlugin
 _USER_HOME_PATH_RE = re.compile(r'^~[_.A-Za-z0-9][-_.A-Za-z0-9]*$')
 
 
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class _ShellCommand:
+    """Internal type returned by shell subsystems that may require both an execution payload and a command (eg powershell)."""
+    command: str
+    input_data: bytes | None = None
+
+
 class ShellBase(AnsiblePlugin):
     def __init__(self):
 
@@ -121,7 +129,13 @@ class ShellBase(AnsiblePlugin):
         cmd = ['test', '-e', self.quote(path)]
         return ' '.join(cmd)
 
-    def mkdtemp(self, basefile=None, system=False, mode=0o700, tmpdir=None):
+    def mkdtemp(
+        self,
+        basefile: str | None = None,
+        system: bool = False,
+        mode: int = 0o700,
+        tmpdir: str | None = None,
+    ) -> str:
         if not basefile:
             basefile = self.__class__._generate_temp_dir_name()
 
@@ -163,7 +177,31 @@ class ShellBase(AnsiblePlugin):
 
         return cmd
 
-    def expand_user(self, user_home_path, username=''):
+    def _mkdtemp2(
+        self,
+        basefile: str | None = None,
+        system: bool = False,
+        mode: int = 0o700,
+        tmpdir: str | None = None,
+    ) -> _ShellCommand:
+        """Gets command info to create a temporary directory.
+
+        This is an internal API that should not be used publicly.
+
+        :args basefile: The base name of the temporary directory.
+        :args system: If True, create the directory in a system-wide location.
+        :args mode: The permissions mode for the directory.
+        :args tmpdir: The directory in which to create the temporary directory.
+        :returns: The shell command to run to create the temp directory.
+        """
+        cmd = self.mkdtemp(basefile=basefile, system=system, mode=mode, tmpdir=tmpdir)
+        return _ShellCommand(command=cmd, input_data=None)
+
+    def expand_user(
+        self,
+        user_home_path: str,
+        username: str = '',
+    ) -> str:
         """ Return a command to expand tildes in a path
 
         It can be either "~" or "~username". We just ignore $HOME
@@ -184,6 +222,22 @@ class ShellBase(AnsiblePlugin):
 
         return 'echo %s' % user_home_path
 
+    def _expand_user2(
+        self,
+        user_home_path: str,
+        username: str = '',
+    ) -> _ShellCommand:
+        """Gets command to expand user path.
+
+        This is an internal API that should not be used publicly.
+
+        :args user_home_path: The path to expand.
+        :args username: The username to use for expansion.
+        :returns: The shell command to run to get the expanded user path.
+        """
+        cmd = self.expand_user(user_home_path, username=username)
+        return _ShellCommand(command=cmd, input_data=None)
+
     def pwd(self):
         """Return the working directory after connecting"""
         return 'echo %spwd%s' % (self._SHELL_SUB_LEFT, self._SHELL_SUB_RIGHT)

ansible/plugins/shell/powershell.py

@@ -21,9 +21,13 @@ import shlex
 import xml.etree.ElementTree as ET
 import ntpath
 
-from ansible.executor.powershell.module_manifest import _get_powershell_script
+from ansible.executor.powershell.module_manifest import _bootstrap_powershell_script, _get_powershell_script
 from ansible.module_utils.common.text.converters import to_bytes, to_text
-from ansible.plugins.shell import ShellBase
+from ansible.plugins.shell import ShellBase, _ShellCommand
+from ansible.utils.display import Display
+
+
+display = Display()
 
 # This is weird, we are matching on byte sequences that match the utf-16-be
 # matches for '_x(a-fA-F0-9){4}_'. The \x00 and {4} will match the hex sequence
@@ -225,9 +229,15 @@ class ShellModule(ShellBase):
         else:
             return self._encode_script("""Remove-Item '%s' -Force;""" % path)
 
-    def mkdtemp(self, basefile=None, system=False, mode=None, tmpdir=None):
-        # Windows does not have an equivalent for the system temp files, so
-        # the param is ignored
+    def mkdtemp(
+        self,
+        basefile: str | None = None,
+        system: bool = False,
+        mode: int = 0o700,
+        tmpdir: str | None = None,
+    ) -> str:
+        # This is not called in Ansible anymore but it is kept for backwards
+        # compatibility in case other action plugins outside Ansible calls this.
         if not basefile:
             basefile = self.__class__._generate_temp_dir_name()
         basefile = self._escape(self._unquote(basefile))
@@ -241,10 +251,38 @@ class ShellModule(ShellBase):
         """
         return self._encode_script(script.strip())
 
-    def expand_user(self, user_home_path, username=''):
-        # PowerShell only supports "~" (not "~username").  Resolve-Path ~ does
-        # not seem to work remotely, though by default we are always starting
-        # in the user's home directory.
+    def _mkdtemp2(
+        self,
+        basefile: str | None = None,
+        system: bool = False,
+        mode: int = 0o700,
+        tmpdir: str | None = None,
+    ) -> _ShellCommand:
+        # Windows does not have an equivalent for the system temp files, so
+        # the param is ignored
+        if not basefile:
+            basefile = self.__class__._generate_temp_dir_name()
+
+        basefile = self._unquote(basefile)
+        basetmpdir = tmpdir if tmpdir else self.get_option('remote_tmp')
+
+        script, stdin = _bootstrap_powershell_script("powershell_mkdtemp.ps1", {
+            'Directory': basetmpdir,
+            'Name': basefile,
+        })
+
+        return _ShellCommand(
+            command=self._encode_script(script),
+            input_data=stdin,
+        )
+
+    def expand_user(
+        self,
+        user_home_path: str,
+        username: str = '',
+    ) -> str:
+        # This is not called in Ansible anymore but it is kept for backwards
+        # compatibility in case other actions plugins outside Ansible called this.
         user_home_path = self._unquote(user_home_path)
         if user_home_path == '~':
             script = 'Write-Output (Get-Location).Path'
@@ -254,6 +292,21 @@ class ShellModule(ShellBase):
             script = "Write-Output '%s'" % self._escape(user_home_path)
         return self._encode_script(f"{self._CONSOLE_ENCODING}; {script}")
 
+    def _expand_user2(
+        self,
+        user_home_path: str,
+        username: str = '',
+    ) -> _ShellCommand:
+        user_home_path = self._unquote(user_home_path)
+        script, stdin = _bootstrap_powershell_script("powershell_expand_user.ps1", {
+            'Path': user_home_path,
+        })
+
+        return _ShellCommand(
+            command=self._encode_script(script),
+            input_data=stdin,
+        )
+
     def exists(self, path):
         path = self._escape(self._unquote(path))
         script = """
@@ -271,6 +324,10 @@ class ShellModule(ShellBase):
         return self._encode_script(script)
 
     def checksum(self, path, *args, **kwargs):
+        display.deprecated(
+            "The 'ShellModule.checksum' method is deprecated. Use 'ActionBase._execute_remote_stat()' instead.",
+            version="2.23"
+        )
         path = self._escape(self._unquote(path))
         script = """
             If (Test-Path -PathType Leaf '%(path)s')

ansible/plugins/shell/sh.py

@@ -14,6 +14,10 @@ extends_documentation_fragment:
 """
 
 from ansible.plugins.shell import ShellBase
+from ansible.utils.display import Display
+
+
+display = Display()
 
 
 class ShellModule(ShellBase):
@@ -43,6 +47,10 @@ class ShellModule(ShellBase):
     _SHELL_GROUP_RIGHT = ')'
 
     def checksum(self, path, python_interp):
+        display.deprecated(
+            "The 'ShellModule.checksum' method is deprecated. Use 'ActionBase._execute_remote_stat()' instead.",
+            version="2.23"
+        )
         # In the following test, each condition is a check and logical
         # comparison (|| or &&) that sets the rc value.  Every check is run so
         # the last check in the series to fail will be the rc that is returned.
@@ -67,11 +75,7 @@ class ShellModule(ShellBase):
         # "one-liner".
         shell_escaped_path = self.quote(path)
         test = "rc=flag; [ -r %(p)s ] %(shell_or)s rc=2; [ -f %(p)s ] %(shell_or)s rc=1; [ -d %(p)s ] %(shell_and)s rc=3; %(i)s -V 2>/dev/null %(shell_or)s rc=4; [ x\"$rc\" != \"xflag\" ] %(shell_and)s echo \"${rc}  \"%(p)s %(shell_and)s exit 0" % dict(p=shell_escaped_path, i=python_interp, shell_and=self._SHELL_AND, shell_or=self._SHELL_OR)  # NOQA
-        csums = [
-            u"({0} -c 'import hashlib; BLOCKSIZE = 65536; hasher = hashlib.sha1();{2}afile = open(\"'{1}'\", \"rb\"){2}buf = afile.read(BLOCKSIZE){2}while len(buf) > 0:{2}\thasher.update(buf){2}\tbuf = afile.read(BLOCKSIZE){2}afile.close(){2}print(hasher.hexdigest())' 2>/dev/null)".format(python_interp, shell_escaped_path, self._SHELL_EMBEDDED_PY_EOL),  # NOQA  Python > 2.4 (including python3)
-            u"({0} -c 'import sha; BLOCKSIZE = 65536; hasher = sha.sha();{2}afile = open(\"'{1}'\", \"rb\"){2}buf = afile.read(BLOCKSIZE){2}while len(buf) > 0:{2}\thasher.update(buf){2}\tbuf = afile.read(BLOCKSIZE){2}afile.close(){2}print(hasher.hexdigest())' 2>/dev/null)".format(python_interp, shell_escaped_path, self._SHELL_EMBEDDED_PY_EOL),  # NOQA  Python == 2.4
-        ]
+        cmd = "({0} -c 'import hashlib; BLOCKSIZE = 65536; hasher = hashlib.sha1();{2}afile = open(\"'{1}'\", \"rb\"){2}buf = afile.read(BLOCKSIZE){2}while len(buf) > 0:{2}\thasher.update(buf){2}\tbuf = afile.read(BLOCKSIZE){2}afile.close(){2}print(hasher.hexdigest())' 2>/dev/null)".format(python_interp, shell_escaped_path, self._SHELL_EMBEDDED_PY_EOL)  # NOQA
 
-        cmd = (" %s " % self._SHELL_OR).join(csums)
         cmd = "%s; %s %s (echo \'0  \'%s)" % (test, cmd, self._SHELL_OR, shell_escaped_path)
         return cmd

ansible/plugins/test/core.py

@@ -31,7 +31,7 @@ from ansible import errors
 from ansible.module_utils.common.text.converters import to_native, to_text, to_bytes
 from ansible._internal._templating._jinja_common import Marker, UndefinedMarker
 from ansible.module_utils.parsing.convert_bool import boolean
-from ansible.plugins import accept_args_markers
+from ansible.template import accept_args_markers
 from ansible.parsing.vault import is_encrypted_file, VaultHelper, VaultLib
 from ansible.utils.display import Display
 from ansible.utils.version import SemanticVersion
@@ -49,37 +49,41 @@ def timedout(result):
     """ Test if task result yields a time out"""
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'timedout' test expects a dictionary")
-    return result.get('timedout', False) and bool(result['timedout'].get('period', False))
+
+    return bool(result.get('timedout') and bool(result['timedout'].get('period')))
 
 
 def failed(result):
     """ Test if task result yields failed """
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'failed' test expects a dictionary")
-    return result.get('failed', False)
+
+    return bool(result.get('failed'))
 
 
 def success(result):
     """ Test if task result yields success """
-    return not failed(result)
+    return not bool(failed(result))
 
 
 def unreachable(result):
     """ Test if task result yields unreachable """
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'unreachable' test expects a dictionary")
-    return result.get('unreachable', False)
+
+    return bool(result.get('unreachable'))
 
 
 def reachable(result):
     """ Test if task result yields reachable """
-    return not unreachable(result)
+    return bool(not unreachable(result))
 
 
 def changed(result):
     """ Test if task result yields changed """
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'changed' test expects a dictionary")
+
     if 'changed' not in result:
         changed = False
         if (
@@ -88,29 +92,31 @@ def changed(result):
             isinstance(result['results'][0], MutableMapping)
         ):
             for res in result['results']:
-                if res.get('changed', False):
+                if res.get('changed'):
                     changed = True
                     break
     else:
-        changed = result.get('changed', False)
-    return changed
+        changed = result.get('changed')
+
+    return bool(changed)
 
 
 def skipped(result):
     """ Test if task result yields skipped """
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'skipped' test expects a dictionary")
-    return result.get('skipped', False)
+
+    return bool(result.get('skipped'))
 
 
 def started(result):
     """ Test if async task has started """
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'started' test expects a dictionary")
+
     if 'started' in result:
         # For async tasks, return status
-        # NOTE: The value of started is 0 or 1, not False or True :-/
-        return result.get('started', 0) == 1
+        return bool(result.get('started'))
     else:
         # For non-async tasks, warn user, but return as if started
         display.warning("The 'started' test expects an async task, but a non-async task was tested")
@@ -121,10 +127,10 @@ def finished(result):
     """ Test if async task has finished """
     if not isinstance(result, MutableMapping):
         raise errors.AnsibleFilterError("The 'finished' test expects a dictionary")
+
     if 'finished' in result:
         # For async tasks, return status
-        # NOTE: The value of finished is 0 or 1, not False or True :-/
-        return result.get('finished', 0) == 1
+        return bool(result.get('finished'))
     else:
         # For non-async tasks, warn user, but return as if finished
         display.warning("The 'finished' test expects an async task, but a non-async task was tested")
@@ -170,7 +176,7 @@ def vaulted_file(value):
         with open(to_bytes(value), 'rb') as f:
             return is_encrypted_file(f)
     except (OSError, IOError) as e:
-        raise errors.AnsibleFilterError(f"Cannot test if the file {value} is a vault", orig_exc=e)
+        raise errors.AnsibleFilterError(f"Cannot test if the file {value} is a vault.") from e
 
 
 def match(value, pattern='', ignorecase=False, multiline=False):

ansible/plugins/test/finished.yml

@@ -5,7 +5,7 @@ DOCUMENTATION:
   short_description: Did async task finish
   description:
     - Used to test if an async task has finished, it will also work with normal tasks but will issue a warning.
-    - This test checks for the existence of a C(finished) key in the input dictionary and that it is V(1) if present
+    - This test checks for the existence of a C(finished) key in the input dictionary and that it is V(True) if present
   options:
     _input:
       description: registered result from an Ansible task

ansible/plugins/test/uri.py

@@ -20,11 +20,8 @@ def is_url(value, schemes=None):
 
     isit = is_uri(value, schemes)
     if isit:
-        try:
-            x = urlparse(value)
-            isit = bool(x.netloc or x.scheme == 'file')
-        except Exception as e:
-            isit = False
+        x = urlparse(value)
+        isit = bool(x.netloc or x.scheme == 'file')
     return isit
 
 

ansible/release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.19.0b3'
+__version__ = '2.19.0b5'
 __author__ = 'Ansible, Inc.'
 __codename__ = "What Is and What Should Never Be"

ansible/template/__init__.py

@@ -98,7 +98,7 @@ class Templar:
     @property
     def basedir(self) -> str:
         """The basedir from DataLoader."""
-        # DTFIX-RELEASE: come up with a better way to handle this so it can be deprecated
+        # DTFIX-FUTURE: come up with a better way to handle this so it can be deprecated
         return self._engine.basedir
 
     @property
@@ -381,7 +381,7 @@ def generate_ansible_template_vars(path: str, fullpath: str | None = None, dest_
     )
 
     ansible_managed = _time.strftime(managed_str, _time.localtime(template_stat.st_mtime))
-    # DTFIX-RELEASE: this should not be tag_copy, it should either be an origin copy or some kind of derived origin
+    # DTFIX7: this should not be tag_copy, it should either be an origin copy or some kind of derived origin
     ansible_managed = _datatag.AnsibleTagHelper.tag_copy(managed_default, ansible_managed)
     ansible_managed = trust_as_template(ansible_managed)
     ansible_managed = _module_utils_datatag.deprecate_value(
@@ -427,3 +427,31 @@ def is_trusted_as_template(value: object) -> bool:
     This function should not be needed for production code, but may be useful in unit tests.
     """
     return isinstance(value, _TRUSTABLE_TYPES) and _tags.TrustedAsTemplate.is_tagged_on(value)
+
+
+_TCallable = _t.TypeVar('_TCallable', bound=_t.Callable)
+
+
+def accept_args_markers(plugin: _TCallable) -> _TCallable:
+    """
+    A decorator to mark a Jinja plugin as capable of handling `Marker` values for its top-level arguments.
+    Non-decorated plugin invocation is skipped when a top-level argument is a `Marker`, with the first such value substituted as the plugin result.
+    This ensures that only plugins which understand `Marker` instances for top-level arguments will encounter them.
+    """
+    plugin.accept_args_markers = True
+
+    return plugin
+
+
+def accept_lazy_markers(plugin: _TCallable) -> _TCallable:
+    """
+    A decorator to mark a Jinja plugin as capable of handling `Marker` values retrieved from lazy containers.
+    Non-decorated plugins will trigger a `MarkerError` exception when attempting to retrieve a `Marker` from a lazy container.
+    This ensures that only plugins which understand lazy retrieval of `Marker` instances will encounter them.
+    """
+    plugin.accept_lazy_markers = True
+
+    return plugin
+
+
+get_first_marker_arg = _jinja_common.get_first_marker_arg

ansible/utils/collection_loader/__init__.py

@@ -13,6 +13,8 @@ import typing as t
 class _EncryptedStringProtocol(t.Protocol):
     """Protocol representing an `EncryptedString`, since it cannot be imported here."""
 
+    # DTFIX-FUTURE: collapse this with the one in config, once we can
+
     def _decrypt(self) -> str: ...