ansible-core 2.19.0b4__py3-none-any.whl → 2.19.0b6__py3-none-any.whl

ansible/_internal/__init__.py

@@ -45,7 +45,7 @@ def setup() -> None:
     """No-op function to ensure that side-effect only imports of this module are not flagged/removed as 'unused'."""
 
 
-# DTFIX-RELEASE: this is really fragile- disordered/incorrect imports (among other things) can mess it up. Consider a hosting-env-managed context
+# DTFIX-FUTURE: this is really fragile- disordered/incorrect imports (among other things) can mess it up. Consider a hosting-env-managed context
 #  with an enum with at least Controller/Target/Unknown values, and possibly using lazy-init module shims or some other mechanism to allow controller-side
 #  notification/augmentation of this kind of metadata.
 _internal.get_controller_serialize_map = get_controller_serialize_map

ansible/_internal/_ansiballz/_builder.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+
+import typing as t
+
+from ansible.module_utils._internal._ansiballz import _extensions
+from ansible.module_utils._internal._ansiballz._extensions import _pydevd, _coverage
+from ansible.constants import config
+
+_T = t.TypeVar('_T')
+
+
+class ExtensionManager:
+    """AnsiballZ extension manager."""
+
+    def __init__(
+        self,
+        debugger: _pydevd.Options | None = None,
+        coverage: _coverage.Options | None = None,
+    ) -> None:
+        options = dict(
+            _pydevd=debugger,
+            _coverage=coverage,
+        )
+
+        self._debugger = debugger
+        self._coverage = coverage
+        self._extension_names = tuple(name for name, option in options.items() if option)
+        self._module_names = tuple(f'{_extensions.__name__}.{name}' for name in self._extension_names)
+
+        self.source_mapping: dict[str, str] = {}
+
+    @property
+    def debugger_enabled(self) -> bool:
+        """Returns True if the debugger extension is enabled, otherwise False."""
+        return bool(self._debugger)
+
+    @property
+    def extension_names(self) -> tuple[str, ...]:
+        """Names of extensions to include in the AnsiballZ payload."""
+        return self._extension_names
+
+    @property
+    def module_names(self) -> tuple[str, ...]:
+        """Python module names of extensions to include in the AnsiballZ payload."""
+        return self._module_names
+
+    def get_extensions(self) -> dict[str, dict[str, object]]:
+        """Return the configured extensions and their options."""
+        extension_options: dict[str, t.Any] = {}
+
+        if self._debugger:
+            extension_options['_pydevd'] = dataclasses.replace(
+                self._debugger,
+                source_mapping=self._get_source_mapping(),
+            )
+
+        if self._coverage:
+            extension_options['_coverage'] = self._coverage
+
+        extensions = {extension: dataclasses.asdict(options) for extension, options in extension_options.items()}
+
+        return extensions
+
+    def _get_source_mapping(self) -> dict[str, str]:
+        """Get the source mapping, adjusting the source root as needed."""
+        if self._debugger.source_mapping:
+            source_mapping = {self._translate_path(key): value for key, value in self.source_mapping.items()}
+        else:
+            source_mapping = self.source_mapping
+
+        return source_mapping
+
+    def _translate_path(self, path: str) -> str:
+        """Translate a local path to a foreign path."""
+        for replace, match in self._debugger.source_mapping.items():
+            if path.startswith(match):
+                return replace + path[len(match) :]
+
+        return path
+
+    @classmethod
+    def create(cls, task_vars: dict[str, object]) -> t.Self:
+        """Create an instance using the provided task vars."""
+        return cls(
+            debugger=cls._get_options('_ANSIBALLZ_DEBUGGER_CONFIG', _pydevd.Options, task_vars),
+            coverage=cls._get_options('_ANSIBALLZ_COVERAGE_CONFIG', _coverage.Options, task_vars),
+        )
+
+    @classmethod
+    def _get_options(cls, name: str, config_type: type[_T], task_vars: dict[str, object]) -> _T | None:
+        """Parse configuration from the named environment variable as the specified type, or None if not configured."""
+        if (value := config.get_config_value(name, variables=task_vars)) is None:
+            return None
+
+        data = json.loads(value) if isinstance(value, str) else value
+        options = config_type(**data)
+
+        return options

ansible/_internal/{_ansiballz.py → _ansiballz/_wrapper.py}

@@ -37,14 +37,13 @@ _ANSIBALLZ_WRAPPER = True
 
 
 def _ansiballz_main(
-    zipdata: str,
+    zip_data: str,
     ansible_module: str,
     module_fqn: str,
     params: str,
     profile: str,
     date_time: datetime.datetime,
-    coverage_config: str | None,
-    coverage_output: str | None,
+    extensions: dict[str, dict[str, object]],
     rlimit_nofile: int,
 ) -> None:
     import os
@@ -136,15 +135,14 @@ def _ansiballz_main(
         # can monkeypatch the right basic
         sys.path.insert(0, modlib_path)
 
-        from ansible.module_utils._internal._ansiballz import run_module
+        from ansible.module_utils._internal._ansiballz import _loader
 
-        run_module(
+        _loader.run_module(
             json_params=json_params,
             profile=profile,
             module_fqn=module_fqn,
             modlib_path=modlib_path,
-            coverage_config=coverage_config,
-            coverage_output=coverage_output,
+            extensions=extensions,
         )
 
     def debug(command: str, modlib_path: str, json_params: bytes) -> None:
@@ -223,13 +221,14 @@ def _ansiballz_main(
             with open(args_path, 'rb') as reader:
                 json_params = reader.read()
 
-            from ansible.module_utils._internal._ansiballz import run_module
+            from ansible.module_utils._internal._ansiballz import _loader
 
-            run_module(
+            _loader.run_module(
                 json_params=json_params,
                 profile=profile,
                 module_fqn=module_fqn,
                 modlib_path=modlib_path,
+                extensions=extensions,
             )
 
         else:
@@ -246,13 +245,14 @@ def _ansiballz_main(
     # store this in remote_tmpdir (use system tempdir instead)
     # Only need to use [ansible_module]_payload_ in the temp_path until we move to zipimport
     # (this helps ansible-test produce coverage stats)
-    temp_path = tempfile.mkdtemp(prefix='ansible_' + ansible_module + '_payload_')
+    # IMPORTANT: The real path must be used here to ensure a remote debugger such as PyCharm (using pydevd) can resolve paths correctly.
+    temp_path = os.path.realpath(tempfile.mkdtemp(prefix='ansible_' + ansible_module + '_payload_'))
 
     try:
         zipped_mod = os.path.join(temp_path, 'ansible_' + ansible_module + '_payload.zip')
 
         with open(zipped_mod, 'wb') as modlib:
-            modlib.write(base64.b64decode(zipdata))
+            modlib.write(base64.b64decode(zip_data))
 
         if len(sys.argv) == 2:
             debug(sys.argv[1], zipped_mod, encoded_params)

ansible/_internal/_collection_proxy.py

@@ -9,7 +9,7 @@ _T_co = _t.TypeVar('_T_co', covariant=True)
 class SequenceProxy(_c.Sequence[_T_co]):
     """A read-only sequence proxy."""
 
-    # DTFIX-RELEASE: needs unit test coverage
+    # DTFIX5: needs unit test coverage
 
     __slots__ = ('__value',)
 

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

@@ -1,10 +1,12 @@
 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.common.messages import ErrorSummary, Detail, _dataclass_kwargs
+from ansible.module_utils._internal import _messages
 
 
 class AnsibleCapturedError(AnsibleRuntimeError):
@@ -16,43 +18,36 @@ class AnsibleCapturedError(AnsibleRuntimeError):
         self,
         *,
         obj: t.Any = None,
-        error_summary: ErrorSummary,
+        event: _messages.Event,
     ) -> None:
         super().__init__(
             obj=obj,
         )
 
-        self._error_summary = error_summary
+        self._event = event
 
-    @property
-    def error_summary(self) -> ErrorSummary:
-        return self._error_summary
 
+class AnsibleResultCapturedError(AnsibleCapturedError, _error_utils.ContributesToTaskResult):
+    """
+    An exception representing error detail captured in a foreign context where an action/module result dictionary is involved.
 
-class AnsibleResultCapturedError(AnsibleCapturedError):
-    """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, error_summary: ErrorSummary, result: dict[str, t.Any]) -> None:
-        super().__init__(error_summary=error_summary)
+    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, result)
-
-    @classmethod
-    def find_first_remoted_error(cls, exception: BaseException) -> t.Self | None:
-        """Find the first captured module error in the cause chain, starting with the given exception, returning None if not found."""
-        while exception:
-            if isinstance(exception, cls):
-                return exception
-
-            exception = exception.__cause__
-
-        return None
+            raise error_summary.error_type(error_summary.event, result)
 
     @classmethod
     def normalize_result_exception(cls, result: dict[str, t.Any]) -> CapturedErrorSummary | None:
@@ -76,17 +71,18 @@ class AnsibleResultCapturedError(AnsibleCapturedError):
 
         if isinstance(exception, CapturedErrorSummary):
             error_summary = exception
-        elif isinstance(exception, ErrorSummary):
+        elif isinstance(exception, _messages.ErrorSummary):
             error_summary = CapturedErrorSummary(
-                details=exception.details,
-                formatted_traceback=cls._normalize_traceback(exception.formatted_traceback),
+                event=exception.event,
                 error_type=cls,
             )
         else:
             # translate non-ErrorDetail errors
             error_summary = CapturedErrorSummary(
-                details=(Detail(msg=str(result.get('msg', 'Unknown error.'))),),
-                formatted_traceback=cls._normalize_traceback(exception),
+                event=_messages.Event(
+                    msg=str(result.get('msg', 'Unknown error.')),
+                    formatted_traceback=cls._normalize_traceback(exception),
+                ),
                 error_type=cls,
             )
 
@@ -122,7 +118,6 @@ class AnsibleModuleCapturedError(AnsibleResultCapturedError):
     context = 'target'
 
 
-@dataclasses.dataclass(**_dataclass_kwargs)
-class CapturedErrorSummary(ErrorSummary):
-    # DTFIX-RELEASE: where to put this, name, etc. since it shows up in results, it's not exactly private (and contains a type ref to an internal type)
+@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