s-storagekit 0.1.0__py3-none-any.whl

s_storagekit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+storagekit/__init__.py,sha256=GAOkkvCu0mL70MsNij7bpKp7UEhO76GZ6-LWe6t00d0,2789
+storagekit/base.py,sha256=x4TBVEPrjQQy9_gWW5q89euaoDVJv79rso25NP07YSg,1731
+storagekit/images.py,sha256=NPNxEjvAhZW3KWfj6wLebfaHGj0TjmReAFm2npqfX1s,6287
+storagekit/minio_storage.py,sha256=YfVaL7hSSV9izYm4kUNUDA3A3-1C8EXixOt2Cspcns4,3288
+storagekit/presign.py,sha256=kegTwCWvOSlNKU-mxwvfcxLpVpc4PiiXcIYsveair_c,1928
+storagekit/testing.py,sha256=KsRC0bLcl2E5v_ABcJztkE3lBV7NCejvu80AwEj5sJU,1676
+s_storagekit-0.1.0.dist-info/METADATA,sha256=0aDLlHIyolRxBZRnNxizbxBplglKdoGsSEx_pB27UQU,6596
+s_storagekit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+s_storagekit-0.1.0.dist-info/RECORD,,

s_storagekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

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",
+]

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."""
+        ...

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

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)

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
+        )

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()