filelayer 0.1.0__tar.gz

filelayer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sireto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

filelayer-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+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.

filelayer-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 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.

filelayer-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "filelayer"
+version = "0.1.0"
+description = "Simple file access abstraction over local filesystem and S3-compatible storage."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Sireto" }
+]
+keywords = ["storage", "s3", "wasabi", "filesystem", "abstraction", "boto3"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Filesystems",
+]
+dependencies = [
+  "boto3>=1.34,<2.0",
+  "pydantic>=2.7,<3.0",
+  "pydantic-settings>=2.2,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+]
+
+[project.urls]
+Homepage = "https://sireto.io"
+Repository = "https://sireto.io"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

filelayer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

filelayer-0.1.0/src/filelayer/__init__.py

@@ -0,0 +1,28 @@
+from .config import StorageSettings
+from .exceptions import (
+    StorageConfigurationError,
+    StorageError,
+    StorageObjectNotFoundError,
+    StorageReadError,
+    StorageWriteError,
+)
+from .factory import create_file_provider
+from .logging_utils import StructuredLogger, configure_logging
+from .providers import FileProvider, LocalFileProvider, S3FileProvider
+from .service import StorageService
+
+__all__ = [
+    "StorageSettings",
+    "StorageError",
+    "StorageConfigurationError",
+    "StorageReadError",
+    "StorageWriteError",
+    "StorageObjectNotFoundError",
+    "StructuredLogger",
+    "configure_logging",
+    "FileProvider",
+    "LocalFileProvider",
+    "S3FileProvider",
+    "create_file_provider",
+    "StorageService",
+]

filelayer-0.1.0/src/filelayer/config.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import AliasChoices, Field, SecretStr, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .exceptions import StorageConfigurationError
+
+
+class StorageSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    provider: Literal["local", "s3"] = Field(
+        ...,
+        validation_alias=AliasChoices("STORAGE_PROVIDER"),
+    )
+
+    default_prefix: str = Field(
+        default="",
+        validation_alias=AliasChoices("STORAGE_DEFAULT_PREFIX"),
+    )
+
+    encoding: str = Field(
+        default="utf-8",
+        validation_alias=AliasChoices("STORAGE_ENCODING"),
+    )
+
+    local_base_path: Path = Field(
+        default=Path("./data/storage"),
+        validation_alias=AliasChoices("LOCAL_STORAGE_BASE_PATH"),
+    )
+
+    s3_endpoint_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("S3_ENDPOINT_URL"),
+    )
+    s3_access_key_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("S3_ACCESS_KEY_ID"),
+    )
+    s3_secret_access_key: SecretStr | None = Field(
+        default=None,
+        validation_alias=AliasChoices("S3_SECRET_ACCESS_KEY"),
+    )
+    s3_session_token: SecretStr | None = Field(
+        default=None,
+        validation_alias=AliasChoices("S3_SESSION_TOKEN"),
+    )
+    s3_region_name: str = Field(
+        default="us-east-1",
+        validation_alias=AliasChoices("S3_REGION_NAME", "AWS_DEFAULT_REGION"),
+    )
+    s3_bucket: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("S3_BUCKET", "S3_BUCKET_NAME"),
+    )
+    s3_use_ssl: bool = Field(
+        default=True,
+        validation_alias=AliasChoices("S3_USE_SSL"),
+    )
+    s3_verify_ssl: bool = Field(
+        default=True,
+        validation_alias=AliasChoices("S3_VERIFY_SSL"),
+    )
+    s3_addressing_style: Literal["virtual", "path", "auto"] = Field(
+        default="virtual",
+        validation_alias=AliasChoices("S3_ADDRESSING_STYLE"),
+    )
+    s3_connect_timeout: int = Field(
+        default=10,
+        validation_alias=AliasChoices("S3_CONNECT_TIMEOUT"),
+    )
+    s3_read_timeout: int = Field(
+        default=60,
+        validation_alias=AliasChoices("S3_READ_TIMEOUT"),
+    )
+    s3_max_attempts: int = Field(
+        default=5,
+        validation_alias=AliasChoices("S3_MAX_ATTEMPTS"),
+    )
+
+    @field_validator("default_prefix")
+    @classmethod
+    def normalize_default_prefix(cls, value: str) -> str:
+        return value.strip("/")
+
+    @field_validator("local_base_path")
+    @classmethod
+    def normalize_local_base_path(cls, value: Path) -> Path:
+        return value.expanduser()
+
+    @model_validator(mode="after")
+    def validate_provider_settings(self) -> "StorageSettings":
+        if self.provider == "s3":
+            missing: list[str] = []
+
+            if not self.s3_access_key_id:
+                missing.append("S3_ACCESS_KEY_ID")
+            if not self.s3_secret_access_key:
+                missing.append("S3_SECRET_ACCESS_KEY")
+            if not self.s3_bucket:
+                missing.append("S3_BUCKET")
+
+            if missing:
+                raise StorageConfigurationError(
+                    "Missing required S3 settings: " + ", ".join(missing)
+                )
+
+        return self
+
+    @property
+    def s3_secret_access_key_value(self) -> str | None:
+        return (
+            self.s3_secret_access_key.get_secret_value()
+            if self.s3_secret_access_key
+            else None
+        )
+
+    @property
+    def s3_session_token_value(self) -> str | None:
+        return (
+            self.s3_session_token.get_secret_value()
+            if self.s3_session_token
+            else None
+        )

filelayer-0.1.0/src/filelayer/exceptions.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+class StorageError(Exception):
+    """Base exception for storage-related errors."""
+
+
+class StorageConfigurationError(StorageError):
+    """Raised when storage configuration is invalid."""
+
+
+class StorageReadError(StorageError):
+    """Raised when reading fails."""
+
+
+class StorageWriteError(StorageError):
+    """Raised when writing fails."""
+
+
+class StorageObjectNotFoundError(StorageError):
+    """Raised when the requested file or object does not exist."""

filelayer-0.1.0/src/filelayer/factory.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import logging
+
+from .config import StorageSettings
+from .exceptions import StorageConfigurationError
+from .providers import FileProvider, LocalFileProvider, S3FileProvider
+
+
+def create_file_provider(
+    settings: StorageSettings | None = None,
+    logger: logging.Logger | None = None,
+) -> FileProvider:
+    resolved_settings = settings or StorageSettings()
+
+    if resolved_settings.provider == "local":
+        return LocalFileProvider(resolved_settings, logger=logger)
+
+    if resolved_settings.provider == "s3":
+        return S3FileProvider(resolved_settings, logger=logger)
+
+    raise StorageConfigurationError(
+        f"Unsupported storage provider: {resolved_settings.provider}"
+    )

filelayer-0.1.0/src/filelayer/logging_utils.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+
+class StructuredLogger:
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+
+    def info(self, event: str, **fields: Any) -> None:
+        self._logger.info(self._serialize(event, **fields))
+
+    def warning(self, event: str, **fields: Any) -> None:
+        self._logger.warning(self._serialize(event, **fields))
+
+    def exception(self, event: str, **fields: Any) -> None:
+        self._logger.exception(self._serialize(event, **fields))
+
+    @staticmethod
+    def _serialize(event: str, **fields: Any) -> str:
+        return json.dumps({"event": event, **fields}, default=str, ensure_ascii=False)

filelayer-0.1.0/src/filelayer/providers/__init__.py

@@ -0,0 +1,9 @@
+from .base import FileProvider
+from .local import LocalFileProvider
+from .s3 import S3FileProvider
+
+__all__ = [
+    "FileProvider",
+    "LocalFileProvider",
+    "S3FileProvider",
+]

filelayer-0.1.0/src/filelayer/providers/base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class FileProvider(ABC):
+    @abstractmethod
+    def read_file(self, filepath: str) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def write_file(self, filepath: str, file_content: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def read_file_bytes(self, filepath: str) -> bytes:
+        raise NotImplementedError
+
+    @abstractmethod
+    def write_file_bytes(self, filepath: str, file_bytes: bytes) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def exists(self, filepath: str) -> bool:
+        raise NotImplementedError

filelayer-0.1.0/src/filelayer/providers/local.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path, PurePosixPath
+
+from ..config import StorageSettings
+from ..exceptions import (
+    StorageConfigurationError,
+    StorageObjectNotFoundError,
+    StorageReadError,
+    StorageWriteError,
+)
+from ..logging_utils import StructuredLogger
+from .base import FileProvider
+
+
+class LocalFileProvider(FileProvider):
+    def __init__(
+        self,
+        settings: StorageSettings,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        if settings.provider != "local":
+            raise StorageConfigurationError(
+                "LocalFileProvider requires STORAGE_PROVIDER=local."
+            )
+
+        self.settings = settings
+        self.root_path = settings.local_base_path.resolve()
+        self.root_path.mkdir(parents=True, exist_ok=True)
+        self.log = StructuredLogger(logger or logging.getLogger(self.__class__.__name__))
+
+    def _normalize_filepath(self, filepath: str) -> str:
+        clean_path = filepath.replace("\\", "/").strip().lstrip("/")
+        path_parts = PurePosixPath(clean_path).parts if clean_path else ()
+
+        if any(part in {".", ".."} for part in path_parts):
+            raise StorageConfigurationError(f"Invalid filepath: {filepath}")
+
+        prefix = self.settings.default_prefix
+
+        if not clean_path and not prefix:
+            raise ValueError("filepath must not be empty.")
+
+        if prefix and clean_path:
+            return f"{prefix}/{clean_path}"
+        return clean_path or prefix
+
+    def _resolve_path(self, filepath: str) -> Path:
+        normalized = self._normalize_filepath(filepath)
+        candidate = (self.root_path / normalized).resolve()
+
+        try:
+            candidate.relative_to(self.root_path)
+        except ValueError as exc:
+            raise StorageConfigurationError(
+                f"filepath escapes local storage root: {filepath}"
+            ) from exc
+
+        return candidate
+
+    def read_file(self, filepath: str) -> str:
+        resolved = self._resolve_path(filepath)
+
+        self.log.info(
+            "local_read_text_started",
+            filepath=filepath,
+            resolved_path=str(resolved),
+            encoding=self.settings.encoding,
+        )
+
+        if not resolved.exists() or not resolved.is_file():
+            raise StorageObjectNotFoundError(f"Local file not found: {filepath}")
+
+        try:
+            content = resolved.read_text(encoding=self.settings.encoding)
+            self.log.info(
+                "local_read_text_completed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+                size_chars=len(content),
+            )
+            return content
+        except StorageObjectNotFoundError:
+            raise
+        except UnicodeDecodeError as exc:
+            self.log.exception(
+                "local_read_text_decode_failed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+                encoding=self.settings.encoding,
+            )
+            raise StorageReadError(
+                f"Failed to decode local file '{filepath}' using '{self.settings.encoding}'."
+            ) from exc
+        except Exception as exc:
+            self.log.exception(
+                "local_read_text_failed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+            )
+            raise StorageReadError(f"Failed to read local file: {filepath}") from exc
+
+    def write_file(self, filepath: str, file_content: str) -> None:
+        resolved = self._resolve_path(filepath)
+        resolved.parent.mkdir(parents=True, exist_ok=True)
+
+        self.log.info(
+            "local_write_text_started",
+            filepath=filepath,
+            resolved_path=str(resolved),
+            size_chars=len(file_content),
+            encoding=self.settings.encoding,
+        )
+
+        try:
+            resolved.write_text(file_content, encoding=self.settings.encoding)
+            self.log.info(
+                "local_write_text_completed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+                size_chars=len(file_content),
+            )
+        except UnicodeEncodeError as exc:
+            self.log.exception(
+                "local_write_text_encode_failed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+                encoding=self.settings.encoding,
+            )
+            raise StorageWriteError(
+                f"Failed to encode local file '{filepath}' using '{self.settings.encoding}'."
+            ) from exc
+        except Exception as exc:
+            self.log.exception(
+                "local_write_text_failed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+            )
+            raise StorageWriteError(f"Failed to write local file: {filepath}") from exc
+
+    def read_file_bytes(self, filepath: str) -> bytes:
+        resolved = self._resolve_path(filepath)
+
+        self.log.info(
+            "local_read_bytes_started",
+            filepath=filepath,
+            resolved_path=str(resolved),
+        )
+
+        if not resolved.exists() or not resolved.is_file():
+            raise StorageObjectNotFoundError(f"Local file not found: {filepath}")
+
+        try:
+            data = resolved.read_bytes()
+            self.log.info(
+                "local_read_bytes_completed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+                size_bytes=len(data),
+            )
+            return data
+        except StorageObjectNotFoundError:
+            raise
+        except Exception as exc:
+            self.log.exception(
+                "local_read_bytes_failed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+            )
+            raise StorageReadError(f"Failed to read local file: {filepath}") from exc
+
+    def write_file_bytes(self, filepath: str, file_bytes: bytes) -> None:
+        resolved = self._resolve_path(filepath)
+        resolved.parent.mkdir(parents=True, exist_ok=True)
+
+        self.log.info(
+            "local_write_bytes_started",
+            filepath=filepath,
+            resolved_path=str(resolved),
+            size_bytes=len(file_bytes),
+        )
+
+        try:
+            resolved.write_bytes(file_bytes)
+            self.log.info(
+                "local_write_bytes_completed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+                size_bytes=len(file_bytes),
+            )
+        except Exception as exc:
+            self.log.exception(
+                "local_write_bytes_failed",
+                filepath=filepath,
+                resolved_path=str(resolved),
+            )
+            raise StorageWriteError(f"Failed to write local file: {filepath}") from exc
+
+    def exists(self, filepath: str) -> bool:
+        resolved = self._resolve_path(filepath)
+        return resolved.exists() and resolved.is_file()

filelayer-0.1.0/src/filelayer/providers/s3.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import logging
+from pathlib import PurePosixPath
+
+import boto3
+from botocore.client import BaseClient
+from botocore.config import Config as BotoConfig
+from botocore.exceptions import (
+    BotoCoreError,
+    ClientError,
+    ConnectTimeoutError,
+    EndpointConnectionError,
+)
+
+from ..config import StorageSettings
+from ..exceptions import (
+    StorageConfigurationError,
+    StorageObjectNotFoundError,
+    StorageReadError,
+    StorageWriteError,
+)
+from ..logging_utils import StructuredLogger
+from .base import FileProvider
+
+
+class S3FileProvider(FileProvider):
+    def __init__(
+        self,
+        settings: StorageSettings,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        if settings.provider != "s3":
+            raise StorageConfigurationError(
+                "S3FileProvider requires STORAGE_PROVIDER=s3."
+            )
+
+        self.settings = settings
+        self.bucket = settings.s3_bucket
+        if not self.bucket:
+            raise StorageConfigurationError("S3 bucket is not configured.")
+
+        self.log = StructuredLogger(logger or logging.getLogger(self.__class__.__name__))
+        self.client = self._build_client()
+
+    def _build_client(self) -> BaseClient:
+        try:
+            boto_config = BotoConfig(
+                region_name=self.settings.s3_region_name,
+                signature_version="s3v4",
+                connect_timeout=self.settings.s3_connect_timeout,
+                read_timeout=self.settings.s3_read_timeout,
+                retries={
+                    "max_attempts": self.settings.s3_max_attempts,
+                    "mode": "standard",
+                },
+                s3={"addressing_style": self.settings.s3_addressing_style},
+            )
+
+            return boto3.client(
+                "s3",
+                endpoint_url=self.settings.s3_endpoint_url,
+                aws_access_key_id=self.settings.s3_access_key_id,
+                aws_secret_access_key=self.settings.s3_secret_access_key_value,
+                aws_session_token=self.settings.s3_session_token_value,
+                region_name=self.settings.s3_region_name,
+                use_ssl=self.settings.s3_use_ssl,
+                verify=self.settings.s3_verify_ssl,
+                config=boto_config,
+            )
+        except Exception as exc:
+            raise StorageConfigurationError("Failed to initialize S3 client.") from exc
+
+    def _normalize_filepath(self, filepath: str) -> str:
+        clean_path = filepath.replace("\\", "/").strip().lstrip("/")
+        path_parts = PurePosixPath(clean_path).parts if clean_path else ()
+
+        if any(part in {".", ".."} for part in path_parts):
+            raise StorageConfigurationError(f"Invalid filepath: {filepath}")
+
+        prefix = self.settings.default_prefix
+
+        if not clean_path and not prefix:
+            raise ValueError("filepath must not be empty.")
+
+        if prefix and clean_path:
+            return f"{prefix}/{clean_path}"
+        return clean_path or prefix
+
+    def read_file(self, filepath: str) -> str:
+        key = self._normalize_filepath(filepath)
+
+        self.log.info(
+            "s3_read_text_started",
+            bucket=self.bucket,
+            key=key,
+            encoding=self.settings.encoding,
+        )
+
+        try:
+            response = self.client.get_object(Bucket=self.bucket, Key=key)
+            body = response["Body"].read()
+
+            if not isinstance(body, bytes):
+                raise StorageReadError(f"Unexpected response body for key: {filepath}")
+
+            content = body.decode(self.settings.encoding)
+
+            self.log.info(
+                "s3_read_text_completed",
+                bucket=self.bucket,
+                key=key,
+                size_chars=len(content),
+            )
+            return content
+
+        except ClientError as exc:
+            error_code = exc.response.get("Error", {}).get("Code")
+            if error_code in {"404", "NoSuchKey", "NotFound"}:
+                raise StorageObjectNotFoundError(f"S3 object not found: {filepath}") from exc
+
+            self.log.exception(
+                "s3_read_text_failed",
+                bucket=self.bucket,
+                key=key,
+                error_code=error_code,
+            )
+            raise StorageReadError(f"Failed to read S3 object: {filepath}") from exc
+
+        except UnicodeDecodeError as exc:
+            self.log.exception(
+                "s3_read_text_decode_failed",
+                bucket=self.bucket,
+                key=key,
+                encoding=self.settings.encoding,
+            )
+            raise StorageReadError(
+                f"Failed to decode S3 object '{filepath}' using '{self.settings.encoding}'."
+            ) from exc
+
+        except (BotoCoreError, EndpointConnectionError, ConnectTimeoutError) as exc:
+            self.log.exception(
+                "s3_read_text_failed",
+                bucket=self.bucket,
+                key=key,
+            )
+            raise StorageReadError(f"Failed to read S3 object: {filepath}") from exc
+
+    def write_file(self, filepath: str, file_content: str) -> None:
+        key = self._normalize_filepath(filepath)
+
+        self.log.info(
+            "s3_write_text_started",
+            bucket=self.bucket,
+            key=key,
+            size_chars=len(file_content),
+            encoding=self.settings.encoding,
+        )
+
+        try:
+            body = file_content.encode(self.settings.encoding)
+            self.client.put_object(
+                Bucket=self.bucket,
+                Key=key,
+                Body=body,
+                ContentType=f"text/plain; charset={self.settings.encoding}",
+            )
+            self.log.info(
+                "s3_write_text_completed",
+                bucket=self.bucket,
+                key=key,
+                size_chars=len(file_content),
+            )
+        except UnicodeEncodeError as exc:
+            self.log.exception(
+                "s3_write_text_encode_failed",
+                bucket=self.bucket,
+                key=key,
+                encoding=self.settings.encoding,
+            )
+            raise StorageWriteError(
+                f"Failed to encode S3 object '{filepath}' using '{self.settings.encoding}'."
+            ) from exc
+        except Exception as exc:
+            self.log.exception(
+                "s3_write_text_failed",
+                bucket=self.bucket,
+                key=key,
+            )
+            raise StorageWriteError(f"Failed to write S3 object: {filepath}") from exc
+
+    def read_file_bytes(self, filepath: str) -> bytes:
+        key = self._normalize_filepath(filepath)
+
+        self.log.info(
+            "s3_read_bytes_started",
+            bucket=self.bucket,
+            key=key,
+        )
+
+        try:
+            response = self.client.get_object(Bucket=self.bucket, Key=key)
+            body = response["Body"].read()
+
+            if not isinstance(body, bytes):
+                raise StorageReadError(f"Unexpected response body for key: {filepath}")
+
+            self.log.info(
+                "s3_read_bytes_completed",
+                bucket=self.bucket,
+                key=key,
+                size_bytes=len(body),
+            )
+            return body
+
+        except ClientError as exc:
+            error_code = exc.response.get("Error", {}).get("Code")
+            if error_code in {"404", "NoSuchKey", "NotFound"}:
+                raise StorageObjectNotFoundError(f"S3 object not found: {filepath}") from exc
+
+            self.log.exception(
+                "s3_read_bytes_failed",
+                bucket=self.bucket,
+                key=key,
+                error_code=error_code,
+            )
+            raise StorageReadError(f"Failed to read S3 object: {filepath}") from exc
+
+        except (BotoCoreError, EndpointConnectionError, ConnectTimeoutError) as exc:
+            self.log.exception(
+                "s3_read_bytes_failed",
+                bucket=self.bucket,
+                key=key,
+            )
+            raise StorageReadError(f"Failed to read S3 object: {filepath}") from exc
+
+    def write_file_bytes(self, filepath: str, file_bytes: bytes) -> None:
+        key = self._normalize_filepath(filepath)
+
+        self.log.info(
+            "s3_write_bytes_started",
+            bucket=self.bucket,
+            key=key,
+            size_bytes=len(file_bytes),
+        )
+
+        try:
+            self.client.put_object(
+                Bucket=self.bucket,
+                Key=key,
+                Body=file_bytes,
+                ContentType="application/octet-stream",
+            )
+            self.log.info(
+                "s3_write_bytes_completed",
+                bucket=self.bucket,
+                key=key,
+                size_bytes=len(file_bytes),
+            )
+        except Exception as exc:
+            self.log.exception(
+                "s3_write_bytes_failed",
+                bucket=self.bucket,
+                key=key,
+            )
+            raise StorageWriteError(f"Failed to write S3 object: {filepath}") from exc
+
+    def exists(self, filepath: str) -> bool:
+        key = self._normalize_filepath(filepath)
+
+        try:
+            self.client.head_object(Bucket=self.bucket, Key=key)
+            return True
+        except ClientError as exc:
+            error_code = exc.response.get("Error", {}).get("Code")
+            if error_code in {"404", "NoSuchKey", "NotFound"}:
+                return False
+            raise StorageReadError(
+                f"Failed to check existence for S3 object: {filepath}"
+            ) from exc
+        except Exception as exc:
+            raise StorageReadError(
+                f"Failed to check existence for S3 object: {filepath}"
+            ) from exc

filelayer-0.1.0/src/filelayer/service.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .config import StorageSettings
+from .factory import create_file_provider
+from .providers.base import FileProvider
+
+
+class StorageService:
+    def __init__(self, provider: FileProvider) -> None:
+        self.provider = provider
+
+    @classmethod
+    def from_settings(cls, settings: StorageSettings | None = None) -> "StorageService":
+        provider = create_file_provider(settings=settings)
+        return cls(provider)
+
+    def read_file(self, filepath: str) -> str:
+        return self.provider.read_file(filepath)
+
+    def write_file(self, filepath: str, file_content: str) -> None:
+        self.provider.write_file(filepath, file_content)
+
+    def read_file_bytes(self, filepath: str) -> bytes:
+        return self.provider.read_file_bytes(filepath)
+
+    def write_file_bytes(self, filepath: str, file_bytes: bytes) -> None:
+        self.provider.write_file_bytes(filepath, file_bytes)
+
+    def exists(self, filepath: str) -> bool:
+        return self.provider.exists(filepath)

filelayer-0.1.0/src/filelayer.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+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.

filelayer-0.1.0/src/filelayer.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/filelayer/__init__.py
+src/filelayer/config.py
+src/filelayer/exceptions.py
+src/filelayer/factory.py
+src/filelayer/logging_utils.py
+src/filelayer/service.py
+src/filelayer.egg-info/PKG-INFO
+src/filelayer.egg-info/SOURCES.txt
+src/filelayer.egg-info/dependency_links.txt
+src/filelayer.egg-info/requires.txt
+src/filelayer.egg-info/top_level.txt
+src/filelayer/providers/__init__.py
+src/filelayer/providers/base.py
+src/filelayer/providers/local.py
+src/filelayer/providers/s3.py
+tests/test_factory.py
+tests/test_local_provider.py
+tests/test_service.py

filelayer-0.1.0/src/filelayer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

filelayer-0.1.0/src/filelayer.egg-info/requires.txt

@@ -0,0 +1,6 @@
+boto3<2.0,>=1.34
+pydantic<3.0,>=2.7
+pydantic-settings<3.0,>=2.2
+
+[dev]
+pytest<9.0,>=8.0

filelayer-0.1.0/src/filelayer.egg-info/top_level.txt

@@ -0,0 +1 @@
+filelayer

filelayer-0.1.0/tests/test_factory.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+from filelayer import LocalFileProvider, StorageSettings, create_file_provider
+
+
+def test_create_local_provider(tmp_path: Path) -> None:
+    settings = StorageSettings(
+        STORAGE_PROVIDER="local",
+        LOCAL_STORAGE_BASE_PATH=str(tmp_path),
+    )
+
+    provider = create_file_provider(settings)
+
+    assert isinstance(provider, LocalFileProvider)

filelayer-0.1.0/tests/test_local_provider.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+import pytest
+
+from filelayer import LocalFileProvider, StorageObjectNotFoundError, StorageSettings
+
+
+@pytest.fixture
+def local_settings(tmp_path: Path) -> StorageSettings:
+    return StorageSettings(
+        STORAGE_PROVIDER="local",
+        LOCAL_STORAGE_BASE_PATH=str(tmp_path),
+        STORAGE_DEFAULT_PREFIX="test-prefix",
+        STORAGE_ENCODING="utf-8",
+    )
+
+
+def test_write_and_read_text(local_settings: StorageSettings) -> None:
+    provider = LocalFileProvider(local_settings)
+
+    provider.write_file("docs/hello.txt", "hello world")
+
+    assert provider.exists("docs/hello.txt") is True
+    assert provider.read_file("docs/hello.txt") == "hello world"
+
+
+def test_write_and_read_bytes(local_settings: StorageSettings) -> None:
+    provider = LocalFileProvider(local_settings)
+
+    provider.write_file_bytes("bin/data.bin", b"\x00\x01\x02")
+
+    assert provider.exists("bin/data.bin") is True
+    assert provider.read_file_bytes("bin/data.bin") == b"\x00\x01\x02"
+
+
+def test_missing_file_raises(local_settings: StorageSettings) -> None:
+    provider = LocalFileProvider(local_settings)
+
+    with pytest.raises(StorageObjectNotFoundError):
+        provider.read_file("missing/file.txt")
+
+
+def test_path_traversal_is_blocked(local_settings: StorageSettings) -> None:
+    provider = LocalFileProvider(local_settings)
+
+    with pytest.raises(Exception):
+        provider.write_file("../escape.txt", "nope")

filelayer-0.1.0/tests/test_service.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from filelayer import LocalFileProvider, StorageService, StorageSettings
+
+
+def test_storage_service_text_and_bytes(tmp_path: Path) -> None:
+    settings = StorageSettings(
+        STORAGE_PROVIDER="local",
+        LOCAL_STORAGE_BASE_PATH=str(tmp_path),
+        STORAGE_DEFAULT_PREFIX="svc",
+    )
+    provider = LocalFileProvider(settings)
+    service = StorageService(provider)
+
+    service.write_file("notes/test.txt", "service text")
+    assert service.read_file("notes/test.txt") == "service text"
+
+    service.write_file_bytes("notes/test.bin", b"abc")
+    assert service.read_file_bytes("notes/test.bin") == b"abc"
+
+    assert service.exists("notes/test.txt") is True
+    assert service.exists("notes/test.bin") is True
+    assert service.exists("notes/missing.txt") is False