parqv 0.1.0__tar.gz → 0.2.1__tar.gz

parqv-0.2.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: parqv
+Version: 0.2.1
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=1.0.0
+Requires-Dist: pyarrow>=16.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: duckdb>=1.2.0
+Dynamic: license-file
+
+# parqv
+
+[![Python Version](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![PyPI version](https://badge.fury.io/py/parqv.svg)](https://badge.fury.io/py/parqv) <!-- TODO: Link after first PyPI release -->
+[![Built with Textual](https://img.shields.io/badge/Built%20with-Textual-blueviolet.svg)](https://textual.textualize.io/)
+
+---
+
+**Supported File Formats:** ✅ **Parquet** | ✅ **JSON** / **JSON Lines (ndjson)** | *(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
+
+![parqv.gif](assets/parqv.gif)
+*(Demo shows Parquet features; UI adapts for other formats)*
+
+## 🤔 Why `parqv`?
+1.  **Unified Interface:** Launch `parqv <your_data_file>` to access **metadata, schema, data preview, and column statistics** all within a single, navigable terminal window. No more juggling different commands for different file types.
+2.  **Interactive Exploration:**
+    *   **🖱️ Keyboard & Mouse Driven:** Navigate using familiar keys (arrows, `hjkl`, Tab) or even your mouse (thanks to `Textual`).
+    *   **📜 Scrollable Views:** Easily scroll through large schemas, data tables, or column lists.
+    *   **🌲 Clear Schema View:** Understand column names, data types, and nullability at a glance. (Complex nested structures visualization might vary by format).
+    *   **📊 Dynamic Stats:** Select a column and instantly see its detailed statistics (counts, nulls, min/max, mean, distinct values, etc.).
+3.  **Cross-Format Consistency:**
+    *   **🎨 Rich Display:** Leverages `rich` and `Textual` for colorful, readable tables and text across supported formats.
+    *   **📈 Quick Stats:** Get key statistical insights consistently, regardless of the underlying file type.
+    *   **🔌 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}>`.
+*   **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.
+    *   Clearly shows column names, data types, and nullability.
+*   **Data Table Viewer:**
+    *   Scrollable table preview of the file's data.
+    *   Attempts to preserve data types for better representation.
+*   **Column Statistics Viewer:**
+    *   Select a column in the Schema tab to view detailed statistics.
+    *   Shows counts (total, valid, null), percentages, and type-specific stats (min/max, mean, stddev, distinct counts, length stats, boolean value counts where applicable).
+*   **Row Group Inspector (Parquet Specific):**
+    *   *This panel only appears when viewing Parquet files.*
+    *   Lists row groups with stats (row count, compressed/uncompressed size).
+    *   (Planned) Select a row group for more details.
+
+## 🚀 Getting Started
+
+**1. Prerequisites:**
+*   **Python:** Version 3.10 or higher.
+*   **pip:** The Python package installer.
+
+**2. Install `parqv`:**
+*   Open your terminal and run:
+    ```bash
+    pip install parqv
+    ```
+    *(This will also install dependencies like `textual`, `pyarrow`, `pandas`, and `duckdb`)*
+*   **Updating `parqv`:**
+    ```bash
+    pip install --upgrade parqv
+    ```
+
+**3. Run `parqv`:**
+*   Point `parqv` to your data file:
+    ```bash
+    #parquet
+    parqv /path/to/your/data.parquet
+    
+    # json
+    parqv /path/to/your/data.json
+*   The interactive TUI will launch. Use your keyboard (and mouse, if supported by your terminal) to navigate:
+    *   **Arrow Keys / `j`,`k` (in lists):** Move selection up/down.
+    *   **`Tab` / `Shift+Tab`:** Cycle focus between the main tab content and potentially other areas. (Focus handling might evolve).
+    *   **`Enter` (in column list):** Select a column to view statistics.
+    *   **View Switching:** Use `Ctrl+N` (Next Tab) and `Ctrl+P` (Previous Tab) or click on the tabs (Metadata, Schema, Data Preview).
+    *   **Scrolling:** Use `PageUp` / `PageDown` / `Home` / `End` or arrow keys/mouse wheel within scrollable areas (like Schema stats or Data Preview).
+    *   **`q` / `Ctrl+C`:** Quit `parqv`.
+    *   *(Help Screen `?` is planned)*
+
+---
+
+## 📄 License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.

parqv-0.2.1/README.md

@@ -0,0 +1,88 @@
+# parqv
+
+[![Python Version](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![PyPI version](https://badge.fury.io/py/parqv.svg)](https://badge.fury.io/py/parqv) <!-- TODO: Link after first PyPI release -->
+[![Built with Textual](https://img.shields.io/badge/Built%20with-Textual-blueviolet.svg)](https://textual.textualize.io/)
+
+---
+
+**Supported File Formats:** ✅ **Parquet** | ✅ **JSON** / **JSON Lines (ndjson)** | *(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
+
+![parqv.gif](assets/parqv.gif)
+*(Demo shows Parquet features; UI adapts for other formats)*
+
+## 🤔 Why `parqv`?
+1.  **Unified Interface:** Launch `parqv <your_data_file>` to access **metadata, schema, data preview, and column statistics** all within a single, navigable terminal window. No more juggling different commands for different file types.
+2.  **Interactive Exploration:**
+    *   **🖱️ Keyboard & Mouse Driven:** Navigate using familiar keys (arrows, `hjkl`, Tab) or even your mouse (thanks to `Textual`).
+    *   **📜 Scrollable Views:** Easily scroll through large schemas, data tables, or column lists.
+    *   **🌲 Clear Schema View:** Understand column names, data types, and nullability at a glance. (Complex nested structures visualization might vary by format).
+    *   **📊 Dynamic Stats:** Select a column and instantly see its detailed statistics (counts, nulls, min/max, mean, distinct values, etc.).
+3.  **Cross-Format Consistency:**
+    *   **🎨 Rich Display:** Leverages `rich` and `Textual` for colorful, readable tables and text across supported formats.
+    *   **📈 Quick Stats:** Get key statistical insights consistently, regardless of the underlying file type.
+    *   **🔌 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}>`.
+*   **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.
+    *   Clearly shows column names, data types, and nullability.
+*   **Data Table Viewer:**
+    *   Scrollable table preview of the file's data.
+    *   Attempts to preserve data types for better representation.
+*   **Column Statistics Viewer:**
+    *   Select a column in the Schema tab to view detailed statistics.
+    *   Shows counts (total, valid, null), percentages, and type-specific stats (min/max, mean, stddev, distinct counts, length stats, boolean value counts where applicable).
+*   **Row Group Inspector (Parquet Specific):**
+    *   *This panel only appears when viewing Parquet files.*
+    *   Lists row groups with stats (row count, compressed/uncompressed size).
+    *   (Planned) Select a row group for more details.
+
+## 🚀 Getting Started
+
+**1. Prerequisites:**
+*   **Python:** Version 3.10 or higher.
+*   **pip:** The Python package installer.
+
+**2. Install `parqv`:**
+*   Open your terminal and run:
+    ```bash
+    pip install parqv
+    ```
+    *(This will also install dependencies like `textual`, `pyarrow`, `pandas`, and `duckdb`)*
+*   **Updating `parqv`:**
+    ```bash
+    pip install --upgrade parqv
+    ```
+
+**3. Run `parqv`:**
+*   Point `parqv` to your data file:
+    ```bash
+    #parquet
+    parqv /path/to/your/data.parquet
+    
+    # json
+    parqv /path/to/your/data.json
+*   The interactive TUI will launch. Use your keyboard (and mouse, if supported by your terminal) to navigate:
+    *   **Arrow Keys / `j`,`k` (in lists):** Move selection up/down.
+    *   **`Tab` / `Shift+Tab`:** Cycle focus between the main tab content and potentially other areas. (Focus handling might evolve).
+    *   **`Enter` (in column list):** Select a column to view statistics.
+    *   **View Switching:** Use `Ctrl+N` (Next Tab) and `Ctrl+P` (Previous Tab) or click on the tabs (Metadata, Schema, Data Preview).
+    *   **Scrolling:** Use `PageUp` / `PageDown` / `Home` / `End` or arrow keys/mouse wheel within scrollable areas (like Schema stats or Data Preview).
+    *   **`q` / `Ctrl+C`:** Quit `parqv`.
+    *   *(Help Screen `?` is planned)*
+
+---
+
+## 📄 License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full license text.

{parqv-0.1.0 → parqv-0.2.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "parqv"
-version = "0.1.0"
-description = "An interactive Python TUI for visualizing, exploring, and analyzing Parquet files directly in your terminal."
+version = "0.2.1"
+description = "An interactive Python TUI for visualizing, exploring, and analyzing files directly in your terminal."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
@@ -15,7 +15,8 @@ dependencies = [
     "textual>=1.0.0",
     "pyarrow>=16.0.0",
     "pandas>=2.0.0",
-    "numpy>=1.20.0"
+    "numpy>=1.20.0",
+    "duckdb>=1.2.0"
 ]
 
 [project.scripts]

parqv-0.2.1/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.2.1/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.2.1/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.2.1/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.2.1/src/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-0.2.1/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