versionio 0.1.1
Drop-in replacement for open() with automatic file versioning
License: MIT
Requires Python: >=3.8

# versionIO

[![PyPI version](https://badge.fury.io/py/versionio.svg)](https://pypi.org/project/versionio/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A drop-in replacement for Python's `open()` function that automatically versions your files.

## Features

- 🔄 **Drop-in replacement** for Python's built-in `open()`
- 📦 **Automatic backups** before every write operation  
- 🗂️ **Version history** with timestamps
- 🔧 **Configurable retention policies** (keep last N versions)
- 🚀 **Zero dependencies** - uses only Python standard library
- 🖥️ **Cross-platform** - Windows, macOS, Linux
- 🔒 **Thread-safe** with file locking

## Installation
```bash
pip install versionio
```

## Quick Start

### Drop-in Replacement

Simply replace Python's `open()` with versionIO's:
```python
# Instead of:
# from builtins import open

# Use:
from versionio import open

# Your existing code works without changes!
with open('important_file.txt', 'w') as f:
    f.write('New content')  # Old version automatically backed up!
```

### High-level Interface
```python
from versionio import VersionedFile

vf = VersionedFile('config.json')

# Write new content (auto-versioned)
vf.write('{"setting": "new_value"}')

# List all versions
for version in vf.versions():
    print(f"{version.timestamp}: {version.size} bytes")

# Restore previous version
vf.restore(vf.versions()[0])
```

### Retention Policy

Keep only the last N versions to save space:
```python
from versionio import open, VersionPolicy

# Keep only last 5 versions
policy = VersionPolicy(max_versions=5)

with open('data.csv', 'w', policy=policy) as f:
    f.write('id,name,value\n1,example,100')
```

## How It Works

versionIO automatically creates backups before modifying files:
```
myfile.txt                    # Current file
.versions/
└── myfile.txt/
    ├── 20240115_143022_001.txt   # Backup from Jan 15, 14:30:22
    ├── 20240115_151533_001.txt   # Backup from Jan 15, 15:15:33
    └── 20240116_091000_001.txt   # Backup from Jan 16, 09:10:00
```

## Advanced Features

### Disable Versioning
```python
# Disable for specific files
with open('temp.txt', 'w', versioning=False) as f:
    f.write('No backup needed')
```

### Custom Policies
```python
from versionio import VersionPolicy

policy = VersionPolicy(
    max_versions=10,      # Keep last 10 versions
    compress=False,       # Don't compress (future feature)
    diff_based=False,     # Store full copies (future feature)
)
```

## Use Cases

- **Configuration files** - Track every change to your app's settings
- **Data files** - Keep history of CSV, JSON, or other data files
- **Log files** - Maintain append history with automatic rotation
- **Critical documents** - Never lose important modifications
- **Development** - Simple version control for single files

## Contributing

Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

Licensed under the [MIT License](https://opensource.org/licenses/MIT).

## Links

<!--- [Documentation](https://versionio.readthedocs.io)-->
- [PyPI Package](https://pypi.org/project/versionio/)
- [GitHub Repository](https://github.com/nikhilsshekhawat/versionio)
<!--- [Issue Tracker](https://github.com/yourusername/versionio/issues)-->