ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/plugins/callback/minimal.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: minimal
     type: stdout
     short_description: minimal Ansible screen output
@@ -13,25 +13,26 @@ DOCUMENTATION = '''
         - This is the default output callback used by the ansible command (ad-hoc)
     extends_documentation_fragment:
       - result_format_callback
-'''
+"""
 
+from ansible.executor.task_result import CallbackTaskResult
 from ansible.plugins.callback import CallbackBase
 from ansible import constants as C
 
 
 class CallbackModule(CallbackBase):
 
-    '''
+    """
     This is the default callback interface, which simply prints messages
     to stdout when new callback events are received.
-    '''
+    """
 
     CALLBACK_VERSION = 2.0
     CALLBACK_TYPE = 'stdout'
     CALLBACK_NAME = 'minimal'
 
     def _command_generic_msg(self, host, result, caption):
-        ''' output the result of a command run '''
+        """ output the result of a command run """
 
         buf = "%s | %s | rc=%s >>\n" % (host, caption, result.get('rc', -1))
         buf += result.get('stdout', '')
@@ -40,39 +41,41 @@ class CallbackModule(CallbackBase):
 
         return buf + "\n"
 
-    def v2_runner_on_failed(self, result, ignore_errors=False):
+    def v2_runner_on_failed(self, result: CallbackTaskResult, ignore_errors: bool = False) -> None:
+        self._handle_warnings_and_exception(result)
 
-        self._handle_exception(result._result)
-        self._handle_warnings(result._result)
-
-        if result._task.action in C.MODULE_NO_JSON and 'module_stderr' not in result._result:
-            self._display.display(self._command_generic_msg(result._host.get_name(), result._result, "FAILED"), color=C.COLOR_ERROR)
+        if result.task.action in C.MODULE_NO_JSON and 'module_stderr' not in result.result:
+            self._display.display(self._command_generic_msg(result.host.get_name(), result.result, "FAILED"), color=C.COLOR_ERROR)
         else:
-            self._display.display("%s | FAILED! => %s" % (result._host.get_name(), self._dump_results(result._result, indent=4)), color=C.COLOR_ERROR)
+            self._display.display("%s | FAILED! => %s" % (result.host.get_name(), self._dump_results(result.result, indent=4)), color=C.COLOR_ERROR)
 
-    def v2_runner_on_ok(self, result):
-        self._clean_results(result._result, result._task.action)
+    def v2_runner_on_ok(self, result: CallbackTaskResult) -> None:
+        self._handle_warnings_and_exception(result)
 
-        self._handle_warnings(result._result)
+        self._clean_results(result.result, result.task.action)
 
-        if result._result.get('changed', False):
+        if result.result.get('changed', False):
             color = C.COLOR_CHANGED
             state = 'CHANGED'
         else:
             color = C.COLOR_OK
             state = 'SUCCESS'
 
-        if result._task.action in C.MODULE_NO_JSON and 'ansible_job_id' not in result._result:
-            self._display.display(self._command_generic_msg(result._host.get_name(), result._result, state), color=color)
+        if result.task.action in C.MODULE_NO_JSON and 'ansible_job_id' not in result.result:
+            self._display.display(self._command_generic_msg(result.host.get_name(), result.result, state), color=color)
         else:
-            self._display.display("%s | %s => %s" % (result._host.get_name(), state, self._dump_results(result._result, indent=4)), color=color)
+            self._display.display("%s | %s => %s" % (result.host.get_name(), state, self._dump_results(result.result, indent=4)), color=color)
+
+    def v2_runner_on_skipped(self, result: CallbackTaskResult) -> None:
+        self._handle_warnings_and_exception(result)
+
+        self._display.display("%s | SKIPPED" % (result.host.get_name()), color=C.COLOR_SKIP)
 
-    def v2_runner_on_skipped(self, result):
-        self._display.display("%s | SKIPPED" % (result._host.get_name()), color=C.COLOR_SKIP)
+    def v2_runner_on_unreachable(self, result: CallbackTaskResult) -> None:
+        self._handle_warnings_and_exception(result)
 
-    def v2_runner_on_unreachable(self, result):
-        self._display.display("%s | UNREACHABLE! => %s" % (result._host.get_name(), self._dump_results(result._result, indent=4)), color=C.COLOR_UNREACHABLE)
+        self._display.display("%s | UNREACHABLE! => %s" % (result.host.get_name(), self._dump_results(result.result, indent=4)), color=C.COLOR_UNREACHABLE)
 
     def v2_on_file_diff(self, result):
-        if 'diff' in result._result and result._result['diff']:
-            self._display.display(self._get_diff(result._result['diff']))
+        if 'diff' in result.result and result.result['diff']:
+            self._display.display(self._get_diff(result.result['diff']))

ansible/plugins/callback/oneline.py

@@ -4,30 +4,36 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: oneline
     type: stdout
     short_description: oneline Ansible screen output
     version_added: historical
     description:
         - This is the output callback used by the C(-o)/C(--one-line) command line option.
-'''
+"""
 
-from ansible.plugins.callback import CallbackBase
 from ansible import constants as C
+from ansible.plugins.callback import CallbackBase
+from ansible.template import Templar
+from ansible.executor.task_result import CallbackTaskResult
 
 
 class CallbackModule(CallbackBase):
 
-    '''
+    """
     This is the default callback interface, which simply prints messages
     to stdout when new callback events are received.
-    '''
+    """
 
     CALLBACK_VERSION = 2.0
     CALLBACK_TYPE = 'stdout'
     CALLBACK_NAME = 'oneline'
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._display.deprecated('The oneline callback plugin is deprecated.', version='2.23')
+
     def _command_generic_msg(self, hostname, result, caption):
         stdout = result.get('stdout', '').replace('\n', '\\n').replace('\r', '\\r')
         if 'stderr' in result and result['stderr']:
@@ -36,40 +42,41 @@ class CallbackModule(CallbackBase):
         else:
             return "%s | %s | rc=%s | (stdout) %s" % (hostname, caption, result.get('rc', -1), stdout)
 
-    def v2_runner_on_failed(self, result, ignore_errors=False):
-        if 'exception' in result._result:
+    def v2_runner_on_failed(self, result: CallbackTaskResult, ignore_errors: bool = False) -> None:
+        if 'exception' in result.result:
+            error_text = Templar().template(result.result['exception'])  # transform to a string
             if self._display.verbosity < 3:
                 # extract just the actual error message from the exception text
-                error = result._result['exception'].strip().split('\n')[-1]
+                error = error_text.strip().split('\n')[-1]
                 msg = "An exception occurred during task execution. To see the full traceback, use -vvv. The error was: %s" % error
             else:
-                msg = "An exception occurred during task execution. The full traceback is:\n" + result._result['exception'].replace('\n', '')
+                msg = "An exception occurred during task execution. The full traceback is:\n" + error_text.replace('\n', '')
 
-            if result._task.action in C.MODULE_NO_JSON and 'module_stderr' not in result._result:
-                self._display.display(self._command_generic_msg(result._host.get_name(), result._result, 'FAILED'), color=C.COLOR_ERROR)
+            if result.task.action in C.MODULE_NO_JSON and 'module_stderr' not in result.result:
+                self._display.display(self._command_generic_msg(result.host.get_name(), result.result, 'FAILED'), color=C.COLOR_ERROR)
             else:
                 self._display.display(msg, color=C.COLOR_ERROR)
 
-        self._display.display("%s | FAILED! => %s" % (result._host.get_name(), self._dump_results(result._result, indent=0).replace('\n', '')),
+        self._display.display("%s | FAILED! => %s" % (result.host.get_name(), self._dump_results(result.result, indent=0).replace('\n', '')),
                               color=C.COLOR_ERROR)
 
-    def v2_runner_on_ok(self, result):
+    def v2_runner_on_ok(self, result: CallbackTaskResult) -> None:
 
-        if result._result.get('changed', False):
+        if result.result.get('changed', False):
             color = C.COLOR_CHANGED
             state = 'CHANGED'
         else:
             color = C.COLOR_OK
             state = 'SUCCESS'
 
-        if result._task.action in C.MODULE_NO_JSON and 'ansible_job_id' not in result._result:
-            self._display.display(self._command_generic_msg(result._host.get_name(), result._result, state), color=color)
+        if result.task.action in C.MODULE_NO_JSON and 'ansible_job_id' not in result.result:
+            self._display.display(self._command_generic_msg(result.host.get_name(), result.result, state), color=color)
         else:
-            self._display.display("%s | %s => %s" % (result._host.get_name(), state, self._dump_results(result._result, indent=0).replace('\n', '')),
+            self._display.display("%s | %s => %s" % (result.host.get_name(), state, self._dump_results(result.result, indent=0).replace('\n', '')),
                                   color=color)
 
-    def v2_runner_on_unreachable(self, result):
-        self._display.display("%s | UNREACHABLE!: %s" % (result._host.get_name(), result._result.get('msg', '')), color=C.COLOR_UNREACHABLE)
+    def v2_runner_on_unreachable(self, result: CallbackTaskResult) -> None:
+        self._display.display("%s | UNREACHABLE!: %s" % (result.host.get_name(), result.result.get('msg', '')), color=C.COLOR_UNREACHABLE)
 
-    def v2_runner_on_skipped(self, result):
-        self._display.display("%s | SKIPPED" % (result._host.get_name()), color=C.COLOR_SKIP)
+    def v2_runner_on_skipped(self, result: CallbackTaskResult) -> None:
+        self._display.display("%s | SKIPPED" % (result.host.get_name()), color=C.COLOR_SKIP)

ansible/plugins/callback/tree.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: tree
     type: notification
     requirements:
@@ -25,28 +25,33 @@ DOCUMENTATION = '''
     description:
         - "This callback is used by the Ansible (adhoc) command line option C(-t|--tree)."
         - This produces a JSON dump of events in a directory, a file for each host, the directory used MUST be passed as a command line option.
-'''
+"""
 
 import os
 
 from ansible.constants import TREE_DIR
+from ansible.executor.task_result import CallbackTaskResult
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.plugins.callback import CallbackBase
 from ansible.utils.path import makedirs_safe, unfrackpath
 
 
 class CallbackModule(CallbackBase):
-    '''
+    """
     This callback puts results into a host specific file in a directory in json format.
-    '''
+    """
 
     CALLBACK_VERSION = 2.0
     CALLBACK_TYPE = 'aggregate'
     CALLBACK_NAME = 'tree'
     CALLBACK_NEEDS_ENABLED = True
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._display.deprecated('The tree callback plugin is deprecated.', version='2.23')
+
     def set_options(self, task_keys=None, var_options=None, direct=None):
-        ''' override to set self.tree '''
+        """ override to set self.tree """
 
         super(CallbackModule, self).set_options(task_keys=task_keys, var_options=var_options, direct=direct)
 
@@ -57,7 +62,7 @@ class CallbackModule(CallbackBase):
             self.tree = self.get_option('directory')
 
     def write_tree_file(self, hostname, buf):
-        ''' write something into treedir/hostname '''
+        """ write something into treedir/hostname """
 
         buf = to_bytes(buf)
         try:
@@ -72,14 +77,14 @@ class CallbackModule(CallbackBase):
         except (OSError, IOError) as e:
             self._display.warning(u"Unable to write to %s's file: %s" % (hostname, to_text(e)))
 
-    def result_to_tree(self, result):
-        self.write_tree_file(result._host.get_name(), self._dump_results(result._result))
+    def result_to_tree(self, result: CallbackTaskResult) -> None:
+        self.write_tree_file(result.host.get_name(), self._dump_results(result.result))
 
-    def v2_runner_on_ok(self, result):
+    def v2_runner_on_ok(self, result: CallbackTaskResult) -> None:
         self.result_to_tree(result)
 
-    def v2_runner_on_failed(self, result, ignore_errors=False):
+    def v2_runner_on_failed(self, result: CallbackTaskResult, ignore_errors: bool = False) -> None:
         self.result_to_tree(result)
 
-    def v2_runner_on_unreachable(self, result):
+    def v2_runner_on_unreachable(self, result: CallbackTaskResult) -> None:
         self.result_to_tree(result)

ansible/plugins/connection/__init__.py

@@ -15,6 +15,7 @@ from abc import abstractmethod
 from functools import wraps
 
 from ansible import constants as C
+from ansible.errors import AnsibleValueOmittedError
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.playbook.play_context import PlayContext
 from ansible.plugins import AnsiblePlugin
@@ -35,6 +36,12 @@ P = t.ParamSpec('P')
 T = t.TypeVar('T')
 
 
+class ConnectionKwargs(t.TypedDict):
+    task_uuid: str
+    ansible_playbook_pid: str
+    shell: t.NotRequired[ShellBase]
+
+
 def ensure_connect(
     func: c.Callable[t.Concatenate[ConnectionBase, P], T],
 ) -> c.Callable[t.Concatenate[ConnectionBase, P], T]:
@@ -47,9 +54,9 @@ def ensure_connect(
 
 
 class ConnectionBase(AnsiblePlugin):
-    '''
+    """
     A base class for connections to contain common code.
-    '''
+    """
 
     has_pipelining = False
     has_native_async = False  # eg, winrm
@@ -71,10 +78,8 @@ class ConnectionBase(AnsiblePlugin):
     def __init__(
         self,
         play_context: PlayContext,
-        new_stdin: io.TextIOWrapper | None = None,
-        shell: ShellBase | None = None,
         *args: t.Any,
-        **kwargs: t.Any,
+        **kwargs: t.Unpack[ConnectionKwargs],
     ) -> None:
 
         super(ConnectionBase, self).__init__()
@@ -83,9 +88,6 @@ class ConnectionBase(AnsiblePlugin):
         if not hasattr(self, '_play_context'):
             # Backwards compat: self._play_context isn't really needed, using set_options/get_option
             self._play_context = play_context
-        # Delete once the deprecation period is over for WorkerProcess._new_stdin
-        if not hasattr(self, '__new_stdin'):
-            self.__new_stdin = new_stdin
         if not hasattr(self, '_display'):
             # Backwards compat: self._display isn't really needed, just import the global display and use that.
             self._display = display
@@ -95,36 +97,25 @@ class ConnectionBase(AnsiblePlugin):
         self._connected = False
         self._socket_path: str | None = None
 
-        # helper plugins
-        self._shell = shell
-
         # we always must have shell
-        if not self._shell:
+        if not (shell := kwargs.get('shell')):
             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)
+            shell = get_shell_plugin(shell_type=shell_type, executable=self._play_context.executable)
+        self._shell = shell
 
         self.become: BecomeBase | None = None
 
-    @property
-    def _new_stdin(self) -> io.TextIOWrapper | None:
-        display.deprecated(
-            "The connection's stdin object is deprecated. "
-            "Call display.prompt_until(msg) instead.",
-            version='2.19',
-        )
-        return self.__new_stdin
-
     def set_become_plugin(self, plugin: BecomeBase) -> None:
         self.become = plugin
 
     @property
     def connected(self) -> bool:
-        '''Read-only property holding whether the connection to the remote host is active or closed.'''
+        """Read-only property holding whether the connection to the remote host is active or closed."""
         return self._connected
 
     @property
     def socket_path(self) -> str | None:
-        '''Read-only property holding the connection socket path for this remote host'''
+        """Read-only property holding the connection socket path for this remote host"""
         return self._socket_path
 
     @staticmethod
@@ -247,10 +238,10 @@ class ConnectionBase(AnsiblePlugin):
         display.warning("Reset is not implemented for this connection")
 
     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.
-        '''
+        """
         for varname in C.COMMON_CONNECTION_VARS:
             value = None
             if varname in variables:
@@ -296,16 +287,39 @@ class ConnectionBase(AnsiblePlugin):
         }
         for var_name in C.config.get_plugin_vars('connection', self._load_name):
             if var_name in variables:
-                var_options[var_name] = templar.template(variables[var_name])
+                try:
+                    var_options[var_name] = templar.template(variables[var_name])
+                except AnsibleValueOmittedError:
+                    pass
 
         # add extras if plugin supports them
         if getattr(self, 'allow_extras', False):
             for var_name in variables:
                 if var_name.startswith(f'ansible_{self.extras_prefix}_') and var_name not in var_options:
-                    var_options['_extras'][var_name] = templar.template(variables[var_name])
+                    try:
+                        var_options['_extras'][var_name] = templar.template(variables[var_name])
+                    except AnsibleValueOmittedError:
+                        pass
 
         return var_options
 
+    def is_pipelining_enabled(self, wrap_async: bool = False) -> bool:
+
+        is_enabled = False
+        if self.has_pipelining and (not self.become or self.become.pipelining):
+            try:
+                is_enabled = self.get_option('pipelining')
+            except KeyError:
+                is_enabled = getattr(self._play_context, 'pipelining', False)
+
+        # TODO: deprecate always_pipeline_modules and has_native_async in favor for each plugin overriding this function
+        conditions = [
+            is_enabled or self.always_pipeline_modules,       # enabled via config or forced via connection (eg winrm)
+            not C.DEFAULT_KEEP_REMOTE_FILES,                  # user wants remote files
+            not wrap_async or self.has_native_async,          # async does not normally support pipelining unless it does (eg winrm)
+        ]
+        return all(conditions)
+
 
 class NetworkConnectionBase(ConnectionBase):
     """
@@ -319,11 +333,10 @@ class NetworkConnectionBase(ConnectionBase):
     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)
+        super(NetworkConnectionBase, self).__init__(play_context, *args, **kwargs)
         self._messages: list[tuple[str, str]] = []
         self._conn_closed = False
 
@@ -377,9 +390,9 @@ class NetworkConnectionBase(ConnectionBase):
         return self._local.fetch_file(in_path, out_path)
 
     def reset(self) -> None:
-        '''
+        """
         Reset the connection
-        '''
+        """
         if self._socket_path:
             self.queue_message('vvvv', 'resetting persistent connection for socket_path %s' % self._socket_path)
             self.close()
@@ -411,14 +424,14 @@ class NetworkConnectionBase(ConnectionBase):
                 pass
 
     def _update_connection_state(self) -> None:
-        '''
+        """
         Reconstruct the connection socket_path and check if it exists
 
         If the socket path exists then the connection is active and set
         both the _socket_path value to the path and the _connected value
         to True.  If the socket path doesn't exist, leave the socket path
         value to None and the _connected value to False
-        '''
+        """
         ssh = connection_loader.get('ssh', class_only=True)
         control_path = ssh._create_control_path(
             self._play_context.remote_addr, self._play_context.port,