ansible-core 2.18.4rc1__py3-none-any.whl → 2.19.0b1__py3-none-any.whl

ansible/plugins/callback/junit.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: junit
     type: aggregate
     short_description: write playbook output to a JUnit file.
@@ -80,14 +80,17 @@ DOCUMENTATION = '''
           - name: JUNIT_TEST_CASE_PREFIX
     requirements:
       - enable in configuration
-'''
+"""
 
+import decimal
 import os
 import time
 import re
 
-from ansible import constants as C
+from ansible import constants
+from ansible.module_utils.common.messages import ErrorSummary
 from ansible.module_utils.common.text.converters import to_bytes, to_text
+from ansible.playbook.task import Task
 from ansible.plugins.callback import CallbackBase
 from ansible.utils._junit_xml import (
     TestCase,
@@ -126,7 +129,7 @@ class CallbackModule(CallbackBase):
                                      Default: True
         JUNIT_HIDE_TASK_ARGUMENTS (optional): Hide the arguments for a task
                                      Default: False
-        JUNIT_TEST_CASE_PREFIX (optional): Consider a task only as test case if it has this value as prefix. Additionally failing tasks are recorded as failed
+        JUNIT_TEST_CASE_PREFIX (optional): Consider a task only as test case if it has this value as prefix. Additionally, failing tasks are recorded as failed
                                      test cases.
                                      Default: <empty>
     """
@@ -136,7 +139,7 @@ class CallbackModule(CallbackBase):
     CALLBACK_NAME = 'junit'
     CALLBACK_NEEDS_ENABLED = True
 
-    def __init__(self):
+    def __init__(self) -> None:
         super(CallbackModule, self).__init__()
 
         self._output_dir = os.getenv('JUNIT_OUTPUT_DIR', os.path.expanduser('~/.ansible.log'))
@@ -150,20 +153,18 @@ class CallbackModule(CallbackBase):
         self._replace_out_of_tree_path = os.getenv('JUNIT_REPLACE_OUT_OF_TREE_PATH', None)
         self._playbook_path = None
         self._playbook_name = None
-        self._play_name = None
-        self._task_data = None
+        self._play_name: str | None = None
+        self._task_data: dict[str, TaskData] = {}
 
         self.disabled = False
 
-        self._task_data = {}
-
         if self._replace_out_of_tree_path is not None:
             self._replace_out_of_tree_path = to_text(self._replace_out_of_tree_path)
 
         if not os.path.exists(self._output_dir):
             os.makedirs(self._output_dir)
 
-    def _start_task(self, task):
+    def _start_task(self, task: Task) -> None:
         """ record the start of a task for one or more hosts """
 
         uuid = task._uuid
@@ -212,11 +213,11 @@ class CallbackModule(CallbackBase):
         if task_data.name.startswith(self._test_case_prefix) or status == 'failed':
             task_data.add_host(HostData(host_uuid, host_name, status, result))
 
-    def _build_test_case(self, task_data, host_data):
+    def _build_test_case(self, task_data: TaskData, host_data: HostData) -> TestCase:
         """ build a TestCase from the given TaskData and HostData """
 
         name = '[%s] %s: %s' % (host_data.name, task_data.play, task_data.name)
-        duration = host_data.finish - task_data.start
+        duration = decimal.Decimal(host_data.finish - task_data.start)
 
         if self._task_relative_path and task_data.path:
             junit_classname = to_text(os.path.relpath(to_bytes(task_data.path), to_bytes(self._task_relative_path)))
@@ -242,10 +243,12 @@ class CallbackModule(CallbackBase):
 
         test_case = TestCase(name=name, classname=junit_classname, time=duration)
 
+        error_summary: ErrorSummary
+
         if host_data.status == 'failed':
-            if 'exception' in res:
-                message = res['exception'].strip().split('\n')[-1]
-                output = res['exception']
+            if error_summary := res.get('exception'):
+                message = error_summary._format()
+                output = error_summary.formatted_traceback
                 test_case.errors.append(TestError(message=message, output=output))
             elif 'msg' in res:
                 message = res['msg']
@@ -261,7 +264,8 @@ class CallbackModule(CallbackBase):
 
         return test_case
 
-    def _cleanse_string(self, value):
+    @staticmethod
+    def _cleanse_string(value):
         """ convert surrogate escapes to the unicode replacement character to avoid XML encoding errors """
         return to_text(to_bytes(value, errors='surrogateescape'), errors='replace')
 
@@ -271,7 +275,7 @@ class CallbackModule(CallbackBase):
         test_cases = []
 
         for task_uuid, task_data in self._task_data.items():
-            if task_data.action in C._ACTION_SETUP and self._include_setup_tasks_in_report == 'false':
+            if task_data.action in constants._ACTION_SETUP and self._include_setup_tasks_in_report == 'false':
                 continue
 
             for host_uuid, host_data in task_data.host_data.items():
@@ -293,16 +297,16 @@ class CallbackModule(CallbackBase):
     def v2_playbook_on_play_start(self, play):
         self._play_name = play.get_name()
 
-    def v2_runner_on_no_hosts(self, task):
+    def v2_runner_on_no_hosts(self, task: Task) -> None:
         self._start_task(task)
 
-    def v2_playbook_on_task_start(self, task, is_conditional):
+    def v2_playbook_on_task_start(self, task: Task, is_conditional: bool) -> None:
         self._start_task(task)
 
-    def v2_playbook_on_cleanup_task_start(self, task):
+    def v2_playbook_on_cleanup_task_start(self, task: Task) -> None:
         self._start_task(task)
 
-    def v2_playbook_on_handler_task_start(self, task):
+    def v2_playbook_on_handler_task_start(self, task: Task) -> None:
         self._start_task(task)
 
     def v2_runner_on_failed(self, result, ignore_errors=False):
@@ -329,17 +333,17 @@ class TaskData:
     Data about an individual task.
     """
 
-    def __init__(self, uuid, name, path, play, action):
+    def __init__(self, uuid: str, name: str, path: str, play: str, action: str) -> None:
         self.uuid = uuid
         self.name = name
         self.path = path
         self.play = play
         self.start = None
-        self.host_data = {}
+        self.host_data: dict[str, HostData] = {}
         self.start = time.time()
         self.action = action
 
-    def add_host(self, host):
+    def add_host(self, host: HostData) -> None:
         if host.uuid in self.host_data:
             if host.status == 'included':
                 # concatenate task include output from multiple items

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 TaskResult
 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,20 +41,18 @@ class CallbackModule(CallbackBase):
 
         return buf + "\n"
 
-    def v2_runner_on_failed(self, result, ignore_errors=False):
-
-        self._handle_exception(result._result)
-        self._handle_warnings(result._result)
+    def v2_runner_on_failed(self, result: TaskResult, ignore_errors: bool = False) -> None:
+        self._handle_warnings_and_exception(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)
         else:
             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: TaskResult) -> 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):
             color = C.COLOR_CHANGED
@@ -67,10 +66,14 @@ class CallbackModule(CallbackBase):
         else:
             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):
+    def v2_runner_on_skipped(self, result: TaskResult) -> None:
+        self._handle_warnings_and_exception(result)
+
         self._display.display("%s | SKIPPED" % (result._host.get_name()), color=C.COLOR_SKIP)
 
-    def v2_runner_on_unreachable(self, result):
+    def v2_runner_on_unreachable(self, result: TaskResult) -> None:
+        self._handle_warnings_and_exception(result)
+
         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):

ansible/plugins/callback/oneline.py

@@ -4,30 +4,35 @@
 
 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
 
 
 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']:
@@ -38,12 +43,13 @@ class CallbackModule(CallbackBase):
 
     def v2_runner_on_failed(self, result, ignore_errors=False):
         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)

ansible/plugins/callback/tree.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: tree
     type: notification
     requirements:
@@ -25,7 +25,7 @@ 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
 
@@ -36,17 +36,21 @@ 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 +61,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:

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,