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

ansible/module_utils/_internal/_ansiballz.py

@@ -6,7 +6,6 @@
 from __future__ import annotations
 
 import atexit
-import dataclasses
 import importlib.util
 import json
 import os
@@ -15,17 +14,14 @@ import sys
 import typing as t
 
 from . import _errors
-from ._plugin_exec_context import PluginExecContext, HasPluginInfo
 from .. import basic
 from ..common.json import get_module_encoder, Direction
-from ..common.messages import PluginInfo
 
 
 def run_module(
     *,
     json_params: bytes,
     profile: str,
-    plugin_info_dict: dict[str, object],
     module_fqn: str,
     modlib_path: str,
     init_globals: dict[str, t.Any] | None = None,
@@ -38,7 +34,6 @@ def run_module(
         _run_module(
             json_params=json_params,
             profile=profile,
-            plugin_info_dict=plugin_info_dict,
             module_fqn=module_fqn,
             modlib_path=modlib_path,
             init_globals=init_globals,
@@ -80,7 +75,6 @@ def _run_module(
     *,
     json_params: bytes,
     profile: str,
-    plugin_info_dict: dict[str, object],
     module_fqn: str,
     modlib_path: str,
     init_globals: dict[str, t.Any] | None = None,
@@ -92,12 +86,11 @@ def _run_module(
     init_globals = init_globals or {}
     init_globals.update(_module_fqn=module_fqn, _modlib_path=modlib_path)
 
-    with PluginExecContext(_ModulePluginWrapper(PluginInfo._from_dict(plugin_info_dict))):
-        # Run the module. By importing it as '__main__', it executes as a script.
-        runpy.run_module(mod_name=module_fqn, init_globals=init_globals, run_name='__main__', alter_sys=True)
+    # Run the module. By importing it as '__main__', it executes as a script.
+    runpy.run_module(mod_name=module_fqn, init_globals=init_globals, run_name='__main__', alter_sys=True)
 
-        # An Ansible module must print its own results and exit. If execution reaches this point, that did not happen.
-        raise RuntimeError('New-style module did not handle its own exit.')
+    # An Ansible module must print its own results and exit. If execution reaches this point, that did not happen.
+    raise RuntimeError('New-style module did not handle its own exit.')
 
 
 def _handle_exception(exception: BaseException, profile: str) -> t.NoReturn:
@@ -112,22 +105,3 @@ def _handle_exception(exception: BaseException, profile: str) -> t.NoReturn:
     print(json.dumps(result, cls=encoder))  # pylint: disable=ansible-bad-function
 
     sys.exit(1)  # pylint: disable=ansible-bad-function
-
-
-@dataclasses.dataclass(frozen=True)
-class _ModulePluginWrapper(HasPluginInfo):
-    """Modules aren't plugin instances; this adapter implements the `HasPluginInfo` protocol to allow `PluginExecContext` infra to work with modules."""
-
-    plugin: PluginInfo
-
-    @property
-    def _load_name(self) -> str:
-        return self.plugin.requested_name
-
-    @property
-    def ansible_name(self) -> str:
-        return self.plugin.resolved_name
-
-    @property
-    def plugin_type(self) -> str:
-        return self.plugin.type

ansible/module_utils/_internal/_datatag/_tags.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import dataclasses
-import datetime
 import typing as t
 
 from ansible.module_utils.common import messages as _messages
@@ -12,27 +11,6 @@ from ansible.module_utils._internal import _datatag
 class Deprecated(_datatag.AnsibleDatatagBase):
     msg: str
     help_text: t.Optional[str] = None
-    removal_date: t.Optional[datetime.date] = None
-    removal_version: t.Optional[str] = None
-    plugin: t.Optional[_messages.PluginInfo] = None
-
-    @classmethod
-    def _from_dict(cls, d: t.Dict[str, t.Any]) -> Deprecated:
-        source = d
-        removal_date = source.get('removal_date')
-
-        if removal_date is not None:
-            source = source.copy()
-            source['removal_date'] = datetime.date.fromisoformat(removal_date)
-
-        return cls(**source)
-
-    def _as_dict(self) -> t.Dict[str, t.Any]:
-        # deprecated: description='no-args super() with slotted dataclass requires 3.14+' python_version='3.13'
-        # see: https://github.com/python/cpython/pull/124455
-        value = super(Deprecated, self)._as_dict()
-
-        if self.removal_date is not None:
-            value['removal_date'] = self.removal_date.isoformat()
-
-        return value
+    date: t.Optional[str] = None
+    version: t.Optional[str] = None
+    deprecator: t.Optional[_messages.PluginInfo] = None

ansible/module_utils/_internal/_deprecator.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import inspect
+import re
+import pathlib
+import sys
+import typing as t
+
+from ansible.module_utils.common.messages import PluginInfo
+
+_ansible_module_base_path: t.Final = pathlib.Path(sys.modules['ansible'].__file__).parent
+"""Runtime-detected base path of the `ansible` Python package to distinguish between Ansible-owned and external code."""
+
+ANSIBLE_CORE_DEPRECATOR: t.Final = PluginInfo._from_collection_name('ansible.builtin')
+"""Singleton `PluginInfo` instance for ansible-core callers where the plugin can/should not be identified in messages."""
+
+INDETERMINATE_DEPRECATOR: t.Final = PluginInfo(resolved_name='indeterminate', type='indeterminate')
+"""Singleton `PluginInfo` instance for indeterminate deprecator."""
+
+_DEPRECATOR_PLUGIN_TYPES = frozenset(
+    {
+        'action',
+        'become',
+        'cache',
+        'callback',
+        'cliconf',
+        'connection',
+        # doc_fragments - no code execution
+        # filter - basename inadequate to identify plugin
+        'httpapi',
+        'inventory',
+        'lookup',
+        'module',  # only for collections
+        'netconf',
+        'shell',
+        'strategy',
+        'terminal',
+        # test - basename inadequate to identify plugin
+        'vars',
+    }
+)
+"""Plugin types which are valid for identifying a deprecator for deprecation purposes."""
+
+_AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES = frozenset(
+    {
+        'filter',
+        'test',
+    }
+)
+"""Plugin types for which basename cannot be used to identify the plugin name."""
+
+
+def get_best_deprecator(*, deprecator: PluginInfo | None = None, collection_name: str | None = None) -> PluginInfo:
+    """Return the best-available `PluginInfo` for the caller of this method."""
+    _skip_stackwalk = True
+
+    if deprecator and collection_name:
+        raise ValueError('Specify only one of `deprecator` or `collection_name`.')
+
+    return deprecator or PluginInfo._from_collection_name(collection_name) or get_caller_plugin_info() or INDETERMINATE_DEPRECATOR
+
+
+def get_caller_plugin_info() -> PluginInfo | None:
+    """Try to get `PluginInfo` for the caller of this method, ignoring marked infrastructure stack frames."""
+    _skip_stackwalk = True
+
+    if frame_info := next((frame_info for frame_info in inspect.stack() if '_skip_stackwalk' not in frame_info.frame.f_locals), None):
+        return _path_as_core_plugininfo(frame_info.filename) or _path_as_collection_plugininfo(frame_info.filename)
+
+    return None  # pragma: nocover
+
+
+def _path_as_core_plugininfo(path: str) -> PluginInfo | None:
+    """Return a `PluginInfo` instance if the provided `path` refers to a core plugin."""
+    try:
+        relpath = str(pathlib.Path(path).relative_to(_ansible_module_base_path))
+    except ValueError:
+        return None  # not ansible-core
+
+    namespace = 'ansible.builtin'
+
+    if match := re.match(r'plugins/(?P<plugin_type>\w+)/(?P<plugin_name>\w+)', relpath):
+        plugin_name = match.group("plugin_name")
+        plugin_type = match.group("plugin_type")
+
+        if plugin_type not in _DEPRECATOR_PLUGIN_TYPES:
+            # The plugin type isn't a known deprecator type, so we have to assume the caller is intermediate code.
+            # We have no way of knowing if the intermediate code is deprecating its own feature, or acting on behalf of another plugin.
+            # Callers in this case need to identify the deprecating plugin name, otherwise only ansible-core will be reported.
+            # Reporting ansible-core is never wrong, it just may be missing an additional detail (plugin name) in the "on behalf of" case.
+            return ANSIBLE_CORE_DEPRECATOR
+    elif match := re.match(r'modules/(?P<module_name>\w+)', relpath):
+        # AnsiballZ Python package for core modules
+        plugin_name = match.group("module_name")
+        plugin_type = "module"
+    elif match := re.match(r'legacy/(?P<module_name>\w+)', relpath):
+        # AnsiballZ Python package for non-core library/role modules
+        namespace = 'ansible.legacy'
+
+        plugin_name = match.group("module_name")
+        plugin_type = "module"
+    else:
+        return ANSIBLE_CORE_DEPRECATOR  # non-plugin core path, safe to use ansible-core for the same reason as the non-deprecator plugin type case above
+
+    name = f'{namespace}.{plugin_name}'
+
+    return PluginInfo(resolved_name=name, type=plugin_type)
+
+
+def _path_as_collection_plugininfo(path: str) -> PluginInfo | None:
+    """Return a `PluginInfo` instance if the provided `path` refers to a collection plugin."""
+    if not (match := re.search(r'/ansible_collections/(?P<ns>\w+)/(?P<coll>\w+)/plugins/(?P<plugin_type>\w+)/(?P<plugin_name>\w+)', path)):
+        return None
+
+    plugin_type = match.group('plugin_type')
+
+    if plugin_type in _AMBIGUOUS_DEPRECATOR_PLUGIN_TYPES:
+        # We're able to detect the namespace, collection and plugin type -- but we have no way to identify the plugin name currently.
+        # To keep things simple we'll fall back to just identifying the namespace and collection.
+        # In the future we could improve the detection and/or make it easier for a caller to identify the plugin name.
+        return PluginInfo._from_collection_name('.'.join((match.group('ns'), match.group('coll'))))
+
+    if plugin_type == 'modules':
+        plugin_type = 'module'
+
+    if plugin_type not in _DEPRECATOR_PLUGIN_TYPES:
+        # The plugin type isn't a known deprecator type, so we have to assume the caller is intermediate code.
+        # We have no way of knowing if the intermediate code is deprecating its own feature, or acting on behalf of another plugin.
+        # Callers in this case need to identify the deprecator to avoid ambiguity, since it could be the same collection or another collection.
+        return INDETERMINATE_DEPRECATOR
+
+    name = '.'.join((match.group('ns'), match.group('coll'), match.group('plugin_name')))
+
+    return PluginInfo(resolved_name=name, type=plugin_type)

ansible/module_utils/_internal/_plugin_info.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import typing as t
+
+from ..common import messages as _messages
+
+
+class HasPluginInfo(t.Protocol):
+    """Protocol to type-annotate and expose PluginLoader-set values."""
+
+    @property
+    def ansible_name(self) -> str | None:
+        """Fully resolved plugin name."""
+
+    @property
+    def plugin_type(self) -> str:
+        """Plugin type name."""
+
+
+def get_plugin_info(value: HasPluginInfo) -> _messages.PluginInfo:
+    """Utility method that returns a `PluginInfo` from an object implementing the `HasPluginInfo` protocol."""
+    return _messages.PluginInfo(
+        resolved_name=value.ansible_name,
+        type=value.plugin_type,
+    )

ansible/module_utils/_internal/_validation.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import keyword
+
+
+def validate_collection_name(collection_name: object, name: str = 'collection_name') -> None:
+    """Validate a collection name."""
+    if not isinstance(collection_name, str):
+        raise TypeError(f"{name} must be {str} instead of {type(collection_name)}")
+
+    parts = collection_name.split('.')
+
+    if len(parts) != 2 or not all(part.isidentifier() and not keyword.iskeyword(part) for part in parts):
+        raise ValueError(f"{name} must consist of two non-keyword identifiers separated by '.'")

ansible/module_utils/ansible_release.py

@@ -17,6 +17,6 @@
 
 from __future__ import annotations
 
-__version__ = '2.19.0b2'
+__version__ = '2.19.0b4'
 __author__ = 'Ansible, Inc.'
 __codename__ = "What Is and What Should Never Be"

ansible/module_utils/basic.py

@@ -75,7 +75,7 @@ except ImportError:
 # Python2 & 3 way to get NoneType
 NoneType = type(None)
 
-from ._internal import _traceback, _errors, _debugging
+from ._internal import _traceback, _errors, _debugging, _deprecator
 
 from .common.text.converters import (
     to_native,
@@ -509,16 +509,31 @@ class AnsibleModule(object):
         warn(warning)
         self.log('[WARNING] %s' % warning)
 
-    def deprecate(self, msg, version=None, date=None, collection_name=None):
-        if version is not None and date is not None:
-            raise AssertionError("implementation error -- version and date must not both be set")
-        deprecate(msg, version=version, date=date)
-        # For compatibility, we accept that neither version nor date is set,
-        # and treat that the same as if version would not have been set
-        if date is not None:
-            self.log('[DEPRECATION WARNING] %s %s' % (msg, date))
-        else:
-            self.log('[DEPRECATION WARNING] %s %s' % (msg, version))
+    def deprecate(
+        self,
+        msg: str,
+        version: str | None = None,
+        date: str | None = None,
+        collection_name: str | None = None,
+        *,
+        deprecator: _messages.PluginInfo | None = None,
+        help_text: str | None = None,
+    ) -> None:
+        """
+        Record a deprecation warning to be returned with the module result.
+        Most callers do not need to provide `collection_name` or `deprecator` -- but provide only one if needed.
+        Specify `version` or `date`, but not both.
+        If `date` is a string, it must be in the form `YYYY-MM-DD`.
+        """
+        _skip_stackwalk = True
+
+        deprecate(  # pylint: disable=ansible-deprecated-date-not-permitted,ansible-deprecated-unnecessary-collection-name
+            msg=msg,
+            version=version,
+            date=date,
+            deprecator=_deprecator.get_best_deprecator(deprecator=deprecator, collection_name=collection_name),
+            help_text=help_text,
+        )
 
     def load_file_common_arguments(self, params, path=None):
         """
@@ -1404,6 +1419,7 @@ class AnsibleModule(object):
             self.cleanup(path)
 
     def _return_formatted(self, kwargs):
+        _skip_stackwalk = True
 
         self.add_path_info(kwargs)
 
@@ -1411,6 +1427,13 @@ class AnsibleModule(object):
             kwargs['invocation'] = {'module_args': self.params}
 
         if 'warnings' in kwargs:
+            self.deprecate(  # pylint: disable=ansible-deprecated-unnecessary-collection-name
+                msg='Passing `warnings` to `exit_json` or `fail_json` is deprecated.',
+                version='2.23',
+                help_text='Use `AnsibleModule.warn` instead.',
+                deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+            )
+
             if isinstance(kwargs['warnings'], list):
                 for w in kwargs['warnings']:
                     self.warn(w)
@@ -1422,17 +1445,38 @@ class AnsibleModule(object):
             kwargs['warnings'] = warnings
 
         if 'deprecations' in kwargs:
+            self.deprecate(  # pylint: disable=ansible-deprecated-unnecessary-collection-name
+                msg='Passing `deprecations` to `exit_json` or `fail_json` is deprecated.',
+                version='2.23',
+                help_text='Use `AnsibleModule.deprecate` instead.',
+                deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+            )
+
             if isinstance(kwargs['deprecations'], list):
                 for d in kwargs['deprecations']:
-                    if isinstance(d, SEQUENCETYPE) and len(d) == 2:
-                        self.deprecate(d[0], version=d[1])
+                    if isinstance(d, (KeysView, Sequence)) and len(d) == 2:
+                        self.deprecate(  # pylint: disable=ansible-deprecated-unnecessary-collection-name,ansible-invalid-deprecated-version
+                            msg=d[0],
+                            version=d[1],
+                            deprecator=_deprecator.get_best_deprecator(),
+                        )
                     elif isinstance(d, Mapping):
-                        self.deprecate(d['msg'], version=d.get('version'), date=d.get('date'),
-                                       collection_name=d.get('collection_name'))
+                        self.deprecate(  # pylint: disable=ansible-deprecated-date-not-permitted,ansible-deprecated-unnecessary-collection-name
+                            msg=d['msg'],
+                            version=d.get('version'),
+                            date=d.get('date'),
+                            deprecator=_deprecator.get_best_deprecator(collection_name=d.get('collection_name')),
+                        )
                     else:
-                        self.deprecate(d)  # pylint: disable=ansible-deprecated-no-version
+                        self.deprecate(  # pylint: disable=ansible-deprecated-unnecessary-collection-name,ansible-deprecated-no-version
+                            msg=d,
+                            deprecator=_deprecator.get_best_deprecator(),
+                        )
             else:
-                self.deprecate(kwargs['deprecations'])  # pylint: disable=ansible-deprecated-no-version
+                self.deprecate(  # pylint: disable=ansible-deprecated-unnecessary-collection-name,ansible-deprecated-no-version
+                    msg=kwargs['deprecations'],
+                    deprecator=_deprecator.get_best_deprecator(),
+                )
 
         deprecations = get_deprecations()
         if deprecations:
@@ -1452,6 +1496,7 @@ class AnsibleModule(object):
 
     def exit_json(self, **kwargs) -> t.NoReturn:
         """ return from the module, without error """
+        _skip_stackwalk = True
 
         self.do_cleanup_files()
         self._return_formatted(kwargs)
@@ -1473,6 +1518,8 @@ class AnsibleModule(object):
         When `exception` is not specified, a formatted traceback will be retrieved from the current exception.
         If no exception is pending, the current call stack will be used instead.
         """
+        _skip_stackwalk = True
+
         msg = str(msg)  # coerce to str instead of raising an error due to an invalid type
 
         kwargs.update(

ansible/module_utils/common/arg_spec.py

@@ -22,6 +22,7 @@ from ansible.module_utils.common.parameters import (
 
 from ansible.module_utils.common.text.converters import to_native
 from ansible.module_utils.common.warnings import deprecate, warn
+from ansible.module_utils.common import messages as _messages
 
 from ansible.module_utils.common.validation import (
     check_mutually_exclusive,
@@ -300,9 +301,13 @@ class ModuleArgumentSpecValidator(ArgumentSpecValidator):
         result = super(ModuleArgumentSpecValidator, self).validate(parameters)
 
         for d in result._deprecations:
-            deprecate(d['msg'],
-                      version=d.get('version'), date=d.get('date'),
-                      collection_name=d.get('collection_name'))
+            # DTFIX-FUTURE: pass an actual deprecator instead of one derived from collection_name
+            deprecate(  # pylint: disable=ansible-deprecated-date-not-permitted,ansible-deprecated-unnecessary-collection-name
+                msg=d['msg'],
+                version=d.get('version'),
+                date=d.get('date'),
+                deprecator=_messages.PluginInfo._from_collection_name(d.get('collection_name')),
+            )
 
         for w in result._warnings:
             warn('Both option {option} and its alias {alias} are set.'.format(option=w['option'], alias=w['alias']))

ansible/module_utils/common/messages.py

@@ -13,7 +13,7 @@ import dataclasses as _dataclasses
 # deprecated: description='typing.Self exists in Python 3.11+' python_version='3.10'
 from ..compat import typing as _t
 
-from ansible.module_utils._internal import _datatag
+from ansible.module_utils._internal import _datatag, _validation
 
 if _sys.version_info >= (3, 10):
     # Using slots for reduced memory usage and improved performance.
@@ -27,13 +27,27 @@ else:
 class PluginInfo(_datatag.AnsibleSerializableDataclass):
     """Information about a loaded plugin."""
 
-    requested_name: str
-    """The plugin name as requested, before resolving, which may be partially or fully qualified."""
     resolved_name: str
     """The resolved canonical plugin name; always fully-qualified for collection plugins."""
     type: str
     """The plugin type."""
 
+    _COLLECTION_ONLY_TYPE: _t.ClassVar[str] = 'collection'
+    """This is not a real plugin type. It's a placeholder for use by a `PluginInfo` instance which references a collection without a plugin."""
+
+    @classmethod
+    def _from_collection_name(cls, collection_name: str | None) -> _t.Self | None:
+        """Returns an instance with the special `collection` type to refer to a non-plugin or ambiguous caller within a collection."""
+        if not collection_name:
+            return None
+
+        _validation.validate_collection_name(collection_name)
+
+        return cls(
+            resolved_name=collection_name,
+            type=cls._COLLECTION_ONLY_TYPE,
+        )
+
 
 @_dataclasses.dataclass(**_dataclass_kwargs)
 class Detail(_datatag.AnsibleSerializableDataclass):
@@ -75,34 +89,37 @@ class WarningSummary(SummaryBase):
 class DeprecationSummary(WarningSummary):
     """Deprecation summary with details (possibly derived from an exception __cause__ chain) and an optional traceback."""
 
-    version: _t.Optional[str] = None
-    date: _t.Optional[str] = None
-    plugin: _t.Optional[PluginInfo] = None
-
-    @property
-    def collection_name(self) -> _t.Optional[str]:
-        if not self.plugin:
-            return None
-
-        parts = self.plugin.resolved_name.split('.')
-
-        if len(parts) < 2:
-            return None
-
-        collection_name = '.'.join(parts[:2])
+    deprecator: _t.Optional[PluginInfo] = None
+    """
+    The identifier for the content which is being deprecated.
+    """
 
-        # deprecated: description='enable the deprecation message for collection_name' core_version='2.23'
-        # from ansible.module_utils.datatag import deprecate_value
-        # collection_name = deprecate_value(collection_name, 'The `collection_name` property is deprecated.', removal_version='2.27')
+    date: _t.Optional[str] = None
+    """
+    The date after which a new release of `deprecator` will remove the feature described by `msg`.
+    Ignored if `deprecator` is not provided.
+    """
 
-        return collection_name
+    version: _t.Optional[str] = None
+    """
+    The version of `deprecator` which will remove the feature described by `msg`.
+    Ignored if `deprecator` is not provided.
+    Ignored if `date` is provided.
+    """
 
     def _as_simple_dict(self) -> _t.Dict[str, _t.Any]:
         """Returns a dictionary representation of the deprecation object in the format exposed to playbooks."""
+        from ansible.module_utils._internal._deprecator import INDETERMINATE_DEPRECATOR  # circular import from messages
+
+        if self.deprecator and self.deprecator != INDETERMINATE_DEPRECATOR:
+            collection_name = '.'.join(self.deprecator.resolved_name.split('.')[:2])
+        else:
+            collection_name = None
+
         result = self._as_dict()
         result.update(
             msg=self._format(),
-            collection_name=self.collection_name,
+            collection_name=collection_name,
         )
 
         return result

ansible/module_utils/common/process.py

@@ -29,7 +29,6 @@ def get_bin_path(arg, opt_dirs=None, required=None):
         deprecate(
             msg="The `required` parameter in `get_bin_path` API is deprecated.",
             version="2.21",
-            collection_name="ansible.builtin",
         )
 
     paths = []

ansible/module_utils/common/respawn.py

@@ -3,14 +3,12 @@
 
 from __future__ import annotations
 
-import dataclasses
 import os
 import pathlib
 import subprocess
 import sys
 import typing as t
 
-from ansible.module_utils._internal import _plugin_exec_context
 from ansible.module_utils.common.text.converters import to_bytes
 
 _ANSIBLE_PARENT_PATH = pathlib.Path(__file__).parents[3]
@@ -99,7 +97,6 @@ if __name__ == '__main__':
 
     json_params = {json_params!r}
     profile = {profile!r}
-    plugin_info_dict = {plugin_info_dict!r}
     module_fqn = {module_fqn!r}
     modlib_path = {modlib_path!r}
 
@@ -110,19 +107,15 @@ if __name__ == '__main__':
     _ansiballz.run_module(
         json_params=json_params,
         profile=profile,
-        plugin_info_dict=plugin_info_dict,
         module_fqn=module_fqn,
         modlib_path=modlib_path,
         init_globals=dict(_respawned=True),
     )
 """
 
-    plugin_info = _plugin_exec_context.PluginExecContext.get_current_plugin_info()
-
     respawn_code = respawn_code_template.format(
         json_params=basic._ANSIBLE_ARGS,
         profile=basic._ANSIBLE_PROFILE,
-        plugin_info_dict=dataclasses.asdict(plugin_info),
         module_fqn=module_fqn,
         modlib_path=modlib_path,
     )