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

splurge_dsv/dsv_helper.py

@@ -9,11 +9,12 @@ This module is licensed under the MIT License.
 """
 
 # Standard library imports
+import warnings
 from collections.abc import Iterator
 from os import PathLike
 
 # Local imports
-from splurge_dsv.exceptions import SplurgeParameterError
+from splurge_dsv.exceptions import SplurgeDsvParameterError
 from splurge_dsv.string_tokenizer import StringTokenizer
 from splurge_dsv.text_file_helper import TextFileHelper
 
@@ -43,30 +44,34 @@ class DsvHelper:
         bookend: str | None = None,
         bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
     ) -> list[str]:
-        """
-        Parse a string into a list of strings.
+        """Parse a single DSV line into tokens.
+
+        This method tokenizes a single line of DSV text using the provided
+        ``delimiter``. It optionally strips surrounding whitespace from each
+        token and may remove configured bookend characters (for example,
+        double-quotes used around fields).
 
         Args:
-            content (str): The string to parse.
-            delimiter (str): The delimiter to use.
-            strip (bool): Whether to strip whitespace from the strings.
-            bookend (str | None): The bookend to use for text fields.
-            bookend_strip (bool): Whether to strip whitespace from the bookend.
+            content: The input line to tokenize.
+            delimiter: A single-character delimiter string (e.g. "," or "\t").
+            strip: If True, strip leading/trailing whitespace from each token.
+            bookend: Optional bookend character to remove from token ends.
+            bookend_strip: If True, strip whitespace after removing bookends.
 
         Returns:
-            list[str]: The list of strings.
+            A list of parsed token strings.
 
         Raises:
-            SplurgeParameterError: If delimiter is empty or None.
+            SplurgeDsvParameterError: If ``delimiter`` is empty or None.
 
-        Example:
+        Examples:
             >>> DsvHelper.parse("a,b,c", delimiter=",")
             ['a', 'b', 'c']
             >>> DsvHelper.parse('"a","b","c"', delimiter=",", bookend='"')
             ['a', 'b', 'c']
         """
         if delimiter is None or delimiter == "":
-            raise SplurgeParameterError("delimiter cannot be empty or None")
+            raise SplurgeDsvParameterError("delimiter cannot be empty or None")
 
         tokens: list[str] = StringTokenizer.parse(content, delimiter=delimiter, strip=strip)
 
@@ -85,32 +90,34 @@ class DsvHelper:
         bookend: str | None = None,
         bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
     ) -> list[list[str]]:
-        """
-        Parse a list of strings into a list of lists of strings.
+        """Parse multiple DSV lines.
+
+        Given a list of lines (for example, the result of reading a file),
+        return a list where each element is the list of tokens for that line.
 
         Args:
-            content (list[str]): The list of strings to parse.
-            delimiter (str): The delimiter to use.
-            strip (bool): Whether to strip whitespace from the strings.
-            bookend (str | None): The bookend to use for text fields.
-            bookend_strip (bool): Whether to strip whitespace from the bookend.
+            content: A list of input lines to parse.
+            delimiter: Delimiter used to split each line.
+            strip: If True, strip whitespace from tokens.
+            bookend: Optional bookend character to remove from tokens.
+            bookend_strip: If True, strip whitespace after removing bookends.
 
         Returns:
-            list[list[str]]: The list of lists of strings.
+            A list of token lists, one per input line.
 
         Raises:
-            SplurgeParameterError: If delimiter is empty or None.
-            SplurgeParameterError: If content is not a list of strings.
+            SplurgeDsvParameterError: If ``content`` is not a list of strings or
+                if ``delimiter`` is empty or None.
 
         Example:
             >>> DsvHelper.parses(["a,b,c", "d,e,f"], delimiter=",")
             [['a', 'b', 'c'], ['d', 'e', 'f']]
         """
         if not isinstance(content, list):
-            raise SplurgeParameterError("content must be a list")
+            raise SplurgeDsvParameterError("content must be a list")
 
         if not all(isinstance(item, str) for item in content):
-            raise SplurgeParameterError("content must be a list of strings")
+            raise SplurgeDsvParameterError("content must be a list of strings")
 
         return [
             cls.parse(item, delimiter=delimiter, strip=strip, bookend=bookend, bookend_strip=bookend_strip)
@@ -130,31 +137,33 @@ class DsvHelper:
         skip_header_rows: int = DEFAULT_SKIP_HEADER_ROWS,
         skip_footer_rows: int = DEFAULT_SKIP_FOOTER_ROWS,
     ) -> list[list[str]]:
-        """
-        Parse a file into a list of lists of strings.
+        """Read and parse an entire DSV file.
+
+        This convenience reads all lines from ``file_path`` using
+        :class:`splurge_dsv.text_file_helper.TextFileHelper` and then parses each
+        line into tokens. Header and footer rows may be skipped via the
+        ``skip_header_rows`` and ``skip_footer_rows`` parameters.
 
         Args:
-            file_path (PathLike[str] | str): The path to the file to parse.
-            delimiter (str): The delimiter to use.
-            strip (bool): Whether to strip whitespace from the strings.
-            bookend (str | None): The bookend to use for text fields.
-            bookend_strip (bool): Whether to strip whitespace from the bookend.
-            encoding (str): The file encoding.
-            skip_header_rows (int): Number of header rows to skip.
-            skip_footer_rows (int): Number of footer rows to skip.
+            file_path: Path to the file to read.
+            delimiter: Delimiter to split fields on.
+            strip: If True, strip whitespace from tokens.
+            bookend: Optional bookend character to remove from tokens.
+            bookend_strip: If True, strip whitespace after removing bookends.
+            encoding: Text encoding to use when reading the file.
+            skip_header_rows: Number of leading lines to ignore.
+            skip_footer_rows: Number of trailing lines to ignore.
 
         Returns:
-            list[list[str]]: The list of lists of strings.
+            A list of token lists (one list per non-skipped line).
 
         Raises:
-            SplurgeParameterError: If delimiter is empty or None.
-            SplurgeFileNotFoundError: If the file does not exist.
-            SplurgeFilePermissionError: If the file cannot be accessed.
-            SplurgeFileEncodingError: If the file cannot be decoded with the specified encoding.
-
-        Example:
-            >>> DsvHelper.parse_file("data.csv", delimiter=",")
-            [['header1', 'header2'], ['value1', 'value2']]
+            SplurgeDsvParameterError: If ``delimiter`` is empty or None.
+            SplurgeDsvFileNotFoundError: If the file at ``file_path`` does not exist.
+            SplurgeDsvFilePermissionError: If the file cannot be accessed due to
+                permission restrictions.
+            SplurgeDsvFileEncodingError: If the file cannot be decoded using
+                the provided ``encoding``.
         """
         lines: list[str] = TextFileHelper.read(
             file_path, encoding=encoding, skip_header_rows=skip_header_rows, skip_footer_rows=skip_footer_rows
@@ -172,23 +181,26 @@ class DsvHelper:
         bookend: str | None = None,
         bookend_strip: bool = DEFAULT_BOOKEND_STRIP,
     ) -> list[list[str]]:
-        """
-        Process a chunk of lines from the stream.
+        """Parse a chunk of lines into tokenized rows.
+
+        Designed to be used by :meth:`parse_stream` as a helper for converting a
+        batch of raw lines into parsed rows.
 
         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
+            chunk: A list of raw input lines.
+            delimiter: Delimiter used to split each line.
+            strip: If True, strip whitespace from tokens.
+            bookend: Optional bookend character to remove from tokens.
+            bookend_strip: If True, strip whitespace after removing bookends.
 
         Returns:
-            list[list[str]]: Parsed rows
+            A list where each element is the token list for a corresponding
+            input line from ``chunk``.
         """
         return cls.parses(chunk, delimiter=delimiter, strip=strip, bookend=bookend, bookend_strip=bookend_strip)
 
     @classmethod
-    def parse_stream(
+    def parse_file_stream(
         cls,
         file_path: PathLike[str] | str,
         *,
@@ -202,7 +214,7 @@ class DsvHelper:
         chunk_size: int = DEFAULT_CHUNK_SIZE,
     ) -> Iterator[list[list[str]]]:
         """
-        Stream-parse a DSV file in chunks of lines.
+        Stream-parse a DSV file into chunks of lines.
 
         Args:
             file_path (PathLike[str] | str): The path to the file to parse.
@@ -225,7 +237,7 @@ class DsvHelper:
             SplurgeFileEncodingError: If the file cannot be decoded with the specified encoding.
         """
         if delimiter is None or delimiter == "":
-            raise SplurgeParameterError("delimiter cannot be empty or None")
+            raise SplurgeDsvParameterError("delimiter cannot be empty or None")
 
         chunk_size = max(chunk_size, cls.DEFAULT_MIN_CHUNK_SIZE)
         skip_header_rows = max(skip_header_rows, cls.DEFAULT_SKIP_HEADER_ROWS)
@@ -244,3 +256,51 @@ class DsvHelper:
                 chunk_size=chunk_size,
             )
         )
+
+    @classmethod
+    def parse_stream(
+        cls,
+        file_path: PathLike[str] | str,
+        *,
+        delimiter: str,
+        strip: bool = DEFAULT_STRIP,
+        bookend: str | None = None,
+        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,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+    ) -> 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(
+            "DsvHelper.parse_stream() is deprecated and will be removed in a future release; use DsvHelper.parse_file_stream() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return cls.parse_file_stream(
+            file_path,
+            delimiter=delimiter,
+            strip=strip,
+            bookend=bookend,
+            bookend_strip=bookend_strip,
+            encoding=encoding,
+            skip_header_rows=skip_header_rows,
+            skip_footer_rows=skip_footer_rows,
+            chunk_size=chunk_size,
+        )

splurge_dsv/exceptions.py

@@ -1,136 +1,153 @@
-"""
-Custom exceptions for the splurge-dsv package.
+"""Custom exceptions used across the splurge-dsv package.
 
-This module provides a hierarchy of custom exceptions for better error handling
-and more specific error messages throughout the package.
+This module defines a clear exception hierarchy so callers can catch
+specific error categories (file, validation, parsing, streaming, etc.)
+instead of dealing with generic builtins. Each exception stores a
+human-readable ``message`` and optional ``details`` for diagnostic output.
 
-Copyright (c) 2025 Jim Schilling
+Module contents are intentionally lightweight: exceptions are primarily
+containers for structured error information.
 
-Please preserve this header and all related material when sharing!
+Example:
+    raise SplurgeDsvFileNotFoundError("File not found", details="/data/foo.csv")
 
-This module is licensed under the MIT License.
+License: MIT
+
+Copyright (c) 2025 Jim Schilling
 """
 
 
 class SplurgeDsvError(Exception):
-    """Base exception for all splurge-dsv errors."""
+    """Base exception carrying a message and optional details.
 
-    def __init__(self, message: str, *, details: str | None = None) -> None:
-        """
-        Initialize SplurgeDsvError.
+    Args:
+        message: Primary error message to display to the user.
+        details: Optional machine-readable details useful for debugging.
+
+    Attributes:
+        message: User-facing error message.
+        details: Optional additional diagnostic information.
+    """
 
-        Args:
-            message: Primary error message
-            details: Additional error details
-        """
+    def __init__(self, message: str, *, details: str | None = None) -> None:
         self.message = message
         self.details = details
         super().__init__(self.message)
 
 
-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."""
+# New-style exception names. Use a SplurgeDsv* prefix to avoid colliding with
+# Python builtins. We keep the Splurge* aliases for backward compatibility.
 
-    pass
 
+class SplurgeDsvValidationError(SplurgeDsvError):
+    """Raised when data validation fails.
 
-class SplurgeFilePermissionError(SplurgeFileOperationError):
-    """Raised when there are permission issues with file operations."""
+    This exception indicates input or configuration values do not meet
+    expected constraints (for example: invalid delimiter, out-of-range
+    parameters, or malformed metadata).
+    """
 
-    pass
 
+class SplurgeDsvFileOperationError(SplurgeDsvError):
+    """Base exception for file operation errors.
 
-class SplurgeFileEncodingError(SplurgeFileOperationError):
-    """Raised when there are encoding issues with file operations."""
+    Used as a parent for file-related conditions such as not found,
+    permission denied, or encoding issues.
+    """
 
-    pass
 
+class SplurgeDsvFileNotFoundError(SplurgeDsvFileOperationError):
+    """Raised when an expected file cannot be located.
 
-class SplurgePathValidationError(SplurgeFileOperationError):
-    """Raised when file path validation fails."""
+    This typically maps to ``FileNotFoundError`` semantics but uses the
+    package-specific exception hierarchy so callers can distinguish
+    file errors from other error types.
+    """
 
-    pass
 
+class SplurgeDsvFilePermissionError(SplurgeDsvFileOperationError):
+    """Raised for permission or access-related file errors.
 
-class SplurgeDataProcessingError(SplurgeDsvError):
-    """Base exception for data processing errors."""
+    For example, attempting to open a file without read permission will
+    raise this exception.
+    """
 
-    pass
 
+class SplurgeDsvFileEncodingError(SplurgeDsvFileOperationError):
+    """Raised when decoding or encoding a text file fails.
 
-class SplurgeParsingError(SplurgeDataProcessingError):
-    """Raised when data parsing fails."""
+    The exception typically wraps the underlying decoding error and
+    provides a descriptive message and optional details for diagnostics.
+    """
 
-    pass
 
+class SplurgeDsvPathValidationError(SplurgeDsvFileOperationError):
+    """Raised when a provided filesystem path fails validation checks.
 
-class SplurgeTypeConversionError(SplurgeDataProcessingError):
-    """Raised when type conversion fails."""
+    Use this exception for path traversal, dangerous characters, or other
+    validation failures detected by the path validation utilities.
+    """
 
-    pass
 
+class SplurgeDsvDataProcessingError(SplurgeDsvError):
+    """Base exception for errors that occur during data processing (parsing, conversion).
 
-class SplurgeStreamingError(SplurgeDataProcessingError):
-    """Raised when streaming operations fail."""
+    This groups parsing, type conversion, and streaming errors that occur
+    while transforming file content into structured data.
+    """
 
-    pass
 
+class SplurgeDsvParsingError(SplurgeDsvDataProcessingError):
+    """Raised when parsing fails due to malformed or unexpected content."""
 
-class SplurgeConfigurationError(SplurgeDsvError):
-    """Raised when configuration is invalid."""
 
-    pass
+class SplurgeDsvTypeConversionError(SplurgeDsvDataProcessingError):
+    """Raised when a value cannot be converted to the requested type."""
 
 
-class SplurgeResourceError(SplurgeDsvError):
-    """Base exception for resource management errors."""
+class SplurgeDsvStreamingError(SplurgeDsvDataProcessingError):
+    """Raised for errors during streaming (e.g., partial reads, IO interruptions)."""
 
-    pass
 
+class SplurgeDsvConfigurationError(SplurgeDsvError):
+    """Raised when an invalid configuration is provided to an API.
 
-class SplurgeResourceAcquisitionError(SplurgeResourceError):
-    """Raised when resource acquisition fails."""
+    Examples include invalid chunk sizes, missing delimiters, or mutually
+    exclusive options supplied together.
+    """
 
-    pass
 
+class SplurgeDsvResourceError(SplurgeDsvError):
+    """Base exception for resource acquisition and release errors."""
 
-class SplurgeResourceReleaseError(SplurgeResourceError):
-    """Raised when resource release fails."""
 
-    pass
+class SplurgeDsvResourceAcquisitionError(SplurgeDsvResourceError):
+    """Raised when acquiring external resources (files, streams) fails."""
 
 
-class SplurgePerformanceWarning(SplurgeDsvError):
-    """Warning for performance-related issues."""
+class SplurgeDsvResourceReleaseError(SplurgeDsvResourceError):
+    """Raised when releasing resources (closing files or handles) fails."""
 
-    pass
 
+class SplurgeDsvPerformanceWarning(SplurgeDsvError):
+    """Raised to indicate performance-related concerns that may need attention.
 
-class SplurgeParameterError(SplurgeValidationError):
-    """Raised when function parameters are invalid."""
+    This is not a fatal error but can be used to signal suboptimal usage
+    patterns (for example, very small streaming chunk sizes) to callers.
+    """
 
-    pass
 
+class SplurgeDsvParameterError(SplurgeDsvValidationError):
+    """Raised when a function or method receives invalid parameters.
 
-class SplurgeRangeError(SplurgeValidationError):
-    """Raised when values are outside expected ranges."""
+    Use this for invalid types, missing required values, or arguments that
+    violate expected constraints.
+    """
 
-    pass
 
+class SplurgeDsvRangeError(SplurgeDsvValidationError):
+    """Raised when a value falls outside an expected numeric or length range."""
 
-class SplurgeFormatError(SplurgeValidationError):
-    """Raised when data format is invalid."""
 
-    pass
+class SplurgeDsvFormatError(SplurgeDsvValidationError):
+    """Raised when the data format is invalid or cannot be parsed as expected."""