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

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,8 +177,32 @@ class ShellBase(AnsiblePlugin):
 
         return cmd
 
-    def expand_user(self, user_home_path, username=''):
-        ''' Return a command to expand tildes in a path
+    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
         We use the POSIX definition of a username:
@@ -172,7 +210,7 @@ class ShellBase(AnsiblePlugin):
             http://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_276
 
             Falls back to 'current working directory' as we assume 'home is where the remote user ends up'
-        '''
+        """
 
         # Check that the user_path to expand is safe
         if user_home_path != '~':
@@ -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/cmd.py

@@ -2,7 +2,7 @@
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 name: cmd
 version_added: '2.8'
 short_description: Windows Command Prompt
@@ -10,7 +10,7 @@ description:
 - Used with the 'ssh' connection plugin and no C(DefaultShell) has been set on the Windows host.
 extends_documentation_fragment:
 - shell_windows
-'''
+"""
 
 import re
 

ansible/plugins/shell/powershell.py

@@ -3,7 +3,7 @@
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 name: powershell
 version_added: historical
 short_description: Windows PowerShell
@@ -12,18 +12,22 @@ description:
 - Can also be used when using 'ssh' as a connection plugin and the C(DefaultShell) has been configured to PowerShell.
 extends_documentation_fragment:
 - shell_windows
-'''
+"""
 
 import base64
 import os
 import re
 import shlex
-import pkgutil
 import xml.etree.ElementTree as ET
 import ntpath
 
+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
@@ -221,30 +225,64 @@ class ShellModule(ShellBase):
     def remove(self, path, recurse=False):
         path = self._escape(self._unquote(path))
         if recurse:
-            return self._encode_script('''Remove-Item '%s' -Force -Recurse;''' % path)
+            return self._encode_script("""Remove-Item '%s' -Force -Recurse;""" % path)
         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
+            return self._encode_script("""Remove-Item '%s' -Force;""" % path)
+
+    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))
         basetmpdir = self._escape(tmpdir if tmpdir else self.get_option('remote_tmp'))
 
-        script = f'''
+        script = f"""
         {self._CONSOLE_ENCODING}
         $tmp_path = [System.Environment]::ExpandEnvironmentVariables('{basetmpdir}')
         $tmp = New-Item -Type Directory -Path $tmp_path -Name '{basefile}'
         Write-Output -InputObject $tmp.FullName
-        '''
+        """
         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,9 +292,24 @@ 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 = '''
+        script = """
             If (Test-Path '%s')
             {
                 $res = 0;
@@ -267,12 +320,17 @@ class ShellModule(ShellBase):
             }
             Write-Output '$res';
             Exit $res;
-         ''' % path
+         """ % path
         return self._encode_script(script)
 
     def checksum(self, path, *args, **kwargs):
+        display.deprecated(
+            msg="The `ShellModule.checksum` method is deprecated.",
+            version="2.23",
+            help_text="Use `ActionBase._execute_remote_stat()` instead.",
+        )
         path = self._escape(self._unquote(path))
-        script = '''
+        script = """
             If (Test-Path -PathType Leaf '%(path)s')
             {
                 $sp = new-object -TypeName System.Security.Cryptography.SHA1CryptoServiceProvider;
@@ -288,11 +346,11 @@ class ShellModule(ShellBase):
             {
                 Write-Output "1";
             }
-        ''' % dict(path=path)
+        """ % dict(path=path)
         return self._encode_script(script)
 
     def build_module_command(self, env_string, shebang, cmd, arg_path=None):
-        bootstrap_wrapper = pkgutil.get_data("ansible.executor.powershell", "bootstrap_wrapper.ps1")
+        bootstrap_wrapper = _get_powershell_script("bootstrap_wrapper.ps1")
 
         # pipelining bypass
         if cmd == '':
@@ -303,18 +361,35 @@ class ShellModule(ShellBase):
         cmd_parts = shlex.split(cmd, posix=False)
         cmd_parts = list(map(to_text, cmd_parts))
         if shebang and shebang.lower() == '#!powershell':
-            if not self._unquote(cmd_parts[0]).lower().endswith('.ps1'):
-                # we're running a module via the bootstrap wrapper
-                cmd_parts[0] = '"%s.ps1"' % self._unquote(cmd_parts[0])
-            wrapper_cmd = "type " + cmd_parts[0] + " | " + self._encode_script(script=bootstrap_wrapper, strict_mode=False, preserve_rc=False)
-            return wrapper_cmd
+            if arg_path:
+                # Running a module without the exec_wrapper and with an argument
+                # file.
+                script_path = self._unquote(cmd_parts[0])
+                if not script_path.lower().endswith('.ps1'):
+                    script_path += '.ps1'
+
+                cmd_parts.insert(0, '-File')
+                cmd_parts[1] = f'"{script_path}"'
+                if arg_path:
+                    cmd_parts.append(f'"{arg_path}"')
+
+                wrapper_cmd = " ".join(_common_args + cmd_parts)
+                return wrapper_cmd
+
+            else:
+                # Running a module with ANSIBLE_KEEP_REMOTE_FILES=true, the script
+                # arg is actually the input manifest JSON to provide to the bootstrap
+                # wrapper.
+                wrapper_cmd = "type " + cmd_parts[0] + " | " + self._encode_script(script=bootstrap_wrapper, strict_mode=False, preserve_rc=False)
+                return wrapper_cmd
+
         elif shebang and shebang.startswith('#!'):
             cmd_parts.insert(0, shebang[2:])
         elif not shebang:
             # The module is assumed to be a binary
             cmd_parts[0] = self._unquote(cmd_parts[0])
             cmd_parts.append(arg_path)
-        script = '''
+        script = """
             Try
             {
                 %s
@@ -349,14 +424,14 @@ class ShellModule(ShellBase):
                 Echo $_obj | ConvertTo-Json -Compress -Depth 99
                 Exit 1
             }
-        ''' % (env_string, ' '.join(cmd_parts))
+        """ % (env_string, ' '.join(cmd_parts))
         return self._encode_script(script, preserve_rc=False)
 
     def wrap_for_exec(self, cmd):
         return '& %s; exit $LASTEXITCODE' % cmd
 
     def _unquote(self, value):
-        '''Remove any matching quotes that wrap the given value.'''
+        """Remove any matching quotes that wrap the given value."""
         value = to_text(value or '')
         m = re.match(r'^\s*?\'(.*?)\'\s*?$', value)
         if m:
@@ -367,13 +442,13 @@ class ShellModule(ShellBase):
         return value
 
     def _escape(self, value):
-        '''Return value escaped for use in PowerShell single quotes.'''
+        """Return value escaped for use in PowerShell single quotes."""
         # There are 5 chars that need to be escaped in a single quote.
         # https://github.com/PowerShell/PowerShell/blob/b7cb335f03fe2992d0cbd61699de9d9aafa1d7c1/src/System.Management.Automation/engine/parser/CharTraits.cs#L265-L272
         return re.compile(u"(['\u2018\u2019\u201a\u201b])").sub(u'\\1\\1', value)
 
     def _encode_script(self, script, as_list=False, strict_mode=True, preserve_rc=True):
-        '''Convert a PowerShell script to a single base64-encoded command.'''
+        """Convert a PowerShell script to a single base64-encoded command."""
         script = to_text(script)
 
         if script == u'-':

ansible/plugins/shell/sh.py

@@ -3,7 +3,7 @@
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
 name: sh
 short_description: "POSIX shell (/bin/sh)"
 version_added: historical
@@ -11,9 +11,13 @@ description:
   - This shell plugin is the one you want to use on most Unix systems, it is the most compatible and widely installed shell.
 extends_documentation_fragment:
   - shell_common
-'''
+"""
 
 from ansible.plugins.shell import ShellBase
+from ansible.utils.display import Display
+
+
+display = Display()
 
 
 class ShellModule(ShellBase):
@@ -29,6 +33,7 @@ class ShellModule(ShellBase):
 
     # commonly used
     ECHO = 'echo'
+    CD = 'cd'
     COMMAND_SEP = ';'
 
     # How to end lines in a python script one-liner
@@ -42,6 +47,11 @@ class ShellModule(ShellBase):
     _SHELL_GROUP_RIGHT = ')'
 
     def checksum(self, path, python_interp):
+        display.deprecated(
+            msg="The `ShellModule.checksum` method is deprecated.",
+            version="2.23",
+            help_text="Use `ActionBase._execute_remote_stat()` instead.",
+        )
         # 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.
@@ -66,11 +76,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