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

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/_utils.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import dataclasses
+import itertools
+import pathlib
+import sys
+import textwrap
+import typing as t
+
+from ansible.module_utils.common.messages import Detail, ErrorSummary
+from ansible._internal._datatag._tags import Origin
+from ansible.module_utils._internal import _ambient_context, _traceback
+from ansible import errors
+
+if t.TYPE_CHECKING:
+    from ansible.utils.display import Display
+
+
+class RedactAnnotatedSourceContext(_ambient_context.AmbientContextBase):
+    """
+    When active, this context will redact annotated source lines, showing only the origin.
+    """
+
+
+def _dedupe_and_concat_message_chain(message_parts: list[str]) -> str:
+    message_parts = list(reversed(message_parts))
+
+    message = message_parts.pop(0)
+
+    for message_part in message_parts:
+        # avoid duplicate messages where the cause was already concatenated to the exception message
+        if message_part.endswith(message):
+            message = message_part
+        else:
+            message = concat_message(message_part, message)
+
+    return message
+
+
+def _collapse_error_details(error_details: t.Sequence[Detail]) -> list[Detail]:
+    """
+    Return a potentially modified error chain, with redundant errors collapsed into previous error(s) in the chain.
+    This reduces the verbosity of messages by eliminating repetition when multiple errors in the chain share the same contextual information.
+    """
+    previous_error = error_details[0]
+    previous_warnings: list[str] = []
+    collapsed_error_details: list[tuple[Detail, list[str]]] = [(previous_error, previous_warnings)]
+
+    for error in error_details[1:]:
+        details_present = error.formatted_source_context or error.help_text
+        details_changed = error.formatted_source_context != previous_error.formatted_source_context or error.help_text != previous_error.help_text
+
+        if details_present and details_changed:
+            previous_error = error
+            previous_warnings = []
+            collapsed_error_details.append((previous_error, previous_warnings))
+        else:
+            previous_warnings.append(error.msg)
+
+    final_error_details: list[Detail] = []
+
+    for error, messages in collapsed_error_details:
+        final_error_details.append(dataclasses.replace(error, msg=_dedupe_and_concat_message_chain([error.msg] + messages)))
+
+    return final_error_details
+
+
+def _get_cause(exception: BaseException) -> BaseException | None:
+    # deprecated: description='remove support for orig_exc (deprecated in 2.23)' core_version='2.27'
+
+    if not isinstance(exception, errors.AnsibleError):
+        return exception.__cause__
+
+    if exception.__cause__:
+        if exception.orig_exc and exception.orig_exc is not exception.__cause__:
+            _get_display().warning(
+                msg=f"The `orig_exc` argument to `{type(exception).__name__}` was given, but differed from the cause given by `raise ... from`.",
+            )
+
+        return exception.__cause__
+
+    if exception.orig_exc:
+        # encourage the use of `raise ... from` before deprecating `orig_exc`
+        _get_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
+
+
+class _TemporaryDisplay:
+    # DTFIX-FUTURE: generalize this and hide it in the display module so all users of Display can benefit
+
+    @staticmethod
+    def warning(*args, **kwargs):
+        print(f'FALLBACK WARNING: {args} {kwargs}', file=sys.stderr)
+
+    @staticmethod
+    def deprecated(*args, **kwargs):
+        print(f'FALLBACK DEPRECATION: {args} {kwargs}', file=sys.stderr)
+
+
+def _get_display() -> Display | _TemporaryDisplay:
+    try:
+        from ansible.utils.display import Display
+    except ImportError:
+        return _TemporaryDisplay()
+
+    return Display()
+
+
+def _create_error_summary(exception: BaseException, event: _traceback.TracebackEvent | None = None) -> ErrorSummary:
+    from . import _captured  # avoid circular import due to AnsibleError import
+
+    current_exception: BaseException | None = exception
+    error_details: list[Detail] = []
+
+    if event:
+        formatted_traceback = _traceback.maybe_extract_traceback(exception, event)
+    else:
+        formatted_traceback = None
+
+    while current_exception:
+        if isinstance(current_exception, errors.AnsibleError):
+            include_cause_message = current_exception._include_cause_message
+            edc = Detail(
+                msg=current_exception._original_message.strip(),
+                formatted_source_context=current_exception._formatted_source_context,
+                help_text=current_exception._help_text,
+            )
+        else:
+            include_cause_message = True
+            edc = Detail(
+                msg=str(current_exception).strip(),
+            )
+
+        error_details.append(edc)
+
+        if isinstance(current_exception, _captured.AnsibleCapturedError):
+            detail = current_exception.error_summary
+            error_details.extend(detail.details)
+
+            if formatted_traceback and detail.formatted_traceback:
+                formatted_traceback = (
+                    f'{detail.formatted_traceback}\n'
+                    f'The {current_exception.context} exception above was the direct cause of the following controller exception:\n\n'
+                    f'{formatted_traceback}'
+                )
+
+        if not include_cause_message:
+            break
+
+        current_exception = _get_cause(current_exception)
+
+    return ErrorSummary(details=tuple(error_details), formatted_traceback=formatted_traceback)
+
+
+def concat_message(left: str, right: str) -> str:
+    """Normalize `left` by removing trailing punctuation and spaces before appending new punctuation and `right`."""
+    return f'{left.rstrip(". ")}: {right}'
+
+
+def get_chained_message(exception: BaseException) -> str:
+    """
+    Return the full chain of exception messages by concatenating the cause(s) until all are exhausted.
+    """
+    error_summary = _create_error_summary(exception)
+    message_parts = [edc.msg for edc in error_summary.details]
+
+    return _dedupe_and_concat_message_chain(message_parts)
+
+
+@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)
+
+        # DTFIX-RELEASE: redaction context may not be sufficient to avoid secret disclosure without SensitiveData and other enhancements
+        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
+        )

ansible/_internal/_json/__init__.py

@@ -0,0 +1,203 @@
+"""Internal utilities for serialization and deserialization."""
+
+# DTFIX-RELEASE: 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,
+        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.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(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(value)
+
+        if self.apply_transforms and value_type in _transform._type_transform_mapping:
+            value = self._template_engine.transform(value)
+            value_type = type(value)
+
+        # DTFIX-RELEASE: need to handle native copy for keys too
+        if self.convert_to_native_values and isinstance(value, _datatag.AnsibleTaggedObject):
+            value = value._native_copy()
+            value_type = type(value)
+
+        result: _T
+
+        # DTFIX-RELEASE: the visitor is ignoring dict/mapping keys except for debugging and schema-aware checking, it should be doing type checks on keys
+        #                keep in mind the allowed types for keys is a more restrictive set than for values (str and taggged str only, not EncryptedString)
+        # DTFIX-RELEASE: some type lists being consulted (the ones from datatag) are probably too permissive, and perhaps should not be dynamic
+
+        if (result := self._early_visit(value, value_type)) is not _sentinel:
+            pass
+        # DTFIX-RELEASE: 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, ((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.encrypted_string_behavior != EncryptedStringBehavior.FAIL and isinstance(value, EncryptedString):
+            match self.encrypted_string_behavior:
+                case EncryptedStringBehavior.REDACT:
+                    result = "<redacted>"  # type: ignore[assignment]
+                case EncryptedStringBehavior.PRESERVE:
+                    result = value  # type: ignore[assignment]
+                case EncryptedStringBehavior.DECRYPT:
+                    result = str(value)  # type: ignore[assignment]
+        elif self.convert_mapping_to_dict and _internal.is_intermediate_mapping(value):
+            with self:  # supports StateTrackingMixIn
+                result = {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]
+        else:
+            if value_type not in _ANSIBLE_ALLOWED_VAR_TYPES:
+                raise AnsibleVariableTypeError.from_value(obj=value)
+
+            # supported scalar type that requires no special handling, just return as-is
+            result = 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)