ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__py3-none-any.whl

ansible/plugins/__init__.py

@@ -19,36 +19,56 @@
 
 from __future__ import annotations
 
-from abc import ABC
-
+import abc
+import functools
 import types
 import typing as t
 
 from ansible import constants as C
 from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_native
-from ansible.module_utils.six import string_types
 from ansible.utils.display import Display
+from ansible.utils import display as _display
+
+from ansible.module_utils._internal import _plugin_info
 
 display = Display()
 
 if t.TYPE_CHECKING:
-    from .loader import PluginPathContext
+    from . import loader as _t_loader
 
 # Global so that all instances of a PluginLoader will share the caches
 MODULE_CACHE = {}  # type: dict[str, dict[str, types.ModuleType]]
-PATH_CACHE = {}  # type: dict[str, list[PluginPathContext] | None]
-PLUGIN_PATH_CACHE = {}  # type: dict[str, dict[str, dict[str, PluginPathContext]]]
+PATH_CACHE = {}  # type: dict[str, list[_t_loader.PluginPathContext] | None]
+PLUGIN_PATH_CACHE = {}  # type: dict[str, dict[str, dict[str, _t_loader.PluginPathContext]]]
 
 
 def get_plugin_class(obj):
-    if isinstance(obj, string_types):
+    if isinstance(obj, str):
         return obj.lower().replace('module', '')
     else:
         return obj.__class__.__name__.lower().replace('module', '')
 
 
-class AnsiblePlugin(ABC):
+class _ConfigurablePlugin(t.Protocol):
+    """Protocol to provide type-safe access to config for plugin-related mixins."""
+
+    def get_option(self, option: str, hostvars: dict[str, object] | None = None) -> t.Any: ...
+
+
+class _AnsiblePluginInfoMixin(_plugin_info.HasPluginInfo):
+    """Mixin to provide type annotations and default values for existing PluginLoader-set load-time attrs."""
+    _original_path: str | None = None
+    _load_name: str | None = None
+    _redirected_names: list[str] | None = None
+    ansible_aliases: list[str] | None = None
+    ansible_name: str | None = None
+
+    @property
+    def plugin_type(self) -> str:
+        return self.__class__.__name__.lower().replace('module', '')
+
+
+class AnsiblePlugin(_AnsiblePluginInfoMixin, _ConfigurablePlugin, metaclass=abc.ABCMeta):
 
     # Set by plugin loader
     _load_name: str
@@ -81,9 +101,17 @@ class AnsiblePlugin(ABC):
         try:
             option_value, origin = C.config.get_config_value_and_origin(option, plugin_type=self.plugin_type, plugin_name=self._load_name, variables=hostvars)
         except AnsibleError as e:
-            raise KeyError(to_native(e))
+            raise KeyError(str(e))
         return option_value, origin
 
+    @functools.cached_property
+    def __plugin_info(self):
+        """
+        Internal cached property to retrieve `PluginInfo` for this plugin instance.
+        Only for use by the `AnsiblePlugin` base class.
+        """
+        return _plugin_info.get_plugin_info(self)
+
     def get_option(self, option, hostvars=None):
 
         if option not in self._options:
@@ -99,16 +127,16 @@ class AnsiblePlugin(ABC):
 
     def set_option(self, option, value):
         self._options[option] = C.config.get_config_value(option, plugin_type=self.plugin_type, plugin_name=self._load_name, direct={option: value})
-        C.handle_config_noise(display)
+        _display._report_config_warnings(self.__plugin_info)
 
     def set_options(self, task_keys=None, var_options=None, direct=None):
-        '''
+        """
         Sets the _options attribute with the configuration/keyword information for this plugin
 
         :arg task_keys: Dict with playbook keywords that affect this option
         :arg var_options: Dict with either 'connection variables'
         :arg direct: Dict with 'direct assignment'
-        '''
+        """
         self._options = C.config.get_plugin_options(self.plugin_type, self._load_name, keys=task_keys, variables=var_options, direct=direct)
 
         # allow extras/wildcards from vars that are not directly consumed in configuration
@@ -116,20 +144,16 @@ class AnsiblePlugin(ABC):
         if self.allow_extras and var_options and '_extras' in var_options:
             # these are largely unvalidated passthroughs, either plugin or underlying API will validate
             self._options['_extras'] = var_options['_extras']
-        C.handle_config_noise(display)
+        _display._report_config_warnings(self.__plugin_info)
 
     def has_option(self, option):
         if not self._options:
             self.set_options()
         return option in self._options
 
-    @property
-    def plugin_type(self):
-        return self.__class__.__name__.lower().replace('module', '')
-
     @property
     def option_definitions(self):
-        if self._defs is None:
+        if (not hasattr(self, "_defs")) or self._defs is None:
             self._defs = C.config.get_configuration_definitions(plugin_type=self.plugin_type, name=self._load_name)
         return self._defs
 
@@ -137,23 +161,31 @@ class AnsiblePlugin(ABC):
         # FIXME: standardize required check based on config
         pass
 
+    def __repr__(self):
+        ansible_name = getattr(self, 'ansible_name', '(unknown)')
+        load_name = getattr(self, '_load_name', '(unknown)')
+        return f'{type(self).__name__}(plugin_type={self.plugin_type!r}, {ansible_name=!r}, {load_name=!r})'
 
-class AnsibleJinja2Plugin(AnsiblePlugin):
-
-    def __init__(self, function):
 
+class AnsibleJinja2Plugin(AnsiblePlugin, metaclass=abc.ABCMeta):
+    def __init__(self, function: t.Callable) -> None:
         super(AnsibleJinja2Plugin, self).__init__()
         self._function = function
 
+        # Declare support for markers. Plugins with `False` here will never be invoked with markers for top-level arguments.
+        self.accept_args_markers = getattr(self._function, 'accept_args_markers', False)
+        self.accept_lazy_markers = getattr(self._function, 'accept_lazy_markers', False)
+
     @property
-    def plugin_type(self):
-        return self.__class__.__name__.lower().replace('ansiblejinja2', '')
+    @abc.abstractmethod
+    def plugin_type(self) -> str:
+        ...
 
-    def _no_options(self, *args, **kwargs):
+    def _no_options(self, *args, **kwargs) -> t.NoReturn:
         raise NotImplementedError()
 
     has_option = get_option = get_options = option_definitions = set_option = set_options = _no_options
 
     @property
-    def j2_function(self):
+    def j2_function(self) -> t.Callable:
         return self._function