updated more docstrings for various controllers; prepped musician tests

server/app/controllers/events.py

@@ -18,16 +18,19 @@ class EventController(BaseController):
     Testing: pass a mocked EventQueries object to the constructor.
     """
 
-    def __init__(self, eq=event_queries) -> None:
+    def __init__(self, event_queries=event_queries) -> None:
         super().__init__()
-        self.db: EventQueries = eq
+        self.db: EventQueries = event_queries
 
     def _all_series(self, data: list[dict]) -> dict[str, EventSeries]:
-        """
-        Helper method to instantiate EventSeries objects from sql rows (a list of dictionaries).
-        Instantiation is done by destructuring the dictionary into the EventSeries constructor.
-        Should not be called directly; use get_all_series() instead.
-        series.name is a required and unique field and can reliably be used as a key in a dictionary.
+        """Creates and returns a dictionary of EventSeries objects from a list of sql rows (as dicts).
+        Should only be used internally.
+
+        Args:
+            data (list[dict]): List of dicts, each representing a row from the database. `event_id` may be null
+
+        Returns:
+            dict[str, EventSeries]: A dictionary of EventSeries objects, keyed by series name
         """
         all_series: dict[str, EventSeries] = {}
 
@@ -41,12 +44,13 @@ class EventController(BaseController):
         return all_series
 
     async def get_all_series(self) -> list[EventSeries]:
-        """
-        Attempts to create and return a list of EventSeries objects and is consumed by the main controller.
-        Will trigger a 500 status code if any exception is raised, and log the error to a timestamped text file.
+        """Retrieves all EventSeries objects from the database and returns them as a list.
 
-        The list of EventSeries is created by calling the _all_series() helper method, which provided this data
-        as a list of dicts.
+        Raises:
+            HTTPException: If any error occurs during the retrieval process (status code 500)
+
+        Returns:
+            list[EventSeries]: A list of EventSeries objects which are suitable for a response body
         """
         series_data = await self.db.select_all_series()
 
@@ -60,16 +64,25 @@ class EventController(BaseController):
             )
 
     async def get_one_series_by_id(self, series_id: int) -> EventSeries:
+        """Builds and returns a single EventSeries object by its numeric ID.
+
+        Args:
+            series_id (int): The numeric id of the series to retrieve
+
+        Raises:
+            HTTPException: If the series is not found (status code 404)
+            HTTPException:  If an error occurs (status code 500)
+
+        Returns:
+            EventSeries: A single EventSeries object
         """
-        Builds and returns a single EventSeries object by its numeric ID.
-        """
-        if not (data := await self.db.select_one_by_id(series_id)):
+        if not (rows := await self.db.select_one_by_id(series_id)):
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND, detail="Event not found"
             )
         try:
             return EventSeries(
-                **data[0], events=[Event(**e) for e in data if e["event_id"]]
+                **rows[0], events=[Event(**row) for row in rows if row.get("event_id")]
             )
         except Exception as e:
             raise HTTPException(
@@ -78,8 +91,16 @@ class EventController(BaseController):
             )
 
     async def create_series(self, series: NewEventSeries) -> EventSeries:
-        """
-        Takes a NewEventSeries object and passes it to the database layer for insertion.
+        """Takes a NewEventSeries object and passes it to the database layer for insertion.
+
+        Args:
+            series (NewEventSeries): A NewEventSeries object which does not yet have an ID
+
+        Raises:
+            HTTPException: If the series name already exists (status code 400)
+
+        Returns:
+            EventSeries: The newly created EventSeries object with an ID
         """
         try:
             inserted_id = await self.db.insert_one_series(series)
@@ -92,10 +113,17 @@ class EventController(BaseController):
                 detail=f"Series name already exists. Each series must have a unique name.\n{e}",
             )
 
-    async def add_series_poster(self, series_id, poster: UploadFile) -> EventSeries:
-        """
-        Adds (or updates) a poster image to a series.
-        Actual image storage is done with Cloudinary and the public ID is stored in the database.
+    async def add_series_poster(
+        self, series_id: int, poster: UploadFile
+    ) -> EventSeries:
+        """Adds (or updates) a poster image to a series.
+
+        Args:
+            series_id (int): The numeric ID of the series to update
+            poster (UploadFile): The image file to upload
+
+        Returns:
+            EventSeries: The updated EventSeries object
         """
         series = await self.get_one_series_by_id(series_id)
         series.poster_id = await self._upload_poster(poster)
@@ -103,8 +131,17 @@ class EventController(BaseController):
         return await self.get_one_series_by_id(series.series_id)
 
     async def _upload_poster(self, poster: UploadFile) -> str:
-        """
-        Uploads a poster image to Cloudinary and returns the public ID for storage in the database.
+        """Uploads a poster image to Cloudinary and returns the public ID for storage in the database.
+        Should only be used internally.
+
+        Args:
+            poster (UploadFile): The image file to upload
+
+        Raises:
+            HTTPException: If an error occurs during the upload process (status code 500)
+
+        Returns:
+            str: The public ID of the uploaded image
         """
         image_file = await self.verify_image(poster)
         try:
@@ -117,15 +154,27 @@ class EventController(BaseController):
             )
 
     async def delete_series(self, id: int) -> None:
-        """
-        Ensures an EventSeries object exists and then deletes it from the database
+        """Ensures an EventSeries object exists and then deletes it from the database.
+
+        Args:
+            id (int): The numeric ID of the series to delete
         """
         series = await self.get_one_series_by_id(id)
         await self.db.delete_one_series(series)
 
     async def update_series(self, route_id: int, series: EventSeries) -> EventSeries:
-        """
-        Updates an existing EventSeries object in the database.
+        """Updates an existing EventSeries object in the database.
+
+        Args:
+            route_id (int): The numeric ID of the series in the URL
+            series (EventSeries): The updated EventSeries object
+
+        Raises:
+            HTTPException: if the ID in the URL does not match the ID in the request body (status code 400)
+            HTTPException: if the poster ID is updated directly (status code 400)
+
+        Returns:
+            EventSeries: The updated EventSeries object with updated info
         """
         if route_id != series.series_id:
             raise HTTPException(