Define query protocol for multiple objects

.github/workflows/test.yaml

@@ -70,79 +70,49 @@ jobs:
           path: www
           key: ${{ inputs.runs-on }}-www
 
-  setup_backend:
-    name: Setup Backend
-    runs-on: ${{ inputs.runs-on }}
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
-        with:
-          python-version-file: pyproject.toml
-      - uses: astral-sh/setup-uv@v7
-        with:
-          activate-environment: true
-          enable-cache: true
-      - run: uv venv
-      - run: uv sync
-      - uses: actions/cache@v5
-        with:
-          path: .venv
-          key: ${{ inputs.runs-on }}-.venv
   lint_backend:
     name: Lint Backend
-    needs: setup_backend
     runs-on: ${{ inputs.runs-on }}
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/cache@v5
-        with:
-          path: .venv
-          key: ${{ inputs.runs-on }}-.venv
-      - uses: actions/setup-python@v6
-        with:
-          python-version-file: pyproject.toml
-
       - uses: astral-sh/setup-uv@v7
         with:
           activate-environment: true
           enable-cache: true
+      - run: uv sync
+      - run: ruff check
+      - run: ty check
   test_backend:
     name: Test Backend
-    needs: [setup_backend, build_frontend]
+    needs: build_frontend
     runs-on: ${{ inputs.runs-on }}
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/cache@v5
+      - uses: astral-sh/setup-uv@v7
         with:
-          path: .venv
-          key: ${{ inputs.runs-on }}-.venv
+          activate-environment: true
+          enable-cache: true
+      - run: uv sync
       - uses: actions/cache@v5
         with:
           path: www
           key: ${{ inputs.runs-on }}-www
           fail-on-cache-miss: true
-      - uses: actions/setup-python@v6
-        with:
-          python-version-file: pyproject.toml
-      - uses: astral-sh/setup-uv@v7
-        with:
-          activate-environment: true
-          enable-cache: true
       - run: pytest backend/tests --tag-name ${{ github.ref_name }}
         if: ${{ inputs.test-release }}
       - run: pytest
         if: ${{ !inputs.test-release }}
   build_backend:
     name: Build backend
-    needs: [setup_backend, build_frontend]
+    needs: build_frontend
     runs-on: ${{ inputs.runs-on }}
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/cache@v5
+      - uses: astral-sh/setup-uv@v7
         with:
-          path: .venv
-          key: ${{ inputs.runs-on }}-.venv
-          fail-on-cache-miss: true
+          activate-environment: true
+          enable-cache: true
+      - run: uv sync
       - uses: actions/cache@v5
         with:
           path: www
@@ -151,10 +121,6 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version-file: pyproject.toml
-      - uses: astral-sh/setup-uv@v7
-        with:
-          activate-environment: true
-          enable-cache: true
       - run: pyinstaller onedir.spec
       - run: rm -rf "dist/NSO Bridge"
         if: ${{ inputs.runs-on == 'macos-latest' }}

backend/src/core/__init__.py

@@ -4,7 +4,7 @@
 """
 
 from .database import CASCADE_CHILD, CASCADE_OTHER, BaseSQLModel, DatabaseEngine
-from .dependencies import AsyncSessionDepends, EngineFactory
+from .dependencies import EngineFactory, GetAsyncSession
 from .protocols import Memento
 from .router import api_router, assets, pages_router
 from .schemas import APIResponseClass, ClientSchema, ServerSchema
@@ -21,7 +21,6 @@
     'api_router',
     'APIResponseClass',
     'assets',
-    'AsyncSessionDepends',
     'BaseSQLModel',
     'CASCADE_CHILD',
     'CASCADE_OTHER',
@@ -33,6 +32,7 @@
     'get_default_route',
     'get_resource_path',
     'get_server',
+    'GetAsyncSession',
     'Memento',
     'pages_router',
     'ServerSchema',

backend/src/core/database.py

@@ -10,6 +10,7 @@
     ClassVar,
     Final,
 )
+from uuid import UUID, uuid4
 
 from sqlalchemy.engine import URL
 from sqlalchemy.ext.asyncio import (
@@ -45,7 +46,7 @@ class BaseSQLModel(AsyncAttrs, DeclarativeBase):
 
     """
 
-    id: Mapped[int | None] = mapped_column(nullable=False, primary_key=True)
+    uuid: Mapped[UUID] = mapped_column(default=uuid4, primary_key=True)
 
     __abstract__: bool = True
     __type_annotation_map__: dict = {timedelta: _TimedeltaAsMilliseconds}

backend/src/core/dependencies.py

@@ -78,7 +78,7 @@ async def yield_async_session(cls) -> AsyncGenerator[AsyncSession, None]:
             await session.commit()  # Automatically commit after each session
 
 
-AsyncSessionDepends: TypeAlias = Annotated[
+GetAsyncSession: TypeAlias = Annotated[
     AsyncSession,
     Depends(EngineFactory.yield_async_session),
 ]

backend/src/core/schemas.py

@@ -116,5 +116,5 @@ def render(self, content: Any) -> bytes:
             allow_nan=False,
             indent=None,
             separators=(',', ':'),
-            default=(lambda dt: str(dt)),  # Serialize datetime objects
+            default=(str),  # Serialize datetime objects
         ).encode('utf-8')

backend/src/game/__init__.py

@@ -26,17 +26,16 @@
 from .bouts.router import router as bout_router
 from .jams.router import router as jam_router
 from .models import CacheableSQLModel, CacheKey
-from .rosters.models import Roster
-from .rosters.router import router as roster_router
 from .rulesets import wftda_2025
 from .series.models import Series
 from .series.router import router as series_router
+from .skaters.router import router as skater_router
 from .timeouts.router import router as timeout_router
 
 routers: Final[tuple[APIRouter, ...]] = (
     bout_router,
     jam_router,
-    roster_router,
+    skater_router,
     series_router,
     timeout_router,
 )
@@ -45,7 +44,6 @@
 __all__ = (
     'CacheKey',
     'CacheableSQLModel',
-    'Roster',  # Non-rule-bound objects can be exported
     'routers',
     'Series',  # Non-rule-bound objects can be exported
     'wftda_2025',

backend/src/game/bouts/dependencies.py

@@ -1,8 +1,9 @@
 """The FastAPI dependencies methods for Bouts."""
 
 from typing import TYPE_CHECKING, Annotated, TypeAlias
+from uuid import UUID
 
-from core import AsyncSessionDepends
+from core import GetAsyncSession
 from core.exceptions import ModelLookupError
 from fastapi import Depends, Query, Request
 from sqlalchemy import select
@@ -18,22 +19,23 @@
 async def _get_bout(
     request: Request,
     user: GetUser,
-    session: AsyncSessionDepends,
-    bout_id: Annotated[int, Query(alias='boutId')],
+    session: GetAsyncSession,
+    bout_uuid: Annotated[UUID, Query(alias='boutUuid')],
 ) -> BaseBout:
-    # Query the database for the desired Bout
-    statement: Select[tuple[BaseBout]] = select(BaseBout).where(BaseBout.id == bout_id)
+    statement: Select[tuple[BaseBout]] = select(BaseBout).where(
+        BaseBout.uuid == bout_uuid
+    )
     results: Result[tuple[BaseBout]] = await session.execute(statement)
 
     try:
         bout: BaseBout = results.scalar_one()
     except NoResultFound as e:
-        raise ModelLookupError(f'Could not find Bout with ID {bout_id}') from e
+        raise ModelLookupError(f'Could not find Bout ({bout_uuid=})') from e
 
     # Optionally take a snapshot of the Bout state and return the Bout
     if request.method != 'GET':
         user.stage(bout.get_memento())
     return bout
 
 
-BoutDepends: TypeAlias = Annotated[BaseBout, Depends(_get_bout)]
+GetBout: TypeAlias = Annotated[BaseBout, Depends(_get_bout)]

backend/src/game/bouts/models.py

@@ -4,6 +4,7 @@
 
 from datetime import datetime  # noqa: TC003
 from typing import TYPE_CHECKING, Any, ClassVar, Final, Literal, final, override
+from uuid import UUID  # noqa: TC003
 
 from core import CASCADE_CHILD, CASCADE_OTHER
 from game.clocks.models import Clock
@@ -32,8 +33,10 @@ class BaseBout(CacheableSQLModel):
 
     ruleset: ClassVar[Ruleset]
 
-    series_id: Mapped[int] = mapped_column(ForeignKey('series.id'))
-    clock_id: Mapped[int] = mapped_column(ForeignKey('clocks.id', ondelete='RESTRICT'))
+    _clock_uuid: Mapped[UUID] = mapped_column(
+        ForeignKey('clocks.uuid', ondelete='RESTRICT')
+    )
+    series_uuid: Mapped[UUID] = mapped_column(ForeignKey('series.uuid'))
 
     start_countdown: Mapped[datetime | None] = mapped_column(default=None)
     is_final: Mapped[bool] = mapped_column(default=False)
@@ -43,18 +46,19 @@ class BaseBout(CacheableSQLModel):
     _series: Mapped[Series] = relationship(
         back_populates='bouts',
         cascade=CASCADE_OTHER,
-        foreign_keys=[series_id],
+        foreign_keys=[series_uuid],
     )
     clock: Mapped[Clock] = relationship(
         cascade=CASCADE_CHILD,
-        foreign_keys=[clock_id],
+        foreign_keys=[_clock_uuid],
         lazy='joined',
         single_parent=True,
     )
     teams: Mapped[list[BaseTeam]] = relationship(
         back_populates='_bout',
         cascade=CASCADE_CHILD,
         lazy='selectin',
+        order_by=[column('num')],
     )
     jams: Mapped[list[BaseJam]] = relationship(
         back_populates='_bout',
@@ -66,7 +70,7 @@ class BaseBout(CacheableSQLModel):
         back_populates='_bout',
         cascade=CASCADE_CHILD,
         lazy='selectin',
-        order_by=[column('id')],
+        order_by=[column('num')],
     )
 
     __tablename__: str = 'bouts'
@@ -82,7 +86,7 @@ def __str__(self) -> str:
             str: a str representation of this Bout.
 
         """
-        return f'[Bout ID: {self.id}]'
+        return f'[Bout UUID: {self.uuid}]'
 
     def __init__(self, ruleset_name: str, *teams: BaseTeam) -> None:
         """Instantiate a Bout.
@@ -96,8 +100,8 @@ def __init__(self, ruleset_name: str, *teams: BaseTeam) -> None:
         super().__init__(clock=Clock(), ruleset_name=ruleset_name, teams=list(teams))
 
     @override
-    def cache_key(self) -> CacheKey:
-        return (self.__tablename__, self.id)
+    async def cache_key(self) -> CacheKey:
+        return (self.__tablename__, self.uuid)
 
     @override
     async def get_parents(self) -> tuple[BaseSQLModel, ...]:
@@ -136,6 +140,15 @@ def state(self) -> Literal['final', 'jam', 'lineup', 'stopped', 'timeout']:
         else:
             return 'stopped'
 
+    def get_active_jam(self) -> BaseJam:
+        """Get the most recently started Jam or upcoming Jam.
+
+        Returns:
+            BaseJam: the active Jam.
+
+        """
+        return next((j for j in self.jams if j.is_started()), self.jams[-1])
+
     def get_running_jam(self) -> BaseJam | None:
         """Get the running Jam if there is one.
 
@@ -165,16 +178,14 @@ def get_running_timeout(self) -> BaseTimeout | None:
         """
         return next((t for t in self.timeouts if t.is_running()), None)
 
-    def get_upcoming_timeout(self) -> BaseTimeout | None:
-        """Get the upcoming Timeout if there is one.
-
-        The upcoming Timeout is the first Timeout that is not started.
+    def get_last_timeout(self) -> BaseTimeout | None:
+        """Get most recently complete Timeout if there is one.
 
         Returns:
-            BaseTimeout | None: the upcoming Timeout or None.
+            BaseTimeout | None: the most recently complete Timeout or None.
 
         """
-        return next((t for t in self.timeouts if not t.is_started()), None)
+        return next((t for t in reversed(self.timeouts) if not t.is_running()), None)
 
     async def begin_period(self, timestamp: datetime) -> None:
         """Begin the next Period.