Metadata-Version: 2.4
Name: filelayer
Version: 0.1.0
Summary: Simple file access abstraction over local filesystem and S3-compatible storage.
Author: Sireto
License: MIT
Project-URL: Homepage, https://sireto.io
Project-URL: Repository, https://sireto.io
Keywords: storage,s3,wasabi,filesystem,abstraction,boto3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3<2.0,>=1.34
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pydantic-settings<3.0,>=2.2
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Dynamic: license-file

# filelayer

`filelayer` is a small Python package that provides a simple file abstraction over:

- local filesystem
- S3-compatible object storage such as Wasabi

It exposes a minimal API:

- `read_file(filepath) -> str`
- `write_file(filepath, file_content) -> None`
- `read_file_bytes(filepath) -> bytes`
- `write_file_bytes(filepath, file_bytes) -> None`
- `exists(filepath) -> bool`

For S3-compatible backends, `filepath` is treated as the object key.
For local storage, `filepath` is resolved relative to the configured local base path.

## Installation

```bash
pip install filelayer
```

For development:

```bash
pip install -e .[dev]
```

## Local filesystem example

Environment:

```env
STORAGE_PROVIDER=local
STORAGE_DEFAULT_PREFIX=my-app
STORAGE_ENCODING=utf-8
LOCAL_STORAGE_BASE_PATH=./data/storage
```

Usage:

```python
from filelayer import StorageService

storage = StorageService.from_settings()

storage.write_file("documents/example.txt", "Hello from local storage")
content = storage.read_file("documents/example.txt")
print(content)

storage.write_file_bytes("documents/example.bin", b"\x00\x01\x02")
print(storage.read_file_bytes("documents/example.bin"))
print(storage.exists("documents/example.txt"))
```

## Wasabi / S3-compatible example

Environment:

```env
STORAGE_PROVIDER=s3
STORAGE_DEFAULT_PREFIX=my-app
STORAGE_ENCODING=utf-8

S3_ENDPOINT_URL=https://s3.eu-central-1.wasabisys.com
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_REGION_NAME=eu-central-1
S3_BUCKET=your-bucket
S3_USE_SSL=true
S3_VERIFY_SSL=true
S3_ADDRESSING_STYLE=virtual
S3_CONNECT_TIMEOUT=10
S3_READ_TIMEOUT=60
S3_MAX_ATTEMPTS=5
```

Usage:

```python
from filelayer import StorageService

storage = StorageService.from_settings()

storage.write_file("documents/example.txt", "Hello from Wasabi")
print(storage.read_file("documents/example.txt"))
print(storage.exists("documents/example.txt"))
```

## Notes

- `STORAGE_DEFAULT_PREFIX` is prepended to all paths or keys.
- `write_file()` stores text using `STORAGE_ENCODING`.
- `write_file_bytes()` stores raw bytes unchanged.
- Local provider prevents path traversal outside the configured storage root.
