splurge-dsv 2025.1.4__tar.gz → 2025.2.0__tar.gz

splurge_dsv-2025.2.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: splurge-dsv
+Version: 2025.2.0
+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"
+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"
+Requires-Dist: hypothesis>=6.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-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)
+[![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/)
+
+A robust Python library for parsing and processing delimited-separated value (DSV) files with advanced features for data validation, streaming, and error handling.
+
+## Features
+
+- **Multi-format DSV Support**: Parse CSV, TSV, pipe-delimited, and custom delimiter files
+- **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
+
+**⚠️ BREAKING CHANGES in v2025.2.0**
+>
+> - **Exception Names Changed**: All exceptions now use `SplurgeDsv*` prefix (e.g., `SplurgeParameterError` → `SplurgeDsvParameterError`)
+> - **Resource Manager Removed**: The `ResourceManager` module and all related classes have been completely removed
+>
+> See the [CHANGELOG](CHANGELOG.md) for migration guidance.
+
+## Installation
+
+```bash
+pip install splurge-dsv
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Parse a CSV file
+python -m splurge_dsv data.csv --delimiter ,
+
+# Stream a large file
+python -m splurge_dsv large_file.csv --delimiter , --stream --chunk-size 1000
+```
+
+### API Usage
+
+```python
+from splurge_dsv import DsvHelper
+
+# Parse a 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=",")
+```
+
+### Modern API
+
+```python
+from splurge_dsv import Dsv, DsvConfig
+
+# Create configuration and parser
+config = DsvConfig.csv(skip_header=1)
+dsv = Dsv(config)
+
+# Parse files
+rows = dsv.parse_file("data.csv")
+```
+
+## Documentation
+
+- **[Detailed Documentation](docs/README-details.md)**: Complete API reference, CLI options, and examples
+- **[Testing Best Practices](docs/testing_best_practices.md)**: Comprehensive testing guidelines and patterns
+- **[Hypothesis Usage Patterns](docs/hypothesis_usage_patterns.md)**: Property-based testing guide
+- **[Changelog](CHANGELOG.md)**: Release notes and migration guides
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+----------------------------
+
+This library enforces deterministic newline handling for text files. The reader
+normalizes CRLF (`\r\n`), CR (`\r`) and LF (`\n`) to LF internally and
+returns logical lines. The writer utilities normalize any input newlines to LF
+before writing. This avoids platform-dependent differences when reading files
+produced by diverse sources.
+
+Recommended usage:
+
+- When creating files inside the project, prefer the `open_text_writer` context
+    manager or `SafeTextFileWriter` which will normalize to LF.
+- When reading unknown files, the `open_text` / `SafeTextFileReader` will
+    provide deterministic normalization regardless of the source.
+- `SplurgeResourceAcquisitionError` - Resource acquisition failures
+- `SplurgeResourceReleaseError` - Resource cleanup failures
+
+## Development
+
+### Testing Suite
+
+splurge-dsv features a comprehensive testing suite designed for robustness and reliability:
+
+#### Test Categories
+- **Unit Tests**: Core functionality testing (300+ tests)
+- **Integration Tests**: End-to-end workflow validation (50+ tests)
+- **Property-Based Tests**: Hypothesis-driven testing for edge cases (50+ tests)
+- **Edge Case Tests**: Malformed input, encoding issues, filesystem anomalies
+- **Cross-Platform Tests**: Path handling, line endings, encoding consistency
+
+#### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage report
+pytest tests/ --cov=splurge_dsv --cov-report=html
+
+# Run specific test categories
+pytest tests/unit/ -v                    # Unit tests only
+pytest tests/integration/ -v            # Integration tests only
+pytest tests/property/ -v               # Property-based tests only
+pytest tests/platform/ -v               # Cross-platform tests only
+
+# Run with parallel execution
+pytest tests/ -n 4 --cov=splurge_dsv
+
+# Run performance benchmarks
+pytest tests/ --durations=10
+```
+
+#### Test Quality Standards
+- **94%+ Code Coverage**: All public APIs and critical paths covered
+- **Property-Based Testing**: Hypothesis framework validates complex scenarios
+- **Cross-Platform Compatibility**: Tests run on Windows, Linux, and macOS
+- **Performance Regression Detection**: Automated benchmarks prevent slowdowns
+- **Zero False Positives**: All property tests pass without spurious failures
+
+#### Testing Best Practices
+- Tests use `pytest-mock` for modern mocking patterns
+- Property tests use Hypothesis strategies for comprehensive input generation
+- Edge case tests validate error handling and boundary conditions
+- Cross-platform tests ensure consistent behavior across operating systems
+
+### 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 see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:
+
+- Development setup and workflow
+- Coding standards and best practices
+- Testing requirements and guidelines
+- Pull request process and review criteria
+
+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.2.0/README.md

@@ -0,0 +1,184 @@
+# 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-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)
+[![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/)
+
+A robust Python library for parsing and processing delimited-separated value (DSV) files with advanced features for data validation, streaming, and error handling.
+
+## Features
+
+- **Multi-format DSV Support**: Parse CSV, TSV, pipe-delimited, and custom delimiter files
+- **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
+
+**⚠️ BREAKING CHANGES in v2025.2.0**
+>
+> - **Exception Names Changed**: All exceptions now use `SplurgeDsv*` prefix (e.g., `SplurgeParameterError` → `SplurgeDsvParameterError`)
+> - **Resource Manager Removed**: The `ResourceManager` module and all related classes have been completely removed
+>
+> See the [CHANGELOG](CHANGELOG.md) for migration guidance.
+
+## Installation
+
+```bash
+pip install splurge-dsv
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Parse a CSV file
+python -m splurge_dsv data.csv --delimiter ,
+
+# Stream a large file
+python -m splurge_dsv large_file.csv --delimiter , --stream --chunk-size 1000
+```
+
+### API Usage
+
+```python
+from splurge_dsv import DsvHelper
+
+# Parse a 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=",")
+```
+
+### Modern API
+
+```python
+from splurge_dsv import Dsv, DsvConfig
+
+# Create configuration and parser
+config = DsvConfig.csv(skip_header=1)
+dsv = Dsv(config)
+
+# Parse files
+rows = dsv.parse_file("data.csv")
+```
+
+## Documentation
+
+- **[Detailed Documentation](docs/README-details.md)**: Complete API reference, CLI options, and examples
+- **[Testing Best Practices](docs/testing_best_practices.md)**: Comprehensive testing guidelines and patterns
+- **[Hypothesis Usage Patterns](docs/hypothesis_usage_patterns.md)**: Property-based testing guide
+- **[Changelog](CHANGELOG.md)**: Release notes and migration guides
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+----------------------------
+
+This library enforces deterministic newline handling for text files. The reader
+normalizes CRLF (`\r\n`), CR (`\r`) and LF (`\n`) to LF internally and
+returns logical lines. The writer utilities normalize any input newlines to LF
+before writing. This avoids platform-dependent differences when reading files
+produced by diverse sources.
+
+Recommended usage:
+
+- When creating files inside the project, prefer the `open_text_writer` context
+    manager or `SafeTextFileWriter` which will normalize to LF.
+- When reading unknown files, the `open_text` / `SafeTextFileReader` will
+    provide deterministic normalization regardless of the source.
+- `SplurgeResourceAcquisitionError` - Resource acquisition failures
+- `SplurgeResourceReleaseError` - Resource cleanup failures
+
+## Development
+
+### Testing Suite
+
+splurge-dsv features a comprehensive testing suite designed for robustness and reliability:
+
+#### Test Categories
+- **Unit Tests**: Core functionality testing (300+ tests)
+- **Integration Tests**: End-to-end workflow validation (50+ tests)
+- **Property-Based Tests**: Hypothesis-driven testing for edge cases (50+ tests)
+- **Edge Case Tests**: Malformed input, encoding issues, filesystem anomalies
+- **Cross-Platform Tests**: Path handling, line endings, encoding consistency
+
+#### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage report
+pytest tests/ --cov=splurge_dsv --cov-report=html
+
+# Run specific test categories
+pytest tests/unit/ -v                    # Unit tests only
+pytest tests/integration/ -v            # Integration tests only
+pytest tests/property/ -v               # Property-based tests only
+pytest tests/platform/ -v               # Cross-platform tests only
+
+# Run with parallel execution
+pytest tests/ -n 4 --cov=splurge_dsv
+
+# Run performance benchmarks
+pytest tests/ --durations=10
+```
+
+#### Test Quality Standards
+- **94%+ Code Coverage**: All public APIs and critical paths covered
+- **Property-Based Testing**: Hypothesis framework validates complex scenarios
+- **Cross-Platform Compatibility**: Tests run on Windows, Linux, and macOS
+- **Performance Regression Detection**: Automated benchmarks prevent slowdowns
+- **Zero False Positives**: All property tests pass without spurious failures
+
+#### Testing Best Practices
+- Tests use `pytest-mock` for modern mocking patterns
+- Property tests use Hypothesis strategies for comprehensive input generation
+- Edge case tests validate error handling and boundary conditions
+- Cross-platform tests ensure consistent behavior across operating systems
+
+### 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 see our [Contributing Guide](CONTRIBUTING.md) for detailed information on:
+
+- Development setup and workflow
+- Coding standards and best practices
+- Testing requirements and guidelines
+- Pull request process and review criteria
+
+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.4 → splurge_dsv-2025.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splurge-dsv"
-version = "2025.1.4"
+version = "2025.2.0"
 description = "A utility library for working with DSV (Delimited String Values) files"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -32,6 +32,10 @@ dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "pytest-xdist>=3.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.0.241",
+    "pytest-mock>=3.0.0",
+    "hypothesis>=6.0.0",
 ]
 
 [project.urls]
@@ -40,13 +44,16 @@ Repository = "https://github.com/jim-schilling/splurge-dsv"
 Documentation = "https://github.com/jim-schilling/splurge-dsv#readme"
 "Bug Tracker" = "https://github.com/jim-schilling/splurge-dsv/issues"
 
+[project.scripts]
+splurge-dsv = "splurge_dsv.cli:run_cli"
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["splurge_dsv*"]
 
 [tool.pytest.ini_options]
 minversion = "7.0"
-addopts = "-x -v --cov=splurge_dsv --cov-report=term-missing --cov-report=html --cov-fail-under=85"
+addopts = "-x -v -n 4"
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
@@ -56,6 +63,13 @@ filterwarnings = [
     "ignore::PendingDeprecationWarning",
 ]
 
+[tool.hypothesis]
+# Hypothesis configuration for property-based testing
+max_examples = 100
+deadline = 5000  # 5 seconds per test
+suppress_health_check = ["too_slow"]
+verbosity = "normal"
+
 [tool.coverage.run]
 source = ["splurge_dsv"]
 omit = [
@@ -108,3 +122,9 @@ quote-style = "double"
 indent-style = "space"
 skip-magic-trailing-comma = false
 line-ending = "auto"
+
+[tool.mypy]
+# Only run mypy against the splurge_dsv package
+files = ["splurge_dsv"]
+# show_error_codes helps with diagnostics
+show_error_codes = true

splurge_dsv-2025.2.0/splurge_dsv/__init__.py

@@ -0,0 +1,96 @@
+"""Top-level package for Splurge DSV.
+
+This package provides utilities for parsing, processing and manipulating
+delimited string value (DSV) files. It exposes the high-level API objects
+such as :class:`~splurge_dsv.dsv.Dsv` and :class:`~splurge_dsv.dsv.DsvConfig`,
+convenience helpers, and the package's exception types.
+
+License: MIT
+Copyright (c) 2025 Jim Schilling
+"""
+
+# Ensure current working directory exists. Some test environments or earlier
+# test cases may remove the process working directory which causes calls to
+# os.getcwd() to raise FileNotFoundError later during test execution. Guard
+# against that here by switching to this package directory when cwd is missing.
+import os
+from pathlib import Path as _Path
+
+try:
+    try:
+        # os.getcwd() can raise FileNotFoundError in CI/runner environments
+        # if the original working directory was removed. Check existence via
+        # Path.cwd(); if it doesn't exist, switch to the package directory.
+        if not _Path.cwd().exists():
+            os.chdir(_Path(__file__).resolve().parent)
+    except FileNotFoundError:
+        # Fall back to package directory when cwd is gone
+        os.chdir(_Path(__file__).resolve().parent)
+except Exception:
+    # Be conservative: if this fails, don't break import - tests will report
+    # the original failure. Swallowing ensures import-time is resilient.
+    pass
+
+# Local imports
+from splurge_dsv.dsv import Dsv, DsvConfig
+from splurge_dsv.dsv_helper import DsvHelper
+from splurge_dsv.exceptions import (
+    SplurgeDsvConfigurationError,
+    SplurgeDsvDataProcessingError,
+    # canonical SplurgeDsv* exception names
+    SplurgeDsvError,
+    SplurgeDsvFileEncodingError,
+    SplurgeDsvFileNotFoundError,
+    SplurgeDsvFileOperationError,
+    SplurgeDsvFilePermissionError,
+    SplurgeDsvFormatError,
+    SplurgeDsvParameterError,
+    SplurgeDsvParsingError,
+    SplurgeDsvPathValidationError,
+    SplurgeDsvPerformanceWarning,
+    SplurgeDsvRangeError,
+    SplurgeDsvResourceAcquisitionError,
+    SplurgeDsvResourceError,
+    SplurgeDsvResourceReleaseError,
+    SplurgeDsvStreamingError,
+    SplurgeDsvTypeConversionError,
+    SplurgeDsvValidationError,
+)
+from splurge_dsv.path_validator import PathValidator
+from splurge_dsv.string_tokenizer import StringTokenizer
+from splurge_dsv.text_file_helper import TextFileHelper
+
+__version__ = "2025.2.0"
+__author__ = "Jim Schilling"
+__license__ = "MIT"
+
+__all__ = [
+    # Main classes
+    "Dsv",
+    "DsvConfig",
+    "DsvHelper",
+    # Exceptions
+    "SplurgeDsvError",
+    "SplurgeDsvValidationError",
+    "SplurgeDsvFileOperationError",
+    "SplurgeDsvFileNotFoundError",
+    "SplurgeDsvFilePermissionError",
+    "SplurgeDsvFileEncodingError",
+    "SplurgeDsvPathValidationError",
+    "SplurgeDsvDataProcessingError",
+    "SplurgeDsvParsingError",
+    "SplurgeDsvTypeConversionError",
+    "SplurgeDsvStreamingError",
+    "SplurgeDsvConfigurationError",
+    "SplurgeDsvResourceError",
+    "SplurgeDsvResourceAcquisitionError",
+    "SplurgeDsvResourceReleaseError",
+    "SplurgeDsvPerformanceWarning",
+    "SplurgeDsvParameterError",
+    "SplurgeDsvRangeError",
+    "SplurgeDsvFormatError",
+    # Utility classes
+    "StringTokenizer",
+    "TextFileHelper",
+    "PathValidator",
+]

splurge_dsv-2025.2.0/splurge_dsv/__main__.py

@@ -0,0 +1,19 @@
+"""Module entrypoint for running splurge-dsv as a script.
+
+When executed (``python -m splurge_dsv``), this module delegates to
+``splurge_dsv.cli.run_cli`` and returns the resulting exit code.
+
+License: MIT
+Copyright (c) 2025 Jim Schilling
+"""
+
+from __future__ import annotations
+
+# Standard library
+import sys
+
+# Local
+from splurge_dsv.cli import run_cli
+
+if __name__ == "__main__":
+    sys.exit(run_cli())