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

webscout/swiftcli/plugins/base.py

@@ -0,0 +1,134 @@
+"""Base plugin system for SwiftCLI."""
+
+from typing import Any, Dict, List, Optional
+
+
+class Plugin:
+    """
+    Base class for SwiftCLI plugins.
+
+    Plugins can extend the CLI functionality by hooking into various stages
+    of command execution. Subclass this class and override the methods
+    you want to hook into.
+
+    Attributes:
+        app: The CLI application instance
+        enabled: Whether the plugin is enabled
+        config: Plugin configuration dictionary
+
+    Example:
+        class LoggingPlugin(Plugin):
+            def before_command(self, command, args):
+                print(f"[LOG] Running command: {command}")
+
+            def after_command(self, command, args, result):
+                print(f"[LOG] Command completed: {result}")
+    """
+
+    def __init__(self):
+        self.app = None  # Set by plugin manager
+        self.enabled: bool = True
+        self.config: Dict[str, Any] = {}
+
+    def init_app(self, app: Any) -> None:
+        """
+        Initialize plugin with CLI app instance.
+
+        Args:
+            app: The CLI application instance
+        """
+        self.app = app
+
+    def before_command(self, command: str, args: List[str]) -> Optional[bool]:
+        """
+        Called before command execution.
+
+        Args:
+            command: Command name
+            args: Command arguments
+
+        Returns:
+            Optional[bool]: Return False to prevent command execution
+        """
+        pass
+
+    def after_command(self, command: str, args: List[str], result: Any) -> None:
+        """
+        Called after command execution.
+
+        Args:
+            command: Command name
+            args: Command arguments
+            result: Command result
+        """
+        pass
+
+    def on_error(self, command: str, error: Exception) -> None:
+        """
+        Called when command raises an error.
+
+        Args:
+            command: Command name
+            error: The exception that was raised
+        """
+        pass
+
+    def on_help(self, command: str) -> Optional[str]:
+        """
+        Called when help is requested for a command.
+
+        Args:
+            command: Command name
+
+        Returns:
+            Optional[str]: Additional help text to display
+        """
+        pass
+
+    def on_completion(self, command: str, incomplete: str) -> List[str]:
+        """
+        Called when shell completion is requested.
+
+        Args:
+            command: Command name
+            incomplete: Incomplete text to complete
+
+        Returns:
+            List[str]: Possible completions
+        """
+        return []
+
+    def configure(self, config: Dict[str, Any]) -> None:
+        """
+        Configure the plugin.
+
+        Args:
+            config: Configuration dictionary
+        """
+        self.config.update(config)
+
+    def validate_config(self) -> None:
+        """
+        Validate plugin configuration.
+
+        Raises:
+            PluginError: If configuration is invalid
+        """
+        pass
+
+    def enable(self) -> None:
+        """Enable the plugin."""
+        self.enabled = True
+
+    def disable(self) -> None:
+        """Disable the plugin."""
+        self.enabled = False
+
+    @property
+    def name(self) -> str:
+        """Get plugin name."""
+        return self.__class__.__name__
+
+    def __repr__(self) -> str:
+        status = "enabled" if self.enabled else "disabled"
+        return f"<{self.name} [{status}]>"

webscout/swiftcli/plugins/manager.py

@@ -0,0 +1,269 @@
+"""Plugin manager for SwiftCLI."""
+
+import importlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from rich.console import Console
+
+from ..exceptions import PluginError
+from .base import Plugin
+
+console = Console()
+
+class PluginManager:
+    """
+    Manages SwiftCLI plugins.
+
+    The plugin manager handles plugin registration, loading, and execution.
+    It provides hooks for plugins to extend CLI functionality at various points
+    during command execution.
+
+    Attributes:
+        plugins: List of registered plugins
+        plugin_dir: Directory where plugins are stored
+
+    Example:
+        # Register a plugin
+        plugin_manager = PluginManager()
+        plugin_manager.register(LoggingPlugin())
+
+        # Load plugins from directory
+        plugin_manager.load_plugins()
+    """
+
+    def __init__(self, plugin_dir: Optional[str] = None):
+        """
+        Initialize plugin manager.
+
+        Args:
+            plugin_dir: Optional custom plugin directory path
+        """
+        self.plugins: List[Plugin] = []
+        # Use temporary directory instead of ~/.swiftcli/plugins
+        if plugin_dir:
+            self.plugin_dir = plugin_dir
+            os.makedirs(self.plugin_dir, exist_ok=True)
+        else:
+            # Create a temporary directory that will be cleaned up when the process exits
+            self.temp_dir = tempfile.TemporaryDirectory(prefix="swiftcli_")
+            self.plugin_dir = self.temp_dir.name
+
+        # Add plugin directory to Python path
+        if self.plugin_dir not in sys.path:
+            sys.path.append(self.plugin_dir)
+
+    def register(self, plugin: Plugin) -> None:
+        """
+        Register a new plugin.
+
+        Args:
+            plugin: Plugin instance to register
+
+        Raises:
+            PluginError: If plugin is invalid or already registered
+        """
+        if not isinstance(plugin, Plugin):
+            raise PluginError(f"Invalid plugin type: {type(plugin)}")
+
+        if self._get_plugin(plugin.name):
+            raise PluginError(f"Plugin already registered: {plugin.name}")
+
+        try:
+            plugin.validate_config()
+        except Exception as e:
+            raise PluginError(f"Plugin configuration invalid: {str(e)}")
+
+        self.plugins.append(plugin)
+
+    def unregister(self, plugin_name: str) -> None:
+        """
+        Unregister a plugin.
+
+        Args:
+            plugin_name: Name of plugin to unregister
+
+        Raises:
+            PluginError: If plugin not found
+        """
+        plugin = self._get_plugin(plugin_name)
+        if not plugin:
+            raise PluginError(f"Plugin not found: {plugin_name}")
+
+        self.plugins.remove(plugin)
+
+    def load_plugins(self) -> None:
+        """
+        Load all plugins from plugin directory.
+
+        This method searches for Python files in the plugin directory and
+        attempts to load any Plugin subclasses defined in them.
+        """
+        for file in Path(self.plugin_dir).glob("*.py"):
+            if file.name.startswith("_"):
+                continue
+
+            try:
+                module = importlib.import_module(file.stem)
+
+                # Find Plugin subclasses in module
+                for attr_name in dir(module):
+                    attr = getattr(module, attr_name)
+                    if (isinstance(attr, type) and
+                        issubclass(attr, Plugin) and
+                        attr is not Plugin):
+                        plugin = attr()
+                        self.register(plugin)
+
+            except Exception as e:
+                console.print(f"[red]Error loading plugin {file.name}: {e}[/red]")
+
+    def init_plugins(self, app: Any) -> None:
+        """
+        Initialize all plugins with the CLI application instance.
+
+        Args:
+            app: The CLI application instance
+        """
+        for plugin in self.plugins:
+            plugin.init_app(app)
+
+    def configure_plugins(self, config: Dict[str, Dict[str, Any]]) -> None:
+        """
+        Configure plugins with provided configuration.
+
+        Args:
+            config: Dictionary of plugin configurations
+        """
+        for plugin in self.plugins:
+            if plugin.name in config:
+                plugin.configure(config[plugin.name])
+
+    def before_command(self, command: str, args: List[str]) -> bool:
+        """
+        Run before_command hooks for all plugins.
+
+        Args:
+            command: Command name
+            args: Command arguments
+
+        Returns:
+            bool: False if any plugin prevents command execution
+        """
+        for plugin in self.plugins:
+            if not plugin.enabled:
+                continue
+
+            try:
+                result = plugin.before_command(command, args)
+                if result is False:
+                    return False
+            except Exception as e:
+                console.print(f"[red]Error in plugin {plugin.name}: {e}[/red]")
+                if plugin.app and getattr(plugin.app, 'debug', False):
+                    import traceback
+                    traceback.print_exc()
+
+        return True
+
+    def after_command(self, command: str, args: List[str], result: Any) -> None:
+        """
+        Run after_command hooks for all plugins.
+
+        Args:
+            command: Command name
+            args: Command arguments
+            result: Command result
+        """
+        for plugin in self.plugins:
+            if not plugin.enabled:
+                continue
+
+            try:
+                plugin.after_command(command, args, result)
+            except Exception as e:
+                console.print(f"[red]Error in plugin {plugin.name}: {e}[/red]")
+                if plugin.app and getattr(plugin.app, 'debug', False):
+                    import traceback
+                    traceback.print_exc()
+
+    def on_error(self, command: str, error: Exception) -> None:
+        """
+        Run error hooks for all plugins.
+
+        Args:
+            command: Command name
+            error: The exception that was raised
+        """
+        for plugin in self.plugins:
+            if not plugin.enabled:
+                continue
+
+            try:
+                plugin.on_error(command, error)
+            except Exception as e:
+                console.print(f"[red]Error in plugin {plugin.name}: {e}[/red]")
+                if plugin.app and getattr(plugin.app, 'debug', False):
+                    import traceback
+                    traceback.print_exc()
+
+    def get_help_text(self, command: str) -> List[str]:
+        """
+        Get additional help text from plugins.
+
+        Args:
+            command: Command name
+
+        Returns:
+            List[str]: List of help text strings from plugins
+        """
+        help_texts = []
+        for plugin in self.plugins:
+            if not plugin.enabled:
+                continue
+
+            try:
+                help_text = plugin.on_help(command)
+                if help_text:
+                    help_texts.append(help_text)
+            except Exception as e:
+                console.print(f"[red]Error in plugin {plugin.name}: {e}[/red]")
+
+        return help_texts
+
+    def get_completions(self, command: str, incomplete: str) -> List[str]:
+        """
+        Get command completions from plugins.
+
+        Args:
+            command: Command name
+            incomplete: Incomplete text to complete
+
+        Returns:
+            List[str]: Combined list of completions from all plugins
+        """
+        completions = []
+        for plugin in self.plugins:
+            if not plugin.enabled:
+                continue
+
+            try:
+                plugin_completions = plugin.on_completion(command, incomplete)
+                completions.extend(plugin_completions)
+            except Exception as e:
+                console.print(f"[red]Error in plugin {plugin.name}: {e}[/red]")
+
+        return list(set(completions))  # Remove duplicates
+
+    def _get_plugin(self, name: str) -> Optional[Plugin]:
+        """Get plugin by name."""
+        for plugin in self.plugins:
+            if plugin.name == name:
+                return plugin
+        return None
+
+    def __repr__(self) -> str:
+        return f"<PluginManager plugins={len(self.plugins)}>"

webscout/swiftcli/utils/__init__.py

@@ -0,0 +1,58 @@
+"""Utility functions for SwiftCLI."""
+
+from .formatting import (
+    clear_screen,
+    create_padding,
+    create_table,
+    format_dict,
+    format_error,
+    format_info,
+    format_list,
+    format_success,
+    format_warning,
+    get_terminal_size,
+    strip_ansi,
+    style_text,
+    truncate_text,
+    wrap_text,
+)
+from .parsing import (
+    convert_type,
+    get_env_var,
+    load_config_file,
+    parse_args,
+    parse_dict,
+    parse_key_value,
+    parse_list,
+    validate_choice,
+    validate_required,
+)
+
+__all__ = [
+    # Formatting utilities
+    'style_text',
+    'format_error',
+    'format_warning',
+    'format_success',
+    'format_info',
+    'create_table',
+    'truncate_text',
+    'wrap_text',
+    'format_dict',
+    'format_list',
+    'strip_ansi',
+    'get_terminal_size',
+    'clear_screen',
+    'create_padding',
+
+    # Parsing utilities
+    'parse_args',
+    'validate_required',
+    'convert_type',
+    'validate_choice',
+    'load_config_file',
+    'parse_key_value',
+    'parse_list',
+    'parse_dict',
+    'get_env_var'
+]

webscout/swiftcli/utils/formatting.py

@@ -0,0 +1,251 @@
+"""Utility functions for text formatting and styling."""
+
+import re
+from typing import Any, Dict, List, Optional, Union
+
+from rich.console import Console
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+def style_text(
+    text: str,
+    color: Optional[str] = None,
+    bold: bool = False,
+    italic: bool = False,
+    underline: bool = False
+) -> Text:
+    """
+    Apply styling to text.
+
+    Args:
+        text: Text to style
+        color: Text color
+        bold: Bold text
+        italic: Italic text
+        underline: Underline text
+
+    Returns:
+        Rich Text object with applied styling
+    """
+    style = []
+    if color:
+        style.append(color)
+    if bold:
+        style.append("bold")
+    if italic:
+        style.append("italic")
+    if underline:
+        style.append("underline")
+
+    return Text(text, style=" ".join(style))
+
+def format_error(message: str, title: str = "Error") -> None:
+    """
+    Format and display error message.
+
+    Args:
+        message: Error message
+        title: Error title
+    """
+    console.print(f"[bold red]{title}:[/] {message}")
+
+def format_warning(message: str, title: str = "Warning") -> None:
+    """
+    Format and display warning message.
+
+    Args:
+        message: Warning message
+        title: Warning title
+    """
+    console.print(f"[bold yellow]{title}:[/] {message}")
+
+def format_success(message: str, title: str = "Success") -> None:
+    """
+    Format and display success message.
+
+    Args:
+        message: Success message
+        title: Success title
+    """
+    console.print(f"[bold green]{title}:[/] {message}")
+
+def format_info(message: str, title: str = "Info") -> None:
+    """
+    Format and display info message.
+
+    Args:
+        message: Info message
+        title: Info title
+    """
+    console.print(f"[bold blue]{title}:[/] {message}")
+
+def create_table(
+    headers: List[str],
+    rows: List[List[Any]],
+    title: Optional[str] = None,
+    style: str = "default",
+    show_lines: bool = False
+) -> Table:
+    """
+    Create a formatted table.
+
+    Args:
+        headers: Column headers
+        rows: Table rows
+        title: Table title
+        style: Table style
+        show_lines: Show row/column lines
+
+    Returns:
+        Rich Table object
+    """
+    table = Table(
+        title=title,
+        show_header=True,
+        header_style="bold blue",
+        show_lines=show_lines
+    )
+
+    # Add columns
+    for header in headers:
+        table.add_column(header)
+
+    # Add rows
+    for row in rows:
+        table.add_row(*[str(cell) for cell in row])
+
+    return table
+
+def truncate_text(
+    text: str,
+    max_length: int,
+    suffix: str = "..."
+) -> str:
+    """
+    Truncate text to specified length.
+
+    Args:
+        text: Text to truncate
+        max_length: Maximum length
+        suffix: Truncation suffix
+
+    Returns:
+        Truncated text
+    """
+    if len(text) <= max_length:
+        return text
+    return text[:max_length - len(suffix)] + suffix
+
+def wrap_text(
+    text: str,
+    width: int,
+    indent: str = "",
+    initial_indent: str = ""
+) -> str:
+    """
+    Wrap text to specified width.
+
+    Args:
+        text: Text to wrap
+        width: Maximum line width
+        indent: Indentation for wrapped lines
+        initial_indent: Indentation for first line
+
+    Returns:
+        Wrapped text
+    """
+    import textwrap
+    return textwrap.fill(
+        text,
+        width=width,
+        initial_indent=initial_indent,
+        subsequent_indent=indent
+    )
+
+def format_dict(
+    data: Dict[str, Any],
+    indent: int = 2,
+    sort_keys: bool = True
+) -> str:
+    """
+    Format dictionary for display.
+
+    Args:
+        data: Dictionary to format
+        indent: Indentation level
+        sort_keys: Sort dictionary keys
+
+    Returns:
+        Formatted string
+    """
+    import json
+    return json.dumps(
+        data,
+        indent=indent,
+        sort_keys=sort_keys,
+        default=str
+    )
+
+def format_list(
+    items: List[Any],
+    bullet: str = "•",
+    indent: int = 2
+) -> str:
+    """
+    Format list for display.
+
+    Args:
+        items: List to format
+        bullet: Bullet point character
+        indent: Indentation level
+
+    Returns:
+        Formatted string
+    """
+    indent_str = " " * indent
+    return "\n".join(f"{indent_str}{bullet} {item}" for item in items)
+
+def strip_ansi(text: str) -> str:
+    """
+    Remove ANSI escape sequences from text.
+
+    Args:
+        text: Text containing ANSI sequences
+
+    Returns:
+        Clean text
+    """
+    ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
+    return ansi_escape.sub('', text)
+
+def get_terminal_size() -> tuple:
+    """
+    Get terminal size.
+
+    Returns:
+        Tuple of (width, height)
+    """
+    return console.size
+
+def clear_screen() -> None:
+    """Clear the terminal screen."""
+    console.clear()
+
+def create_padding(
+    renderable: Any,
+    pad: Union[int, tuple] = 1
+) -> Padding:
+    """
+    Add padding around content.
+
+    Args:
+        renderable: Content to pad
+        pad: Padding amount
+
+    Returns:
+        Padded content
+    """
+    return Padding(renderable, pad)