webscout 8.2.7__py3-none-any.whl → 8.2.9__py3-none-any.whl

webscout/swiftcli/core/cli.py

@@ -0,0 +1,297 @@
+"""Main CLI application class."""
+
+import sys
+from typing import Any, Dict, List, Optional, Union
+
+from rich.console import Console
+
+from ..exceptions import UsageError
+from ..plugins.manager import PluginManager
+from ..utils.formatting import format_error, format_success
+from .context import Context
+
+console = Console()
+
+class CLI:
+    """
+    Main CLI application class.
+    
+    The CLI class is the core of SwiftCLI. It handles command registration,
+    argument parsing, and command execution. It also manages plugins and
+    provides the main entry point for CLI applications.
+    
+    Attributes:
+        name: Application name
+        help: Application description
+        version: Application version
+        debug: Debug mode flag
+        commands: Registered commands
+        groups: Command groups
+        plugin_manager: Plugin manager instance
+        
+    Example:
+        >>> app = CLI(name="myapp", version="1.0.0")
+        >>> @app.command()
+        ... def greet(name: str):
+        ...     '''Greet someone'''
+        ...     print(f"Hello {name}!")
+        >>> app.run()
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        help: Optional[str] = None,
+        version: Optional[str] = None,
+        debug: bool = False
+    ):
+        """
+        Initialize CLI application.
+        
+        Args:
+            name: Application name
+            help: Application description
+            version: Application version
+            debug: Enable debug mode
+        """
+        self.name = name
+        self.help = help
+        self.version = version
+        self.debug = debug
+        
+        self.commands: Dict[str, Dict[str, Any]] = {}
+        self.groups: Dict[str, 'Group'] = {}  # type: ignore
+        self.plugin_manager = PluginManager()
+        
+        # Initialize plugin manager with this CLI instance
+        self.plugin_manager.init_plugins(self)
+    
+    def command(
+        self,
+        name: Optional[str] = None,
+        help: Optional[str] = None,
+        aliases: Optional[List[str]] = None,
+        hidden: bool = False
+    ):
+        """
+        Decorator to register a command.
+        
+        Args:
+            name: Command name (defaults to function name)
+            help: Command help text
+            aliases: Alternative command names
+            hidden: Hide from help output
+            
+        Example:
+            @app.command()
+            def hello(name: str):
+                '''Say hello'''
+                print(f"Hello {name}!")
+        """
+        def decorator(f):
+            cmd_name = name or f.__name__
+            self.commands[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 command group.
+        
+        Args:
+            name: Group name
+            help: Group help text
+            **kwargs: Additional group options
+            
+        Example:
+            @app.group()
+            def db():
+                '''Database commands'''
+                pass
+                
+            @db.command()
+            def migrate():
+                '''Run migrations'''
+                pass
+        """
+        from .group import Group  # Import here to avoid circular dependency
+        
+        def decorator(f):
+            group_name = name or f.__name__
+            group = Group(
+                name=group_name,
+                help=help or f.__doc__,
+                parent=self,
+                **kwargs
+            )
+            self.groups[group_name] = group
+            return group
+        return decorator
+    
+    def run(self, args: Optional[List[str]] = None) -> int:
+        """
+        Run the CLI application.
+        
+        Args:
+            args: Command line arguments (defaults to sys.argv[1:])
+            
+        Returns:
+            Exit code (0 for success, non-zero for error)
+        """
+        try:
+            args = args or sys.argv[1:]
+            
+            # Show help if no arguments
+            if not args or args[0] in ['-h', '--help']:
+                self._print_help()
+                return 0
+            
+            # Show version if requested
+            if args[0] in ['-v', '--version'] and self.version:
+                console.print(self.version)
+                return 0
+            
+            command_name = args[0]
+            command_args = args[1:]
+            
+            # Check if it's a group command
+            if command_name in self.groups:
+                return self.groups[command_name].run(command_args)
+            
+            # Check if it's a regular command
+            if command_name not in self.commands:
+                format_error(f"Unknown command: {command_name}")
+                self._print_help()
+                return 1
+            
+            # Create command context
+            ctx = Context(self, command=command_name, debug=self.debug)
+            
+            # Run command through plugin system
+            if not self.plugin_manager.before_command(command_name, command_args):
+                return 1
+            
+            try:
+                command = self.commands[command_name]
+                result = command['func'](**self._parse_args(command, command_args))
+                self.plugin_manager.after_command(command_name, command_args, result)
+                return 0
+            except Exception as e:
+                self.plugin_manager.on_error(command_name, e)
+                if self.debug:
+                    raise
+                format_error(str(e))
+                return 1
+            
+        except KeyboardInterrupt:
+            console.print("\nOperation cancelled by user")
+            return 130
+        except Exception as e:
+            if self.debug:
+                raise
+            format_error(str(e))
+            return 1
+    
+    def _parse_args(self, command: Dict[str, Any], args: List[str]) -> Dict[str, Any]:
+        """Parse command arguments."""
+        from ..utils.parsing import (
+            parse_args, validate_required, convert_type,
+            validate_choice, get_env_var
+        )
+        
+        params = {}
+        func = command['func']
+        
+        # Parse command-line arguments
+        parsed_args = parse_args(args)
+        
+        # Handle options
+        if hasattr(func, '_options'):
+            for opt in func._options:
+                name = opt['param_decls'][0].lstrip('-').replace('-', '_')
+                if name in parsed_args:
+                    value = parsed_args[name]
+                    if 'type' in opt:
+                        value = convert_type(value, opt['type'], name)
+                    if 'choices' in opt and opt['choices']:
+                        validate_choice(
+                            value,
+                            opt['choices'],
+                            name,
+                            opt.get('case_sensitive', True)
+                        )
+                    params[name] = value
+                elif opt.get('required', False):
+                    raise UsageError(f"Missing required option: {name}")
+                elif 'default' in opt:
+                    params[name] = opt['default']
+        
+        # Handle arguments
+        if hasattr(func, '_arguments'):
+            for i, arg in enumerate(func._arguments):
+                name = arg['name']
+                if f'arg{i}' in parsed_args:
+                    value = parsed_args[f'arg{i}']
+                    if 'type' in arg:
+                        value = convert_type(value, arg['type'], name)
+                    params[name] = value
+                elif arg.get('required', True):
+                    raise UsageError(f"Missing required argument: {name}")
+                elif 'default' in arg:
+                    params[name] = arg['default']
+        
+        # Handle environment variables
+        if hasattr(func, '_envvars'):
+            for env in func._envvars:
+                name = env['name'].lower()
+                value = get_env_var(
+                    env['name'],
+                    env.get('type', str),
+                    env.get('required', False),
+                    env.get('default')
+                )
+                if value is not None:
+                    params[name] = value
+        
+        return params
+    
+    def _print_help(self) -> None:
+        """Print application help message."""
+        console.print(f"\n[bold]{self.name}[/]")
+        if self.help:
+            console.print(f"\n{self.help}")
+        
+        # Show commands
+        console.print("\n[bold]Commands:[/]")
+        for name, cmd in self.commands.items():
+            if not cmd.get('hidden', False):
+                console.print(f"  {name:20} {cmd['help'] or ''}")
+        
+        # Show command groups
+        for name, group in self.groups.items():
+            console.print(f"\n[bold]{name} commands:[/]")
+            for cmd_name, cmd in group.commands.items():
+                if not cmd.get('hidden', False):
+                    console.print(f"  {cmd_name:20} {cmd['help'] or ''}")
+        
+        console.print("\nUse -h or --help with any command for more info")
+        if self.version:
+            console.print("Use -v or --version to show version")
+    
+    def __repr__(self) -> str:
+        return f"<CLI name={self.name}>"

webscout/swiftcli/core/context.py

@@ -0,0 +1,104 @@
+"""Context handling for SwiftCLI."""
+
+from typing import Any, Dict, Optional
+
+class Context:
+    """
+    Context object that holds state for the CLI app.
+    
+    The Context class provides access to the CLI application instance and maintains
+    state throughout command execution. It can be used to pass data between
+    commands and access global configuration.
+
+    Attributes:
+        cli: The CLI application instance.
+        parent: The parent context if this is a subcommand.
+        command: The current command name.
+        obj: An object that can be used to store arbitrary data.
+        params: Dictionary of current command parameters.
+        debug: Debug mode flag.
+        
+    Example:
+        @app.command()
+        @pass_context
+        def status(ctx):
+            '''Show application status'''
+            print(f"App: {ctx.cli.name}")
+            print(f"Debug: {ctx.debug}")
+    """
+    
+    def __init__(
+        self,
+        cli: 'CLI',  # type: ignore
+        parent: Optional['Context'] = None,
+        command: Optional[str] = None,
+        obj: Any = None,
+        debug: bool = False
+    ):
+        self.cli = cli
+        self.parent = parent
+        self.command = command
+        self.obj = obj
+        self.params: Dict[str, Any] = {}
+        self.debug = debug
+    
+    def get_parameter(self, name: str, default: Any = None) -> Any:
+        """
+        Get a parameter value from the context.
+        
+        Args:
+            name: Parameter name
+            default: Default value if parameter not found
+            
+        Returns:
+            Parameter value or default
+        """
+        return self.params.get(name, default)
+    
+    def set_parameter(self, name: str, value: Any) -> None:
+        """
+        Set a parameter value in the context.
+        
+        Args:
+            name: Parameter name
+            value: Parameter value
+        """
+        self.params[name] = value
+    
+    def get_parent_context(self) -> Optional['Context']:
+        """Get the parent context if it exists."""
+        return self.parent
+    
+    def create_child_context(
+        self,
+        command: Optional[str] = None,
+        obj: Any = None
+    ) -> 'Context':
+        """
+        Create a new child context.
+        
+        Args:
+            command: Command name for the child context
+            obj: Object to store in child context
+            
+        Returns:
+            New child context
+        """
+        return Context(
+            cli=self.cli,
+            parent=self,
+            command=command,
+            obj=obj,
+            debug=self.debug
+        )
+    
+    @property
+    def root_context(self) -> 'Context':
+        """Get the root context by traversing up the parent chain."""
+        ctx = self
+        while ctx.parent is not None:
+            ctx = ctx.parent
+        return ctx
+    
+    def __repr__(self) -> str:
+        return f"<Context command={self.command}>"

webscout/swiftcli/core/group.py

@@ -0,0 +1,241 @@
+"""Command group handling for SwiftCLI."""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from rich.console import Console
+
+from ..exceptions import UsageError
+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, 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] = {
+                '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
+            ctx = Context(
+                self.parent,
+                command=f"{self.name} {command_name}",
+                debug=getattr(self.parent, 'debug', 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:
+                result = command['func'](**self._parse_args(command, command_args))
+                
+                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
+                
+                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:[/]")
+        for name, cmd in self.commands.items():
+            if isinstance(cmd, Group):
+                console.print(f"  {name} [group]")
+                if cmd.help:
+                    console.print(f"    {cmd.help}")
+            elif not cmd.get('hidden', False):
+                console.print(f"  {name:20} {cmd['help'] or ''}")
+        
+        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 command, group, argument, flag, pass_context
+from .options import option, envvar, config_file, version_option, help_option
+from .output import table_output, progress, panel_output, format_output, pager_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'
+]