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

webscout/swiftcli/decorators/options.py

@@ -0,0 +1,247 @@
+"""Option decorators for SwiftCLI."""
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+# Sentinel for unspecified defaults
+_NO_DEFAULT = object()
+
+
+def option(
+    *param_decls: str,
+    type: Any = str,
+    required: bool = False,
+    default: Any = _NO_DEFAULT,
+    help: Optional[str] = None,
+    is_flag: bool = False,
+    multiple: bool = False,
+    count: bool = False,
+    prompt: Union[bool, str] = False,
+    hide_input: bool = False,
+    confirmation_prompt: Union[bool, str] = 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,
+    validation: Optional[Dict[str, Any]] = None,
+    mutually_exclusive: Optional[List[str]] = None,
+) -> 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 (can be string for prompt text)
+        hide_input: Whether to hide input when prompting
+        confirmation_prompt: Whether to prompt for confirmation (can be string for prompt text)
+        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
+        validation: Dictionary of validation rules (min_length, max_length, pattern, etc.)
+        mutually_exclusive: List of option names that are mutually exclusive with this option
+
+    Example:
+        @command()
+        @option("--count", "-c", type=int, default=1)
+        @option("--format", type=str, choices=["json", "yaml"])
+        @option("--verbose", is_flag=True)
+        @option("--name", validation={'min_length': 3, 'max_length': 20})
+        def process(count: int, format: str, verbose: bool, name: str):
+            '''Process data'''
+            if verbose:
+                print(f"Processing {count} items as {format}")
+    """
+
+    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": param_decls,
+                "type": type,
+                "required": required,
+                # Only include default explicitly if something other than sentinel was provided
+                **({"default": default} if default is not _NO_DEFAULT else {}),
+                "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,
+                "validation": validation,
+                "mutually_exclusive": mutually_exclusive,
+            }
+        )
+        return f
+
+    return decorator
+
+
+def envvar(
+    name: str,
+    type: Any = str,
+    required: bool = False,
+    default: Any = None,
+    help: Optional[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 = []  # type: ignore[attr-defined]
+
+        f._envvars.append(  # type: ignore[attr-defined]
+            {
+                "name": name,
+                "type": type,
+                "required": required,
+                "default": default,
+                "help": help,
+            }
+        )
+        return f
+
+    return decorator
+
+
+def config_file(
+    path: Optional[str] = None,
+    section: Optional[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 = {  # type: ignore[attr-defined]
+            "path": path,
+            "section": section,
+            "required": required,
+            "auto_create": auto_create,
+            "format": format,
+        }
+        return f
+
+    return decorator
+
+
+def version_option(
+    version: Optional[str] = None,
+    prog_name: Optional[str] = None,
+    message: Optional[str] = None,
+    package_name: Optional[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 = {  # type: ignore[attr-defined]
+            "version": version,
+            "prog_name": prog_name,
+            "message": message,
+            "package_name": package_name,
+        }
+        return f
+
+    return decorator
+
+
+def help_option(param_decls: Optional[List[str]] = None, help: Optional[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 = {  # type: ignore[attr-defined]
+            "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,392 @@
+"""Output formatting decorators for SwiftCLI."""
+
+import json
+from functools import wraps
+from typing import TYPE_CHECKING, Callable, List, Optional, Union
+
+import yaml
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+if TYPE_CHECKING:
+    from rich.progress import (
+        BarColumn,
+        Progress,
+        SpinnerColumn,
+        TaskProgressColumn,
+        TextColumn,
+        TimeRemainingColumn,
+    )
+else:
+    # Handle different versions of rich
+    try:
+        from rich.progress import (
+            BarColumn,
+            Progress,
+            SpinnerColumn,
+            TaskProgressColumn,
+            TextColumn,
+            TimeRemainingColumn,
+        )
+    except ImportError:
+        # If standard imports fail, try older rich versions or create minimal fallbacks
+        try:
+            from rich.progress import (
+                BarColumn,
+                Progress,
+                SpinnerColumn,
+                TextColumn,
+                TimeRemainingColumn,
+            )
+
+            # Create a simple TaskProgressColumn replacement for older versions
+            class TaskProgressColumn:
+                def __init__(self):
+                    pass
+
+                def __call__(self, task):
+                    return f"{task.percentage:.1f}%"
+        except ImportError:
+            # If rich is too old or not installed, create minimal fallbacks
+            class Progress:
+                def __init__(self, *args, **kwargs):
+                    pass
+
+                def __enter__(self):
+                    return self
+
+                def __exit__(self, *args):
+                    pass
+
+                def add_task(self, description, total=None):
+                    return 0
+
+                def update(self, task_id, **kwargs):
+                    pass
+
+            class SpinnerColumn:
+                pass
+
+            class TextColumn:
+                def __init__(self, text):
+                    pass
+
+            class BarColumn:
+                pass
+
+            class TaskProgressColumn:
+                pass
+
+            class TimeRemainingColumn:
+                pass
+
+
+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 json_output(indent: int = 2, sort_keys: bool = False, ensure_ascii: bool = False) -> Callable:
+    """
+    Decorator to format command output as JSON.
+
+    Args:
+        indent: Indentation level for pretty printing
+        sort_keys: Whether to sort dictionary keys
+        ensure_ascii: Whether to escape non-ASCII characters
+
+    Example:
+        @command()
+        @json_output(indent=2)
+        def get_data():
+            '''Get data as JSON'''
+            return {"status": "success", "data": [1, 2, 3]}
+    """
+
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            result = f(*args, **kwargs)
+            if result:
+                json_str = json.dumps(
+                    result, indent=indent, sort_keys=sort_keys, ensure_ascii=ensure_ascii
+                )
+                console.print(json_str)
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def yaml_output(default_flow_style: bool = False, sort_keys: bool = False) -> Callable:
+    """
+    Decorator to format command output as YAML.
+
+    Args:
+        default_flow_style: Whether to use flow style for collections
+        sort_keys: Whether to sort dictionary keys
+
+    Example:
+        @command()
+        @yaml_output()
+        def get_config():
+            '''Get configuration as YAML'''
+            return {"database": {"host": "localhost", "port": 5432}}
+    """
+
+    def decorator(f: Callable) -> Callable:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            result = f(*args, **kwargs)
+            if result:
+                yaml_str = yaml.safe_dump(
+                    result, default_flow_style=default_flow_style, sort_keys=sort_keys
+                )
+                console.print(yaml_str)
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def progress(
+    description: Optional[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:
+                try:
+                    columns.append(TaskProgressColumn())
+                except Exception:
+                    # Fallback for older rich versions
+                    columns.append(TextColumn("[progress.percentage]{task.percentage:>3.0f}%"))
+            if show_time:
+                columns.append(TimeRemainingColumn())
+
+            with Progress(*columns, transient=transient) as progress:
+                task = progress.add_task(description or getattr(f, '__name__', 'unknown'), 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

webscout/swiftcli/plugins/__init__.py

@@ -0,0 +1,9 @@
+"""Plugin system for SwiftCLI."""
+
+from .base import Plugin
+from .manager import PluginManager
+
+__all__ = [
+    'Plugin',
+    'PluginManager'
+]