splurge-dsv 2025.1.0__py3-none-any.whl → 2025.1.2__py3-none-any.whl

splurge_dsv/__init__.py

@@ -0,0 +1,84 @@
+"""
+Splurge DSV - A utility library for working with DSV (Delimited String Values) files.
+
+This package provides utilities for parsing, processing, and manipulating
+delimited string value files with support for various delimiters, text bookends,
+and streaming operations.
+
+Copyright (c) 2025 Jim Schilling
+
+This module is licensed under the MIT License.
+"""
+
+# Local imports
+from splurge_dsv.dsv_helper import DsvHelper
+from splurge_dsv.exceptions import (
+    SplurgeConfigurationError,
+    SplurgeDataProcessingError,
+    SplurgeDsvError,
+    SplurgeFileEncodingError,
+    SplurgeFileNotFoundError,
+    SplurgeFileOperationError,
+    SplurgeFilePermissionError,
+    SplurgeFormatError,
+    SplurgeParameterError,
+    SplurgeParsingError,
+    SplurgePathValidationError,
+    SplurgePerformanceWarning,
+    SplurgeRangeError,
+    SplurgeResourceAcquisitionError,
+    SplurgeResourceError,
+    SplurgeResourceReleaseError,
+    SplurgeStreamingError,
+    SplurgeTypeConversionError,
+    SplurgeValidationError,
+)
+from splurge_dsv.path_validator import PathValidator
+from splurge_dsv.resource_manager import (
+    FileResourceManager,
+    ResourceManager,
+    StreamResourceManager,
+    safe_file_operation,
+    safe_stream_operation,
+)
+from splurge_dsv.string_tokenizer import StringTokenizer
+from splurge_dsv.text_file_helper import TextFileHelper
+
+__version__ = "2025.1.2"
+__author__ = "Jim Schilling"
+__license__ = "MIT"
+
+__all__ = [
+    # Main helper class
+    "DsvHelper",
+    # Exceptions
+    "SplurgeDsvError",
+    "SplurgeValidationError",
+    "SplurgeFileOperationError",
+    "SplurgeFileNotFoundError",
+    "SplurgeFilePermissionError",
+    "SplurgeFileEncodingError",
+    "SplurgePathValidationError",
+    "SplurgeDataProcessingError",
+    "SplurgeParsingError",
+    "SplurgeTypeConversionError",
+    "SplurgeStreamingError",
+    "SplurgeConfigurationError",
+    "SplurgeResourceError",
+    "SplurgeResourceAcquisitionError",
+    "SplurgeResourceReleaseError",
+    "SplurgePerformanceWarning",
+    "SplurgeParameterError",
+    "SplurgeRangeError",
+    "SplurgeFormatError",
+    # Utility classes
+    "StringTokenizer",
+    "TextFileHelper",
+    "PathValidator",
+    "ResourceManager",
+    "FileResourceManager",
+    "StreamResourceManager",
+    # Context managers
+    "safe_file_operation",
+    "safe_stream_operation",
+]

splurge_dsv/__main__.py

@@ -0,0 +1,15 @@
+"""
+Command-line interface entry point for splurge-dsv.
+
+This module serves as the entry point when running the package as a module.
+It imports and calls the main CLI function from the cli module.
+"""
+
+# Standard library imports
+import sys
+
+# Local imports
+from splurge_dsv.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

splurge_dsv/cli.py

@@ -0,0 +1,158 @@
+"""
+Command-line interface for splurge-dsv.
+
+This module provides a command-line interface for the splurge-dsv library,
+allowing users to parse DSV files from the command line.
+
+Usage:
+    python -m splurge_dsv <file_path> [options]
+    python -m splurge_dsv --help
+"""
+
+# Standard library imports
+import argparse
+import sys
+from pathlib import Path
+
+# Local imports
+from splurge_dsv.dsv_helper import DsvHelper
+from splurge_dsv.exceptions import SplurgeDsvError
+
+
+def parse_arguments() -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Parse DSV (Delimited String Values) files",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python -m splurge_dsv data.csv --delimiter ,
+  python -m splurge_dsv data.tsv --delimiter "\\t"
+  python -m splurge_dsv data.txt --delimiter "|" --bookend '"'
+        """,
+    )
+
+    parser.add_argument("file_path", type=str, help="Path to the DSV file to parse")
+
+    parser.add_argument("--delimiter", "-d", type=str, required=True, help="Delimiter character to use for parsing")
+
+    parser.add_argument("--bookend", "-b", type=str, help="Bookend character for text fields (e.g., '\"')")
+
+    parser.add_argument("--no-strip", action="store_true", help="Don't strip whitespace from values")
+
+    parser.add_argument("--no-bookend-strip", action="store_true", help="Don't strip whitespace from bookends")
+
+    parser.add_argument("--encoding", "-e", type=str, default="utf-8", help="File encoding (default: utf-8)")
+
+    parser.add_argument("--skip-header", type=int, default=0, help="Number of header rows to skip (default: 0)")
+
+    parser.add_argument("--skip-footer", type=int, default=0, help="Number of footer rows to skip (default: 0)")
+
+    parser.add_argument(
+        "--stream", "-s", action="store_true", help="Stream the file in chunks instead of loading entirely into memory"
+    )
+
+    parser.add_argument("--chunk-size", type=int, default=500, help="Chunk size for streaming (default: 500)")
+
+    parser.add_argument("--version", action="version", version="%(prog)s 2025.1.2")
+
+    return parser.parse_args()
+
+
+def print_results(rows: list[list[str]], delimiter: str) -> None:
+    """Print parsed results in a formatted way."""
+    if not rows:
+        print("No data found.")
+        return
+
+    # Find the maximum width for each column
+    if rows:
+        max_widths = []
+        for col_idx in range(len(rows[0])):
+            max_width = max(len(str(row[col_idx])) for row in rows)
+            max_widths.append(max_width)
+
+        # Print header separator
+        print("-" * (sum(max_widths) + len(max_widths) * 3 - 1))
+
+        # Print each row
+        for row_idx, row in enumerate(rows):
+            formatted_row = []
+            for col_idx, value in enumerate(row):
+                formatted_value = str(value).ljust(max_widths[col_idx])
+                formatted_row.append(formatted_value)
+            print(f"| {' | '.join(formatted_row)} |")
+
+            # Print separator after header
+            if row_idx == 0:
+                print("-" * (sum(max_widths) + len(max_widths) * 3 - 1))
+
+
+def main() -> int:
+    """Main entry point for the command-line interface."""
+    try:
+        args = parse_arguments()
+
+        # Validate file path
+        file_path = Path(args.file_path)
+        if not file_path.exists():
+            print(f"Error: File '{args.file_path}' not found.", file=sys.stderr)
+            return 1
+
+        if not file_path.is_file():
+            print(f"Error: '{args.file_path}' is not a file.", file=sys.stderr)
+            return 1
+
+        # Parse the file
+        if args.stream:
+            print(f"Streaming file '{args.file_path}' with delimiter '{args.delimiter}'...")
+            chunk_count = 0
+            total_rows = 0
+
+            for chunk in DsvHelper.parse_stream(
+                file_path,
+                delimiter=args.delimiter,
+                strip=not args.no_strip,
+                bookend=args.bookend,
+                bookend_strip=not args.no_bookend_strip,
+                encoding=args.encoding,
+                skip_header_rows=args.skip_header,
+                skip_footer_rows=args.skip_footer,
+                chunk_size=args.chunk_size,
+            ):
+                chunk_count += 1
+                total_rows += len(chunk)
+                print(f"Chunk {chunk_count}: {len(chunk)} rows")
+                print_results(chunk, args.delimiter)
+                print()
+
+            print(f"Total: {total_rows} rows in {chunk_count} chunks")
+        else:
+            print(f"Parsing file '{args.file_path}' with delimiter '{args.delimiter}'...")
+            rows = DsvHelper.parse_file(
+                file_path,
+                delimiter=args.delimiter,
+                strip=not args.no_strip,
+                bookend=args.bookend,
+                bookend_strip=not args.no_bookend_strip,
+                encoding=args.encoding,
+                skip_header_rows=args.skip_header,
+                skip_footer_rows=args.skip_footer,
+            )
+
+            print(f"Parsed {len(rows)} rows")
+            print_results(rows, args.delimiter)
+
+        return 0
+
+    except KeyboardInterrupt:
+        print("\nOperation cancelled by user.", file=sys.stderr)
+        return 130
+    except SplurgeDsvError as e:
+        print(f"Error: {e.message}", file=sys.stderr)
+        if e.details:
+            print(f"Details: {e.details}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        return 1

splurge_dsv/dsv_helper.py

@@ -8,12 +8,15 @@ Please preserve this header and all related material when sharing!
 This module is licensed under the MIT License.
 """
 
+# Standard library imports
+from collections.abc import Iterator
 from os import PathLike
-from typing import Iterator
 
+# Local imports
+from splurge_dsv.exceptions import SplurgeParameterError
 from splurge_dsv.string_tokenizer import StringTokenizer
 from splurge_dsv.text_file_helper import TextFileHelper
-from splurge_dsv.exceptions import SplurgeParameterError
+
 
 class DsvHelper:
     """
@@ -38,7 +41,7 @@ class DsvHelper:
         delimiter: str,
         strip: bool = DEFAULT_STRIP,
         bookend: str | None = None,
-        bookend_strip: bool = DEFAULT_BOOKEND_STRIP
+        bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
     ) -> list[str]:
         """
         Parse a string into a list of strings.
@@ -68,10 +71,7 @@ class DsvHelper:
         tokens: list[str] = StringTokenizer.parse(content, delimiter=delimiter, strip=strip)
 
         if bookend:
-            tokens = [
-                StringTokenizer.remove_bookends(token, bookend=bookend, strip=bookend_strip)
-                for token in tokens
-            ]
+            tokens = [StringTokenizer.remove_bookends(token, bookend=bookend, strip=bookend_strip) for token in tokens]
 
         return tokens
 
@@ -83,7 +83,7 @@ class DsvHelper:
         delimiter: str,
         strip: bool = DEFAULT_STRIP,
         bookend: str | None = None,
-        bookend_strip: bool = DEFAULT_BOOKEND_STRIP
+        bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
     ) -> list[list[str]]:
         """
         Parse a list of strings into a list of lists of strings.
@@ -108,7 +108,7 @@ class DsvHelper:
         """
         if not isinstance(content, list):
             raise SplurgeParameterError("content must be a list")
-        
+
         if not all(isinstance(item, str) for item in content):
             raise SplurgeParameterError("content must be a list of strings")
 
@@ -128,7 +128,7 @@ class DsvHelper:
         bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
         encoding: str = DEFAULT_ENCODING,
         skip_header_rows: int = DEFAULT_SKIP_HEADER_ROWS,
-        skip_footer_rows: int = DEFAULT_SKIP_FOOTER_ROWS
+        skip_footer_rows: int = DEFAULT_SKIP_FOOTER_ROWS,
     ) -> list[list[str]]:
         """
         Parse a file into a list of lists of strings.
@@ -157,19 +157,10 @@ class DsvHelper:
             [['header1', 'header2'], ['value1', 'value2']]
         """
         lines: list[str] = TextFileHelper.read(
-            file_path,
-            encoding=encoding,
-            skip_header_rows=skip_header_rows,
-            skip_footer_rows=skip_footer_rows
+            file_path, encoding=encoding, skip_header_rows=skip_header_rows, skip_footer_rows=skip_footer_rows
         )
 
-        return cls.parses(
-            lines,
-            delimiter=delimiter,
-            strip=strip,
-            bookend=bookend,
-            bookend_strip=bookend_strip
-        )
+        return cls.parses(lines, delimiter=delimiter, strip=strip, bookend=bookend, bookend_strip=bookend_strip)
 
     @classmethod
     def _process_stream_chunk(
@@ -179,28 +170,22 @@ class DsvHelper:
         delimiter: str,
         strip: bool = DEFAULT_STRIP,
         bookend: str | None = None,
-        bookend_strip: bool = DEFAULT_BOOKEND_STRIP
+        bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
     ) -> list[list[str]]:
         """
         Process a chunk of lines from the stream.
-        
+
         Args:
             chunk: List of lines to process
             delimiter: Delimiter to use for parsing
             strip: Whether to strip whitespace
             bookend: Bookend character for text fields
             bookend_strip: Whether to strip whitespace from bookends
-            
+
         Returns:
             list[list[str]]: Parsed rows
         """
-        return cls.parses(
-            chunk,
-            delimiter=delimiter,
-            strip=strip,
-            bookend=bookend,
-            bookend_strip=bookend_strip
-        )
+        return cls.parses(chunk, delimiter=delimiter, strip=strip, bookend=bookend, bookend_strip=bookend_strip)
 
     @classmethod
     def parse_stream(
@@ -214,7 +199,7 @@ class DsvHelper:
         encoding: str = DEFAULT_ENCODING,
         skip_header_rows: int = DEFAULT_SKIP_HEADER_ROWS,
         skip_footer_rows: int = DEFAULT_SKIP_FOOTER_ROWS,
-        chunk_size: int = DEFAULT_CHUNK_SIZE
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
     ) -> Iterator[list[list[str]]]:
         """
         Stream-parse a DSV file in chunks of lines.
@@ -247,17 +232,15 @@ class DsvHelper:
         skip_footer_rows = max(skip_footer_rows, cls.DEFAULT_SKIP_FOOTER_ROWS)
 
         # Use TextFileHelper.read_as_stream for consistent error handling
-        for chunk in TextFileHelper.read_as_stream(
-            file_path,
-            encoding=encoding,
-            skip_header_rows=skip_header_rows,
-            skip_footer_rows=skip_footer_rows,
-            chunk_size=chunk_size
-        ):
-            yield cls._process_stream_chunk(
-                chunk,
-                delimiter=delimiter,
-                strip=strip,
-                bookend=bookend,
-                bookend_strip=bookend_strip
-            )   
+        yield from (
+            cls._process_stream_chunk(
+                chunk, delimiter=delimiter, strip=strip, bookend=bookend, bookend_strip=bookend_strip
+            )
+            for chunk in TextFileHelper.read_as_stream(
+                file_path,
+                encoding=encoding,
+                skip_header_rows=skip_header_rows,
+                skip_footer_rows=skip_footer_rows,
+                chunk_size=chunk_size,
+            )
+        )

splurge_dsv/exceptions.py

@@ -14,16 +14,11 @@ This module is licensed under the MIT License.
 
 class SplurgeDsvError(Exception):
     """Base exception for all splurge-dsv errors."""
-    
-    def __init__(
-        self,
-        message: str,
-        *,
-        details: str | None = None
-    ) -> None:
+
+    def __init__(self, message: str, *, details: str | None = None) -> None:
         """
         Initialize SplurgeDsvError.
-        
+
         Args:
             message: Primary error message
             details: Additional error details
@@ -35,89 +30,107 @@ class SplurgeDsvError(Exception):
 
 class SplurgeValidationError(SplurgeDsvError):
     """Raised when data validation fails."""
+
     pass
 
 
 class SplurgeFileOperationError(SplurgeDsvError):
     """Base exception for file operation errors."""
+
     pass
 
 
 class SplurgeFileNotFoundError(SplurgeFileOperationError):
     """Raised when a file is not found."""
+
     pass
 
 
 class SplurgeFilePermissionError(SplurgeFileOperationError):
     """Raised when there are permission issues with file operations."""
+
     pass
 
 
 class SplurgeFileEncodingError(SplurgeFileOperationError):
     """Raised when there are encoding issues with file operations."""
+
     pass
 
 
 class SplurgePathValidationError(SplurgeFileOperationError):
     """Raised when file path validation fails."""
+
     pass
 
 
 class SplurgeDataProcessingError(SplurgeDsvError):
     """Base exception for data processing errors."""
+
     pass
 
 
 class SplurgeParsingError(SplurgeDataProcessingError):
     """Raised when data parsing fails."""
+
     pass
 
 
 class SplurgeTypeConversionError(SplurgeDataProcessingError):
     """Raised when type conversion fails."""
+
     pass
 
 
 class SplurgeStreamingError(SplurgeDataProcessingError):
     """Raised when streaming operations fail."""
+
     pass
 
 
 class SplurgeConfigurationError(SplurgeDsvError):
     """Raised when configuration is invalid."""
+
     pass
 
 
 class SplurgeResourceError(SplurgeDsvError):
     """Base exception for resource management errors."""
+
     pass
 
 
 class SplurgeResourceAcquisitionError(SplurgeResourceError):
     """Raised when resource acquisition fails."""
+
     pass
 
 
 class SplurgeResourceReleaseError(SplurgeResourceError):
     """Raised when resource release fails."""
+
     pass
 
 
 class SplurgePerformanceWarning(SplurgeDsvError):
     """Warning for performance-related issues."""
+
     pass
 
 
 class SplurgeParameterError(SplurgeValidationError):
     """Raised when function parameters are invalid."""
+
     pass
 
 
 class SplurgeRangeError(SplurgeValidationError):
     """Raised when values are outside expected ranges."""
+
     pass
 
 
 class SplurgeFormatError(SplurgeValidationError):
     """Raised when data format is invalid."""
-    pass
+
+    pass