ansible-core 2.19.0b1__py3-none-any.whl → 2.19.0b3__py3-none-any.whl

ansible/executor/task_result.py

@@ -4,15 +4,24 @@
 
 from __future__ import annotations
 
+import collections.abc as _c
+import dataclasses
+import functools
 import typing as t
 
-from ansible import constants as C
-from ansible.parsing.dataloader import DataLoader
+from ansible import constants
+from ansible.utils import vars as _vars
 from ansible.vars.clean import module_response_deepcopy, strip_internal_keys
+from ansible.module_utils.common import messages as _messages
+from ansible._internal import _collection_proxy
+
+if t.TYPE_CHECKING:
+    from ansible.inventory.host import Host
+    from ansible.playbook.task import Task
 
 _IGNORE = ('failed', 'skipped')
-_PRESERVE = ('attempts', 'changed', 'retries', '_ansible_no_log')
-_SUB_PRESERVE = {'_ansible_delegated_vars': ('ansible_host', 'ansible_port', 'ansible_user', 'ansible_connection')}
+_PRESERVE = {'attempts', 'changed', 'retries', '_ansible_no_log'}
+_SUB_PRESERVE = {'_ansible_delegated_vars': {'ansible_host', 'ansible_port', 'ansible_user', 'ansible_connection'}}
 
 # stuff callbacks need
 CLEAN_EXCEPTIONS = (
@@ -23,61 +32,120 @@ CLEAN_EXCEPTIONS = (
 )
 
 
-class TaskResult:
+@t.final
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class _WireTaskResult:
+    """A thin version of `_RawTaskResult` which can be sent over the worker queue."""
+
+    host_name: str
+    task_uuid: str
+    return_data: _c.MutableMapping[str, object]
+    task_fields: _c.Mapping[str, object]
+
+
+class _BaseTaskResult:
     """
     This class is responsible for interpreting the resulting data
     from an executed task, and provides helper methods for determining
     the result of a given task.
     """
 
-    def __init__(self, host, task, return_data, task_fields=None):
-        self._host = host
-        self._task = task
+    def __init__(self, host: Host, task: Task, return_data: _c.MutableMapping[str, t.Any], task_fields: _c.Mapping[str, t.Any]) -> None:
+        self.__host = host
+        self.__task = task
+        self._return_data = return_data  # FIXME: this should be immutable, but strategy result processing mutates it in some corner cases
+        self.__task_fields = task_fields
 
-        if isinstance(return_data, dict):
-            self._result = return_data.copy()
-        else:
-            self._result = DataLoader().load(return_data)
+    @property
+    def host(self) -> Host:
+        """The host associated with this result."""
+        return self.__host
 
-        if task_fields is None:
-            self._task_fields = dict()
-        else:
-            self._task_fields = task_fields
+    @property
+    def _host(self) -> Host:
+        """Use the `host` property when supporting only ansible-core 2.19 or later."""
+        # deprecated: description='Deprecate `_host` in favor of `host`' core_version='2.23'
+        return self.__host
+
+    @property
+    def task(self) -> Task:
+        """The task associated with this result."""
+        return self.__task
+
+    @property
+    def _task(self) -> Task:
+        """Use the `task` property when supporting only ansible-core 2.19 or later."""
+        # deprecated: description='Deprecate `_task` in favor of `task`' core_version='2.23'
+        return self.__task
+
+    @property
+    def task_fields(self) -> _c.Mapping[str, t.Any]:
+        """The task fields associated with this result."""
+        return self.__task_fields
+
+    @property
+    def _task_fields(self) -> _c.Mapping[str, t.Any]:
+        """Use the `task_fields` property when supporting only ansible-core 2.19 or later."""
+        # deprecated: description='Deprecate `_task_fields` in favor of `task`' core_version='2.23'
+        return self.__task_fields
+
+    @property
+    def exception(self) -> _messages.ErrorSummary | None:
+        """The error from this task result, if any."""
+        return self._return_data.get('exception')
+
+    @property
+    def warnings(self) -> _c.Sequence[_messages.WarningSummary]:
+        """The warnings for this task, if any."""
+        return _collection_proxy.SequenceProxy(self._return_data.get('warnings') or [])
+
+    @property
+    def deprecations(self) -> _c.Sequence[_messages.DeprecationSummary]:
+        """The deprecation warnings for this task, if any."""
+        return _collection_proxy.SequenceProxy(self._return_data.get('deprecations') or [])
+
+    @property
+    def _loop_results(self) -> list[_c.MutableMapping[str, t.Any]]:
+        """Return a list of loop results. If no loop results are present, an empty list is returned."""
+        results = self._return_data.get('results')
+
+        if not isinstance(results, list):
+            return []
+
+        return results
 
     @property
-    def task_name(self):
-        return self._task_fields.get('name', None) or self._task.get_name()
+    def task_name(self) -> str:
+        return str(self.task_fields.get('name', '')) or self.task.get_name()
 
-    def is_changed(self):
+    def is_changed(self) -> bool:
         return self._check_key('changed')
 
-    def is_skipped(self):
-        # loop results
-        if 'results' in self._result:
-            results = self._result['results']
+    def is_skipped(self) -> bool:
+        if self._loop_results:
             # Loop tasks are only considered skipped if all items were skipped.
             # some squashed results (eg, dnf) are not dicts and can't be skipped individually
-            if results and all(isinstance(res, dict) and res.get('skipped', False) for res in results):
+            if all(isinstance(loop_res, dict) and loop_res.get('skipped', False) for loop_res in self._loop_results):
                 return True
 
         # regular tasks and squashed non-dict results
-        return self._result.get('skipped', False)
+        return bool(self._return_data.get('skipped', False))
 
-    def is_failed(self):
-        if 'failed_when_result' in self._result or \
-           'results' in self._result and True in [True for x in self._result['results'] if 'failed_when_result' in x]:
+    def is_failed(self) -> bool:
+        if 'failed_when_result' in self._return_data or any(isinstance(loop_res, dict) and 'failed_when_result' in loop_res for loop_res in self._loop_results):
             return self._check_key('failed_when_result')
-        else:
-            return self._check_key('failed')
 
-    def is_unreachable(self):
+        return self._check_key('failed')
+
+    def is_unreachable(self) -> bool:
         return self._check_key('unreachable')
 
-    def needs_debugger(self, globally_enabled=False):
-        _debugger = self._task_fields.get('debugger')
-        _ignore_errors = C.TASK_DEBUGGER_IGNORE_ERRORS and self._task_fields.get('ignore_errors')
+    def needs_debugger(self, globally_enabled: bool = False) -> bool:
+        _debugger = self.task_fields.get('debugger')
+        _ignore_errors = constants.TASK_DEBUGGER_IGNORE_ERRORS and self.task_fields.get('ignore_errors')
 
         ret = False
+
         if globally_enabled and ((self.is_failed() and not _ignore_errors) or self.is_unreachable()):
             ret = True
 
@@ -94,68 +162,96 @@ class TaskResult:
 
         return ret
 
-    def _check_key(self, key):
-        """get a specific key from the result or its items"""
+    def _check_key(self, key: str) -> bool:
+        """Fetch a specific named boolean value from the result; if missing, a logical OR of the value from nested loop results; False for non-loop results."""
+        if (value := self._return_data.get(key, ...)) is not ...:
+            return bool(value)
 
-        if isinstance(self._result, dict) and key in self._result:
-            return self._result.get(key, False)
-        else:
-            flag = False
-            for res in self._result.get('results', []):
-                if isinstance(res, dict):
-                    flag |= res.get(key, False)
-            return flag
+        return any(isinstance(result, dict) and result.get(key) for result in self._loop_results)
 
-    def clean_copy(self):
 
-        """ returns 'clean' taskresult object """
+@t.final
+class _RawTaskResult(_BaseTaskResult):
+    def as_wire_task_result(self) -> _WireTaskResult:
+        """Return a `_WireTaskResult` from this instance."""
+        return _WireTaskResult(
+            host_name=self.host.name,
+            task_uuid=self.task._uuid,
+            return_data=self._return_data,
+            task_fields=self.task_fields,
+        )
 
-        # FIXME: clean task_fields, _task and _host copies
-        result = TaskResult(self._host, self._task, {}, self._task_fields)
+    def as_callback_task_result(self) -> CallbackTaskResult:
+        """Return a `CallbackTaskResult` from this instance."""
+        ignore: tuple[str, ...]
 
         # statuses are already reflected on the event type
-        if result._task and result._task.action in C._ACTION_DEBUG:
+        if self.task and self.task.action in constants._ACTION_DEBUG:
             # debug is verbose by default to display vars, no need to add invocation
             ignore = _IGNORE + ('invocation',)
         else:
             ignore = _IGNORE
 
-        subset = {}
+        subset: dict[str, dict[str, object]] = {}
+
         # preserve subset for later
-        for sub in _SUB_PRESERVE:
-            if sub in self._result:
-                subset[sub] = {}
-                for key in _SUB_PRESERVE[sub]:
-                    if key in self._result[sub]:
-                        subset[sub][key] = self._result[sub][key]
+        for sub, sub_keys in _SUB_PRESERVE.items():
+            sub_data = self._return_data.get(sub)
+
+            if isinstance(sub_data, dict):
+                subset[sub] = {key: value for key, value in sub_data.items() if key in sub_keys}
 
         # DTFIX-FUTURE: is checking no_log here redundant now that we use _ansible_no_log everywhere?
-        if isinstance(self._task.no_log, bool) and self._task.no_log or self._result.get('_ansible_no_log'):
-            censored_result = censor_result(self._result)
+        if isinstance(self.task.no_log, bool) and self.task.no_log or self._return_data.get('_ansible_no_log'):
+            censored_result = censor_result(self._return_data)
 
-            if results := self._result.get('results'):
+            if self._loop_results:
                 # maintain shape for loop results so callback behavior recognizes a loop was performed
-                censored_result.update(results=[censor_result(item) if item.get('_ansible_no_log') else item for item in results])
+                censored_result.update(results=[
+                    censor_result(loop_res) if isinstance(loop_res, dict) and loop_res.get('_ansible_no_log') else loop_res for loop_res in self._loop_results
+                ])
 
-            result._result = censored_result
-        elif self._result:
-            result._result = module_response_deepcopy(self._result)
-
-            # actually remove
-            for remove_key in ignore:
-                if remove_key in result._result:
-                    del result._result[remove_key]
+            return_data = censored_result
+        elif self._return_data:
+            return_data = {k: v for k, v in module_response_deepcopy(self._return_data).items() if k not in ignore}
 
             # remove almost ALL internal keys, keep ones relevant to callback
-            strip_internal_keys(result._result, exceptions=CLEAN_EXCEPTIONS)
+            strip_internal_keys(return_data, exceptions=CLEAN_EXCEPTIONS)
+        else:
+            return_data = {}
 
         # keep subset
-        result._result.update(subset)
+        return_data.update(subset)
+
+        return CallbackTaskResult(self.host, self.task, return_data, self.task_fields)
+
+
+@t.final
+class CallbackTaskResult(_BaseTaskResult):
+    """Public contract of TaskResult """
+
+    # DTFIX-RELEASE: find a better home for this since it's public API
+
+    @property
+    def _result(self) -> _c.MutableMapping[str, t.Any]:
+        """Use the `result` property when supporting only ansible-core 2.19 or later."""
+        # deprecated: description='Deprecate `_result` in favor of `result`' core_version='2.23'
+        return self.result
+
+    @functools.cached_property
+    def result(self) -> _c.MutableMapping[str, t.Any]:
+        """
+        Returns a cached copy of the task result dictionary for consumption by callbacks.
+        Internal custom types are transformed to native Python types to facilitate access and serialization.
+        """
+        return t.cast(_c.MutableMapping[str, t.Any], _vars.transform_to_native_types(self._return_data))
+
 
-        return result
+TaskResult = CallbackTaskResult
+"""Compatibility name for the pre-2.19 callback-shaped TaskResult passed to callbacks."""
 
 
-def censor_result(result: dict[str, t.Any]) -> dict[str, t.Any]:
+def censor_result(result: _c.Mapping[str, t.Any]) -> dict[str, t.Any]:
     censored_result = {key: value for key in _PRESERVE if (value := result.get(key, ...)) is not ...}
     censored_result.update(censored="the output has been hidden due to the fact that 'no_log: true' was specified for this result")
 

ansible/galaxy/api.py

@@ -138,7 +138,7 @@ def g_connect(versions):
                     'The v2 Ansible Galaxy API is deprecated and no longer supported. '
                     'Ensure that you have configured the ansible-galaxy CLI to utilize an '
                     'updated and supported version of Ansible Galaxy.',
-                    version='2.20'
+                    version='2.20',
                 )
 
             return method(self, *args, **kwargs)

ansible/galaxy/collection/__init__.py

@@ -201,9 +201,9 @@ class CollectionSignatureError(Exception):
 
 # FUTURE: expose actual verify result details for a collection on this object, maybe reimplement as dataclass on py3.8+
 class CollectionVerifyResult:
-    def __init__(self, collection_name):  # type: (str) -> None
-        self.collection_name = collection_name  # type: str
-        self.success = True  # type: bool
+    def __init__(self, collection_name: str) -> None:
+        self.collection_name = collection_name
+        self.success = True
 
 
 def verify_local_collection(local_collection, remote_collection, artifacts_manager):

ansible/inventory/manager.py

@@ -30,6 +30,7 @@ from random import shuffle
 
 from ansible import constants as C
 from ansible._internal import _json, _wrapt
+from ansible._internal._json import EncryptedStringBehavior
 from ansible.errors import AnsibleError, AnsibleOptionsError
 from ansible.inventory.data import InventoryData
 from ansible.module_utils.six import string_types
@@ -787,7 +788,7 @@ class _InventoryDataWrapper(_wrapt.ObjectProxy):
         return _json.AnsibleVariableVisitor(
             trusted_as_template=self._target_plugin.trusted_by_default,
             origin=self._default_origin,
-            allow_encrypted_string=True,
+            encrypted_string_behavior=EncryptedStringBehavior.PRESERVE,
         )
 
     def set_variable(self, entity: str, varname: str, value: t.Any) -> None:

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.0b1'
+__version__ = '2.19.0b3'
 __author__ = 'Ansible, Inc.'
 __codename__ = "What Is and What Should Never Be"