ansible-core 2.19.0b3__py3-none-any.whl → 2.19.0b5__py3-none-any.whl

ansible/_internal/__init__.py

@@ -18,7 +18,7 @@ def get_controller_serialize_map() -> dict[type, t.Callable]:
     return {
         _lazy_containers._AnsibleLazyTemplateDict: _profiles._JSONSerializationProfile.discard_tags,
         _lazy_containers._AnsibleLazyTemplateList: _profiles._JSONSerializationProfile.discard_tags,
-        EncryptedString: str,  # preserves tags since this is an intance of EncryptedString; if tags should be discarded from str, another entry will handle it
+        EncryptedString: str,  # preserves tags since this is an instance of EncryptedString; if tags should be discarded from str, another entry will handle it
     }
 
 
@@ -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/_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

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/_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))

ansible/_internal/_event_formatting.py

@@ -0,0 +1,127 @@
+from __future__ import annotations as _annotations
+
+import collections.abc as _c
+import textwrap as _textwrap
+
+from ansible.module_utils._internal import _event_utils, _messages
+
+
+def format_event(event: _messages.Event, include_traceback: bool) -> str:
+    """Format an event into a verbose message and traceback."""
+    msg = format_event_verbose_message(event)
+
+    if include_traceback:
+        msg += '\n' + format_event_traceback(event)
+
+    msg = msg.strip()
+
+    if '\n' in msg:
+        msg += '\n\n'
+    else:
+        msg += '\n'
+
+    return msg
+
+
+def format_event_traceback(event: _messages.Event) -> str:
+    """Format an event into a traceback."""
+    segments: list[str] = []
+
+    while event:
+        segment = event.formatted_traceback or '(traceback missing)\n'
+
+        if event.events:
+            child_tracebacks = [format_event_traceback(child) for child in event.events]
+            segment += _format_event_children("Sub-Traceback", child_tracebacks)
+
+        segments.append(segment)
+
+        if event.chain:
+            segments.append(f'\n{event.chain.traceback_reason}\n\n')
+
+            event = event.chain.event
+        else:
+            event = None
+
+    return ''.join(reversed(segments))
+
+
+def format_event_verbose_message(event: _messages.Event) -> str:
+    """
+    Format an event into a verbose message.
+    Help text, contextual information and sub-events will be included.
+    """
+    segments: list[str] = []
+    original_event = event
+
+    while event:
+        messages = [event.msg]
+        chain: _messages.EventChain = event.chain
+
+        while chain and chain.follow:
+            if chain.event.events:
+                break  # do not collapse a chained event with sub-events, since they would be lost
+
+            if chain.event.formatted_source_context or chain.event.help_text:
+                if chain.event.formatted_source_context != event.formatted_source_context or chain.event.help_text != event.help_text:
+                    break  # do not collapse a chained event with different details, since they would be lost
+
+            if chain.event.chain and chain.msg_reason != chain.event.chain.msg_reason:
+                break  # do not collapse a chained event which has a chain with a different msg_reason
+
+            messages.append(chain.event.msg)
+
+            chain = chain.event.chain
+
+        msg = _event_utils.deduplicate_message_parts(messages)
+        segment = '\n'.join(_get_message_lines(msg, event.help_text, event.formatted_source_context)) + '\n'
+
+        if event.events:
+            child_msgs = [format_event_verbose_message(child) for child in event.events]
+            segment += _format_event_children("Sub-Event", child_msgs)
+
+        segments.append(segment)
+
+        if chain and chain.follow:
+            segments.append(f'\n{chain.msg_reason}\n\n')
+
+            event = chain.event
+        else:
+            event = None
+
+    if len(segments) > 1:
+        segments.insert(0, _event_utils.format_event_brief_message(original_event) + '\n\n')
+
+    return ''.join(segments)
+
+
+def _format_event_children(label: str, children: _c.Iterable[str]) -> str:
+    """Format the given list of child messages into a single string."""
+    items = list(children)
+    count = len(items)
+    lines = ['\n']
+
+    for idx, item in enumerate(items):
+        lines.append(f'+--[ {label} {idx + 1} of {count} ]---\n')
+        lines.append(_textwrap.indent(f"\n{item}\n", "| ", lambda value: True))
+
+    lines.append(f'+--[ End {label} ]---\n')
+
+    return ''.join(lines)
+
+
+def _get_message_lines(message: str, help_text: str | None, formatted_source_context: str | None) -> list[str]:
+    """Return a list of message lines constructed from the given message, help text and formatted source context."""
+    if help_text and not formatted_source_context and '\n' not in message and '\n' not in help_text:
+        return [f'{message} {help_text}']  # prefer a single-line message with help text when there is no source context
+
+    message_lines = [message]
+
+    if formatted_source_context:
+        message_lines.append(formatted_source_context)
+
+    if help_text:
+        message_lines.append('')
+        message_lines.append(help_text)
+
+    return message_lines