parqv 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

parqv/__init__.py

@@ -0,0 +1,31 @@
+"""
+parqv - A Textual application for visualizing Parquet and JSON files.
+"""
+
+from .app import ParqV
+from .cli import run_app
+from .core import (
+    SUPPORTED_EXTENSIONS, 
+    DEFAULT_PREVIEW_ROWS,
+    FileValidationError, 
+    validate_and_detect_file,
+    HandlerFactory, 
+    HandlerCreationError,
+    setup_logging, 
+    get_logger
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ParqV",
+    "run_app", 
+    "SUPPORTED_EXTENSIONS",
+    "DEFAULT_PREVIEW_ROWS",
+    "FileValidationError",
+    "validate_and_detect_file",
+    "HandlerFactory",
+    "HandlerCreationError",
+    "setup_logging",
+    "get_logger",
+]

parqv/app.py

@@ -1,104 +1,77 @@
-import logging
-import sys
-from logging.handlers import RotatingFileHandler
 from pathlib import Path
-from typing import Optional, Type
+from typing import Optional
 
 from textual.app import App, ComposeResult, Binding
 from textual.containers import Container
 from textual.widgets import Header, Footer, Static, Label, TabbedContent, TabPane
 
-from .handlers import (
-    DataHandler,
-    DataHandlerError,
-    ParquetHandler,
-    JsonHandler,
-)
+from .core import CSS_PATH, FileValidationError, validate_and_detect_file, HandlerFactory, HandlerCreationError, get_logger
+from .data_sources import DataHandler
 from .views.data_view import DataView
 from .views.metadata_view import MetadataView
 from .views.schema_view import SchemaView
 
-LOG_FILENAME = "parqv.log"
-file_handler = RotatingFileHandler(
-    LOG_FILENAME, maxBytes=1024 * 1024 * 5, backupCount=3, encoding="utf-8"
-)
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s [%(levelname)-5.5s] %(name)s (%(filename)s:%(lineno)d) - %(message)s",
-    handlers=[file_handler, logging.StreamHandler(sys.stdout)],
-)
-log = logging.getLogger(__name__)
-
-AnyHandler = DataHandler
-AnyHandlerError = DataHandlerError
+log = get_logger(__name__)
 
 
 class ParqV(App[None]):
     """A Textual app to visualize Parquet or JSON files."""
 
-    CSS_PATH = "parqv.css"
+    CSS_PATH = CSS_PATH
     BINDINGS = [
         Binding("q", "quit", "Quit", priority=True),
     ]
 
-    # App State
-    file_path: Optional[Path] = None
-    handler: Optional[AnyHandler] = None  # Use ABC type hint
-    handler_type: Optional[str] = None  # Keep for display ('parquet', 'json')
-    error_message: Optional[str] = None
-
     def __init__(self, file_path_str: Optional[str] = None, *args, **kwargs):
+        """
+        Initialize the ParqV application.
+        
+        Args:
+            file_path_str: Path to the file to visualize
+            *args, **kwargs: Additional arguments for the Textual App
+        """
         super().__init__(*args, **kwargs)
-        if not file_path_str:
-            self.error_message = "No file path provided."
-            log.error(self.error_message)
-            return
-
-        self.file_path = Path(file_path_str)
-        log.debug(f"Input file path: {self.file_path}")
-
-        if not self.file_path.is_file():
-            self.error_message = f"File not found or is not a regular file: {self.file_path}"
-            log.error(self.error_message)
-            return
-
-        # Handler Detection
-        handler_class: Optional[Type[AnyHandler]] = None
-        handler_error_class: Type[AnyHandlerError] = DataHandlerError
-        detected_type = "unknown"
-        file_suffix = self.file_path.suffix.lower()
-
-        if file_suffix == ".parquet":
-            log.info("Detected '.parquet' extension, using ParquetHandler.")
-            handler_class = ParquetHandler
-            detected_type = "parquet"
-        elif file_suffix in [".json", ".ndjson"]:
-            log.info(f"Detected '{file_suffix}' extension, using JsonHandler.")
-            handler_class = JsonHandler
-            detected_type = "json"
-        else:
-            self.error_message = f"Unsupported file extension: '{file_suffix}'. Only .parquet, .json, .ndjson are supported."
-            log.error(self.error_message)
-            return
-
-        # Instantiate Handler
-        if handler_class:
-            log.info(f"Attempting to initialize {detected_type.capitalize()} handler for: {self.file_path}")
-            try:
-                self.handler = handler_class(self.file_path)
-                self.handler_type = detected_type
-                log.info(f"{detected_type.capitalize()} handler initialized successfully.")
-            except DataHandlerError as e:
-                self.error_message = f"Failed to initialize {detected_type} handler: {e}"
-                log.error(self.error_message, exc_info=True)
-            except Exception as e:
-                self.error_message = f"An unexpected error occurred during {detected_type} handler initialization: {e}"
-                log.exception(f"Unexpected error during {detected_type} handler initialization:")
+        
+        # Application state
+        self.file_path: Optional[Path] = None
+        self.handler: Optional[DataHandler] = None
+        self.handler_type: Optional[str] = None
+        self.error_message: Optional[str] = None
+        
+        # Initialize with file if provided
+        if file_path_str:
+            self._initialize_file_handler(file_path_str)
+
+    def _initialize_file_handler(self, file_path_str: str) -> None:
+        """
+        Initialize the file handler for the given file path.
+        
+        Args:
+            file_path_str: Path to the file to process
+        """
+        try:
+            # Validate file and detect type
+            self.file_path, self.handler_type = validate_and_detect_file(file_path_str)
+            
+            # Create appropriate handler
+            self.handler = HandlerFactory.create_handler(self.file_path, self.handler_type)
+            
+            log.info(f"Successfully initialized {self.handler_type} handler for: {self.file_path.name}")
+            
+        except (FileValidationError, HandlerCreationError) as e:
+            self.error_message = str(e)
+            log.error(f"Failed to initialize handler: {e}")
+            
+        except Exception as e:
+            self.error_message = f"An unexpected error occurred: {e}"
+            log.exception("Unexpected error during handler initialization")
 
     def compose(self) -> ComposeResult:
+        """Compose the UI layout."""
         yield Header()
+        
         if self.error_message:
-            log.error(f"Displaying error message: {self.error_message}")
+            log.debug(f"Displaying error message: {self.error_message}")
             yield Container(
                 Label("Error Loading File:", classes="error-title"),
                 Static(self.error_message, classes="error-content"),
@@ -111,57 +84,66 @@ class ParqV(App[None]):
                 yield TabPane("Schema", SchemaView(id="schema-view"), id="tab-schema")
                 yield TabPane("Data Preview", DataView(id="data-view"), id="tab-data")
         else:
-            log.error("Compose called but no handler and no error message. Initialization likely failed silently.")
-            yield Container(Label("Initialization failed."), id="init-failed")
+            log.warning("No handler available and no error message set")
+            yield Container(
+                Label("No file loaded.", classes="error-title"),
+                Static("Please provide a valid file path.", classes="error-content"),
+                id="no-file-container"
+            )
+            
         yield Footer()
 
     def on_mount(self) -> None:
+        """Handle app mount event - set up header information."""
         log.debug("App mounted.")
+        self._update_header()
+
+    def _update_header(self) -> None:
+        """Update the header with file and format information."""
         try:
             header = self.query_one(Header)
-            display_name = "N/A"
-            format_name = "Unknown"
-            if self.handler and self.file_path:
+            
+            if self.handler and self.file_path and self.handler_type:
                 display_name = self.file_path.name
-                format_name = self.handler_type.capitalize() if self.handler_type else "Unknown"
+                format_name = self.handler_type.capitalize()
                 header.title = f"parqv - {display_name}"
                 header.sub_title = f"Format: {format_name}"
             elif self.error_message:
                 header.title = "parqv - Error"
+                header.sub_title = "Failed to load file"
             else:
                 header.title = "parqv"
+                header.sub_title = "File Viewer"
+                
         except Exception as e:
-            log.error(f"Failed to set header title: {e}")
+            log.error(f"Failed to update header: {e}")
 
     def action_quit(self) -> None:
+        """Handle quit action - cleanup and exit."""
         log.info("Quit action triggered.")
+        self._cleanup()
+        self.exit()
+
+    def _cleanup(self) -> None:
+        """Clean up resources before exit."""
         if self.handler:
             try:
                 self.handler.close()
+                log.info("Handler closed successfully.")
             except Exception as e:
                 log.error(f"Error during handler cleanup: {e}")
-        self.exit()
 
 
-# CLI Entry Point
+# For backward compatibility, keep the old CLI entry point
 def run_app():
-    log.info("--- parqv (ABC Handler) started ---")
-    if len(sys.argv) < 2:
-        print("Usage: parqv <path_to_parquet_or_json_file>")
-        log.error("No file path provided.")
-        sys.exit(1)
-
-    file_path_str = sys.argv[1]
-    log.debug(f"File path from argument: {file_path_str}")
-
-    _path = Path(file_path_str)
-    if not _path.suffix.lower() in ['.parquet', '.json', '.ndjson']:
-        print(f"Error: Unsupported file type '{_path.suffix}'. Please provide a .parquet, .json, or .ndjson file.")
-        log.error(f"Unsupported file type provided via CLI: {_path.suffix}")
-        sys.exit(1)
-
-    app = ParqV(file_path_str=file_path_str)
-    app.run()
+    """
+    Legacy CLI entry point for backward compatibility.
+    
+    Note: New code should use parqv.cli.run_app() instead.
+    """
+    from .cli import run_app as new_run_app
+    log.warning("Using legacy run_app(). Consider importing from parqv.cli instead.")
+    new_run_app()
 
 
 if __name__ == "__main__":

parqv/cli.py

@@ -0,0 +1,112 @@
+"""
+Command Line Interface for parqv application.
+"""
+
+import sys
+
+from .app import ParqV
+from .core import SUPPORTED_EXTENSIONS, FileValidationError, validate_and_detect_file, setup_logging, get_logger
+
+
+def _print_user_message(message: str, log_level: str = "info") -> None:
+    """
+    Show a message to the user and log it.
+    
+    Args:
+        message: message to display and log
+        log_level: log level ('info', 'error', 'warning')
+    """
+    log = get_logger(__name__)
+
+    print(message, file=sys.stderr)
+
+    if log_level == "error":
+        log.error(message)
+    elif log_level == "warning":
+        log.warning(message)
+    else:
+        log.info(message)
+
+
+def validate_cli_arguments() -> str:
+    """
+    Validates command line arguments.
+    
+    Returns:
+        The file path string from command line arguments
+        
+    Raises:
+        SystemExit: If arguments are invalid
+    """
+    log = get_logger(__name__)
+
+    if len(sys.argv) < 2:
+        usage_message = "Usage: parqv <path_to_parquet_or_json_file>"
+        supported_message = f"Supported file types: {', '.join(SUPPORTED_EXTENSIONS.keys())}"
+
+        _print_user_message(usage_message, "error")
+        _print_user_message(supported_message, "info")
+
+        log.error("No file path provided via CLI arguments")
+        sys.exit(1)
+
+    file_path_str = sys.argv[1]
+    log.debug(f"File path received from CLI: {file_path_str}")
+    return file_path_str
+
+
+def run_app() -> None:
+    """
+    Main entry point for the parqv CLI application.
+    
+    This function:
+    1. Sets up logging
+    2. Validates command line arguments
+    3. Validates the file path and type
+    4. Creates and runs the Textual app
+    """
+    # Setup logging first
+    log = setup_logging()
+    log.info("--- parqv CLI started ---")
+
+    try:
+        # Get and validate CLI arguments
+        file_path_str = validate_cli_arguments()
+
+        # Validate file path and detect type (for early validation)
+        file_path, file_type = validate_and_detect_file(file_path_str)
+        log.info(f"File validated successfully: {file_path} (type: {file_type})")
+
+        # Create and run the app
+        log.info("Starting parqv application...")
+        app = ParqV(file_path_str=file_path_str)
+        app.run()
+
+        log.info("parqv application finished successfully")
+
+    except FileValidationError as e:
+        log.error(f"File validation failed: {e}")
+
+        error_message = f"Error: {e}"
+        help_message = f"Please provide a file with one of these extensions: {', '.join(SUPPORTED_EXTENSIONS.keys())}"
+
+        _print_user_message(error_message, "error")
+        _print_user_message(help_message, "info")
+
+        log.error("Exiting due to file validation error")
+        sys.exit(1)
+
+    except KeyboardInterrupt:
+        log.info("Application interrupted by user (Ctrl+C)")
+        _print_user_message("\nApplication interrupted by user.", "info")
+        sys.exit(0)
+
+    except Exception as e:
+        log.exception(f"Unexpected error in CLI: {e}")
+        _print_user_message(f"An unexpected error occurred: {e}", "error")
+        _print_user_message("Check the log file for more details.", "info")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    run_app()

parqv/core/__init__.py

@@ -0,0 +1,31 @@
+"""
+Core modules for parqv application.
+
+This package contains fundamental configuration, utilities, and factory classes.
+"""
+
+from .config import SUPPORTED_EXTENSIONS, DEFAULT_PREVIEW_ROWS, CSS_PATH
+from .logging import setup_logging, get_logger
+from .file_utils import FileValidationError, validate_and_detect_file, validate_file_path, detect_file_type
+from .handler_factory import HandlerFactory, HandlerCreationError
+
+__all__ = [
+    # Configuration
+    "SUPPORTED_EXTENSIONS",
+    "DEFAULT_PREVIEW_ROWS", 
+    "CSS_PATH",
+    
+    # Logging
+    "setup_logging",
+    "get_logger",
+    
+    # File utilities
+    "FileValidationError",
+    "validate_and_detect_file",
+    "validate_file_path",
+    "detect_file_type",
+    
+    # Factory
+    "HandlerFactory",
+    "HandlerCreationError",
+] 

parqv/core/config.py

@@ -0,0 +1,25 @@
+"""
+Configuration constants and settings for parqv application.
+"""
+
+from typing import Dict, Type, List
+from pathlib import Path
+
+# File extensions and their corresponding handler types
+SUPPORTED_EXTENSIONS: Dict[str, str] = {
+    ".parquet": "parquet",
+    ".json": "json", 
+    ".ndjson": "json"
+}
+
+# Application constants
+LOG_FILENAME = "parqv.log"
+LOG_MAX_BYTES = 1024 * 1024 * 5  # 5MB
+LOG_BACKUP_COUNT = 3
+LOG_ENCODING = "utf-8"
+
+# UI Constants
+DEFAULT_PREVIEW_ROWS = 50
+
+# CSS Path (relative to the app module)
+CSS_PATH = "parqv.css" 

parqv/core/file_utils.py

@@ -0,0 +1,88 @@
+"""
+File utilities for parqv application.
+"""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+from .config import SUPPORTED_EXTENSIONS
+from .logging import get_logger
+
+log = get_logger(__name__)
+
+
+class FileValidationError(Exception):
+    """Exception raised when file validation fails."""
+    pass
+
+
+def validate_file_path(file_path_str: Optional[str]) -> Path:
+    """
+    Validates and resolves the file path.
+    
+    Args:
+        file_path_str: String representation of the file path
+        
+    Returns:
+        Resolved Path object
+        
+    Raises:
+        FileValidationError: If file path is invalid or file doesn't exist
+    """
+    if not file_path_str:
+        raise FileValidationError("No file path provided.")
+    
+    file_path = Path(file_path_str)
+    log.debug(f"Validating file path: {file_path}")
+    
+    if not file_path.is_file():
+        raise FileValidationError(f"File not found or is not a regular file: {file_path}")
+    
+    return file_path
+
+
+def detect_file_type(file_path: Path) -> str:
+    """
+    Detects the file type based on its extension.
+    
+    Args:
+        file_path: Path object representing the file
+        
+    Returns:
+        String representing the detected file type ('parquet' or 'json')
+        
+    Raises:
+        FileValidationError: If file extension is not supported
+    """
+    file_suffix = file_path.suffix.lower()
+    
+    if file_suffix not in SUPPORTED_EXTENSIONS:
+        supported_exts = ", ".join(SUPPORTED_EXTENSIONS.keys())
+        raise FileValidationError(
+            f"Unsupported file extension: '{file_suffix}'. "
+            f"Only {supported_exts} are supported."
+        )
+    
+    detected_type = SUPPORTED_EXTENSIONS[file_suffix]
+    log.info(f"Detected '{file_suffix}' extension, type: {detected_type}")
+    
+    return detected_type
+
+
+def validate_and_detect_file(file_path_str: Optional[str]) -> Tuple[Path, str]:
+    """
+    Convenience function that validates file path and detects file type.
+    
+    Args:
+        file_path_str: String representation of the file path
+        
+    Returns:
+        Tuple of (validated_path, detected_type)
+        
+    Raises:
+        FileValidationError: If validation or type detection fails
+    """
+    file_path = validate_file_path(file_path_str)
+    file_type = detect_file_type(file_path)
+    
+    return file_path, file_type 

parqv/core/handler_factory.py

@@ -0,0 +1,89 @@
+"""
+Handler factory for creating appropriate data handlers based on file type.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from ..data_sources import DataHandler, DataHandlerError, ParquetHandler, JsonHandler
+from .logging import get_logger
+
+log = get_logger(__name__)
+
+
+class HandlerCreationError(Exception):
+    """Exception raised when handler creation fails."""
+    pass
+
+
+class HandlerFactory:
+    """Factory class for creating data handlers."""
+    
+    # Registry of handler types to handler classes
+    _HANDLER_REGISTRY = {
+        "parquet": ParquetHandler,
+        "json": JsonHandler,
+    }
+    
+    @classmethod
+    def create_handler(cls, file_path: Path, handler_type: str) -> DataHandler:
+        """
+        Creates an appropriate handler for the given file type.
+        
+        Args:
+            file_path: Path to the data file
+            handler_type: Type of handler to create ('parquet' or 'json')
+            
+        Returns:
+            An instance of the appropriate DataHandler subclass
+            
+        Raises:
+            HandlerCreationError: If handler creation fails
+        """
+        if handler_type not in cls._HANDLER_REGISTRY:
+            available_types = ", ".join(cls._HANDLER_REGISTRY.keys())
+            raise HandlerCreationError(
+                f"Unknown handler type: '{handler_type}'. "
+                f"Available types: {available_types}"
+            )
+        
+        handler_class = cls._HANDLER_REGISTRY[handler_type]
+        
+        log.info(f"Creating {handler_type.capitalize()} handler for: {file_path}")
+        
+        try:
+            handler = handler_class(file_path)
+            log.info(f"{handler_type.capitalize()} handler created successfully.")
+            return handler
+            
+        except DataHandlerError as e:
+            log.error(f"Failed to create {handler_type} handler: {e}")
+            raise HandlerCreationError(f"Failed to initialize {handler_type} handler: {e}") from e
+            
+        except Exception as e:
+            log.exception(f"Unexpected error creating {handler_type} handler")
+            raise HandlerCreationError(
+                f"Unexpected error during {handler_type} handler creation: {e}"
+            ) from e
+    
+    @classmethod
+    def get_supported_types(cls) -> list[str]:
+        """
+        Returns a list of supported handler types.
+        
+        Returns:
+            List of supported handler type strings
+        """
+        return list(cls._HANDLER_REGISTRY.keys())
+    
+    @classmethod
+    def register_handler(cls, handler_type: str, handler_class: type[DataHandler]) -> None:
+        """
+        Registers a new handler type (for extensibility).
+        
+        Args:
+            handler_type: String identifier for the handler type
+            handler_class: Class that implements DataHandler interface
+        """
+        log.info(f"Registering handler type '{handler_type}' with class {handler_class.__name__}")
+        cls._HANDLER_REGISTRY[handler_type] = handler_class 

parqv/core/logging.py

@@ -0,0 +1,46 @@
+"""
+Logging configuration for parqv application.
+"""
+
+import logging
+import sys
+from logging.handlers import RotatingFileHandler
+
+from .config import LOG_FILENAME, LOG_MAX_BYTES, LOG_BACKUP_COUNT, LOG_ENCODING
+
+
+def setup_logging() -> logging.Logger:
+    """
+    Sets up logging configuration for the parqv application.
+    
+    Returns:
+        The root logger instance configured for parqv.
+    """
+    file_handler = RotatingFileHandler(
+        LOG_FILENAME, 
+        maxBytes=LOG_MAX_BYTES, 
+        backupCount=LOG_BACKUP_COUNT, 
+        encoding=LOG_ENCODING
+    )
+    
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)-5.5s] %(name)s (%(filename)s:%(lineno)d) - %(message)s",
+        handlers=[file_handler, logging.StreamHandler(sys.stdout)],
+        force=True  # Override any existing configuration
+    )
+    
+    return logging.getLogger(__name__)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Gets a logger instance for the given name.
+    
+    Args:
+        name: The name for the logger (typically __name__)
+        
+    Returns:
+        A logger instance.
+    """
+    return logging.getLogger(name)