midpoint-cli 1.6.0.dev3__py3-none-any.whl

midpoint_cli/prompt/resource.py

@@ -0,0 +1,217 @@
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+from midpoint_cli.client import SHADOW_SITUATIONS, MidpointObjectList, MidpointObjectTypes, MidpointServerError
+from midpoint_cli.client.constants import ResultStatus
+from midpoint_cli.client.task_definitions import SHADOW_KINDS
+from midpoint_cli.prompt.base import PromptBase, add_listing_arguments, add_new_task_arguments
+from midpoint_cli.prompt.complete import RESOURCE, completes
+from midpoint_cli.prompt.console import print_error, print_info, print_rows, print_success, print_warning
+
+resource_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='resource',
+    description='Manage resources.',
+    epilog="""
+Available commands:
+  ls     List all server resources. Exits with status 1 when any resource
+         has a known availability status other than 'up'. With --metrics,
+         also count the shadows of each resource by synchronization situation.
+  test   Test a resource.
+  import Import objects from a resource (creates and runs an import task).
+  reconcile Reconcile a resource (creates and runs a reconciliation task).
+""",
+)
+resource_parser.add_argument('command', help='Resource command to execute.')
+resource_parser.add_argument('arg', help='Optional command arguments.', nargs='*')
+
+resource_ls_parser = add_listing_arguments(
+    ArgumentParser(
+        formatter_class=RawTextHelpFormatter,
+        prog='resource ls',
+        description='List server resources. Exits with status 1 when any listed resource\n'
+        "has a known availability status other than 'up'.",
+    ),
+    'resources',
+)
+resource_ls_parser.add_argument(
+    '--metrics',
+    action='store_true',
+    help='Also count the shadows of each resource by synchronization situation.\n'
+    'Midpoint 4.10+ counts on the server (6 small searches per resource); earlier\n'
+    'versions download every shadow of the resource, which is slow on large ones.',
+)
+
+# Shadow count columns of resource ls --metrics: (count key, column header).
+METRIC_COLUMNS = (
+    *((situation, situation.capitalize()) for situation in SHADOW_SITUATIONS),
+    ('none', 'No Situation'),
+    ('total', 'Shadows'),
+)
+
+# resource RUN parser
+
+resource_test_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='resource test',
+    description='Test a resource status.',
+)
+completes(resource_test_parser.add_argument('resource', help='Resource to be tested.', nargs='+'), RESOURCE)
+
+
+def _resource_task_parser(operation: str, description: str) -> ArgumentParser:
+    parser = ArgumentParser(
+        formatter_class=RawTextHelpFormatter,
+        prog=f'resource {operation}',
+        description=description,
+        epilog='Objects are selected by kind and intent, by object class, or both. Without --kind and\n'
+        '--object-class, the accounts of the resource are processed. The task is created like the\n'
+        'Midpoint GUI creates it and stays on the server, so `task run` can run it again.',
+    )
+    completes(parser.add_argument('resource', help='Resource OID or name.'), RESOURCE)
+    parser.add_argument('--kind', choices=SHADOW_KINDS, help='Kind of the resource objects (default: account).')
+    parser.add_argument('--intent', help='Intent of the resource objects (default: the default intent of the kind).')
+    parser.add_argument(
+        '--object-class',
+        metavar='NAME',
+        help='Object class of the resource objects, e.g. AccountObjectClass or inetOrgPerson.',
+    )
+    return add_new_task_arguments(parser)
+
+
+resource_import_parser = _resource_task_parser(
+    'import', 'Import objects from a resource: create an import task and run it.'
+)
+resource_reconcile_parser = _resource_task_parser(
+    'reconcile', 'Reconcile a resource: create a reconciliation task and run it.'
+)
+
+# Each subcommand with its parser; None for those taking no arguments.
+resource_subparsers: dict[str, ArgumentParser | None] = {
+    'ls': resource_ls_parser,
+    'test': resource_test_parser,
+    'import': resource_import_parser,
+    'reconcile': resource_reconcile_parser,
+}
+
+
+def _status_style(column: str, value: str) -> str | None:
+    if 'status' in column.lower():
+        return {'up': 'green', 'down': 'red'}.get(value.lower())
+    return None
+
+
+class ResourceClientPrompt(PromptBase):
+    subparsers_resource = resource_subparsers
+
+    def do_resource(self, inp: str) -> None:
+        """Manage server resources (subcommands: ls, test, import, reconcile)."""
+        self._dispatch_subcommand(
+            inp,
+            resource_parser,
+            resource_subparsers,
+            {
+                'ls': self._resource_ls,
+                'test': self._resource_test,
+                'import': lambda args: self._start_resource_task('import', args),
+                'reconcile': lambda args: self._start_resource_task('reconcile', args),
+            },
+        )
+
+    def _resource_ls(self, args: list[str]) -> None:
+        ls_ns = resource_ls_parser.parse_args(args)
+        resources = self.client.get_resources(limit=ls_ns.limit, name_filter=ls_ns.filter)
+        connectors = self.client.get_connectors()
+
+        connectors_by_oid = {c['OID']: c for c in connectors}
+
+        for resource in resources:
+            connector = connectors_by_oid.get(resource['connectorRef'])
+
+            if connector is not None:
+                connector_type = connector['Connector type']
+                connector_version = connector['Version']
+            elif resource['connectorRef']:
+                # connectorRef points at a connector the server did not return:
+                # a dangling reference, or one hidden by authorizations.
+                connector_type = '(unknown)'
+                connector_version = ''
+            else:
+                # No connectorRef at all, e.g. an abstract resource template.
+                connector_type = ''
+                connector_version = ''
+
+            # Applied on every path: _print_resources_table takes its columns
+            # from resources[0] alone, so a row with different keys would be
+            # rendered under the wrong headers.
+            del resource['connectorRef']
+            resource['Connector Type'] = connector_type
+            resource['Version'] = connector_version
+
+        if ls_ns.metrics:
+            self._add_shadow_metrics(resources)
+
+        self._print_resources_table(resources)
+
+        s = {r['Availability Status'] for r in resources if r['Availability Status']}
+        self.error_code = 1 if s - {'up'} else 0
+
+    def _resource_test(self, args: list[str]) -> None:
+        run_ns = resource_test_parser.parse_args(args)
+
+        for resource_id in run_ns.resource:
+            print_info(f'Testing resource {resource_id}...')
+            resource_obj = self._find_reference(MidpointObjectTypes.RESOURCE.value, resource_id, 'Resource')
+
+            if resource_obj is not None:
+                resource_oid = resource_obj.get_oid()
+                if resource_oid is None:
+                    raise AssertionError('Resource OID cannot be None')
+                status = self.client.test_resource(resource_oid)
+                if status == ResultStatus.SUCCESS:
+                    print_success(f'Test status: {status}')
+                else:
+                    self._fail()
+                    print_error(f'Test status: {status}')
+
+    def _start_resource_task(self, operation: str, args: list[str]) -> None:
+        """resource import/reconcile: create the task for the resource, then follow it."""
+        parser = resource_import_parser if operation == 'import' else resource_reconcile_parser
+        task_ns = parser.parse_args(args)
+        kind = task_ns.kind or (None if task_ns.object_class else 'account')
+        resource_obj = self._require_object(MidpointObjectTypes.RESOURCE.value, task_ns.resource, 'Resource')
+        if resource_obj is None:
+            return
+        try:
+            task_oid, task_name = self.client.start_resource_task(
+                operation, resource_obj, kind=kind, intent=task_ns.intent, object_class=task_ns.object_class
+            )
+        except ValueError as e:
+            self._fail(str(e))
+            return
+        self._follow_new_task(task_oid, task_name, task_ns.no_wait, show_changes=not task_ns.no_changes)
+
+    def help_resource(self) -> None:
+        resource_parser.print_help()
+
+    def do_resources(self, inp: str) -> None:
+        """Shortcut for 'resource ls' — list all server resources."""
+        self._list_shortcut(inp, 'resources', 'resource', self.do_resource)
+
+    def help_resources(self) -> None:
+        print('List all server resources. This is a shortcut for "resource ls"')
+
+    def _add_shadow_metrics(self, resources: MidpointObjectList) -> None:
+        """Add the shadow count columns to each resource; one whose shadows cannot be counted gets empty cells."""
+        for resource in resources:
+            try:
+                counts: dict[str, int] | None = self.client.get_resource_shadow_counts(resource['OID'])
+            except MidpointServerError as e:
+                print_warning(f'Cannot count the shadows of resource {resource["Name"]}: {e}')
+                counts = None
+            for key, header in METRIC_COLUMNS:
+                resource[header] = str(counts[key]) if counts is not None else ''
+
+    @staticmethod
+    def _print_resources_table(resources: MidpointObjectList) -> None:
+        """Print resources in the selected output format, coloring the availability status."""
+        print_rows(resources, title='Server Resources', noun='resources', cell_style=_status_style)

midpoint_cli/prompt/role.py

@@ -0,0 +1,96 @@
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+from midpoint_cli.client import MidpointObjectList, MidpointObjectTypes
+from midpoint_cli.prompt.base import PromptBase, add_listing_arguments, print_object_detail
+from midpoint_cli.prompt.complete import ROLE, completes
+from midpoint_cli.prompt.console import print_rows
+
+role_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='role',
+    description='Manage server roles.',
+    epilog="""
+Available commands:
+  ls       List all roles.
+  search   Search for a role.
+  get      Get role details by OID or name.
+""",
+)
+role_parser.add_argument('command', help='Role command to execute.')
+role_parser.add_argument('arg', help='Optional command arguments.', nargs='*')
+
+role_ls_parser = add_listing_arguments(
+    ArgumentParser(
+        formatter_class=RawTextHelpFormatter,
+        prog='role ls',
+        description='List roles.',
+    ),
+    'roles',
+)
+
+role_search = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='role search',
+    description='Search for roles by substring of their name or display name, ignoring case.\n'
+    'Terms are combined with OR. Prefix a term with + to make it mandatory (AND).',
+)
+role_search.add_argument(
+    'searchquery',
+    help='String fragments to search for. Use +term to require a match (AND); plain terms are optional (OR).',
+    nargs='+',
+)
+
+role_get_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='role get',
+    description='Get role details by OID or name.',
+)
+completes(role_get_parser.add_argument('oid', help='A role OID or name.'), ROLE)
+
+# Each subcommand with its parser; None for those taking no arguments.
+role_subparsers: dict[str, ArgumentParser | None] = {
+    'ls': role_ls_parser,
+    'search': role_search,
+    'get': role_get_parser,
+}
+
+
+class RoleClientPrompt(PromptBase):
+    subparsers_role = role_subparsers
+
+    def do_role(self, inp: str) -> None:
+        """Manage roles (subcommands: ls, search, get)."""
+        self._dispatch_subcommand(
+            inp,
+            role_parser,
+            role_subparsers,
+            {'ls': self._role_ls, 'search': self._role_search, 'get': self._role_get},
+        )
+
+    def _role_ls(self, args: list[str]) -> None:
+        ls_ns = role_ls_parser.parse_args(args)
+        self._print_roles_table(self.client.get_roles(limit=ls_ns.limit, name_filter=ls_ns.filter))
+
+    def _role_search(self, args: list[str]) -> None:
+        search_ns = role_search.parse_args(args)
+        self._print_roles_table(self.client.search_roles(search_ns.searchquery))
+
+    def _role_get(self, args: list[str]) -> None:
+        get_ns = role_get_parser.parse_args(args)
+        oid = self.client.resolve_oid(MidpointObjectTypes.ROLE.value, get_ns.oid)
+        print_object_detail(self.client.get_role(oid), 'Role Details')
+
+    def help_role(self) -> None:
+        role_parser.print_help()
+
+    def do_roles(self, inp: str) -> None:
+        """Shortcut for 'role ls' — list all roles."""
+        self._list_shortcut(inp, 'roles', 'role', self.do_role)
+
+    def help_roles(self) -> None:
+        print('List all server roles. This is a shortcut for "role ls"')
+
+    @staticmethod
+    def _print_roles_table(roles: MidpointObjectList) -> None:
+        """Print roles in the selected output format."""
+        print_rows(roles, title='Roles', noun='roles')

midpoint_cli/prompt/script.py

@@ -0,0 +1,154 @@
+import shlex
+import sys
+import traceback
+import unittest
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+# Run command wrapper parser
+from midpoint_cli.prompt.base import PromptBase
+from midpoint_cli.prompt.complete import FILE, completes
+
+STDIN_SCRIPT_NAME = '<stdin>'
+
+script_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='script',
+    description='Run client Python scripts.',
+    epilog="""
+Available commands:
+  run      Run a local client script.
+""",
+)
+script_parser.add_argument('command', help='Script command to execute.')
+script_parser.add_argument('arg', help='Optional command arguments.', nargs='*')
+
+# Script RUN parser
+
+script_run_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='script run',
+    description="""Run script. In the script execution environment, the following variables are defined:
+ - tc       A TestCase instance that can be used to write assertions
+ - client   The MidpointClient instance object
+
+A failed assertion is reported with its location and exits 1. Any other
+exception is reported as a traceback covering the script's own frames. A script
+may also call sys.exit() to choose its own exit code.
+
+Script files are executed as-is with the authenticated client in scope, so only
+run scripts you trust.
+""",
+)
+completes(
+    script_run_parser.add_argument(
+        'script', help='A file name containing the script, or "-" to read script from stdin.'
+    ),
+    FILE,
+)
+
+script_subparsers: dict[str, ArgumentParser | None] = {'run': script_run_parser}
+
+
+class ScriptClientPrompt(PromptBase):
+    subparsers_script = script_subparsers
+
+    def do_script(self, inp: str) -> None:
+        """Execute a local Python client script (subcommand: run)."""
+        # An argparse SystemExit here propagates to onecmd; the script's own
+        # sys.exit() is handled separately in _run_script.
+        script_args = shlex.split(inp)
+        if self._subcommand_help(script_args, script_subparsers):
+            return
+        ns = script_parser.parse_args(script_args)
+
+        if ns.command != 'run':
+            self._fail(f'Unknown command {ns.command}')
+            return
+
+        run_ns = script_run_parser.parse_args(script_args[1:])
+
+        if run_ns.script == '-':
+            name = STDIN_SCRIPT_NAME
+            code = sys.stdin.read()
+        else:
+            name = run_ns.script
+            try:
+                with open(name) as f:
+                    code = f.read()
+            except OSError as e:
+                self._fail(f'Cannot read {name}: {e.strerror or e}')
+                return
+
+        self._run_script(code, name)
+
+    def _run_script(self, code: str, name: str) -> None:
+        """Run a client script, reporting its failures instead of our own stack.
+
+        The script is compiled under its real filename so its frames carry a
+        usable location: exec() on a raw string labels them ``<string>``, which
+        linecache then resolves against whatever else occupies that line — for a
+        console-script entry point, the launcher's own source — so the traceback
+        used to quote a line the user never wrote.
+        """
+        try:
+            compiled = compile(code, name, 'exec')
+        except SyntaxError as e:
+            self.error_code = 1
+            location = f'{name}:{e.lineno}' if e.lineno else name
+            self.error_message = f'{location}: invalid Python syntax ({e.msg})'
+            return
+
+        try:
+            # One namespace, not separate globals/locals: with two dicts the body
+            # behaves like a class body, so a top-level def lands in locals while
+            # calls from inside other functions resolve against globals and miss it.
+            # Any script whose helpers called each other raised NameError.
+            # S102: executing the user's own script file is the purpose of this command.
+            exec(compiled, {'client': self.client, 'tc': unittest.TestCase()})  # noqa: S102
+        except AssertionError as e:
+            # The documented purpose of `tc`: an expected failure, so report it
+            # the way a test runner would rather than as a crash.
+            self.error_code = 1
+            detail = str(e) or 'no message'
+            self.error_message = f'Assertion failed at {self._deepest_script_location(e, name)}: {detail}'
+        except SystemExit as e:
+            self._apply_script_exit(e.code)
+        except Exception as e:
+            # Arbitrary user code: a traceback is the useful answer, but only over
+            # the script's own frames. error_message is left unset so the single
+            # traceback below is the whole report.
+            self.error_code = 1
+            sys.stderr.write(self._script_traceback(e, name))
+
+    def _apply_script_exit(self, code: object) -> None:
+        """Honour a sys.exit() from the script; it used to be swallowed as argparse's."""
+        if code is None:
+            self.error_code = 0
+        elif isinstance(code, bool):
+            self.error_code = int(code)
+        elif isinstance(code, int):
+            self.error_code = code
+        else:
+            self._fail(str(code))
+
+    @staticmethod
+    def _deepest_script_location(exc: BaseException, name: str) -> str:
+        """Locate the failure in the script itself, past any library frames."""
+        lineno = None
+        tb = exc.__traceback__
+        while tb is not None:
+            if tb.tb_frame.f_code.co_filename == name:
+                lineno = tb.tb_lineno
+            tb = tb.tb_next
+        return f'{name}:{lineno}' if lineno is not None else name
+
+    @staticmethod
+    def _script_traceback(exc: BaseException, name: str) -> str:
+        """Format the traceback from the script's first frame, hiding our own."""
+        tb = exc.__traceback__
+        while tb is not None and tb.tb_frame.f_code.co_filename != name:
+            tb = tb.tb_next
+        return ''.join(traceback.format_exception(type(exc), exc, tb or exc.__traceback__))
+
+    def help_script(self) -> None:
+        script_parser.print_help()

midpoint_cli/prompt/search.py

@@ -0,0 +1,51 @@
+import shlex
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+from midpoint_cli.client import MidpointObjectTypes, MidpointServerError
+from midpoint_cli.client.objects import MidpointTypeNotFound
+from midpoint_cli.prompt.base import PromptBase, _positive_int
+from midpoint_cli.prompt.complete import OBJECT_TYPE, completes
+from midpoint_cli.prompt.console import print_rows
+
+search_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='search',
+    description='Search server objects of any type with a Midpoint Query Language filter.',
+    epilog="""The filter is evaluated by the server, e.g.:
+  search user --filter 'activation/administrativeStatus = "disabled"'
+  search role --filter 'name startsWith "App"' --limit 10
+  search shadow --raw --filter 'resourceRef matches (oid = "<resource OID>") and kind = "account"'
+Without --filter, every object of the type is listed. Results are sorted by name.""",
+)
+completes(search_parser.add_argument('objectclass', help='Type of the objects to search (Java Type).'), OBJECT_TYPE)
+search_parser.add_argument('--filter', metavar='QUERY', help='Midpoint Query Language (Axiom) filter.')
+search_parser.add_argument(
+    '--limit', type=_positive_int, metavar='N', help='List at most N objects (paged on the server).'
+)
+search_parser.add_argument(
+    '--raw',
+    action='store_true',
+    help='Search the repository only, without contacting resources (needed to search shadows\n'
+    'by resource without an object class).',
+)
+
+
+class SearchClientPrompt(PromptBase):
+    parser_search = search_parser
+
+    def do_search(self, inp: str) -> None:
+        """Search server objects of any type with a Midpoint Query Language filter."""
+        try:
+            ns = search_parser.parse_args(shlex.split(inp))
+            object_type = MidpointObjectTypes.find_by_name(ns.objectclass)
+            if object_type.endpoint is None:
+                self._fail(f'{ns.objectclass} cannot be searched through the REST API')
+                return
+            objects = self.client.search_text(object_type, ns.filter, limit=ns.limit, raw=ns.raw)
+            print_rows(objects, title=f'{object_type.object_type} objects', noun='objects')
+        except (MidpointTypeNotFound, MidpointServerError) as e:
+            self._fail(str(e))
+
+    @staticmethod
+    def help_search() -> None:
+        search_parser.print_help()

midpoint_cli/prompt/shadow.py

@@ -0,0 +1,87 @@
+from argparse import ArgumentParser, RawTextHelpFormatter
+
+from midpoint_cli.client import MidpointObjectList, MidpointObjectTypes
+from midpoint_cli.client.task_definitions import SHADOW_KINDS
+from midpoint_cli.prompt.base import PromptBase, add_listing_arguments
+from midpoint_cli.prompt.complete import RESOURCE, completes
+from midpoint_cli.prompt.console import print_rows
+
+shadow_parser = ArgumentParser(
+    formatter_class=RawTextHelpFormatter,
+    prog='shadow',
+    description='Inspect shadows, the copies of resource objects Midpoint keeps in its repository.',
+    epilog="""
+Available commands:
+  ls     List shadows, optionally of one resource, kind and intent.
+""",
+)
+shadow_parser.add_argument('command', help='Shadow command to execute.')
+shadow_parser.add_argument('arg', help='Optional command arguments.', nargs='*')
+
+shadow_ls_parser = add_listing_arguments(
+    ArgumentParser(
+        formatter_class=RawTextHelpFormatter,
+        prog='shadow ls',
+        description='List the shadows of the repository, sorted by name.\n'
+        'The repository is searched without contacting the resources, so the list shows what\n'
+        'Midpoint last saw: run `resource import` or `resource reconcile` to refresh it.',
+    ),
+    'shadows',
+)
+completes(
+    shadow_ls_parser.add_argument('--resource', help='Only list shadows of this resource (OID or name).'), RESOURCE
+)
+shadow_ls_parser.add_argument('--kind', choices=SHADOW_KINDS, help='Only list shadows of this kind.')
+shadow_ls_parser.add_argument('--intent', help='Only list shadows of this intent.')
+
+# Each subcommand with its parser; None for those taking no arguments.
+shadow_subparsers: dict[str, ArgumentParser | None] = {'ls': shadow_ls_parser}
+
+SHADOW_COLUMNS = ('OID', 'Name', 'Resource', 'Kind', 'Intent', 'Situation', 'Dead')
+
+
+class ShadowClientPrompt(PromptBase):
+    subparsers_shadow = shadow_subparsers
+
+    def do_shadow(self, inp: str) -> None:
+        """Inspect resource object shadows (subcommand: ls)."""
+        self._dispatch_subcommand(inp, shadow_parser, shadow_subparsers, {'ls': self._shadow_ls})
+
+    def _shadow_ls(self, args: list[str]) -> None:
+        ls_ns = shadow_ls_parser.parse_args(args)
+        resource_names: dict[str, str] = {}
+        resource_oid = None
+        if ls_ns.resource is not None:
+            resource = self._require_object(MidpointObjectTypes.RESOURCE.value, ls_ns.resource, 'Resource')
+            if resource is None:
+                return
+            resource_oid = resource.get_oid()
+            resource_names[str(resource_oid)] = resource.get_name() or str(resource_oid)
+        shadows = self.client.get_shadows(
+            resource_oid=resource_oid,
+            kind=ls_ns.kind,
+            intent=ls_ns.intent,
+            limit=ls_ns.limit,
+            name_filter=ls_ns.filter,
+        )
+        self._print_shadows(shadows, resource_names)
+
+    def _print_shadows(self, shadows: MidpointObjectList, resource_names: dict[str, str]) -> None:
+        """Print shadows with the name of their resource, looked up in one search when not known yet."""
+        unknown = sorted({str(s['ResourceOID']) for s in shadows if s.get('ResourceOID')} - set(resource_names))
+        if unknown:
+            for resource in self.client.get_objects_by_oid(MidpointObjectTypes.RESOURCE.value, unknown):
+                oid = resource.get_oid()
+                if oid is not None:
+                    resource_names[oid] = resource.get_name() or oid
+        rows = []
+        for shadow in shadows:
+            row = {column: shadow.get(column) for column in SHADOW_COLUMNS}
+            resource_oid = shadow.get('ResourceOID')
+            row['Resource'] = resource_names.get(str(resource_oid), resource_oid) if resource_oid else ''
+            rows.append(row)
+        print_rows(rows, title='Shadows', noun='shadows', columns=SHADOW_COLUMNS)
+
+    @staticmethod
+    def help_shadow() -> None:
+        shadow_parser.print_help()