SSF Tools - Rich Output Interface¶

Overview¶

The Rich Output Interface provides a unified, consistent approach to terminal output across all SSF Tools commands. It centralizes styling, progress tracking, status messaging, and user interaction to ensure a professional and cohesive user experience. This service is implemented using the rich library and adheres to SOLID principles for dependency injection.

Architectural Principles¶

Design Goals¶

Consistency: Ensure uniform output styling across all commands.
Flexibility: Support various output modes (quiet, verbose, no color).
Testability: Enable mocking for unit tests.
Extensibility: Facilitate easy addition of new output features.

Key Benefits¶

Improved User Experience: Clear and visually appealing terminal output.
Centralized Management: Single interface for all output operations.
Enhanced Debugging: Verbose mode for detailed logs.
Error Handling: Rich error panels for detailed feedback.
Progress Tracking: Context managers for progress bars and spinners.

Architecture Overview¶

graph TD subgraph Core Services A[RichOutputService] end subgraph Dependencies B[Rich Library] end subgraph Example Consumers C[FileAnalyzer] D[NetworkManager] E[ErrorHandler] end A --> B C -->|"Uses progress bar"| A D -->|"Logs info/warning/error"| A E -->|"Displays error panels"| A

Rich Output Protocols¶

OutputInterface¶

Defines the contract for the Rich Output Service.

from typing import Protocol, Any, ContextManager
from enum import Enum

class MessageSeverity(Enum):
    SUCCESS = "success"
    INFO = "info"
    WARNING = "warning"
    ERROR = "error"
    CRITICAL = "critical"

class OutputInterface(Protocol):
    def success(self, message: str, **kwargs) -> None: ...
    def info(self, message: str, **kwargs) -> None: ...
    def warning(self, message: str, **kwargs) -> None: ...
    def error(self, message: str, **kwargs) -> None: ...
    def critical(self, message: str, **kwargs) -> None: ...
    def status(self, message: str, severity: MessageSeverity, **kwargs) -> None: ...
    def progress(self, description: str) -> ContextManager: ...
    def spinner(self, message: str) -> ContextManager: ...

Configuration Models¶

Rich Output Configuration¶

# In ssf-tools-config.yaml
rich_output:
  quiet: false
  verbose: false
  no_color: false
  width: 80

Service Implementation¶

RichOutputService¶

The RichOutputService implements the OutputInterface protocol and provides methods for styled terminal output.

from rich.console import Console
from rich.progress import Progress
from threading import Lock

class RichOutputService:
    def __init__(self, quiet: bool = False, verbose: bool = False, no_color: bool = False):
        self.console = Console(force_terminal=not no_color)
        self.quiet = quiet
        self.verbose = verbose
        self._lock = Lock()

    def success(self, message: str, **kwargs) -> None:
        if not self.quiet:
            with self._lock:
                self.console.print(f"[green]✓ {message}[/green]", **kwargs)

Container Integration¶

CoreContainer Registration¶

The RichOutputService is registered as a singleton in the CoreContainer.

from dependency_injector import containers, providers
from kp_ssf_tools.core.services.rich_output import RichOutputService

class CoreContainer(containers.DeclarativeContainer):
    rich_output = providers.Singleton(RichOutputService, quiet=False, verbose=False, no_color=False)

CLI Integration¶

Command Registration¶

The RichOutputService is used in CLI commands for user feedback.

import click
from kp_ssf_tools.core.rich_output import init_rich_output

@click.command()
@click.option('--quiet', is_flag=True, help='Suppress non-essential output')
@click.option('--verbose', is_flag=True, help='Show detailed output')
def analyze(quiet, verbose):
    output = init_rich_output(quiet=quiet, verbose=verbose)
    output.info("Starting analysis...")

Usage Examples¶

Basic Operations¶

output.success("Operation completed successfully.")
output.warning("This is a warning message.")
output.error("An error occurred.")

Progress Tracking¶

with output.progress("Processing files...") as progress:
    task = progress.add_task("Processing", total=100)
    for _ in range(100):
        progress.advance(task)

Performance Considerations¶

Thread Safety¶

All methods use a thread-local lock to ensure safe concurrent access.

Resource Efficiency¶

Reuses console instances to minimize overhead.

Testing Patterns¶

Mocking the OutputInterface¶

class MockOutput:
    def success(self, message: str, **kwargs):
        print(f"SUCCESS: {message}")

Unit Tests¶

def test_success_message():
    mock_output = MockOutput()
    mock_output.success("Test passed.")

Implementation Roadmap¶

[x] Implement RichOutputService.
[x] Integrate with CoreContainer.
[x] Add CLI support.
[ ] Optimize performance for large-scale operations.