ansible-core 2.18.5rc1__py3-none-any.whl → 2.19.0b2__py3-none-any.whl

ansible/_internal/_json/_profiles/_cache_persistence.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import datetime as _datetime
+
+from ansible.module_utils._internal import _datatag
+from ansible.module_utils._internal._json import _profiles
+from ansible.parsing import vault as _vault
+from ansible._internal._datatag import _tags
+
+
+class _Profile(_profiles._JSONSerializationProfile):
+    """Profile for external cache persistence of inventory/fact data that preserves most tags."""
+
+    serialize_map = {}
+    schema_id = 1
+
+    @classmethod
+    def post_init(cls, **kwargs):
+        cls.allowed_ansible_serializable_types = (
+            _profiles._common_module_types
+            | _profiles._common_module_response_types
+            | {
+                _datatag._AnsibleTaggedDate,
+                _datatag._AnsibleTaggedTime,
+                _datatag._AnsibleTaggedDateTime,
+                _datatag._AnsibleTaggedStr,
+                _datatag._AnsibleTaggedInt,
+                _datatag._AnsibleTaggedFloat,
+                _datatag._AnsibleTaggedList,
+                _datatag._AnsibleTaggedSet,
+                _datatag._AnsibleTaggedTuple,
+                _datatag._AnsibleTaggedDict,
+                _tags.SourceWasEncrypted,
+                _tags.Origin,
+                _tags.TrustedAsTemplate,
+                _vault.EncryptedString,
+                _vault.VaultedValue,
+            }
+        )
+
+        cls.serialize_map = {
+            set: cls.serialize_as_list,
+            tuple: cls.serialize_as_list,
+            _datetime.date: _datatag.AnsibleSerializableDate,
+            _datetime.time: _datatag.AnsibleSerializableTime,
+            _datetime.datetime: _datatag.AnsibleSerializableDateTime,
+        }
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile

ansible/_internal/_json/_profiles/_inventory_legacy.py

@@ -0,0 +1,40 @@
+"""
+Backwards compatibility profile for serialization for persisted ansible-inventory output.
+Behavior is equivalent to pre 2.18 `AnsibleJSONEncoder` with vault_to_text=True.
+"""
+
+from __future__ import annotations
+
+from ... import _json
+from . import _legacy
+
+
+class _InventoryVariableVisitor(_legacy._LegacyVariableVisitor, _json.StateTrackingMixIn):
+    """State-tracking visitor implementation that only applies trust to `_meta.hostvars` and `vars` inventory values."""
+
+    # DTFIX-RELEASE: does the variable visitor need to support conversion of sequence/mapping for inventory?
+
+    @property
+    def _allow_trust(self) -> bool:
+        stack = self._get_stack()
+
+        if len(stack) >= 4 and stack[:2] == ['_meta', 'hostvars']:
+            return True
+
+        if len(stack) >= 3 and stack[1] == 'vars':
+            return True
+
+        return False
+
+
+class _Profile(_legacy._Profile):
+    visitor_type = _InventoryVariableVisitor
+    encode_strings_as_utf8 = True
+
+
+class Encoder(_legacy.Encoder):
+    _profile = _Profile
+
+
+class Decoder(_legacy.Decoder):
+    _profile = _Profile

ansible/_internal/_json/_profiles/_legacy.py

@@ -0,0 +1,197 @@
+"""
+Backwards compatibility profile for serialization other than inventory (which should use inventory_legacy for backward-compatible trust behavior).
+Behavior is equivalent to pre 2.18 `AnsibleJSONEncoder` with vault_to_text=True.
+"""
+
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+import typing as _t
+
+from ansible._internal import _json
+from ansible._internal._datatag import _tags
+from ansible.module_utils._internal import _datatag
+from ansible.module_utils._internal._json import _profiles
+from ansible.parsing import vault as _vault
+
+
+class _Untrusted:
+    """
+    Temporarily wraps strings which are not trusted for templating.
+    Used before serialization of strings not tagged TrustedAsTemplate when trust inversion is enabled and trust is allowed in the string's context.
+    Used during deserialization of `__ansible_unsafe` strings to indicate they should not be tagged TrustedAsTemplate.
+    """
+
+    __slots__ = ('value',)
+
+    def __init__(self, value: str) -> None:
+        self.value = value
+
+
+class _LegacyVariableVisitor(_json.AnsibleVariableVisitor):
+    """Variable visitor that supports optional trust inversion for legacy serialization."""
+
+    def __init__(
+        self,
+        *,
+        trusted_as_template: bool = False,
+        invert_trust: bool = False,
+        origin: _tags.Origin | None = None,
+        convert_mapping_to_dict: bool = False,
+        convert_sequence_to_list: bool = False,
+        convert_custom_scalars: bool = False,
+    ):
+        super().__init__(
+            trusted_as_template=trusted_as_template,
+            origin=origin,
+            convert_mapping_to_dict=convert_mapping_to_dict,
+            convert_sequence_to_list=convert_sequence_to_list,
+            convert_custom_scalars=convert_custom_scalars,
+            encrypted_string_behavior=_json.EncryptedStringBehavior.PRESERVE,
+        )
+
+        self.invert_trust = invert_trust
+
+        if trusted_as_template and invert_trust:
+            raise ValueError('trusted_as_template is mutually exclusive with invert_trust')
+
+    @property
+    def _allow_trust(self) -> bool:
+        """
+        This profile supports trust application in all contexts.
+        Derived implementations can override this behavior for application-dependent/schema-aware trust.
+        """
+        return True
+
+    def _early_visit(self, value, value_type) -> _t.Any:
+        """Similar to base implementation, but supports an intermediate wrapper for trust inversion."""
+        if value_type in (str, _datatag._AnsibleTaggedStr):
+            # apply compatibility behavior
+            if self.trusted_as_template and self._allow_trust:
+                result = _tags.TrustedAsTemplate().tag(value)
+            elif self.invert_trust and not _tags.TrustedAsTemplate.is_tagged_on(value) and self._allow_trust:
+                result = _Untrusted(value)
+            else:
+                result = value
+        elif value_type is _Untrusted:
+            result = value.value
+        else:
+            result = _json._sentinel
+
+        return result
+
+
+class _Profile(_profiles._JSONSerializationProfile["Encoder", "Decoder"]):
+    visitor_type = _LegacyVariableVisitor
+
+    @classmethod
+    def serialize_untrusted(cls, value: _Untrusted) -> dict[str, str] | str:
+        return dict(
+            __ansible_unsafe=_datatag.AnsibleTagHelper.untag(value.value),
+        )
+
+    @classmethod
+    def serialize_tagged_str(cls, value: _datatag.AnsibleTaggedObject) -> _t.Any:
+        if ciphertext := _vault.VaultHelper.get_ciphertext(value, with_tags=False):
+            return dict(
+                __ansible_vault=ciphertext,
+            )
+
+        return _datatag.AnsibleTagHelper.untag(value)
+
+    @classmethod
+    def deserialize_unsafe(cls, value: dict[str, _t.Any]) -> _Untrusted:
+        ansible_unsafe = value['__ansible_unsafe']
+
+        if type(ansible_unsafe) is not str:  # pylint: disable=unidiomatic-typecheck
+            raise TypeError(f"__ansible_unsafe is {type(ansible_unsafe)} not {str}")
+
+        return _Untrusted(ansible_unsafe)
+
+    @classmethod
+    def deserialize_vault(cls, value: dict[str, _t.Any]) -> _vault.EncryptedString:
+        ansible_vault = value['__ansible_vault']
+
+        if type(ansible_vault) is not str:  # pylint: disable=unidiomatic-typecheck
+            raise TypeError(f"__ansible_vault is {type(ansible_vault)} not {str}")
+
+        encrypted_string = _vault.EncryptedString(ciphertext=ansible_vault)
+
+        return encrypted_string
+
+    @classmethod
+    def serialize_encrypted_string(cls, value: _vault.EncryptedString) -> dict[str, str]:
+        return dict(
+            __ansible_vault=_vault.VaultHelper.get_ciphertext(value, with_tags=False),
+        )
+
+    @classmethod
+    def post_init(cls) -> None:
+        cls.serialize_map = {
+            set: cls.serialize_as_list,
+            tuple: cls.serialize_as_list,
+            _datetime.date: cls.serialize_as_isoformat,  # existing devel behavior
+            _datetime.time: cls.serialize_as_isoformat,  # always failed pre-2.18, so okay to include for consistency
+            _datetime.datetime: cls.serialize_as_isoformat,  # existing devel behavior
+            _datatag._AnsibleTaggedDate: cls.discard_tags,
+            _datatag._AnsibleTaggedTime: cls.discard_tags,
+            _datatag._AnsibleTaggedDateTime: cls.discard_tags,
+            _vault.EncryptedString: cls.serialize_encrypted_string,
+            _datatag._AnsibleTaggedStr: cls.serialize_tagged_str,  # for VaultedValue tagged str
+            _datatag._AnsibleTaggedInt: cls.discard_tags,
+            _datatag._AnsibleTaggedFloat: cls.discard_tags,
+            _datatag._AnsibleTaggedList: cls.discard_tags,
+            _datatag._AnsibleTaggedSet: cls.discard_tags,
+            _datatag._AnsibleTaggedTuple: cls.discard_tags,
+            _datatag._AnsibleTaggedDict: cls.discard_tags,
+            _Untrusted: cls.serialize_untrusted,  # equivalent to AnsibleJSONEncoder(preprocess_unsafe=True) in devel
+        }
+
+        cls.deserialize_map = {
+            '__ansible_unsafe': cls.deserialize_unsafe,
+            '__ansible_vault': cls.deserialize_vault,
+        }
+
+    @classmethod
+    def pre_serialize(cls, encoder: Encoder, o: _t.Any) -> _t.Any:
+        # DTFIX-RELEASE: these conversion args probably aren't needed
+        avv = cls.visitor_type(invert_trust=True, convert_mapping_to_dict=True, convert_sequence_to_list=True, convert_custom_scalars=True)
+
+        return avv.visit(o)
+
+    @classmethod
+    def post_deserialize(cls, decoder: Decoder, o: _t.Any) -> _t.Any:
+        avv = cls.visitor_type(trusted_as_template=decoder._trusted_as_template, origin=decoder._origin)
+
+        return avv.visit(o)
+
+    @classmethod
+    def handle_key(cls, k: _t.Any) -> _t.Any:
+        if isinstance(k, str):
+            return k
+
+        # DTFIX-RELEASE: decide if this is a deprecation warning, error, or what?
+        #  Non-string variable names have been disallowed by set_fact and other things since at least 2021.
+        # DTFIX-RELEASE: document why this behavior is here, also verify the legacy tagless use case doesn't need this same behavior
+        return str(k)
+
+
+class Encoder(_profiles.AnsibleProfileJSONEncoder):
+    _profile = _Profile
+
+
+class Decoder(_profiles.AnsibleProfileJSONDecoder):
+    _profile = _Profile
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+
+        # NB: these can only be sampled properly when loading strings, eg, `json.loads`; the global `json.load` function does not expose the file-like to us
+        self._origin: _tags.Origin | None = None
+        self._trusted_as_template: bool = False
+
+    def raw_decode(self, s: str, idx: int = 0) -> tuple[_t.Any, int]:
+        self._origin = _tags.Origin.get_tag(s)
+        self._trusted_as_template = _tags.TrustedAsTemplate.is_tagged_on(s)
+
+        return super().raw_decode(s, idx)

ansible/_internal/_locking.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import typing as t
+
+
+@contextlib.contextmanager
+def named_mutex(path: str) -> t.Iterator[None]:
+    """
+    Lightweight context manager wrapper over `fcntl.flock` to provide IPC locking via a shared filename.
+    Entering the context manager blocks until the lock is acquired.
+    The lock file will be created automatically, but creation of the parent directory and deletion of the lockfile are the caller's responsibility.
+    """
+    with open(path, 'a') as file:
+        fcntl.flock(file, fcntl.LOCK_EX)
+
+        try:
+            yield
+        finally:
+            fcntl.flock(file, fcntl.LOCK_UN)

ansible/_internal/_plugins/_cache.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import functools
+import json
+import json.encoder
+import json.decoder
+import typing as t
+
+from .._wrapt import ObjectProxy
+from .._json._profiles import _cache_persistence
+
+
+class PluginInterposer(ObjectProxy):
+    """Proxies a Cache plugin instance to implement transparent encapsulation of serialized Ansible internal data types."""
+
+    _PAYLOAD_KEY = '__payload__'
+    """The key used to store the serialized payload."""
+
+    def get(self, key: str) -> dict[str, object]:
+        return self._decode(self.__wrapped__.get(self._get_key(key)))
+
+    def set(self, key: str, value: dict[str, object]) -> None:
+        self.__wrapped__.set(self._get_key(key), self._encode(value))
+
+    def keys(self) -> t.Sequence[str]:
+        return [k for k in (self._restore_key(k) for k in self.__wrapped__.keys()) if k is not None]
+
+    def contains(self, key: t.Any) -> bool:
+        return self.__wrapped__.contains(self._get_key(key))
+
+    def delete(self, key: str) -> None:
+        self.__wrapped__.delete(self._get_key(key))
+
+    @classmethod
+    def _restore_key(cls, wrapped_key: str) -> str | None:
+        prefix = cls._get_wrapped_key_prefix()
+
+        if not wrapped_key.startswith(prefix):
+            return None
+
+        return wrapped_key[len(prefix) :]
+
+    @classmethod
+    @functools.cache
+    def _get_wrapped_key_prefix(cls) -> str:
+        return f's{_cache_persistence._Profile.schema_id}_'
+
+    @classmethod
+    def _get_key(cls, key: str) -> str:
+        """Augment the supplied key with a schema identifier to allow for side-by-side caching across incompatible schemas."""
+        return f'{cls._get_wrapped_key_prefix()}{key}'
+
+    def _encode(self, value: dict[str, object]) -> dict[str, object]:
+        return {self._PAYLOAD_KEY: json.dumps(value, cls=_cache_persistence.Encoder)}
+
+    def _decode(self, value: dict[str, t.Any]) -> dict[str, object]:
+        return json.loads(value[self._PAYLOAD_KEY], cls=_cache_persistence.Decoder)

ansible/_internal/_task.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from collections import abc as c
+
+from ansible import constants
+from ansible._internal._templating import _engine
+from ansible._internal._templating._chain_templar import ChainTemplar
+from ansible.errors import AnsibleError
+from ansible.module_utils._internal._ambient_context import AmbientContextBase
+from ansible.module_utils.datatag import native_type_name
+from ansible.parsing import vault as _vault
+from ansible.utils.display import Display
+
+if t.TYPE_CHECKING:
+    from ansible.playbook.task import Task
+
+
+@dataclasses.dataclass
+class TaskContext(AmbientContextBase):
+    """Ambient context that wraps task execution on workers. It provides access to the currently executing task."""
+
+    task: Task
+
+
+TaskArgsFinalizerCallback = t.Callable[[str, t.Any, _engine.TemplateEngine, t.Any], t.Any]
+"""Type alias for the shape of the `ActionBase.finalize_task_arg` method."""
+
+
+class TaskArgsChainTemplar(ChainTemplar):
+    """
+    A ChainTemplar that carries a user-provided context object, optionally provided by `ActionBase.get_finalize_task_args_context`.
+    TaskArgsFinalizer provides the context to each `ActionBase.finalize_task_arg` call to allow for more complex/stateful customization.
+    """
+
+    def __init__(self, *sources: c.Mapping, templar: _engine.TemplateEngine, callback: TaskArgsFinalizerCallback, context: t.Any) -> None:
+        super().__init__(*sources, templar=templar)
+
+        self.callback = callback
+        self.context = context
+
+    def template(self, key: t.Any, value: t.Any) -> t.Any:
+        return self.callback(key, value, self.templar, self.context)
+
+
+class TaskArgsFinalizer:
+    """Invoked during task args finalization; allows actions to override default arg processing (e.g., templating)."""
+
+    def __init__(self, *args: c.Mapping[str, t.Any] | str | None, templar: _engine.TemplateEngine) -> None:
+        self._args_layers = [arg for arg in args if arg is not None]
+        self._templar = templar
+
+    def finalize(self, callback: TaskArgsFinalizerCallback, context: t.Any) -> dict[str, t.Any]:
+        resolved_layers: list[c.Mapping[str, t.Any]] = []
+
+        for layer in self._args_layers:
+            if isinstance(layer, (str, _vault.EncryptedString)):  # EncryptedString can hide a template
+                if constants.config.get_config_value('INJECT_FACTS_AS_VARS'):
+                    Display().warning(
+                        "Using a template for task args is unsafe in some situations "
+                        "(see https://docs.ansible.com/ansible/devel/reference_appendices/faq.html#argsplat-unsafe).",
+                        obj=layer,
+                    )
+
+                resolved_layer = self._templar.resolve_to_container(layer, options=_engine.TemplateOptions(value_for_omit={}))
+            else:
+                resolved_layer = layer
+
+            if not isinstance(resolved_layer, dict):
+                raise AnsibleError(f'Task args must resolve to a {native_type_name(dict)!r} not {native_type_name(resolved_layer)!r}.', obj=layer)
+
+            resolved_layers.append(resolved_layer)
+
+        ct = TaskArgsChainTemplar(*reversed(resolved_layers), templar=self._templar, callback=callback, context=context)
+
+        return ct.as_dict()

ansible/_internal/_templating/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from jinja2 import __version__ as _jinja2_version
+
+# DTFIX-FUTURE: sanity test to ensure this doesn't drift from requirements
+_MINIMUM_JINJA_VERSION = (3, 1)
+_CURRENT_JINJA_VERSION = tuple(map(int, _jinja2_version.split('.', maxsplit=2)[:2]))
+
+if _CURRENT_JINJA_VERSION < _MINIMUM_JINJA_VERSION:
+    raise RuntimeError(f'Jinja version {".".join(map(str, _MINIMUM_JINJA_VERSION))} or higher is required (current version {_jinja2_version}).')

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())