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

ansible/cli/arguments/option_helpers.py

@@ -16,10 +16,9 @@ import typing as t
 
 import yaml
 
-from jinja2 import __version__ as j2_version
-
 import ansible
 from ansible import constants as C
+from ansible._internal import _templating
 from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.common.yaml import HAS_LIBYAML, yaml_load
 from ansible.release import __version__
@@ -244,7 +243,7 @@ def _git_repo_info(repo_path):
                     repo_path = gitdir
                 else:
                     repo_path = os.path.join(repo_path[:-4], gitdir)
-            except (IOError, AttributeError):
+            except (OSError, AttributeError):
                 return ''
         with open(os.path.join(repo_path, "HEAD")) as f:
             line = f.readline().rstrip("\n")
@@ -313,7 +312,7 @@ def version(prog=None):
     result.append("  ansible collection location = %s" % ':'.join(C.COLLECTIONS_PATHS))
     result.append("  executable location = %s" % sys.argv[0])
     result.append("  python version = %s (%s)" % (''.join(sys.version.splitlines()), to_native(sys.executable)))
-    result.append("  jinja version = %s" % j2_version)
+    result.append(f"  jinja version = {_templating.jinja2_version}")
     result.append(f"  pyyaml version = {yaml.__version__} ({libyaml_fragment})")
 
     return "\n".join(result)

ansible/cli/console.py

@@ -573,7 +573,7 @@ class ConsoleCLI(CLI, cmd.Cmd):
         histfile = os.path.join(os.path.expanduser("~"), ".ansible-console_history")
         try:
             readline.read_history_file(histfile)
-        except IOError:
+        except OSError:
             pass
 
         atexit.register(readline.write_history_file, histfile)

ansible/cli/doc.py

@@ -9,12 +9,14 @@ from __future__ import annotations
 # ansible.cli needs to be imported first, to ensure the source bin/* scripts run that code first
 from ansible.cli import CLI
 
+import collections.abc
 import importlib
 import pkgutil
 import os
 import os.path
 import re
 import textwrap
+import typing as t
 
 import yaml
 
@@ -35,7 +37,7 @@ from ansible.parsing.plugin_docs import read_docstub
 from ansible.parsing.yaml.dumper import AnsibleDumper
 from ansible.parsing.yaml.loader import AnsibleLoader
 from ansible._internal._yaml._loader import AnsibleInstrumentedLoader
-from ansible.plugins.list import list_plugins
+from ansible.plugins.list import _list_plugins_with_info, _PluginDocMetadata
 from ansible.plugins.loader import action_loader, fragment_loader
 from ansible.utils.collection_loader import AnsibleCollectionConfig, AnsibleCollectionRef
 from ansible.utils.collection_loader._collection_finder import _get_collection_name_from_path
@@ -44,6 +46,7 @@ from ansible.utils.display import Display
 from ansible.utils.plugin_docs import get_plugin_docs, get_docstring, get_versioned_doclink
 from ansible.template import trust_as_template
 from ansible._internal import _json
+from ansible._internal._templating import _jinja_plugins
 
 display = Display()
 
@@ -134,8 +137,8 @@ class RoleMixin(object):
                 data = yaml.load(trust_as_template(f), Loader=AnsibleLoader)
                 if data is None:
                     data = {}
-        except (IOError, OSError) as ex:
-            raise AnsibleParserError(f"Could not read the role {role_name!r} (at {path}).") from ex
+        except OSError as ex:
+            raise AnsibleParserError(f"Could not read the role {role_name!r} at {path!r}.") from ex
 
         return data
 
@@ -788,35 +791,47 @@ class DocCLI(CLI, RoleMixin):
         return coll_filter
 
     def _list_plugins(self, plugin_type, content):
-
-        results = {}
-        self.plugins = {}
-        loader = DocCLI._prep_loader(plugin_type)
+        DocCLI._prep_loader(plugin_type)
 
         coll_filter = self._get_collection_filter()
-        self.plugins.update(list_plugins(plugin_type, coll_filter))
+        plugins = _list_plugins_with_info(plugin_type, coll_filter)
+
+        # Remove the internal ansible._protomatter plugins if getting all plugins
+        if not coll_filter:
+            plugins = {k: v for k, v in plugins.items() if not k.startswith('ansible._protomatter.')}
 
         # get appropriate content depending on option
         if content == 'dir':
-            results = self._get_plugin_list_descriptions(loader)
+            results = self._get_plugin_list_descriptions(plugins)
         elif content == 'files':
-            results = {k: self.plugins[k][0] for k in self.plugins.keys()}
+            results = {k: v.path for k, v in plugins.items()}
         else:
-            results = {k: {} for k in self.plugins.keys()}
+            results = {k: {} for k in plugins.keys()}
             self.plugin_list = set()  # reset for next iteration
 
         return results
 
-    def _get_plugins_docs(self, plugin_type, names, fail_ok=False, fail_on_errors=True):
-
+    def _get_plugins_docs(self, plugin_type: str, names: collections.abc.Iterable[str], fail_ok: bool = False, fail_on_errors: bool = True) -> dict[str, dict]:
         loader = DocCLI._prep_loader(plugin_type)
 
+        if plugin_type in ('filter', 'test'):
+            jinja2_builtins = _jinja_plugins.get_jinja_builtin_plugin_descriptions(plugin_type)
+            jinja2_builtins.update({name.split('.')[-1]: value for name, value in jinja2_builtins.items()})  # add short-named versions for lookup
+        else:
+            jinja2_builtins = {}
+
         # get the docs for plugins in the command line list
         plugin_docs = {}
         for plugin in names:
-            doc = {}
+            doc: dict[str, t.Any] = {}
             try:
-                doc, plainexamples, returndocs, metadata = get_plugin_docs(plugin, plugin_type, loader, fragment_loader, (context.CLIARGS['verbosity'] > 0))
+                doc, plainexamples, returndocs, metadata = self._get_plugin_docs_with_jinja2_builtins(
+                    plugin,
+                    plugin_type,
+                    loader,
+                    fragment_loader,
+                    jinja2_builtins,
+                )
             except AnsiblePluginNotFound as e:
                 display.warning(to_native(e))
                 continue
@@ -853,6 +868,39 @@ class DocCLI(CLI, RoleMixin):
 
         return plugin_docs
 
+    def _get_plugin_docs_with_jinja2_builtins(
+        self,
+        plugin_name: str,
+        plugin_type: str,
+        loader: t.Any,
+        fragment_loader: t.Any,
+        jinja_builtins: dict[str, str],
+    ) -> tuple[dict, str | None, dict | None, dict | None]:
+        try:
+            return get_plugin_docs(plugin_name, plugin_type, loader, fragment_loader, (context.CLIARGS['verbosity'] > 0))
+        except Exception:
+            if (desc := jinja_builtins.get(plugin_name, ...)) is not ...:
+                short_name = plugin_name.split('.')[-1]
+                long_name = f'ansible.builtin.{short_name}'
+                # Dynamically build a doc stub for any Jinja2 builtin plugin we haven't
+                # explicitly documented.
+                doc = dict(
+                    collection='ansible.builtin',
+                    plugin_name=long_name,
+                    filename='',
+                    short_description=desc,
+                    description=[
+                        desc,
+                        '',
+                        f"This is the Jinja builtin {plugin_type} plugin {short_name!r}.",
+                        f"See: U(https://jinja.palletsprojects.com/en/stable/templates/#jinja-{plugin_type}s.{short_name})",
+                    ],
+                )
+
+                return doc, None, None, None
+
+            raise
+
     def _get_roles_path(self):
         """
          Add any 'roles' subdir in playbook dir to the roles search path.
@@ -1001,10 +1049,10 @@ class DocCLI(CLI, RoleMixin):
     def get_all_plugins_of_type(plugin_type):
         loader = getattr(plugin_loader, '%s_loader' % plugin_type)
         paths = loader._get_paths_with_context()
-        plugins = {}
+        plugins = []
         for path_context in paths:
-            plugins.update(list_plugins(plugin_type))
-        return sorted(plugins.keys())
+            plugins += _list_plugins_with_info(plugin_type).keys()
+        return sorted(plugins)
 
     @staticmethod
     def get_plugin_metadata(plugin_type, plugin_name):
@@ -1101,18 +1149,20 @@ class DocCLI(CLI, RoleMixin):
 
         return text
 
-    def _get_plugin_list_descriptions(self, loader):
+    def _get_plugin_list_descriptions(self, plugins: dict[str, _PluginDocMetadata]) -> dict[str, str]:
 
         descs = {}
-        for plugin in self.plugins.keys():
+        for plugin, plugin_info in plugins.items():
             # TODO: move to plugin itself i.e: plugin.get_desc()
             doc = None
-            filename = Path(to_native(self.plugins[plugin][0]))
+
             docerror = None
-            try:
-                doc = read_docstub(filename)
-            except Exception as e:
-                docerror = e
+            if plugin_info.path:
+                filename = Path(to_native(plugin_info.path))
+                try:
+                    doc = read_docstub(filename)
+                except Exception as e:
+                    docerror = e
 
             # plugin file was empty or had error, lets try other options
             if doc is None:
@@ -1127,9 +1177,15 @@ class DocCLI(CLI, RoleMixin):
                     except Exception as e:
                         docerror = e
 
-            if docerror:
-                display.warning("%s has a documentation formatting error: %s" % (plugin, docerror))
-                continue
+                # Do a final fallback to see if the plugin is a shadowed Jinja2 plugin
+                # without any explicit documentation.
+                if doc is None and plugin_info.jinja_builtin_short_description:
+                    descs[plugin] = plugin_info.jinja_builtin_short_description
+                    continue
+
+                if docerror:
+                    display.error_as_warning(f"{plugin} has a documentation formatting error.", exception=docerror)
+                    continue
 
             if not doc or not isinstance(doc, dict):
                 desc = 'UNDOCUMENTED'
@@ -1368,7 +1424,7 @@ class DocCLI(CLI, RoleMixin):
                     try:
                         text.append(yaml_dump(doc.pop('examples'), indent=2, default_flow_style=False))
                     except Exception as e:
-                        raise AnsibleParserError("Unable to parse examples section", orig_exc=e)
+                        raise AnsibleParserError("Unable to parse examples section.") from e
 
         return text
 
@@ -1406,7 +1462,7 @@ class DocCLI(CLI, RoleMixin):
                 try:
                     text.append('\t' + C.config.get_deprecated_msg_from_config(doc['deprecated'], True, collection_name=collection_name))
                 except KeyError as e:
-                    raise AnsibleError("Invalid deprecation documentation structure", orig_exc=e)
+                    raise AnsibleError("Invalid deprecation documentation structure.") from e
             else:
                 text.append("%s" % doc['deprecated'])
             del doc['deprecated']

ansible/cli/inventory.py

@@ -14,13 +14,12 @@ import sys
 import typing as t
 
 import argparse
-import functools
 
 from ansible import constants as C
 from ansible import context
 from ansible.cli.arguments import option_helpers as opt_help
 from ansible.errors import AnsibleError, AnsibleOptionsError, AnsibleRuntimeError
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible._internal._json._profiles import _inventory_legacy
 from ansible.utils.vars import combine_vars
 from ansible.utils.display import Display
@@ -152,8 +151,8 @@ class InventoryCLI(CLI):
                 try:
                     with open(to_bytes(outfile), 'wb') as f:
                         f.write(to_bytes(results))
-                except (OSError, IOError) as e:
-                    raise AnsibleError('Unable to write to destination file (%s): %s' % (to_native(outfile), to_native(e)))
+                except OSError as ex:
+                    raise AnsibleError(f'Unable to write to destination file {outfile!r}.') from ex
             sys.exit(0)
 
         sys.exit(1)
@@ -162,11 +161,10 @@ class InventoryCLI(CLI):
     def dump(stuff):
         if context.CLIARGS['yaml']:
             import yaml
+
             from ansible.parsing.yaml.dumper import AnsibleDumper
 
-            # DTFIX-RELEASE: need shared infra to smuggle custom kwargs to dumpers, since yaml.dump cannot (as of PyYAML 6.0.1)
-            dumper = functools.partial(AnsibleDumper, dump_vault_tags=True)
-            results = to_text(yaml.dump(stuff, Dumper=dumper, default_flow_style=False, allow_unicode=True))
+            results = to_text(yaml.dump(stuff, Dumper=AnsibleDumper, default_flow_style=False, allow_unicode=True))
         elif context.CLIARGS['toml']:
             results = toml_dumps(stuff)
         else:

ansible/compat/importlib_resources.py

@@ -3,17 +3,14 @@
 
 from __future__ import annotations
 
-import sys
+from ansible.utils.display import Display as _Display
 
-HAS_IMPORTLIB_RESOURCES = False
+from importlib.resources import files  # pylint: disable=unused-import
 
-if sys.version_info < (3, 10):
-    try:
-        from importlib_resources import files  # type: ignore[import]  # pylint: disable=unused-import
-    except ImportError:
-        files = None  # type: ignore[assignment]
-    else:
-        HAS_IMPORTLIB_RESOURCES = True
-else:
-    from importlib.resources import files
-    HAS_IMPORTLIB_RESOURCES = True
+HAS_IMPORTLIB_RESOURCES = True
+
+_Display().deprecated(
+    msg="The `ansible.compat.importlib_resources` module is deprecated.",
+    help_text="Use `importlib.resources` from the Python standard library instead.",
+    version="2.23",
+)

ansible/config/base.yml

@@ -1,6 +1,26 @@
 # Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 ---
+_ANSIBALLZ_COVERAGE_CONFIG:
+  name: Configure the AnsiballZ code coverage extension
+  description:
+    - Enables and configures the AnsiballZ code coverage extension.
+    - This is for internal use only.
+  env:
+  - {name: _ANSIBLE_ANSIBALLZ_COVERAGE_CONFIG}
+  vars:
+  - {name: _ansible_ansiballz_coverage_config}
+  version_added: '2.19'
+_ANSIBALLZ_DEBUGGER_CONFIG:
+  name: Configure the AnsiballZ remote debugging extension
+  description:
+    - Enables and configures the AnsiballZ remote debugging extension.
+    - This is for internal use only.
+  env:
+  - {name: _ANSIBLE_ANSIBALLZ_DEBUGGER_CONFIG}
+  vars:
+  - {name: _ansible_ansiballz_debugger_config}
+  version_added: '2.19'
 _ANSIBLE_CONNECTION_PATH:
   env:
   - name: _ANSIBLE_CONNECTION_PATH
@@ -906,6 +926,10 @@ DEFAULT_MANAGED_STR:
   ini:
   - {key: ansible_managed, section: defaults}
   yaml: {key: defaults.ansible_managed}
+  deprecated:
+    why: The `ansible_managed` variable can be set just like any other variable, or a different variable can be used.
+    version: "2.23"
+    alternatives: Set the `ansible_managed` variable, or use any custom variable in templates.
 DEFAULT_MODULE_ARGS:
   name: Adhoc default arguments
   default: ~
@@ -1335,6 +1359,7 @@ DISPLAY_TRACEBACK:
     - error
     - warning
     - deprecated
+    - deprecated_value
     - always
     - never
   version_added: "2.19"
@@ -1961,6 +1986,14 @@ SSH_AGENT:
   env: [{name: ANSIBLE_SSH_AGENT}]
   ini: [{key: ssh_agent, section: connection}]
   version_added: '2.19'
+SSH_AGENT_EXECUTABLE:
+  name: Executable to start for the ansible-managed SSH agent
+  description: When ``SSH_AGENT`` is ``auto``, the path or name of the ssh agent executable to start.
+  default: ssh-agent
+  type: str
+  env: [ { name: ANSIBLE_SSH_AGENT_EXECUTABLE } ]
+  ini: [ { key: ssh_agent_executable, section: connection } ]
+  version_added: '2.19'
 SSH_AGENT_KEY_LIFETIME:
   name: Set a maximum lifetime when adding identities to an agent
   description: For keys inserted into an agent defined by ``SSH_AGENT``, define a lifetime, in seconds, that the key may remain
@@ -2035,6 +2068,19 @@ TASK_TIMEOUT:
   - {key: task_timeout, section: defaults}
   type: integer
   version_added: '2.10'
+_TEMPLAR_SANDBOX_MODE:
+  name: Control Jinja template sandbox behavior
+  default: default
+  description:
+    - The default Jinja sandbox behavior blocks template access to all `_` prefixed object attributes and known collection mutation methods (e.g., `dict.clear()`, `list.append()`).
+  type: choices
+  choices:
+    - default
+    - allow_unsafe_attributes
+  env: [{name: _ANSIBLE_TEMPLAR_SANDBOX_MODE}]
+  deprecated:
+    why: controlling sandbox behavior is a temporary workaround
+    version: '2.23'
 _TEMPLAR_UNKNOWN_TYPE_CONVERSION:
   name: Templar unknown type conversion behavior
   default: warning

ansible/errors/__init__.py

@@ -3,20 +3,18 @@
 
 from __future__ import annotations
 
+import collections.abc as _c
 import enum
-import traceback
-import sys
 import types
 import typing as t
 
-from collections.abc import Sequence
-
 from json import JSONDecodeError
 
 from ansible.module_utils.common.text.converters import to_text
 from ..module_utils.datatag import native_type_name
 from ansible._internal._datatag import _tags
-from .._internal._errors import _utils
+from .._internal._errors import _error_utils
+from ansible.module_utils._internal import _text_utils
 
 if t.TYPE_CHECKING:
     from ansible.plugins import loader as _t_loader
@@ -73,7 +71,7 @@ class AnsibleError(Exception):
             message = str(message)
 
         if self._default_message and message:
-            message = _utils.concat_message(self._default_message, message)
+            message = _text_utils.concat_message(self._default_message, message)
         elif self._default_message:
             message = self._default_message
         elif not message:
@@ -97,8 +95,9 @@ class AnsibleError(Exception):
                 self._show_content = False
 
             Display().deprecated(
-                msg=f"The `suppress_extended_error` argument to `{type(self).__name__}` is deprecated. Use `show_content=False` instead.",
+                msg=f"The `suppress_extended_error` argument to `{type(self).__name__}` is deprecated.",
                 version="2.23",
+                help_text="Use `show_content=False` instead.",
             )
 
     @property
@@ -108,12 +107,10 @@ class AnsibleError(Exception):
     @property
     def message(self) -> str:
         """
-        If `include_cause_message` is False, return the original message.
-        Otherwise, return the original message with cause message(s) appended, stopping on (and including) the first non-AnsibleError.
-        The recursion is due to `AnsibleError.__str__` calling this method, which uses `str` on child exceptions to create the cause message.
-        Recursion stops on the first non-AnsibleError since those exceptions do not implement the custom `__str__` behavior.
+        Return the original message with cause message(s) appended.
+        The cause will not be followed on any `AnsibleError` with `_include_cause_message=False`.
         """
-        return _utils.get_chained_message(self)
+        return _error_utils.format_exception_message(self)
 
     @message.setter
     def message(self, val) -> None:
@@ -121,8 +118,8 @@ class AnsibleError(Exception):
 
     @property
     def _formatted_source_context(self) -> str | None:
-        with _utils.RedactAnnotatedSourceContext.when(not self._show_content):
-            if source_context := _utils.SourceContext.from_value(self.obj):
+        with _error_utils.RedactAnnotatedSourceContext.when(not self._show_content):
+            if source_context := _error_utils.SourceContext.from_value(self.obj):
                 return str(source_context)
 
         return None
@@ -238,8 +235,20 @@ class AnsibleModuleError(AnsibleRuntimeError):
     """A module failed somehow."""
 
 
-class AnsibleConnectionFailure(AnsibleRuntimeError):
-    """The transport / connection_plugin had a fatal error."""
+class AnsibleConnectionFailure(AnsibleRuntimeError, _error_utils.ContributesToTaskResult):
+    """
+    The transport / connection_plugin had a fatal error.
+
+    This exception provides a result dictionary via the ContributesToTaskResult mixin.
+    """
+
+    @property
+    def result_contribution(self) -> t.Mapping[str, object]:
+        return dict(unreachable=True)
+
+    @property
+    def omit_failed_key(self) -> bool:
+        return True
 
 
 class AnsibleAuthenticationFailure(AnsibleConnectionFailure):
@@ -319,7 +328,7 @@ class AnsibleFileNotFound(AnsibleRuntimeError):
         else:
             message += "Could not find file"
 
-        if self.paths and isinstance(self.paths, Sequence):
+        if self.paths and isinstance(self.paths, _c.Sequence):
             searched = to_text('\n\t'.join(self.paths))
             if message:
                 message += "\n"
@@ -331,47 +340,76 @@ class AnsibleFileNotFound(AnsibleRuntimeError):
                                                   suppress_extended_error=suppress_extended_error, orig_exc=orig_exc)
 
 
-# These Exceptions are temporary, using them as flow control until we can get a better solution.
-# DO NOT USE as they will probably be removed soon.
-# We will port the action modules in our tree to use a context manager instead.
-class AnsibleAction(AnsibleRuntimeError):
+class AnsibleAction(AnsibleRuntimeError, _error_utils.ContributesToTaskResult):
     """Base Exception for Action plugin flow control."""
 
     def __init__(self, message="", obj=None, show_content=True, suppress_extended_error=..., orig_exc=None, result=None):
-        super(AnsibleAction, self).__init__(message=message, obj=obj, show_content=show_content,
-                                            suppress_extended_error=suppress_extended_error, orig_exc=orig_exc)
-        if result is None:
-            self.result = {}
-        else:
-            self.result = result
+        super().__init__(message=message, obj=obj, show_content=show_content, suppress_extended_error=suppress_extended_error, orig_exc=orig_exc)
+
+        self._result = result or {}
+
+    @property
+    def result_contribution(self) -> _c.Mapping[str, object]:
+        return self._result
+
+    @property
+    def result(self) -> dict[str, object]:
+        """Backward compatibility property returning a mutable dictionary."""
+        return dict(self.result_contribution)
 
 
 class AnsibleActionSkip(AnsibleAction):
-    """An action runtime skip."""
+    """
+    An action runtime skip.
 
-    def __init__(self, message="", obj=None, show_content=True, suppress_extended_error=..., orig_exc=None, result=None):
-        super(AnsibleActionSkip, self).__init__(message=message, obj=obj, show_content=show_content,
-                                                suppress_extended_error=suppress_extended_error, orig_exc=orig_exc, result=result)
-        self.result.update({'skipped': True, 'msg': message})
+    This exception provides a result dictionary via the ContributesToTaskResult mixin.
+    """
+
+    @property
+    def result_contribution(self) -> _c.Mapping[str, object]:
+        return self._result | dict(
+            skipped=True,
+            msg=self.message,
+        )
+
+    @property
+    def omit_failed_key(self) -> bool:
+        return True
+
+    @property
+    def omit_exception_key(self) -> bool:
+        return True
 
 
 class AnsibleActionFail(AnsibleAction):
-    """An action runtime failure."""
+    """
+    An action runtime failure.
 
-    def __init__(self, message="", obj=None, show_content=True, suppress_extended_error=..., orig_exc=None, result=None):
-        super(AnsibleActionFail, self).__init__(message=message, obj=obj, show_content=show_content,
-                                                suppress_extended_error=suppress_extended_error, orig_exc=orig_exc, result=result)
+    This exception provides a result dictionary via the ContributesToTaskResult mixin.
+    """
+
+    @property
+    def result_contribution(self) -> _c.Mapping[str, object]:
+        return self._result | dict(
+            failed=True,
+            msg=self.message,
+        )
 
-        result_overrides = {'failed': True, 'msg': message}
-        # deprecated: description='use sys.exception()' python_version='3.11'
-        if sys.exc_info()[1]:  # DTFIX-RELEASE: remove this hack once TaskExecutor is no longer shucking AnsibleActionFail and returning its result
-            result_overrides['exception'] = traceback.format_exc()
 
-        self.result.update(result_overrides)
+class _ActionDone(AnsibleAction):
+    """
+    Imports as `_AnsibleActionDone` are deprecated. An action runtime early exit.
+
+    This exception provides a result dictionary via the ContributesToTaskResult mixin.
+    """
 
+    @property
+    def omit_failed_key(self) -> bool:
+        return not self._result.get('failed')
 
-class _AnsibleActionDone(AnsibleAction):
-    """An action runtime early exit."""
+    @property
+    def omit_exception_key(self) -> bool:
+        return not self._result.get('failed')
 
 
 class AnsiblePluginError(AnsibleError):
@@ -422,13 +460,23 @@ def __getattr__(name: str) -> t.Any:
     """Inject import-time deprecation warnings."""
     from ..utils.display import Display
 
-    if name == 'AnsibleFilterTypeError':
-        Display().deprecated(
-            msg="Importing 'AnsibleFilterTypeError' is deprecated.",
-            help_text=f"Import {AnsibleTypeError.__name__!r} instead.",
-            version="2.23",
-        )
+    match name:
+        case 'AnsibleFilterTypeError':
+            Display().deprecated(
+                msg=f"Importing {name!r} is deprecated.",
+                help_text=f"Import {AnsibleTypeError.__name__!r} instead.",
+                version="2.23",
+            )
+
+            return AnsibleTypeError
+
+        case '_AnsibleActionDone':
+            Display().deprecated(
+                msg=f"Importing {name!r} is deprecated.",
+                help_text="Return directly from action plugins instead.",
+                version="2.23",
+            )
 
-        return AnsibleTypeError
+            return _ActionDone
 
     raise AttributeError(f'module {__name__!r} has no attribute {name!r}')