added docstrings to event controller and moved constants

server/app/controllers/__init__.py

@@ -1,3 +1,3 @@
-from .controller import Controller
+from .controller import MainController
 
-controller = Controller()
+controller = MainController()

server/app/controllers/base_controller.py

@@ -6,20 +6,25 @@ from pathlib import Path
 from fastapi import HTTPException, UploadFile, status
 from icecream import ic
 
+from app.constants import ALLOWED_FILES_TYPES, ONE_MB
 from app.db.base_queries import BaseQueries
 
-ALLOWED_FILES_TYPES = ["image/jpeg", "image/png"]
-MAX_FILE_SIZE = 1000000  # 1 MB
-
 
 class BaseController:
+    """
+    A generic controller class which includes logging, image verification, and other common methods.
+    Model-specific controllers should inherit from this class and this class should not be instantiated directly.
+    """
+
     def __init__(self) -> None:
         self.db: BaseQueries = None  # type: ignore
         self.ALL_FILES = ALLOWED_FILES_TYPES
-        self.MAX_FILE_SIZE = MAX_FILE_SIZE
+        self.MAX_FILE_SIZE = ONE_MB
 
     async def verify_image(self, file: UploadFile) -> bytes:
-        print("verifying image")
+        """
+        Verifies that the file is an image and is within the maximum file size.
+        """
         if file.content_type not in self.ALL_FILES:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
@@ -34,6 +39,9 @@ class BaseController:
         return image_file
 
     def log_error(self, e: Exception) -> None:
+        """
+        Logs an error to a timestamped text file in the logs directory.
+        """
         curr_dir = Path(__file__).parent
         log_dir = curr_dir / "logs"
         log_dir.mkdir(exist_ok=True)

server/app/controllers/controller.py

@@ -13,7 +13,15 @@ from app.models.musician import Musician
 from app.models.user import User
 
 
-class Controller:
+class MainController:
+    """
+    The main controller and entry point for all API requests.
+    All methods are either pass-throughs to the appropriate controller or
+    are used to coordinate multiple controllers.
+
+    token-based authentication is handled here as needed per the nature of the data being accessed.
+    """
+
     def __init__(self) -> None:
         self.event_controller = EventController()
         self.musician_controller = MusicianController()

server/app/controllers/events.py

@@ -10,11 +10,25 @@ from app.models.event import Event, EventSeries, NewEventSeries
 
 
 class EventController(BaseController):
+    """
+    Handles all event-related operations and serves as an intermediate controller between
+    the main controller and the model layer.
+    Inherits from BaseController, which provides logging and other generic methods.
+
+    Testing: pass a mocked EventQueries object to the constructor.
+    """
+
     def __init__(self, eq=event_queries) -> None:
         super().__init__()
         self.db: EventQueries = eq
 
-    def _all_series(self, data: list[dict]) -> list[EventSeries]:
+    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.
+        """
         all_series: dict[str, EventSeries] = {}
 
         for event_series_row in data:
@@ -24,13 +38,20 @@ class EventController(BaseController):
             if event_series_row.get("event_id"):
                 all_series[series_name].events.append(Event(**event_series_row))
 
-        return [series for series in all_series.values()]
+        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.
+
+        The list of EventSeries is created by calling the _all_series() helper method, which provided this data
+        as a list of dicts.
+        """
         series_data = await self.db.select_all_series()
 
         try:
-            return self._all_series(series_data)
+            return [series for series in self._all_series(series_data).values()]
         except Exception as e:
             self.log_error(e)
             raise HTTPException(
@@ -39,6 +60,9 @@ 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.
+        """
         if not (data := await self.db.select_one_series_by_id(series_id)):
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND, detail="Event not found"
@@ -54,6 +78,9 @@ class EventController(BaseController):
             )
 
     async def create_series(self, series: NewEventSeries) -> EventSeries:
+        """
+        Takes a NewEventSeries object and passes it to the database layer for insertion.
+        """
         try:
             inserted_id = await self.db.insert_one_series(series)
             for new_event in series.events:
@@ -66,12 +93,19 @@ class EventController(BaseController):
             )
 
     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.
+        """
         series = await self.get_one_series_by_id(series_id)
         series.poster_id = await self._upload_poster(poster)
         await self.db.update_series_poster(series)
         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.
+        """
         image_file = await self.verify_image(poster)
         try:
             data = uploader.upload(image_file)
@@ -83,12 +117,17 @@ class EventController(BaseController):
             )
 
     async def delete_series(self, id: int) -> None:
+        """
+        Ensures an EventSeries object exists and then deletes it from the database
+        """
         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.
+        """
         if route_id != series.series_id:
-            print("error")
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="ID in URL does not match ID in request body",