feat: add election model for better documentation

Author: jbriones1

src/elections/crud.py

@@ -50,7 +50,7 @@ async def delete_election(db_session: AsyncSession, slug: str) -> None:
 # ------------------------------------------------------- #
 
 # TODO: switch to only using one of application or registration
-async def get_all_registrations(
+async def get_all_registrations_of_user(
     db_session: AsyncSession,
     computing_id: str,
     election_slug: str

src/elections/models.py

@@ -0,0 +1,20 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ElectionTypeEnum(str, Enum):
+    GENERAL = "general_election"
+    BY_ELECTION = "by_election"
+    COUNCIL_REP = "council_rep_election"
+
+class ElectionModel(BaseModel):
+    slug: str
+    name: str
+    type: ElectionTypeEnum
+    datetime_start_nominations: str
+    datetime_start_voting: str
+    datetime_end_voting: str
+    available_positions: str
+    survey_link: str | None
+

src/elections/urls.py

@@ -8,6 +8,7 @@
 import elections
 import elections.crud
 import elections.tables
+from elections.models import ElectionModel
 from elections.tables import Election, NomineeApplication, NomineeInfo, election_types
 from officers.constants import OfficerPosition
 from permission.types import ElectionOfficer, WebsiteAdmin
@@ -41,7 +42,8 @@ async def _validate_user(
 
 @router.get(
     "/list",
-    description="Returns a list of all elections & their status"
+    description="Returns a list of all elections & their status",
+    response_model=list[ElectionModel]
 )
 async def list_elections(
     _: Request,
@@ -68,7 +70,8 @@ async def list_elections(
     Retrieves the election data for an election by name.
     Returns private details when the time is allowed.
     If user is an admin or elections officer, returns computing ids for each candidate as well.
-    """
+    """,
+    response_model=ElectionModel
 )
 async def get_election(
     request: Request,
@@ -168,6 +171,7 @@ def _raise_if_bad_election_data(
 @router.post(
     "/{election_name:str}",
     description="Creates an election and places it in the database. Returns election json on success",
+    response_model=ElectionModel
 )
 async def create_election(
     request: Request,
@@ -253,7 +257,8 @@ async def create_election(
         name produces the same slug.
 
         Returns election json on success.
-    """
+    """,
+    response_model=ElectionModel
 )
 async def update_election(
     request: Request,
@@ -312,7 +317,8 @@ async def update_election(
 
 @router.delete(
     "/{election_name:str}",
-    description="Deletes an election from the database. Returns whether the election exists after deletion."
+    description="Deletes an election from the database. Returns whether the election exists after deletion.",
+    response_model=SuccessFailModel
 )
 async def delete_election(
     request: Request,
@@ -360,7 +366,7 @@ async def get_election_registrations(
             detail=f"election with slug {slugified_name} does not exist"
         )
 
-    registration_list = await elections.crud.get_all_registrations(db_session, computing_id, slugified_name)
+    registration_list = await elections.crud.get_all_registrations_of_user(db_session, computing_id, slugified_name)
     if registration_list is None:
         return JSONResponse([])
     return JSONResponse([
@@ -416,7 +422,7 @@ async def register_in_election(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="registrations can only be made during the nomination period"
         )
-    elif await elections.crud.get_all_registrations(db_session, computing_id, slugified_name):
+    elif await elections.crud.get_all_registrations_of_user(db_session, computing_id, slugified_name):
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="you are already registered in this election"
@@ -484,7 +490,7 @@ async def update_registration(
             detail="speeches can only be updated during the nomination period"
         )
 
-    elif not await elections.crud.get_all_registrations(db_session, ccid_of_registrant, slugified_name):
+    elif not await elections.crud.get_all_registrations_of_user(db_session, ccid_of_registrant, slugified_name):
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail="applicant not yet registered in this election"
@@ -533,7 +539,7 @@ async def delete_registration(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="registration can only be revoked during the nomination period"
         )
-    elif not await elections.crud.get_all_registrations(db_session, computing_id, slugified_name):
+    elif not await elections.crud.get_all_registrations_of_user(db_session, computing_id, slugified_name):
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail="you are not yet registered in this election"

src/utils/shared_models.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+
+class SuccessFailModel(BaseModel):
+    success: bool