usecase

Writing use cases (src/application/v1/usecases/<domain>/)

A use case is the transport-agnostic unit of business logic. Endpoints, consumers, and scheduled tasks all call request_bus.send(Request(...)) and get back a Result. Use cases never know who called them.

One file, two classes

Every use case file defines exactly one Request class and exactly one UseCase class. Keep them in the same file — they are a pair.

# src/application/v1/usecases/widget/create.py
from dataclasses import dataclass
from typing import Annotated

import uuid_utils.compat as uuid
from pydantic import Field

from src.application.common.interfaces.usecase import UseCase
from src.application.common.request import Request
from src.application.v1.results import WidgetResult
from src.database.psql import DBGateway


class CreateWidgetRequest(Request):
    name: Annotated[str, Field(max_length=64)]
    owner_uuid: uuid.UUID


@dataclass(slots=True)
class CreateWidgetUseCase(UseCase[CreateWidgetRequest, WidgetResult]):
    database: DBGateway

    async def __call__(self, request: CreateWidgetRequest) -> WidgetResult:
        async with self.database:
            widget = (
                await self.database.widget.create(
                    name=request.name,
                    owner_uuid=request.owner_uuid,
                )
            ).result()
            return WidgetResult(**widget.as_dict())

Invariants

1. Request inherits src.application.common.request.Request (Pydantic, frozen=True). Validation via Annotated[..., Field(...)]. Do not reuse HTTP Contract classes here — the Request describes the use-case input, not the HTTP input.
2. UseCase inherits UseCase[RequestClass, ReturnType]. The base class auto-applies @dataclass(slots=True) — add your own @dataclass(slots=True) on the subclass too for mypy/readability.
3. Dependencies are dataclass fields: database: DBGateway, hasher: Hasher, cache: StrCache, services: ServiceGateway, etc. Injected by Dishka via the request bus — do not instantiate manually.
4. Returns a Result subclass from src/application/v1/results/ — never a Contract from presentation/, never a bare ORM model, never a dict.
5. Register the use case in src/application/v1/usecases/__init__.py::setup_use_cases():

   request_bus.register(widget.CreateWidgetRequest, widget.CreateWidgetUseCase)
   

6. Re-export from src/application/v1/usecases/widget/__init__.py so the presentation/consumers layer can import from src.application.v1.usecases.widget import CreateWidgetRequest.