parqv 0.2.0__tar.gz → 0.3.0__tar.gz

{parqv-0.2.0/src/parqv.egg-info → parqv-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parqv
-Version: 0.2.0
+Version: 0.3.0
 Summary: An interactive Python TUI for visualizing, exploring, and analyzing files directly in your terminal.
 Author-email: Sangmin Yoon <sanspareilsmyn@gmail.com>
 License-Expression: Apache-2.0
@@ -23,14 +23,13 @@ Dynamic: license-file
 
 ---
 
-**Supported File Formats:** ✅ **Parquet** | ✅ **JSON** / **JSON Lines (ndjson)** | *(More planned!)*
+**Supported File Formats:** ✅ **Parquet** | ✅ **JSON** / **JSON Lines (ndjson)** | ✅ **CSV / TSV** | *(More planned!)*
 
 ---
 
-**`parqv` is a Python-based interactive TUI (Text User Interface) tool designed to explore, analyze, and understand various data file formats directly within your terminal.** Initially supporting Parquet and JSON, `parqv` aims to provide a unified, visual experience for quick data inspection without leaving your console.
-
-## 💻 Demo (Showing Parquet)
+**`parqv` is a Python-based interactive TUI (Text User Interface) tool designed to explore, analyze, and understand various data file formats directly within your terminal.** `parqv` aims to provide a unified, visual experience for quick data inspection without leaving your console.
 
+## 💻 Demo
 ![parqv.gif](assets/parqv.gif)
 *(Demo shows Parquet features; UI adapts for other formats)*
 
@@ -47,7 +46,7 @@ Dynamic: license-file
     *   **🔌 Extensible:** Designed with a handler interface to easily add support for more file formats in the future (like CSV, Arrow IPC, etc.).
 
 ## ✨ Features (TUI Mode)
-*   **Multi-Format Support:** Currently supports **Parquet** (`.parquet`) and **JSON/JSON Lines** (`.json`, `.ndjson`). Run `parqv <your_file.{parquet,json,ndjson}>`.
+*   **Multi-Format Support:** Now supports **Parquet** (`.parquet`), **JSON/JSON Lines** (`.json`, `.ndjson`), and **CSV/TSV** (`.csv`, `.tsv`). Run `parqv <your_file.{parquet,json,ndjson,csv,tsv}>`.
 *   **Metadata Panel:** Displays key file information (path, format, size, total rows, column count, etc.). *Fields may vary slightly depending on the file format.*
 *   **Schema Explorer:**
     *   Interactive list view of columns.

{parqv-0.2.0 → parqv-0.3.0}/README.md

@@ -7,14 +7,13 @@
 
 ---
 
-**Supported File Formats:** ✅ **Parquet** | ✅ **JSON** / **JSON Lines (ndjson)** | *(More planned!)*
+**Supported File Formats:** ✅ **Parquet** | ✅ **JSON** / **JSON Lines (ndjson)** | ✅ **CSV / TSV** | *(More planned!)*
 
 ---
 
-**`parqv` is a Python-based interactive TUI (Text User Interface) tool designed to explore, analyze, and understand various data file formats directly within your terminal.** Initially supporting Parquet and JSON, `parqv` aims to provide a unified, visual experience for quick data inspection without leaving your console.
-
-## 💻 Demo (Showing Parquet)
+**`parqv` is a Python-based interactive TUI (Text User Interface) tool designed to explore, analyze, and understand various data file formats directly within your terminal.** `parqv` aims to provide a unified, visual experience for quick data inspection without leaving your console.
 
+## 💻 Demo
 ![parqv.gif](assets/parqv.gif)
 *(Demo shows Parquet features; UI adapts for other formats)*
 
@@ -31,7 +30,7 @@
     *   **🔌 Extensible:** Designed with a handler interface to easily add support for more file formats in the future (like CSV, Arrow IPC, etc.).
 
 ## ✨ Features (TUI Mode)
-*   **Multi-Format Support:** Currently supports **Parquet** (`.parquet`) and **JSON/JSON Lines** (`.json`, `.ndjson`). Run `parqv <your_file.{parquet,json,ndjson}>`.
+*   **Multi-Format Support:** Now supports **Parquet** (`.parquet`), **JSON/JSON Lines** (`.json`, `.ndjson`), and **CSV/TSV** (`.csv`, `.tsv`). Run `parqv <your_file.{parquet,json,ndjson,csv,tsv}>`.
 *   **Metadata Panel:** Displays key file information (path, format, size, total rows, column count, etc.). *Fields may vary slightly depending on the file format.*
 *   **Schema Explorer:**
     *   Interactive list view of columns.
@@ -85,4 +84,4 @@
 
 ## 📄 License
 
-Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.

{parqv-0.2.0 → parqv-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "parqv"
-version = "0.2.0"
+version = "0.3.0"
 description = "An interactive Python TUI for visualizing, exploring, and analyzing files directly in your terminal."
 readme = "README.md"
 requires-python = ">=3.10"

parqv-0.3.0/src/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-0.3.0/src/parqv/app.py

@@ -0,0 +1,150 @@
+from pathlib import Path
+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 .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 = get_logger(__name__)
+
+
+class ParqV(App[None]):
+    """A Textual app to visualize Parquet or JSON files."""
+
+    CSS_PATH = CSS_PATH
+    BINDINGS = [
+        Binding("q", "quit", "Quit", priority=True),
+    ]
+
+    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)
+        
+        # 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.debug(f"Displaying error message: {self.error_message}")
+            yield Container(
+                Label("Error Loading File:", classes="error-title"),
+                Static(self.error_message, classes="error-content"),
+                id="error-container"
+            )
+        elif self.handler:
+            log.debug(f"Composing main layout with TabbedContent for {self.handler_type} handler.")
+            with TabbedContent(id="main-tabs"):
+                yield TabPane("Metadata", MetadataView(id="metadata-view"), id="tab-metadata")
+                yield TabPane("Schema", SchemaView(id="schema-view"), id="tab-schema")
+                yield TabPane("Data Preview", DataView(id="data-view"), id="tab-data")
+        else:
+            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)
+            
+            if self.handler and self.file_path and self.handler_type:
+                display_name = self.file_path.name
+                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 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}")
+
+
+# For backward compatibility, keep the old CLI entry point
+def run_app():
+    """
+    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__":
+    run_app()

parqv-0.3.0/src/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-0.3.0/src/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-0.3.0/src/parqv/core/config.py

@@ -0,0 +1,26 @@
+"""
+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",
+    ".csv": "csv"
+}
+
+# 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-0.3.0/src/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-0.3.0/src/parqv/core/handler_factory.py

@@ -0,0 +1,90 @@
+"""
+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, CsvHandler
+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,
+        "csv": CsvHandler,
+    }
+    
+    @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-0.3.0/src/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)