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

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: