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

splurge_dsv/safe_text_file_writer.py

@@ -1,136 +0,0 @@
-"""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/text_file_helper.py

@@ -1,240 +0,0 @@
-"""
-Text file utility functions for common file operations.
-
-This module provides helper methods for working with text files, including
-line counting, file previewing, and file loading capabilities. The TextFileHelper
-class implements static methods for efficient file operations without requiring
-class instantiation.
-
-Key features:
-- Line counting for text files
-- File previewing with configurable line limits
-- Complete file loading with header/footer skipping
-- Streaming file loading with configurable chunk sizes
-- Configurable whitespace handling and encoding
-- Secure file path validation
-- Resource management with context managers
-
-Copyright (c) 2025 Jim Schilling
-
-Please preserve this header and all related material when sharing!
-
-This module is licensed under the MIT License.
-"""
-
-# Standard library imports
-from collections.abc import Iterator
-from os import PathLike
-from pathlib import Path
-
-# Local imports
-from splurge_dsv.exceptions import SplurgeDsvParameterError
-from splurge_dsv.path_validator import PathValidator
-from splurge_dsv.safe_text_file_reader import SafeTextFileReader
-
-
-class TextFileHelper:
-    """Utility helpers for working with text files.
-
-    All methods are provided as classmethods and are designed to be memory
-    efficient. This module enforces a deterministic newline policy: CRLF
-    ("\r\n"), CR ("\r"), and LF ("\n") are normalized to a single ``\n``
-    newline. Methods return logical, normalized lines which makes behavior
-    consistent across platforms and simplifies testing.
-    """
-
-    DEFAULT_ENCODING = "utf-8"
-    DEFAULT_MAX_LINES = 100
-    DEFAULT_CHUNK_SIZE = 500
-    DEFAULT_MIN_CHUNK_SIZE = 100
-    DEFAULT_SKIP_HEADER_ROWS = 0
-    DEFAULT_SKIP_FOOTER_ROWS = 0
-    DEFAULT_STRIP = True
-    DEFAULT_MODE = "r"
-
-    @classmethod
-    def line_count(cls, file_path: PathLike[str] | str, *, encoding: str = DEFAULT_ENCODING) -> int:
-        """Return the number of logical lines in ``file_path``.
-
-        The file is iterated efficiently without reading the entire contents
-        into memory. Newlines are normalized according to the package newline
-        policy before counting.
-
-        Args:
-            file_path: Path to the text file to inspect.
-            encoding: Text encoding to use when reading the file.
-
-        Returns:
-            The number of logical lines in the file.
-
-        Raises:
-            SplurgeDsvFileNotFoundError: If ``file_path`` does not exist.
-            SplurgeDsvFilePermissionError: If the file cannot be read due to
-                permissions.
-            SplurgeDsvFileEncodingError: If the file cannot be decoded using the
-                provided ``encoding``.
-            SplurgeDsvPathValidationError: If path validation fails.
-        """
-        # Validate file path
-        validated_path = PathValidator.validate_path(
-            Path(file_path), must_exist=True, must_be_file=True, must_be_readable=True
-        )
-
-        # Delegate to SafeTextFileReader which centralizes newline normalization
-        reader = SafeTextFileReader(validated_path, encoding=encoding)
-        return len(reader.read(strip=False))
-
-    @classmethod
-    def preview(
-        cls,
-        file_path: PathLike[str] | str,
-        *,
-        max_lines: int = DEFAULT_MAX_LINES,
-        strip: bool = DEFAULT_STRIP,
-        encoding: str = DEFAULT_ENCODING,
-        skip_header_rows: int = DEFAULT_SKIP_HEADER_ROWS,
-    ) -> list[str]:
-        """Return the first ``max_lines`` logical lines from ``file_path``.
-
-        The preview respects header skipping and optional whitespace
-        stripping. Lines returned are normalized according to the package
-        newline policy.
-
-        Args:
-            file_path: Path to the text file.
-            max_lines: Maximum number of lines to return (must be >= 1).
-            strip: If True, strip leading/trailing whitespace from each line.
-            encoding: File encoding to use when reading the file.
-            skip_header_rows: Number of leading lines to ignore before previewing.
-
-        Returns:
-            A list of logical lines (strings), up to ``max_lines`` in length.
-
-        Raises:
-            SplurgeDsvParameterError: If ``max_lines`` is less than 1.
-            SplurgeDsvFileNotFoundError: If ``file_path`` does not exist.
-            SplurgeDsvFilePermissionError: If the file cannot be read due to
-                permissions.
-            SplurgeDsvFileEncodingError: If the file cannot be decoded using the
-                provided ``encoding``.
-            SplurgeDsvPathValidationError: If path validation fails.
-        """
-        if max_lines < 1:
-            raise SplurgeDsvParameterError(
-                "TextFileHelper.preview: max_lines is less than 1", details="max_lines must be at least 1"
-            )
-
-        # Validate file path
-        validated_path = PathValidator.validate_path(
-            Path(file_path), must_exist=True, must_be_file=True, must_be_readable=True
-        )
-
-        skip_header_rows = max(skip_header_rows, cls.DEFAULT_SKIP_HEADER_ROWS)
-        reader = SafeTextFileReader(validated_path, encoding=encoding)
-        return reader.preview(max_lines=max_lines, strip=strip, skip_header_rows=skip_header_rows)
-
-    @classmethod
-    def read_as_stream(
-        cls,
-        file_path: PathLike[str] | str,
-        *,
-        strip: bool = DEFAULT_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[str]]:
-        """Yield the file contents as successive chunks of logical lines.
-
-        Each yielded value is a list of lines (strings), where each chunk
-        contains up to ``chunk_size`` lines. Footer skipping is implemented
-        using a sliding-window technique so the file is not fully loaded into
-        memory.
-
-        Args:
-            file_path: Path to the text file to stream.
-            strip: If True, strip leading/trailing whitespace from each line.
-            encoding: Text encoding used to read the file.
-            skip_header_rows: Number of leading lines to skip before yielding.
-            skip_footer_rows: Number of trailing lines to skip (handled via
-                an internal buffer; does not require reading the whole file).
-            chunk_size: Target number of lines per yielded chunk.
-
-        Yields:
-            Lists of logical lines (each a list[str]) for each chunk.
-
-        Raises:
-            SplurgeDsvFileNotFoundError: If ``file_path`` does not exist.
-            SplurgeDsvFilePermissionError: If the file cannot be read due to
-                permissions.
-            SplurgeDsvFileEncodingError: If the file cannot be decoded using the
-                provided ``encoding``.
-            SplurgeDsvPathValidationError: If path validation fails.
-        """
-        # Allow small chunk sizes for testing, but enforce minimum for performance
-        # Only enforce minimum if chunk_size is "moderately small" (to prevent accidental small chunks)
-        if chunk_size >= 10:  # If someone sets a chunk size >= 10, enforce minimum for performance
-            chunk_size = max(chunk_size, cls.DEFAULT_MIN_CHUNK_SIZE)
-        # For very small chunk sizes (like 1-9), allow them (useful for testing)
-        skip_header_rows = max(skip_header_rows, cls.DEFAULT_SKIP_HEADER_ROWS)
-        skip_footer_rows = max(skip_footer_rows, cls.DEFAULT_SKIP_FOOTER_ROWS)
-
-        # Validate file path
-        validated_path = PathValidator.validate_path(
-            Path(file_path), must_exist=True, must_be_file=True, must_be_readable=True
-        )
-
-        # Use SafeTextFileReader to centralize newline normalization and streaming behavior.
-        reader = SafeTextFileReader(validated_path, encoding=encoding)
-        yield from reader.read_as_stream(
-            strip=strip, skip_header_rows=skip_header_rows, skip_footer_rows=skip_footer_rows, chunk_size=chunk_size
-        )
-
-    @classmethod
-    def read(
-        cls,
-        file_path: PathLike[str] | str,
-        *,
-        strip: bool = DEFAULT_STRIP,
-        encoding: str = DEFAULT_ENCODING,
-        skip_header_rows: int = DEFAULT_SKIP_HEADER_ROWS,
-        skip_footer_rows: int = DEFAULT_SKIP_FOOTER_ROWS,
-    ) -> list[str]:
-        """Read all logical lines from ``file_path`` into memory.
-
-        This convenience method returns the entire file as a list of
-        normalized lines. Header and footer rows may be skipped with the
-        corresponding parameters.
-
-        Args:
-            file_path: Path to the text file to read.
-            strip: If True, strip leading/trailing whitespace from each line.
-            encoding: Text encoding used to read the file.
-            skip_header_rows: Number of leading lines to ignore.
-            skip_footer_rows: Number of trailing lines to ignore.
-
-        Returns:
-            A list containing every logical line from the file except skipped
-            header/footer lines.
-
-        Raises:
-            SplurgeDsvFileNotFoundError: If ``file_path`` does not exist.
-            SplurgeDsvFilePermissionError: If the file cannot be read due to
-                permissions.
-            SplurgeDsvFileEncodingError: If the file cannot be decoded using the
-                provided ``encoding``.
-            SplurgeDsvPathValidationError: If path validation fails.
-        """
-        # Validate file path
-        validated_path = PathValidator.validate_path(
-            Path(file_path), must_exist=True, must_be_file=True, must_be_readable=True
-        )
-
-        skip_header_rows = max(skip_header_rows, cls.DEFAULT_SKIP_HEADER_ROWS)
-        skip_footer_rows = max(skip_footer_rows, cls.DEFAULT_SKIP_FOOTER_ROWS)
-
-        skip_header_rows = max(skip_header_rows, cls.DEFAULT_SKIP_HEADER_ROWS)
-        skip_footer_rows = max(skip_footer_rows, cls.DEFAULT_SKIP_FOOTER_ROWS)
-
-        reader = SafeTextFileReader(validated_path, encoding=encoding)
-        return reader.read(strip=strip, skip_header_rows=skip_header_rows, skip_footer_rows=skip_footer_rows)

splurge_dsv-2025.2.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-splurge_dsv/__init__.py,sha256=5TfARRtn0dMytGL4TnlEOWBon3HJiwN8MKEdHMItPZI,3337
-splurge_dsv/__main__.py,sha256=6dpfX_96hEpOqxv5X4bK73xX86YTgK0Adad1uTWSABM,426
-splurge_dsv/cli.py,sha256=qm7ZwgkUjMW5ASj14kWFyXrXY2T-MGhiCFHh8XUHi38,7605
-splurge_dsv/dsv.py,sha256=5wDtHDk8Iio2SAIPO7Ce01dGhzH3fv12by8hQcPkJVI,9873
-splurge_dsv/dsv_helper.py,sha256=ppFVZ4LNSepWbVJtYMQvsZGmMBDr6nbP4yKZettWczk,12060
-splurge_dsv/exceptions.py,sha256=hefUTjk3ULca5TdXoKe5L-cME7SU1RFcWVHxNpZ_w-Y,5274
-splurge_dsv/path_validator.py,sha256=r08PkuMdL0eBY_iao00_irBMdT6ORJ2-cNK5AUssEKs,10681
-splurge_dsv/safe_text_file_reader.py,sha256=9GCOGCTDDP5FJD0u2wZ107SQNEIj9Rm1zN6shYiKq7g,6659
-splurge_dsv/safe_text_file_writer.py,sha256=zQIsDZ6jRN_ZWwLX4dpUZI35iudxzuv1Gjv7K1vSFJk,4562
-splurge_dsv/string_tokenizer.py,sha256=jFgkqeGx5PnmKAvu7sn3xxHcQklZTZUy8x_eo5e6TWI,4497
-splurge_dsv/text_file_helper.py,sha256=2SxbYtZtpMtHQ-5g1aQzgvQobBrlQH4EsrhBY5t3Xx4,10362
-splurge_dsv-2025.2.1.dist-info/licenses/LICENSE,sha256=fPgtg-tIFHinQvJH0arRfv50AuxikD5eHw6rrPy2A5w,1091
-splurge_dsv-2025.2.1.dist-info/METADATA,sha256=V1gWLbEKupAzTYWWvgx1UviuOtkjEhAYuPQ6pwOsDYM,8518
-splurge_dsv-2025.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-splurge_dsv-2025.2.1.dist-info/entry_points.txt,sha256=QmGyc3qHYtY61uanRxNOXw-waSJ01qypSCI8Kb3zgsU,56
-splurge_dsv-2025.2.1.dist-info/top_level.txt,sha256=D6Si3FTfpRYqH7kzM7tSQAyaKbbraO6UPLpcqcY4XXM,12
-splurge_dsv-2025.2.1.dist-info/RECORD,,