ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__py3-none-any.whl

ansible/_internal/_templating/_access.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import abc
+import typing as t
+
+from contextvars import ContextVar
+
+from ansible.module_utils._internal._datatag import AnsibleTagHelper
+
+
+class NotifiableAccessContextBase(metaclass=abc.ABCMeta):
+    """Base class for a context manager that, when active, receives notification of managed access for types/tags in which it has registered an interest."""
+
+    _type_interest: t.FrozenSet[type] = frozenset()
+    """Set of types (including tag types) for which this context will be notified upon access."""
+
+    _mask: t.ClassVar[bool] = False
+    """When true, only the innermost (most recently created) context of this type will be notified."""
+
+    def __enter__(self):
+        # noinspection PyProtectedMember
+        AnsibleAccessContext.current()._register_interest(self)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        # noinspection PyProtectedMember
+        AnsibleAccessContext.current()._unregister_interest(self)
+        return None
+
+    @abc.abstractmethod
+    def _notify(self, o: t.Any) -> t.Any:
+        """Derived classes implement custom notification behavior when a registered type or tag is accessed."""
+
+
+class AnsibleAccessContext:
+    """
+    Broker object for managed access registration and notification.
+    Each thread or other logical callstack has a dedicated `AnsibleAccessContext` object with which `NotifiableAccessContext` objects can register interest.
+    When a managed access occurs on an object, each active `NotifiableAccessContext` within the current callstack that has registered interest in that
+    object's type or a tag present on it will be notified.
+    """
+
+    _contextvar: t.ClassVar[ContextVar[AnsibleAccessContext]] = ContextVar('AnsibleAccessContext')
+
+    @staticmethod
+    def current() -> AnsibleAccessContext:
+        """Creates or retrieves an `AnsibleAccessContext` for the current logical callstack."""
+        try:
+            ctx: AnsibleAccessContext = AnsibleAccessContext._contextvar.get()
+        except LookupError:
+            # didn't exist; create it
+            ctx = AnsibleAccessContext()
+            AnsibleAccessContext._contextvar.set(ctx)  # we ignore the token, since this should live for the life of the thread/async ctx
+
+        return ctx
+
+    def __init__(self) -> None:
+        self._notify_contexts: list[NotifiableAccessContextBase] = []
+
+    def _register_interest(self, context: NotifiableAccessContextBase) -> None:
+        self._notify_contexts.append(context)
+
+    def _unregister_interest(self, context: NotifiableAccessContextBase) -> None:
+        ctx = self._notify_contexts.pop()
+
+        if ctx is not context:
+            raise RuntimeError(f'Out-of-order context deactivation detected. Found {ctx} instead of {context}.')
+
+    def access(self, value: t.Any) -> None:
+        """Notify all contexts which have registered interest in the given value that it is being accessed."""
+        if not self._notify_contexts:
+            return
+
+        value_types = AnsibleTagHelper.tag_types(value) | frozenset((type(value),))
+        masked: set[type] = set()
+
+        for ctx in reversed(self._notify_contexts):
+            if ctx._mask:
+                if (ctx_type := type(ctx)) in masked:
+                    continue
+
+                masked.add(ctx_type)
+
+            # noinspection PyProtectedMember
+            if ctx._type_interest.intersection(value_types):
+                ctx._notify(value)

ansible/_internal/_templating/_chain_templar.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import collections.abc as c
+import itertools
+import typing as t
+
+from ansible.errors import AnsibleValueOmittedError, AnsibleError
+
+from ._engine import TemplateEngine
+
+
+class ChainTemplar:
+    """A basic variable layering mechanism that supports templating and obliteration of `omit` values."""
+
+    def __init__(self, *sources: c.Mapping, templar: TemplateEngine) -> None:
+        self.sources = sources
+        self.templar = templar
+
+    def template(self, key: t.Any, value: t.Any) -> t.Any:
+        """
+        Render the given value using the templar.
+        Intended to be overridden by subclasses.
+        """
+        return self.templar.template(value)
+
+    def get(self, key: t.Any) -> t.Any:
+        """Get the value for the given key, templating the result before returning it."""
+        for source in self.sources:
+            if key not in source:
+                continue
+
+            value = source[key]
+
+            try:
+                return self.template(key, value)
+            except AnsibleValueOmittedError:
+                break  # omit == obliterate - matches historical behavior where dict layers were squashed before templating was applied
+            except Exception as ex:
+                raise AnsibleError(f'Error while resolving value for {key!r}.', obj=value) from ex
+
+        raise KeyError(key)
+
+    def keys(self) -> t.Iterable[t.Any]:
+        """
+        Returns a sorted iterable of all keys present in all source layers, without templating associated values.
+        Values that resolve to `omit` are thus included.
+        """
+        return sorted(set(itertools.chain.from_iterable(self.sources)))
+
+    def items(self) -> t.Iterable[t.Tuple[t.Any, t.Any]]:
+        """
+        Returns a sorted iterable of (key, templated value) tuples.
+        Any tuple where the templated value resolves to `omit` will not be included in the result.
+        """
+        for key in self.keys():
+            try:
+                yield key, self.get(key)
+            except KeyError:
+                pass
+
+    def as_dict(self) -> dict[t.Any, t.Any]:
+        """Returns a dict representing all layers, squashed and templated, with `omit` values dropped."""
+        return dict(self.items())

ansible/_internal/_templating/_datatag.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import contextlib as _contextlib
+import dataclasses
+import typing as t
+
+from ansible.module_utils._internal._datatag import AnsibleSingletonTagBase, _tag_dataclass_kwargs
+from ansible.module_utils._internal._datatag._tags import Deprecated
+from ansible._internal._datatag._tags import Origin
+from ansible.utils.display import Display
+
+from ._access import NotifiableAccessContextBase
+from ._utils import TemplateContext
+
+display = Display()
+
+
+@dataclasses.dataclass(**_tag_dataclass_kwargs)
+class _JinjaConstTemplate(AnsibleSingletonTagBase):
+    # deprecated: description='embedded Jinja constant string template support' core_version='2.23'
+    pass
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class _TrippedDeprecationInfo:
+    template: str
+    deprecated: Deprecated
+
+
+class DeprecatedAccessAuditContext(NotifiableAccessContextBase):
+    """When active, captures metadata about managed accesses to `Deprecated` tagged objects."""
+
+    _type_interest = frozenset([Deprecated])
+
+    @classmethod
+    def when(cls, condition: bool, /) -> t.Self | _contextlib.nullcontext:
+        """Returns a new instance if `condition` is True (usually `TemplateContext.is_top_level`), otherwise a `nullcontext` instance."""
+        if condition:
+            return cls()
+
+        return _contextlib.nullcontext()
+
+    def __init__(self) -> None:
+        self._tripped_deprecation_info: dict[int, _TrippedDeprecationInfo] = {}
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        result = super().__exit__(exc_type, exc_val, exc_tb)
+
+        for item in self._tripped_deprecation_info.values():
+            if Origin.is_tagged_on(item.template):
+                msg = item.deprecated.msg
+            else:
+                # without an origin, we need to include what context we do have (the template)
+                msg = f'While processing {item.template!r}: {item.deprecated.msg}'
+
+            display._deprecated_with_plugin_info(
+                msg=msg,
+                help_text=item.deprecated.help_text,
+                version=item.deprecated.version,
+                date=item.deprecated.date,
+                obj=item.template,
+                deprecator=item.deprecated.deprecator,
+                formatted_traceback=item.deprecated.formatted_traceback,
+            )
+
+        return result
+
+    def _notify(self, o: t.Any) -> None:
+        deprecated = Deprecated.get_required_tag(o)
+        deprecated_key = id(deprecated)
+
+        if deprecated_key in self._tripped_deprecation_info:
+            return  # record only the first access for each deprecated tag in a given context
+
+        template_ctx = TemplateContext.current(optional=True)
+        template = template_ctx.template_value if template_ctx else None
+
+        # when the current template input is a container, provide a descriptive string with origin propagated (if possible)
+        if not isinstance(template, str):
+            # DTFIX-FUTURE: ascend the template stack to try and find the nearest string source template
+            origin = Origin.get_tag(template)
+
+            # DTFIX-FUTURE: this should probably use a synthesized description value on the tag
+            #              it is reachable from the data_tagging_controller test: ../playbook_output_validator/filter.py actual_stdout.txt actual_stderr.txt
+            # -[DEPRECATION WARNING]: `something_old` is deprecated, don't use it! This feature will be removed in version 1.2.3.
+            # +[DEPRECATION WARNING]: While processing '<<container>>': `something_old` is deprecated, don't use it! This feature will be removed in ...
+            template = '<<container>>'
+
+            if origin:
+                origin.tag(template)
+
+        self._tripped_deprecation_info[deprecated_key] = _TrippedDeprecationInfo(
+            template=template,
+            deprecated=deprecated,
+        )