splurge-dsv 2025.1.5__py3-none-any.whl → 2025.2.1__py3-none-any.whl

splurge_dsv/__init__.py

@@ -1,84 +1,96 @@
-"""
-Splurge DSV - A utility library for working with DSV (Delimited String Values) files.
+"""Top-level package for Splurge DSV.
 
-This package provides utilities for parsing, processing, and manipulating
-delimited string value files with support for various delimiters, text bookends,
-and streaming operations.
+This package provides utilities for parsing, processing and manipulating
+delimited string value (DSV) files. It exposes the high-level API objects
+such as :class:`~splurge_dsv.dsv.Dsv` and :class:`~splurge_dsv.dsv.DsvConfig`,
+convenience helpers, and the package's exception types.
 
+License: MIT
 Copyright (c) 2025 Jim Schilling
-
-This module is licensed under the MIT License.
 """
 
+# Ensure current working directory exists. Some test environments or earlier
+# test cases may remove the process working directory which causes calls to
+# os.getcwd() to raise FileNotFoundError later during test execution. Guard
+# against that here by switching to this package directory when cwd is missing.
+import os
+from pathlib import Path as _Path
+
+try:
+    try:
+        # os.getcwd() can raise FileNotFoundError in CI/runner environments
+        # if the original working directory was removed. Check existence via
+        # Path.cwd(); if it doesn't exist, switch to the package directory.
+        if not _Path.cwd().exists():
+            os.chdir(_Path(__file__).resolve().parent)
+    except FileNotFoundError:
+        # Fall back to package directory when cwd is gone
+        os.chdir(_Path(__file__).resolve().parent)
+except Exception:
+    # Be conservative: if this fails, don't break import - tests will report
+    # the original failure. Swallowing ensures import-time is resilient.
+    pass
+
 # Local imports
+from splurge_dsv.dsv import Dsv, DsvConfig
 from splurge_dsv.dsv_helper import DsvHelper
 from splurge_dsv.exceptions import (
-    SplurgeConfigurationError,
-    SplurgeDataProcessingError,
+    SplurgeDsvConfigurationError,
+    SplurgeDsvDataProcessingError,
+    # canonical SplurgeDsv* exception names
     SplurgeDsvError,
-    SplurgeFileEncodingError,
-    SplurgeFileNotFoundError,
-    SplurgeFileOperationError,
-    SplurgeFilePermissionError,
-    SplurgeFormatError,
-    SplurgeParameterError,
-    SplurgeParsingError,
-    SplurgePathValidationError,
-    SplurgePerformanceWarning,
-    SplurgeRangeError,
-    SplurgeResourceAcquisitionError,
-    SplurgeResourceError,
-    SplurgeResourceReleaseError,
-    SplurgeStreamingError,
-    SplurgeTypeConversionError,
-    SplurgeValidationError,
+    SplurgeDsvFileEncodingError,
+    SplurgeDsvFileNotFoundError,
+    SplurgeDsvFileOperationError,
+    SplurgeDsvFilePermissionError,
+    SplurgeDsvFormatError,
+    SplurgeDsvParameterError,
+    SplurgeDsvParsingError,
+    SplurgeDsvPathValidationError,
+    SplurgeDsvPerformanceWarning,
+    SplurgeDsvRangeError,
+    SplurgeDsvResourceAcquisitionError,
+    SplurgeDsvResourceError,
+    SplurgeDsvResourceReleaseError,
+    SplurgeDsvStreamingError,
+    SplurgeDsvTypeConversionError,
+    SplurgeDsvValidationError,
 )
 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.5"
+__version__ = "2025.2.1"
 __author__ = "Jim Schilling"
 __license__ = "MIT"
 
 __all__ = [
-    # Main helper class
+    # Main classes
+    "Dsv",
+    "DsvConfig",
     "DsvHelper",
     # Exceptions
     "SplurgeDsvError",
-    "SplurgeValidationError",
-    "SplurgeFileOperationError",
-    "SplurgeFileNotFoundError",
-    "SplurgeFilePermissionError",
-    "SplurgeFileEncodingError",
-    "SplurgePathValidationError",
-    "SplurgeDataProcessingError",
-    "SplurgeParsingError",
-    "SplurgeTypeConversionError",
-    "SplurgeStreamingError",
-    "SplurgeConfigurationError",
-    "SplurgeResourceError",
-    "SplurgeResourceAcquisitionError",
-    "SplurgeResourceReleaseError",
-    "SplurgePerformanceWarning",
-    "SplurgeParameterError",
-    "SplurgeRangeError",
-    "SplurgeFormatError",
+    "SplurgeDsvValidationError",
+    "SplurgeDsvFileOperationError",
+    "SplurgeDsvFileNotFoundError",
+    "SplurgeDsvFilePermissionError",
+    "SplurgeDsvFileEncodingError",
+    "SplurgeDsvPathValidationError",
+    "SplurgeDsvDataProcessingError",
+    "SplurgeDsvParsingError",
+    "SplurgeDsvTypeConversionError",
+    "SplurgeDsvStreamingError",
+    "SplurgeDsvConfigurationError",
+    "SplurgeDsvResourceError",
+    "SplurgeDsvResourceAcquisitionError",
+    "SplurgeDsvResourceReleaseError",
+    "SplurgeDsvPerformanceWarning",
+    "SplurgeDsvParameterError",
+    "SplurgeDsvRangeError",
+    "SplurgeDsvFormatError",
     # Utility classes
     "StringTokenizer",
     "TextFileHelper",
     "PathValidator",
-    "ResourceManager",
-    "FileResourceManager",
-    "StreamResourceManager",
-    # Context managers
-    "safe_file_operation",
-    "safe_stream_operation",
 ]

splurge_dsv/__main__.py

@@ -1,14 +1,18 @@
-"""
-Command-line interface entry point for splurge-dsv.
+"""Module entrypoint for running splurge-dsv as a script.
+
+When executed (``python -m splurge_dsv``), this module delegates to
+``splurge_dsv.cli.run_cli`` and returns the resulting exit code.
 
-This module serves as the entry point when running the package as a module.
-It imports and calls the run_cli function from the cli module.
+License: MIT
+Copyright (c) 2025 Jim Schilling
 """
 
-# Standard library imports
+from __future__ import annotations
+
+# Standard library
 import sys
 
-# Local imports
+# Local
 from splurge_dsv.cli import run_cli
 
 if __name__ == "__main__":

splurge_dsv/cli.py

@@ -1,14 +1,17 @@
-"""
-Command-line interface for splurge-dsv.
+"""Command-line interface utilities 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.
+This module provides the CLI entry points and helpers for parsing DSV
+files from the command line. It exposes a thin wrapper around the
+library API suitable for use as ``python -m splurge_dsv``.
 
-Copyright (c) 2025 Jim Schilling
+Public API:
+    - parse_arguments: Build and parse the CLI argument parser.
+    - print_results: Nicely format parsed rows to stdout.
+    - run_cli: Main entrypoint invoked by ``__main__``.
 
-This module is licensed under the MIT License.
+License: MIT
 
-Please preserve this header and all related material when sharing!
+Copyright (c) 2025 Jim Schilling
 """
 
 # Standard library imports
@@ -19,12 +22,17 @@ from pathlib import Path
 
 # Local imports
 from splurge_dsv import __version__
-from splurge_dsv.dsv_helper import DsvHelper
+from splurge_dsv.dsv import Dsv, DsvConfig
 from splurge_dsv.exceptions import SplurgeDsvError
 
 
 def parse_arguments() -> argparse.Namespace:
-    """Parse command line arguments."""
+    """Construct and parse command-line arguments for the CLI.
+
+    Returns:
+        argparse.Namespace: Parsed arguments with attributes matching the
+            defined options.
+    """
     parser = argparse.ArgumentParser(
         description="Parse DSV (Delimited String Values) files",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -71,7 +79,15 @@ Examples:
 
 
 def print_results(rows: list[list[str]], delimiter: str) -> None:
-    """Print parsed results in a formatted way."""
+    """Print parsed rows in a human-readable table format.
+
+    The function computes column widths and prints a simple ASCII table.
+
+    Args:
+        rows: Parsed rows to print (first row is treated as header).
+        delimiter: Delimiter used (included here for compatibility; printing
+            does not depend on it directly).
+    """
     if not rows:
         print("No data found.")
         return
@@ -100,23 +116,17 @@ def print_results(rows: list[list[str]], delimiter: str) -> None:
 
 
 def run_cli() -> int:
-    """Run the command-line interface for DSV file parsing.
+    """Main entry point for running the splurge-dsv CLI.
 
-    This function serves as the main entry point for the splurge-dsv CLI tool.
-    It parses command-line arguments, validates the input file, and processes
-    DSV files according to the specified options. Supports both regular parsing
-    and streaming modes for large files.
+    The function handles argument parsing, basic path validation, constructing
+    the ``DsvConfig`` and ``Dsv`` objects, and printing results in the
+    requested format. Designed to be invoked from ``__main__``.
 
     Returns:
-        int: Exit code indicating success or failure:
-            - 0: Success
-            - 1: Generic error (file not found, parsing error, etc.)
-            - 2: Invalid arguments
-            - 130: Operation interrupted (Ctrl+C)
+        Exit code (0 success, non-zero error codes on failure).
 
     Raises:
-        SystemExit: Terminates the program with the appropriate exit code.
-            This is handled internally and should not be caught by callers.
+        SystemExit: On argument parser termination (handled internally).
     """
     try:
         args = parse_arguments()
@@ -131,6 +141,19 @@ def run_cli() -> int:
             print(f"Error: '{args.file_path}' is not a file.", file=sys.stderr)
             return 1
 
+        # Create configuration and Dsv instance for parsing
+        config = DsvConfig(
+            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,
+        )
+        dsv = Dsv(config)
+
         # Parse the file
         if args.stream:
             if args.output_format != "json":
@@ -138,17 +161,7 @@ def run_cli() -> int:
             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,
-            ):
+            for chunk in dsv.parse_file_stream(file_path):
                 chunk_count += 1
                 total_rows += len(chunk)
                 if args.output_format == "json":
@@ -166,16 +179,7 @@ def run_cli() -> int:
         else:
             if args.output_format not in ["json", "ndjson"]:
                 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,
-            )
+            rows = dsv.parse_file(file_path)
 
             if args.output_format == "json":
                 print(json.dumps(rows, ensure_ascii=False))

splurge_dsv/dsv.py

@@ -0,0 +1,280 @@
+"""DSV parsing primitives and configuration objects.
+
+This module exposes the :class:`DsvConfig` dataclass and the :class:`Dsv`
+parser. ``DsvConfig`` encapsulates parsing options such as delimiter,
+encoding and header/footer skipping. ``Dsv`` is a thin, stateful wrapper
+around :mod:`splurge_dsv.dsv_helper` that binds a configuration to
+parsing operations and provides convenience methods for parsing strings,
+files, and streaming large inputs.
+
+Public API:
+    - DsvConfig: Configuration dataclass for parsing behavior.
+    - Dsv: Parser instance that performs parse/parse_file/parse_stream.
+
+License: MIT
+
+Copyright (c) 2025 Jim Schilling
+"""
+
+# Standard library imports
+import warnings
+from collections.abc import Iterator
+from dataclasses import dataclass, fields
+from os import PathLike
+
+# Local imports
+from splurge_dsv.dsv_helper import DsvHelper
+from splurge_dsv.exceptions import SplurgeDsvParameterError
+
+
+@dataclass(frozen=True)
+class DsvConfig:
+    """Configuration for DSV parsing operations.
+
+    This frozen dataclass stores parsing options and performs basic
+    validation in :meth:`__post_init__`.
+
+    Args:
+        delimiter: The delimiter character used to separate values.
+        strip: Whether to strip whitespace from parsed values.
+        bookend: Optional character that wraps text fields (e.g., quotes).
+        bookend_strip: Whether to strip whitespace from bookend characters.
+        encoding: Text encoding for file operations.
+        skip_header_rows: Number of header rows to skip when reading files.
+        skip_footer_rows: Number of footer rows to skip when reading files.
+        chunk_size: Size of chunks for streaming operations.
+
+    Raises:
+        SplurgeDsvParameterError: If delimiter is empty, chunk_size is too
+            small, or skip counts are negative.
+    """
+
+    delimiter: str
+    strip: bool = True
+    bookend: str | None = None
+    bookend_strip: bool = True
+    encoding: str = "utf-8"
+    skip_header_rows: int = 0
+    skip_footer_rows: int = 0
+    chunk_size: int = 500
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization.
+
+        Ensures required fields are present and numeric ranges are valid.
+        """
+        if not self.delimiter:
+            raise SplurgeDsvParameterError("delimiter cannot be empty or None")
+
+        if self.chunk_size < DsvHelper.DEFAULT_MIN_CHUNK_SIZE:
+            raise SplurgeDsvParameterError(
+                f"chunk_size must be at least {DsvHelper.DEFAULT_MIN_CHUNK_SIZE}, got {self.chunk_size}"
+            )
+
+        if self.skip_header_rows < 0:
+            raise SplurgeDsvParameterError(f"skip_header_rows cannot be negative, got {self.skip_header_rows}")
+
+        if self.skip_footer_rows < 0:
+            raise SplurgeDsvParameterError(f"skip_footer_rows cannot be negative, got {self.skip_footer_rows}")
+
+    @classmethod
+    def csv(cls, **overrides) -> "DsvConfig":
+        """
+        Create a CSV configuration with sensible defaults.
+
+        Args:
+            **overrides: Any configuration values to override
+
+        Returns:
+            DsvConfig: CSV configuration object
+
+        Example:
+            >>> config = DsvConfig.csv(skip_header_rows=1)
+            >>> config.delimiter
+            ','
+        """
+        return cls(delimiter=",", **overrides)
+
+    @classmethod
+    def tsv(cls, **overrides) -> "DsvConfig":
+        """
+        Create a TSV configuration with sensible defaults.
+
+        Args:
+            **overrides: Any configuration values to override
+
+        Returns:
+            DsvConfig: TSV configuration object
+
+        Example:
+            >>> config = DsvConfig.tsv(encoding="utf-16")
+            >>> config.delimiter
+            '\t'
+        """
+        return cls(delimiter="\t", **overrides)
+
+    @classmethod
+    def from_params(cls, **kwargs) -> "DsvConfig":
+        """
+        Create a DsvConfig from arbitrary keyword arguments.
+
+        This method filters out any invalid parameters that don't correspond
+        to DsvConfig fields, making it safe to pass through arbitrary parameter
+        dictionaries (useful for migration from existing APIs).
+
+        Args:
+            **kwargs: Configuration parameters (invalid ones are ignored)
+
+        Returns:
+            DsvConfig: Configuration object with valid parameters
+
+        Example:
+            >>> config = DsvConfig.from_params(delimiter=",", invalid_param="ignored")
+            >>> config.delimiter
+            ','
+        """
+        valid_fields = {f.name for f in fields(cls)}
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_fields}
+        return cls(**filtered_kwargs)
+
+
+class Dsv:
+    """Parser class that binds a :class:`DsvConfig` to parsing operations.
+
+    The class delegates actual parsing to :mod:`splurge_dsv.dsv_helper` while
+    providing a convenient instance API for repeated parsing tasks with the
+    same configuration.
+
+    Attributes:
+        config (DsvConfig): Configuration instance used for parsing calls.
+    """
+
+    def __init__(self, config: DsvConfig) -> None:
+        """
+        Initialize DSV parser with configuration.
+
+        Args:
+            config: DsvConfig object containing parsing parameters
+
+        Example:
+            >>> config = DsvConfig(delimiter=",")
+            >>> parser = Dsv(config)
+        """
+        self.config = config
+
+    def parse(self, content: str) -> list[str]:
+        """Parse a single DSV record (string) into a list of tokens.
+
+        Args:
+            content: Input string representing a single DSV record.
+
+        Returns:
+            List of parsed tokens as strings.
+
+        Raises:
+            SplurgeDsvParameterError: If the configured delimiter is invalid.
+        """
+        return DsvHelper.parse(
+            content,
+            delimiter=self.config.delimiter,
+            strip=self.config.strip,
+            bookend=self.config.bookend,
+            bookend_strip=self.config.bookend_strip,
+        )
+
+    def parses(self, content: list[str]) -> list[list[str]]:
+        """
+        Parse a list of strings into a list of lists of strings.
+
+        Args:
+            content: List of strings to parse
+
+        Returns:
+            List of lists of parsed strings
+
+        Example:
+            >>> parser = Dsv(DsvConfig(delimiter=","))
+            >>> parser.parses(["a,b", "c,d"])
+            [['a', 'b'], ['c', 'd']]
+        """
+        return DsvHelper.parses(
+            content,
+            delimiter=self.config.delimiter,
+            strip=self.config.strip,
+            bookend=self.config.bookend,
+            bookend_strip=self.config.bookend_strip,
+        )
+
+    def parse_file(self, file_path: PathLike[str] | str) -> list[list[str]]:
+        """Parse a DSV file and return all rows as lists of strings.
+
+        Args:
+            file_path: Path to the file to parse.
+
+        Returns:
+            A list of rows, where each row is a list of string tokens.
+
+        Raises:
+            SplurgeDsvFileNotFoundError: If the file cannot be found.
+            SplurgeDsvFilePermissionError: If the file cannot be read.
+            SplurgeDsvFileEncodingError: If the file cannot be decoded with
+                the configured encoding.
+        """
+        return DsvHelper.parse_file(
+            file_path,
+            delimiter=self.config.delimiter,
+            strip=self.config.strip,
+            bookend=self.config.bookend,
+            bookend_strip=self.config.bookend_strip,
+            encoding=self.config.encoding,
+            skip_header_rows=self.config.skip_header_rows,
+            skip_footer_rows=self.config.skip_footer_rows,
+        )
+
+    def parse_file_stream(self, file_path: PathLike[str] | str) -> Iterator[list[list[str]]]:
+        """Stream-parse a DSV file, yielding chunks of parsed rows.
+
+        The method yields lists of parsed rows (each row itself is a list of
+        strings). Chunk sizing is controlled by the bound configuration's
+        ``chunk_size`` value.
+
+        Args:
+            file_path: Path to the file to parse.
+
+        Yields:
+            Lists of parsed rows, each list containing up to ``chunk_size`` rows.
+        """
+        return DsvHelper.parse_file_stream(
+            file_path,
+            delimiter=self.config.delimiter,
+            strip=self.config.strip,
+            bookend=self.config.bookend,
+            bookend_strip=self.config.bookend_strip,
+            encoding=self.config.encoding,
+            skip_header_rows=self.config.skip_header_rows,
+            skip_footer_rows=self.config.skip_footer_rows,
+            chunk_size=self.config.chunk_size,
+        )
+
+    def parse_stream(self, file_path: PathLike[str] | str) -> Iterator[list[list[str]]]:
+        """Stream-parse a DSV file, yielding chunks of parsed rows.
+
+        The method yields lists of parsed rows (each row itself is a list of
+        strings). Chunk sizing is controlled by the bound configuration's
+        ``chunk_size`` value.
+
+        Args:
+            file_path: Path to the file to parse.
+
+        Yields:
+            Lists of parsed rows, each list containing up to ``chunk_size`` rows.
+
+        Deprecated: Use `parse_file_stream` instead. This method will be removed in a future release.
+        """
+        # Emit a DeprecationWarning to signal removal in a future release
+        warnings.warn(
+            "Dsv.parse_stream() is deprecated and will be removed in a future release; use Dsv.parse_file_stream() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return Dsv.parse_file_stream(self, file_path)