ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__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/_template_vars.py

@@ -0,0 +1,72 @@
+from __future__ import annotations as _annotations
+
+import datetime as _datetime
+import os as _os
+import pwd as _pwd
+import time as _time
+
+from ansible import constants as _constants
+from ansible.module_utils._internal import _datatag
+
+
+def generate_ansible_template_vars(
+    path: str,
+    fullpath: str | None = None,
+    dest_path: str | None = None,
+    include_ansible_managed: bool = True,
+) -> dict[str, object]:
+    """
+    Generate and return a dictionary with variable metadata about the template specified by `fullpath`.
+    If `fullpath` is `None`, `path` will be used instead.
+    """
+    # deprecated description="update the ansible.windows collection to inline this logic instead of calling this internal function" core_version="2.23"
+    if fullpath is None:
+        fullpath = _os.path.abspath(path)
+
+    template_path = fullpath
+    template_stat = _os.stat(template_path)
+
+    template_uid: int | str
+
+    try:
+        template_uid = _pwd.getpwuid(template_stat.st_uid).pw_name
+    except KeyError:
+        template_uid = template_stat.st_uid
+
+    temp_vars = dict(
+        template_host=_os.uname()[1],
+        template_path=path,
+        template_mtime=_datetime.datetime.fromtimestamp(template_stat.st_mtime),
+        template_uid=template_uid,
+        template_run_date=_datetime.datetime.now(),
+        template_destpath=dest_path,
+        template_fullpath=fullpath,
+    )
+
+    if include_ansible_managed:  # only inject the config default value if the variable wasn't set
+        temp_vars['ansible_managed'] = _generate_ansible_managed(template_stat)
+
+    return temp_vars
+
+
+def _generate_ansible_managed(template_stat: _os.stat_result) -> str:
+    """Generate and return the `ansible_managed` variable."""
+    # deprecated description="remove the `_generate_ansible_managed` function and use a constant instead" core_version="2.23"
+
+    from ansible.template import trust_as_template
+
+    managed_default = _constants.config.get_config_value('DEFAULT_MANAGED_STR')
+
+    managed_str = managed_default.format(
+        # IMPORTANT: These values must be constant strings to avoid template injection.
+        #            Use Jinja template expressions where variables are needed.
+        host="{{ template_host }}",
+        uid="{{ template_uid }}",
+        file="{{ template_path }}",
+    )
+
+    ansible_managed = _time.strftime(managed_str, _time.localtime(template_stat.st_mtime))
+    ansible_managed = _datatag.AnsibleTagHelper.tag_copy(managed_default, ansible_managed)
+    ansible_managed = trust_as_template(ansible_managed)
+
+    return ansible_managed

ansible/_internal/_templating/_transform.py

@@ -0,0 +1,70 @@
+"""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, _event_utils, _messages
+from ansible.parsing.vault import EncryptedString, VaultHelper
+from ansible.utils.display import Display
+
+from ._jinja_common import VaultExceptionMarker
+from .._errors import _captured, _error_factory
+from .. import _event_formatting
+
+display = Display()
+
+
+def plugin_info(value: _messages.PluginInfo) -> dict[str, str]:
+    """Render PluginInfo as a dictionary."""
+    return dataclasses.asdict(value)
+
+
+def plugin_type(value: _messages.PluginType) -> str:
+    """Render PluginType as a string."""
+    return value.value
+
+
+def error_summary(value: _messages.ErrorSummary) -> str:
+    """Render ErrorSummary as a formatted traceback for backward-compatibility with pre-2.19 TaskResult.exception."""
+    if _traceback._is_traceback_enabled(_traceback.TracebackEvent.ERROR):
+        return _event_formatting.format_event_traceback(value.event)
+
+    return '(traceback unavailable)'
+
+
+def warning_summary(value: _messages.WarningSummary) -> str:
+    """Render WarningSummary as a simple message string for backward-compatibility with pre-2.19 TaskResult.warnings."""
+    return _event_utils.format_event_brief_message(value.event)
+
+
+def deprecation_summary(value: _messages.DeprecationSummary) -> dict[str, t.Any]:
+    """Render DeprecationSummary as dict values for backward-compatibility with pre-2.19 TaskResult.deprecations."""
+    transformed = _event_utils.deprecation_as_dict(value)
+    transformed.update(deprecator=value.deprecator)
+
+    return transformed
+
+
+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),
+            event=_error_factory.ControllerEventFactory.from_exception(ex, _traceback.is_traceback_enabled(_traceback.TracebackEvent.ERROR)),
+        )
+
+
+_type_transform_mapping: dict[type, t.Callable[[t.Any], t.Any]] = {
+    _captured.CapturedErrorSummary: error_summary,
+    _messages.PluginInfo: plugin_info,
+    _messages.PluginType: plugin_type,
+    _messages.ErrorSummary: error_summary,
+    _messages.WarningSummary: warning_summary,
+    _messages.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,108 @@
+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)
+
+
+IGNORE_SCALAR_VAR_TYPES = {value for value in _datatag._ANSIBLE_ALLOWED_SCALAR_VAR_TYPES if not issubclass(value, str)}
+"""Scalar variable types that short-circuit bypass templating."""
+
+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
+}
+"""Scalar variable types which are allowed to appear in finalized template results."""

ansible/_internal/_testing.py

@@ -0,0 +1,26 @@
+"""
+Testing utilities for use in integration tests, not unit tests or non-test code.
+Provides better error behavior than Python's `assert` statement.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import typing as t
+
+
+class _Checker:
+    @staticmethod
+    def check(value: object, msg: str | None = 'Value is not truthy.') -> None:
+        """Raise an `AssertionError` if the given `value` is not truthy."""
+        if not value:
+            raise AssertionError(msg)
+
+
+@contextlib.contextmanager
+def hard_fail_context(msg: str) -> t.Generator[_Checker]:
+    """Enter a context which converts all exceptions to `BaseException` and provides a `Checker` instance for making assertions."""
+    try:
+        yield _Checker()
+    except BaseException as ex:
+        raise BaseException(f"Hard failure: {msg}") from ex