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

parqv/data_sources/__init__.py

@@ -0,0 +1,48 @@
+"""
+Data sources package for parqv application.
+
+This package provides adapters for various data file formats,
+offering a unified interface for data access.
+"""
+
+# Base classes and exceptions
+from .base import (
+    DataHandler,
+    DataHandlerError,
+    DataSourceError,
+    FileValidationError,
+    UnsupportedFormatError,
+    DataReadError,
+    SchemaError,
+    MetadataError,
+)
+
+# Format-specific handlers
+from .formats import (
+    ParquetHandler,
+    ParquetHandlerError,
+    JsonHandler,
+    JsonHandlerError,
+    CsvHandler,
+    CsvHandlerError,
+)
+
+__all__ = [
+    # Base interface and exceptions
+    "DataHandler",
+    "DataHandlerError",
+    "DataSourceError",
+    "FileValidationError",
+    "UnsupportedFormatError", 
+    "DataReadError",
+    "SchemaError",
+    "MetadataError",
+    
+    # Format handlers
+    "ParquetHandler",
+    "ParquetHandlerError",
+    "JsonHandler",
+    "JsonHandlerError",
+    "CsvHandler",
+    "CsvHandlerError",
+]

parqv/data_sources/base/__init__.py

@@ -0,0 +1,28 @@
+"""
+Base classes and interfaces for data sources.
+"""
+
+from .handler import DataHandler
+from .exceptions import (
+    DataSourceError,
+    DataHandlerError,
+    FileValidationError,
+    UnsupportedFormatError,
+    DataReadError,
+    SchemaError,
+    MetadataError,
+)
+
+__all__ = [
+    # Base handler interface
+    "DataHandler",
+    
+    # Exception classes
+    "DataSourceError",
+    "DataHandlerError",
+    "FileValidationError",
+    "UnsupportedFormatError",
+    "DataReadError",
+    "SchemaError",
+    "MetadataError",
+] 

parqv/data_sources/base/exceptions.py

@@ -0,0 +1,38 @@
+"""
+Exception classes for data sources.
+"""
+
+
+class DataSourceError(Exception):
+    """Base exception for all data source errors."""
+    pass
+
+
+class DataHandlerError(DataSourceError):
+    """Base exception for all data handler errors."""
+    pass
+
+
+class FileValidationError(DataSourceError):
+    """Exception raised when file validation fails."""
+    pass
+
+
+class UnsupportedFormatError(DataSourceError):
+    """Exception raised when an unsupported file format is encountered."""
+    pass
+
+
+class DataReadError(DataSourceError):
+    """Exception raised when data reading fails."""
+    pass
+
+
+class SchemaError(DataSourceError):
+    """Exception raised when schema operations fail."""
+    pass
+
+
+class MetadataError(DataSourceError):
+    """Exception raised when metadata operations fail."""
+    pass 

parqv/{handlers/base_handler.py → data_sources/base/handler.py}

@@ -1,28 +1,28 @@
-import logging
+"""
+Base data handler interface for parqv data sources.
+"""
+
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 import pandas as pd
 
-log = logging.getLogger(__name__)
-
-
-class DataHandlerError(Exception):
-    """Base exception for all data handler errors."""
-    pass
+from ...core import get_logger
 
 
 class DataHandler(ABC):
     """
     Abstract Base Class for data handlers.
+    
     Defines the common interface required by the ParqV application
     to interact with different data file formats.
     """
 
     def __init__(self, file_path: Path):
         """
-        Initializes the handler with the file path.
+        Initialize the handler with the file path.
+        
         Subclasses should open the file or set up necessary resources here.
 
         Args:
@@ -32,11 +32,13 @@ class DataHandler(ABC):
             DataHandlerError: If initialization fails (e.g., file not found, format error).
         """
         self.file_path = file_path
+        self.logger = get_logger(f"{self.__class__.__module__}.{self.__class__.__name__}")
 
     @abstractmethod
     def close(self) -> None:
         """
-        Closes any open resources (files, connections, etc.).
+        Close any open resources (files, connections, etc.).
+        
         Must be implemented by subclasses.
         """
         pass
@@ -44,7 +46,8 @@ class DataHandler(ABC):
     @abstractmethod
     def get_metadata_summary(self) -> Dict[str, Any]:
         """
-        Returns a dictionary containing summary metadata about the data source.
+        Get a dictionary containing summary metadata about the data source.
+        
         Keys should be human-readable strings. Values can be of various types.
         Should include an 'error' key if metadata retrieval fails.
 
@@ -54,13 +57,14 @@ class DataHandler(ABC):
         pass
 
     @abstractmethod
-    def get_schema_data(self) -> Optional[List[Dict[str, str]]]:
+    def get_schema_data(self) -> Optional[List[Dict[str, Any]]]:
         """
-        Returns the schema as a list of dictionaries.
+        Get the schema as a list of dictionaries.
+        
         Each dictionary should represent a column and ideally contain keys:
-        'name' (str): Column name.
-        'type' (str): Formatted data type string.
-        'nullable' (Any): Indicator of nullability (e.g., bool, str "YES"/"NO").
+        - 'name' (str): Column name.
+        - 'type' (str): Formatted data type string.
+        - 'nullable' (Any): Indicator of nullability (e.g., bool, str "YES"/"NO").
 
         Returns:
             A list of schema dictionaries, an empty list if no columns,
@@ -71,7 +75,7 @@ class DataHandler(ABC):
     @abstractmethod
     def get_data_preview(self, num_rows: int = 50) -> Optional[pd.DataFrame]:
         """
-        Fetches a preview of the data.
+        Fetch a preview of the data.
 
         Args:
             num_rows: The maximum number of rows to fetch.
@@ -85,14 +89,15 @@ class DataHandler(ABC):
     @abstractmethod
     def get_column_stats(self, column_name: str) -> Dict[str, Any]:
         """
-        Calculates and returns statistics for a specific column.
+        Calculate and return statistics for a specific column.
+        
         The returned dictionary should ideally contain keys like:
-        'column' (str): Column name.
-        'type' (str): Formatted data type string.
-        'nullable' (Any): Nullability indicator.
-        'calculated' (Dict[str, Any]): Dictionary of computed statistics.
-        'error' (Optional[str]): Error message if calculation failed.
-        'message' (Optional[str]): Informational message.
+        - 'column' (str): Column name.
+        - 'type' (str): Formatted data type string.
+        - 'nullable' (Any): Nullability indicator.
+        - 'calculated' (Dict[str, Any]): Dictionary of computed statistics.
+        - 'error' (Optional[str]): Error message if calculation failed.
+        - 'message' (Optional[str]): Informational message.
 
         Args:
             column_name: The name of the column.
@@ -102,8 +107,16 @@ class DataHandler(ABC):
         """
         pass
 
-    def _format_size(self, num_bytes: int) -> str:
-        """Formats bytes into a human-readable string."""
+    def format_size(self, num_bytes: int) -> str:
+        """
+        Format bytes into a human-readable string.
+        
+        Args:
+            num_bytes: Number of bytes to format
+            
+        Returns:
+            Human-readable size string
+        """
         if num_bytes < 1024:
             return f"{num_bytes} bytes"
         elif num_bytes < 1024 ** 2:
@@ -112,3 +125,19 @@ class DataHandler(ABC):
             return f"{num_bytes / 1024 ** 2:.1f} MB"
         else:
             return f"{num_bytes / 1024 ** 3:.1f} GB"
+
+    def __enter__(self):
+        """Enter the runtime context related to this object."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the runtime context related to this object, ensuring cleanup."""
+        self.close()
+
+    def __del__(self):
+        """Attempt to close the handler when the object is garbage collected (best effort)."""
+        try:
+            self.close()
+        except Exception:
+            # Ignore exceptions during garbage collection
+            pass

parqv/{handlers → data_sources/formats}/__init__.py

@@ -1,13 +1,21 @@
-# src/parqv/handlers/__init__.py
-from .base_handler import DataHandler, DataHandlerError
+"""
+Format-specific data handlers for parqv.
+"""
+
 from .parquet import ParquetHandler, ParquetHandlerError
 from .json import JsonHandler, JsonHandlerError
+from .csv import CsvHandler, CsvHandlerError
 
 __all__ = [
-    "DataHandler",
-    "DataHandlerError",
+    # Parquet format
     "ParquetHandler",
     "ParquetHandlerError",
+    
+    # JSON format  
     "JsonHandler",
     "JsonHandlerError",
-]
+    
+    # CSV format
+    "CsvHandler",
+    "CsvHandlerError",
+]