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

ansible/_internal/_errors/_alarm_timeout.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import contextlib
+import signal
+import types
+import typing as _t
+
+from ansible.module_utils import datatag
+
+
+class AnsibleTimeoutError(BaseException):
+    """A general purpose timeout."""
+
+    _MAX_TIMEOUT = 100_000_000
+    """
+    The maximum supported timeout value.
+    This value comes from BSD's alarm limit, which is due to that function using setitimer.
+    """
+
+    def __init__(self, timeout: int) -> None:
+        self.timeout = timeout
+
+        super().__init__(f"Timed out after {timeout} second(s).")
+
+    @classmethod
+    @contextlib.contextmanager
+    def alarm_timeout(cls, timeout: int | None) -> _t.Iterator[None]:
+        """
+        Context for running code under an optional timeout.
+        Raises an instance of this class if the timeout occurs.
+
+        New usages of this timeout mechanism are discouraged.
+        """
+        if timeout is not None:
+            if not isinstance(timeout, int):
+                raise TypeError(f"Timeout requires 'int' argument, not {datatag.native_type_name(timeout)!r}.")
+
+            if timeout < 0 or timeout > cls._MAX_TIMEOUT:
+                # On BSD based systems, alarm is implemented using setitimer.
+                # If out-of-bounds values are passed to alarm, they will return -1, which would be interpreted as an existing timer being set.
+                # To avoid that, bounds checking is performed in advance.
+                raise ValueError(f'Timeout {timeout} is invalid, it must be between 0 and {cls._MAX_TIMEOUT}.')
+
+        if not timeout:
+            yield  # execute the context manager's body
+            return  # no timeout to deal with, exit immediately
+
+        def on_alarm(_signal: int, _frame: types.FrameType) -> None:
+            raise cls(timeout)
+
+        if signal.signal(signal.SIGALRM, on_alarm):
+            raise RuntimeError("An existing alarm handler was present.")
+
+        try:
+            try:
+                if signal.alarm(timeout):
+                    raise RuntimeError("An existing alarm was set.")
+
+                yield  # execute the context manager's body
+            finally:
+                # Disable the alarm.
+                # If the alarm fires inside this finally block, the alarm is still disabled.
+                # This guarantees the cleanup code in the outer finally block runs without risk of encountering the `TaskTimeoutError` from the alarm.
+                signal.alarm(0)
+        finally:
+            signal.signal(signal.SIGALRM, signal.SIG_DFL)

ansible/_internal/_errors/_captured.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import collections.abc as _c
+import dataclasses
+import typing as t
+
+from ansible._internal._errors import _error_utils
+from ansible.errors import AnsibleRuntimeError
+from ansible.module_utils._internal import _messages
+
+
+class AnsibleCapturedError(AnsibleRuntimeError):
+    """An exception representing error detail captured in another context where the error detail must be serialized to be preserved."""
+
+    context: t.ClassVar[str]
+
+    def __init__(
+        self,
+        *,
+        obj: t.Any = None,
+        event: _messages.Event,
+    ) -> None:
+        super().__init__(
+            obj=obj,
+        )
+
+        self._event = event
+
+
+class AnsibleResultCapturedError(AnsibleCapturedError, _error_utils.ContributesToTaskResult):
+    """
+    An exception representing error detail captured in a foreign context where an action/module result dictionary is involved.
+
+    This exception provides a result dictionary via the ContributesToTaskResult mixin.
+    """
+
+    def __init__(self, event: _messages.Event, result: dict[str, t.Any]) -> None:
+        super().__init__(event=event)
+
+        self._result = result
+
+    @property
+    def result_contribution(self) -> _c.Mapping[str, object]:
+        return self._result
+
+    @classmethod
+    def maybe_raise_on_result(cls, result: dict[str, t.Any]) -> None:
+        """Normalize the result and raise an exception if the result indicated failure."""
+        if error_summary := cls.normalize_result_exception(result):
+            raise error_summary.error_type(error_summary.event, result)
+
+    @classmethod
+    def normalize_result_exception(cls, result: dict[str, t.Any]) -> CapturedErrorSummary | None:
+        """
+        Normalize the result `exception`, if any, to be a `CapturedErrorSummary` instance.
+        If a new `CapturedErrorSummary` was created, the `error_type` will be `cls`.
+        The `exception` key will be removed if falsey.
+        A `CapturedErrorSummary` instance will be returned if `failed` is truthy.
+        """
+        if type(cls) is AnsibleResultCapturedError:  # pylint: disable=unidiomatic-typecheck
+            raise TypeError('The normalize_result_exception method cannot be called on the AnsibleCapturedError base type, use a derived type.')
+
+        if not isinstance(result, dict):
+            raise TypeError(f'Malformed result. Received {type(result)} instead of {dict}.')
+
+        failed = result.get('failed')  # DTFIX-FUTURE: warn if failed is present and not a bool, or exception is present without failed being True
+        exception = result.pop('exception', None)
+
+        if not failed and not exception:
+            return None
+
+        if isinstance(exception, CapturedErrorSummary):
+            error_summary = exception
+        elif isinstance(exception, _messages.ErrorSummary):
+            error_summary = CapturedErrorSummary(
+                event=exception.event,
+                error_type=cls,
+            )
+        else:
+            # translate non-ErrorDetail errors
+            error_summary = CapturedErrorSummary(
+                event=_messages.Event(
+                    msg=str(result.get('msg', 'Unknown error.')),
+                    formatted_traceback=cls._normalize_traceback(exception),
+                ),
+                error_type=cls,
+            )
+
+        result.update(exception=error_summary)
+
+        return error_summary if failed else None  # even though error detail was normalized, only return it if the result indicated failure
+
+    @classmethod
+    def _normalize_traceback(cls, value: object | None) -> str | None:
+        """Normalize the provided traceback value, returning None if it is falsey."""
+        if not value:
+            return None
+
+        value = str(value).rstrip()
+
+        if not value:
+            return None
+
+        return value + '\n'
+
+
+class AnsibleActionCapturedError(AnsibleResultCapturedError):
+    """An exception representing error detail sourced directly by an action in its result dictionary."""
+
+    _default_message = 'Action failed.'
+    context = 'action'
+
+
+class AnsibleModuleCapturedError(AnsibleResultCapturedError):
+    """An exception representing error detail captured in a module context and returned from an action's result dictionary."""
+
+    _default_message = 'Module failed.'
+    context = 'target'
+
+
+@dataclasses.dataclass(**_messages._dataclass_kwargs)
+class CapturedErrorSummary(_messages.ErrorSummary):
+    error_type: type[AnsibleResultCapturedError] | None = None

ansible/_internal/_errors/_error_factory.py

@@ -0,0 +1,89 @@
+from __future__ import annotations as _annotations
+
+from ansible.module_utils._internal import _errors, _messages
+
+
+class ControllerEventFactory(_errors.EventFactory):
+    """Factory for creating `Event` instances from `BaseException` instances on the controller."""
+
+    def _get_msg(self, exception: BaseException) -> str | None:
+        from ansible.errors import AnsibleError
+
+        if not isinstance(exception, AnsibleError):
+            return super()._get_msg(exception)
+
+        return exception._original_message.strip()
+
+    def _get_formatted_source_context(self, exception: BaseException) -> str | None:
+        from ansible.errors import AnsibleError
+
+        if not isinstance(exception, AnsibleError):
+            return super()._get_formatted_source_context(exception)
+
+        return exception._formatted_source_context
+
+    def _get_help_text(self, exception: BaseException) -> str | None:
+        from ansible.errors import AnsibleError
+
+        if not isinstance(exception, AnsibleError):
+            return super()._get_help_text(exception)
+
+        return exception._help_text
+
+    def _get_chain(self, exception: BaseException) -> _messages.EventChain | None:
+        from ansible._internal._errors import _captured  # avoid circular import due to AnsibleError import
+
+        if isinstance(exception, _captured.AnsibleCapturedError):
+            # a captured error provides its own cause event, it never has a normal __cause__
+            return _messages.EventChain(
+                msg_reason=_errors.MSG_REASON_DIRECT_CAUSE,
+                traceback_reason=f'The above {exception.context} exception was the direct cause of the following controller exception:',
+                event=exception._event,
+            )
+
+        return super()._get_chain(exception)
+
+    def _follow_cause(self, exception: BaseException) -> bool:
+        from ansible.errors import AnsibleError
+
+        return not isinstance(exception, AnsibleError) or exception._include_cause_message
+
+    def _get_cause(self, exception: BaseException) -> BaseException | None:
+        # deprecated: description='remove support for orig_exc (deprecated in 2.23)' core_version='2.27'
+
+        cause = super()._get_cause(exception)
+
+        from ansible.errors import AnsibleError
+
+        if not isinstance(exception, AnsibleError):
+            return cause
+
+        try:
+            from ansible.utils.display import _display
+        except Exception:  # pylint: disable=broad-except  # if config is broken, this can raise things other than ImportError
+            _display = None
+
+        if cause:
+            if exception.orig_exc and exception.orig_exc is not cause and _display:
+                _display.warning(
+                    msg=f"The `orig_exc` argument to `{type(exception).__name__}` was given, but differed from the cause given by `raise ... from`.",
+                )
+
+            return cause
+
+        if exception.orig_exc:
+            if _display:
+                # encourage the use of `raise ... from` before deprecating `orig_exc`
+                _display.warning(
+                    msg=f"The `orig_exc` argument to `{type(exception).__name__}` was given without using `raise ... from orig_exc`.",
+                )
+
+            return exception.orig_exc
+
+        return None
+
+    def _get_events(self, exception: BaseException) -> tuple[_messages.Event, ...] | None:
+        if isinstance(exception, BaseExceptionGroup):
+            return tuple(self._convert_exception(ex) for ex in exception.exceptions)
+
+        return None

ansible/_internal/_errors/_error_utils.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import abc
+import collections.abc as _c
+import dataclasses
+import itertools
+import pathlib
+import textwrap
+import typing as t
+
+from ansible._internal._datatag._tags import Origin
+from ansible._internal._errors import _error_factory
+from ansible.module_utils._internal import _ambient_context, _event_utils, _messages, _traceback
+
+
+class ContributesToTaskResult(metaclass=abc.ABCMeta):
+    """Exceptions may include this mixin to contribute task result dictionary data directly to the final result."""
+
+    @property
+    @abc.abstractmethod
+    def result_contribution(self) -> _c.Mapping[str, object]:
+        """Mapping of results to apply to the task result."""
+
+    @property
+    def omit_exception_key(self) -> bool:
+        """Non-error exceptions (e.g., `AnsibleActionSkip`) must return `True` to ensure omission of the `exception` key."""
+        return False
+
+    @property
+    def omit_failed_key(self) -> bool:
+        """Exceptions representing non-failure scenarios (e.g., `skipped`, `unreachable`) must return `True` to ensure omisson of the `failed` key."""
+        return False
+
+
+class RedactAnnotatedSourceContext(_ambient_context.AmbientContextBase):
+    """When active, this context will redact annotated source lines, showing only the origin."""
+
+
+@dataclasses.dataclass(kw_only=True, frozen=True)
+class SourceContext:
+    origin: Origin
+    annotated_source_lines: list[str]
+    target_line: str | None
+
+    def __str__(self) -> str:
+        msg_lines = [f'Origin: {self.origin}']
+
+        if self.annotated_source_lines:
+            msg_lines.append('')
+            msg_lines.extend(self.annotated_source_lines)
+
+        return '\n'.join(msg_lines)
+
+    @classmethod
+    def from_value(cls, value: t.Any) -> SourceContext | None:
+        """Attempt to retrieve source and render a contextual indicator from the value's origin (if any)."""
+        if value is None:
+            return None
+
+        if isinstance(value, Origin):
+            origin = value
+            value = None
+        else:
+            origin = Origin.get_tag(value)
+
+        if RedactAnnotatedSourceContext.current(optional=True):
+            return cls.error('content redacted')
+
+        if origin and origin.path:
+            return cls.from_origin(origin)
+
+        if value is None:
+            truncated_value = None
+            annotated_source_lines = []
+        else:
+            # DTFIX-FUTURE: cleanup/share width
+            try:
+                value = str(value)
+            except Exception as ex:
+                value = f'<< context unavailable: {ex} >>'
+
+            truncated_value = textwrap.shorten(value, width=120)
+            annotated_source_lines = [truncated_value]
+
+        return SourceContext(
+            origin=origin or Origin.UNKNOWN,
+            annotated_source_lines=annotated_source_lines,
+            target_line=truncated_value,
+        )
+
+    @staticmethod
+    def error(message: str | None, origin: Origin | None = None) -> SourceContext:
+        return SourceContext(
+            origin=origin,
+            annotated_source_lines=[f'(source not shown: {message})'] if message else [],
+            target_line=None,
+        )
+
+    @classmethod
+    def from_origin(cls, origin: Origin) -> SourceContext:
+        """Attempt to retrieve source and render a contextual indicator of an error location."""
+        from ansible.parsing.vault import is_encrypted  # avoid circular import
+
+        # DTFIX-FUTURE: support referencing the column after the end of the target line, so we can indicate where a missing character (quote) needs to be added
+        #               this is also useful for cases like end-of-stream reported by the YAML parser
+
+        # DTFIX-FUTURE: Implement line wrapping and match annotated line width to the terminal display width.
+
+        context_line_count: t.Final = 2
+        max_annotated_line_width: t.Final = 120
+        truncation_marker: t.Final = '...'
+
+        target_line_num = origin.line_num
+
+        if RedactAnnotatedSourceContext.current(optional=True):
+            return cls.error('content redacted', origin)
+
+        if not target_line_num or target_line_num < 1:
+            return cls.error(None, origin)  # message omitted since lack of line number is obvious from pos
+
+        start_line_idx = max(0, (target_line_num - 1) - context_line_count)  # if near start of file
+        target_col_num = origin.col_num
+
+        try:
+            with pathlib.Path(origin.path).open() as src:
+                first_line = src.readline()
+                lines = list(itertools.islice(itertools.chain((first_line,), src), start_line_idx, target_line_num))
+        except Exception as ex:
+            return cls.error(type(ex).__name__, origin)
+
+        if is_encrypted(first_line):
+            return cls.error('content encrypted', origin)
+
+        if len(lines) != target_line_num - start_line_idx:
+            return cls.error('file truncated', origin)
+
+        annotated_source_lines = []
+
+        line_label_width = len(str(target_line_num))
+        max_src_line_len = max_annotated_line_width - line_label_width - 1
+
+        usable_line_len = max_src_line_len
+
+        for line_num, line in enumerate(lines, start_line_idx + 1):
+            line = line.rstrip('\n')  # universal newline default mode on `open` ensures we'll never see anything but \n
+            line = line.replace('\t', ' ')  # mixed tab/space handling is intentionally disabled since we're both format and display config agnostic
+
+            if len(line) > max_src_line_len:
+                line = line[: max_src_line_len - len(truncation_marker)] + truncation_marker
+                usable_line_len = max_src_line_len - len(truncation_marker)
+
+            annotated_source_lines.append(f'{str(line_num).rjust(line_label_width)}{" " if line else ""}{line}')
+
+        if target_col_num and usable_line_len >= target_col_num >= 1:
+            column_marker = f'column {target_col_num}'
+
+            target_col_idx = target_col_num - 1
+
+            if target_col_idx + 2 + len(column_marker) > max_src_line_len:
+                column_marker = f'{" " * (target_col_idx - len(column_marker) - 1)}{column_marker} ^'
+            else:
+                column_marker = f'{" " * target_col_idx}^ {column_marker}'
+
+            column_marker = f'{" " * line_label_width} {column_marker}'
+
+            annotated_source_lines.append(column_marker)
+        elif target_col_num is None:
+            underline_length = len(annotated_source_lines[-1]) - line_label_width - 1
+            annotated_source_lines.append(f'{" " * line_label_width} {"^" * underline_length}')
+
+        return SourceContext(
+            origin=origin,
+            annotated_source_lines=annotated_source_lines,
+            target_line=lines[-1].rstrip('\n'),  # universal newline default mode on `open` ensures we'll never see anything but \n
+        )
+
+
+def format_exception_message(exception: BaseException) -> str:
+    """Return the full chain of exception messages by concatenating the cause(s) until all are exhausted."""
+    return _event_utils.format_event_brief_message(_error_factory.ControllerEventFactory.from_exception(exception, False))
+
+
+def result_dict_from_exception(exception: BaseException, accept_result_contribution: bool = False) -> dict[str, object]:
+    """Return a failed task result dict from the given exception."""
+    event = _error_factory.ControllerEventFactory.from_exception(exception, _traceback.is_traceback_enabled(_traceback.TracebackEvent.ERROR))
+
+    result: dict[str, object] = {}
+    omit_failed_key = False
+    omit_exception_key = False
+
+    if accept_result_contribution:
+        while exception:
+            if isinstance(exception, ContributesToTaskResult):
+                result = dict(exception.result_contribution)
+                omit_failed_key = exception.omit_failed_key
+                omit_exception_key = exception.omit_exception_key
+                break
+
+            exception = exception.__cause__
+
+    if omit_failed_key:
+        result.pop('failed', None)
+    else:
+        result.update(failed=True)
+
+    if omit_exception_key:
+        result.pop('exception', None)
+    else:
+        result.update(exception=_messages.ErrorSummary(event=event))
+
+    if 'msg' not in result:
+        # if nothing contributed `msg`, generate one from the exception messages
+        result.update(msg=_event_utils.format_event_brief_message(event))
+
+    return result
+
+
+def result_dict_from_captured_errors(
+    msg: str,
+    *,
+    errors: list[_messages.ErrorSummary] | None = None,
+) -> dict[str, object]:
+    """Return a failed task result dict from the given error message and captured errors."""
+    _skip_stackwalk = True
+
+    event = _messages.Event(
+        msg=msg,
+        formatted_traceback=_traceback.maybe_capture_traceback(msg, _traceback.TracebackEvent.ERROR),
+        events=tuple(error.event for error in errors) if errors else None,
+    )
+
+    result = dict(
+        failed=True,
+        exception=_messages.ErrorSummary(
+            event=event,
+        ),
+        msg=_event_utils.format_event_brief_message(event),
+    )
+
+    return result

ansible/_internal/_errors/_handler.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import contextlib
+import enum
+import typing as t
+
+from ansible.utils.display import Display
+from ansible.constants import config
+
+display = Display()
+
+# FUTURE: add sanity test to detect use of skip_on_ignore without Skippable (and vice versa)
+
+
+class ErrorAction(enum.Enum):
+    """Action to take when an error is encountered."""
+
+    IGNORE = enum.auto()
+    WARNING = enum.auto()
+    ERROR = enum.auto()
+
+    @classmethod
+    def from_config(cls, setting: str, variables: dict[str, t.Any] | None = None) -> t.Self:
+        """Return an `ErrorAction` enum from the specified Ansible config setting."""
+        return cls[config.get_config_value(setting, variables=variables).upper()]
+
+
+class _SkipException(BaseException):
+    """Internal flow control exception for skipping code blocks within a `Skippable` context manager."""
+
+    def __init__(self) -> None:
+        super().__init__('Skipping ignored action due to use of `skip_on_ignore`. It is a bug to encounter this message outside of debugging.')
+
+
+class _SkippableContextManager:
+    """Internal context manager to support flow control for skipping code blocks."""
+
+    def __enter__(self) -> None:
+        pass
+
+    def __exit__(self, exc_type, _exc_val, _exc_tb) -> bool:
+        if exc_type is None:
+            raise RuntimeError('A `Skippable` context manager was entered, but a `skip_on_ignore` handler was never invoked.')
+
+        return exc_type is _SkipException  # only mask a _SkipException, allow all others to raise
+
+
+Skippable = _SkippableContextManager()
+"""Context manager singleton required to enclose `ErrorHandler.handle` invocations when `skip_on_ignore` is `True`."""
+
+
+class ErrorHandler:
+    """
+    Provides a configurable error handler context manager for a specific list of exception types.
+    Unhandled errors leaving the context manager can be ignored, treated as warnings, or allowed to raise by setting `ErrorAction`.
+    """
+
+    def __init__(self, action: ErrorAction) -> None:
+        self.action = action
+
+    @contextlib.contextmanager
+    def handle(self, *args: type[BaseException], skip_on_ignore: bool = False) -> t.Iterator[None]:
+        """
+        Handle the specified exception(s) using the defined error action.
+        If `skip_on_ignore` is `True`, the body of the context manager will be skipped for `ErrorAction.IGNORE`.
+        Use of `skip_on_ignore` requires enclosure within the `Skippable` context manager.
+        """
+        if not args:
+            raise ValueError('At least one exception type is required.')
+
+        if skip_on_ignore and self.action == ErrorAction.IGNORE:
+            raise _SkipException()  # skipping ignored action
+
+        try:
+            yield
+        except args as ex:
+            match self.action:
+                case ErrorAction.WARNING:
+                    display.error_as_warning(msg=None, exception=ex)
+                case ErrorAction.ERROR:
+                    raise
+                case _:  # ErrorAction.IGNORE
+                    pass
+
+        if skip_on_ignore:
+            raise _SkipException()  # completed skippable action, ensures the `Skippable` context was used
+
+    @classmethod
+    def from_config(cls, setting: str, variables: dict[str, t.Any] | None = None) -> t.Self:
+        """Return an `ErrorHandler` instance configured using the specified Ansible config setting."""
+        return cls(ErrorAction.from_config(setting, variables=variables))

ansible/_internal/_errors/_task_timeout.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections import abc as _c
+
+from ansible._internal._errors._alarm_timeout import AnsibleTimeoutError
+from ansible._internal._errors._error_utils import ContributesToTaskResult
+from ansible.module_utils.datatag import deprecate_value
+
+
+class TaskTimeoutError(AnsibleTimeoutError, ContributesToTaskResult):
+    """
+    A task-specific timeout.
+
+    This exception provides a result dictionary via the ContributesToTaskResult mixin.
+    """
+
+    @property
+    def result_contribution(self) -> _c.Mapping[str, object]:
+        help_text = "Configure `DISPLAY_TRACEBACK` to see a traceback on timeout errors."
+
+        frame = deprecate_value(
+            value=help_text,
+            msg="The `timedout.frame` task result key is deprecated.",
+            help_text=help_text,
+            version="2.23",
+        )
+
+        return dict(timedout=dict(frame=frame, period=self.timeout))