splurge-dsv 2025.1.4__py3-none-any.whl → 2025.2.0__py3-none-any.whl

splurge_dsv/dsv_helper.py

@@ -13,7 +13,7 @@ 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 +43,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 +89,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 +136,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,18 +180,21 @@ 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)
 
@@ -225,7 +236,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)

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."""

splurge_dsv/path_validator.py

@@ -17,7 +17,11 @@ import re
 from pathlib import Path
 
 # Local imports
-from splurge_dsv.exceptions import SplurgeFileNotFoundError, SplurgeFilePermissionError, SplurgePathValidationError
+from splurge_dsv.exceptions import (
+    SplurgeDsvFileNotFoundError,
+    SplurgeDsvFilePermissionError,
+    SplurgeDsvPathValidationError,
+)
 
 # Module-level constants for path validation
 _MAX_PATH_LENGTH = 4096  # Maximum path length for most filesystems
@@ -94,24 +98,27 @@ class PathValidator:
         allow_relative: bool = True,
         base_directory: str | Path | None = None,
     ) -> Path:
-        """
-        Validate a file path for security and correctness.
+        """Validate a filesystem path for security and correctness.
+
+        This is the central path validation routine used across the package.
 
         Args:
-            file_path: Path to validate
-            must_exist: Whether the file must exist
-            must_be_file: Whether the path must be a file (not directory)
-            must_be_readable: Whether the file must be readable
-            allow_relative: Whether to allow relative paths
-            base_directory: Base directory for relative path resolution
+            file_path: Path or string to validate.
+            must_exist: If True, require the path to exist.
+            must_be_file: If True, require the path to be a regular file.
+            must_be_readable: If True, check read permission via os.access().
+            allow_relative: If False, disallow relative paths.
+            base_directory: Optional directory to resolve relative paths
+                against and to restrict the resolved path to.
 
         Returns:
-            Normalized Path object
+            pathlib.Path: Resolved and normalized path.
 
         Raises:
-            SplurgePathValidationError: If path validation fails
-            SplurgeFileNotFoundError: If file doesn't exist when required
-            SplurgeFilePermissionError: If file is not readable when required
+            SplurgeDsvPathValidationError: If any validation rule fails.
+            SplurgeDsvFileNotFoundError: If must_exist is True and file is missing.
+            SplurgeDsvFilePermissionError: If must_be_readable is True and the
+                file is not readable.
         """
         # Convert to Path object
         path = Path(file_path) if isinstance(file_path, str) else file_path
@@ -130,7 +137,7 @@ class PathValidator:
 
         # Handle relative paths
         if not path.is_absolute() and not allow_relative:
-            raise SplurgePathValidationError(
+            raise SplurgeDsvPathValidationError(
                 f"Relative paths are not allowed: {path}", details="Set allow_relative=True to allow relative paths"
             )
 
@@ -147,39 +154,39 @@ class PathValidator:
                 try:
                     resolved_path.relative_to(base_path)
                 except ValueError:
-                    raise SplurgePathValidationError(
+                    raise SplurgeDsvPathValidationError(
                         f"Path {path} resolves outside base directory {base_directory}",
                         details="Path traversal detected",
                     ) from None
             else:
                 resolved_path = path.resolve()
         except (OSError, RuntimeError) as e:
-            raise SplurgePathValidationError(
+            raise SplurgeDsvPathValidationError(
                 f"Failed to resolve path {path}: {e}", details="Check if path contains invalid characters or symlinks"
             ) from e
 
         # Check if file exists
         if must_exist and not resolved_path.exists():
-            raise SplurgeFileNotFoundError(
+            raise SplurgeDsvFileNotFoundError(
                 f"File does not exist: {resolved_path}", details="Set must_exist=False to allow non-existent files"
             )
 
         # Check if it's a file (not directory)
         if must_be_file and resolved_path.exists() and not resolved_path.is_file():
-            raise SplurgePathValidationError(
+            raise SplurgeDsvPathValidationError(
                 f"Path is not a file: {resolved_path}", details="Path exists but is not a regular file"
             )
 
         # Check if file is readable
         if must_be_readable:
             if not resolved_path.exists():
-                raise SplurgeFileNotFoundError(
+                raise SplurgeDsvFileNotFoundError(
                     f"Cannot check readability of non-existent file: {resolved_path}",
                     details="File must exist to check readability",
                 )
 
             if not os.access(resolved_path, os.R_OK):
-                raise SplurgeFilePermissionError(
+                raise SplurgeDsvFilePermissionError(
                     f"File is not readable: {resolved_path}", details="Check file permissions"
                 )
 
@@ -187,26 +194,24 @@ class PathValidator:
 
     @classmethod
     def _is_valid_windows_drive_pattern(cls, path_str: str) -> bool:
-        """
-        Check if a path string contains a valid Windows drive letter pattern.
+        """Return True if ``path_str`` looks like a valid Windows drive pattern.
 
-        Args:
-            path_str: Path string to validate
-
-        Returns:
-            True if the path contains a valid Windows drive letter pattern,
-            False otherwise
+        Accepts both ``C:`` and ``C:\\...`` or ``C:/...`` forms.
         """
         # Must be C: at the end of the string, or C:\ (or C:/) followed by path
         return bool(re.match(r"^[A-Za-z]:$", path_str)) or bool(re.match(r"^[A-Za-z]:[\\/]", path_str))
 
     @classmethod
     def _check_dangerous_characters(cls, path_str: str) -> None:
-        """Check for dangerous characters in path string."""
+        """Raise if ``path_str`` contains characters disallowed by policy.
+
+        This guards against NULs, control characters, and reserved filesystem
+        characters which may be used in injection or traversal attacks.
+        """
         # Check for dangerous characters, but allow colons in Windows drive letters
         for char in cls._DANGEROUS_CHARS:
             if char in path_str:
-                raise SplurgePathValidationError(
+                raise SplurgeDsvPathValidationError(
                     f"Path contains dangerous character: {repr(char)}",
                     details=f"Character at position {path_str.find(char)}",
                 )
@@ -214,25 +219,33 @@ class PathValidator:
         # Special handling for colons - only allow them in Windows drive letters (e.g., C:)
         if ":" in path_str:
             if not cls._is_valid_windows_drive_pattern(path_str):
-                raise SplurgePathValidationError(
+                raise SplurgeDsvPathValidationError(
                     "Path contains colon in invalid position",
                     details="Colons are only allowed in Windows drive letters (e.g., C: or C:\\)",
                 )
 
     @classmethod
     def _check_path_traversal(cls, path_str: str) -> None:
-        """Check for path traversal patterns."""
+        """Raise if ``path_str`` contains obvious traversal patterns.
+
+        This is a best-effort check that catches sequences such as ``..``
+        and unusual repeated separators that are likely malicious.
+        """
         for pattern in cls._PATH_TRAVERSAL_PATTERNS:
             if re.search(pattern, path_str):
-                raise SplurgePathValidationError(
+                raise SplurgeDsvPathValidationError(
                     f"Path contains traversal pattern: {pattern}", details="Path traversal attacks are not allowed"
                 )
 
     @classmethod
     def _check_path_length(cls, path_str: str) -> None:
-        """Check if path length is within acceptable limits."""
+        """Raise if the path exceeds the configured maximum length.
+
+        Long paths can indicate malformed input or attempt to overflow
+        downstream APIs; this check enforces a sane upper bound.
+        """
         if len(path_str) > cls.MAX_PATH_LENGTH:
-            raise SplurgePathValidationError(
+            raise SplurgeDsvPathValidationError(
                 f"Path is too long: {len(path_str)} characters",
                 details=f"Maximum allowed length is {cls.MAX_PATH_LENGTH} characters",
             )
@@ -281,5 +294,5 @@ class PathValidator:
         try:
             cls.validate_path(file_path)
             return True
-        except (SplurgePathValidationError, SplurgeFileNotFoundError, SplurgeFilePermissionError):
+        except (SplurgeDsvPathValidationError, SplurgeDsvFileNotFoundError, SplurgeDsvFilePermissionError):
             return False