opengater-storage-client

Тонкий async-клиент к сервису opengater-storage — инкапсулирует POST /uploads (получение presigned-PUT URL) и DELETE /objects (удаление файла). Аутентификация через заголовок X-API-Key.

По структуре аналогичен opengater-globalauth-client: без FastAPI, без брокера, только httpx + pydantic.

Установка

После публикации на PyPI:

uv add opengater-storage-client

На время разработки — git-зависимость на тег:

uv add "opengater-storage-client @ git+https://gitlab.com/toltol1992toltol/opengater-storage-client.git@v0.1.0"

Быстрый старт

from opengater_storage_client import StorageClient

storage = StorageClient(base_url="http://opengater-storage:8000", api_key="...")

# Создать загрузку — получить presigned-PUT URL
res = await storage.create_upload("image/png", prefix="news/articles")
# res.upload_url — PUT сюда файл напрямую из браузера/клиента
# res.key        — ключ объекта в хранилище
# res.public_url — публичный URL после загрузки

# Удалить объект (по public_url или по key)
await storage.delete_object(public_url=res.public_url)
# или
await storage.delete_object(key=res.key)

await storage.aclose()

API

StorageClient(base_url, api_key, timeout=30.0)

create_upload(content_type, prefix="") -> UploadResult

Отправляет POST /uploads. Возвращает UploadResult с полями:

upload_file(content, filename, content_type, prefix="") -> StoredObject

Отправляет POST /uploads/file multipart-запросом. Файл загружается на сервер напрямую — без промежуточного presigned-URL. Возвращает StoredObject:

res = await storage.upload_file(content=b"...", filename="pic.png", content_type="image/png", prefix="news/articles")
# res.key / res.public_url  (StoredObject — без upload_url)

delete_object(public_url=None, key=None) -> None

Отправляет DELETE /objects. Нужно передать хотя бы один из параметров; если не передан ни один — поднимает ValueError.

Важно: при удалении по public_url сервис сам срезает URL до ключа по своей базе. Передавать key надёжнее, если он у вас есть.

aclose() -> None

Закрывает внутренний httpx.AsyncClient. Вызывайте по завершении работы (или используйте клиент через async with).

Ошибки

Все ошибки — наследники StorageError. Библиотека честно поднимает их — best-effort-политику (например, глушить удаление чужого URL) реализует потребитель.

Атрибуты .status_code (int | None) и .detail (str | None) доступны на всех экземплярах.

from opengater_storage_client import StorageClient, StorageAuthError, StorageUnavailable

try:
    res = await storage.create_upload("image/jpeg")
except StorageAuthError as e:
    # неверный ключ
    raise
except StorageUnavailable as e:
    # сервис недоступен или таймаут — логируйте e.detail
    raise