fs-transaction 🛡️

Stop writing corrupted files.

fs-transaction provides Python context managers for atomic, crash-safe file operations. It ensures your file writes are "all-or-nothing," preventing data corruption during crashes, power failures, or concurrent access.

💥 The Problem

In standard Python, writing to a file is risky:

# ⚠️ DANGEROUS CODE
with open("database.json", "w") as f:
    f.write(start_processing())
    # <--- CRASH HERE (Power loss, Exception, OOM)
    f.write(finish_processing())
# RESULT: "database.json" is now half-written and corrupted forever.

✅ The Solution

fs-transaction uses the Write-Replace Pattern:

1. It writes data to a temporary file in the same directory.
2. It calls os.fsync() for crash safety.
3. It performs an atomic os.replace() to swap the new file with the old one.

If the script crashes at any point before step 3, your original file remains 100% untouched and valid.

🆚 Why use fs-transaction?

📦 Installation

pip install fs-transaction

🚀 Usage

Quick Start: AtomicWrite

Use AtomicWrite as a drop-in replacement for open() when you need crash-safe single-file writes:

from fs_transaction import AtomicWrite
import json

data = {"status": "processing", "items": [1, 2, 3]}

# Even if this block raises an Exception, 'config.json' will NOT be corrupted.
with AtomicWrite("config.json", mode="w") as f:
    f.write(json.dumps(data, indent=2))

print("File written safely and atomically!")

Batch Operations: Transaction

Use Transaction to group multiple file operations into a single atomic unit:

from fs_transaction import Transaction

with Transaction() as t:
    t.write("config.json", json.dumps(new_config), overwrite=True)
    t.move("data/old.csv", "archive/old.csv")
    t.copy("templates/default.yaml", "config/app.yaml")
    t.delete("cache/stale.tmp")
# ✅ All 4 operations succeed together, or none of them happen.

Overwriting Existing Files

By default, operations raise FileExistsError if the destination exists. Use overwrite=True to safely replace:

# AtomicWrite overwrites by default (like open())
with AtomicWrite("existing_file.txt") as f:
    f.write("Updated content")

# Transaction methods require explicit overwrite=True
with Transaction() as t:
    t.write("existing_file.txt", "Updated", overwrite=True)
    t.copy("src.txt", "existing_dst.txt", overwrite=True)
    t.move("new.txt", "existing.txt", overwrite=True)

Dry-Run Mode

Validate all operations without executing them:

with Transaction(dry_run=True) as t:
    t.move("important.txt", "archive/important.txt")
    t.write("report.txt", generate_report())
# ✅ Validation passed, but no files were changed.

Deleting Files Safely

with Transaction() as t:
    t.delete("obsolete_config.json")
    t.delete("old_data.csv")
# Files are backed up before deletion.
# If something fails, they are restored automatically.

🔧 API Reference

AtomicWrite(path, mode='w', overwrite=True, fsync=True, **kwargs)

Context manager for atomic single-file writes.

Transaction(dry_run=False, fsync=True)

Context manager for batching multiple file operations atomically.

Methods:

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│                  Transaction                     │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│  │FileMove │ │FileCopy │ │FileWrite│ │FileDel │ │
│  └────┬────┘ └────┬────┘ └────┬────┘ └───┬────┘ │
│       │           │           │           │      │
│  ┌────▼───────────▼───────────▼───────────▼────┐ │
│  │           1. Validate All                   │ │
│  │           2. Execute All (with backups)      │ │
│  │           3. Cleanup / Rollback              │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

🛡️ Safety Guarantees

• Atomicity: Operations are committed as a single unit. Partial state is impossible.
• Crash Safety: os.fsync() ensures data hits disk before the atomic rename.
• Backup-Restore: Original files are backed up before overwrite. On failure, they are restored.
• Thread Safety: Internal locking prevents concurrent commits.
• Automatic Cleanup: Temp files are always cleaned up, even on exceptions.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

📋 Changelog

See CHANGELOG.md for a list of changes.