midpoint-cli 1.6.0__py3-none-any.whl

midpoint_cli/prompt/task.py

@@ -0,0 +1,296 @@
+from argparse import ArgumentParser, RawTextHelpFormatter
+from typing import Any, cast
+
+# Task command wrapper parser
+from midpoint_cli.client import (
+    MidpointObjectList,
+    MidpointObjectTypes,
+    MidpointTask,
+    NopProgressMonitor,
+    TaskExecutionFailure,
+)
+from midpoint_cli.client.constants import ResultStatus, TaskExecutionState
+from midpoint_cli.client.object_query import TASK_STATUS_FILTERS
+from midpoint_cli.client.safe_xml import fromstring as safe_fromstring
+from midpoint_cli.prompt.base import PromptBase, add_listing_arguments
+from midpoint_cli.prompt.complete import TASK, completes
+from midpoint_cli.prompt.console import (
+    OUTCOME_STYLE,
+    create_progress_monitor,
+    get_console,
+    is_machine_output,
+    print_details,
+    print_error,
+    print_info,
+    print_rows,
+)
+
+task_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='task',
+    description='Manage server tasks.',
+    epilog="""
+Available commands:
+  ls       List all server tasks.
+  get      Show the details of task(s).
+  run      Run task(s) sequentially.
+  suspend  Suspend task(s).
+  resume   Resume task(s).
+  wait     Wait for task completion.
+""",
+)
+task_parser.add_argument('command', help='Task command to execute.')
+task_parser.add_argument('arg', help='Optional command arguments.', nargs='*')
+
+# Task LS parser
+
+task_ls_parser = add_listing_arguments(
+    ArgumentParser(
+        formatter_class=RawTextHelpFormatter,
+        prog='task ls',
+        description='List server tasks.',
+    ),
+    'tasks',
+)
+task_ls_parser.add_argument(
+    '--status',
+    action='append',
+    choices=list(TASK_STATUS_FILTERS),
+    metavar='STATUS',
+    help='Only list tasks in this status (filtered on the server); repeat to list several.\n'
+    'Execution states: running, runnable, waiting, suspended, closed.\n'
+    'Last run results: in_progress, success, warning, failed (fatal or partial error).',
+)
+
+# Task GET parser
+
+task_get_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='task get',
+    description='Show the details of tasks.',
+)
+completes(task_get_parser.add_argument('task', help='Task to show. Can be an OID or a task name.', nargs='+'), TASK)
+
+# Task RUN parser
+
+task_run_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='task run',
+    description='Run tasks synchronously.',
+)
+completes(task_run_parser.add_argument('task', help='Task to be run. Can be an OID or a task name.', nargs='+'), TASK)
+task_run_parser.add_argument(
+    '--no-changes',
+    action='store_true',
+    help="Don't stream audit events as the task runs (silences the inline change log).",
+)
+
+# Task WAIT parser
+
+task_wait_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='task wait',
+    description='Wait for tasks to complete. Without a task, waits for every task in progress.',
+)
+completes(
+    task_wait_parser.add_argument('task', help='Task to wait for. Can be an OID or a task name.', nargs='*'), TASK
+)
+task_wait_parser.add_argument(
+    '--no-changes',
+    action='store_true',
+    help="Don't stream audit events while waiting (silences the inline change log).",
+)
+
+# Task SUSPEND and RESUME parsers
+
+task_suspend_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='task suspend',
+    description='Suspend tasks.',
+)
+completes(
+    task_suspend_parser.add_argument('task', help='Task to suspend. Can be an OID or a task name.', nargs='+'), TASK
+)
+
+task_resume_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='task resume',
+    description='Resume suspended tasks.',
+)
+completes(
+    task_resume_parser.add_argument('task', help='Task to resume. Can be an OID or a task name.', nargs='+'), TASK
+)
+
+# Each subcommand with its parser; None for those taking no arguments.
+task_subparsers: dict[str, ArgumentParser | None] = {
+    'ls': task_ls_parser,
+    'get': task_get_parser,
+    'run': task_run_parser,
+    'wait': task_wait_parser,
+    'suspend': task_suspend_parser,
+    'resume': task_resume_parser,
+}
+
+
+def _task_cell_style(column: str, value: str) -> str | None:
+    """Color the result status of a task row by outcome; an empty status keeps the column style."""
+    if column == 'Result Status' and value:
+        return OUTCOME_STYLE.get(value.replace('-', '_').lower())
+    return None
+
+
+def task_details(task: MidpointTask) -> dict[str, Any]:
+    """A task as one detail object: the properties of `task get`, then its Transitions and Actions.
+
+    The nested records use the column names of the Transitions and Actions tables.
+    """
+    details: dict[str, Any] = dict(task)
+    details['Transitions'] = [
+        {'From State': from_state, 'To State': to_state, 'Count': count}
+        for from_state, to_state, count in task.get_transitions()
+    ]
+    details['Actions'] = [
+        {'Type': object_type, 'Action': operation, 'Success': success, 'Failure': failure}
+        for object_type, operation, success, failure in task.get_actions()
+    ]
+    return details
+
+
+class TaskClientPrompt(PromptBase):
+    subparsers_task = task_subparsers
+
+    def do_task(self, inp: str) -> None:
+        """Manage server tasks (subcommands: ls, run, suspend, resume, wait, get)."""
+        # Strict: an unknown subcommand followed by arguments is a usage error, so a typo
+        # in a subcommand is not mistaken for another command.
+        self._dispatch_subcommand(
+            inp,
+            task_parser,
+            task_subparsers,
+            {
+                'ls': self._task_ls,
+                'get': self._task_get,
+                'wait': self._task_wait,
+                'run': lambda args: self._task_action('run', task_run_parser, args),
+                'resume': lambda args: self._task_action('resume', task_resume_parser, args),
+                'suspend': lambda args: self._task_action('suspend', task_suspend_parser, args),
+            },
+            strict=True,
+        )
+
+    def _task_ls(self, args: list[str]) -> None:
+        ls_ns = task_ls_parser.parse_args(args)
+        if ls_ns.status:
+            tasks = self.client.get_tasks(limit=ls_ns.limit, name_filter=ls_ns.filter, statuses=ls_ns.status)
+        else:
+            tasks = self.client.get_tasks(limit=ls_ns.limit, name_filter=ls_ns.filter)
+        self._print_tasks_table(tasks)
+
+    def _task_get(self, args: list[str]) -> None:
+        get_ns = task_get_parser.parse_args(args)
+        details = []
+
+        for task_id in get_ns.task:
+            task_obj = self._find_reference(MidpointObjectTypes.TASK.value, task_id, 'Task')
+            if task_obj is None:
+                continue
+            if is_machine_output():
+                details.append(task_details(cast(MidpointTask, task_obj)))
+            else:
+                get_console().print(cast(MidpointTask, task_obj).get_full_description())
+
+        if is_machine_output():
+            # Shaped by the arguments, not by how many were found: one task, one object.
+            print_details(details, as_list=len(get_ns.task) > 1)
+
+    def _task_wait(self, args: list[str]) -> None:
+        wait_ns = task_wait_parser.parse_args(args)
+        tasks_to_wait: list[str] = wait_ns.task or [
+            oid
+            for task in self.client.get_tasks()
+            if task['Result Status'] == ResultStatus.IN_PROGRESS and (oid := task.get_oid()) is not None
+        ]
+
+        for task_id in tasks_to_wait:
+            task_obj = self._find_reference(MidpointObjectTypes.TASK.value, task_id, 'Task')
+            if task_obj is None:
+                continue
+            task_oid = task_obj.get_oid()
+            if task_oid is None:
+                raise AssertionError('Task OID cannot be None')
+            print_info(f'Waiting for task {task_oid} / {task_obj.get_name()}')
+            try:
+                self.client.task_wait(task_oid, create_progress_monitor(), show_changes=not wait_ns.no_changes)
+            except TaskExecutionFailure as e:
+                # Reported now, so a later failure does not hide this one.
+                self._fail()
+                self._print_failed_task(task_oid, e)
+                print_error(e.message)
+
+    def _task_action(self, action: str, parser: ArgumentParser, args: list[str]) -> None:
+        """task run/resume/suspend: apply the action to each task in turn, stopping at the first failure."""
+        action_ns = parser.parse_args(args)
+
+        for task_id in action_ns.task:
+            task_obj = self._find_reference(MidpointObjectTypes.TASK.value, task_id, 'Task')
+            if task_obj is None:
+                continue
+            task_oid = task_obj.get_oid()
+            if task_oid is None:
+                raise AssertionError('Task OID cannot be None')
+            if action == 'run' and task_obj['Execution Status'] == TaskExecutionState.SUSPENDED:
+                print_info('Task currently suspended, activating it...')
+                self.client.task_action(task_oid, 'resume', NopProgressMonitor())
+                print_info('Now running task...')
+
+            print_info(f'Task {task_obj.get_name()} - {action}')
+            # Only a run is followed to completion.
+            monitor = create_progress_monitor() if action == 'run' else NopProgressMonitor()
+
+            try:
+                task_result = self.client.task_action(
+                    task_oid,
+                    action,
+                    monitor,
+                    show_changes=not getattr(action_ns, 'no_changes', False),
+                )
+                # Always display the task result if available
+                if task_result is not None:
+                    get_console().print(task_result.get_full_description())
+            except TaskExecutionFailure as e:
+                self._print_failed_task(task_oid, e)
+                self._fail(e.message)
+                break
+
+    def _print_failed_task(self, task_oid: str, failure: TaskExecutionFailure) -> None:
+        """Show the details and statistics of a failed task, before its error is reported.
+
+        The error and action counts are what tells why a task failed, so they are shown
+        exactly as for a successful run. The task comes with the failure when the client
+        read it while waiting; otherwise it is fetched again.
+        """
+        failed_task = failure.task
+        if failed_task is None:
+            try:
+                failed_task_xml = self.client.api_client.get_element(MidpointObjectTypes.TASK.value, task_oid)
+                failed_task = MidpointTask(safe_fromstring(failed_task_xml), self.client.get_server_version())
+            except Exception:
+                return  # Without the task details, the error is still reported
+        get_console().print(failed_task.get_full_description())
+
+    @staticmethod
+    def help_task() -> None:
+        task_parser.print_help()
+
+    def do_tasks(self, inp: str) -> None:
+        """Shortcut for 'task ls' — list all server tasks."""
+        self._list_shortcut(inp, 'tasks', 'task', self.do_task)
+
+    @staticmethod
+    def help_tasks() -> None:
+        print('List all server tasks. This is a shortcut for "task ls"')
+
+    @staticmethod
+    def _print_tasks_table(tasks: MidpointObjectList) -> None:
+        """Print tasks in the selected output format, coloring the result status."""
+        print_rows(tasks, title='Server Tasks', noun='tasks', cell_style=_task_cell_style)