refactor: deepen Deck and Card data-access modules

app/api/decks.py

@@ -6,7 +6,6 @@
 from litestar.exceptions import HTTPException
 from litestar.params import FromPath  # noqa: TC002
 from litestar.plugins.pydantic import PydanticDTO
-from sqlalchemy import orm
 
 from app import models, schemas
 from app.repositories import CardsRepository, DecksRepository  # noqa: TC001
@@ -20,10 +19,7 @@ async def list_decks(decks_repository: DecksRepository) -> schemas.Decks:
 
 @litestar.get("/decks/{deck_id:int}/")
 async def get_deck(deck_id: FromPath[int], decks_repository: DecksRepository) -> schemas.Deck:
-    instance = await decks_repository.get_one_or_none(
-        models.Deck.id == deck_id,
-        load=[orm.selectinload(models.Deck.cards)],
-    )
+    instance = await decks_repository.fetch_with_cards(deck_id)
     if not instance:
         raise HTTPException(status_code=status_codes.HTTP_404_NOT_FOUND, detail="Deck is not found")
 
@@ -51,7 +47,7 @@ async def create_deck(data: schemas.DeckCreate, decks_repository: DecksRepositor
 
 @litestar.get("/decks/{deck_id:int}/cards/")
 async def list_cards(deck_id: FromPath[int], cards_repository: CardsRepository) -> schemas.Cards:
-    objects = await cards_repository.get_many(models.Card.deck_id == deck_id)
+    objects = await cards_repository.list_for_deck(deck_id)
     return schemas.Cards(items=objects)  # ty: ignore[invalid-argument-type]
 
 
@@ -67,19 +63,15 @@ async def get_card(card_id: FromPath[int], cards_repository: CardsRepository) ->
 async def create_cards(
     deck_id: FromPath[int], data: list[schemas.CardCreate], cards_repository: CardsRepository
 ) -> schemas.Cards:
-    objects = await cards_repository.create_many(
-        data=[models.Card(**card.model_dump(), deck_id=deck_id) for card in data],
-    )
+    objects = await cards_repository.add_cards(deck_id, data)
     return schemas.Cards(items=objects)  # ty: ignore[invalid-argument-type]
 
 
 @litestar.put("/decks/{deck_id:int}/cards/")
 async def update_cards(
     deck_id: FromPath[int], data: list[schemas.Card], cards_repository: CardsRepository
 ) -> schemas.Cards:
-    objects = await cards_repository.upsert_many(
-        data=[models.Card(**card.model_dump(exclude={"deck_id"}), deck_id=deck_id) for card in data],
-    )
+    objects = await cards_repository.upsert_cards(deck_id, data)
     return schemas.Cards(items=objects)  # ty: ignore[invalid-argument-type]
 
 

app/repositories.py

@@ -1,7 +1,14 @@
+from typing import TYPE_CHECKING
+
 from advanced_alchemy.repository import SQLAlchemyAsyncRepository
 from advanced_alchemy.service import SQLAlchemyAsyncRepositoryService
+from sqlalchemy import orm
+
+from app import models, schemas
 
-from app import models
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
 
 class DecksRepository(SQLAlchemyAsyncRepositoryService[models.Deck]):
@@ -10,9 +17,26 @@ class BaseRepository(SQLAlchemyAsyncRepository[models.Deck]):
 
     repository_type = BaseRepository
 
+    async def fetch_with_cards(self, deck_id: int) -> models.Deck | None:
+        return await self.get_one_or_none(
+            models.Deck.id == deck_id,
+            load=[orm.selectinload(models.Deck.cards)],
+        )
+
 
 class CardsRepository(SQLAlchemyAsyncRepositoryService[models.Card]):
     class BaseRepository(SQLAlchemyAsyncRepository[models.Card]):
         model_type = models.Card
 
     repository_type = BaseRepository
+
+    async def list_for_deck(self, deck_id: int) -> Sequence[models.Card]:
+        return await self.get_many(models.Card.deck_id == deck_id)
+
+    async def add_cards(self, deck_id: int, cards: list[schemas.CardCreate]) -> Sequence[models.Card]:
+        return await self.create_many([models.Card(**card.model_dump(), deck_id=deck_id) for card in cards])
+
+    async def upsert_cards(self, deck_id: int, cards: list[schemas.Card]) -> Sequence[models.Card]:
+        return await self.upsert_many(
+            [models.Card(**card.model_dump(exclude={"deck_id"}), deck_id=deck_id) for card in cards],
+        )