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

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

splurge_dsv/safe_text_file_reader.py

@@ -0,0 +1,177 @@
+"""Safe text file reader utilities.
+
+This module implements :class:`SafeTextFileReader`, a small helper that reads
+text files in binary mode and performs deterministic newline normalization.
+It intentionally decodes bytes explicitly to avoid platform newline
+translation side-effects and centralizes encoding error handling into a
+package-specific exception type.
+
+Public API summary:
+        - SafeTextFileReader: Read, preview, and stream text files with normalized
+            newlines and optional header/footer skipping.
+        - open_text: Context manager returning an in-memory text stream for
+            callers that expect a file-like object.
+
+Example:
+        reader = SafeTextFileReader("data.csv", encoding="utf-8")
+        lines = reader.read()
+
+License: MIT
+
+Copyright (c) 2025 Jim Schilling
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from io import StringIO
+from pathlib import Path
+
+from splurge_dsv.exceptions import SplurgeDsvFileEncodingError
+
+
+class SafeTextFileReader:
+    """Read text files with deterministic newline normalization.
+
+    The class reads raw bytes from disk and decodes using the provided
+    encoding. Newline sequences are normalized to ``\n`` (LF). Public
+    methods provide convenience wrappers for full reads, previews and
+    chunked streaming.
+
+    Args:
+        file_path (Path | str): Path to the file to read.
+        encoding (str): Encoding to use when decoding bytes (default: utf-8).
+
+    Example:
+        reader = SafeTextFileReader("/tmp/data.csv", encoding="utf-8")
+        rows = reader.read(skip_header_rows=1)
+    """
+
+    def __init__(self, file_path: Path | str, *, encoding: str = "utf-8") -> None:
+        self.path = Path(file_path)
+        self.encoding = encoding
+
+    def _read_text(self) -> str:
+        """Read the file bytes and return decoded text with no newline normalization applied.
+
+        Returns:
+            Decoded text (str).
+
+        Raises:
+            SplurgeDsvFileEncodingError: If decoding fails or the file cannot
+                be read.
+        """
+        try:
+            # Read raw bytes and decode explicitly to avoid the platform's
+            # text-mode newline translations which can alter mixed line endings.
+            with self.path.open("rb") as fh:
+                raw = fh.read()
+            return raw.decode(self.encoding)
+        except Exception as e:
+            raise SplurgeDsvFileEncodingError(f"Encoding error reading file: {self.path}", details=str(e)) from e
+
+    def read(self, *, strip: bool = True, skip_header_rows: int = 0, skip_footer_rows: int = 0) -> list[str]:
+        """Read the entire file and return a list of normalized lines.
+
+        Newlines are normalized to ``\n`` and optional header/footer rows
+        can be skipped. If ``strip`` is True, whitespace surrounding each
+        line is removed.
+
+        Args:
+            strip (bool): Strip whitespace from each line (default: True).
+            skip_header_rows (int): Number of rows to skip at the start.
+            skip_footer_rows (int): Number of rows to skip at the end.
+
+        Returns:
+            List of lines as strings.
+        """
+        text = self._read_text()
+        # Normalize newlines to LF
+        normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+        lines = normalized.splitlines()
+
+        if skip_header_rows:
+            lines = lines[skip_header_rows:]
+        if skip_footer_rows:
+            if skip_footer_rows >= len(lines):
+                return []
+            lines = lines[:-skip_footer_rows]
+
+        if strip:
+            return [ln.strip() for ln in lines]
+        return list(lines)
+
+    def preview(self, max_lines: int = 100, *, strip: bool = True, skip_header_rows: int = 0) -> list[str]:
+        """Return the first ``max_lines`` lines of the file after normalization.
+
+        Args:
+            max_lines (int): Maximum number of lines to return.
+            strip (bool): Strip whitespace from each returned line.
+            skip_header_rows (int): Number of header rows to skip before previewing.
+
+        Returns:
+            A list of preview lines.
+        """
+        text = self._read_text()
+        normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+        lines = normalized.splitlines()
+        if skip_header_rows:
+            lines = lines[skip_header_rows:]
+        if max_lines < 1:
+            return []
+        result = lines[:max_lines]
+        return [ln.strip() for ln in result] if strip else list(result)
+
+    def read_as_stream(
+        self, *, strip: bool = True, skip_header_rows: int = 0, skip_footer_rows: int = 0, chunk_size: int = 500
+    ) -> Iterator[list[str]]:
+        """Yield chunks of lines from the file.
+
+        This convenience method currently reads the decoded file into memory
+        and yields chunks of ``chunk_size`` lines. For very large files this
+        could be optimized to stream from disk without full materialization.
+
+        Args:
+            strip (bool): Whether to strip whitespace from each line.
+            skip_header_rows (int): Number of header rows to skip.
+            skip_footer_rows (int): Number of footer rows to skip.
+            chunk_size (int): Number of lines per yielded chunk.
+
+        Yields:
+            Lists of lines (each list length <= chunk_size).
+        """
+        lines = self.read(strip=strip, skip_header_rows=skip_header_rows, skip_footer_rows=skip_footer_rows)
+        chunk: list[str] = []
+        for ln in lines:
+            chunk.append(ln)
+            if len(chunk) >= chunk_size:
+                yield chunk
+                chunk = []
+        if chunk:
+            yield chunk
+
+
+@contextmanager
+def open_text(file_path: Path | str, *, encoding: str = "utf-8"):
+    """Context manager returning a text stream (io.StringIO) with normalized newlines.
+
+    Useful when an API expects a file-like object. The returned StringIO
+    contains the normalized text (LF newlines) and is closed automatically
+    when the context exits.
+
+    Args:
+        file_path: Path to the file to open.
+        encoding: Encoding to decode the file with.
+
+    Yields:
+        io.StringIO: In-memory text buffer with normalized newlines.
+    """
+    reader = SafeTextFileReader(file_path, encoding=encoding)
+    text_lines = reader.read(strip=False)
+    text = "\n".join(text_lines)
+    sio = StringIO(text)
+    try:
+        yield sio
+    finally:
+        sio.close()

splurge_dsv/safe_text_file_writer.py

@@ -0,0 +1,136 @@
+"""Deterministic text-only writer utilities.
+
+This module implements :class:`SafeTextFileWriter` and a convenience
+``open_text_writer`` context manager. Writes always use the configured
+encoding and normalize newline characters to a canonical form (LF) to
+ensure consistent files across platforms.
+
+Example:
+    with open_text_writer("out.txt") as buf:
+        buf.write("line1\nline2\n")
+
+Copyright (c) 2025 Jim Schilling
+Please preserve this header and all related material when sharing!
+
+License: MIT
+"""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import cast
+
+from .exceptions import SplurgeDsvFileEncodingError
+
+
+class SafeTextFileWriter:
+    """Helper for deterministic text writes with newline normalization.
+
+    Args:
+        file_path: Destination file path.
+        encoding: Text encoding to use (default: 'utf-8').
+        newline: Canonical newline sequence to write (default: '\n').
+
+    The class exposes a minimal file-like API and will raise
+    :class:`SplurgeDsvFileEncodingError` when the underlying file cannot be
+    opened with the requested encoding.
+    """
+
+    def __init__(self, file_path: Path, *, encoding: str = "utf-8", newline: str | None = "\n") -> None:
+        self._path = Path(file_path)
+        self._encoding = encoding
+        # newline is the canonical newline we will write; default to LF
+        self._newline = "\n" if newline is None else newline
+        self._file: io.TextIOBase | None = None
+
+    def open(self, mode: str = "w") -> io.TextIOBase:
+        """Open the underlying file for text writing.
+
+        Args:
+            mode: File open mode (default: 'w').
+
+        Returns:
+            The opened text file object.
+
+        Raises:
+            SplurgeDsvFileEncodingError: If the file cannot be opened with the
+                requested encoding or underlying OS error occurs.
+        """
+        try:
+            # open with newline="" to allow us to manage newline normalization
+            fp = open(self._path, mode, encoding=self._encoding, newline="")
+            # cast to TextIOBase for precise typing
+            self._file = cast(io.TextIOBase, fp)
+            return self._file
+        except (LookupError, OSError) as exc:
+            raise SplurgeDsvFileEncodingError(str(exc)) from exc
+
+    def write(self, text: str) -> int:
+        """Normalize newlines and write ``text`` to the opened file.
+
+        Args:
+            text: Text to write (newlines will be normalized).
+
+        Returns:
+            Number of characters written.
+        """
+        if self._file is None:
+            raise ValueError("file not opened")
+        normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+        return self._file.write(normalized)
+
+    def writelines(self, lines: Iterable[str]) -> None:
+        if self._file is None:
+            raise ValueError("file not opened")
+        for line in lines:
+            self.write(line)
+
+    def flush(self) -> None:
+        if self._file is None:
+            return
+        self._file.flush()
+
+    def close(self) -> None:
+        if self._file is None:
+            return
+        try:
+            self._file.close()
+        finally:
+            self._file = None
+
+
+@contextmanager
+def open_text_writer(file_path: Path | str, *, encoding: str = "utf-8", mode: str = "w") -> Iterator[io.StringIO]:
+    """Context manager yielding an in-memory StringIO to accumulate text.
+
+    On successful exit, the buffered content is normalized and written to
+    disk using :class:`SafeTextFileWriter`. If an exception occurs inside
+    the context, nothing is written and the exception is propagated.
+
+    Args:
+        file_path: Destination path to write to on successful exit.
+        encoding: Encoding to use when writing.
+        mode: File open mode passed to writer (default: 'w').
+
+    Yields:
+        io.StringIO: Buffer to write textual content into.
+    """
+    path = Path(file_path)
+    buffer = io.StringIO()
+    try:
+        yield buffer
+    except Exception:
+        # Do not write on exceptions; re-raise
+        raise
+    else:
+        content = buffer.getvalue()
+        writer = SafeTextFileWriter(path, encoding=encoding)
+        try:
+            writer.open(mode=mode)
+            writer.write(content)
+            writer.flush()
+        finally:
+            writer.close()

splurge_dsv/string_tokenizer.py

@@ -12,7 +12,7 @@ This module is licensed under the MIT License.
 """
 
 # Local imports
-from splurge_dsv.exceptions import SplurgeParameterError
+from splurge_dsv.exceptions import SplurgeDsvParameterError
 
 
 class StringTokenizer:
@@ -29,21 +29,24 @@ class StringTokenizer:
 
     @staticmethod
     def parse(content: str | None, *, delimiter: str, strip: bool = DEFAULT_STRIP) -> list[str]:
-        """
-        Split a string into tokens based on a delimiter.
+        """Tokenize a single string using ``delimiter``.
+
+        The function preserves empty tokens (e.g. ``"a,,c"`` with
+        delimiter ``","`` yields ``['a', '', 'c']``). If ``content`` is
+        None an empty list is returned.
 
         Args:
-            content (str | None): The input string to tokenize
-            delimiter (str): The character(s) to split the string on
-            strip (bool, optional): Whether to strip whitespace from tokens. Defaults to True.
+            content: The input string to tokenize, or ``None``.
+            delimiter: The delimiter string to split on.
+            strip: If True, strip leading/trailing whitespace from each token.
 
         Returns:
-            list[str]: List of tokens, preserving empty tokens
+            A list of tokens. Empty tokens are preserved.
 
         Raises:
-            SplurgeParameterError: If delimiter is empty or None
+            SplurgeDsvParameterError: If ``delimiter`` is empty or ``None``.
 
-        Example:
+        Examples:
             >>> StringTokenizer.parse("a,b,c", delimiter=",")
             ['a', 'b', 'c']
             >>> StringTokenizer.parse("a,,c", delimiter=",")
@@ -53,7 +56,7 @@ class StringTokenizer:
             return []
 
         if delimiter is None or delimiter == "":
-            raise SplurgeParameterError("delimiter cannot be empty or None")
+            raise SplurgeDsvParameterError("delimiter cannot be empty or None")
 
         if strip and not content.strip():
             return []
@@ -65,51 +68,56 @@ class StringTokenizer:
 
     @classmethod
     def parses(cls, content: list[str], *, delimiter: str, strip: bool = DEFAULT_STRIP) -> list[list[str]]:
-        """
-        Process multiple strings into lists of tokens.
+        """Tokenize multiple strings.
 
         Args:
-            content (list[str]): List of strings to tokenize
-            delimiter (str): The character(s) to split each string on
-            strip (bool, optional): Whether to strip whitespace from tokens. Defaults to True.
+            content: A list of strings to tokenize.
+            delimiter: The delimiter to use for splitting.
+            strip: If True, strip whitespace from tokens.
 
         Returns:
-            list[list[str]]: List of token lists, one for each input string
+            A list where each element is the token list for the corresponding
+            input string.
 
         Raises:
-            SplurgeParameterError: If delimiter is empty or None
+            SplurgeDsvParameterError: If ``delimiter`` is empty or ``None``.
 
         Example:
             >>> StringTokenizer.parses(["a,b", "c,d"], delimiter=",")
             [['a', 'b'], ['c', 'd']]
         """
         if delimiter is None or delimiter == "":
-            raise SplurgeParameterError("delimiter cannot be empty or None")
+            raise SplurgeDsvParameterError("delimiter cannot be empty or None")
 
         return [cls.parse(text, delimiter=delimiter, strip=strip) for text in content]
 
     @staticmethod
     def remove_bookends(content: str, *, bookend: str, strip: bool = DEFAULT_STRIP) -> str:
-        """
-        Remove matching characters from both ends of a string.
+        """Remove matching bookend characters from both endpoints of ``content``.
+
+        The function optionally strips surrounding whitespace before checking
+        for matching bookend characters. If both ends match the provided
+        ``bookend`` and the remaining content is long enough, the bookends are
+        removed; otherwise the possibly-stripped input is returned unchanged.
 
         Args:
-            content (str): The input string to process
-            bookend (str): The character(s) to remove from both ends
-            strip (bool, optional): Whether to strip whitespace first. Defaults to True.
+            content: The input string to process.
+            bookend: The bookend string to remove from both ends (e.g. '"').
+            strip: If True, strip whitespace prior to bookend removal.
 
         Returns:
-            str: The string with matching bookends removed
+            The input string with matching bookend characters removed when
+            applicable.
 
         Raises:
-            SplurgeParameterError: If bookend is empty or None
+            SplurgeDsvParameterError: If ``bookend`` is empty or ``None``.
 
         Example:
             >>> StringTokenizer.remove_bookends("'hello'", bookend="'")
             'hello'
         """
         if bookend is None or bookend == "":
-            raise SplurgeParameterError("bookend cannot be empty or None")
+            raise SplurgeDsvParameterError("bookend cannot be empty or None")
 
         value: str = content.strip() if strip else content
         if value.startswith(bookend) and value.endswith(bookend) and len(value) > 2 * len(bookend) - 1: