Metadata-Version: 2.4
Name: splurge-safe-io
Version: 2025.4.2
Summary: A safe, atomic, and cross-platform way to handle text file I/O in Python.
Author: Jim Schilling
License-Expression: MIT
Project-URL: Homepage, https://github.com/jim-schilling/splurge-safe-io
Project-URL: Repository, https://github.com/jim-schilling/splurge-safe-io
Project-URL: Documentation, https://github.com/jim-schilling/splurge-safe-io#readme
Project-URL: Bug Tracker, https://github.com/jim-schilling/splurge-safe-io/issues
Keywords: io,file,file-processing
Classifier: Development Status :: 4 - Beta
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.18.2; extra == "dev"
Requires-Dist: ruff>=0.13.3; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: hypothesis>=6.140.3; extra == "dev"
Dynamic: license-file

# splurge-safe-io

[![PyPI version](https://badge.fury.io/py/splurge-safe-io.svg)](https://pypi.org/project/splurge-safe-io/)
[![Python versions](https://img.shields.io/pypi/pyversions/splurge-safe-io.svg)](https://pypi.org/project/splurge-safe-io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

[![CI](https://github.com/jim-schilling/splurge-safe-io/actions/workflows/ci-quick-test.yml/badge.svg)](https://github.com/jim-schilling/splurge-safe-io/actions/workflows/ci-quick-test.yml)
[![Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](https://github.com/jim-schilling/splurge-safe-io)
[![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 small, secure, and deterministic text file I/O helper library.

Key features

- Deterministic newline normalization (LF) for text reads/writes.
- Secure path validation utilities to avoid traversal and dangerous characters.
- Streaming reader with incremental decoding and a safe fallback for tricky encodings.
- Clear, small exception hierarchy for stable error handling.

Quick start

```py
from splurge_safe_io.safe_text_file_reader import SafeTextFileReader
from splurge_safe_io.safe_text_file_writer import open_safe_text_writer

# Read lines
reader = SafeTextFileReader('data.csv')
rows = reader.readlines()

# Write via context manager
with open_safe_text_writer('out.txt') as buf:
    buf.write('\n'.join(['one','two','three']))
```


> **⚠️ BREAKING CHANGE for v2025.1.0:** `SafeTextFileReader.read()` now returns a `str` containing the entire normalized file content instead of a `list[str]` of lines. Use `SafeTextFileReader.readlines()` to get a list of lines.


See `docs/README-DETAILS.md` for a complete guide and usage examples.
