ansible-core 2.19.0b4__py3-none-any.whl → 2.19.0b6__py3-none-any.whl

ansible/_internal/_templating/_jinja_plugins.py

@@ -6,8 +6,12 @@ import collections.abc as c
 import dataclasses
 import datetime
 import functools
+import inspect
+import re
 import typing as t
 
+from jinja2 import defaults
+
 from ansible.module_utils._internal._ambient_context import AmbientContextBase
 from ansible.module_utils.common.collections import is_sequence
 from ansible.module_utils._internal._datatag import AnsibleTagHelper
@@ -115,7 +119,7 @@ class JinjaPluginIntercept(c.MutableMapping):
         except MarkerError as ex:
             return ex.source
         except Exception as ex:
-            raise AnsibleTemplatePluginRuntimeError(instance.plugin_type, instance.ansible_name) from ex  # DTFIX-RELEASE: which name to use? use plugin info?
+            raise AnsibleTemplatePluginRuntimeError(instance.plugin_type, instance.ansible_name) from ex  # DTFIX-FUTURE: which name to use? use plugin info?
 
     def _wrap_test(self, instance: AnsibleJinja2Plugin) -> t.Callable:
         """Intercept point for all test plugins to ensure that args are properly templated/lazified."""
@@ -124,10 +128,12 @@ class JinjaPluginIntercept(c.MutableMapping):
         def wrapper(*args, **kwargs) -> bool | Marker:
             result = self._invoke_plugin(instance, *args, **kwargs)
 
+            if isinstance(result, Marker):
+                return result
+
             if not isinstance(result, bool):
                 template = TemplateContext.current().template_value
 
-                # DTFIX-RELEASE: which name to use? use plugin info?
                 _display.deprecated(
                     msg=f"The test plugin {instance.ansible_name!r} returned a non-boolean result of type {type(result)!r}. "
                     "Test plugins must have a boolean result.",
@@ -157,7 +163,7 @@ class JinjaPluginIntercept(c.MutableMapping):
 class _DirectCall:
     """Functions/methods marked `_DirectCall` bypass Jinja Environment checks for `Marker`."""
 
-    _marker_attr: str = "_directcall"
+    _marker_attr: t.Final[str] = "_directcall"
 
     @classmethod
     def mark(cls, src: _TCallable) -> _TCallable:
@@ -166,7 +172,7 @@ class _DirectCall:
 
     @classmethod
     def is_marked(cls, value: t.Callable) -> bool:
-        return callable(value) and getattr(value, "_directcall", False)
+        return callable(value) and getattr(value, cls._marker_attr, False)
 
 
 @_DirectCall.mark
@@ -254,7 +260,7 @@ def _invoke_lookup(*, plugin_name: str, lookup_terms: list, lookup_kwargs: dict[
         except MarkerError as ex:
             return ex.source
         except Exception as ex:
-            # DTFIX-RELEASE: convert this to the new error/warn/ignore context manager
+            # DTFIX-FUTURE: convert this to the new error/warn/ignore context manager
             if errors == 'warn':
                 _display.error_as_warning(
                     msg=f'An error occurred while running the lookup plugin {plugin_name!r}.',
@@ -339,3 +345,28 @@ def _wrap_plugin_output(o: t.Any) -> t.Any:
         o = list(o)
 
     return _AnsibleLazyTemplateMixin._try_create(o, LazyOptions.SKIP_TEMPLATES)
+
+
+_PLUGIN_SOURCES = dict(
+    filter=defaults.DEFAULT_FILTERS,
+    test=defaults.DEFAULT_TESTS,
+)
+
+
+def _get_builtin_short_description(plugin: object) -> str:
+    """
+    Make a reasonable effort to break a function docstring down to a single sentence.
+    We can't use the full docstring due to embedded formatting, particularly RST.
+    This isn't intended to be perfect, just good enough until we can write our own docs for these.
+    """
+    value = re.split(r'(\.|!|\s\(|:\s)', inspect.getdoc(plugin), 1)[0].replace('\n', ' ')
+
+    if value:
+        value += '.'
+
+    return value
+
+
+def get_jinja_builtin_plugin_descriptions(plugin_type: str) -> dict[str, str]:
+    """Returns a dictionary of Jinja builtin plugin names and their short descriptions."""
+    return {f'ansible.builtin.{name}': _get_builtin_short_description(plugin) for name, plugin in _PLUGIN_SOURCES[plugin_type].items() if name.isidentifier()}

ansible/_internal/_templating/_lazy_containers.py

@@ -43,7 +43,7 @@ _KNOWN_TYPES: t.Final[set[type]] = (
         TemplateModule,  # example: '{% import "importme.j2" as im %}{{ im | type_debug }}'
     }
     | set(PASS_THROUGH_SCALAR_VAR_TYPES)
-    | set(Marker.concrete_subclasses)
+    | set(Marker._concrete_subclasses)
 )
 """
 These types are known to the templating system.
@@ -195,7 +195,7 @@ class _AnsibleLazyTemplateMixin:
         Return an iterable that wraps each of the given elements in a lazy wrapper.
         Only elements wrapped this way will receive lazy processing when retrieved from the collection.
         """
-        # DTFIX-RELEASE: check relative performance of method-local vs stored generator expressions on implementations of this method
+        # DTFIX-FUTURE: check relative performance of method-local vs stored generator expressions on implementations of this method
         raise NotImplementedError()  # pragma: nocover
 
     def _proxy_or_render_lazy_value(self, key: t.Any, value: t.Any) -> t.Any:
@@ -346,13 +346,13 @@ class _AnsibleLazyTemplateDict(_AnsibleTaggedDict, _AnsibleLazyTemplateMixin):
         return super().__ne__(other)
 
     def __or__(self, other):
-        # DTFIX-RELEASE: support preservation of laziness when possible like we do for list
+        # DTFIX-FUTURE: support preservation of laziness when possible like we do for list
         # Both sides end up going through _proxy_or_render_lazy_value, so there's no Templar preservation needed.
         # In the future this could be made more lazy when both Templar instances are the same, or if per-value Templar tracking was used.
         return super().__or__(other)
 
     def __ror__(self, other):
-        # DTFIX-RELEASE: support preservation of laziness when possible like we do for list
+        # DTFIX-FUTURE: support preservation of laziness when possible like we do for list
         # Both sides end up going through _proxy_or_render_lazy_value, so there's no Templar preservation needed.
         # In the future this could be made more lazy when both Templar instances are the same, or if per-value Templar tracking was used.
         return super().__ror__(other)
@@ -549,7 +549,7 @@ class _AnsibleLazyAccessTuple(_AnsibleTaggedTuple, _AnsibleLazyTemplateMixin):
     created as a results of managed access.
     """
 
-    # DTFIX-RELEASE: ensure we have tests that explicitly verify this behavior
+    # DTFIX5: ensure we have tests that explicitly verify this behavior
 
     # nonempty __slots__ not supported for subtype of 'tuple'
 

ansible/_internal/_templating/_template_vars.py

@@ -0,0 +1,72 @@
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+import os as _os
+import pwd as _pwd
+import time as _time
+
+from ansible import constants as _constants
+from ansible.module_utils._internal import _datatag
+
+
+def generate_ansible_template_vars(
+    path: str,
+    fullpath: str | None = None,
+    dest_path: str | None = None,
+    include_ansible_managed: bool = True,
+) -> dict[str, object]:
+    """
+    Generate and return a dictionary with variable metadata about the template specified by `fullpath`.
+    If `fullpath` is `None`, `path` will be used instead.
+    """
+    # deprecated description="update the ansible.windows collection to inline this logic instead of calling this internal function" core_version="2.23"
+    if fullpath is None:
+        fullpath = _os.path.abspath(path)
+
+    template_path = fullpath
+    template_stat = _os.stat(template_path)
+
+    template_uid: int | str
+
+    try:
+        template_uid = _pwd.getpwuid(template_stat.st_uid).pw_name
+    except KeyError:
+        template_uid = template_stat.st_uid
+
+    temp_vars = dict(
+        template_host=_os.uname()[1],
+        template_path=path,
+        template_mtime=_datetime.datetime.fromtimestamp(template_stat.st_mtime),
+        template_uid=template_uid,
+        template_run_date=_datetime.datetime.now(),
+        template_destpath=dest_path,
+        template_fullpath=fullpath,
+    )
+
+    if include_ansible_managed:  # only inject the config default value if the variable wasn't set
+        temp_vars['ansible_managed'] = _generate_ansible_managed(template_stat)
+
+    return temp_vars
+
+
+def _generate_ansible_managed(template_stat: _os.stat_result) -> str:
+    """Generate and return the `ansible_managed` variable."""
+    # deprecated description="remove the `_generate_ansible_managed` function and use a constant instead" core_version="2.23"
+
+    from ansible.template import trust_as_template
+
+    managed_default = _constants.config.get_config_value('DEFAULT_MANAGED_STR')
+
+    managed_str = managed_default.format(
+        # IMPORTANT: These values must be constant strings to avoid template injection.
+        #            Use Jinja template expressions where variables are needed.
+        host="{{ template_host }}",
+        uid="{{ template_uid }}",
+        file="{{ template_path }}",
+    )
+
+    ansible_managed = _time.strftime(managed_str, _time.localtime(template_stat.st_mtime))
+    ansible_managed = _datatag.AnsibleTagHelper.tag_copy(managed_default, ansible_managed)
+    ansible_managed = trust_as_template(ansible_managed)
+
+    return ansible_managed

ansible/_internal/_templating/_transform.py

@@ -5,39 +5,46 @@ from __future__ import annotations
 import dataclasses
 import typing as t
 
-from ansible.module_utils._internal import _traceback
-from ansible.module_utils.common.messages import PluginInfo, ErrorSummary, WarningSummary, DeprecationSummary
+from ansible.module_utils._internal import _traceback, _event_utils, _messages
 from ansible.parsing.vault import EncryptedString, VaultHelper
 from ansible.utils.display import Display
 
 from ._jinja_common import VaultExceptionMarker
-from .._errors import _captured, _utils
+from .._errors import _captured, _error_factory
+from .. import _event_formatting
 
 display = Display()
 
 
-def plugin_info(value: PluginInfo) -> dict[str, str]:
+def plugin_info(value: _messages.PluginInfo) -> dict[str, str]:
     """Render PluginInfo as a dictionary."""
     return dataclasses.asdict(value)
 
 
-def error_summary(value: ErrorSummary) -> str:
+def plugin_type(value: _messages.PluginType) -> str:
+    """Render PluginType as a string."""
+    return value.value
+
+
+def error_summary(value: _messages.ErrorSummary) -> str:
     """Render ErrorSummary as a formatted traceback for backward-compatibility with pre-2.19 TaskResult.exception."""
-    return value.formatted_traceback or '(traceback unavailable)'
+    if _traceback._is_traceback_enabled(_traceback.TracebackEvent.ERROR):
+        return _event_formatting.format_event_traceback(value.event)
+
+    return '(traceback unavailable)'
 
 
-def warning_summary(value: WarningSummary) -> str:
+def warning_summary(value: _messages.WarningSummary) -> str:
     """Render WarningSummary as a simple message string for backward-compatibility with pre-2.19 TaskResult.warnings."""
-    return value._format()
+    return _event_utils.format_event_brief_message(value.event)
 
 
-def deprecation_summary(value: DeprecationSummary) -> dict[str, t.Any]:
+def deprecation_summary(value: _messages.DeprecationSummary) -> dict[str, t.Any]:
     """Render DeprecationSummary as dict values for backward-compatibility with pre-2.19 TaskResult.deprecations."""
-    # DTFIX-RELEASE: reconsider which deprecation fields should be exposed here, taking into account that collection_name is to be deprecated
-    result = value._as_simple_dict()
-    result.pop('details')
+    transformed = _event_utils.deprecation_as_dict(value)
+    transformed.update(deprecator=value.deprecator)
 
-    return result
+    return transformed
 
 
 def encrypted_string(value: EncryptedString) -> str | VaultExceptionMarker:
@@ -47,17 +54,17 @@ def encrypted_string(value: EncryptedString) -> str | VaultExceptionMarker:
     except Exception as ex:
         return VaultExceptionMarker(
             ciphertext=VaultHelper.get_ciphertext(value, with_tags=True),
-            reason=_utils.get_chained_message(ex),
-            traceback=_traceback.maybe_extract_traceback(ex, _traceback.TracebackEvent.ERROR),
+            event=_error_factory.ControllerEventFactory.from_exception(ex, _traceback.is_traceback_enabled(_traceback.TracebackEvent.ERROR)),
         )
 
 
 _type_transform_mapping: dict[type, t.Callable[[t.Any], t.Any]] = {
     _captured.CapturedErrorSummary: error_summary,
-    PluginInfo: plugin_info,
-    ErrorSummary: error_summary,
-    WarningSummary: warning_summary,
-    DeprecationSummary: deprecation_summary,
+    _messages.PluginInfo: plugin_info,
+    _messages.PluginType: plugin_type,
+    _messages.ErrorSummary: error_summary,
+    _messages.WarningSummary: warning_summary,
+    _messages.DeprecationSummary: deprecation_summary,
     EncryptedString: encrypted_string,
 }
 """This mapping is consulted by `Templar.template` to provide custom views of some objects."""

ansible/_internal/_templating/_utils.py

@@ -99,7 +99,7 @@ Omit = object.__new__(_OmitType)
 _datatag._untaggable_types.add(_OmitType)
 
 
-# DTFIX-RELEASE: review these type sets to ensure they're not overly permissive/dynamic
+# DTFIX5: review these type sets to ensure they're not overly permissive/dynamic
 IGNORE_SCALAR_VAR_TYPES = {value for value in _datatag._ANSIBLE_ALLOWED_SCALAR_VAR_TYPES if not issubclass(value, str)}
 
 PASS_THROUGH_SCALAR_VAR_TYPES = _datatag._ANSIBLE_ALLOWED_SCALAR_VAR_TYPES | {

ansible/_internal/_yaml/_constructor.py

@@ -4,13 +4,13 @@ import abc
 import copy
 import typing as t
 
-from yaml import Node
+from yaml import Node, ScalarNode
 from yaml.constructor import SafeConstructor
 from yaml.resolver import BaseResolver
 
 from ansible import constants as C
 from ansible.module_utils.common.text.converters import to_text
-from ansible.module_utils._internal._datatag import AnsibleTagHelper
+from ansible.module_utils._internal._datatag import AnsibleTagHelper, AnsibleDatatagBase
 from ansible._internal._datatag._tags import Origin, TrustedAsTemplate
 from ansible.parsing.vault import EncryptedString
 from ansible.utils.display import Display
@@ -117,13 +117,13 @@ class AnsibleInstrumentedConstructor(_BaseConstructor):
         items = [origin.tag(item) for item in items]
         yield origin.tag(items)
 
-    def construct_yaml_str(self, node):
+    def construct_yaml_str(self, node: ScalarNode) -> str:
         # Override the default string handling function
         # to always return unicode objects
         # DTFIX-FUTURE: is this to_text conversion still necessary under Py3?
         value = to_text(self.construct_scalar(node))
 
-        tags = [self._node_position_info(node)]
+        tags: list[AnsibleDatatagBase] = [self._node_position_info(node)]
 
         if self.trusted_as_template:
             # NB: since we're not context aware, this will happily add trust to dictionary keys; this is actually necessary for

ansible/_internal/_yaml/_dumper.py

@@ -4,8 +4,10 @@ import abc
 import collections.abc as c
 import typing as t
 
-from yaml.representer import SafeRepresenter
+from yaml.nodes import ScalarNode, Node
 
+from ansible._internal._templating import _jinja_common
+from ansible.module_utils import _internal
 from ansible.module_utils._internal._datatag import AnsibleTaggedObject, Tripwire, AnsibleTagHelper
 from ansible.parsing.vault import VaultHelper
 from ansible.module_utils.common.yaml import HAS_LIBYAML
@@ -32,30 +34,36 @@ class _BaseDumper(SafeDumper, metaclass=abc.ABCMeta):
 class AnsibleDumper(_BaseDumper):
     """A simple stub class that allows us to add representers for our custom types."""
 
-    # DTFIX-RELEASE: need a better way to handle serialization controls during YAML dumping
-    def __init__(self, *args, dump_vault_tags: bool | None = None, **kwargs):
-        super().__init__(*args, **kwargs)
-
-        self._dump_vault_tags = dump_vault_tags
-
     @classmethod
     def _register_representers(cls) -> None:
         cls.add_multi_representer(AnsibleTaggedObject, cls.represent_ansible_tagged_object)
         cls.add_multi_representer(Tripwire, cls.represent_tripwire)
-        cls.add_multi_representer(c.Mapping, SafeRepresenter.represent_dict)
-        cls.add_multi_representer(c.Sequence, SafeRepresenter.represent_list)
-
-    def represent_ansible_tagged_object(self, data):
-        if self._dump_vault_tags is not False and (ciphertext := VaultHelper.get_ciphertext(data, with_tags=False)):
-            # deprecated: description='enable the deprecation warning below' core_version='2.23'
-            # if self._dump_vault_tags is None:
-            #     Display().deprecated(
-            #         msg="Implicit YAML dumping of vaulted value ciphertext is deprecated. Set `dump_vault_tags` to explicitly specify the desired behavior",
-            #         version="2.27",
-            #     )
+        cls.add_multi_representer(c.Mapping, cls.represent_dict)
+        cls.add_multi_representer(c.Collection, cls.represent_list)
+        cls.add_multi_representer(_jinja_common.VaultExceptionMarker, cls.represent_vault_exception_marker)
 
+    def get_node_from_ciphertext(self, data: object) -> ScalarNode | None:
+        if ciphertext := VaultHelper.get_ciphertext(data, with_tags=False):
             return self.represent_scalar('!vault', ciphertext, style='|')
 
+        return None
+
+    def represent_vault_exception_marker(self, data: _jinja_common.VaultExceptionMarker) -> ScalarNode:
+        if node := self.get_node_from_ciphertext(data):
+            return node
+
+        data.trip()
+
+    def represent_ansible_tagged_object(self, data: AnsibleTaggedObject) -> Node:
+        if _internal.is_intermediate_mapping(data):
+            return self.represent_dict(data)
+
+        if _internal.is_intermediate_iterable(data):
+            return self.represent_list(data)
+
+        if node := self.get_node_from_ciphertext(data):
+            return node
+
         return self.represent_data(AnsibleTagHelper.as_native_type(data))  # automatically decrypts encrypted strings
 
     def represent_tripwire(self, data: Tripwire) -> t.NoReturn:

ansible/_internal/_yaml/_errors.py

@@ -7,7 +7,7 @@ import typing as t
 from yaml import MarkedYAMLError
 from yaml.constructor import ConstructorError
 
-from ansible._internal._errors import _utils
+from ansible._internal._errors import _error_utils
 from ansible.errors import AnsibleParserError
 from ansible._internal._datatag._tags import Origin
 
@@ -34,7 +34,7 @@ class AnsibleYAMLParserError(AnsibleParserError):
         if isinstance(exception, MarkedYAMLError):
             origin = origin.replace(line_num=exception.problem_mark.line + 1, col_num=exception.problem_mark.column + 1)
 
-        source_context = _utils.SourceContext.from_origin(origin)
+        source_context = _error_utils.SourceContext.from_origin(origin)
 
         target_line = source_context.target_line or ''  # for these cases, we don't need to distinguish between None and empty string
 
@@ -66,12 +66,12 @@ class AnsibleYAMLParserError(AnsibleParserError):
         # There may be cases where there is a valid tab in a line that has other errors.
         # That's OK, users should "fix" their tab usage anyway -- at which point later error handling logic will hopefully find the real issue.
         elif (tab_idx := target_line.find('\t')) >= 0:
-            source_context = _utils.SourceContext.from_origin(origin.replace(col_num=tab_idx + 1))
+            source_context = _error_utils.SourceContext.from_origin(origin.replace(col_num=tab_idx + 1))
             message = "Tabs are usually invalid in YAML."
 
         # Check for unquoted templates.
         elif match := re.search(r'^\s*(?:-\s+)*(?:[\w\s]+:\s+)?(?P<value>\{\{.*}})', target_line):
-            source_context = _utils.SourceContext.from_origin(origin.replace(col_num=match.start('value') + 1))
+            source_context = _error_utils.SourceContext.from_origin(origin.replace(col_num=match.start('value') + 1))
             message = 'This may be an issue with missing quotes around a template block.'
             # FIXME: Use the captured value to show the actual fix required.
             help_text = """
@@ -95,7 +95,7 @@ Should be:
             # look for an unquoted colon in the value
             and (colon_match := re.search(r':($| )', target_fragment))
         ):
-            source_context = _utils.SourceContext.from_origin(origin.replace(col_num=value_match.start('value') + colon_match.start() + 1))
+            source_context = _error_utils.SourceContext.from_origin(origin.replace(col_num=value_match.start('value') + colon_match.start() + 1))
             message = 'Colons in unquoted values must be followed by a non-space character.'
             # FIXME: Use the captured value to show the actual fix required.
             help_text = """
@@ -114,7 +114,7 @@ Should be:
             first, last = suspected_value[0], suspected_value[-1]
 
             if first != last:  # "foo" in bar
-                source_context = _utils.SourceContext.from_origin(origin.replace(col_num=match.start('value') + 1))
+                source_context = _error_utils.SourceContext.from_origin(origin.replace(col_num=match.start('value') + 1))
                 message = 'Values starting with a quote must end with the same quote.'
                 # FIXME: Use the captured value to show the actual fix required, and use that same logic to improve the origin further.
                 help_text = """
@@ -127,7 +127,7 @@ Should be:
     raw: '"foo" in bar'
 """
             elif first == last and target_line.count(first) > 2:  # "foo" and "bar"
-                source_context = _utils.SourceContext.from_origin(origin.replace(col_num=match.start('value') + 1))
+                source_context = _error_utils.SourceContext.from_origin(origin.replace(col_num=match.start('value') + 1))
                 message = 'Values starting with a quote must end with the same quote, and not contain that quote.'
                 # FIXME: Use the captured value to show the actual fix required, and use that same logic to improve the origin further.
                 help_text = """

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/true_type.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import typing as t
 
-from ansible.plugins import accept_args_markers
+from ansible.template import accept_args_markers
 
 
 @accept_args_markers

ansible/_internal/ansible_collections/ansible/_protomatter/plugins/filter/unmask.py

@@ -12,7 +12,7 @@ from ansible.errors import AnsibleError
 
 def unmask(value: object, type_names: str | list[str]) -> object:
     """
-    Internal filter to suppress automatic type transformation in Jinja (e.g., WarningMessageDetail, DeprecationMessageDetail, ErrorDetail).
+    Internal filter to suppress automatic type transformation in Jinja (e.g., WarningSummary, DeprecationSummary, ErrorSummary).
     Lazy collection caching is in play - the first attempt to access a value in a given lazy container must be with unmasking in place, or the transformed value
     will already be cached.
     """

ansible/cli/__init__.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 
 import locale
 import os
-import signal
 import sys
 
 # We overload the ``ansible`` adhoc command to provide the functionality for
@@ -76,8 +75,6 @@ def initialize_locale():
 initialize_locale()
 
 
-import atexit
-import errno
 import getpass
 import subprocess
 import traceback
@@ -96,7 +93,7 @@ try:
     display = Display()
 except Exception as ex:
     if isinstance(ex, AnsibleError):
-        ex_msg = ' '.join((ex.message, ex._help_text)).strip()
+        ex_msg = ' '.join((ex.message, ex._help_text or '')).strip()
     else:
         ex_msg = str(ex)
 
@@ -112,17 +109,17 @@ from ansible.module_utils.six import string_types
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.module_utils.common.collections import is_sequence
 from ansible.module_utils.common.file import is_executable
-from ansible.module_utils.common.process import get_bin_path
 from ansible.parsing.dataloader import DataLoader
 from ansible.parsing.vault import PromptVaultSecret, get_file_vault_secret, VaultSecretsContext
 from ansible.plugins.loader import add_all_plugin_dirs, init_plugin_loader
 from ansible.release import __version__
-from ansible.utils._ssh_agent import SshAgentClient
 from ansible.utils.collection_loader import AnsibleCollectionConfig
 from ansible.utils.collection_loader._collection_finder import _get_collection_name_from_path
 from ansible.utils.path import unfrackpath
 from ansible.vars.manager import VariableManager
 from ansible.module_utils._internal import _deprecator
+from ansible._internal._ssh import _agent_launch
+
 
 try:
     import argcomplete
@@ -131,77 +128,6 @@ except ImportError:
     HAS_ARGCOMPLETE = False
 
 
-_SSH_AGENT_STDOUT_READ_TIMEOUT = 5  # seconds
-
-
-def _ssh_agent_timeout_handler(signum, frame):
-    raise TimeoutError
-
-
-def _launch_ssh_agent() -> None:
-    ssh_agent_cfg = C.config.get_config_value('SSH_AGENT')
-    match ssh_agent_cfg:
-        case 'none':
-            display.debug('SSH_AGENT set to none')
-            return
-        case 'auto':
-            try:
-                ssh_agent_bin = get_bin_path('ssh-agent')
-            except ValueError as e:
-                raise AnsibleError('SSH_AGENT set to auto, but cannot find ssh-agent binary') from e
-            ssh_agent_dir = os.path.join(C.DEFAULT_LOCAL_TMP, 'ssh_agent')
-            os.mkdir(ssh_agent_dir, 0o700)
-            sock = os.path.join(ssh_agent_dir, 'agent.sock')
-            display.vvv('SSH_AGENT: starting...')
-            try:
-                p = subprocess.Popen(
-                    [ssh_agent_bin, '-D', '-s', '-a', sock],
-                    stdin=subprocess.PIPE,
-                    stdout=subprocess.PIPE,
-                    stderr=subprocess.PIPE,
-                )
-            except OSError as e:
-                raise AnsibleError(
-                    f'Could not start ssh-agent: {e}'
-                ) from e
-
-            if p.poll() is not None:
-                raise AnsibleError(
-                    f'Could not start ssh-agent: rc={p.returncode} stderr="{p.stderr.read().decode()}"'
-                )
-
-            old_sigalrm_handler = signal.signal(signal.SIGALRM, _ssh_agent_timeout_handler)
-            signal.alarm(_SSH_AGENT_STDOUT_READ_TIMEOUT)
-            try:
-                stdout = p.stdout.read(13)
-            except TimeoutError:
-                stdout = b''
-            finally:
-                signal.alarm(0)
-                signal.signal(signal.SIGALRM, old_sigalrm_handler)
-
-            if stdout != b'SSH_AUTH_SOCK':
-                display.warning(
-                    f'The first 13 characters of stdout did not match the '
-                    f'expected SSH_AUTH_SOCK. This may not be the right binary, '
-                    f'or an incompatible agent: {stdout.decode()}'
-                )
-            display.vvv(f'SSH_AGENT: ssh-agent[{p.pid}] started and bound to {sock}')
-            atexit.register(p.terminate)
-        case _:
-            sock = ssh_agent_cfg
-
-    try:
-        with SshAgentClient(sock) as client:
-            client.list()
-    except Exception as e:
-        raise AnsibleError(
-            f'Could not communicate with ssh-agent using auth sock {sock}: {e}'
-        ) from e
-
-    os.environ['SSH_AUTH_SOCK'] = os.environ['ANSIBLE_SSH_AGENT'] = sock
-
-
 class CLI(ABC):
     """ code behind bin/ansible* programs """
 
@@ -599,9 +525,7 @@ class CLI(ABC):
         try:
             cmd = subprocess.Popen(CLI.PAGER, shell=True, stdin=subprocess.PIPE, stdout=sys.stdout)
             cmd.communicate(input=to_bytes(text))
-        except IOError:
-            pass
-        except KeyboardInterrupt:
+        except (OSError, KeyboardInterrupt):
             pass
 
     def _play_prereqs(self):
@@ -636,10 +560,7 @@ class CLI(ABC):
         loader.set_vault_secrets(vault_secrets)
 
         if self.USES_CONNECTION:
-            try:
-                _launch_ssh_agent()
-            except Exception as e:
-                raise AnsibleError('Failed to launch ssh agent', orig_exc=e)
+            _agent_launch.launch_ssh_agent()
 
         # create the inventory, and filter it based on the subset specified (if any)
         inventory = InventoryManager(loader=loader, sources=options['inventory'], cache=(not options.get('flush_cache')))
@@ -709,8 +630,8 @@ class CLI(ABC):
             try:
                 with open(b_pwd_file, "rb") as password_file:
                     secret = password_file.read().strip()
-            except (OSError, IOError) as e:
-                raise AnsibleError("Could not read password file %s: %s" % (pwd_file, e))
+            except OSError as ex:
+                raise AnsibleError(f"Could not read password file {pwd_file!r}.") from ex
 
         secret = secret.strip(b'\r\n')
 
@@ -729,12 +650,9 @@ class CLI(ABC):
 
             ansible_dir = Path(C.ANSIBLE_HOME).expanduser()
             try:
-                ansible_dir.mkdir(mode=0o700)
-            except OSError as exc:
-                if exc.errno != errno.EEXIST:
-                    display.warning(
-                        "Failed to create the directory '%s': %s" % (ansible_dir, to_text(exc, errors='surrogate_or_replace'))
-                    )
+                ansible_dir.mkdir(mode=0o700, exist_ok=True)
+            except OSError as ex:
+                display.error_as_warning(f"Failed to create the directory {ansible_dir!r}.", ex)
             else:
                 display.debug("Created the '%s' directory" % ansible_dir)
 
@@ -750,7 +668,7 @@ class CLI(ABC):
             try:
                 raise AnsibleError("Unexpected Exception, this is probably a bug.") from ex
             except AnsibleError as ex2:
-                # DTFIX-RELEASE: clean this up so we're not hacking the internals- re-wrap in an AnsibleCLIUnhandledError that always shows TB, or?
+                # DTFIX-FUTURE: clean this up so we're not hacking the internals- re-wrap in an AnsibleCLIUnhandledError that always shows TB, or?
                 from ansible.module_utils._internal import _traceback
                 _traceback._is_traceback_enabled = lambda *_args, **_kwargs: True
                 display.error(ex2)