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

ansible/_internal/_templating/_marker_behaviors.py

@@ -0,0 +1,103 @@
+"""Handling of `Marker` values."""
+
+from __future__ import annotations
+
+import abc
+import contextlib
+import dataclasses
+import itertools
+import typing as t
+
+from ansible.utils.display import Display
+
+from ._jinja_common import Marker
+
+
+class MarkerBehavior(metaclass=abc.ABCMeta):
+    """Base class to support custom handling of `Marker` values encountered during concatenation or finalization."""
+
+    @abc.abstractmethod
+    def handle_marker(self, value: Marker) -> t.Any:
+        """Handle the given `Marker` value."""
+
+
+class FailingMarkerBehavior(MarkerBehavior):
+    """
+    The default behavior when encountering a `Marker` value during concatenation or finalization.
+    This always raises the template-internal `MarkerError` exception.
+    """
+
+    def handle_marker(self, value: Marker) -> t.Any:
+        value.trip()
+
+
+# FAIL_ON_MARKER_BEHAVIOR
+# _DETONATE_MARKER_BEHAVIOR - internal singleton since it's the default and nobody should need to reference it, or make it an actual singleton
+FAIL_ON_UNDEFINED: t.Final = FailingMarkerBehavior()  # no sense in making many instances...
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class _MarkerTracker:
+    """A numbered occurrence of a `Marker` value for later conversion to a warning."""
+
+    number: int
+    value: Marker
+
+
+class ReplacingMarkerBehavior(MarkerBehavior):
+    """All `Marker` values are replaced with a numbered string placeholder and the message from the value."""
+
+    def __init__(self) -> None:
+        self._trackers: list[_MarkerTracker] = []
+
+    def record_marker(self, value: Marker) -> t.Any:
+        """Assign a sequence number to the given value and record it for later generation of warnings."""
+        number = len(self._trackers) + 1
+
+        self._trackers.append(_MarkerTracker(number=number, value=value))
+
+        return number
+
+    def emit_warnings(self) -> None:
+        """Emit warning messages caused by Marker values, aggregated by unique template."""
+
+        display = Display()
+        grouped_templates = itertools.groupby(self._trackers, key=lambda tracker: tracker.value._marker_template_source)
+
+        for template, items in grouped_templates:
+            item_list = list(items)
+
+            msg = f'Encountered {len(item_list)} template error{"s" if len(item_list) > 1 else ""}.'
+
+            for item in item_list:
+                msg += f'\nerror {item.number} - {item.value._as_message()}'
+
+            display.warning(msg=msg, obj=template)
+
+    @classmethod
+    @contextlib.contextmanager
+    def warning_context(cls) -> t.Generator[t.Self, None, None]:
+        """Collect warnings for `Marker` values and emit warnings when the context exits."""
+        instance = cls()
+
+        try:
+            yield instance
+        finally:
+            instance.emit_warnings()
+
+    def handle_marker(self, value: Marker) -> t.Any:
+        number = self.record_marker(value)
+
+        return f"<< error {number} - {value._as_message()} >>"
+
+
+class RoutingMarkerBehavior(MarkerBehavior):
+    """Routes instances of Marker (by type reference) to another MarkerBehavior, defaulting to FailingMarkerBehavior."""
+
+    def __init__(self, dispatch_table: dict[type[Marker], MarkerBehavior]) -> None:
+        self._dispatch_table = dispatch_table
+
+    def handle_marker(self, value: Marker) -> t.Any:
+        behavior = self._dispatch_table.get(type(value), FAIL_ON_UNDEFINED)
+
+        return behavior.handle_marker(value)

ansible/_internal/_templating/_transform.py

@@ -0,0 +1,63 @@
+"""Runtime projections to provide template/var-visible views of objects that are not natively allowed in Ansible's type system."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from ansible.module_utils._internal import _traceback
+from ansible.module_utils.common.messages import PluginInfo, ErrorSummary, WarningSummary, DeprecationSummary
+from ansible.parsing.vault import EncryptedString, VaultHelper
+from ansible.utils.display import Display
+
+from ._jinja_common import VaultExceptionMarker
+from .._errors import _captured, _utils
+
+display = Display()
+
+
+def plugin_info(value: PluginInfo) -> dict[str, str]:
+    """Render PluginInfo as a dictionary."""
+    return dataclasses.asdict(value)
+
+
+def error_summary(value: ErrorSummary) -> str:
+    """Render ErrorSummary as a formatted traceback for backward-compatibility with pre-2.19 TaskResult.exception."""
+    return value.formatted_traceback or '(traceback unavailable)'
+
+
+def warning_summary(value: WarningSummary) -> str:
+    """Render WarningSummary as a simple message string for backward-compatibility with pre-2.19 TaskResult.warnings."""
+    return value._format()
+
+
+def deprecation_summary(value: DeprecationSummary) -> dict[str, t.Any]:
+    """Render DeprecationSummary as dict values for backward-compatibility with pre-2.19 TaskResult.deprecations."""
+    # DTFIX-RELEASE: reconsider which deprecation fields should be exposed here, taking into account that collection_name is to be deprecated
+    result = value._as_simple_dict()
+    result.pop('details')
+
+    return result
+
+
+def encrypted_string(value: EncryptedString) -> str | VaultExceptionMarker:
+    """Decrypt an encrypted string and return its value, or a VaultExceptionMarker if decryption fails."""
+    try:
+        return value._decrypt()
+    except Exception as ex:
+        return VaultExceptionMarker(
+            ciphertext=VaultHelper.get_ciphertext(value, with_tags=True),
+            reason=_utils.get_chained_message(ex),
+            traceback=_traceback.maybe_extract_traceback(ex, _traceback.TracebackEvent.ERROR),
+        )
+
+
+_type_transform_mapping: dict[type, t.Callable[[t.Any], t.Any]] = {
+    _captured.CapturedErrorSummary: error_summary,
+    PluginInfo: plugin_info,
+    ErrorSummary: error_summary,
+    WarningSummary: warning_summary,
+    DeprecationSummary: deprecation_summary,
+    EncryptedString: encrypted_string,
+}
+"""This mapping is consulted by `Templar.template` to provide custom views of some objects."""

ansible/_internal/_templating/_utils.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from ansible.module_utils._internal import _ambient_context, _datatag
+
+if t.TYPE_CHECKING:
+    from ._engine import TemplateEngine, TemplateOptions
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class LazyOptions:
+    """Templating options that apply to lazy containers, which are inherited by descendent lazy containers."""
+
+    DEFAULT: t.ClassVar[t.Self]
+    """A shared instance with the default options to minimize instance creation for arg defaults."""
+    SKIP_TEMPLATES: t.ClassVar[t.Self]
+    """A shared instance with only `template=False` set to minimize instance creation for arg defaults."""
+    SKIP_TEMPLATES_AND_ACCESS: t.ClassVar[t.Self]
+    """A shared instance with both `template=False` and `access=False` set to minimize instance creation for arg defaults."""
+
+    template: bool = True
+    """Enable/disable templating."""
+
+    access: bool = True
+    """Enable/disables access calls."""
+
+    unmask_type_names: frozenset[str] = frozenset()
+    """Disables template transformations for the provided type names."""
+
+
+LazyOptions.DEFAULT = LazyOptions()
+LazyOptions.SKIP_TEMPLATES = LazyOptions(template=False)
+LazyOptions.SKIP_TEMPLATES_AND_ACCESS = LazyOptions(template=False, access=False)
+
+
+class TemplateContext(_ambient_context.AmbientContextBase):
+    def __init__(
+        self,
+        *,
+        template_value: t.Any,
+        templar: TemplateEngine,
+        options: TemplateOptions,
+        stop_on_template: bool = False,
+        _render_jinja_const_template: bool = False,
+    ):
+        self._template_value = template_value
+        self._templar = templar
+        self._options = options
+        self._stop_on_template = stop_on_template
+        self._parent_ctx = TemplateContext.current(optional=True)
+        self._render_jinja_const_template = _render_jinja_const_template
+
+    @property
+    def is_top_level(self) -> bool:
+        return not self._parent_ctx
+
+    @property
+    def template_value(self) -> t.Any:
+        return self._template_value
+
+    @property
+    def templar(self) -> TemplateEngine:
+        return self._templar
+
+    @property
+    def options(self) -> TemplateOptions:
+        return self._options
+
+    @property
+    def stop_on_template(self) -> bool:
+        return self._stop_on_template
+
+
+class _OmitType:
+    """
+    A placeholder singleton used to dynamically omit items from a dict/list/tuple/set when the value is `Omit`.
+
+    The `Omit` singleton is accessible from all Ansible templating contexts via the Jinja global name `omit`.
+    The `Omit` placeholder value will be visible to Jinja plugins during templating.
+    Jinja plugins requiring omit behavior are responsible for handling encountered `Omit` values.
+    `Omit` values remaining in template results will be automatically dropped during template finalization.
+    When a finalized template renders to a scalar `Omit`, `AnsibleValueOmittedError` will be raised.
+    Passing a value other than `Omit` for `value_for_omit` to the `template` call allows that value to be substituted instead of raising.
+    """
+
+    __slots__ = ()
+
+    def __new__(cls):
+        return Omit
+
+    def __repr__(self):
+        return "<<Omit>>"
+
+
+Omit = object.__new__(_OmitType)
+
+_datatag._untaggable_types.add(_OmitType)
+
+
+# DTFIX-RELEASE: review these type sets to ensure they're not overly permissive/dynamic
+IGNORE_SCALAR_VAR_TYPES = {value for value in _datatag._ANSIBLE_ALLOWED_SCALAR_VAR_TYPES if not issubclass(value, str)}
+
+PASS_THROUGH_SCALAR_VAR_TYPES = _datatag._ANSIBLE_ALLOWED_SCALAR_VAR_TYPES | {
+    _OmitType,  # allow pass through of omit for later handling after top-level finalize completes
+}