ansible-core 2.19.2rc1__py3-none-any.whl → 2.20.0b1__py3-none-any.whl

ansible/_internal/__init__.py

@@ -30,10 +30,7 @@ def import_controller_module(module_name: str, /) -> t.Any:
     return importlib.import_module(module_name)
 
 
-_T = t.TypeVar('_T')
-
-
-def experimental(obj: _T) -> _T:
+def experimental[T](obj: T) -> T:
     """
     Decorator for experimental types and methods outside the `_internal` package which accept or expose internal types.
     As with internal APIs, these are subject to change at any time without notice.

ansible/_internal/_ansiballz/_builder.py

@@ -9,8 +9,6 @@ from ansible.module_utils._internal._ansiballz import _extensions
 from ansible.module_utils._internal._ansiballz._extensions import _debugpy, _pydevd, _coverage
 from ansible.constants import config
 
-_T = t.TypeVar('_T')
-
 
 class ExtensionManager:
     """AnsiballZ extension manager."""
@@ -101,7 +99,7 @@ class ExtensionManager:
         )
 
     @classmethod
-    def _get_options(cls, name: str, config_type: type[_T], task_vars: dict[str, object]) -> _T | None:
+    def _get_options[T](cls, name: str, config_type: type[T], task_vars: dict[str, object]) -> T | None:
         """Parse configuration from the named environment variable as the specified type, or None if not configured."""
         if (value := config.get_config_value(name, variables=task_vars)) is None:
             return None

ansible/_internal/_collection_proxy.py

@@ -3,26 +3,24 @@ from __future__ import annotations as _annotations
 import collections.abc as _c
 import typing as _t
 
-_T_co = _t.TypeVar('_T_co', covariant=True)
 
-
-class SequenceProxy(_c.Sequence[_T_co]):
+class SequenceProxy[T](_c.Sequence[T]):
     """A read-only sequence proxy."""
 
     # DTFIX5: needs unit test coverage
 
     __slots__ = ('__value',)
 
-    def __init__(self, value: _c.Sequence[_T_co]) -> None:
+    def __init__(self, value: _c.Sequence[T]) -> None:
         self.__value = value
 
     @_t.overload
-    def __getitem__(self, index: int) -> _T_co: ...
+    def __getitem__(self, index: int) -> T: ...
 
     @_t.overload
-    def __getitem__(self, index: slice) -> _c.Sequence[_T_co]: ...
+    def __getitem__(self, index: slice) -> _c.Sequence[T]: ...
 
-    def __getitem__(self, index: int | slice) -> _T_co | _c.Sequence[_T_co]:
+    def __getitem__(self, index: int | slice) -> T | _c.Sequence[T]:
         if isinstance(index, slice):
             return self.__class__(self.__value[index])
 
@@ -34,10 +32,10 @@ class SequenceProxy(_c.Sequence[_T_co]):
     def __contains__(self, item: object) -> bool:
         return item in self.__value
 
-    def __iter__(self) -> _t.Iterator[_T_co]:
+    def __iter__(self) -> _t.Iterator[T]:
         yield from self.__value
 
-    def __reversed__(self) -> _c.Iterator[_T_co]:
+    def __reversed__(self) -> _c.Iterator[T]:
         return reversed(self.__value)
 
     def index(self, *args) -> int:

ansible/_internal/_display_utils.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import dataclasses
+
+from ansible.module_utils._internal import _ambient_context, _messages
+from . import _event_formatting
+
+
+class DeferredWarningContext(_ambient_context.AmbientContextBase):
+    """
+    Calls to `Display.warning()` and `Display.deprecated()` within this context will cause the resulting warnings to be captured and not displayed.
+    The intended use is for task-initiated warnings to be recorded with the task result, which makes them visible to registered results, callbacks, etc.
+    The active display callback is responsible for communicating any warnings to the user.
+    """
+
+    # DTFIX-FUTURE: once we start implementing nested scoped contexts for our own bookkeeping, this should be an interface facade that forwards to the nearest
+    #               context that actually implements the warnings collection capability
+
+    def __init__(self, *, variables: dict[str, object]) -> None:
+        self._variables = variables  # DTFIX-FUTURE: move this to an AmbientContext-derived TaskContext (once it exists)
+        self._deprecation_warnings: list[_messages.DeprecationSummary] = []
+        self._warnings: list[_messages.WarningSummary] = []
+        self._seen: set[_messages.WarningSummary] = set()
+
+    def capture(self, warning: _messages.WarningSummary) -> None:
+        """Add the warning/deprecation to the context if it has not already been seen by this context."""
+        if warning in self._seen:
+            return
+
+        self._seen.add(warning)
+
+        if isinstance(warning, _messages.DeprecationSummary):
+            self._deprecation_warnings.append(warning)
+        else:
+            self._warnings.append(warning)
+
+    def get_warnings(self) -> list[_messages.WarningSummary]:
+        """Return a list of the captured non-deprecation warnings."""
+        # DTFIX-FUTURE: return a read-only list proxy instead
+        return self._warnings
+
+    def get_deprecation_warnings(self) -> list[_messages.DeprecationSummary]:
+        """Return a list of the captured deprecation warnings."""
+        # DTFIX-FUTURE: return a read-only list proxy instead
+        return self._deprecation_warnings
+
+
+def format_message(summary: _messages.SummaryBase, include_traceback: bool) -> str:
+    if isinstance(summary, _messages.DeprecationSummary):
+        deprecation_message = get_deprecation_message_with_plugin_info(
+            msg=summary.event.msg,
+            version=summary.version,
+            date=summary.date,
+            deprecator=summary.deprecator,
+        )
+
+        event = dataclasses.replace(summary.event, msg=deprecation_message)
+    else:
+        event = summary.event
+
+    return _event_formatting.format_event(event, include_traceback)
+
+
+def get_deprecation_message_with_plugin_info(
+    *,
+    msg: str,
+    version: str | None,
+    removed: bool = False,
+    date: str | None,
+    deprecator: _messages.PluginInfo | None,
+) -> str:
+    """Internal use only. Return a deprecation message and help text for display."""
+    # DTFIX-FUTURE: 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'
+    else:
+        removal_fragment = 'This feature will be removed'
+
+    if not deprecator or not deprecator.type:
+        # indeterminate has no resolved_name or type
+        # collections have a resolved_name but no type
+        collection = deprecator.resolved_name if deprecator else None
+        plugin_fragment = ''
+    elif deprecator.resolved_name == 'ansible.builtin':
+        # core deprecations from base classes (the API) have no plugin name, only 'ansible.builtin'
+        plugin_type_name = str(deprecator.type) if deprecator.type is _messages.PluginType.MODULE else f'{deprecator.type} plugin'
+
+        collection = deprecator.resolved_name
+        plugin_fragment = f'the {plugin_type_name} API'
+    else:
+        parts = deprecator.resolved_name.split('.')
+        plugin_name = parts[-1]
+        plugin_type_name = str(deprecator.type) if deprecator.type is _messages.PluginType.MODULE else f'{deprecator.type} plugin'
+
+        collection = '.'.join(parts[:2]) if len(parts) > 2 else None
+        plugin_fragment = f'{plugin_type_name} {plugin_name!r}'
+
+    if collection and plugin_fragment:
+        plugin_fragment += ' in'
+
+    if collection == 'ansible.builtin':
+        collection_fragment = 'ansible-core'
+    elif collection:
+        collection_fragment = f'collection {collection!r}'
+    else:
+        collection_fragment = ''
+
+    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:
+        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 join_sentences(msg, deprecation_msg)
+
+
+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))

ansible/_internal/_json/__init__.py

@@ -24,7 +24,6 @@ from ansible._internal._templating import _transform
 from ansible.module_utils import _internal
 from ansible.module_utils._internal import _datatag
 
-_T = t.TypeVar('_T')
 _sentinel = object()
 
 
@@ -115,7 +114,7 @@ class AnsibleVariableVisitor:
         if func := getattr(super(), '__exit__', None):
             func(*args, **kwargs)
 
-    def visit(self, value: _T) -> _T:
+    def visit[T](self, value: T) -> T:
         """
         Enforces Ansible's variable type system restrictions before a var is accepted in inventory. Also, conditionally implements template trust
         compatibility, depending on the plugin's declared understanding (or lack thereof). This always recursively copies inputs to fully isolate
@@ -143,7 +142,7 @@ class AnsibleVariableVisitor:
 
         return self._visit(None, key)  # key=None prevents state tracking from seeing the key as value
 
-    def _visit(self, key: t.Any, value: _T) -> _T:
+    def _visit[T](self, key: t.Any, value: T) -> T:
         """Internal implementation to recursively visit a data structure's contents."""
         self._current = key  # supports StateTrackingMixIn
 
@@ -168,7 +167,7 @@ class AnsibleVariableVisitor:
             value = value._native_copy()
             value_type = type(value)
 
-        result: _T
+        result: T
 
         # DTFIX-FUTURE: Visitor generally ignores dict/mapping keys by default except for debugging and schema-aware checking.
         #               It could be checking keys destined for variable storage to apply more strict rules about key shape and type.

ansible/_internal/_templating/_engine.py

@@ -193,7 +193,7 @@ class TemplateEngine:
         return self._variables
 
     @available_variables.setter
-    def available_variables(self, variables: dict[str, t.Any]) -> None:
+    def available_variables(self, variables: dict[str, t.Any] | ChainMap[str, t.Any]) -> None:
         self._variables = variables
 
     def resolve_variable_expression(

ansible/_internal/_templating/_jinja_plugins.py

@@ -29,7 +29,6 @@ from ._utils import LazyOptions, TemplateContext
 
 _display = Display()
 
-_TCallable = t.TypeVar("_TCallable", bound=t.Callable)
 _ITERATOR_TYPES: t.Final = (c.Iterator, c.ItemsView, c.KeysView, c.ValuesView, range)
 
 
@@ -174,7 +173,7 @@ class _DirectCall:
     _marker_attr: t.Final[str] = "_directcall"
 
     @classmethod
-    def mark(cls, src: _TCallable) -> _TCallable:
+    def mark[T: t.Callable](cls, src: T) -> T:
         setattr(src, cls._marker_attr, True)
         return src