Metadata-Version: 2.4
Name: sonnet-storage
Version: 0.1.0
Summary: Virtual file storage backed by PostgreSQL for sonnet-server applications
Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
License-Expression: Apache-2.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <4.0,>=3.14
Description-Content-Type: text/markdown
Requires-Dist: sonnet-server>=0.1.12
Requires-Dist: universal-pathlib>=0.3.10
Requires-Dist: loguru>=0.7.3
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

# sonnet-storage

Virtual file storage backed by PostgreSQL for sonnet-server applications.

Provides a [UPath](https://github.com/fsspec/universal_pathlib)-compatible
filesystem abstraction over a database table. Consumers use standard
pathlib operations (`read_text()`, `write_text()`, `iterdir()`, etc.)
and the backend (local filesystem or database) is transparent.

## Quick Start

```python
from sonnet_storage import get_storage_root, register_protocol

# Register the db:// protocol (once at startup)
register_protocol()

# Use like pathlib
root = get_storage_root()
rules = root / "rules"
for f in rules.iterdir():
    content = f.read_text()
```

## Features

- Text, JSON (native JSONB), and binary content storage
- Soft delete with recovery
- Versioning (monotonic counter per file)
- Seeding from local directories / package data
- Configurable UPath protocol name (default: `db://`)
- Pre-built REST router factory
- Optional `StorageExtension` for auto-registration

## Database

PostgreSQL only. See [docs/data-model.md](docs/data-model.md) for the
complete schema reference. Consumers own their Alembic migrations --
see [ADR-0002](../../docs/adr/0002-no-shipped-migrations.md).

## Documentation

- [Design document](docs/design/virtual-file-storage.md)
- [Data model reference](docs/data-model.md)
