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

splurge_dsv/string_tokenizer.py

@@ -58,8 +58,14 @@ class StringTokenizer:
         if delimiter is None or delimiter == "":
             raise SplurgeDsvParameterError("delimiter cannot be empty or None")
 
+        # If stripping is enabled and the input is only whitespace (or
+        # empty), treat it as a single empty token rather than returning an
+        # empty list. Returning [] causes downstream code that expects the
+        # same number of columns as the header to raise IndexError. The
+        # external safe reader yields empty strings for blank lines, so we
+        # preserve that semantic here.
         if strip and not content.strip():
-            return []
+            return [""]
 
         result: list[str] = content.split(delimiter)
         if strip:

{splurge_dsv-2025.2.0.dist-info → splurge_dsv-2025.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splurge-dsv
-Version: 2025.2.0
+Version: 2025.3.1
 Summary: A utility library for working with DSV (Delimited String Values) files
 Author: Jim Schilling
 License-Expression: MIT
@@ -21,10 +21,11 @@ Classifier: Topic :: Text Processing :: Filters
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: splurge-safe-io>=2025.0.5
+Requires-Dist: PyYAML>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: ruff>=0.0.241; extra == "dev"
 Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
@@ -38,7 +39,7 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 [![CI](https://github.com/jim-schilling/splurge-dsv/actions/workflows/ci-quick-test.yml/badge.svg)](https://github.com/jim-schilling/splurge-dsv/actions/workflows/ci-quick-test.yml)
-[![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)](https://github.com/jim-schilling/splurge-dsv)
+[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen.svg)](https://github.com/jim-schilling/splurge-dsv)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![mypy](https://img.shields.io/badge/mypy-checked-black)](https://mypy-lang.org/)
 
@@ -46,12 +47,49 @@ A robust Python library for parsing and processing delimited-separated value (DS
 
 ## Features
 
-- **Multi-format DSV Support**: Parse CSV, TSV, pipe-delimited, and custom delimiter files
+- **Multi-format DSV Support**: Parse CSV, TSV, pipe-delimited, and custom delimiter separated value files/objects
+- **Configurable Parsing**: Flexible options for delimiters, quote characters, escape characters, header/footer row(s) handling
 - **Memory-Efficient Streaming**: Process large files without loading entire content into memory
 - **Security & Validation**: Comprehensive path validation and file permission checks
 - **Unicode Support**: Full Unicode character and encoding support
 - **Type Safety**: Full type annotations with mypy validation
-- **Comprehensive Testing**: 420 tests (409 passed, 11 skipped) with 94% code coverage including property-based testing, edge case testing, and cross-platform compatibility
+- **Deterministic Newline Handling**: Consistent handling of CRLF, CR, and LF newlines across platforms
+- **CLI Tool**: Command-line interface for quick parsing and inspection of DSV files
+- **Robust Error Handling**: Clear and specific exceptions for various error scenarios
+- **Modern API**: Object-oriented API with `Dsv` and `DsvConfig` classes for easy configuration and reuse
+- **Comprehensive Documentation**: In-depth API reference and usage examples
+- **Exhaustive Testing**: 283 tests with 93% code coverage including property-based testing, edge case testing, and cross-platform compatibility validation
+
+**⚠️ CHANGES in v2025.3.1**
+> - **skip_empty_lines** option added to `DsvConfig`, `DsvHelper`, and CLI.
+>   - This option allows users to skip logical empty lines when parsing DSV files.
+
+**⚠️ CHANGES in v2025.3.0**
+> - **Commit-Only Release**: v2025.3.0 is a commit-only release and will not be published to PyPI.
+> - The legacy `parse_stream()` helpers were removed in release 2025.3.0.
+>   - Use `parse_file_stream()` on `Dsv`/`DsvHelper` for stream-based parsing of files. This standardizes the API naming and clarifies that streaming helpers accept file paths rather than arbitrary iterables.
+> - TextFileHelper, SafeTextFileReader, SafeTextFileWriter, and PathValidator, as well as all their associated tests have been removed in this release.
+>   - Their functionality has been migrated in favor of the `splurge-safe-io` package, which provides robust and secure file I/O operations.
+>   - This change reduces code duplication and improves maintainability by leveraging the functionality of `splurge-safe-io`.
+>   - Users should refer to the `splurge-safe-io` documentation for details on its usage and features.
+> - **See API-REFERENCE.md for migration guidance and complete reference documentation, with usage examples.**
+
+**⚠️ CHANGES in v2025.2.2**
+> - **Deprecated Warning**: The following modules and their associated classes and functions are deprecated and will be removed in a future release (2025.3.0). Users are encouraged to transition to the `splurge-safe-io` package for these functionalities:
+>   - `splurge_dsv.safe_text_file_reader`
+>   - `splurge_dsv.safe_text_file_writer`
+>   - `splurge_dsv.path_validator`
+>   - `splurge_dsv.text_file_helper`
+> - **New Exception**: Added `SplurgeDsvFileExistsError` to handle file existence errors.
+> - **Fixed Exception Mapping**: Many errors were incorrectly mapped to SplurgeDsvEncodingError; this has been corrected to use appropriate exception types. 
+>   - Some exceptions were not mapped to any SplurgeDsv* exception; these have also been corrected.
+> - **3rd-Party Dependency Additions**: Added `splurge-safe-io (v2025.0.4)`.
+>   - `splurge-safe-io` is a new dependency that provides robust and secure file I/O operations, including safe text file reading and writing with deterministic newline handling and path validation.
+>   - This change reduces code duplication and improves maintainability by leveraging the functionality of `splurge-safe-io`.
+>   - Users should refer to the `splurge-safe-io` documentation for details on its usage and features.
+> - **Code Refactoring**: Refactored `SafeTextFileReader`, `SafeTextFileWriter`, and `PathValidator` to utilize `splurge-safe-io` implementations internally, ensuring consistent behavior and reducing maintenance overhead.
+> - **This release maintains backward compatibility** for existing users, but users are encouraged to transition to `splurge-safe-io` for future-proofing their codebases.
+>   - **_This release is a commit-only release and will not be published to PyPI._**
 
 **⚠️ BREAKING CHANGES in v2025.2.0**
 >
@@ -78,6 +116,41 @@ python -m splurge_dsv data.csv --delimiter ,
 python -m splurge_dsv large_file.csv --delimiter , --stream --chunk-size 1000
 ```
 
+### YAML configuration file
+
+You can place CLI-equivalent options in a YAML file and pass it to the CLI
+using `--config` (or `-c`). CLI arguments override values found in the
+YAML file. Example `config.yaml`:
+
+```yaml
+delimiter: ","
+strip: true
+bookend: '"'
+encoding: utf-8
+skip_header_rows: 1
+skip_footer_rows: 0
+skip_empty_lines: false
+detect_columns: true
+chunk_size: 500
+max_detect_chunks: 5
+raise_on_missing_columns: false
+raise_on_extra_columns: false
+```
+
+Usage with CLI:
+
+```bash
+python -m splurge_dsv data.csv --config config.yaml --delimiter "|"
+# The CLI delimiter '|' overrides the YAML delimiter
+```
+
+Example using the shipped example config in the repository:
+
+```bash
+# Use the example file provided at examples/config.yaml
+python -m splurge_dsv data.csv --config examples/config.yaml
+```
+
 ### API Usage
 
 ```python

splurge_dsv-2025.3.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+splurge_dsv/__init__.py,sha256=Kbxp7HgplCz8nSISs3JlS9yv2tcm4ksNKOlfZdFF4Xg,3838
+splurge_dsv/__main__.py,sha256=6dpfX_96hEpOqxv5X4bK73xX86YTgK0Adad1uTWSABM,426
+splurge_dsv/cli.py,sha256=Ohpr7Pa62hAL3_ga9Pffw-0oWyBva4Wg49uk6wxf3hQ,11859
+splurge_dsv/dsv.py,sha256=gU6PmY09dJG-UiTui1dnBl6lzMzXRHyTflcUaLCNODw,13849
+splurge_dsv/dsv_helper.py,sha256=qcj93SfKldNpS27liSLxaBW3wARnUErgY-Gdz8__qRo,29393
+splurge_dsv/exceptions.py,sha256=X7dq0eNSp_QPyXP12YJHuoLembR8OY48AQC0BPmAPPw,6026
+splurge_dsv/string_tokenizer.py,sha256=_yShUGbW8cK8X7b9f2INj5C2B1Zzz4j3evI_rx-X58U,4913
+splurge_dsv-2025.3.1.dist-info/licenses/LICENSE,sha256=fPgtg-tIFHinQvJH0arRfv50AuxikD5eHw6rrPy2A5w,1091
+splurge_dsv-2025.3.1.dist-info/METADATA,sha256=cQJW9gez32t7daLRZxRK903xPUIj6OMO-gX9vapP5yA,13022
+splurge_dsv-2025.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+splurge_dsv-2025.3.1.dist-info/entry_points.txt,sha256=QmGyc3qHYtY61uanRxNOXw-waSJ01qypSCI8Kb3zgsU,56
+splurge_dsv-2025.3.1.dist-info/top_level.txt,sha256=D6Si3FTfpRYqH7kzM7tSQAyaKbbraO6UPLpcqcY4XXM,12
+splurge_dsv-2025.3.1.dist-info/RECORD,,

splurge_dsv/path_validator.py

@@ -1,298 +0,0 @@
-"""
-File path validation utilities for secure file operations.
-
-This module provides utilities for validating file paths to prevent
-path traversal attacks and ensure secure file operations.
-
-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
-import os
-import re
-from pathlib import Path
-
-# Local imports
-from splurge_dsv.exceptions import (
-    SplurgeDsvFileNotFoundError,
-    SplurgeDsvFilePermissionError,
-    SplurgeDsvPathValidationError,
-)
-
-# Module-level constants for path validation
-_MAX_PATH_LENGTH = 4096  # Maximum path length for most filesystems
-_DEFAULT_FILENAME = "unnamed_file"  # Default filename when sanitization results in empty string
-
-
-class PathValidator:
-    """
-    Utility class for validating file paths securely.
-
-    This class provides methods to validate file paths and prevent
-    path traversal attacks and other security vulnerabilities.
-    """
-
-    # Private constants for path validation
-    _PATH_TRAVERSAL_PATTERNS = [
-        r"\.\.",  # Directory traversal
-        r"//+",  # Multiple forward slashes (including //)
-        r"\\{2,}",  # Two or more consecutive backslashes (not normal Windows paths)
-        r"~",  # Home directory expansion
-    ]
-
-    _DANGEROUS_CHARS = [
-        "<",
-        ">",
-        '"',
-        "|",
-        "?",
-        "*",  # Windows reserved characters (excluding ':' for drive letters)
-        "\x00",
-        "\x01",
-        "\x02",
-        "\x03",
-        "\x04",
-        "\x05",
-        "\x06",
-        "\x07",  # Control characters
-        "\x08",
-        "\x09",
-        "\x0a",
-        "\x0b",
-        "\x0c",
-        "\x0d",
-        "\x0e",
-        "\x0f",
-        "\x10",
-        "\x11",
-        "\x12",
-        "\x13",
-        "\x14",
-        "\x15",
-        "\x16",
-        "\x17",
-        "\x18",
-        "\x19",
-        "\x1a",
-        "\x1b",
-        "\x1c",
-        "\x1d",
-        "\x1e",
-        "\x1f",
-    ]
-
-    MAX_PATH_LENGTH = _MAX_PATH_LENGTH
-
-    @classmethod
-    def validate_path(
-        cls,
-        file_path: str | Path,
-        *,
-        must_exist: bool = False,
-        must_be_file: bool = False,
-        must_be_readable: bool = False,
-        allow_relative: bool = True,
-        base_directory: str | Path | None = None,
-    ) -> Path:
-        """Validate a filesystem path for security and correctness.
-
-        This is the central path validation routine used across the package.
-
-        Args:
-            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:
-            pathlib.Path: Resolved and normalized path.
-
-        Raises:
-            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
-
-        # Get the original string for validation (before Path normalization)
-        path_str = str(file_path) if isinstance(file_path, str) else str(path)
-
-        # Check for dangerous characters
-        cls._check_dangerous_characters(path_str)
-
-        # Check for path traversal patterns
-        cls._check_path_traversal(path_str)
-
-        # Check path length
-        cls._check_path_length(path_str)
-
-        # Handle relative paths
-        if not path.is_absolute() and not allow_relative:
-            raise SplurgeDsvPathValidationError(
-                f"Relative paths are not allowed: {path}", details="Set allow_relative=True to allow relative paths"
-            )
-
-        # Resolve path (handles symlinks and normalizes)
-        try:
-            if base_directory:
-                base_path = Path(base_directory).resolve()
-                if not path.is_absolute():
-                    resolved_path = (base_path / path).resolve()
-                else:
-                    resolved_path = path.resolve()
-
-                # Ensure resolved path is within base directory
-                try:
-                    resolved_path.relative_to(base_path)
-                except ValueError:
-                    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 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 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 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 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 SplurgeDsvFilePermissionError(
-                    f"File is not readable: {resolved_path}", details="Check file permissions"
-                )
-
-        return resolved_path
-
-    @classmethod
-    def _is_valid_windows_drive_pattern(cls, path_str: str) -> bool:
-        """Return True if ``path_str`` looks like a valid Windows drive pattern.
-
-        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:
-        """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 SplurgeDsvPathValidationError(
-                    f"Path contains dangerous character: {repr(char)}",
-                    details=f"Character at position {path_str.find(char)}",
-                )
-
-        # 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 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:
-        """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 SplurgeDsvPathValidationError(
-                    f"Path contains traversal pattern: {pattern}", details="Path traversal attacks are not allowed"
-                )
-
-    @classmethod
-    def _check_path_length(cls, path_str: str) -> None:
-        """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 SplurgeDsvPathValidationError(
-                f"Path is too long: {len(path_str)} characters",
-                details=f"Maximum allowed length is {cls.MAX_PATH_LENGTH} characters",
-            )
-
-    @classmethod
-    def sanitize_filename(cls, filename: str) -> str:
-        """
-        Sanitize a filename by removing dangerous characters.
-
-        Args:
-            filename: Original filename
-
-        Returns:
-            Sanitized filename
-        """
-        # Remove or replace dangerous characters
-        sanitized = filename
-
-        # Replace Windows reserved characters
-        for char in ["<", ">", ":", '"', "|", "?", "*"]:
-            sanitized = sanitized.replace(char, "_")
-
-        # Remove control characters
-        sanitized = "".join(char for char in sanitized if ord(char) >= 32)
-
-        # Remove leading/trailing spaces and dots
-        sanitized = sanitized.strip(" .")
-
-        # Ensure filename is not empty
-        if not sanitized:
-            sanitized = _DEFAULT_FILENAME
-
-        return sanitized
-
-    @classmethod
-    def is_safe_path(cls, file_path: str | Path) -> bool:
-        """
-        Check if a path is safe without raising exceptions.
-
-        Args:
-            file_path: Path to check
-
-        Returns:
-            True if path is safe, False otherwise
-        """
-        try:
-            cls.validate_path(file_path)
-            return True
-        except (SplurgeDsvPathValidationError, SplurgeDsvFileNotFoundError, SplurgeDsvFilePermissionError):
-            return False

splurge_dsv/safe_text_file_reader.py

@@ -1,177 +0,0 @@
-"""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()