Merge pull request #5 from ljensen505/add-docstrings

fixed errant method name refactor, added docstrings

server/app/controllers/events.py

@@ -63,7 +63,7 @@ class EventController(BaseController):
         """
         Builds and returns a single EventSeries object by its numeric ID.
         """
-        if not (data := await self.db.select_one_series_by_id(series_id)):
+        if not (data := await self.db.select_one_by_id(series_id)):
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND, detail="Event not found"
             )

server/app/controllers/group.py

@@ -12,7 +12,7 @@ class GroupController(BaseController):
         self.db: GroupQueries = group_queries
 
     async def get_group(self) -> Group:
-        if (data := await self.db.select_one_series_by_id()) is None:
+        if (data := await self.db.select_one_by_id()) is None:
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND, detail="Group not found"
             )

server/app/controllers/musicians.py

@@ -24,7 +24,7 @@ class MusicianController(BaseController):
             )
 
     async def get_musician(self, id: int) -> Musician:
-        if (data := await self.db.select_one_series_by_id(id)) is None:
+        if (data := await self.db.select_one_by_id(id)) is None:
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND, detail="Musician not found"
             )

server/app/controllers/users.py

@@ -24,7 +24,7 @@ class UserController(BaseController):
             )
 
     async def get_user_by_id(self, id: int) -> User:
-        if (data := await self.db.select_one_series_by_id(id)) is None:
+        if (data := await self.db.select_one_by_id(id)) is None:
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
             )

server/app/db/base_queries.py

@@ -1,10 +1,17 @@
 from typing import Callable
 
+from icecream import ic
+
 from app.db.conn import connect_db
 
 
 class BaseQueries:
-    from icecream import ic
+    """
+    Base class for all query classes.
+    This class provides a connection to the database.
+
+    Should not be used directly; instead, inherit from this class and provide the table name.
+    """
 
     def __init__(self) -> None:
         self.table: str = None  # type: ignore
@@ -20,7 +27,7 @@ class BaseQueries:
         db.close()
         return data  # type: ignore
 
-    async def select_one_series_by_id(self, id: int) -> dict | None:
+    async def select_one_by_id(self, id: int) -> dict | None:
         query = f"SELECT * FROM {self.table} WHERE id = %s"
         db = self.connect_db()
         cursor = db.cursor(dictionary=True)

server/app/db/events.py

@@ -8,11 +8,16 @@ from app.models.event import Event, EventSeries, NewEvent, NewEventSeries
 
 
 class EventQueries(BaseQueries):
+    """
+    A collection of queries for handling Event and Series data.
+    Inherits from BaseQueries, which provides a connection to the database.
+    """
+
     def __init__(self) -> None:
         super().__init__()
         self.table = SERIES_TABLE
 
-    async def select_one_series_by_id(self, series_id: int) -> list[dict] | None:
+    async def select_one_by_id(self, series_id: int) -> list[dict] | None:
         query = f"""
             SELECT s.series_id , s.name , s.description , s.poster_id , e.event_id , e.location , e.`time` , e.ticket_url , e.map_url
             FROM {SERIES_TABLE} s
@@ -29,6 +34,11 @@ class EventQueries(BaseQueries):
         return data
 
     async def select_all_series(self) -> list[dict]:
+        """
+        Queries for all Series and Event info and returns a list of dictionaries.
+        Data is gathered with a LEFT JOIN on the Event table to ensure all Series are returned.
+        A Series with no Events is valid.
+        """
         query = f"""
                 SELECT s.series_id , s.name , s.description , s.poster_id , e.event_id , e.location , e.`time` , e.ticket_url , e.map_url
                 FROM {SERIES_TABLE} s

server/app/db/group.py

@@ -7,7 +7,7 @@ class GroupQueries(BaseQueries):
         super().__init__()
         self.table = GROUP_TABLE
 
-    async def select_one_series_by_id(self) -> dict:
+    async def select_one_by_id(self) -> dict:
         query = f"SELECT * FROM {self.table}"
         db = self.connect_db()
         cursor = db.cursor(dictionary=True)