tempest-fastapi-sdk 0.63.0__tar.gz → 0.64.0__tar.gz

{tempest_fastapi_sdk-0.63.0 → tempest_fastapi_sdk-0.64.0}/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.64.0] — 2026-06-21
+
+### Added
+
+- **`StoredFileServiceMixin[Model]`** — a service mixin that encodes the
+  single-key stored-file flow once, parameterized by field name:
+  - `set_file(ref, file, *, field, subdir=..., filename=..., keep_original_name=...)`
+    resolves the entity (detach-safe), uploads the new file and deletes the
+    old one via `UploadUtils.replace` (new written before old deleted),
+    writes the key back and commits.
+  - `clear_file(ref, *, field)` deletes the object and nulls the field
+    (no-op, no commit, when the field is already empty).
+  - `file_url(key, *, expires=...)` returns a presigned download URL, or
+    `None` for an empty key.
+
+  Removes the ~13-line boilerplate every service reimplements for avatars,
+  banners, covers and attachments. Reads its `upload_utils` and `storage`
+  collaborators off `self`, so the owning service keeps configuration (size
+  limits, allowed types, bucket). Covers the common "one key field →
+  presigned URL" case; resize/thumbnail pipelines, multi-variant assets and
+  galleries are out of scope (compose `UploadUtils` directly). See the
+  **Arquivo no serviço (mixin)** recipe.
+- **`SupportsUpload`** and **`SupportsPresign`** — structural-typing
+  protocols describing the collaborators `StoredFileServiceMixin` needs
+  (satisfied by `UploadUtils` and `AsyncMinIOClient`), so importing the
+  mixin never pulls the optional `[upload]` / `[minio]` extras.
+
 ## [0.63.0] — 2026-06-21
 
 ### Changed

{tempest_fastapi_sdk-0.63.0 → tempest_fastapi_sdk-0.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.63.0
+Version: 0.64.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk

tempest_fastapi_sdk-0.64.0/docs/recipes/stored-files.en.md

@@ -0,0 +1,129 @@
+# File on the service — `StoredFileServiceMixin`
+
+An entity almost always carries **one** storage key: the user's avatar, an
+event banner, a product cover, an attachment. And every service that owns one
+rewrites the same dance by hand:
+
+1. resolve the entity,
+2. upload the new file and delete the old one,
+3. write the new key onto the model,
+4. `commit`,
+5. hand out a temporary download URL.
+
+`StoredFileServiceMixin` does this flow **once**, parameterized by the
+**field name** — so a single service can manage several file fields without
+duplication. It builds on top of [`UploadUtils`](uploads.md) (upload +
+validation) and [`AsyncMinIOClient`](storage.md) (presigned URL); it needs the
+`[upload]` and `[minio]` extras.
+
+!!! info "Scope: the common case"
+    Covers **one key per field → presigned URL**. Thumbnails, variants
+    (S/M/L), public/CDN buckets and galleries (one-to-many) are out of scope —
+    compose `UploadUtils` directly for those.
+
+## Mixing it into your service
+
+The mixin builds nothing: it reads two collaborators off `self` —
+`upload_utils` and `storage`. The service stays in charge of configuration
+(size, allowed types, bucket):
+
+```python
+from tempest_fastapi_sdk import (
+    AsyncMinIOClient,
+    BaseService,
+    StoredFileServiceMixin,
+    UploadUtils,
+)
+
+from src.db.models import UserModel
+from src.db.repositories import UserRepository
+from src.schemas import UserResponseSchema
+
+
+class UserService(
+    BaseService[UserRepository, UserResponseSchema],
+    StoredFileServiceMixin[UserModel],
+):
+    def __init__(
+        self,
+        repository: UserRepository,
+        storage: AsyncMinIOClient,
+        upload_utils: UploadUtils,
+    ) -> None:
+        super().__init__(repository)
+        self.storage = storage
+        self.upload_utils = upload_utils
+```
+
+Base order matters: `BaseService` brings the `repository`; the mixin only
+adds the file methods on top.
+
+## Swap the file — `set_file`
+
+```python
+async def update_profile_picture(
+    self, user: UUID | UserModel, image: UploadFile
+) -> UserResponseSchema:
+    """Upload the new picture, delete the old one, return the profile + URL."""
+    updated = await self.set_file(
+        user, image, field="profile_picture", subdir="profiles"
+    )
+    response = await self._map_to_response(updated)
+    response.profile_picture_url = await self.file_url(updated.profile_picture)
+    return response
+```
+
+That's it. Against the ~13 hand-written lines, `set_file` resolves the
+entity, calls `replace` (writes the new file **before** deleting the old),
+stores the key and commits — in one step.
+
+!!! tip "Safe with the authenticated user"
+    `set_file` re-resolves the entity on the request session via
+    `repository.resolve()`. If you pass the `UserModel` from
+    `get_current_user` (which on mis-wired apps used to be *detached*),
+    `resolve` re-attaches it before the write — no
+    `InvalidRequestError: Instance is not persistent within this Session`.
+
+## Serve the URL — `file_url`
+
+```python
+url = await self.file_url(user.profile_picture)            # 1h lifetime
+url = await self.file_url(user.profile_picture, expires=timedelta(minutes=5))
+```
+
+Returns `None` when the key is empty, so you can feed the result straight into
+a response-schema field without an `if`:
+
+```python
+response.profile_picture_url = await self.file_url(updated.profile_picture)
+```
+
+## Remove the file — `clear_file`
+
+```python
+updated = await self.clear_file(user, field="profile_picture")
+```
+
+Deletes the storage object and nulls the field. When the field is already
+empty it is a **no-op**: the entity is returned without a `commit` and without
+touching storage.
+
+## Several fields? Same mixin
+
+`field=` is just an argument — one service handles as many fields as you like:
+
+```python
+await self.set_file(event, cover, field="cover_image", subdir="events/covers")
+await self.set_file(event, banner, field="banner_image", subdir="events/banners")
+```
+
+## Recap
+
+- Mix `StoredFileServiceMixin[Model]` into the service and expose
+  `upload_utils` + `storage`.
+- `set_file(ref, file, *, field, subdir=...)` → upload, swap old, persist.
+  Detach-safe.
+- `file_url(key, *, expires=...)` → presigned URL or `None`.
+- `clear_file(ref, *, field)` → delete + null (no-op when already empty).
+- Common case (one key + presigned). For resize/variants/gallery, use
+  [`UploadUtils`](uploads.md) directly.

tempest_fastapi_sdk-0.64.0/docs/recipes/stored-files.md

@@ -0,0 +1,128 @@
+# Arquivo no serviço — `StoredFileServiceMixin`
+
+Uma entidade quase sempre carrega **uma** chave de storage: o avatar do
+usuário, o banner de um evento, a capa de um produto, um anexo. E todo
+serviço que cuida disso reescreve a mesma dança na mão:
+
+1. resolver a entidade,
+2. subir o arquivo novo e apagar o antigo,
+3. gravar a chave nova no model,
+4. dar `commit`,
+5. devolver uma URL temporária de download.
+
+O `StoredFileServiceMixin` faz esse fluxo **uma vez**, parametrizado pelo
+**nome do campo** — então um mesmo serviço cuida de vários campos de arquivo
+sem repetição. Ele monta por cima do [`UploadUtils`](uploads.md) (upload +
+validação) e do [`AsyncMinIOClient`](storage.md) (presigned URL); requer os
+extras `[upload]` e `[minio]`.
+
+!!! info "Escopo: o caso comum"
+    Cobre **uma chave por campo → URL presigned**. Thumbnails, variantes
+    (S/M/L), bucket público/CDN e galerias (um-para-muitos) ficam de fora —
+    pra esses, componha o `UploadUtils` direto.
+
+## Misturando no seu serviço
+
+O mixin não constrói nada: ele lê dois colaboradores de `self` —
+`upload_utils` e `storage`. Quem mistura continua dono da configuração
+(tamanho, tipos aceitos, bucket):
+
+```python
+from tempest_fastapi_sdk import (
+    AsyncMinIOClient,
+    BaseService,
+    StoredFileServiceMixin,
+    UploadUtils,
+)
+
+from src.db.models import UserModel
+from src.db.repositories import UserRepository
+from src.schemas import UserResponseSchema
+
+
+class UserService(
+    BaseService[UserRepository, UserResponseSchema],
+    StoredFileServiceMixin[UserModel],
+):
+    def __init__(
+        self,
+        repository: UserRepository,
+        storage: AsyncMinIOClient,
+        upload_utils: UploadUtils,
+    ) -> None:
+        super().__init__(repository)
+        self.storage = storage
+        self.upload_utils = upload_utils
+```
+
+A ordem das bases importa: `BaseService` traz o `repository`; o mixin só
+adiciona os métodos de arquivo por cima.
+
+## Trocar o arquivo — `set_file`
+
+```python
+async def update_profile_picture(
+    self, user: UUID | UserModel, image: UploadFile
+) -> UserResponseSchema:
+    """Sobe a foto nova, apaga a antiga e devolve o perfil com a URL."""
+    updated = await self.set_file(
+        user, image, field="profile_picture", subdir="profiles"
+    )
+    response = await self._map_to_response(updated)
+    response.profile_picture_url = await self.file_url(updated.profile_picture)
+    return response
+```
+
+Foi isso. Comparado às ~13 linhas manuais, o `set_file` resolve a entidade,
+chama `replace` (grava a nova **antes** de apagar a antiga), grava a chave e
+dá `commit` — tudo num passo.
+
+!!! tip "Seguro com o usuário autenticado"
+    O `set_file` re-resolve a entidade na sessão do request via
+    `repository.resolve()`. Se você passar o `UserModel` que veio de
+    `get_current_user` (que em apps mal-fiados vinha *detached*), o `resolve`
+    o reanexa antes da escrita — sem o
+    `InvalidRequestError: Instance is not persistent within this Session`.
+
+## Servir a URL — `file_url`
+
+```python
+url = await self.file_url(user.profile_picture)            # 1h de validade
+url = await self.file_url(user.profile_picture, expires=timedelta(minutes=5))
+```
+
+Devolve `None` quando a chave é vazia, então você pode jogar o resultado
+direto num campo do schema de resposta sem `if`:
+
+```python
+response.profile_picture_url = await self.file_url(updated.profile_picture)
+```
+
+## Remover o arquivo — `clear_file`
+
+```python
+updated = await self.clear_file(user, field="profile_picture")
+```
+
+Apaga o objeto do storage e zera o campo. Quando o campo já está vazio, é
+um **no-op**: a entidade volta sem `commit` e sem chamar o storage.
+
+## Vários campos? Mesmo mixin
+
+`field=` é só um argumento — o mesmo serviço cuida de quantos campos quiser:
+
+```python
+await self.set_file(event, cover, field="cover_image", subdir="events/covers")
+await self.set_file(event, banner, field="banner_image", subdir="events/banners")
+```
+
+## Recapitulando
+
+- Misture `StoredFileServiceMixin[Model]` no serviço e exponha `upload_utils`
+  + `storage`.
+- `set_file(ref, file, *, field, subdir=...)` → sobe, troca a antiga,
+  persiste. Detach-safe.
+- `file_url(key, *, expires=...)` → URL presigned ou `None`.
+- `clear_file(ref, *, field)` → apaga + zera (no-op se já vazio).
+- Caso comum (uma chave + presigned). Pra resize/variantes/galeria, use o
+  [`UploadUtils`](uploads.md) direto.

{tempest_fastapi_sdk-0.63.0 → tempest_fastapi_sdk-0.64.0}/docs/reference.md

@@ -68,6 +68,7 @@ Gerada automaticamente a partir das docstrings do SDK via [`mkdocstrings`](https
 ## Services & Controllers
 
 ::: tempest_fastapi_sdk.services.base.BaseService
+::: tempest_fastapi_sdk.services.file_mixin.StoredFileServiceMixin
 ::: tempest_fastapi_sdk.controllers.base.BaseController
 
 ---

{tempest_fastapi_sdk-0.63.0 → tempest_fastapi_sdk-0.64.0}/mkdocs.yml

@@ -220,6 +220,7 @@ nav:
       - "Observabilidade (tracing)": recipes/observability.md
       - Storage (MinIO/S3): recipes/storage.md
       - Uploads (backends): recipes/uploads.md
+      - "Arquivo no serviço (mixin)": recipes/stored-files.md
       - Downloads: recipes/downloads.md
       - Idempotência: recipes/idempotency.md
       - Sync offline-first (delta): recipes/offline-sync.md

{tempest_fastapi_sdk-0.63.0 → tempest_fastapi_sdk-0.64.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.63.0"
+version = "0.64.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.63.0 → tempest_fastapi_sdk-0.64.0}/tempest_fastapi_sdk/__init__.py

@@ -180,7 +180,12 @@ from tempest_fastapi_sdk.schemas import (
     decode_cursor,
     encode_cursor,
 )
-from tempest_fastapi_sdk.services import BaseService
+from tempest_fastapi_sdk.services import (
+    BaseService,
+    StoredFileServiceMixin,
+    SupportsPresign,
+    SupportsUpload,
+)
 from tempest_fastapi_sdk.sessions import (
     MemorySessionStore,
     RedisSessionStore,
@@ -301,7 +306,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.63.0"
+__version__: str = "0.64.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -462,6 +467,9 @@ __all__: list[str] = [
     "SlowQueryLogger",
     "SoftDeleteMixin",
     "StateBR",
+    "StoredFileServiceMixin",
+    "SupportsPresign",
+    "SupportsUpload",
     "SyncFilterSchema",
     "SyncPaginationSchema",
     "SystemMetrics",

tempest_fastapi_sdk-0.64.0/tempest_fastapi_sdk/services/__init__.py

@@ -0,0 +1,15 @@
+"""Business-logic layer base classes."""
+
+from tempest_fastapi_sdk.services.base import BaseService
+from tempest_fastapi_sdk.services.file_mixin import (
+    StoredFileServiceMixin,
+    SupportsPresign,
+    SupportsUpload,
+)
+
+__all__: list[str] = [
+    "BaseService",
+    "StoredFileServiceMixin",
+    "SupportsPresign",
+    "SupportsUpload",
+]

tempest_fastapi_sdk-0.64.0/tempest_fastapi_sdk/services/file_mixin.py

@@ -0,0 +1,221 @@
+"""Reusable service mixin for single-key stored-file fields.
+
+A great many entities carry exactly one object-storage key — an avatar,
+a banner, a cover, a document — and every service that owns one rewrites
+the same orchestration by hand:
+
+1. resolve the entity (detach-safe),
+2. upload the new file and delete the one it replaces,
+3. write the new key back onto the model,
+4. commit, and
+5. hand out a presigned download URL.
+
+:class:`StoredFileServiceMixin` encodes that flow once, parameterized by
+the **field name**, so a single service can manage several file fields
+without duplication. It deliberately covers only the common
+"one key column → presigned URL" case; resize/thumbnail pipelines,
+multi-variant assets and gallery (one-to-many) uploads are out of scope —
+compose :class:`UploadUtils` directly for those.
+
+The mixin is storage-agnostic by structural typing: it reads two
+collaborators off ``self`` — ``upload_utils`` and ``storage`` — described
+by the :class:`SupportsUpload` and :class:`SupportsPresign` protocols, so
+importing it never pulls the optional ``[upload]`` / ``[minio]`` extras.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar
+from uuid import UUID
+
+from tempest_fastapi_sdk.db.model import BaseModel
+
+if TYPE_CHECKING:
+    from fastapi import UploadFile
+
+    from tempest_fastapi_sdk.db.repository import BaseRepository
+
+ModelType = TypeVar("ModelType", bound=BaseModel)
+
+# One hour matches AsyncMinIOClient.presigned_get_url's own default.
+_DEFAULT_URL_TTL = timedelta(hours=1)
+
+
+class SupportsUpload(Protocol):
+    """Structural type for the upload helper the mixin needs.
+
+    Satisfied by :class:`tempest_fastapi_sdk.UploadUtils`.
+    """
+
+    async def replace(
+        self,
+        old_key: Path | str | None,
+        file: UploadFile,
+        *,
+        subdir: str = ...,
+        filename: str | None = ...,
+        keep_original_name: bool = ...,
+    ) -> Path:
+        """Persist ``file`` and delete the object at ``old_key``."""
+        ...
+
+    async def delete(self, key: Path | str) -> bool:
+        """Delete the object at ``key``; return whether it existed."""
+        ...
+
+
+class SupportsPresign(Protocol):
+    """Structural type for the storage client the mixin needs.
+
+    Satisfied by :class:`tempest_fastapi_sdk.AsyncMinIOClient`.
+    """
+
+    async def presigned_get_url(
+        self,
+        key: str,
+        *,
+        expires: timedelta = ...,
+    ) -> str:
+        """Return a temporary download URL for ``key``."""
+        ...
+
+
+class StoredFileServiceMixin(Generic[ModelType]):
+    """Manage a single object-storage key field on a service's model.
+
+    Mix into a service that already owns a ``repository`` (e.g. a
+    :class:`tempest_fastapi_sdk.BaseService` subclass) and exposes an
+    ``upload_utils`` and a ``storage`` collaborator::
+
+        class UserService(
+            BaseService[UserRepository, UserResponseSchema],
+            StoredFileServiceMixin[UserModel],
+        ):
+            def __init__(self, repository, storage, upload_utils):
+                super().__init__(repository)
+                self.storage = storage
+                self.upload_utils = upload_utils
+
+        user = await service.set_file(
+            user, image, field="profile_picture", subdir="profiles"
+        )
+        url = await service.file_url(user.profile_picture)
+
+    The mixin does not construct its collaborators — it reads them off
+    ``self`` so the owning service stays in charge of configuration
+    (size limits, allowed types, bucket).
+
+    Generic parameters:
+        ModelType: The ORM model whose field is managed.
+
+    Attributes:
+        repository (BaseRepository[ModelType]): Supplied by the service.
+        upload_utils (SupportsUpload): Supplied by the service.
+        storage (SupportsPresign): Supplied by the service.
+    """
+
+    repository: BaseRepository[ModelType]
+    upload_utils: SupportsUpload
+    storage: SupportsPresign
+
+    async def set_file(
+        self,
+        ref: UUID | ModelType,
+        file: UploadFile,
+        *,
+        field: str,
+        subdir: str = "",
+        filename: str | None = None,
+        keep_original_name: bool = False,
+    ) -> ModelType:
+        """Upload ``file`` and store its key on ``field``, replacing any old one.
+
+        The new object is written **before** the old one is deleted (via
+        :meth:`SupportsUpload.replace`), so a failed upload leaves the
+        existing file untouched. The entity is re-resolved on the
+        repository's session first, so a detached instance (e.g. the
+        authenticated user) is safely re-attached before the write.
+
+        Args:
+            ref (UUID | ModelType): The entity to update, by id or instance.
+            file (UploadFile): The uploaded file.
+            field (str): Name of the model attribute holding the storage key.
+            subdir (str): Optional key prefix / sub-directory.
+            filename (str | None): Explicit final filename. When omitted the
+                upload helper derives one.
+            keep_original_name (bool): Preserve the upload's original
+                filename when ``filename`` is not given.
+
+        Returns:
+            ModelType: The persisted entity with the new key on ``field``.
+
+        Raises:
+            AppException: ``repository.not_found_exception`` when ``ref`` is
+                an id with no matching row.
+        """
+        entity = await self.repository.resolve(ref)
+        old_key: Any = getattr(entity, field)
+        new_key = await self.upload_utils.replace(
+            old_key,
+            file,
+            subdir=subdir,
+            filename=filename,
+            keep_original_name=keep_original_name,
+        )
+        setattr(entity, field, str(new_key))
+        return await self.repository.update(entity)
+
+    async def clear_file(
+        self,
+        ref: UUID | ModelType,
+        *,
+        field: str,
+    ) -> ModelType:
+        """Delete the stored object (if any) and null ``field``.
+
+        A no-op write is avoided when the field is already empty: the
+        resolved entity is returned without a commit.
+
+        Args:
+            ref (UUID | ModelType): The entity to update, by id or instance.
+            field (str): Name of the model attribute holding the storage key.
+
+        Returns:
+            ModelType: The entity with ``field`` set to ``None`` (persisted
+            only when there was a key to clear).
+
+        Raises:
+            AppException: ``repository.not_found_exception`` when ``ref`` is
+                an id with no matching row.
+        """
+        entity = await self.repository.resolve(ref)
+        old_key: Any = getattr(entity, field)
+        if not old_key:
+            return entity
+        await self.upload_utils.delete(old_key)
+        setattr(entity, field, None)
+        return await self.repository.update(entity)
+
+    async def file_url(
+        self,
+        key: str | None,
+        *,
+        expires: timedelta = _DEFAULT_URL_TTL,
+    ) -> str | None:
+        """Return a presigned download URL for ``key``, or ``None`` when empty.
+
+        Args:
+            key (str | None): The stored object key (typically the field
+                value). ``None`` / empty returns ``None`` so callers can
+                forward the result straight into a response schema.
+            expires (timedelta): URL lifetime. Defaults to one hour.
+
+        Returns:
+            str | None: A temporary download URL, or ``None`` when there is
+            no key.
+        """
+        if not key:
+            return None
+        return await self.storage.presigned_get_url(key, expires=expires)