repl-toolkit 1.2.0__py3-none-any.whl

repl_toolkit/__init__.py

@@ -0,0 +1,70 @@
+"""
+REPL Toolkit - A Python toolkit for building interactive REPL and headless interfaces.
+
+This package provides tools for creating interactive command-line interfaces
+with support for both commands and keyboard shortcuts, featuring late backend
+binding for resource context scenarios.
+
+Key Features:
+- Action system with commands and keyboard shortcuts
+- Late backend binding for resource contexts
+- Protocol-based architecture for type safety
+- Comprehensive test coverage
+- Async-native design
+- Auto-formatting utilities for HTML and ANSI text
+- Custom output handling with configurable printer
+- Shell expansion and prefix-based completion
+
+Example:
+    >>> import asyncio
+    >>> from repl_toolkit import run_async_repl, ActionRegistry
+    >>>
+    >>> class MyBackend:
+    ...     async def handle_input(self, user_input: str) -> bool:
+    ...         print(f"You said: {user_input}")
+    ...         return True
+    >>>
+    >>> async def main():
+    ...     backend = MyBackend()
+    ...     await run_async_repl(backend=backend)
+    >>>
+    >>> # asyncio.run(main())
+"""
+
+__version__ = "1.2.0"
+__author__ = "REPL Toolkit Contributors"
+__license__ = "MIT"
+
+from .actions import Action, ActionContext, ActionError, ActionRegistry
+
+# Core exports
+from .async_repl import AsyncREPL, run_async_repl
+from .completion import PrefixCompleter, ShellExpansionCompleter
+from .formatting import auto_format, create_auto_printer, detect_format_type, print_auto_formatted
+from .headless_repl import HeadlessREPL, run_headless_mode
+from .ptypes import ActionHandler, AsyncBackend, Completer
+
+__all__ = [
+    # Core classes
+    "AsyncREPL",
+    "HeadlessREPL",
+    "ActionRegistry",
+    "Action",
+    "ActionContext",
+    "ActionError",
+    # Convenience functions
+    "run_async_repl",
+    "run_headless_mode",
+    # Protocols/Types
+    "AsyncBackend",
+    "ActionHandler",
+    "Completer",
+    # Formatting utilities
+    "detect_format_type",
+    "auto_format",
+    "print_auto_formatted",
+    "create_auto_printer",
+    # Completion utilities
+    "ShellExpansionCompleter",
+    "PrefixCompleter",
+]

repl_toolkit/actions/__init__.py

@@ -0,0 +1,24 @@
+"""
+Action system for repl_toolkit.
+
+This module provides the action architecture that combines command
+and keyboard shortcut handling into a single, extensible framework.
+
+The action system allows developers to define actions that can be triggered
+by either typed commands (e.g., /help) or keyboard shortcuts (e.g., F1),
+providing a consistent and discoverable interface for users.
+"""
+
+from .action import Action, ActionContext, ActionError, ActionExecutionError, ActionValidationError
+from .registry import ActionRegistry
+
+__all__ = [
+    # Core action types
+    "Action",
+    "ActionContext",
+    "ActionError",
+    "ActionValidationError",
+    "ActionExecutionError",
+    # Registry
+    "ActionRegistry",
+]

repl_toolkit/actions/action.py

@@ -0,0 +1,223 @@
+"""
+Core action definition and context for the action system.
+
+This module defines the Action dataclass and ActionContext that form the
+foundation of the command and keyboard shortcut system.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Union
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from .registry import ActionRegistry
+
+
+@dataclass
+class Action:
+    """
+    Action definition that can be triggered by commands or keyboard shortcuts.
+
+    Actions provide a way to define functionality that can be accessed
+    through multiple interaction methods (commands, shortcuts) while maintaining
+    consistent behavior and documentation.
+
+    Example:
+        # Action with both command and shortcut
+        help_action = Action(
+            name="show_help",
+            description="Show help information",
+            category="General",
+            handler=show_help_function,
+            command="/help",
+            command_usage="/help [command] - Show help for all or specific command",
+            keys="F1",
+            keys_description="Show help"
+        )
+
+        # Command-only action
+        history_action = Action(
+            name="show_history",
+            description="Display conversation history",
+            category="Information",
+            handler=show_history_function,
+            command="/history",
+            command_usage="/history - Display message history"
+        )
+
+        # Shortcut-only action
+        save_action = Action(
+            name="quick_save",
+            description="Quick save current state",
+            category="File",
+            handler=quick_save_function,
+            keys="ctrl-s",
+            keys_description="Quick save"
+        )
+
+        # Main-loop action (handled externally)
+        exit_action = Action(
+            name="exit_repl",
+            description="Exit the application",
+            category="Control",
+            handler=None,  # Handled by main loop
+            command="/exit",
+            command_usage="/exit - Exit the application"
+        )
+    """
+
+    # Core action definition
+    name: str  # Unique action identifier
+    description: str  # Human-readable description
+    category: str  # Category for grouping/organization
+    handler: Optional[Union[Callable, str]]  # Handler function, import path, or None for main-loop
+
+    # Command binding (optional)
+    command: Optional[str] = None  # Command string (e.g., "/help")
+    command_args_description: Optional[str] = None  # Description of command arguments
+    command_usage: Optional[str] = None  # Full usage description
+
+    # Keyboard shortcut binding (optional)
+    keys: Optional[Union[str, List[str]]] = None  # Key combination(s)
+    keys_description: Optional[str] = None  # Shortcut description for help
+
+    # Metadata and control
+    enabled: bool = True  # Whether action is currently enabled
+    context: Optional[str] = None  # Context where action is available
+    requires_backend: bool = False  # Whether action needs backend access
+    hidden: bool = False  # Hide from help listings
+
+    def __post_init__(self):
+        """Validate action definition after initialization."""
+        logger.trace("Action.__post_init__() entry")
+
+        if not self.name:
+            raise ValueError("Action name cannot be empty")
+
+        if not self.description:
+            raise ValueError("Action description cannot be empty")
+
+        if not self.category:
+            raise ValueError("Action category cannot be empty")
+
+        # Handler can be None for main-loop actions like exit/quit
+        # but if provided, it cannot be empty string
+        if self.handler == "":
+            raise ValueError(
+                "Action handler cannot be empty string (use None for main-loop actions)"
+            )
+
+        if not self.command and not self.keys:
+            raise ValueError("Action must have either command or keys binding")
+
+        # Validate command format
+        if self.command and not self.command.startswith("/"):
+            raise ValueError(f"Command '{self.command}' must start with '/'")
+
+        # Ensure command usage is provided for commands
+        if self.command and not self.command_usage:
+            logger.warning(f"Action '{self.name}' has command but no usage description")
+
+        # Ensure keys description is provided for shortcuts
+        if self.keys and not self.keys_description:
+            logger.warning(f"Action '{self.name}' has keys but no keys description")
+
+        logger.trace("Action.__post_init__() exit")
+
+    @property
+    def has_command(self) -> bool:
+        """Check if action has a command binding."""
+        logger.trace("Action.has_command() entry/exit")
+        return self.command is not None
+
+    @property
+    def has_shortcut(self) -> bool:
+        """Check if action has a keyboard shortcut binding."""
+        logger.trace("Action.has_shortcut() entry/exit")
+        return self.keys is not None
+
+    @property
+    def is_main_loop_action(self) -> bool:
+        """Check if action is handled by the main loop (handler is None)."""
+        logger.trace("Action.is_main_loop_action() entry/exit")
+        return self.handler is None
+
+    def get_keys_list(self) -> List[str]:
+        """Get keys as a list, handling both string and list formats."""
+        logger.trace("Action.get_keys_list() entry")
+
+        if not self.keys:
+            logger.trace("Action.get_keys_list() exit - no keys")
+            return []
+
+        result = [self.keys] if isinstance(self.keys, str) else self.keys
+        logger.trace("Action.get_keys_list() exit")
+        return result
+
+
+@dataclass
+class ActionContext:
+    """
+    Context information passed to action handlers.
+
+    ActionContext provides handlers with access to the registry, backend,
+    and context-specific information needed to execute actions properly.
+
+    The context varies depending on how the action was triggered:
+    - Command: args contains parsed command arguments
+    - Keyboard: event contains the key press event
+    - Programmatic: context can be customized
+    """
+
+    registry: "ActionRegistry"  # Reference to action registry
+    backend: Optional[Any] = None  # Backend instance (if available)
+    event: Optional[Any] = None  # KeyPress event for shortcuts
+    args: List[str] = field(default_factory=list)  # Command arguments
+    triggered_by: str = "unknown"  # How action was triggered
+    user_input: Optional[str] = None  # Original user input
+    headless_mode: bool = False  # Whether in headless mode
+    buffer: Optional[Any] = None  # Reference to input buffer (if applicable)
+    printer: Callable[[str], None] = print  # Output function for action messages
+
+    def __post_init__(self):
+        """Set triggered_by based on available context."""
+        logger.trace("ActionContext.__post_init__() entry")
+
+        if self.triggered_by == "unknown":
+            if self.event is not None:
+                self.triggered_by = "shortcut"
+            elif self.args or self.user_input:
+                self.triggered_by = "command"
+            else:
+                self.triggered_by = "programmatic"
+
+        logger.trace("ActionContext.__post_init__() exit")
+
+
+class ActionError(Exception):
+    """Base exception for action-related errors."""
+
+    def __init__(self, message: str, action_name: Optional[str] = None):
+        """
+        Initialize action error.
+
+        Args:
+            message: Error description
+            action_name: Name of action that caused error (optional)
+        """
+        logger.trace("ActionError.__init__() entry/exit")
+        super().__init__(message)
+        self.action_name = action_name
+
+
+class ActionValidationError(ActionError):
+    """Exception raised when action validation fails."""
+
+    pass
+
+
+class ActionExecutionError(ActionError):
+    """Exception raised when action execution fails."""
+
+    pass