s-storagekit 0.1.0__tar.gz

s_storagekit-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.ruff_cache/
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

s_storagekit-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: s-storagekit
+Version: 0.1.0
+Summary: Объектное хранилище (ObjectStorage protocol + MinIO adapter + image normalization for Skillery)
+Author: Dmitry
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: anyio>=3.0
+Requires-Dist: minio>=7.0
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# s-storagekit
+
+Объектное хранилище для Skillery: портабельное async-API для key→bytes операций с реализациями S3-compatible протокола (MinIO) и вспомогательными утилитами нормализации изображений (Pillow).
+
+## Установка
+
+```bash
+pip install s-storagekit>=0.1.0
+```
+
+## Быстрый старт
+
+### Использование MinIO
+
+```python
+from storagekit import MinioObjectStorage, ObjectNotFoundError
+
+# Инициализация
+storage = MinioObjectStorage(
+    endpoint="minio:9000",
+    access_key="minioadmin",
+    secret_key="minioadmin",
+    bucket="my-bucket",
+    secure=False,  # http в dev, https в prod
+)
+
+# Запись объекта
+await storage.put("avatars/user_1/photo.jpg", image_bytes, "image/jpeg")
+
+# Чтение объекта
+data, content_type = await storage.get("avatars/user_1/photo.jpg")
+
+# Удаление объекта
+await storage.delete("avatars/user_1/photo.jpg")
+```
+
+### Обработка изображений
+
+```python
+from storagekit import (
+    normalize_image,
+    normalize_square_avatar,
+    square_avatar_variants,
+)
+
+# Квадратный аватар одного размера
+jpeg_bytes, ct = normalize_square_avatar(raw_image, size=256)
+await storage.put(f"avatars/user_1/{token}.jpg", jpeg_bytes, ct)
+
+# Несколько вариантов размеров (responsive)
+variants = square_avatar_variants(raw_image, sizes=[64, 128, 256])
+for size, blob in variants:
+    key = f"avatars/user_1/{token}_{size}.jpg"
+    await storage.put(key, blob, "image/jpeg")
+
+# Масштабирование обложки (сохраняет пропорции)
+cover_data, ct = normalize_image(raw_image, max_px=1200)
+await storage.put(f"skills/42/cover_{token}.jpg", cover_data, ct)
+```
+
+### Тестирование
+
+```python
+import pytest
+from storagekit.testing import InMemoryObjectStorage, fake_image_bytes
+
+@pytest.fixture
+def storage():
+    return InMemoryObjectStorage()
+
+@pytest.mark.asyncio
+async def test_avatar_upload(storage):
+    raw = fake_image_bytes(100, 100)
+    jpeg_bytes, _ = normalize_square_avatar(raw, size=256)
+    
+    await storage.put("avatars/test.jpg", jpeg_bytes, "image/jpeg")
+    data, ct = await storage.get("avatars/test.jpg")
+    
+    assert ct == "image/jpeg"
+    assert len(data) > 0
+```
+
+### Presigned URL (без auth)
+
+```python
+from storagekit import PresignedUrlGenerator
+
+gen = PresignedUrlGenerator(
+    endpoint="minio:9000",
+    access_key="minioadmin",
+    secret_key="minioadmin",
+    bucket="my-bucket",
+)
+
+# Генерировать URL с TTL (по умолчанию 1 час)
+url = await gen.generate_presigned_get_url("avatars/user_1/photo.jpg")
+# Клиент может скачать файл по этому URL без токена
+```
+
+## API
+
+### Протоколы
+
+```python
+class ObjectStorage(Protocol):
+    """Async key→bytes хранилище."""
+    
+    async def put(self, key: str, data: bytes, content_type: str) -> None:
+        """Записать/перезаписать объект."""
+        ...
+    
+    async def get(self, key: str) -> tuple[bytes, str]:
+        """Вернуть (data, content_type). Бросает ObjectNotFoundError."""
+        ...
+    
+    async def delete(self, key: str) -> None:
+        """Удалить объект. Отсутствие не ошибка (idempotent)."""
+        ...
+```
+
+### Исключения
+
+```python
+class ObjectNotFoundError(Exception):
+    """Объект не найден. Имеет атрибут .key."""
+    def __init__(self, key: str) -> None: ...
+```
+
+### Реализации
+
+```python
+# S3-compatible хранилище (prod/dev)
+class MinioObjectStorage:
+    def __init__(
+        self,
+        *,
+        endpoint: str,        # host:port БЕЗ схемы
+        access_key: str,
+        secret_key: str,
+        bucket: str,
+        secure: bool = False, # http (dev) vs https (prod)
+    ) -> None: ...
+```
+
+### Image-утилиты
+
+```python
+# Список допустимых MIME-типов входных файлов
+ALLOWED_IMAGE_CONTENT_TYPES: frozenset[str]
+
+# Квадратный аватар (center cover-crop) → JPEG
+def normalize_square_avatar(data: bytes, *, size: int) -> tuple[bytes, str]: ...
+
+# Несколько вариантов размеров одного аватара
+def square_avatar_variants(
+    data: bytes, *, sizes: list[int]
+) -> list[tuple[int, bytes]]: ...
+
+# Масштабирование по длинной стороне (сохраняет пропорции)
+def normalize_image(data: bytes, *, max_px: int) -> tuple[bytes, str]: ...
+```
+
+### Утилиты
+
+```python
+# Канонический ключ snapshot'а версии
+def snapshot_key(*, skill_id: int | str, semver: str) -> str:
+    """Возвращает f'skills/{skill_id}/versions/{semver}.tar.gz'."""
+```
+
+### Тестирование
+
+```python
+# Фейк-хранилище в памяти
+class InMemoryObjectStorage:
+    async def put(self, key: str, data: bytes, content_type: str) -> None: ...
+    async def get(self, key: str) -> tuple[bytes, str]: ...
+    async def delete(self, key: str) -> None: ...
+
+# Генерировать тестовый PNG-файл
+def fake_image_bytes(width: int = 100, height: int = 100) -> bytes: ...
+```
+
+## Параметризация
+
+| Параметр | Значение | Примечание |
+|----------|----------|-----------|
+| MinIO endpoint | `host:port` (БЕЗ схемы) | dev: `minio:9000`, prod: `minio.example.com:9000` |
+| MinIO secure | `False` (dev), `True` (prod) | http vs https |
+| Avatar sizes | `[64, 128, 256]` (default) | Можно переопределить в клиенте |
+| Skill cover max px | `1200` (constant) | Не параметризуется |
+| JPEG quality | `85` (constant) | Не параметризуется |
+
+## Зависимости
+
+- **minio>=7.0** — S3 SDK
+- **anyio>=3.0** — async threading
+- **Pillow>=10.0** — image processing
+
+## Лицензия
+
+MIT

s_storagekit-0.1.0/README.md

@@ -0,0 +1,202 @@
+# s-storagekit
+
+Объектное хранилище для Skillery: портабельное async-API для key→bytes операций с реализациями S3-compatible протокола (MinIO) и вспомогательными утилитами нормализации изображений (Pillow).
+
+## Установка
+
+```bash
+pip install s-storagekit>=0.1.0
+```
+
+## Быстрый старт
+
+### Использование MinIO
+
+```python
+from storagekit import MinioObjectStorage, ObjectNotFoundError
+
+# Инициализация
+storage = MinioObjectStorage(
+    endpoint="minio:9000",
+    access_key="minioadmin",
+    secret_key="minioadmin",
+    bucket="my-bucket",
+    secure=False,  # http в dev, https в prod
+)
+
+# Запись объекта
+await storage.put("avatars/user_1/photo.jpg", image_bytes, "image/jpeg")
+
+# Чтение объекта
+data, content_type = await storage.get("avatars/user_1/photo.jpg")
+
+# Удаление объекта
+await storage.delete("avatars/user_1/photo.jpg")
+```
+
+### Обработка изображений
+
+```python
+from storagekit import (
+    normalize_image,
+    normalize_square_avatar,
+    square_avatar_variants,
+)
+
+# Квадратный аватар одного размера
+jpeg_bytes, ct = normalize_square_avatar(raw_image, size=256)
+await storage.put(f"avatars/user_1/{token}.jpg", jpeg_bytes, ct)
+
+# Несколько вариантов размеров (responsive)
+variants = square_avatar_variants(raw_image, sizes=[64, 128, 256])
+for size, blob in variants:
+    key = f"avatars/user_1/{token}_{size}.jpg"
+    await storage.put(key, blob, "image/jpeg")
+
+# Масштабирование обложки (сохраняет пропорции)
+cover_data, ct = normalize_image(raw_image, max_px=1200)
+await storage.put(f"skills/42/cover_{token}.jpg", cover_data, ct)
+```
+
+### Тестирование
+
+```python
+import pytest
+from storagekit.testing import InMemoryObjectStorage, fake_image_bytes
+
+@pytest.fixture
+def storage():
+    return InMemoryObjectStorage()
+
+@pytest.mark.asyncio
+async def test_avatar_upload(storage):
+    raw = fake_image_bytes(100, 100)
+    jpeg_bytes, _ = normalize_square_avatar(raw, size=256)
+    
+    await storage.put("avatars/test.jpg", jpeg_bytes, "image/jpeg")
+    data, ct = await storage.get("avatars/test.jpg")
+    
+    assert ct == "image/jpeg"
+    assert len(data) > 0
+```
+
+### Presigned URL (без auth)
+
+```python
+from storagekit import PresignedUrlGenerator
+
+gen = PresignedUrlGenerator(
+    endpoint="minio:9000",
+    access_key="minioadmin",
+    secret_key="minioadmin",
+    bucket="my-bucket",
+)
+
+# Генерировать URL с TTL (по умолчанию 1 час)
+url = await gen.generate_presigned_get_url("avatars/user_1/photo.jpg")
+# Клиент может скачать файл по этому URL без токена
+```
+
+## API
+
+### Протоколы
+
+```python
+class ObjectStorage(Protocol):
+    """Async key→bytes хранилище."""
+    
+    async def put(self, key: str, data: bytes, content_type: str) -> None:
+        """Записать/перезаписать объект."""
+        ...
+    
+    async def get(self, key: str) -> tuple[bytes, str]:
+        """Вернуть (data, content_type). Бросает ObjectNotFoundError."""
+        ...
+    
+    async def delete(self, key: str) -> None:
+        """Удалить объект. Отсутствие не ошибка (idempotent)."""
+        ...
+```
+
+### Исключения
+
+```python
+class ObjectNotFoundError(Exception):
+    """Объект не найден. Имеет атрибут .key."""
+    def __init__(self, key: str) -> None: ...
+```
+
+### Реализации
+
+```python
+# S3-compatible хранилище (prod/dev)
+class MinioObjectStorage:
+    def __init__(
+        self,
+        *,
+        endpoint: str,        # host:port БЕЗ схемы
+        access_key: str,
+        secret_key: str,
+        bucket: str,
+        secure: bool = False, # http (dev) vs https (prod)
+    ) -> None: ...
+```
+
+### Image-утилиты
+
+```python
+# Список допустимых MIME-типов входных файлов
+ALLOWED_IMAGE_CONTENT_TYPES: frozenset[str]
+
+# Квадратный аватар (center cover-crop) → JPEG
+def normalize_square_avatar(data: bytes, *, size: int) -> tuple[bytes, str]: ...
+
+# Несколько вариантов размеров одного аватара
+def square_avatar_variants(
+    data: bytes, *, sizes: list[int]
+) -> list[tuple[int, bytes]]: ...
+
+# Масштабирование по длинной стороне (сохраняет пропорции)
+def normalize_image(data: bytes, *, max_px: int) -> tuple[bytes, str]: ...
+```
+
+### Утилиты
+
+```python
+# Канонический ключ snapshot'а версии
+def snapshot_key(*, skill_id: int | str, semver: str) -> str:
+    """Возвращает f'skills/{skill_id}/versions/{semver}.tar.gz'."""
+```
+
+### Тестирование
+
+```python
+# Фейк-хранилище в памяти
+class InMemoryObjectStorage:
+    async def put(self, key: str, data: bytes, content_type: str) -> None: ...
+    async def get(self, key: str) -> tuple[bytes, str]: ...
+    async def delete(self, key: str) -> None: ...
+
+# Генерировать тестовый PNG-файл
+def fake_image_bytes(width: int = 100, height: int = 100) -> bytes: ...
+```
+
+## Параметризация
+
+| Параметр | Значение | Примечание |
+|----------|----------|-----------|
+| MinIO endpoint | `host:port` (БЕЗ схемы) | dev: `minio:9000`, prod: `minio.example.com:9000` |
+| MinIO secure | `False` (dev), `True` (prod) | http vs https |
+| Avatar sizes | `[64, 128, 256]` (default) | Можно переопределить в клиенте |
+| Skill cover max px | `1200` (constant) | Не параметризуется |
+| JPEG quality | `85` (constant) | Не параметризуется |
+
+## Зависимости
+
+- **minio>=7.0** — S3 SDK
+- **anyio>=3.0** — async threading
+- **Pillow>=10.0** — image processing
+
+## Лицензия
+
+MIT

s_storagekit-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "s-storagekit"
+version = "0.1.0"
+description = "Объектное хранилище (ObjectStorage protocol + MinIO adapter + image normalization for Skillery)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Dmitry" }]
+# Зависимости: async-обёртка sync-SDK, image processing, S3-compatible storage.
+# 0 завязок на FastAPI/pydantic/SQLAlchemy — чистая логика.
+dependencies = [
+    "minio>=7.0",
+    "anyio>=3.0",
+    "Pillow>=10.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["storagekit"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["."]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "SIM", "RUF"]
+# RUF001/RUF002/RUF003 — кириллица в строках/докстрингах/комментах намеренная
+#   (русскоязычный код), ruff принимает её за «двусмысленную» латиницу.
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]

s_storagekit-0.1.0/storagekit/__init__.py

@@ -0,0 +1,72 @@
+"""storagekit — объектное хранилище для Skillery.
+
+Портабельное async-API для key→bytes операций с реализациями минарального
+протокола (MinIO) и вспомогательными утилитами нормализации изображений
+(Pillow). 0 завязок на FastAPI/pydantic — чистая логика.
+
+Основные компоненты:
+
+- **Протоколы:** `ObjectStorage`, `ISnapshotStorage` — минимальные async-интерфейсы.
+- **Реализация:** `MinioObjectStorage` — S3-compatible хранилище (prod/dev).
+- **Image-утилиты:** `normalize_image`, `square_avatar_variants`, `normalize_square_avatar`.
+- **Presigning:** `PresignedUrlGenerator`, `snapshot_key`.
+- **Тесты:** `InMemoryObjectStorage`, `fake_image_bytes`.
+
+Примеры использования:
+
+    # Инициализация
+    from storagekit import MinioObjectStorage
+    storage = MinioObjectStorage(
+        endpoint="minio:9000",
+        access_key="...",
+        secret_key="...",
+        bucket="my-bucket",
+    )
+
+    # Загрузка картинки
+    from storagekit import square_avatar_variants
+    variants = square_avatar_variants(raw_bytes, sizes=[64, 128, 256])
+    for size, blob in variants:
+        key = f"avatars/{uid}/{token}_{size}.jpg"
+        await storage.put(key, blob, "image/jpeg")
+
+    # Тестирование
+    from storagekit.testing import InMemoryObjectStorage, fake_image_bytes
+    storage = InMemoryObjectStorage()
+    raw = fake_image_bytes(100, 100)
+    variants = square_avatar_variants(raw, sizes=[64, 128])
+"""
+from __future__ import annotations
+
+from storagekit.base import ISnapshotStorage, ObjectNotFoundError, ObjectStorage
+from storagekit.images import (
+    ALLOWED_IMAGE_CONTENT_TYPES,
+    ValidationError,
+    normalize_image,
+    normalize_square_avatar,
+    square_avatar_variants,
+)
+from storagekit.minio_storage import MinioObjectStorage
+from storagekit.presign import PresignedUrlGenerator, snapshot_key
+from storagekit.testing import InMemoryObjectStorage, fake_image_bytes
+
+__all__ = [
+    # Протоколы и исключения
+    "ObjectStorage",
+    "ISnapshotStorage",
+    "ObjectNotFoundError",
+    # Реализация хранилища
+    "MinioObjectStorage",
+    # Image-обработка
+    "ValidationError",
+    "ALLOWED_IMAGE_CONTENT_TYPES",
+    "normalize_image",
+    "normalize_square_avatar",
+    "square_avatar_variants",
+    # Presigning
+    "PresignedUrlGenerator",
+    "snapshot_key",
+    # Тестовые утилиты
+    "InMemoryObjectStorage",
+    "fake_image_bytes",
+]

s_storagekit-0.1.0/storagekit/base.py

@@ -0,0 +1,43 @@
+"""Портокол объектного хранилища.
+
+`ObjectStorage` — минимальный async-протокол put/get/delete над key→bytes.
+Реализации: `MinioObjectStorage` (prod/dev, S3-совместимое MinIO) и
+`InMemoryObjectStorage` (тесты). Роуты зависят от протокола, не от MinIO.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+class ObjectNotFoundError(Exception):
+    """Объект с указанным key отсутствует в хранилище."""
+
+    def __init__(self, key: str) -> None:
+        super().__init__(f"object not found: {key}")
+        self.key = key
+
+
+@runtime_checkable
+class ObjectStorage(Protocol):
+    """Async key→bytes хранилище. Key — это «путь» объекта (напр.
+    ``avatars/42/ab12.jpg``); семантику ключей задаёт вызывающий код."""
+
+    async def put(self, key: str, data: bytes, content_type: str) -> None:
+        """Записать (или перезаписать) объект."""
+        ...
+
+    async def get(self, key: str) -> tuple[bytes, str]:
+        """Вернуть ``(data, content_type)``. Бросает ``ObjectNotFoundError``."""
+        ...
+
+    async def delete(self, key: str) -> None:
+        """Удалить объект. Отсутствие — не ошибка (idempotent)."""
+        ...
+
+
+class ISnapshotStorage(Protocol):
+    """Только запись (узкий подмножество ObjectStorage для snapshot-версий)."""
+
+    async def put(self, key: str, data: bytes, content_type: str) -> None:
+        """Записать snapshot."""
+        ...

s_storagekit-0.1.0/storagekit/images.py

@@ -0,0 +1,131 @@
+"""Image-обработка загрузок: нормализация аватара через Pillow.
+
+Чистые функции bytes→bytes — тривиально юнит-тестируются, не требуют MinIO.
+"""
+from __future__ import annotations
+
+import io
+
+from PIL import Image, UnidentifiedImageError
+
+# Pillow 10+ переименовал фильтры в Image.Resampling.*; для совместимости с
+# более ранними версиями используем getattr-fallback.
+_LANCZOS = getattr(Image, "Resampling", Image).LANCZOS
+
+
+class ValidationError(Exception):
+    """Ошибка валидации изображения."""
+
+    def __init__(self, message: str, *, details: dict | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+# Допустимые content-type для загружаемых картинок (аватары/скриншоты).
+ALLOWED_IMAGE_CONTENT_TYPES: frozenset[str] = frozenset(
+    {"image/jpeg", "image/png", "image/webp", "image/gif"}
+)
+
+
+def square_avatar_variants(
+    data: bytes, *, sizes: list[int]
+) -> list[tuple[int, bytes]]:
+    """Генерировать несколько JPEG-вариантов аватара разных размеров.
+
+    Алгоритм:
+    1. Открыть изображение через Pillow, конвертировать в RGB.
+    2. Center cover-crop до квадрата (min(w,h) × min(w,h)).
+    3. Ограничить мастер-сторону до max(sizes) — уменьшение без апскейла.
+    4. Для каждого размера из ``sizes``: масштабировать (shrink-only) →
+       JPEG quality 85.
+
+    Возвращает [(size, jpeg_bytes), ...] в порядке переданного ``sizes``.
+    Бросает ``ValidationError`` если ``data`` — не корректное изображение.
+    """
+    if not sizes:
+        return []
+    master_side = max(sizes)
+    try:
+        with Image.open(io.BytesIO(data)) as img:
+            rgb = img.convert("RGB")
+            width, height = rgb.size
+            # --- center cover-crop до квадрата ---
+            side = min(width, height)
+            left = (width - side) // 2
+            top = (height - side) // 2
+            cropped = rgb.crop((left, top, left + side, top + side))
+            # --- ограничить мастер до max(sizes) (shrink-only) ---
+            if side > master_side:
+                cropped = cropped.resize((master_side, master_side), _LANCZOS)
+                side = master_side
+            # --- генерировать каждый вариант ---
+            result: list[tuple[int, bytes]] = []
+            for sz in sizes:
+                # shrink-only: если мастер уже равен sz — не апскейлируем
+                resized = cropped.resize((sz, sz), _LANCZOS) if side != sz else cropped
+                out = io.BytesIO()
+                resized.save(out, format="JPEG", quality=85, optimize=True)
+                result.append((sz, out.getvalue()))
+            return result
+    except (UnidentifiedImageError, OSError) as exc:
+        raise ValidationError(
+            "Файл не является корректным изображением",
+            details={"reason": str(exc)},
+        ) from exc
+
+
+def normalize_square_avatar(data: bytes, *, size: int) -> tuple[bytes, str]:
+    """Привести картинку к квадрату ``size×size`` (center cover-crop) + JPEG.
+
+    Возвращает ``(jpeg_bytes, "image/jpeg")``. Это и есть «уменьшенная версия»
+    для аватара. Бросает ``ValidationError`` если bytes — не валидное
+    изображение (битый/не-image файл).
+    """
+    try:
+        with Image.open(io.BytesIO(data)) as img:
+            rgb = img.convert("RGB")
+            width, height = rgb.size
+            side = min(width, height)
+            left = (width - side) // 2
+            top = (height - side) // 2
+            cropped = rgb.crop((left, top, left + side, top + side))
+            if side != size:
+                cropped = cropped.resize((size, size), _LANCZOS)
+            out = io.BytesIO()
+            cropped.save(out, format="JPEG", quality=85, optimize=True)
+            return out.getvalue(), "image/jpeg"
+    except (UnidentifiedImageError, OSError) as exc:
+        raise ValidationError(
+            "Файл не является корректным изображением",
+            details={"reason": str(exc)},
+        ) from exc
+
+
+def normalize_image(data: bytes, *, max_px: int) -> tuple[bytes, str]:
+    """Привести картинку к JPEG, ужав до ``max_px`` по ДЛИННОЙ стороне с
+    сохранением пропорций (обложки skill'ов).
+
+    В отличие от ``normalize_square_avatar`` (квадрат + crop), здесь aspect
+    ratio сохраняется, а уменьшение происходит ТОЛЬКО если длинная сторона
+    больше ``max_px`` (апскейл не делаем — мелкая картинка остаётся как есть).
+    Возвращает ``(jpeg_bytes, "image/jpeg")``. Бросает ``ValidationError`` если
+    bytes — не валидное изображение.
+    """
+    try:
+        with Image.open(io.BytesIO(data)) as img:
+            rgb = img.convert("RGB")
+            width, height = rgb.size
+            longest = max(width, height)
+            if longest > max_px:
+                scale = max_px / longest
+                new_size = (max(1, round(width * scale)), max(1, round(height * scale)))
+                rgb = rgb.resize(new_size, _LANCZOS)
+            out = io.BytesIO()
+            rgb.save(out, format="JPEG", quality=85, optimize=True)
+            return out.getvalue(), "image/jpeg"
+    except (UnidentifiedImageError, OSError) as exc:
+        raise ValidationError(
+            "Файл не является корректным изображением",
+            details={"reason": str(exc)},
+        ) from exc

s_storagekit-0.1.0/storagekit/minio_storage.py

@@ -0,0 +1,94 @@
+"""MinioObjectStorage — S3-совместимое объектное хранилище на MinIO.
+
+SDK `minio` синхронный, поэтому каждый I/O-вызов уводим в threadpool через
+`anyio.to_thread.run_sync`, чтобы не блокировать event loop. Bucket создаётся
+лениво при первой записи (ensure-on-write) — не требует, чтобы MinIO был готов
+на момент старта.
+"""
+from __future__ import annotations
+
+import io
+
+import anyio
+from minio import Minio
+from minio.error import S3Error
+
+from storagekit.base import ObjectNotFoundError
+
+
+class MinioObjectStorage:
+    """Реализация `ObjectStorage` поверх MinIO.
+
+    `endpoint` — ``host:port`` БЕЗ схемы (схему задаёт `secure`). В dev
+    docker-compose это ``minio:9000`` (internal), `secure=False`.
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        access_key: str,
+        secret_key: str,
+        bucket: str,
+        secure: bool = False,
+    ) -> None:
+        self._client = Minio(
+            endpoint,
+            access_key=access_key,
+            secret_key=secret_key,
+            secure=secure,
+        )
+        self._bucket = bucket
+        self._bucket_ready = False
+
+    # ── sync helpers (выполняются в threadpool) ──
+    def _ensure_bucket(self) -> None:
+        if self._bucket_ready:
+            return
+        if not self._client.bucket_exists(self._bucket):
+            self._client.make_bucket(self._bucket)
+        self._bucket_ready = True
+
+    def _put_sync(self, key: str, data: bytes, content_type: str) -> None:
+        self._ensure_bucket()
+        self._client.put_object(
+            self._bucket,
+            key,
+            io.BytesIO(data),
+            length=len(data),
+            content_type=content_type,
+        )
+
+    def _get_sync(self, key: str) -> tuple[bytes, str]:
+        try:
+            resp = self._client.get_object(self._bucket, key)
+        except S3Error as exc:
+            if exc.code in {"NoSuchKey", "NoSuchBucket"}:
+                raise ObjectNotFoundError(key) from exc
+            raise
+        try:
+            data = resp.read()
+            content_type = resp.headers.get(
+                "Content-Type", "application/octet-stream"
+            )
+            return data, content_type
+        finally:
+            resp.close()
+            resp.release_conn()
+
+    def _delete_sync(self, key: str) -> None:
+        self._ensure_bucket()
+        self._client.remove_object(self._bucket, key)
+
+    # ── async API (ObjectStorage protocol) ──
+    async def put(self, key: str, data: bytes, content_type: str) -> None:
+        """Записать объект в MinIO через threadpool."""
+        await anyio.to_thread.run_sync(self._put_sync, key, data, content_type)
+
+    async def get(self, key: str) -> tuple[bytes, str]:
+        """Получить объект из MinIO через threadpool."""
+        return await anyio.to_thread.run_sync(self._get_sync, key)
+
+    async def delete(self, key: str) -> None:
+        """Удалить объект из MinIO через threadpool."""
+        await anyio.to_thread.run_sync(self._delete_sync, key)

s_storagekit-0.1.0/storagekit/presign.py

@@ -0,0 +1,62 @@
+"""Presigned URL генерация для MinIO.
+
+Позволяет клиентам получать прямые ссылки на объекты с TTL без auth.
+"""
+from __future__ import annotations
+
+import io
+from datetime import timedelta
+
+import anyio
+from minio import Minio
+from minio.error import S3Error
+
+from storagekit.base import ObjectNotFoundError
+
+
+def snapshot_key(*, skill_id: int | str, semver: str) -> str:
+    """Канонический ключ snapshot'а версии в object_storage.
+
+    Возвращает f'skills/{skill_id}/versions/{semver}.tar.gz'.
+
+    Примеры:
+        key = snapshot_key(skill_id=42, semver='1.0.0')
+        # → 'skills/42/versions/1.0.0.tar.gz'
+    """
+    return f"skills/{skill_id}/versions/{semver}.tar.gz"
+
+
+class PresignedUrlGenerator:
+    """Генератор presigned URL для MinIO объектов."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        access_key: str,
+        secret_key: str,
+        bucket: str,
+        secure: bool = False,
+    ) -> None:
+        self._client = Minio(
+            endpoint,
+            access_key=access_key,
+            secret_key=secret_key,
+            secure=secure,
+        )
+        self._bucket = bucket
+
+    def _generate_presigned_get_url_sync(
+        self, key: str, ttl_seconds: int = 3600
+    ) -> str:
+        """Сгенерировать presigned GET-URL для объекта (sync версия)."""
+        ttl = timedelta(seconds=ttl_seconds)
+        return self._client.get_presigned_object_url("GET", self._bucket, key, ttl)
+
+    async def generate_presigned_get_url(
+        self, key: str, ttl_seconds: int = 3600
+    ) -> str:
+        """Сгенерировать presigned GET-URL для объекта (async версия)."""
+        return await anyio.to_thread.run_sync(
+            self._generate_presigned_get_url_sync, key, ttl_seconds
+        )

s_storagekit-0.1.0/storagekit/testing.py

@@ -0,0 +1,44 @@
+"""Тестовые mock-реализации ObjectStorage протокола и утилиты генерации данных."""
+from __future__ import annotations
+
+import io
+
+from PIL import Image
+
+from storagekit.base import ObjectNotFoundError
+
+
+class InMemoryObjectStorage:
+    """Фейк-хранилище в памяти для unit-тестов.
+
+    Имитирует ObjectStorage protocol через dict в памяти.
+    Синхронное, но async-методы для совместимости с протоколом.
+    """
+
+    def __init__(self) -> None:
+        self._storage: dict[str, tuple[bytes, str]] = {}
+
+    async def put(self, key: str, data: bytes, content_type: str) -> None:
+        """Записать объект в память."""
+        self._storage[key] = (data, content_type)
+
+    async def get(self, key: str) -> tuple[bytes, str]:
+        """Получить объект из памяти."""
+        if key not in self._storage:
+            raise ObjectNotFoundError(key)
+        return self._storage[key]
+
+    async def delete(self, key: str) -> None:
+        """Удалить объект из памяти (idempotent)."""
+        self._storage.pop(key, None)
+
+
+def fake_image_bytes(width: int = 100, height: int = 100) -> bytes:
+    """Сгенерировать валидное PNG-изображение для тестов.
+
+    Возвращает bytes PNG-изображения указанных размеров (сплошной серый).
+    """
+    img = Image.new("RGB", (width, height), color=(128, 128, 128))
+    out = io.BytesIO()
+    img.save(out, format="PNG")
+    return out.getvalue()

s_storagekit-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Тесты модуля storagekit."""

s_storagekit-0.1.0/tests/test_base.py

@@ -0,0 +1,76 @@
+"""Тесты базового протокола ObjectStorage."""
+from __future__ import annotations
+
+import pytest
+
+from storagekit import InMemoryObjectStorage, ObjectNotFoundError
+
+
+@pytest.mark.asyncio
+async def test_in_memory_put_get_delete() -> None:
+    """InMemoryObjectStorage: put → get → delete."""
+    storage = InMemoryObjectStorage()
+
+    # Запись
+    await storage.put("test-key", b"hello world", "text/plain")
+
+    # Чтение
+    data, ct = await storage.get("test-key")
+    assert data == b"hello world"
+    assert ct == "text/plain"
+
+    # Удаление
+    await storage.delete("test-key")
+
+    # Чтение после удаления должно выбросить ошибку
+    with pytest.raises(ObjectNotFoundError) as exc_info:
+        await storage.get("test-key")
+    assert exc_info.value.key == "test-key"
+
+
+@pytest.mark.asyncio
+async def test_in_memory_object_not_found() -> None:
+    """get(unknown_key) → ObjectNotFoundError с .key атрибутом."""
+    storage = InMemoryObjectStorage()
+
+    with pytest.raises(ObjectNotFoundError) as exc_info:
+        await storage.get("nonexistent")
+
+    assert exc_info.value.key == "nonexistent"
+    assert "nonexistent" in str(exc_info.value)
+
+
+@pytest.mark.asyncio
+async def test_in_memory_delete_idempotent() -> None:
+    """delete() on nonexistent key — не ошибка."""
+    storage = InMemoryObjectStorage()
+
+    # delete несуществующего ключа не должен выбросить ошибку
+    await storage.delete("not-created")
+
+
+@pytest.mark.asyncio
+async def test_in_memory_overwrite() -> None:
+    """put() перезаписывает существующий ключ."""
+    storage = InMemoryObjectStorage()
+
+    await storage.put("key", b"first", "text/plain")
+    await storage.put("key", b"second", "text/plain")
+
+    data, _ = await storage.get("key")
+    assert data == b"second"
+
+
+@pytest.mark.asyncio
+async def test_in_memory_different_content_types() -> None:
+    """Разные content-type для разных ключей."""
+    storage = InMemoryObjectStorage()
+
+    await storage.put("image.jpg", b"jpeg", "image/jpeg")
+    await storage.put("image.png", b"png", "image/png")
+
+    _, ct1 = await storage.get("image.jpg")
+    _, ct2 = await storage.get("image.png")
+
+    assert ct1 == "image/jpeg"
+    assert ct2 == "image/png"

s_storagekit-0.1.0/tests/test_images.py

@@ -0,0 +1,175 @@
+"""Тесты обработки изображений."""
+from __future__ import annotations
+
+import io
+
+import pytest
+from PIL import Image
+
+from storagekit import (
+    ValidationError,
+    fake_image_bytes,
+    normalize_image,
+    normalize_square_avatar,
+    square_avatar_variants,
+)
+
+
+def test_normalize_square_avatar() -> None:
+    """normalize_square_avatar: PNG → JPEG квадрат."""
+    raw = fake_image_bytes(width=200, height=150)
+    jpeg_bytes, ct = normalize_square_avatar(raw, size=256)
+
+    assert ct == "image/jpeg"
+    assert len(jpeg_bytes) > 0
+
+    # Проверить, что результат это корректный JPEG
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    assert img.size == (256, 256)
+    assert img.format == "JPEG"
+
+
+def test_normalize_square_avatar_already_square() -> None:
+    """normalize_square_avatar: квадратное изображение."""
+    raw = fake_image_bytes(width=100, height=100)
+    jpeg_bytes, ct = normalize_square_avatar(raw, size=100)
+
+    assert ct == "image/jpeg"
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    assert img.size == (100, 100)
+
+
+def test_normalize_square_avatar_landscape() -> None:
+    """normalize_square_avatar: ландшафтное изображение → crop."""
+    raw = fake_image_bytes(width=400, height=200)
+    jpeg_bytes, ct = normalize_square_avatar(raw, size=256)
+
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    assert img.size == (256, 256)  # квадрат
+
+
+def test_normalize_square_avatar_portrait() -> None:
+    """normalize_square_avatar: портретное изображение → crop."""
+    raw = fake_image_bytes(width=200, height=400)
+    jpeg_bytes, ct = normalize_square_avatar(raw, size=256)
+
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    assert img.size == (256, 256)
+
+
+def test_normalize_square_avatar_invalid() -> None:
+    """normalize_square_avatar(garbage) → ValidationError."""
+    with pytest.raises(ValidationError) as exc_info:
+        normalize_square_avatar(b"not an image", size=256)
+
+    assert "корректным изображением" in exc_info.value.message
+
+
+def test_square_avatar_variants() -> None:
+    """square_avatar_variants: несколько размеров."""
+    raw = fake_image_bytes(width=200, height=150)
+    variants = square_avatar_variants(raw, sizes=[64, 128, 256])
+
+    assert len(variants) == 3
+    assert variants[0][0] == 64
+    assert variants[1][0] == 128
+    assert variants[2][0] == 256
+
+    # Проверить каждый вариант
+    for size, jpeg_bytes in variants:
+        assert len(jpeg_bytes) > 0
+        img = Image.open(io.BytesIO(jpeg_bytes))
+        assert img.size == (size, size)
+        assert img.format == "JPEG"
+
+
+def test_square_avatar_variants_empty_sizes() -> None:
+    """square_avatar_variants: пустой список размеров."""
+    raw = fake_image_bytes(width=100, height=100)
+    variants = square_avatar_variants(raw, sizes=[])
+
+    assert variants == []
+
+
+def test_square_avatar_variants_single_size() -> None:
+    """square_avatar_variants: один размер."""
+    raw = fake_image_bytes(width=100, height=100)
+    variants = square_avatar_variants(raw, sizes=[128])
+
+    assert len(variants) == 1
+    assert variants[0][0] == 128
+
+
+def test_square_avatar_variants_invalid() -> None:
+    """square_avatar_variants(garbage) → ValidationError."""
+    with pytest.raises(ValidationError):
+        square_avatar_variants(b"not an image", sizes=[64, 128])
+
+
+def test_normalize_image_landscape() -> None:
+    """normalize_image: ландшафтное изображение уменьшается по длинной стороне."""
+    raw = fake_image_bytes(width=2000, height=1000)
+    jpeg_bytes, ct = normalize_image(raw, max_px=1200)
+
+    assert ct == "image/jpeg"
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    # ширина (длинная) должна быть уменьшена до 1200
+    assert img.width == 1200
+    # высота должна быть пропорционально уменьшена
+    assert img.height == 600
+
+
+def test_normalize_image_portrait() -> None:
+    """normalize_image: портретное изображение."""
+    raw = fake_image_bytes(width=1000, height=2000)
+    jpeg_bytes, ct = normalize_image(raw, max_px=1200)
+
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    # высота (длинная) должна быть 1200
+    assert img.height == 1200
+    # ширина должна быть пропорциональна
+    assert img.width == 600
+
+
+def test_normalize_image_no_downscale() -> None:
+    """normalize_image: маленькое изображение не апскейлируется."""
+    raw = fake_image_bytes(width=200, height=100)
+    jpeg_bytes, ct = normalize_image(raw, max_px=1200)
+
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    # Размер не должен измениться (нет апскейла)
+    assert img.width == 200
+    assert img.height == 100
+
+
+def test_normalize_image_square() -> None:
+    """normalize_image: квадратное изображение."""
+    raw = fake_image_bytes(width=1000, height=1000)
+    jpeg_bytes, ct = normalize_image(raw, max_px=500)
+
+    img = Image.open(io.BytesIO(jpeg_bytes))
+    assert img.width == 500
+    assert img.height == 500
+
+
+def test_normalize_image_invalid() -> None:
+    """normalize_image(garbage) → ValidationError."""
+    with pytest.raises(ValidationError):
+        normalize_image(b"not an image", max_px=1200)
+
+
+def test_fake_image_bytes_default() -> None:
+    """fake_image_bytes: генерирует корректный PNG."""
+    raw = fake_image_bytes()
+    img = Image.open(io.BytesIO(raw))
+
+    assert img.size == (100, 100)
+    assert img.format == "PNG"
+
+
+def test_fake_image_bytes_custom_size() -> None:
+    """fake_image_bytes: пользовательские размеры."""
+    raw = fake_image_bytes(width=500, height=300)
+    img = Image.open(io.BytesIO(raw))
+
+    assert img.size == (500, 300)

s_storagekit-0.1.0/tests/test_presign.py

@@ -0,0 +1,23 @@
+"""Тесты presigned URL и утилит."""
+from __future__ import annotations
+
+from storagekit import snapshot_key
+
+
+def test_snapshot_key_int_skill_id() -> None:
+    """snapshot_key: целочисленный skill_id."""
+    key = snapshot_key(skill_id=42, semver="1.0.0")
+    assert key == "skills/42/versions/1.0.0.tar.gz"
+
+
+def test_snapshot_key_str_skill_id() -> None:
+    """snapshot_key: строковый skill_id."""
+    key = snapshot_key(skill_id="my-skill", semver="1.0.0")
+    assert key == "skills/my-skill/versions/1.0.0.tar.gz"
+
+
+def test_snapshot_key_various_semvers() -> None:
+    """snapshot_key: различные версии."""
+    assert snapshot_key(skill_id=1, semver="0.1.0") == "skills/1/versions/0.1.0.tar.gz"
+    assert snapshot_key(skill_id=1, semver="2.5.10") == "skills/1/versions/2.5.10.tar.gz"
+    assert snapshot_key(skill_id=1, semver="1.0.0-rc.1") == "skills/1/versions/1.0.0-rc.1.tar.gz"