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

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, ...)
-
 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 ''
+
+        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 f'{name} {plugin_type}{clarification}'
+        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,37 +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,
-            ))
-
-        if not _DeferredWarningContext.deprecation_warnings_enabled():
-            return
+                deprecator=deprecator,
+            )
 
-        self.warning('Deprecation warnings can be disabled by setting `deprecation_warnings=False` in ansible.cfg.')
+            raise AnsibleError(formatted_msg)
 
         if source_context := _utils.SourceContext.from_value(obj):
             formatted_source_context = str(source_context)
@@ -728,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),
         )
 
@@ -746,6 +753,11 @@ class Display(metaclass=Singleton):
         # This is the post-proxy half of the `deprecated` implementation.
         # Any logic that must occur in the primary controller process needs to be implemented here.
 
+        if not _DeferredWarningContext.deprecation_warnings_enabled():
+            return
+
+        self.warning('Deprecation warnings can be disabled by setting `deprecation_warnings=False` in ansible.cfg.')
+
         msg = format_message(warning)
         msg = f'[DEPRECATION WARNING]: {msg}'
 
@@ -983,8 +995,8 @@ class Display(metaclass=Singleton):
         msg: str,
         private: bool = False,
         seconds: int | None = None,
-        interrupt_input: c.Container[bytes] | None = None,
-        complete_input: c.Container[bytes] | None = None,
+        interrupt_input: c.Iterable[bytes] | None = None,
+        complete_input: c.Iterable[bytes] | None = None,
     ) -> bytes:
         if self._final_q:
             from ansible.executor.process.worker import current_worker
@@ -1039,8 +1051,8 @@ class Display(metaclass=Singleton):
         self,
         echo: bool = False,
         seconds: int | None = None,
-        interrupt_input: c.Container[bytes] | None = None,
-        complete_input: c.Container[bytes] | None = None,
+        interrupt_input: c.Iterable[bytes] | None = None,
+        complete_input: c.Iterable[bytes] | None = None,
     ) -> bytes:
         if self._final_q:
             raise NotImplementedError
@@ -1225,20 +1237,70 @@ 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.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/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/utils/vars.py

@@ -27,6 +27,7 @@ from json import dumps
 
 from ansible import constants as C
 from ansible import context
+from ansible._internal import _json
 from ansible.errors import AnsibleError, AnsibleOptionsError
 from ansible.module_utils.datatag import native_type_name
 from ansible.module_utils.common.text.converters import to_native, to_text
@@ -284,3 +285,25 @@ def validate_variable_name(name: object) -> None:
         help_text='Variable names must be strings starting with a letter or underscore character, and contain only letters, numbers and underscores.',
         obj=name,
     )
+
+
+def transform_to_native_types(
+    value: object,
+    redact: bool = True,
+) -> object:
+    """
+    Recursively transform the given value to Python native types.
+    Potentially sensitive values such as individually vaulted variables will be redacted unless ``redact=False`` is passed.
+    Which values are considered potentially sensitive may change in future releases.
+    Types which cannot be converted to Python native types will result in an error.
+    """
+    avv = _json.AnsibleVariableVisitor(
+        convert_mapping_to_dict=True,
+        convert_sequence_to_list=True,
+        convert_custom_scalars=True,
+        convert_to_native_values=True,
+        apply_transforms=True,
+        encrypted_string_behavior=_json.EncryptedStringBehavior.REDACT if redact else _json.EncryptedStringBehavior.DECRYPT,
+    )
+
+    return avv.visit(value)

ansible/vars/clean.py

@@ -42,7 +42,7 @@ def module_response_deepcopy(v):
     backwards compatibility, in case we need to extend this function
     to handle our specific needs:
 
-    * ``ansible.executor.task_result.TaskResult.clean_copy``
+    * ``ansible.executor.task_result._RawTaskResult.as_callback_task_result``
     * ``ansible.vars.clean.clean_facts``
     * ``ansible.vars.namespace_facts``
     """

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)
@@ -214,24 +226,6 @@ class VariableManager:
             all_group = self._inventory.groups.get('all')
             host_groups = sort_groups([g for g in host.get_groups() if g.name != 'all'])
 
-            def _get_plugin_vars(plugin, path, entities):
-                data = {}
-                try:
-                    data = plugin.get_vars(self._loader, path, entities)
-                except AttributeError:
-                    try:
-                        for entity in entities:
-                            if isinstance(entity, Host):
-                                data |= plugin.get_host_vars(entity.name)
-                            else:
-                                data |= plugin.get_group_vars(entity.name)
-                    except AttributeError:
-                        if hasattr(plugin, 'run'):
-                            raise AnsibleError("Cannot use v1 type vars plugin %s from %s" % (plugin._load_name, plugin._original_path))
-                        else:
-                            raise AnsibleError("Invalid vars plugin %s from %s" % (plugin._load_name, plugin._original_path))
-                return data
-
             # internal functions that actually do the work
             def _plugins_inventory(entities):
                 """ merges all entities by inventory source """
@@ -495,11 +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='Use `ansible_play_batch` instead of `play_hosts`.',
-                    removal_version='2.23',
-                )
+                # 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.0b1.dist-info → ansible_core-2.19.0b3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ansible-core
-Version: 2.19.0b1
+Version: 2.19.0b3
 Summary: Radically simple IT automation
 Author: Ansible Project
 Project-URL: Homepage, https://ansible.com/