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

ansible/_internal/_event_formatting.py

@@ -0,0 +1,127 @@
+from __future__ import annotations as _annotations
+
+import collections.abc as _c
+import textwrap as _textwrap
+
+from ansible.module_utils._internal import _event_utils, _messages
+
+
+def format_event(event: _messages.Event, include_traceback: bool) -> str:
+    """Format an event into a verbose message and traceback."""
+    msg = format_event_verbose_message(event)
+
+    if include_traceback:
+        msg += '\n' + format_event_traceback(event)
+
+    msg = msg.strip()
+
+    if '\n' in msg:
+        msg += '\n\n'
+    else:
+        msg += '\n'
+
+    return msg
+
+
+def format_event_traceback(event: _messages.Event) -> str:
+    """Format an event into a traceback."""
+    segments: list[str] = []
+
+    while event:
+        segment = event.formatted_traceback or '(traceback missing)\n'
+
+        if event.events:
+            child_tracebacks = [format_event_traceback(child) for child in event.events]
+            segment += _format_event_children("Sub-Traceback", child_tracebacks)
+
+        segments.append(segment)
+
+        if event.chain:
+            segments.append(f'\n{event.chain.traceback_reason}\n\n')
+
+            event = event.chain.event
+        else:
+            event = None
+
+    return ''.join(reversed(segments))
+
+
+def format_event_verbose_message(event: _messages.Event) -> str:
+    """
+    Format an event into a verbose message.
+    Help text, contextual information and sub-events will be included.
+    """
+    segments: list[str] = []
+    original_event = event
+
+    while event:
+        messages = [event.msg]
+        chain: _messages.EventChain = event.chain
+
+        while chain and chain.follow:
+            if chain.event.events:
+                break  # do not collapse a chained event with sub-events, since they would be lost
+
+            if chain.event.formatted_source_context or chain.event.help_text:
+                if chain.event.formatted_source_context != event.formatted_source_context or chain.event.help_text != event.help_text:
+                    break  # do not collapse a chained event with different details, since they would be lost
+
+            if chain.event.chain and chain.msg_reason != chain.event.chain.msg_reason:
+                break  # do not collapse a chained event which has a chain with a different msg_reason
+
+            messages.append(chain.event.msg)
+
+            chain = chain.event.chain
+
+        msg = _event_utils.deduplicate_message_parts(messages)
+        segment = '\n'.join(_get_message_lines(msg, event.help_text, event.formatted_source_context)) + '\n'
+
+        if event.events:
+            child_msgs = [format_event_verbose_message(child) for child in event.events]
+            segment += _format_event_children("Sub-Event", child_msgs)
+
+        segments.append(segment)
+
+        if chain and chain.follow:
+            segments.append(f'\n{chain.msg_reason}\n\n')
+
+            event = chain.event
+        else:
+            event = None
+
+    if len(segments) > 1:
+        segments.insert(0, _event_utils.format_event_brief_message(original_event) + '\n\n')
+
+    return ''.join(segments)
+
+
+def _format_event_children(label: str, children: _c.Iterable[str]) -> str:
+    """Format the given list of child messages into a single string."""
+    items = list(children)
+    count = len(items)
+    lines = ['\n']
+
+    for idx, item in enumerate(items):
+        lines.append(f'+--[ {label} {idx + 1} of {count} ]---\n')
+        lines.append(_textwrap.indent(f"\n{item}\n", "| ", lambda value: True))
+
+    lines.append(f'+--[ End {label} ]---\n')
+
+    return ''.join(lines)
+
+
+def _get_message_lines(message: str, help_text: str | None, formatted_source_context: str | None) -> list[str]:
+    """Return a list of message lines constructed from the given message, help text and formatted source context."""
+    if help_text and not formatted_source_context and '\n' not in message and '\n' not in help_text:
+        return [f'{message} {help_text}']  # prefer a single-line message with help text when there is no source context
+
+    message_lines = [message]
+
+    if formatted_source_context:
+        message_lines.append(formatted_source_context)
+
+    if help_text:
+        message_lines.append('')
+        message_lines.append(help_text)
+
+    return message_lines

ansible/_internal/_json/__init__.py

@@ -0,0 +1,214 @@
+"""Internal utilities for serialization and deserialization."""
+
+# DTFIX-FUTURE: most of this isn't JSON specific, find a better home
+
+from __future__ import annotations
+
+import enum
+import json
+import typing as t
+
+from ansible.errors import AnsibleVariableTypeError
+
+from ansible.module_utils._internal._datatag import (
+    _ANSIBLE_ALLOWED_MAPPING_VAR_TYPES,
+    _ANSIBLE_ALLOWED_NON_SCALAR_COLLECTION_VAR_TYPES,
+    _ANSIBLE_ALLOWED_VAR_TYPES,
+    _AnsibleTaggedStr,
+    AnsibleTagHelper,
+)
+from ansible.module_utils._internal._json._profiles import _tagless
+from ansible.parsing.vault import EncryptedString
+from ansible._internal._datatag._tags import Origin, TrustedAsTemplate
+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()
+
+
+class HasCurrent(t.Protocol):
+    """Utility protocol for mixin type safety."""
+
+    _current: t.Any
+
+
+class StateTrackingMixIn(HasCurrent):
+    """Mixin for use with `AnsibleVariableVisitor` to track current visitation context."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+        self._stack: list[t.Any] = []
+
+    def __enter__(self) -> None:
+        self._stack.append(self._current)
+
+    def __exit__(self, *_args, **_kwargs) -> None:
+        self._stack.pop()
+
+    def _get_stack(self) -> list[t.Any]:
+        if not self._stack:
+            return []
+
+        return self._stack[1:] + [self._current]
+
+
+class EncryptedStringBehavior(enum.Enum):
+    """How `AnsibleVariableVisitor` will handle instances of `EncryptedString`."""
+
+    PRESERVE = enum.auto()
+    """Preserves the unmodified `EncryptedString` instance."""
+    DECRYPT = enum.auto()
+    """Replaces the value with its decrypted plaintext."""
+    REDACT = enum.auto()
+    """Replaces the value with a placeholder string."""
+    FAIL = enum.auto()
+    """Raises an `AnsibleVariableTypeError` error."""
+
+
+class AnsibleVariableVisitor:
+    """Utility visitor base class to recursively apply various behaviors and checks to variable object graphs."""
+
+    def __init__(
+        self,
+        *,
+        trusted_as_template: bool = False,
+        origin: Origin | None = None,
+        convert_mapping_to_dict: bool = False,
+        convert_sequence_to_list: bool = False,
+        convert_custom_scalars: bool = False,
+        convert_to_native_values: bool = False,
+        apply_transforms: bool = False,
+        visit_keys: bool = False,
+        encrypted_string_behavior: EncryptedStringBehavior = EncryptedStringBehavior.DECRYPT,
+    ):
+        super().__init__()  # supports StateTrackingMixIn
+
+        self.trusted_as_template = trusted_as_template
+        self.origin = origin
+        self.convert_mapping_to_dict = convert_mapping_to_dict
+        self.convert_sequence_to_list = convert_sequence_to_list
+        self.convert_custom_scalars = convert_custom_scalars
+        self.convert_to_native_values = convert_to_native_values
+        self.apply_transforms = apply_transforms
+        self.visit_keys = visit_keys
+        self.encrypted_string_behavior = encrypted_string_behavior
+
+        if apply_transforms:
+            from ansible._internal._templating import _engine
+
+            self._template_engine = _engine.TemplateEngine()
+        else:
+            self._template_engine = None
+
+        self._current: t.Any = None  # supports StateTrackingMixIn
+
+    def __enter__(self) -> t.Any:
+        """No-op context manager dispatcher (delegates to mixin behavior if present)."""
+        if func := getattr(super(), '__enter__', None):
+            func()
+
+    def __exit__(self, *args, **kwargs) -> t.Any:
+        """No-op context manager dispatcher (delegates to mixin behavior if present)."""
+        if func := getattr(super(), '__exit__', None):
+            func(*args, **kwargs)
+
+    def visit(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
+        inventory data from what the plugin provided, and prevent any later mutation.
+        """
+        return self._visit(None, value)
+
+    def _early_visit(self, value, value_type) -> t.Any:
+        """Overridable hook point to allow custom string handling in derived visitors."""
+        if value_type in (str, _AnsibleTaggedStr):
+            # apply compatibility behavior
+            if self.trusted_as_template:
+                result = TrustedAsTemplate().tag(value)
+            else:
+                result = value
+        else:
+            result = _sentinel
+
+        return result
+
+    def _visit_key(self, key: t.Any) -> t.Any:
+        """Internal implementation to recursively visit a key if visit_keys is enabled."""
+        if not self.visit_keys:
+            return key
+
+        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:
+        """Internal implementation to recursively visit a data structure's contents."""
+        self._current = key  # supports StateTrackingMixIn
+
+        value_type: type = type(value)
+
+        # handle EncryptedString conversion before more generic transformation and native conversions
+        if value_type is EncryptedString:  # pylint: disable=unidiomatic-typecheck
+            match self.encrypted_string_behavior:
+                case EncryptedStringBehavior.DECRYPT:
+                    value = str(value)  # type: ignore[assignment]
+                    value_type = str
+                case EncryptedStringBehavior.REDACT:
+                    value = "<redacted>"  # type: ignore[assignment]
+                    value_type = str
+                case EncryptedStringBehavior.FAIL:
+                    raise AnsibleVariableTypeError.from_value(obj=value)
+        elif self.apply_transforms and value_type in _transform._type_transform_mapping:
+            value = self._template_engine.transform(value)
+            value_type = type(value)
+
+        if self.convert_to_native_values and isinstance(value, _datatag.AnsibleTaggedObject):
+            value = value._native_copy()
+            value_type = type(value)
+
+        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.
+
+        if (result := self._early_visit(value, value_type)) is not _sentinel:
+            pass
+        # DTFIX7: de-duplicate and optimize; extract inline generator expressions and fallback function or mapping for native type calculation?
+        elif value_type in _ANSIBLE_ALLOWED_MAPPING_VAR_TYPES:  # check mappings first, because they're also collections
+            with self:  # supports StateTrackingMixIn
+                result = AnsibleTagHelper.tag_copy(value, ((self._visit_key(k), self._visit(k, v)) for k, v in value.items()), value_type=value_type)
+        elif value_type in _ANSIBLE_ALLOWED_NON_SCALAR_COLLECTION_VAR_TYPES:
+            with self:  # supports StateTrackingMixIn
+                result = AnsibleTagHelper.tag_copy(value, (self._visit(k, v) for k, v in enumerate(t.cast(t.Iterable, value))), value_type=value_type)
+        elif self.convert_mapping_to_dict and _internal.is_intermediate_mapping(value):
+            with self:  # supports StateTrackingMixIn
+                result = {self._visit_key(k): self._visit(k, v) for k, v in value.items()}  # type: ignore[assignment]
+        elif self.convert_sequence_to_list and _internal.is_intermediate_iterable(value):
+            with self:  # supports StateTrackingMixIn
+                result = [self._visit(k, v) for k, v in enumerate(t.cast(t.Iterable, value))]  # type: ignore[assignment]
+        elif self.convert_custom_scalars and isinstance(value, str):
+            result = str(value)  # type: ignore[assignment]
+        elif self.convert_custom_scalars and isinstance(value, float):
+            result = float(value)  # type: ignore[assignment]
+        elif self.convert_custom_scalars and isinstance(value, int) and not isinstance(value, bool):
+            result = int(value)  # type: ignore[assignment]
+        elif value_type in _ANSIBLE_ALLOWED_VAR_TYPES:
+            # supported scalar type that requires no special handling, just return as-is
+            result = value
+        elif self.encrypted_string_behavior is EncryptedStringBehavior.PRESERVE and isinstance(value, EncryptedString):
+            result = value  # type: ignore[assignment]
+        else:
+            raise AnsibleVariableTypeError.from_value(obj=value)
+
+        if self.origin and not Origin.is_tagged_on(result):
+            # apply shared instance default origin tag
+            result = self.origin.tag(result)
+
+        return result
+
+
+def json_dumps_formatted(value: object) -> str:
+    """Return a JSON dump of `value` with formatting and keys sorted."""
+    return json.dumps(value, cls=_tagless.Encoder, sort_keys=True, indent=4)

ansible/_internal/_json/_legacy_encoder.py

@@ -0,0 +1,34 @@
+from __future__ import annotations as _annotations
+
+import typing as _t
+
+from ansible.module_utils._internal._json import _profiles
+from ansible._internal._json._profiles import _legacy
+from ansible.parsing import vault as _vault
+
+
+class LegacyControllerJSONEncoder(_legacy.Encoder):
+    """Compatibility wrapper over `legacy` profile JSON encoder to support trust stripping and vault value plaintext conversion."""
+
+    def __init__(self, preprocess_unsafe: bool = False, vault_to_text: bool = False, _decode_bytes: bool = False, **kwargs) -> None:
+        self._preprocess_unsafe = preprocess_unsafe
+        self._vault_to_text = vault_to_text
+        self._decode_bytes = _decode_bytes
+
+        super().__init__(**kwargs)
+
+    def default(self, o: _t.Any) -> _t.Any:
+        """Hooked default that can conditionally bypass base encoder behavior based on this instance's config."""
+        if type(o) is _profiles._WrappedValue:  # pylint: disable=unidiomatic-typecheck
+            o = o.wrapped
+
+        if not self._preprocess_unsafe and type(o) is _legacy._Untrusted:  # pylint: disable=unidiomatic-typecheck
+            return o.value  # if not emitting unsafe markers, bypass custom unsafe serialization and just return the raw value
+
+        if self._vault_to_text and type(o) is _vault.EncryptedString:  # pylint: disable=unidiomatic-typecheck
+            return str(o)  # decrypt and return the plaintext (or fail trying)
+
+        if self._decode_bytes and isinstance(o, bytes):
+            return o.decode(errors='surrogateescape')  # backward compatibility with `ansible.module_utils.basic.jsonify`
+
+        return super().default(o)

ansible/_internal/_json/_profiles/_cache_persistence.py

@@ -0,0 +1,57 @@
+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,
+        }
+
+        cls.handle_key = cls._handle_key_str_fallback  # legacy stdlib-compatible key behavior
+
+
+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."""
+
+    # DTFIX5: 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,189 @@
+"""
+Backwards compatibility profile for serialization other than inventory (which should use inventory_legacy for backward-compatible trust behavior).
+Behavior is equivalent to pre 2.19 `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,
+        }
+
+        cls.handle_key = cls._handle_key_str_fallback  # type: ignore[method-assign]  # legacy stdlib-compatible key behavior
+
+    @classmethod
+    def pre_serialize(cls, encoder: Encoder, o: _t.Any) -> _t.Any:
+        # DTFIX7: 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)
+
+
+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)