webscout 8.2.2__py3-none-any.whl → 2026.1.19__py3-none-any.whl

webscout/swiftcli/core/group.py

@@ -0,0 +1,268 @@
+"""Command group handling for SwiftCLI."""
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from rich.console import Console
+
+from ..utils.formatting import format_error
+from .context import Context
+
+if TYPE_CHECKING:
+    from .cli import CLI
+
+console = Console()
+
+
+class Group:
+    """
+    Command group that can contain subcommands.
+
+    Groups allow organizing related commands together and support command
+    chaining for building command pipelines.
+
+    Attributes:
+        name: Group name
+        help: Group description
+        commands: Registered commands
+        parent: Parent CLI instance
+        chain: Enable command chaining
+        invoke_without_command: Allow invoking group without subcommand
+
+    Example:
+        @app.group()
+        def db():
+            '''Database commands'''
+            pass
+
+        @db.command()
+        def migrate():
+            '''Run database migrations'''
+            print("Running migrations...")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        help: Optional[str] = None,
+        parent: Optional["CLI"] = None,
+        chain: bool = False,
+        invoke_without_command: bool = False,
+    ):
+        """
+        Initialize command group.
+
+        Args:
+            name: Group name
+            help: Group description
+            parent: Parent CLI instance
+            chain: Enable command chaining
+            invoke_without_command: Allow invoking group without subcommand
+        """
+        self.name = name
+        self.help = help
+        self.parent = parent
+        self.chain = chain
+        self.invoke_without_command = invoke_without_command
+        self.commands: Dict[str, Any] = {}
+
+    def command(
+        self,
+        name: Optional[str] = None,
+        help: Optional[str] = None,
+        aliases: Optional[List[str]] = None,
+        hidden: bool = False,
+    ):
+        """
+        Decorator to register a command in this group.
+
+        Args:
+            name: Command name (defaults to function name)
+            help: Command help text
+            aliases: Alternative command names
+            hidden: Hide from help output
+
+        Example:
+            @group.command()
+            def status():
+                '''Show status'''
+                print("Status: OK")
+        """
+
+        def decorator(f):
+            cmd_name = name or f.__name__
+            self.commands[cmd_name] = {
+                "name": cmd_name,
+                "func": f,
+                "help": help or f.__doc__,
+                "aliases": aliases or [],
+                "hidden": hidden,
+            }
+
+            # Register aliases
+            for alias in aliases or []:
+                self.commands[alias] = self.commands[cmd_name]
+
+            return f
+
+        return decorator
+
+    def group(self, name: Optional[str] = None, help: Optional[str] = None, **kwargs):
+        """
+        Create a subgroup within this group.
+
+        Args:
+            name: Subgroup name
+            help: Subgroup help text
+            **kwargs: Additional group options
+
+        Example:
+            @group.group()
+            def config():
+                '''Configuration commands'''
+                pass
+        """
+
+        def decorator(f):
+            subgroup = Group(
+                name=name or f.__name__, help=help or f.__doc__, parent=self.parent, **kwargs
+            )
+            self.commands[subgroup.name] = subgroup
+            return subgroup
+
+        return decorator
+
+    def run(self, args: List[str]) -> int:
+        """
+        Run a command in this group.
+
+        Args:
+            args: Command arguments
+
+        Returns:
+            Exit code (0 for success, non-zero for error)
+        """
+        try:
+            # Show help if no arguments or help requested
+            if not args or args[0] in ["-h", "--help"]:
+                self._print_help()
+                return 0
+
+            command_name = args[0]
+            command_args = args[1:]
+
+            # Check if command exists
+            if command_name not in self.commands:
+                format_error(f"Unknown command: {self.name} {command_name}")
+                self._print_help()
+                return 1
+
+            command = self.commands[command_name]
+
+            # Handle nested groups
+            if isinstance(command, Group):
+                return command.run(command_args)
+
+            # Create command context - parent is a CLI instance, never None at this point
+            # Context expects CLI type, and self.parent should be set when group is created by CLI
+            cli = self.parent
+            ctx = Context(
+                cli,
+                command=f"{self.name} {command_name}",
+                debug=getattr(self.parent, "debug", False) if self.parent else False,
+            )
+
+            # Run command through plugin system
+            if self.parent and not self.parent.plugin_manager.before_command(
+                f"{self.name} {command_name}", command_args
+            ):
+                return 1
+
+            try:
+                import asyncio
+                import inspect
+
+                func = command["func"]
+                params = self._parse_args(command, command_args)
+
+                # Inject context if function was decorated with pass_context
+                if getattr(func, "_pass_context", False):
+                    call_args = (ctx,)
+                else:
+                    call_args = ()
+
+                # If coroutine function, run it using asyncio
+                if inspect.iscoroutinefunction(func):
+                    result = asyncio.run(func(*call_args, **params))
+                else:
+                    result = func(*call_args, **params)
+
+                # If function returned a coroutine-like object
+                if not inspect.iscoroutine(result) and hasattr(result, "__await__"):
+                    result = asyncio.run(result)
+
+                if self.parent:
+                    self.parent.plugin_manager.after_command(
+                        f"{self.name} {command_name}", command_args, result
+                    )
+
+                # Handle command chaining
+                if self.chain and result is not None:
+                    return result if isinstance(result, int) else 0
+
+                return 0
+
+            except Exception as e:
+                if self.parent:
+                    self.parent.plugin_manager.on_error(f"{self.name} {command_name}", e)
+                if getattr(self.parent, "debug", False):
+                    raise
+                format_error(str(e))
+                return 1
+
+        except Exception as e:
+            if getattr(self.parent, "debug", False):
+                raise
+            format_error(str(e))
+            return 1
+
+    def _parse_args(self, command: Dict[str, Any], args: List[str]) -> Dict[str, Any]:
+        """Parse command arguments."""
+        # Use parent CLI's argument parser if available
+        if self.parent:
+            return self.parent._parse_args(command, args)
+
+        # Fallback to basic argument parsing
+        from ..utils.parsing import parse_args
+
+        return parse_args(args)
+
+    def _print_help(self) -> None:
+        """Print group help message."""
+        console.print(f"\n[bold]{self.name}[/] - {self.help or ''}")
+
+        console.print("\n[bold]Commands:[/]")
+        printed = set()
+        for name, cmd in self.commands.items():
+            # cmd can be a Group or a dict mapping
+            if isinstance(cmd, Group):
+                primary = cmd.name
+                if primary in printed:
+                    continue
+                printed.add(primary)
+                console.print(f"  {primary} [group]")
+                if cmd.help:
+                    console.print(f"    {cmd.help}")
+            elif isinstance(cmd, dict):
+                primary = cmd.get("name", name)
+                if primary in printed:
+                    continue
+                printed.add(primary)
+                if not cmd.get("hidden", False):
+                    aliases = cmd.get("aliases", [])
+                    alias_text = f" (aliases: {', '.join(aliases)})" if aliases else ""
+                    console.print(f"  {primary:20} {cmd['help'] or ''}{alias_text}")
+
+        console.print("\nUse -h or --help with any command for more info")
+
+    def __repr__(self) -> str:
+        return f"<Group name={self.name}>"

webscout/swiftcli/decorators/__init__.py

@@ -0,0 +1,28 @@
+"""Decorators for SwiftCLI."""
+
+from .command import argument, command, flag, group, pass_context
+from .options import config_file, envvar, help_option, option, version_option
+from .output import format_output, pager_output, panel_output, progress, table_output
+
+__all__ = [
+    # Command decorators
+    'command',
+    'group',
+    'argument',
+    'flag',
+    'pass_context',
+
+    # Option decorators
+    'option',
+    'envvar',
+    'config_file',
+    'version_option',
+    'help_option',
+
+    # Output decorators
+    'table_output',
+    'progress',
+    'panel_output',
+    'format_output',
+    'pager_output'
+]

webscout/swiftcli/decorators/command.py

@@ -0,0 +1,243 @@
+"""Command decorators for SwiftCLI."""
+
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional
+
+from ..core.context import Context
+
+
+def command(
+    name: Optional[str] = None,
+    help: Optional[str] = None,
+    aliases: Optional[List[str]] = None,
+    hidden: bool = False,
+) -> Callable:
+    """
+    Decorator to register a new command.
+
+    This decorator marks a function as a CLI command and provides metadata
+    about how command should be registered and displayed.
+
+    Args:
+        name: Command name (defaults to function name)
+        help: Help text (defaults to function docstring)
+        aliases: Alternative names for command
+        hidden: Whether to hide from help output
+
+    Example:
+        @command(name="greet", help="Say hello")
+        def hello(name: str):
+            print(f"Hello {name}!")
+
+        @command(aliases=["hi", "hey"])
+        def hello(name: str):
+            '''Say hello to someone'''
+            print(f"Hello {name}!")
+    """
+
+    def decorator(f: Callable) -> Callable:
+        f._command = {  # type: ignore[attr-defined]
+            "name": name or getattr(f, '__name__', 'unknown'),
+            "help": help or f.__doc__,
+            "aliases": aliases or [],
+            "hidden": hidden,
+        }
+        return f
+
+    return decorator
+
+
+def group(
+    name: Optional[str] = None,
+    help: Optional[str] = None,
+    chain: bool = False,
+    invoke_without_command: bool = False,
+) -> Callable:
+    """
+    Decorator to create a command group.
+
+    Command groups can contain subcommands and optionally chain their results.
+
+    Args:
+        name: Group name (defaults to function name)
+        help: Help text (defaults to function docstring)
+        chain: Whether to chain command results
+        invoke_without_command: Allow group to be invoked without subcommand
+
+    Example:
+        @group()
+        def db():
+            '''Database commands'''
+            pass
+
+        @db.command()
+        def migrate():
+            '''Run database migrations'''
+            print("Running migrations...")
+
+        @group(chain=True)
+        def process():
+            '''Process data'''
+            pass
+
+        @process.command()
+        def validate():
+            '''Validate data'''
+            return {"valid": True}
+    """
+
+    def decorator(f: Callable) -> Callable:
+        f._group = {  # type: ignore[attr-defined]
+            "name": name or getattr(f, '__name__', 'unknown'),
+            "help": help or f.__doc__,
+            "chain": chain,
+            "invoke_without_command": invoke_without_command,
+        }
+        return f
+
+    return decorator
+
+
+def pass_context(f: Callable) -> Callable:
+    """
+    Decorator to pass CLI context to command.
+
+    This decorator injects current Context object as first argument
+    to the decorated command function.
+
+    Example:
+        @command()
+        @pass_context
+        def status(ctx):
+            '''Show application status'''
+            print(f"App: {ctx.cli.name}")
+            print(f"Debug: {ctx.debug}")
+    """
+    f._pass_context = True  # type: ignore[attr-defined]
+    return f
+
+
+def completion(func: Optional[Callable] = None) -> Callable:
+    """
+    Decorator to provide shell completion for a command.
+
+    The decorated function should return a list of possible completions
+    based on current incomplete value.
+
+    Example:
+        @command()
+        @option("--service", type=str)
+        def restart(service: str):
+            '''Restart a service'''
+            print(f"Restarting {service}...")
+
+        @restart.completion()
+        def complete_service(ctx, incomplete):
+            services = ["nginx", "apache", "mysql"]
+            return [s for s in services if s.startswith(incomplete)]
+    """
+
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(ctx: Context, incomplete: str) -> List[str]:
+            try:
+                return f(ctx, incomplete)
+            except Exception:
+                return []
+
+        return wrapper
+
+    if func is None:
+        return decorator
+    return decorator(func)
+
+
+def argument(
+    name: str,
+    type: Any = str,
+    required: bool = True,
+    help: Optional[str] = None,
+    default: Any = None,
+    validation: Optional[Dict[str, Any]] = None,
+    mutually_exclusive: Optional[List[str]] = None,
+) -> Callable:
+    """
+    Decorator to add a command argument.
+
+    Arguments are positional parameters that must be provided in order.
+
+    Args:
+        name: Argument name
+        type: Expected type
+        required: Whether argument is required
+        help: Help text
+        default: Default value if not required
+        validation: Dictionary of validation rules (min_length, max_length, pattern, choices, etc.)
+        mutually_exclusive: List of argument names that are mutually exclusive with this argument
+
+    Example:
+        @command()
+        @argument("name", validation={'min_length': 2, 'max_length': 50})
+        @argument("count", type=int, default=1, validation={'min': 1, 'max': 100})
+        def greet(name: str, count: int):
+            '''Greet someone multiple times'''
+            for _ in range(count):
+                print(f"Hello {name}!")
+    """
+
+    def decorator(f: Callable) -> Callable:
+        if not hasattr(f, "_arguments"):
+            f._arguments = []  # type: ignore[attr-defined]
+
+        f._arguments.append(  # type: ignore[attr-defined]
+            {
+                "name": name,
+                "type": type,
+                "required": required,
+                "help": help,
+                "default": default,
+                "validation": validation,
+                "mutually_exclusive": mutually_exclusive,
+            }
+        )
+        return f
+
+    return decorator
+
+
+def flag(name: str, help: Optional[str] = None, hidden: bool = False) -> Callable:
+    """
+    Decorator to add a boolean flag option.
+
+    Flags are special options that don't take a value - they're either
+    present (True) or absent (False).
+
+    Args:
+        name: Flag name
+        help: Help text
+        hidden: Whether to hide from help output
+
+    Example:
+        @command()
+        @flag("--verbose", help="Enable verbose output")
+        def process(verbose: bool):
+            '''Process data'''
+            if verbose:
+                print("Verbose mode enabled")
+    """
+
+    def decorator(f: Callable) -> Callable:
+        if not hasattr(f, "_options"):
+            f._options = []  # type: ignore[attr-defined]
+
+        f._options.append(  # type: ignore[attr-defined]
+            {
+                "param_decls": [name],
+                "is_flag": True,
+                "help": help,
+                "hidden": hidden,
+            }
+        )
+        return f
+
+    return decorator