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

splurge_dsv/resource_manager.py

@@ -1,371 +0,0 @@
-"""
-Resource management utilities with context managers.
-
-This module provides context managers and resource management utilities
-for safe handling of file operations, streams, and other resources.
-
-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 contextlib import contextmanager
-from pathlib import Path
-from typing import IO, Any
-
-# Local imports
-from splurge_dsv.exceptions import (
-    SplurgeFileEncodingError,
-    SplurgeFileNotFoundError,
-    SplurgeFilePermissionError,
-    SplurgeResourceAcquisitionError,
-    SplurgeResourceReleaseError,
-)
-from splurge_dsv.path_validator import PathValidator
-
-# Module-level constants for resource management
-DEFAULT_BUFFERING = -1  # Default buffering for file operations
-DEFAULT_ENCODING = "utf-8"  # Default text encoding
-DEFAULT_MODE = "r"  # Default file mode for reading
-
-
-def _safe_open_file(
-    file_path: Path,
-    *,
-    mode: str,
-    encoding: str | None = None,
-    errors: str | None = None,
-    newline: str | None = None,
-    buffering: int = DEFAULT_BUFFERING,
-) -> IO[Any]:
-    """
-    Safely open a file with proper error handling.
-
-    This function provides centralized file opening with consistent error handling
-    that converts standard file operation exceptions to custom exceptions.
-
-    Args:
-        file_path: Path to the file
-        mode: File open mode
-        encoding: Text encoding (for text mode)
-        errors: Error handling for encoding
-        newline: Newline handling
-        buffering: Buffer size
-
-    Returns:
-        File handle
-
-    Raises:
-        SplurgeFileNotFoundError: If file is not found
-        SplurgeFilePermissionError: If permission is denied
-        SplurgeFileEncodingError: If encoding error occurs
-        SplurgeResourceAcquisitionError: If other file operation fails
-    """
-    try:
-        if "b" in mode:
-            # Binary mode
-            return open(file_path, mode=mode, buffering=buffering)
-        else:
-            # Text mode
-            return open(file_path, mode=mode, encoding=encoding, errors=errors, newline=newline, buffering=buffering)
-    except FileNotFoundError as e:
-        raise SplurgeFileNotFoundError(f"File not found: {file_path}", details=str(e)) from e
-    except PermissionError as e:
-        raise SplurgeFilePermissionError(f"Permission denied: {file_path}", details=str(e)) from e
-    except UnicodeDecodeError as e:
-        raise SplurgeFileEncodingError(f"Encoding error reading file: {file_path}", details=str(e)) from e
-    except OSError as e:
-        raise SplurgeResourceAcquisitionError(f"Failed to open file: {file_path}", details=str(e)) from e
-
-
-class ResourceManager:
-    """
-    Generic resource manager that implements the ResourceManagerProtocol.
-
-    This class provides a base implementation for resource management
-    with acquire/release semantics.
-    """
-
-    def __init__(self) -> None:
-        """Initialize the resource manager."""
-        self._resource: Any | None = None
-        self._is_acquired_flag: bool = False
-
-    def acquire(self) -> Any:
-        """
-        Acquire the managed resource.
-
-        Returns:
-            The acquired resource
-
-        Raises:
-            NotImplementedError: If _create_resource is not implemented by subclass
-            SplurgeResourceAcquisitionError: If resource cannot be acquired
-        """
-        if self._is_acquired_flag:
-            raise SplurgeResourceAcquisitionError(
-                "Resource is already acquired", details="Cannot acquire resource that is already in use"
-            )
-
-        try:
-            self._resource = self._create_resource()
-            self._is_acquired_flag = True
-            return self._resource
-        except NotImplementedError:
-            # Re-raise NotImplementedError without wrapping it
-            raise
-        except Exception as e:
-            raise SplurgeResourceAcquisitionError("Failed to acquire resource", details=str(e)) from e
-
-    def release(self) -> None:
-        """
-        Release the managed resource.
-
-        Raises:
-            SplurgeResourceReleaseError: If resource cannot be released
-        """
-        if not self._is_acquired_flag:
-            return  # Nothing to release
-
-        try:
-            self._cleanup_resource()
-            self._resource = None
-            self._is_acquired_flag = False
-        except Exception as e:
-            raise SplurgeResourceReleaseError("Failed to release resource", details=str(e)) from e
-
-    def is_acquired(self) -> bool:
-        """
-        Check if the resource is currently acquired.
-
-        Returns:
-            True if resource is acquired, False otherwise
-        """
-        return self._is_acquired_flag
-
-    def _create_resource(self) -> Any:
-        """
-        Create the resource to be managed.
-
-        This method should be overridden by subclasses to provide
-        specific resource creation logic.
-
-        Returns:
-            The created resource
-
-        Raises:
-            NotImplementedError: If not overridden by subclass
-        """
-        raise NotImplementedError("Subclasses must implement _create_resource")
-
-    def _cleanup_resource(self) -> None:
-        """
-        Clean up the managed resource.
-
-        This method should be overridden by subclasses to provide
-        specific resource cleanup logic.
-        """
-        if self._resource is not None and hasattr(self._resource, "close"):
-            self._resource.close()
-
-
-class FileResourceManager:
-    """
-    Context manager for safe file operations with automatic cleanup.
-
-    This class provides context managers for reading and writing files
-    with proper error handling and resource cleanup.
-    """
-
-    def __init__(
-        self,
-        file_path: str | Path,
-        *,
-        mode: str = DEFAULT_MODE,
-        encoding: str | None = DEFAULT_ENCODING,
-        errors: str | None = None,
-        newline: str | None = None,
-        buffering: int = DEFAULT_BUFFERING,
-    ) -> None:
-        """
-        Initialize FileResourceManager.
-
-        Args:
-            file_path: Path to the file
-            mode: File open mode ('r', 'w', 'a', etc.)
-            encoding: Text encoding (for text mode)
-            errors: Error handling for encoding
-            newline: Newline handling
-            buffering: Buffer size
-
-        Raises:
-            SplurgePathValidationError: If file path is invalid
-            SplurgeResourceAcquisitionError: If file cannot be opened
-        """
-        self._file_path = PathValidator.validate_path(
-            file_path, must_exist=(mode in ["r", "rb"]), must_be_file=True, must_be_readable=(mode in ["r", "rb"])
-        )
-        self.mode = mode
-        self.encoding = encoding
-        self.errors = errors
-        self.newline = newline
-        self.buffering = buffering
-        self._file_handle: IO[Any] | None = None
-
-    def __enter__(self) -> IO[Any]:
-        """
-        Open the file and return the file handle.
-
-        Returns:
-            File handle
-
-        Raises:
-            SplurgeFileNotFoundError: If file is not found
-            SplurgeFilePermissionError: If permission is denied
-            SplurgeFileEncodingError: If encoding error occurs
-            SplurgeResourceAcquisitionError: If other file operation fails
-        """
-        self._file_handle = _safe_open_file(
-            self.file_path,
-            mode=self.mode,
-            encoding=self.encoding,
-            errors=self.errors,
-            newline=self.newline,
-            buffering=self.buffering,
-        )
-        return self._file_handle
-
-    def __exit__(self, exc_type: type | None, exc_val: Exception | None, exc_tb: Any | None) -> None:
-        """
-        Close the file handle and cleanup resources.
-
-        Args:
-            exc_type: Exception type if an exception occurred
-            exc_val: Exception value if an exception occurred
-            exc_tb: Exception traceback if an exception occurred
-        """
-        if self._file_handle is not None:
-            try:
-                self._file_handle.close()
-            except OSError as e:
-                raise SplurgeResourceReleaseError(f"Failed to close file: {self.file_path}", details=str(e)) from e
-            finally:
-                self._file_handle = None
-
-    @property
-    def file_path(self) -> Path | None:
-        """Get the path of the temporary file."""
-        return self._file_path
-
-
-class StreamResourceManager:
-    """
-    Context manager for stream operations.
-
-    This class provides context managers for managing data streams
-    with proper cleanup and error handling.
-    """
-
-    def __init__(self, stream: Iterator[Any], *, auto_close: bool = True) -> None:
-        """
-        Initialize StreamResourceManager.
-
-        Args:
-            stream: Iterator to manage
-            auto_close: Whether to automatically close the stream
-        """
-        self.stream = stream
-        self.auto_close = auto_close
-        self._is_closed = False
-
-    def __enter__(self) -> Iterator[Any]:
-        """
-        Return the stream.
-
-        Returns:
-            Stream iterator
-        """
-        return self.stream
-
-    def __exit__(self, exc_type: type | None, exc_val: Exception | None, exc_tb: Any | None) -> None:
-        """
-        Clean up the stream.
-
-        Args:
-            exc_type: Exception type if an exception occurred
-            exc_val: Exception value if an exception occurred
-            exc_tb: Exception traceback if an exception occurred
-        """
-        if self.auto_close and hasattr(self.stream, "close"):
-            try:
-                self.stream.close()
-            except Exception as e:
-                raise SplurgeResourceReleaseError("Failed to close stream", details=str(e)) from e
-
-        # Mark as closed after context manager exits, regardless of close method
-        self._is_closed = True
-
-    @property
-    def is_closed(self) -> bool:
-        """Check if the stream is closed."""
-        return self._is_closed
-
-
-@contextmanager
-def safe_file_operation(
-    file_path: str | Path,
-    *,
-    mode: str = DEFAULT_MODE,
-    encoding: str | None = DEFAULT_ENCODING,
-    errors: str | None = None,
-    newline: str | None = None,
-    buffering: int = DEFAULT_BUFFERING,
-) -> Iterator[IO[Any]]:
-    """
-    Context manager for safe file operations.
-
-    Args:
-        file_path: Path to the file
-        mode: File open mode
-        encoding: Text encoding (for text mode)
-        errors: Error handling for encoding
-        newline: Newline handling
-        buffering: Buffer size
-
-    Yields:
-        File handle
-
-    Raises:
-        SplurgePathValidationError: If file path is invalid
-        SplurgeResourceAcquisitionError: If file cannot be opened
-        SplurgeResourceReleaseError: If file cannot be closed
-    """
-    manager = FileResourceManager(
-        file_path, mode=mode, encoding=encoding, errors=errors, newline=newline, buffering=buffering
-    )
-    with manager as file_handle:
-        yield file_handle
-
-
-@contextmanager
-def safe_stream_operation(stream: Iterator[Any], *, auto_close: bool = True) -> Iterator[Iterator[Any]]:
-    """
-    Context manager for safe stream operations.
-
-    Args:
-        stream: Iterator to manage
-        auto_close: Whether to automatically close the stream
-
-    Yields:
-        Stream iterator
-
-    Raises:
-        SplurgeResourceReleaseError: If stream cannot be closed
-    """
-    manager = StreamResourceManager(stream, auto_close=auto_close)
-    with manager as stream_handle:
-        yield stream_handle

splurge_dsv-2025.1.5.dist-info/METADATA

@@ -1,268 +0,0 @@
-Metadata-Version: 2.4
-Name: splurge-dsv
-Version: 2025.1.5
-Summary: A utility library for working with DSV (Delimited String Values) files
-Author: Jim Schilling
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/jim-schilling/splurge-dsv
-Project-URL: Repository, https://github.com/jim-schilling/splurge-dsv
-Project-URL: Documentation, https://github.com/jim-schilling/splurge-dsv#readme
-Project-URL: Bug Tracker, https://github.com/jim-schilling/splurge-dsv/issues
-Keywords: dsv,csv,tsv,delimited,parsing,file-processing
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Text Processing :: Filters
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-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"
-Dynamic: license-file
-
-# splurge-dsv
-
-[![PyPI version](https://badge.fury.io/py/splurge-dsv.svg)](https://pypi.org/project/splurge-dsv/)
-[![Python versions](https://img.shields.io/pypi/pyversions/splurge-dsv.svg)](https://pypi.org/project/splurge-dsv/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Coverage](https://img.shields.io/badge/coverage-96%25-brightgreen.svg)](https://github.com/jim-schilling/splurge-dsv)
-
-A robust Python library for parsing and processing delimited-separated value (DSV) files with advanced features for data validation, streaming, and error handling.
-
-## Features
-
-### 🔧 Core Functionality
-- **Multi-format DSV Support**: Parse CSV, TSV, pipe-delimited, semicolon-delimited, and custom delimiter files
-- **Flexible Parsing Options**: Configurable whitespace handling, bookend removal, and encoding support
-- **Memory-Efficient Streaming**: Process large files without loading entire content into memory
-- **Header/Footer Skipping**: Skip specified numbers of rows from start or end of files
-- **Unicode Support**: Full Unicode character and delimiter support
-
-### 🛡️ Security & Validation
-- **Path Validation**: Comprehensive file path security validation with traversal attack prevention
-- **File Permission Checks**: Automatic file accessibility and permission validation
-- **Encoding Validation**: Robust encoding error detection and handling
-- **Resource Management**: Automatic file handle cleanup and resource management
-
-### 📊 Advanced Processing
-- **Chunked Processing**: Configurable chunk sizes for streaming large datasets
-- **Mixed Content Handling**: Support for quoted and unquoted values in the same file
-- **Line Ending Flexibility**: Automatic handling of different line ending formats
-- **Error Recovery**: Graceful error handling with detailed error messages
-
-### 🧪 Testing & Quality
-- **Comprehensive Test Suite**: 250+ tests with 85%+ coverage gate
-- **Cross-Platform Support**: Tested on Windows, and should pass on Linux and macOS
-- **Type Safety**: Full type annotations and validation
-- **Documentation**: Complete API documentation with examples
-
-## Installation
-
-```bash
-pip install splurge-dsv
-```
-
-## Quick Start
-
-### Basic CSV Parsing
-
-```python
-from splurge_dsv import DsvHelper
-
-# Parse a simple CSV string
-data = DsvHelper.parse("a,b,c", delimiter=",")
-print(data)  # ['a', 'b', 'c']
-
-# Parse a CSV file
-rows = DsvHelper.parse_file("data.csv", delimiter=",")
-for row in rows:
-    print(row)  # ['col1', 'col2', 'col3']
-```
-
-### Streaming Large Files
-
-```python
-from splurge_dsv import DsvHelper
-
-# Stream a large CSV file in chunks
-for chunk in DsvHelper.parse_stream("large_file.csv", delimiter=",", chunk_size=1000):
-    for row in chunk:
-        process_row(row)
-```
-
-### Advanced Parsing Options
-
-```python
-from splurge_dsv import DsvHelper
-
-# Parse with custom options
-data = DsvHelper.parse(
-    '"a","b","c"',
-    delimiter=",",
-    bookend='"',
-    strip=True,
-    bookend_strip=True
-)
-print(data)  # ['a', 'b', 'c']
-
-# Skip header and footer rows
-rows = DsvHelper.parse_file(
-    "data.csv",
-    delimiter=",",
-    skip_header_rows=1,
-    skip_footer_rows=2
-)
-```
-
-### Text File Operations
-
-```python
-from splurge_dsv import TextFileHelper
-
-# Count lines in a file
-line_count = TextFileHelper.line_count("data.txt")
-
-# Preview first N lines
-preview = TextFileHelper.preview("data.txt", max_lines=10)
-
-# Read entire file with options
-lines = TextFileHelper.read(
-    "data.txt",
-    strip=True,
-    skip_header_rows=1,
-    skip_footer_rows=1
-)
-
-# Stream file content
-for chunk in TextFileHelper.read_as_stream("large_file.txt", chunk_size=500):
-    process_chunk(chunk)
-```
-
-### Path Validation
-
-```python
-from splurge_dsv import PathValidator
-
-# Validate a file path
-valid_path = PathValidator.validate_path(
-    "data.csv",
-    must_exist=True,
-    must_be_file=True,
-    must_be_readable=True
-)
-
-# Check if path is safe
-is_safe = PathValidator.is_safe_path("user_input_path.txt")
-```
-
-## API Reference
-
-### DsvHelper
-
-Main class for DSV parsing operations.
-
-#### Methods
-
-- `parse(content, delimiter, strip=True, bookend=None, bookend_strip=True)` - Parse a single string
-- `parses(content_list, delimiter, strip=True, bookend=None, bookend_strip=True)` - Parse multiple strings
-- `parse_file(file_path, delimiter, strip=True, bookend=None, bookend_strip=True, skip_header_rows=0, skip_footer_rows=0, encoding='utf-8')` - Parse a file
-- `parse_stream(file_path, delimiter, strip=True, bookend=None, bookend_strip=True, skip_header_rows=0, skip_footer_rows=0, encoding='utf-8', chunk_size=500)` - Stream parse a file
-
-### TextFileHelper
-
-Utility class for text file operations.
-
-#### Methods
-
-- `line_count(file_path, encoding='utf-8')` - Count lines in a file
-- `preview(file_path, max_lines=100, strip=True, encoding='utf-8', skip_header_rows=0)` - Preview file content
-- `read(file_path, strip=True, encoding='utf-8', skip_header_rows=0, skip_footer_rows=0)` - Read entire file
-- `read_as_stream(file_path, strip=True, encoding='utf-8', skip_header_rows=0, skip_footer_rows=0, chunk_size=500)` - Stream read file
-
-### PathValidator
-
-Security-focused path validation utilities.
-
-#### Methods
-
-- `validate_path(file_path, must_exist=False, must_be_file=False, must_be_readable=False, allow_relative=False, base_directory=None)` - Validate file path
-- `is_safe_path(file_path)` - Check if path is safe
-- `sanitize_filename(filename, default_name='file')` - Sanitize filename
-
-### ResourceManager
-
-Context managers for safe resource handling.
-
-#### Classes
-
-- `FileResourceManager` - Context manager for file operations
-- `StreamResourceManager` - Context manager for stream operations
-
-#### Functions
-
-- `safe_file_operation(file_path, mode='r', encoding='utf-8', ...)` - Safe file operation context manager
-- `safe_stream_operation(stream, auto_close=True)` - Safe stream operation context manager
-
-## Error Handling
-
-The library provides comprehensive error handling with custom exception classes:
-
-- `SplurgeParameterError` - Invalid parameter values
-- `SplurgeFileNotFoundError` - File not found
-- `SplurgeFilePermissionError` - File permission issues
-- `SplurgeFileEncodingError` - File encoding problems
-- `SplurgePathValidationError` - Path validation failures
-- `SplurgeResourceAcquisitionError` - Resource acquisition failures
-- `SplurgeResourceReleaseError` - Resource cleanup failures
-
-## Development
-
-### Running Tests
-
-```bash
-# Run all tests
-pytest tests/ -v
-
-# Run with coverage
-pytest tests/ --cov=splurge_dsv --cov-report=html
-
-# Run specific test file
-pytest tests/test_dsv_helper.py -v
-```
-
-### Code Quality
-
-The project follows strict coding standards:
-- PEP 8 compliance
-- Type annotations for all functions
-- Google-style docstrings
-- 85%+ coverage gate enforced via CI
-- Comprehensive error handling
-
-## Changelog
-
-See the [CHANGELOG](CHANGELOG.md) for full release notes.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## More Documentation
-
-- Detailed docs: [docs/README-details.md](docs/README-details.md)
-- E2E testing coverage: [docs/e2e_testing_coverage.md](docs/e2e_testing_coverage.md)
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
-
-## Support
-
-For support, please open an issue on the GitHub repository or contact the maintainers.

splurge_dsv-2025.1.5.dist-info/RECORD

@@ -1,14 +0,0 @@
-splurge_dsv/__init__.py,sha256=cqq1MreFbu8ib04OyzkydhLc6ZpJSnc3jyMqoEouABo,2415
-splurge_dsv/__main__.py,sha256=CX8zVMaK6vaaCaC396FyXA1E_-jqKz4zh3CVW8mGKac,359
-splurge_dsv/cli.py,sha256=QLFdb22MSpQF3iXwxdEhETYWTup9y2pGfT6Vt3TzKuA,7612
-splurge_dsv/dsv_helper.py,sha256=VRq2ejx6y-JBtFKJdAaK-GD4V0eoxZZfmoX0I3CSbDI,9428
-splurge_dsv/exceptions.py,sha256=cu9Jd2pGhy7GBbbngH6zs0lfZzLp_OvGwbnsG5khp80,3035
-splurge_dsv/path_validator.py,sha256=RuRFjtHWE1Z5-DlSBBZMoHJegQEFYEQ0HJgN7ndre2k,9969
-splurge_dsv/resource_manager.py,sha256=g4igv1hhJdPtw4A1P-WdaNKcYMfEGCtZ4xaU4ynVbKw,12045
-splurge_dsv/string_tokenizer.py,sha256=wBKWdi68rreTqf3RF-8Oxh1nz6QdnbOyWflw2x8pGWY,4022
-splurge_dsv/text_file_helper.py,sha256=vdhEv9uK0hsNXvTO5SoWwFsI9fPkhdIUXuaJs80DVDA,13573
-splurge_dsv-2025.1.5.dist-info/licenses/LICENSE,sha256=fPgtg-tIFHinQvJH0arRfv50AuxikD5eHw6rrPy2A5w,1091
-splurge_dsv-2025.1.5.dist-info/METADATA,sha256=-dWt2wSfflEcg7KWeftltEFaNEve5Mdwxx3MZ9SRFAQ,9023
-splurge_dsv-2025.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-splurge_dsv-2025.1.5.dist-info/top_level.txt,sha256=D6Si3FTfpRYqH7kzM7tSQAyaKbbraO6UPLpcqcY4XXM,12
-splurge_dsv-2025.1.5.dist-info/RECORD,,