add descriptions for tags;comments on classes

Author: tslashd

globals.py

@@ -28,6 +28,44 @@
     password=config["REDIS"]["PASSWORD"],
 )
 
+tags_metadata = [
+    {
+        "name": "ck_bonus",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "ck_checkpoints",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "ck_latestrecords",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "ck_maptier",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "ck_playeroptions2",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "ck_playerrank",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "ck_playertemp",
+        "description": "All queries concerning this table from `queries.sp`",
+    },
+    {
+        "name": "strays",
+        "description": "All queries that were NOT contained in `queries.sp` for each table",
+    },
+    {
+        "name": "Point Calculation",
+        "description": "Queries that are involved in **player points** calculation",
+    },
+]
 
 # Whitelisted IPs
 WHITELISTED_IPS = config["WHITELISTED_IPS"]
@@ -73,7 +111,14 @@ def set_cache(cache_key: str, data):
 
     redis_client.set(
         cache_key,
-        json.dumps(data, use_decimal=True, encoding='utf-8', ensure_ascii=False, default=default_serializer, allow_nan=True),
+        json.dumps(
+            data,
+            use_decimal=True,
+            encoding="utf-8",
+            ensure_ascii=False,
+            default=default_serializer,
+            allow_nan=True,
+        ),
         ex=config["REDIS"]["EXPIRY"],
     )
 
@@ -94,19 +139,22 @@ def get_cache(cache_key: str):
     else:
         return None
 
+
 def ordinal(n):
-    suffix = ['th', 'st', 'nd', 'rd', 'th'][min(n % 10, 4)]
+    suffix = ["th", "st", "nd", "rd", "th"][min(n % 10, 4)]
     if 11 <= (n % 100) <= 13:
-        suffix = 'th'
+        suffix = "th"
     return str(n) + suffix
 
+
 def custom_date_format(dt):
     day = ordinal(dt.day)
-    month = dt.strftime('%B')
+    month = dt.strftime("%B")
     year = dt.year
-    time = dt.strftime('%H:%M:%S')
+    time = dt.strftime("%H:%M:%S")
     return f"{day} of {month} {year}, {time}"
 
+
 def custom_time_format(time_value):
     # Convert to Decimal for precise arithmetic
     time_value = Decimal(time_value)
@@ -120,6 +168,7 @@ def custom_time_format(time_value):
 
     return formatted_time
 
+
 def default_serializer(obj):
     if isinstance(obj, datetime):
         return custom_date_format(obj)

main.py

@@ -17,6 +17,7 @@
     token_auth_scheme,
     config,
     redis_client,
+    tags_metadata,
     WHITELISTED_IPS,
     append_request_log,
     append_denied_log,
@@ -34,18 +35,6 @@
 from surftimer.ck_playertemp import router as ck_playertemp_router
 
 
-# Responses
-class ResponseInsertQuery:
-    """This is to be used for all `INSERT` queries if possible"""
-
-    def __init__(self, inserted):
-        self.inserted = inserted
-
-    def to_dict(self):
-        """Makes it readable for `print()`"""
-        return {"inserted": self.inserted}
-
-
 class IPValidatorMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):
         # Get client IP
@@ -85,6 +74,7 @@ async def dispatch(self, request: Request, call_next):
     debug=True,
     swagger_ui_parameters=swagger_config,
     middleware=[Middleware(IPValidatorMiddleware)],
+    openapi_tags=tags_metadata,
 )
 
 
@@ -109,7 +99,7 @@ async def custom_swagger_ui_html_cdn():
     )
 
 
-@app.get("/")
+@app.get("/", include_in_schema=False)
 async def home():
     data = {"message": "Suuuuh duuuud"}
     return JSONResponse(status_code=status.HTTP_200_OK, content=data)

surftimer/ck_bonus.py

@@ -12,6 +12,8 @@
 
 
 class NewBonus(BaseModel):
+    """Body for adding a new **Bonus** time"""
+
     steamid32: str
     name: str
     mapname: str
@@ -22,14 +24,6 @@ class NewBonus(BaseModel):
     velStartZ: int
 
 
-class PlayerRankBonus(BaseModel):
-    """To be used for `selectPlayerRankBonus` endpoint"""
-
-    steamid32: str
-    mapname: str
-    zonegroup: int
-
-
 router = APIRouter()
 
 

surftimer/ck_checkpoints.py

@@ -9,6 +9,8 @@
 
 
 class PlayerCheckpoints(BaseModel):
+    """Body for adding or updating **Checkpoint** time"""
+
     steamid: str
     mapname: str
     cp: int
@@ -48,18 +50,18 @@ async def insertOrUpdateCheckpoints(
     )
     xquery = insertQuery(sql)
     content_data = {"inserted": xquery, "xtime": time.perf_counter() - tic}
-    
+
     if xquery < 1:
         # response.body = json.dumps(content_data).encode('utf-8')
-        response.headers['content-type'] = 'application/json'
+        response.headers["content-type"] = "application/json"
         response.status_code = status.HTTP_304_NOT_MODIFIED
         return response
 
     # Prepare the response
     toc = time.perf_counter()
     print(f"Execution time {toc - tic:0.4f}")
-    
-    response.body = json.dumps(content_data).encode('utf-8')
+
+    response.body = json.dumps(content_data).encode("utf-8")
     response.status_code = status.HTTP_201_CREATED
     return response
 
@@ -81,7 +83,8 @@ async def selectCheckpoints(
     if cached_data is not None:
         print(f"[Redis] Loaded '{cache_key}' ({time.perf_counter() - tic:0.4f}s)")
         return JSONResponse(
-            status_code=status.HTTP_200_OK, content=json.loads(cached_data, use_decimal=True, parse_nan=True)
+            status_code=status.HTTP_200_OK,
+            content=json.loads(cached_data, use_decimal=True, parse_nan=True),
         )
 
     xquery = selectQuery(
@@ -126,7 +129,8 @@ async def selectCheckpointsinZoneGroup(
     if cached_data is not None:
         print(f"[Redis] Loaded '{cache_key}' ({time.perf_counter() - tic:0.4f}s)")
         return JSONResponse(
-            status_code=status.HTTP_200_OK, content=json.loads(cached_data, use_decimal=True, parse_nan=True)
+            status_code=status.HTTP_200_OK,
+            content=json.loads(cached_data, use_decimal=True, parse_nan=True),
         )
 
     xquery = selectQuery(
@@ -168,7 +172,8 @@ async def selectRecordCheckpoints(
     if cached_data is not None:
         print(f"[Redis] Loaded '{cache_key}' ({time.perf_counter() - tic:0.4f}s)")
         return JSONResponse(
-            status_code=status.HTTP_200_OK, content=json.loads(cached_data, use_decimal=True, parse_nan=True)
+            status_code=status.HTTP_200_OK,
+            content=json.loads(cached_data, use_decimal=True, parse_nan=True),
         )
 
     xquery = selectQuery(
@@ -211,18 +216,19 @@ async def deleteCheckpoints(
     content_data = {"deleted": xquery, "xtime": time.perf_counter() - tic}
     if xquery < 1:
         # response.body = json.dumps(content_data).encode('utf-8')
-        response.headers['content-type'] = 'application/json'
+        response.headers["content-type"] = "application/json"
         response.status_code = status.HTTP_304_NOT_MODIFIED
         return response
 
     toc = time.perf_counter()
     print(f"Execution time {toc - tic:0.4f}")
 
-    response.body = json.dumps(content_data).encode('utf-8')
-    response.headers['content-type'] = 'application/json'
+    response.body = json.dumps(content_data).encode("utf-8")
+    response.headers["content-type"] = "application/json"
     response.status_code = status.HTTP_200_OK
     return response
 
+
 @router.get(
     "/surftimer/selectStageTimes",
     name="Get Stage Times",
@@ -240,7 +246,8 @@ async def selectStageTimes(
     if cached_data is not None:
         print(f"[Redis] Loaded '{cache_key}' ({time.perf_counter() - tic:0.4f}s)")
         return JSONResponse(
-            status_code=status.HTTP_200_OK, content=json.loads(cached_data, use_decimal=True, parse_nan=True)
+            status_code=status.HTTP_200_OK,
+            content=json.loads(cached_data, use_decimal=True, parse_nan=True),
         )
 
     xquery = selectQuery(
@@ -280,7 +287,8 @@ async def selectStageAttempts(
     if cached_data is not None:
         print(f"[Redis] Loaded '{cache_key}' ({time.perf_counter() - tic:0.4f}s)")
         return JSONResponse(
-            status_code=status.HTTP_200_OK, content=json.loads(cached_data, use_decimal=True, parse_nan=True)
+            status_code=status.HTTP_200_OK,
+            content=json.loads(cached_data, use_decimal=True, parse_nan=True),
         )
 
     xquery = selectQuery(

surftimer/ck_latestrecords.py

@@ -12,11 +12,14 @@
 
 
 class LatestRec(BaseModel):
+    """Body for adding or updating **latest record** entries"""
+
     steamid32: str
     name: str
     runtime: Decimal
     mapname: str
 
+
 # ck_latestrecords
 @router.get(
     "/surftimer/selectLatestRecords",
@@ -61,11 +64,7 @@ async def selectLatestRecord(request: Request, response: Response):
     name="Add Latest Record",
     tags=["ck_latestrecords"],
 )
-async def insertLatestRecord(
-    request: Request,
-    response: Response,
-    data: LatestRec
-):
+async def insertLatestRecord(request: Request, response: Response, data: LatestRec):
     """Inserts a new record to the table\n
     ```char sql_insertLatestRecords[] = ....```"""
     tic = time.perf_counter()
@@ -76,18 +75,18 @@ async def insertLatestRecord(
     xquery = insertQuery(sql)
     # xquery = 0
     # time.sleep(3)
-    
+
     content_data = {"inserted": xquery, "xtime": time.perf_counter() - tic}
     if xquery < 1:
         # response.body = json.dumps(content_data).encode('utf-8')
-        response.headers['content-type'] = 'application/json'
+        response.headers["content-type"] = "application/json"
         response.status_code = status.HTTP_304_NOT_MODIFIED
         return response
 
     # Prepare the response
     toc = time.perf_counter()
     print(f"Execution time {toc - tic:0.4f}")
 
-    response.body = json.dumps(content_data).encode('utf-8')
+    response.body = json.dumps(content_data).encode("utf-8")
     response.status_code = status.HTTP_201_CREATED
     return response