ansible-core 2.15.4rc1__py3-none-any.whl → 2.16.0b2__py3-none-any.whl

ansible/plugins/connection/__init__.py

@@ -2,10 +2,12 @@
 # (c) 2015 Toshio Kuratomi <tkuratomi@ansible.com>
 # (c) 2017, Peter Sprygada <psprygad@redhat.com>
 # (c) 2017 Ansible Project
-from __future__ import (absolute_import, division, print_function)
+from __future__ import (annotations, absolute_import, division, print_function)
 __metaclass__ = type
 
+import collections.abc as c
 import fcntl
+import io
 import os
 import shlex
 import typing as t
@@ -14,8 +16,11 @@ from abc import abstractmethod
 from functools import wraps
 
 from ansible import constants as C
-from ansible.module_utils._text import to_bytes, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.playbook.play_context import PlayContext
 from ansible.plugins import AnsiblePlugin
+from ansible.plugins.become import BecomeBase
+from ansible.plugins.shell import ShellBase
 from ansible.utils.display import Display
 from ansible.plugins.loader import connection_loader, get_shell_plugin
 from ansible.utils.path import unfrackpath
@@ -27,10 +32,15 @@ __all__ = ['ConnectionBase', 'ensure_connect']
 
 BUFSIZE = 65536
 
+P = t.ParamSpec('P')
+T = t.TypeVar('T')
 
-def ensure_connect(func):
+
+def ensure_connect(
+    func: c.Callable[t.Concatenate[ConnectionBase, P], T],
+) -> c.Callable[t.Concatenate[ConnectionBase, P], T]:
     @wraps(func)
-    def wrapped(self, *args, **kwargs):
+    def wrapped(self: ConnectionBase, *args: P.args, **kwargs: P.kwargs) -> T:
         if not self._connected:
             self._connect()
         return func(self, *args, **kwargs)
@@ -57,9 +67,16 @@ class ConnectionBase(AnsiblePlugin):
     supports_persistence = False
     force_persistence = False
 
-    default_user = None
+    default_user: str | None = None
 
-    def __init__(self, play_context, new_stdin=None, shell=None, *args, **kwargs):
+    def __init__(
+        self,
+        play_context: PlayContext,
+        new_stdin: io.TextIOWrapper | None = None,
+        shell: ShellBase | None = None,
+        *args: t.Any,
+        **kwargs: t.Any,
+    ) -> None:
 
         super(ConnectionBase, self).__init__()
 
@@ -77,7 +94,7 @@ class ConnectionBase(AnsiblePlugin):
         self.success_key = None
         self.prompt = None
         self._connected = False
-        self._socket_path = None
+        self._socket_path: str | None = None
 
         # helper plugins
         self._shell = shell
@@ -87,10 +104,10 @@ class ConnectionBase(AnsiblePlugin):
             shell_type = play_context.shell if play_context.shell else getattr(self, '_shell_type', None)
             self._shell = get_shell_plugin(shell_type=shell_type, executable=self._play_context.executable)
 
-        self.become = None
+        self.become: BecomeBase | None = None
 
     @property
-    def _new_stdin(self):
+    def _new_stdin(self) -> io.TextIOWrapper | None:
         display.deprecated(
             "The connection's stdin object is deprecated. "
             "Call display.prompt_until(msg) instead.",
@@ -98,21 +115,21 @@ class ConnectionBase(AnsiblePlugin):
         )
         return self.__new_stdin
 
-    def set_become_plugin(self, plugin):
+    def set_become_plugin(self, plugin: BecomeBase) -> None:
         self.become = plugin
 
     @property
-    def connected(self):
+    def connected(self) -> bool:
         '''Read-only property holding whether the connection to the remote host is active or closed.'''
         return self._connected
 
     @property
-    def socket_path(self):
+    def socket_path(self) -> str | None:
         '''Read-only property holding the connection socket path for this remote host'''
         return self._socket_path
 
     @staticmethod
-    def _split_ssh_args(argstring):
+    def _split_ssh_args(argstring: str) -> list[str]:
         """
         Takes a string like '-o Foo=1 -o Bar="foo bar"' and returns a
         list ['-o', 'Foo=1', '-o', 'Bar=foo bar'] that can be added to
@@ -123,17 +140,17 @@ class ConnectionBase(AnsiblePlugin):
 
     @property
     @abstractmethod
-    def transport(self):
+    def transport(self) -> str:
         """String used to identify this Connection class from other classes"""
         pass
 
     @abstractmethod
-    def _connect(self):
+    def _connect(self: T) -> T:
         """Connect to the host we've been initialized with"""
 
     @ensure_connect
     @abstractmethod
-    def exec_command(self, cmd, in_data=None, sudoable=True):
+    def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
         """Run a command on the remote host.
 
         :arg cmd: byte string containing the command
@@ -201,36 +218,36 @@ class ConnectionBase(AnsiblePlugin):
 
     @ensure_connect
     @abstractmethod
-    def put_file(self, in_path, out_path):
+    def put_file(self, in_path: str, out_path: str) -> None:
         """Transfer a file from local to remote"""
         pass
 
     @ensure_connect
     @abstractmethod
-    def fetch_file(self, in_path, out_path):
+    def fetch_file(self, in_path: str, out_path: str) -> None:
         """Fetch a file from remote to local; callers are expected to have pre-created the directory chain for out_path"""
         pass
 
     @abstractmethod
-    def close(self):
+    def close(self) -> None:
         """Terminate the connection"""
         pass
 
-    def connection_lock(self):
+    def connection_lock(self) -> None:
         f = self._play_context.connection_lockfd
         display.vvvv('CONNECTION: pid %d waiting for lock on %d' % (os.getpid(), f), host=self._play_context.remote_addr)
         fcntl.lockf(f, fcntl.LOCK_EX)
         display.vvvv('CONNECTION: pid %d acquired lock on %d' % (os.getpid(), f), host=self._play_context.remote_addr)
 
-    def connection_unlock(self):
+    def connection_unlock(self) -> None:
         f = self._play_context.connection_lockfd
         fcntl.lockf(f, fcntl.LOCK_UN)
         display.vvvv('CONNECTION: pid %d released lock on %d' % (os.getpid(), f), host=self._play_context.remote_addr)
 
-    def reset(self):
+    def reset(self) -> None:
         display.warning("Reset is not implemented for this connection")
 
-    def update_vars(self, variables):
+    def update_vars(self, variables: dict[str, t.Any]) -> None:
         '''
         Adds 'magic' variables relating to connections to the variable dictionary provided.
         In case users need to access from the play, this is a legacy from runner.
@@ -246,7 +263,7 @@ class ConnectionBase(AnsiblePlugin):
             elif varname == 'ansible_connection':
                 # its me mom!
                 value = self._load_name
-            elif varname == 'ansible_shell_type':
+            elif varname == 'ansible_shell_type' and self._shell:
                 # its my cousin ...
                 value = self._shell._load_name
             else:
@@ -279,9 +296,15 @@ class NetworkConnectionBase(ConnectionBase):
     # Do not use _remote_is_local in other connections
     _remote_is_local = True
 
-    def __init__(self, play_context, new_stdin=None, *args, **kwargs):
+    def __init__(
+        self,
+        play_context: PlayContext,
+        new_stdin: io.TextIOWrapper | None = None,
+        *args: t.Any,
+        **kwargs: t.Any,
+    ) -> None:
         super(NetworkConnectionBase, self).__init__(play_context, new_stdin, *args, **kwargs)
-        self._messages = []
+        self._messages: list[tuple[str, str]] = []
         self._conn_closed = False
 
         self._network_os = self._play_context.network_os
@@ -289,7 +312,7 @@ class NetworkConnectionBase(ConnectionBase):
         self._local = connection_loader.get('local', play_context, '/dev/null')
         self._local.set_options()
 
-        self._sub_plugin = {}
+        self._sub_plugin: dict[str, t.Any] = {}
         self._cached_variables = (None, None, None)
 
         # reconstruct the socket_path and set instance values accordingly
@@ -308,10 +331,10 @@ class NetworkConnectionBase(ConnectionBase):
                         return method
             raise AttributeError("'%s' object has no attribute '%s'" % (self.__class__.__name__, name))
 
-    def exec_command(self, cmd, in_data=None, sudoable=True):
+    def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
         return self._local.exec_command(cmd, in_data, sudoable)
 
-    def queue_message(self, level, message):
+    def queue_message(self, level: str, message: str) -> None:
         """
         Adds a message to the queue of messages waiting to be pushed back to the controller process.
 
@@ -321,19 +344,19 @@ class NetworkConnectionBase(ConnectionBase):
         """
         self._messages.append((level, message))
 
-    def pop_messages(self):
+    def pop_messages(self) -> list[tuple[str, str]]:
         messages, self._messages = self._messages, []
         return messages
 
-    def put_file(self, in_path, out_path):
+    def put_file(self, in_path: str, out_path: str) -> None:
         """Transfer a file from local to remote"""
         return self._local.put_file(in_path, out_path)
 
-    def fetch_file(self, in_path, out_path):
+    def fetch_file(self, in_path: str, out_path: str) -> None:
         """Fetch a file from remote to local"""
         return self._local.fetch_file(in_path, out_path)
 
-    def reset(self):
+    def reset(self) -> None:
         '''
         Reset the connection
         '''
@@ -342,12 +365,17 @@ class NetworkConnectionBase(ConnectionBase):
             self.close()
         self.queue_message('vvvv', 'reset call on connection instance')
 
-    def close(self):
+    def close(self) -> None:
         self._conn_closed = True
         if self._connected:
             self._connected = False
 
-    def set_options(self, task_keys=None, var_options=None, direct=None):
+    def set_options(
+        self,
+        task_keys: dict[str, t.Any] | None = None,
+        var_options: dict[str, t.Any] | None = None,
+        direct: dict[str, t.Any] | None = None,
+    ) -> None:
         super(NetworkConnectionBase, self).set_options(task_keys=task_keys, var_options=var_options, direct=direct)
         if self.get_option('persistent_log_messages'):
             warning = "Persistent connection logging is enabled for %s. This will log ALL interactions" % self._play_context.remote_addr
@@ -362,7 +390,7 @@ class NetworkConnectionBase(ConnectionBase):
             except AttributeError:
                 pass
 
-    def _update_connection_state(self):
+    def _update_connection_state(self) -> None:
         '''
         Reconstruct the connection socket_path and check if it exists
 
@@ -385,6 +413,6 @@ class NetworkConnectionBase(ConnectionBase):
             self._connected = True
             self._socket_path = socket_path
 
-    def _log_messages(self, message):
+    def _log_messages(self, message: str) -> None:
         if self.get_option('persistent_log_messages'):
             self.queue_message('log', message)

ansible/plugins/connection/local.py

@@ -2,7 +2,7 @@
 # (c) 2015, 2017 Toshio Kuratomi <tkuratomi@ansible.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-from __future__ import (absolute_import, division, print_function)
+from __future__ import (annotations, absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
@@ -24,12 +24,13 @@ import os
 import pty
 import shutil
 import subprocess
+import typing as t
 
 import ansible.constants as C
 from ansible.errors import AnsibleError, AnsibleFileNotFound
 from ansible.module_utils.compat import selectors
 from ansible.module_utils.six import text_type, binary_type
-from ansible.module_utils._text import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.plugins.connection import ConnectionBase
 from ansible.utils.display import Display
 from ansible.utils.path import unfrackpath
@@ -43,7 +44,7 @@ class Connection(ConnectionBase):
     transport = 'local'
     has_pipelining = True
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
 
         super(Connection, self).__init__(*args, **kwargs)
         self.cwd = None
@@ -53,7 +54,7 @@ class Connection(ConnectionBase):
             display.vv("Current user (uid=%s) does not seem to exist on this system, leaving user empty." % os.getuid())
             self.default_user = ""
 
-    def _connect(self):
+    def _connect(self) -> Connection:
         ''' connect to the local host; nothing to do here '''
 
         # Because we haven't made any remote connection we're running as
@@ -65,7 +66,7 @@ class Connection(ConnectionBase):
             self._connected = True
         return self
 
-    def exec_command(self, cmd, in_data=None, sudoable=True):
+    def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
         ''' run a command on the local host '''
 
         super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
@@ -163,7 +164,7 @@ class Connection(ConnectionBase):
         display.debug("done with local.exec_command()")
         return (p.returncode, stdout, stderr)
 
-    def put_file(self, in_path, out_path):
+    def put_file(self, in_path: str, out_path: str) -> None:
         ''' transfer a file from local to local '''
 
         super(Connection, self).put_file(in_path, out_path)
@@ -181,7 +182,7 @@ class Connection(ConnectionBase):
         except IOError as e:
             raise AnsibleError("failed to transfer file to {0}: {1}".format(to_native(out_path), to_native(e)))
 
-    def fetch_file(self, in_path, out_path):
+    def fetch_file(self, in_path: str, out_path: str) -> None:
         ''' fetch a file from local to local -- for compatibility '''
 
         super(Connection, self).fetch_file(in_path, out_path)
@@ -189,6 +190,6 @@ class Connection(ConnectionBase):
         display.vvv(u"FETCH {0} TO {1}".format(in_path, out_path), host=self._play_context.remote_addr)
         self.put_file(in_path, out_path)
 
-    def close(self):
+    def close(self) -> None:
         ''' terminate the connection; nothing to do here '''
         self._connected = False

ansible/plugins/connection/paramiko_ssh.py

@@ -1,15 +1,15 @@
 # (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
 # (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-from __future__ import (absolute_import, division, print_function)
+from __future__ import (annotations, absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
     author: Ansible Core Team
     name: paramiko
-    short_description: Run tasks via python ssh (paramiko)
+    short_description: Run tasks via Python SSH (paramiko)
     description:
-        - Use the python ssh implementation (Paramiko) to connect to targets
+        - Use the Python SSH implementation (Paramiko) to connect to targets
         - The paramiko transport is provided because many distributions, in particular EL6 and before do not support ControlPersist
           in their SSH implementations.
         - This is needed on the Ansible control machine to be reasonably efficient with connections.
@@ -86,7 +86,7 @@ DOCUMENTATION = """
         description:
             - Whether or not to enable RSA SHA2 algorithms for pubkeys and hostkeys
             - On paramiko versions older than 2.9, this only affects hostkeys
-            - For behavior matching paramiko<2.9 set this to C(False)
+            - For behavior matching paramiko<2.9 set this to V(False)
         vars:
             - name: ansible_paramiko_use_rsa_sha2_algorithms
         ini:
@@ -293,6 +293,7 @@ import tempfile
 import traceback
 import fcntl
 import re
+import typing as t
 
 from ansible.module_utils.compat.version import LooseVersion
 from binascii import hexlify
@@ -307,7 +308,7 @@ from ansible.module_utils.compat.paramiko import PARAMIKO_IMPORT_ERR, paramiko
 from ansible.plugins.connection import ConnectionBase
 from ansible.utils.display import Display
 from ansible.utils.path import makedirs_safe
-from ansible.module_utils._text import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 
 display = Display()
 
@@ -321,8 +322,12 @@ Are you sure you want to continue connecting (yes/no)?
 # SSH Options Regex
 SETTINGS_REGEX = re.compile(r'(\w+)(?:\s*=\s*|\s+)(.+)')
 
+MissingHostKeyPolicy: type = object
+if paramiko:
+    MissingHostKeyPolicy = paramiko.MissingHostKeyPolicy
 
-class MyAddPolicy(object):
+
+class MyAddPolicy(MissingHostKeyPolicy):
     """
     Based on AutoAddPolicy in paramiko so we can determine when keys are added
 
@@ -332,11 +337,11 @@ class MyAddPolicy(object):
     local L{HostKeys} object, and saving it.  This is used by L{SSHClient}.
     """
 
-    def __init__(self, connection):
+    def __init__(self, connection: Connection) -> None:
         self.connection = connection
         self._options = connection._options
 
-    def missing_host_key(self, client, hostname, key):
+    def missing_host_key(self, client, hostname, key) -> None:
 
         if all((self.connection.get_option('host_key_checking'), not self.connection.get_option('host_key_auto_add'))):
 
@@ -367,20 +372,20 @@ class MyAddPolicy(object):
 
 # keep connection objects on a per host basis to avoid repeated attempts to reconnect
 
-SSH_CONNECTION_CACHE = {}  # type: dict[str, paramiko.client.SSHClient]
-SFTP_CONNECTION_CACHE = {}  # type: dict[str, paramiko.sftp_client.SFTPClient]
+SSH_CONNECTION_CACHE: dict[str, paramiko.client.SSHClient] = {}
+SFTP_CONNECTION_CACHE: dict[str, paramiko.sftp_client.SFTPClient] = {}
 
 
 class Connection(ConnectionBase):
     ''' SSH based connections with Paramiko '''
 
     transport = 'paramiko'
-    _log_channel = None
+    _log_channel: str | None = None
 
-    def _cache_key(self):
+    def _cache_key(self) -> str:
         return "%s__%s__" % (self.get_option('remote_addr'), self.get_option('remote_user'))
 
-    def _connect(self):
+    def _connect(self) -> Connection:
         cache_key = self._cache_key()
         if cache_key in SSH_CONNECTION_CACHE:
             self.ssh = SSH_CONNECTION_CACHE[cache_key]
@@ -390,11 +395,11 @@ class Connection(ConnectionBase):
         self._connected = True
         return self
 
-    def _set_log_channel(self, name):
+    def _set_log_channel(self, name: str) -> None:
         '''Mimic paramiko.SSHClient.set_log_channel'''
         self._log_channel = name
 
-    def _parse_proxy_command(self, port=22):
+    def _parse_proxy_command(self, port: int = 22) -> dict[str, t.Any]:
         proxy_command = None
         # Parse ansible_ssh_common_args, specifically looking for ProxyCommand
         ssh_args = [
@@ -439,7 +444,7 @@ class Connection(ConnectionBase):
 
         return sock_kwarg
 
-    def _connect_uncached(self):
+    def _connect_uncached(self) -> paramiko.SSHClient:
         ''' activates the connection object '''
 
         if paramiko is None:
@@ -453,10 +458,11 @@ class Connection(ConnectionBase):
 
         # Set pubkey and hostkey algorithms to disable, the only manipulation allowed currently
         # is keeping or omitting rsa-sha2 algorithms
+        # default_keys: t.Tuple[str] = ()
         paramiko_preferred_pubkeys = getattr(paramiko.Transport, '_preferred_pubkeys', ())
         paramiko_preferred_hostkeys = getattr(paramiko.Transport, '_preferred_keys', ())
         use_rsa_sha2_algorithms = self.get_option('use_rsa_sha2_algorithms')
-        disabled_algorithms = {}
+        disabled_algorithms: t.Dict[str, t.Iterable[str]] = {}
         if not use_rsa_sha2_algorithms:
             if paramiko_preferred_pubkeys:
                 disabled_algorithms['pubkeys'] = tuple(a for a in paramiko_preferred_pubkeys if 'rsa-sha2' in a)
@@ -533,7 +539,7 @@ class Connection(ConnectionBase):
 
         return ssh
 
-    def exec_command(self, cmd, in_data=None, sudoable=True):
+    def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
         ''' run a command on the remote host '''
 
         super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
@@ -576,7 +582,7 @@ class Connection(ConnectionBase):
                     display.debug('Waiting for Privilege Escalation input')
 
                     chunk = chan.recv(bufsize)
-                    display.debug("chunk is: %s" % chunk)
+                    display.debug("chunk is: %r" % chunk)
                     if not chunk:
                         if b'unknown user' in become_output:
                             n_become_user = to_native(self.become.get_option('become_user'))
@@ -606,14 +612,14 @@ class Connection(ConnectionBase):
                     no_prompt_out += become_output
                     no_prompt_err += become_output
         except socket.timeout:
-            raise AnsibleError('ssh timed out waiting for privilege escalation.\n' + become_output)
+            raise AnsibleError('ssh timed out waiting for privilege escalation.\n' + to_text(become_output))
 
         stdout = b''.join(chan.makefile('rb', bufsize))
         stderr = b''.join(chan.makefile_stderr('rb', bufsize))
 
         return (chan.recv_exit_status(), no_prompt_out + stdout, no_prompt_out + stderr)
 
-    def put_file(self, in_path, out_path):
+    def put_file(self, in_path: str, out_path: str) -> None:
         ''' transfer a file from local to remote '''
 
         super(Connection, self).put_file(in_path, out_path)
@@ -633,7 +639,7 @@ class Connection(ConnectionBase):
         except IOError:
             raise AnsibleError("failed to transfer file to %s" % out_path)
 
-    def _connect_sftp(self):
+    def _connect_sftp(self) -> paramiko.sftp_client.SFTPClient:
 
         cache_key = "%s__%s__" % (self.get_option('remote_addr'), self.get_option('remote_user'))
         if cache_key in SFTP_CONNECTION_CACHE:
@@ -642,7 +648,7 @@ class Connection(ConnectionBase):
             result = SFTP_CONNECTION_CACHE[cache_key] = self._connect().ssh.open_sftp()
             return result
 
-    def fetch_file(self, in_path, out_path):
+    def fetch_file(self, in_path: str, out_path: str) -> None:
         ''' save a remote file to the specified path '''
 
         super(Connection, self).fetch_file(in_path, out_path)
@@ -659,7 +665,7 @@ class Connection(ConnectionBase):
         except IOError:
             raise AnsibleError("failed to transfer file from %s" % in_path)
 
-    def _any_keys_added(self):
+    def _any_keys_added(self) -> bool:
 
         for hostname, keys in self.ssh._host_keys.items():
             for keytype, key in keys.items():
@@ -668,14 +674,14 @@ class Connection(ConnectionBase):
                     return True
         return False
 
-    def _save_ssh_host_keys(self, filename):
+    def _save_ssh_host_keys(self, filename: str) -> None:
         '''
         not using the paramiko save_ssh_host_keys function as we want to add new SSH keys at the bottom so folks
         don't complain about it :)
         '''
 
         if not self._any_keys_added():
-            return False
+            return
 
         path = os.path.expanduser("~/.ssh")
         makedirs_safe(path)
@@ -698,13 +704,13 @@ class Connection(ConnectionBase):
                     if added_this_time:
                         f.write("%s %s %s\n" % (hostname, keytype, key.get_base64()))
 
-    def reset(self):
+    def reset(self) -> None:
         if not self._connected:
             return
         self.close()
         self._connect()
 
-    def close(self):
+    def close(self) -> None:
         ''' terminate the connection '''
 
         cache_key = self._cache_key()