"""CLI Adapter: bridge declarative Compartment Commands to the operator CLI.
Converts declarative `Command` and `Parameter` definitions into argparse
subcommands and arguments, and provides table-driven action dispatching.
"""
from __future__ import annotations
import argparse
import dataclasses
from typing import Any, Callable, Mapping, MutableMapping, Optional, Sequence
from ..compartment import Command, CommandError
from ..config.parameter import Parameter
from .base import _ask, emit, fail
[docs]def add_parameter_argument(
parser: argparse.ArgumentParser,
param: Parameter[Any],
help_prefix: str = '',
require_flag: bool = False,
) -> None:
"""Register a Parameter on an ArgumentParser.
Uses `cli_name`, `short`, and `positional` if specified, otherwise derives
long option as `--<param.key_with_dashes>`. Skips if `param.cli` is False
or if the flag is already registered on the parser.
"""
if not getattr(param, 'cli', True):
return
# Check already registered option strings
existing_opts = {opt for action in parser._actions for opt in action.option_strings}
existing_dests = {action.dest for action in parser._actions}
doc = f"{help_prefix}{param.description}" if help_prefix else param.description
if getattr(param, 'positional', False):
dest = param.cli_name or param.key
if dest in existing_dests:
return
kwargs: MutableMapping[str, Any] = {'help': doc}
if param.type in (int, float, str):
kwargs['type'] = param.type
if param.choices:
kwargs['choices'] = param.choices
if getattr(param, 'nargs', ''):
kwargs['nargs'] = param.nargs
elif not getattr(param, 'required', False):
kwargs['nargs'] = '?'
parser.add_argument(dest, **kwargs)
return
# Flag option
long_flag = param.cli_name if (param.cli_name and param.cli_name.startswith('--')) else (
'--' + (param.cli_name or param.key.replace('_', '-')).lstrip('-')
)
flags: list[str] = []
if getattr(param, 'short', ''):
short_flag = '-' + param.short.lstrip('-')
if short_flag not in existing_opts:
flags.append(short_flag)
if long_flag in existing_opts:
return
flags.append(long_flag)
dest = param.key
kwargs = {'help': doc, 'dest': dest}
if param.type is bool:
kwargs['action'] = 'store_true'
elif getattr(param, 'nargs', ''):
kwargs['nargs'] = param.nargs
elif param.type in (list, tuple):
kwargs['action'] = 'append'
else:
if param.type in (int, float, str):
kwargs['type'] = param.type
if param.choices:
kwargs['choices'] = param.choices
# Only set default if it's not a factory and not falsy empty
val = param.value() if hasattr(param, 'value') else None
if val is not None and not callable(param.default) and val not in ('', 0, False, [], (), {}):
kwargs['default'] = val
if require_flag and getattr(param, 'required', False) and not getattr(param, 'positional', False):
kwargs['required'] = True
parser.add_argument(*flags, **kwargs)
[docs]@dataclasses.dataclass
class ActionDef:
"""Definition of one action in a multi-action command group."""
name: str
command: Optional[Command] = None
human: Optional[Callable[..., None]] = None
timeout: float = 10.0
handler: Optional[Callable[[argparse.Namespace], int]] = None
arg_map: dict[str, str] = dataclasses.field(default_factory=dict)
parameters: tuple[Parameter[Any], ...] = ()
[docs]class CommandDispatcher:
"""Table-driven multi-action dispatcher and argument builder for CLI subcommands."""
[docs] def __init__(self, subsystem: str, default_action: str = 'status', action_dest: str = 'action') -> None:
self.subsystem = subsystem
self.default_action = default_action
self.action_dest = action_dest
self.actions: dict[str, ActionDef] = {}
[docs] def add_command(
self,
action_name: str,
command: Command,
human: Optional[Callable[..., None]] = None,
timeout: float = 10.0,
arg_map: Optional[Mapping[str, str]] = None,
extra_parameters: Sequence[Parameter[Any]] = (),
) -> ActionDef:
"""Register an action backed directly by a compartment Command."""
all_params = tuple(command.parameters) + tuple(extra_parameters)
act = ActionDef(
name=action_name,
command=command,
human=human,
timeout=timeout,
arg_map=dict(arg_map or {}),
parameters=all_params,
)
self.actions[action_name] = act
return act
[docs] def add_custom(
self,
action_name: str,
handler: Callable[[argparse.Namespace], int],
parameters: Sequence[Parameter[Any]] = (),
) -> ActionDef:
"""Register an action with custom client-side handling logic."""
act = ActionDef(
name=action_name,
handler=handler,
parameters=tuple(parameters),
)
self.actions[action_name] = act
return act
[docs] def register_arguments(
self,
parser: argparse.ArgumentParser,
action_choices: Sequence[str] | None = None,
action_dest: str | None = None,
) -> None:
"""Register the action positional argument and all action parameters."""
choices = tuple(action_choices) if action_choices is not None else tuple(self.actions.keys())
dest = action_dest if action_dest is not None else self.action_dest
parser.add_argument(
dest,
choices=choices,
default=self.default_action,
nargs='?',
)
for act in self.actions.values():
for p in act.parameters:
add_parameter_argument(parser, p)
[docs] def dispatch(self, a: argparse.Namespace) -> int:
"""Execute the requested action from parsed namespace."""
action_name = getattr(a, self.action_dest, None) or getattr(a, 'action', self.default_action) or self.default_action
act = self.actions.get(action_name)
if not act:
fail(f'unknown action {action_name!r}')
if act.handler is not None:
return act.handler(a)
if act.command is None:
fail(f'action {action_name} has no command or handler')
# Gather arguments declared on the Command
raw_args = {}
for p in act.command.parameters:
dest = act.arg_map.get(p.key, p.key)
val = getattr(a, dest, None)
if p.required and (val is None or val == ''):
flag = p.cli_name or ('--' + p.key.replace('_', '-'))
placeholder = ' <name>' if p.key == 'domain' else f' <{p.key}>'
fail(f'{action_name} requires {flag}{placeholder}')
if val is not None:
raw_args[p.key] = val
try:
valid_args = act.command.validate_args(raw_args)
except CommandError as e:
fail(f'{action_name}: {e}')
res = _ask(a.dir, f'{self.subsystem}.{act.command.key}', timeout=act.timeout, **valid_args)
if act.human is not None:
human_fn = act.human
import inspect
try:
sig = inspect.signature(human_fn)
human_cb: Any = (lambda r: human_fn(r, a)) if len(sig.parameters) >= 2 else human_fn
except (ValueError, TypeError):
human_cb = human_fn
else:
human_cb = None
return emit(a, res, human_cb)