# redis-fs

A unified file-system-like storage API with Redis and local filesystem backends.

## Features

- **Unified API**: Same interface regardless of backend
- **Async-first**: Built on `asyncio`
- **Flexible backends**: Local FS, Redis, or both
- **Automatic sync**: Mirror Redis changes to local filesystem
- **Bulk operations**: Upload/download entire directory trees
- **Upstash support**: Works with Upstash Redis for serverless

## Installation

```bash
# With uv (recommended)
uv add redis-fs

# With pip
pip install redis-fs
```

## Quick Start

```python
import asyncio
from redis_fs import RedisFs

async def main():
    # Filesystem only
    async with RedisFs(fs_root="/tmp/data") as rfs:
        await rfs.write_text("hello.txt", "Hello, World!")
        content = await rfs.read_text("hello.txt")
        print(content)

    # Redis only
    async with RedisFs(redis="redis://localhost:6379", redis_prefix="myapp") as rfs:
        await rfs.write_text("config.json", '{"debug": true}')

    # Both with sync
    async with RedisFs(
        redis="redis://localhost:6379",
        redis_prefix="myapp",
        fs_root="/tmp/data"
    ) as rfs:
        await rfs.start_sync()
        await rfs.write_text("data.txt", "Synced!")
        await rfs.stop_sync()

asyncio.run(main())
```

## Documentation

See the [full documentation](https://yaakovb.github.io/redis-fs/) for:

- [Usage Guide](https://yaakovb.github.io/redis-fs/usage/)
- [Testing](https://yaakovb.github.io/redis-fs/testing/)
- [Build & Publish](https://yaakovb.github.io/redis-fs/publishing/)
- [API Reference](https://yaakovb.github.io/redis-fs/api/)

## License

MIT License - see [LICENSE](LICENSE) for details.
