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

ansible/plugins/strategy/__init__.py

@@ -822,12 +822,12 @@ class StrategyBase:
         """
         if handle_stats_and_callbacks:
             display.deprecated(
-                "Reporting play recap stats and running callbacks functionality for "
-                "``include_tasks`` in ``StrategyBase._load_included_file`` is deprecated. "
-                "See ``https://github.com/ansible/ansible/pull/79260`` for guidance on how to "
-                "move the reporting into specific strategy plugins to account for "
-                "``include_role`` tasks as well.",
-                version="2.21"
+                msg="Reporting play recap stats and running callbacks functionality for "
+                    "``include_tasks`` in ``StrategyBase._load_included_file`` is deprecated. "
+                    "See ``https://github.com/ansible/ansible/pull/79260`` for guidance on how to "
+                    "move the reporting into specific strategy plugins to account for "
+                    "``include_role`` tasks as well.",
+                version="2.21",
             )
         display.debug("loading included file: %s" % included_file._filename)
         try:

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/template/__init__.py

@@ -388,7 +388,7 @@ def generate_ansible_template_vars(path: str, fullpath: str | None = None, dest_
         value=ansible_managed,
         msg="The `ansible_managed` variable is deprecated.",
         help_text="Define and use a custom variable instead.",
-        removal_version='2.23',
+        version='2.23',
     )
 
     temp_vars = dict(

ansible/utils/collection_loader/__init__.py

@@ -13,6 +13,8 @@ import typing as t
 class _EncryptedStringProtocol(t.Protocol):
     """Protocol representing an `EncryptedString`, since it cannot be imported here."""
 
+    # DTFIX-FUTURE: collapse this with the one in config, once we can
+
     def _decrypt(self) -> str: ...
 
 

ansible/utils/collection_loader/_collection_meta.py

@@ -24,11 +24,13 @@ def _meta_yml_to_dict(yaml_string_data: bytes | str, content_id):
     import yaml
 
     try:
-        from yaml import CSafeLoader as SafeLoader
+        from yaml import CBaseLoader as BaseLoader
     except (ImportError, AttributeError):
-        from yaml import SafeLoader  # type: ignore[assignment]
+        from yaml import BaseLoader  # type: ignore[assignment]
 
-    routing_dict = yaml.load(yaml_string_data, Loader=SafeLoader)
+    # Using BaseLoader ensures that all scalars are strings.
+    # Doing so avoids parsing unquoted versions as floats, dates as datetime.date, etc.
+    routing_dict = yaml.load(yaml_string_data, Loader=BaseLoader)
     if not routing_dict:
         routing_dict = {}
     if not isinstance(routing_dict, Mapping):

ansible/utils/display.py

@@ -18,7 +18,6 @@
 from __future__ import annotations
 
 import dataclasses
-import datetime
 
 try:
     import curses
@@ -50,9 +49,10 @@ from functools import wraps
 from struct import unpack, pack
 
 from ansible import constants as C
+from ansible.constants import config
 from ansible.errors import AnsibleAssertionError, AnsiblePromptInterrupt, AnsiblePromptNoninteractive, AnsibleError
 from ansible._internal._errors import _utils
-from ansible.module_utils._internal import _ambient_context, _plugin_exec_context
+from ansible.module_utils._internal import _ambient_context, _deprecator
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible._internal._datatag._tags import TrustedAsTemplate
 from ansible.module_utils.common.messages import ErrorSummary, WarningSummary, DeprecationSummary, Detail, SummaryBase, PluginInfo
@@ -76,8 +76,6 @@ _LIBC.wcswidth.argtypes = (ctypes.c_wchar_p, ctypes.c_int)
 # Max for c_int
 _MAX_INT = 2 ** (ctypes.sizeof(ctypes.c_int) * 8 - 1) - 1
 
-_UNSET = t.cast(t.Any, object())
-
 MOVE_TO_BOL = b'\r'
 CLEAR_TO_EOL = b'\x1b[K'
 
@@ -555,7 +553,7 @@ class Display(metaclass=Singleton):
         msg: str,
         version: str | None = None,
         removed: bool = False,
-        date: str | datetime.date | None = None,
+        date: str | None = None,
         collection_name: str | None = None,
     ) -> str:
         """Return a deprecation message and help text for non-display purposes (e.g., exception messages)."""
@@ -570,7 +568,7 @@ class Display(metaclass=Singleton):
             version=version,
             removed=removed,
             date=date,
-            plugin=_plugin_exec_context.PluginExecContext.get_current_plugin_info(),
+            deprecator=PluginInfo._from_collection_name(collection_name),
         )
 
         if removed:
@@ -582,57 +580,63 @@ class Display(metaclass=Singleton):
 
     def _get_deprecation_message_with_plugin_info(
         self,
+        *,
         msg: str,
-        version: str | None = None,
+        version: str | None,
         removed: bool = False,
-        date: str | datetime.date | None = None,
-        plugin: PluginInfo | None = None,
+        date: str | None,
+        deprecator: PluginInfo | None,
     ) -> str:
         """Internal use only. Return a deprecation message and help text for display."""
-        msg = msg.strip()
-
-        if msg and msg[-1] not in ['!', '?', '.']:
-            msg += '.'
+        # DTFIX-RELEASE: the logic for omitting date/version doesn't apply to the payload, so it shows up in vars in some cases when it should not
 
         if removed:
             removal_fragment = 'This feature was removed'
-            help_text = 'Please update your playbooks.'
         else:
             removal_fragment = 'This feature will be removed'
-            help_text = ''
 
-        if plugin:
-            from_fragment = f'from the {self._describe_plugin_info(plugin)}'
+        if not deprecator or deprecator.type == _deprecator.INDETERMINATE_DEPRECATOR.type:
+            collection = None
+            plugin_fragment = ''
+        elif deprecator.type == _deprecator.PluginInfo._COLLECTION_ONLY_TYPE:
+            collection = deprecator.resolved_name
+            plugin_fragment = ''
         else:
-            from_fragment = ''
+            parts = deprecator.resolved_name.split('.')
+            plugin_name = parts[-1]
+            # DTFIX-RELEASE: normalize 'modules' -> 'module' before storing it so we can eliminate the normalization here
+            plugin_type = "module" if deprecator.type in ("module", "modules") else f'{deprecator.type} plugin'
 
-        if date:
-            when = 'in a release after {0}.'.format(date)
-        elif version:
-            when = 'in version {0}.'.format(version)
-        else:
-            when = 'in a future release.'
+            collection = '.'.join(parts[:2]) if len(parts) > 2 else None
+            plugin_fragment = f'{plugin_type} {plugin_name!r}'
 
-        message_text = ' '.join(f for f in [msg, removal_fragment, from_fragment, when, help_text] if f)
+        if collection and plugin_fragment:
+            plugin_fragment += ' in'
 
-        return message_text
+        if collection == 'ansible.builtin':
+            collection_fragment = 'ansible-core'
+        elif collection:
+            collection_fragment = f'collection {collection!r}'
+        else:
+            collection_fragment = ''
 
-    @staticmethod
-    def _describe_plugin_info(plugin_info: PluginInfo) -> str:
-        """Return a brief description of the plugin info, including name(s) and type."""
-        name = repr(plugin_info.resolved_name)
-        clarification = f' (requested as {plugin_info.requested_name!r})' if plugin_info.requested_name != plugin_info.resolved_name else ''
-
-        if plugin_info.type in ("module", "modules"):
-            # DTFIX-RELEASE: pluginloader or AnsiblePlugin needs a "type desc" property that doesn't suffer from legacy "inconsistencies" like this
-            plugin_type = "module"
-        elif plugin_info.type == "collection":
-            # not a real plugin type, but used for tombstone errors generated by plugin loader
-            plugin_type = plugin_info.type
+        if not collection:
+            when_fragment = 'in the future' if not removed else ''
+        elif date:
+            when_fragment = f'in a release after {date}'
+        elif version:
+            when_fragment = f'version {version}'
         else:
-            plugin_type = f'{plugin_info.type} plugin'
+            when_fragment = 'in a future release' if not removed else ''
 
-        return f'{name} {plugin_type}{clarification}'
+        if plugin_fragment or collection_fragment:
+            from_fragment = 'from'
+        else:
+            from_fragment = ''
+
+        deprecation_msg = ' '.join(f for f in [removal_fragment, from_fragment, plugin_fragment, collection_fragment, when_fragment] if f) + '.'
+
+        return _join_sentences(msg, deprecation_msg)
 
     def _wrap_message(self, msg: str, wrap_text: bool) -> str:
         if wrap_text and self._wrap_stderr:
@@ -661,20 +665,24 @@ class Display(metaclass=Singleton):
         msg: str,
         version: str | None = None,
         removed: bool = False,
-        date: str | datetime.date | None = None,
-        collection_name: str | None = _UNSET,
+        date: str | None = None,
+        collection_name: str | None = None,
         *,
+        deprecator: PluginInfo | None = None,
         help_text: str | None = None,
         obj: t.Any = None,
     ) -> None:
-        """Display a deprecation warning message, if enabled."""
-        # deprecated: description='enable the deprecation message for collection_name' core_version='2.23'
-        # if collection_name is not _UNSET:
-        #     self.deprecated('The `collection_name` argument to `deprecated` is deprecated.', version='2.27')
-
+        """
+        Display a deprecation warning message, if enabled.
+        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`.
+        """
         # DTFIX-RELEASE: are there any deprecation calls where the feature is switching from enabled to disabled, rather than being removed entirely?
         # DTFIX-RELEASE: are there deprecated features which should going through deferred deprecation instead?
 
+        _skip_stackwalk = True
+
         self._deprecated_with_plugin_info(
             msg=msg,
             version=version,
@@ -682,32 +690,36 @@ class Display(metaclass=Singleton):
             date=date,
             help_text=help_text,
             obj=obj,
-            plugin=_plugin_exec_context.PluginExecContext.get_current_plugin_info(),
+            deprecator=_deprecator.get_best_deprecator(deprecator=deprecator, collection_name=collection_name),
         )
 
     def _deprecated_with_plugin_info(
         self,
+        *,
         msg: str,
-        version: str | None = None,
+        version: str | None,
         removed: bool = False,
-        date: str | datetime.date | None = None,
-        *,
-        help_text: str | None = None,
-        obj: t.Any = None,
-        plugin: PluginInfo | None = None,
+        date: str | None,
+        help_text: str | None,
+        obj: t.Any,
+        deprecator: PluginInfo | None,
     ) -> None:
         """
         This is the internal pre-proxy half of the `deprecated` implementation.
         Any logic that must occur on workers needs to be implemented here.
         """
+        _skip_stackwalk = True
+
         if removed:
-            raise AnsibleError(self._get_deprecation_message_with_plugin_info(
+            formatted_msg = self._get_deprecation_message_with_plugin_info(
                 msg=msg,
                 version=version,
                 removed=removed,
                 date=date,
-                plugin=plugin,
-            ))
+                deprecator=deprecator,
+            )
+
+            raise AnsibleError(formatted_msg)
 
         if source_context := _utils.SourceContext.from_value(obj):
             formatted_source_context = str(source_context)
@@ -723,8 +735,8 @@ class Display(metaclass=Singleton):
                 ),
             ),
             version=version,
-            date=str(date) if isinstance(date, datetime.date) else date,
-            plugin=plugin,
+            date=date,
+            deprecator=deprecator,
             formatted_traceback=_traceback.maybe_capture_traceback(_traceback.TracebackEvent.DEPRECATED),
         )
 
@@ -1225,20 +1237,74 @@ def _get_message_lines(message: str, help_text: str | None, formatted_source_con
     return message_lines
 
 
+def _join_sentences(first: str | None, second: str | None) -> str:
+    """Join two sentences together."""
+    first = (first or '').strip()
+    second = (second or '').strip()
+
+    if first and first[-1] not in ('!', '?', '.'):
+        first += '.'
+
+    if second and second[-1] not in ('!', '?', '.'):
+        second += '.'
+
+    if first and not second:
+        return first
+
+    if not first and second:
+        return second
+
+    return ' '.join((first, second))
+
+
 def format_message(summary: SummaryBase) -> str:
-    details: t.Sequence[Detail]
+    details: c.Sequence[Detail] = summary.details
+
+    if isinstance(summary, DeprecationSummary) and details:
+        # augment the first detail element for deprecations to include additional diagnostic info and help text
+        detail_list = list(details)
+        detail = detail_list[0]
+
+        deprecation_msg = _display._get_deprecation_message_with_plugin_info(
+            msg=detail.msg,
+            version=summary.version,
+            date=summary.date,
+            deprecator=summary.deprecator,
+        )
 
-    if isinstance(summary, DeprecationSummary):
-        details = [detail if idx else dataclasses.replace(
+        detail_list[0] = dataclasses.replace(
             detail,
-            msg=_display._get_deprecation_message_with_plugin_info(
-                msg=detail.msg,
-                version=summary.version,
-                date=summary.date,
-                plugin=summary.plugin,
-            ),
-        ) for idx, detail in enumerate(summary.details)]
-    else:
-        details = summary.details
+            msg=deprecation_msg,
+            help_text=detail.help_text,
+        )
+
+        details = detail_list
 
     return _format_error_details(details, summary.formatted_traceback)
+
+
+def _report_config_warnings(deprecator: PluginInfo) -> None:
+    """Called by config to report warnings/deprecations collected during a config parse."""
+    while config._errors:
+        msg, exception = config._errors.pop()
+        _display.error_as_warning(msg=msg, exception=exception)
+
+    while config.WARNINGS:
+        warn = config.WARNINGS.pop()
+        _display.warning(warn)
+
+    while config.DEPRECATED:
+        # tuple with name and options
+        dep = config.DEPRECATED.pop(0)
+        msg = config.get_deprecated_msg_from_config(dep[1]).replace("\t", "")
+
+        _display.deprecated(  # pylint: disable=ansible-deprecated-unnecessary-collection-name,ansible-invalid-deprecated-version
+            msg=f"{dep[0]} option. {msg}",
+            version=dep[1]['version'],
+            deprecator=deprecator,
+        )
+
+
+# emit any warnings or deprecations
+# in the event config fails before display is up, we'll lose warnings -- but that's OK, since everything is broken anyway
+_report_config_warnings(_deprecator.ANSIBLE_CORE_DEPRECATOR)

ansible/utils/plugin_docs.py

@@ -154,7 +154,8 @@ def add_fragments(doc, filename, fragment_loader, is_module=False):
             unknown_fragments.append(fragment_slug)
             continue
 
-        fragment_yaml = getattr(fragment_class, fragment_var, None)
+        # trust-tagged source propagates to loaded values; expressions and templates in config require trust
+        fragment_yaml = _tags.TrustedAsTemplate().tag(getattr(fragment_class, fragment_var, None))
         if fragment_yaml is None:
             if fragment_var != 'DOCUMENTATION':
                 # if it's asking for something specific that's missing, that's an error

ansible/utils/py3compat.py

@@ -6,7 +6,6 @@
 
 from __future__ import annotations
 
-import inspect
 import os
 
 from ansible.utils.display import Display
@@ -19,13 +18,8 @@ def __getattr__(name):
     if name != 'environ':
         raise AttributeError(name)
 
-    caller = inspect.stack()[1]
-
     display.deprecated(
-        (
-            'ansible.utils.py3compat.environ is deprecated in favor of os.environ. '
-            f'Accessed by {caller.filename} line number {caller.lineno}'
-        ),
+        msg='ansible.utils.py3compat.environ is deprecated in favor of os.environ.',
         version='2.20',
     )
 

ansible/utils/ssh_functions.py

@@ -56,7 +56,10 @@ def set_default_transport():
 
     # deal with 'smart' connection .. one time ..
     if C.DEFAULT_TRANSPORT == 'smart':
-        display.deprecated("The 'smart' option for connections is deprecated. Set the connection plugin directly instead.", version='2.20')
+        display.deprecated(
+            msg="The 'smart' option for connections is deprecated. Set the connection plugin directly instead.",
+            version='2.20',
+        )
 
         # see if SSH can support ControlPersist if not use paramiko
         if not check_for_controlpersist('ssh') and paramiko is not None:

ansible/vars/manager.py

@@ -25,6 +25,8 @@ from collections import defaultdict
 from collections.abc import Mapping, MutableMapping
 
 from ansible import constants as C
+from ansible.module_utils._internal import _deprecator
+from ansible.module_utils._internal._datatag import _tags
 from ansible.errors import (AnsibleError, AnsibleParserError, AnsibleUndefinedVariable, AnsibleFileNotFound,
                             AnsibleAssertionError, AnsibleValueOmittedError)
 from ansible.inventory.host import Host
@@ -32,7 +34,6 @@ from ansible.inventory.helpers import sort_groups, get_group_vars
 from ansible.inventory.manager import InventoryManager
 from ansible.module_utils.datatag import native_type_name
 from ansible.module_utils.six import text_type
-from ansible.module_utils.datatag import deprecate_value
 from ansible.parsing.dataloader import DataLoader
 from ansible._internal._templating._engine import TemplateEngine
 from ansible.plugins.loader import cache_loader
@@ -50,8 +51,12 @@ if t.TYPE_CHECKING:
 display = Display()
 
 # deprecated: description='enable top-level facts deprecation' core_version='2.20'
-# _DEPRECATE_TOP_LEVEL_FACT_MSG = sys.intern('Top-level facts are deprecated, use `ansible_facts` instead.')
-# _DEPRECATE_TOP_LEVEL_FACT_REMOVAL_VERSION = sys.intern('2.22')
+# _DEPRECATE_TOP_LEVEL_FACT_TAG = _tags.Deprecated(
+#     msg='Top-level facts are deprecated.',
+#     version='2.24',
+#     deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+#     help_text='Use `ansible_facts` instead.',
+# )
 
 
 def _deprecate_top_level_fact(value: t.Any) -> t.Any:
@@ -61,7 +66,7 @@ def _deprecate_top_level_fact(value: t.Any) -> t.Any:
     Unique tag instances are required to achieve the correct de-duplication within a top-level templating operation.
     """
     # deprecated: description='enable top-level facts deprecation' core_version='2.20'
-    # return deprecate_value(value, _DEPRECATE_TOP_LEVEL_FACT_MSG, removal_version=_DEPRECATE_TOP_LEVEL_FACT_REMOVAL_VERSION)
+    # return _DEPRECATE_TOP_LEVEL_FACT_TAG.tag(value)
     return value
 
 
@@ -96,6 +101,13 @@ class VariableManager:
     _ALLOWED = frozenset(['plugins_by_group', 'groups_plugins_play', 'groups_plugins_inventory', 'groups_inventory',
                           'all_plugins_play', 'all_plugins_inventory', 'all_inventory'])
 
+    _PLAY_HOSTS_DEPRECATED_TAG = _tags.Deprecated(
+        msg='The `play_hosts` magic variable is deprecated.',
+        version='2.23',
+        deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+        help_text='Use `ansible_play_batch` instead.',
+    )
+
     def __init__(self, loader: DataLoader | None = None, inventory: InventoryManager | None = None, version_info: dict[str, str] | None = None) -> None:
         self._nonpersistent_fact_cache: defaultdict[str, dict] = defaultdict(dict)
         self._vars_cache: defaultdict[str, dict] = defaultdict(dict)
@@ -477,12 +489,8 @@ class VariableManager:
                 variables['ansible_play_hosts'] = [x for x in variables['ansible_play_hosts_all'] if x not in play._removed_hosts]
                 variables['ansible_play_batch'] = [x for x in _hosts if x not in play._removed_hosts]
 
-                variables['play_hosts'] = deprecate_value(
-                    value=variables['ansible_play_batch'],
-                    msg='The `play_hosts` magic variable is deprecated.',
-                    removal_version='2.23',
-                    help_text='Use `ansible_play_batch` instead.',
-                )
+                # use a static tag instead of `deprecate_value` to avoid stackwalk in a hot code path
+                variables['play_hosts'] = self._PLAY_HOSTS_DEPRECATED_TAG.tag(variables['ansible_play_batch'])
 
         # Set options vars
         for option, option_value in self._options_vars.items():

ansible/vars/plugins.py

@@ -34,10 +34,10 @@ def get_plugin_vars(loader, plugin, path, entities):
     except AttributeError:
         if hasattr(plugin, 'get_host_vars') or hasattr(plugin, 'get_group_vars'):
             display.deprecated(
-                f"The vars plugin {plugin.ansible_name} from {plugin._original_path} is relying "
-                "on the deprecated entrypoints 'get_host_vars' and 'get_group_vars'. "
-                "This plugin should be updated to inherit from BaseVarsPlugin and define "
-                "a 'get_vars' method as the main entrypoint instead.",
+                msg=f"The vars plugin {plugin.ansible_name} from {plugin._original_path} is relying "
+                    "on the deprecated entrypoints 'get_host_vars' and 'get_group_vars'. "
+                    "This plugin should be updated to inherit from BaseVarsPlugin and define "
+                    "a 'get_vars' method as the main entrypoint instead.",
                 version="2.20",
             )
         try:

{ansible_core-2.19.0b2.dist-info → ansible_core-2.19.0b4.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: ansible-core
-Version: 2.19.0b2
+Version: 2.19.0b4
 Summary: Radically simple IT automation
 Author: Ansible Project
 Project-URL: Homepage, https://ansible.com/
@@ -38,6 +38,7 @@ Requires-Dist: PyYAML>=5.1
 Requires-Dist: cryptography
 Requires-Dist: packaging
 Requires-Dist: resolvelib<2.0.0,>=0.5.3
+Dynamic: license-file
 
 [![PyPI version](https://img.shields.io/pypi/v/ansible-core.svg)](https://pypi.org/project/ansible-core)
 [![Docs badge](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://docs.ansible.com/ansible/latest/)