webscout 8.2.5__py3-none-any.whl → 8.2.6__py3-none-any.whl

webscout/swiftcli/decorators/command.py

@@ -0,0 +1,221 @@
+"""Command decorators for SwiftCLI."""
+
+from functools import wraps
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from ..core.context import Context
+
+def command(
+    name: str = None,
+    help: str = None,
+    aliases: 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 the 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 the 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 = {
+            'name': name or f.__name__,
+            'help': help or f.__doc__,
+            'aliases': aliases or [],
+            'hidden': hidden
+        }
+        return f
+    return decorator
+
+def group(
+    name: str = None,
+    help: 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 = {
+            'name': name or f.__name__,
+            '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 the current Context object as the 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
+    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 the 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: str = None,
+    default: Any = 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
+        
+    Example:
+        @command()
+        @argument("name")
+        @argument("count", type=int, default=1)
+        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 = []
+        
+        f._arguments.append({
+            'name': name,
+            'type': type,
+            'required': required,
+            'help': help,
+            'default': default
+        })
+        return f
+    return decorator
+
+def flag(
+    name: str,
+    help: 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 = []
+        
+        f._options.append({
+            'param_decls': [name],
+            'is_flag': True,
+            'help': help,
+            'hidden': hidden
+        })
+        return f
+    return decorator

webscout/swiftcli/decorators/options.py

@@ -0,0 +1,220 @@
+"""Option decorators for SwiftCLI."""
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+def option(
+    *param_decls: str,
+    type: Any = str,
+    required: bool = False,
+    default: Any = None,
+    help: str = None,
+    is_flag: bool = False,
+    multiple: bool = False,
+    count: bool = False,
+    prompt: bool = False,
+    hide_input: bool = False,
+    confirmation_prompt: bool = False,
+    prompt_required: bool = True,
+    show_default: bool = True,
+    choices: Optional[List[Any]] = None,
+    case_sensitive: bool = True,
+    callback: Optional[Callable] = None,
+    hidden: bool = False
+) -> Callable:
+    """
+    Decorator to add an option to a command.
+    
+    Options are named parameters that can be provided in any order.
+    
+    Args:
+        param_decls: Option names (e.g., "--name", "-n")
+        type: Expected type
+        required: Whether option is required
+        default: Default value
+        help: Help text
+        is_flag: Whether option is a boolean flag
+        multiple: Whether option can be specified multiple times
+        count: Whether option counts occurrences
+        prompt: Whether to prompt for value if not provided
+        hide_input: Whether to hide input when prompting
+        confirmation_prompt: Whether to prompt for confirmation
+        prompt_required: Whether prompt is required
+        show_default: Whether to show default in help
+        choices: List of valid choices
+        case_sensitive: Whether choices are case sensitive
+        callback: Function to process/validate value
+        hidden: Whether to hide from help output
+        
+    Example:
+        @command()
+        @option("--count", "-c", type=int, default=1)
+        @option("--format", type=str, choices=["json", "yaml"])
+        @option("--verbose", is_flag=True)
+        def process(count: int, format: str, verbose: bool):
+            '''Process data'''
+            if verbose:
+                print(f"Processing {count} items as {format}")
+    """
+    def decorator(f: Callable) -> Callable:
+        if not hasattr(f, '_options'):
+            f._options = []
+        
+        f._options.append({
+            'param_decls': param_decls,
+            'type': type,
+            'required': required,
+            'default': default,
+            'help': help,
+            'is_flag': is_flag,
+            'multiple': multiple,
+            'count': count,
+            'prompt': prompt,
+            'hide_input': hide_input,
+            'confirmation_prompt': confirmation_prompt,
+            'prompt_required': prompt_required,
+            'show_default': show_default,
+            'choices': choices,
+            'case_sensitive': case_sensitive,
+            'callback': callback,
+            'hidden': hidden
+        })
+        return f
+    return decorator
+
+def envvar(
+    name: str,
+    type: Any = str,
+    required: bool = False,
+    default: Any = None,
+    help: str = None
+) -> Callable:
+    """
+    Decorator to load option value from environment variable.
+    
+    Args:
+        name: Environment variable name
+        type: Expected type
+        required: Whether variable is required
+        default: Default value if not set
+        help: Help text
+        
+    Example:
+        @command()
+        @envvar("API_KEY", required=True)
+        @envvar("API_URL", default="https://api.example.com")
+        def api_call(api_key: str, api_url: str):
+            '''Make API call'''
+            print(f"Calling {api_url} with key {api_key}")
+    """
+    def decorator(f: Callable) -> Callable:
+        if not hasattr(f, '_envvars'):
+            f._envvars = []
+        
+        f._envvars.append({
+            'name': name,
+            'type': type,
+            'required': required,
+            'default': default,
+            'help': help
+        })
+        return f
+    return decorator
+
+def config_file(
+    path: str = None,
+    section: str = None,
+    required: bool = False,
+    auto_create: bool = True,
+    format: str = 'json'
+) -> Callable:
+    """
+    Decorator to load configuration from file.
+    
+    Args:
+        path: Config file path
+        section: Config section to load
+        required: Whether config is required
+        auto_create: Whether to create file if missing
+        format: File format (json, yaml, ini)
+        
+    Example:
+        @command()
+        @config_file("~/.myapp/config.json")
+        def setup(config: dict):
+            '''Setup application'''
+            print(f"Database: {config.get('database')}")
+            
+        @command()
+        @config_file("config.ini", section="api")
+        def api(config: dict):
+            '''Make API call'''
+            print(f"URL: {config.get('url')}")
+    """
+    def decorator(f: Callable) -> Callable:
+        f._config = {
+            'path': path,
+            'section': section,
+            'required': required,
+            'auto_create': auto_create,
+            'format': format
+        }
+        return f
+    return decorator
+
+def version_option(
+    version: str = None,
+    prog_name: str = None,
+    message: str = None,
+    package_name: str = None
+) -> Callable:
+    """
+    Decorator to add version option to command.
+    
+    Args:
+        version: Version string
+        prog_name: Program name
+        message: Custom version message
+        package_name: Package name to get version from
+        
+    Example:
+        @command()
+        @version_option(version="1.0.0")
+        def main():
+            '''Main command'''
+            pass
+    """
+    def decorator(f: Callable) -> Callable:
+        f._version = {
+            'version': version,
+            'prog_name': prog_name,
+            'message': message,
+            'package_name': package_name
+        }
+        return f
+    return decorator
+
+def help_option(
+    param_decls: List[str] = None,
+    help: str = None
+) -> Callable:
+    """
+    Decorator to customize help option.
+    
+    Args:
+        param_decls: Help option flags
+        help: Help text
+        
+    Example:
+        @command()
+        @help_option(["--help", "-h"], "Show this message")
+        def main():
+            '''Main command'''
+            pass
+    """
+    def decorator(f: Callable) -> Callable:
+        f._help_option = {
+            'param_decls': param_decls or ['--help', '-h'],
+            'help': help or 'Show this message and exit.'
+        }
+        return f
+    return decorator

webscout/swiftcli/decorators/output.py

@@ -0,0 +1,252 @@
+"""Output formatting decorators for SwiftCLI."""
+
+from functools import wraps
+from typing import Any, Callable, List, Optional, Union
+
+from rich.console import Console
+from rich.table import Table
+from rich.progress import (
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    BarColumn,
+    TaskProgressColumn,
+    TimeRemainingColumn
+)
+from rich.panel import Panel
+
+console = Console()
+
+def table_output(
+    headers: List[str],
+    title: Optional[str] = None,
+    style: str = "default",
+    show_lines: bool = False,
+    expand: bool = False
+) -> Callable:
+    """
+    Decorator to format command output as a table.
+    
+    Args:
+        headers: Column headers
+        title: Table title
+        style: Table style
+        show_lines: Show row/column lines
+        expand: Expand table to terminal width
+        
+    Example:
+        @command()
+        @table_output(["ID", "Name", "Status"])
+        def list_users():
+            '''List all users'''
+            return [
+                [1, "John", "Active"],
+                [2, "Jane", "Inactive"]
+            ]
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            result = f(*args, **kwargs)
+            if result:
+                table = Table(
+                    title=title,
+                    show_header=True,
+                    header_style="bold blue",
+                    show_lines=show_lines,
+                    expand=expand
+                )
+                
+                # Add columns
+                for header in headers:
+                    table.add_column(header)
+                
+                # Add rows
+                for row in result:
+                    table.add_row(*[str(cell) for cell in row])
+                
+                console.print(table)
+            return result
+        return wrapper
+    return decorator
+
+def progress(
+    description: str = None,
+    total: Optional[int] = None,
+    transient: bool = False,
+    show_bar: bool = True,
+    show_percentage: bool = True,
+    show_time: bool = True
+) -> Callable:
+    """
+    Decorator to show progress for long-running commands.
+    
+    The decorated function should be a generator that yields
+    progress updates.
+    
+    Args:
+        description: Task description
+        total: Total number of steps
+        transient: Remove progress when done
+        show_bar: Show progress bar
+        show_percentage: Show percentage complete
+        show_time: Show time remaining
+        
+    Example:
+        @command()
+        @progress("Processing files")
+        def process(files: List[str]):
+            '''Process multiple files'''
+            for file in files:
+                # Process file
+                yield f"Processing {file}..."
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            columns = []
+            columns.append(SpinnerColumn())
+            columns.append(TextColumn("[progress.description]{task.description}"))
+            
+            if show_bar:
+                columns.append(BarColumn())
+            if show_percentage:
+                columns.append(TaskProgressColumn())
+            if show_time:
+                columns.append(TimeRemainingColumn())
+            
+            with Progress(*columns, transient=transient) as progress:
+                task = progress.add_task(
+                    description or f.__name__,
+                    total=total
+                )
+                
+                try:
+                    for update in f(*args, **kwargs):
+                        if isinstance(update, (int, float)):
+                            # Update progress by number
+                            progress.update(task, advance=update)
+                        elif isinstance(update, str):
+                            # Update description
+                            progress.update(task, description=update)
+                        elif isinstance(update, dict):
+                            # Update multiple attributes
+                            progress.update(task, **update)
+                        else:
+                            # Just advance by 1
+                            progress.update(task, advance=1)
+                except Exception as e:
+                    progress.update(task, description=f"Error: {str(e)}")
+                    raise
+                finally:
+                    progress.update(task, completed=total or 100)
+        
+        return wrapper
+    return decorator
+
+def panel_output(
+    title: Optional[str] = None,
+    style: str = "default",
+    expand: bool = True,
+    padding: Union[int, tuple] = 1
+) -> Callable:
+    """
+    Decorator to display command output in a panel.
+    
+    Args:
+        title: Panel title
+        style: Panel style
+        expand: Expand panel to terminal width
+        padding: Panel padding
+        
+    Example:
+        @command()
+        @panel_output(title="System Status")
+        def status():
+            '''Show system status'''
+            return "All systems operational"
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            result = f(*args, **kwargs)
+            if result:
+                panel = Panel(
+                    str(result),
+                    title=title,
+                    style=style,
+                    expand=expand,
+                    padding=padding
+                )
+                console.print(panel)
+            return result
+        return wrapper
+    return decorator
+
+def format_output(
+    template: str,
+    style: Optional[str] = None
+) -> Callable:
+    """
+    Decorator to format command output using a template.
+    
+    Args:
+        template: Format string template
+        style: Rich style string
+        
+    Example:
+        @command()
+        @format_output("Created user {name} with ID {id}")
+        def create_user(name: str):
+            '''Create a new user'''
+            return {"name": name, "id": 123}
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            result = f(*args, **kwargs)
+            if result:
+                if isinstance(result, dict):
+                    output = template.format(**result)
+                else:
+                    output = template.format(result)
+                
+                if style:
+                    console.print(output, style=style)
+                else:
+                    console.print(output)
+            return result
+        return wrapper
+    return decorator
+
+def pager_output(
+    use_pager: bool = True,
+    style: Optional[str] = None
+) -> Callable:
+    """
+    Decorator to display command output in a pager.
+    
+    Args:
+        use_pager: Whether to use pager
+        style: Rich style string
+        
+    Example:
+        @command()
+        @pager_output()
+        def show_logs():
+            '''Show application logs'''
+            return "Very long log output..."
+    """
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            result = f(*args, **kwargs)
+            if result:
+                with console.pager(styles=use_pager):
+                    if style:
+                        console.print(result, style=style)
+                    else:
+                        console.print(result)
+            return result
+        return wrapper
+    return decorator

webscout/swiftcli/exceptions.py

@@ -0,0 +1,21 @@
+"""Exception classes for SwiftCLI."""
+
+class SwiftCLIException(Exception):
+    """Base exception class for SwiftCLI."""
+    pass
+
+class UsageError(SwiftCLIException):
+    """Raised when CLI is used incorrectly."""
+    pass
+
+class BadParameter(UsageError):
+    """Raised when a parameter is invalid."""
+    pass
+
+class ConfigError(SwiftCLIException):
+    """Raised when there is a configuration error."""
+    pass
+
+class PluginError(SwiftCLIException):
+    """Raised when there is a plugin error."""
+    pass