refactor: 提高可維護性、移除多餘的括弧

src/api/constant/__init__.py

@@ -0,0 +1 @@
+from . import buses, general

src/api/constant/buses.py

@@ -0,0 +1,14 @@
+from fastapi import Path, Query
+
+# for routers/buses.py
+DEFAULT_LIMIT_DAY_CURRENT = 5
+BUS_TYPE_PATH = Path(..., example="main", description="車種選擇 校本部公車 或 南大區間車")
+BUS_DIRECTION_PATH = Path(..., example="up", description="上山或下山")
+BUS_TYPE_QUERY = Query(..., example="main", description="車種選擇 校本部公車 或 南大區間車")
+BUS_DAY_QUERY = Query(
+    ...,
+    example="weekday",
+    description=f"平日、假日或目前時刻。選擇 current 預設回傳 {DEFAULT_LIMIT_DAY_CURRENT} 筆資料。",
+)
+BUS_DIRECTION_QUERY = Query(..., example="up", description="上山或下山")
+STOPS_NAME_PATH = Path(..., example="北校門口", description="公車站牌名稱")

src/api/constant/general.py

@@ -0,0 +1,4 @@
+from fastapi import Query
+
+# for all routers
+LIMITS_QUERY = Query(None, ge=1, example=5, description="最大回傳資料筆數")

src/api/models/buses.py

@@ -242,17 +242,17 @@ def get_main_data(self) -> dict:
         main_dataset = {
             "toward_TSMC_building_info": self.info_data.loc[("main", "up"), "data"][0],
             "weekday_bus_schedule_toward_TSMC_building": self.raw_schedule_data.loc[
-                (("main", "weekday", "up")), "data"
+                ("main", "weekday", "up"), "data"
             ],
             "weekend_bus_schedule_toward_TSMC_building": self.raw_schedule_data.loc[
-                (("main", "weekend", "up")), "data"
+                ("main", "weekend", "up"), "data"
             ],
             "toward_main_gate_info": self.info_data.loc[("main", "down"), "data"][0],
             "weekday_bus_schedule_toward_main_gate": self.raw_schedule_data.loc[
-                (("main", "weekday", "down")), "data"
+                ("main", "weekday", "down"), "data"
             ],
             "weekend_bus_schedule_toward_main_gate": self.raw_schedule_data.loc[
-                (("main", "weekend", "down")), "data"
+                ("main", "weekend", "down"), "data"
             ],
         }
 
@@ -263,17 +263,17 @@ def get_nanda_data(self) -> dict:
         nanda_dataset = {
             "toward_south_campus_info": self.info_data.loc[("nanda", "up"), "data"][0],
             "weekday_bus_schedule_toward_south_campus": self.raw_schedule_data.loc[
-                (("nanda", "weekday", "up")), "data"
+                ("nanda", "weekday", "up"), "data"
             ],
             "weekend_bus_schedule_toward_south_campus": self.raw_schedule_data.loc[
-                (("nanda", "weekend", "up")), "data"
+                ("nanda", "weekend", "up"), "data"
             ],
             "toward_main_campus_info": self.info_data.loc[("nanda", "down"), "data"][0],
             "weekday_bus_schedule_toward_main_campus": self.raw_schedule_data.loc[
-                (("nanda", "weekday", "down")), "data"
+                ("nanda", "weekday", "down"), "data"
             ],
             "weekend_bus_schedule_toward_main_campus": self.raw_schedule_data.loc[
-                (("nanda", "weekend", "down")), "data"
+                ("nanda", "weekend", "down"), "data"
             ],
         }
 

src/api/routers/buses.py

@@ -1,14 +1,13 @@
 from datetime import datetime
-from typing import Literal, Optional
+from typing import Literal
 
-from fastapi import APIRouter, Depends, Path, Query
+from fastapi import APIRouter, Depends
 
-from src.api import schemas
+from src.api import constant, schemas
 from src.api.models.buses import Buses, after_specific_time, stops
 
 router = APIRouter()
 buses = Buses()
-DEFAULT_LIMIT_DAY_CURRENT = 5
 
 
 def get_current_time_state():
@@ -41,12 +40,8 @@ def get_nanda():
     response_model=list[schemas.buses.BusInfo],
 )
 def get_bus_info(
-    bus_type: Literal["main", "nanda"] = Path(
-        ..., example="main", description="車種選擇 校本部公車 或 南大區間車"
-    ),
-    direction: schemas.buses.BusDirection = Path(
-        ..., example="up", description="上山或下山"
-    ),
+    bus_type: Literal["main", "nanda"] = constant.buses.BUS_TYPE_PATH,
+    direction: schemas.buses.BusDirection = constant.buses.BUS_DIRECTION_PATH,
 ):
     """
     取得公車時刻表。
@@ -62,17 +57,9 @@ def get_bus_info(
     ],
 )
 def get_bus_schedule(
-    bus_type: schemas.buses.BusType = Query(
-        ..., example="main", description="車種選擇 校本部公車 或 南大區間車"
-    ),
-    day: schemas.buses.BusDayWithCurrent = Query(
-        ...,
-        example="weekday",
-        description=f"平日、假日或目前時刻。選擇 current 預設回傳 {DEFAULT_LIMIT_DAY_CURRENT} 筆資料。",
-    ),
-    direction: schemas.buses.BusDirection = Query(
-        ..., example="up", description="上山或下山"
-    ),
+    bus_type: schemas.buses.BusType = constant.buses.BUS_TYPE_QUERY,
+    day: schemas.buses.BusDayWithCurrent = constant.buses.BUS_DAY_QUERY,
+    direction: schemas.buses.BusDirection = constant.buses.BUS_DIRECTION_QUERY,
 ):
     """
     取得公車時刻表。
@@ -90,28 +77,18 @@ def get_bus_schedule(
             ["time"],
         )
 
-        return res[:DEFAULT_LIMIT_DAY_CURRENT]
+        return res[: constant.buses.DEFAULT_LIMIT_DAY_CURRENT]
 
 
 @router.get(
     "/stops/{stop_name}/",
     response_model=list[schemas.buses.BusStopsQueryResult | None],
 )
 def get_stop_bus(
-    stop_name: schemas.buses.StopsName = Path(
-        ..., example="北校門口", description="公車站牌名稱"
-    ),
-    bus_type: schemas.buses.BusType = Query(
-        ..., example="main", description="車種選擇 校本部公車 或 南大區間車"
-    ),
-    day: schemas.buses.BusDayWithCurrent = Query(
-        ...,
-        example="weekday",
-        description=f"平日、假日或目前時刻。選擇 current 預設回傳 {DEFAULT_LIMIT_DAY_CURRENT} 筆資料。",
-    ),
-    direction: schemas.buses.BusDirection = Query(
-        ..., example="up", description="上山或下山"
-    ),
+    stop_name: schemas.buses.StopsName = constant.buses.STOPS_NAME_PATH,
+    bus_type: schemas.buses.BusType = constant.buses.BUS_TYPE_QUERY,
+    day: schemas.buses.BusDayWithCurrent = constant.buses.BUS_DAY_QUERY,
+    direction: schemas.buses.BusDirection = constant.buses.BUS_DIRECTION_QUERY,
     query: schemas.buses.BusQuery = Depends(),
 ):
     """
@@ -122,7 +99,7 @@ def get_stop_bus(
     return_limit = (
         query.limits
         if day != "current"
-        else min(filter(None, (query.limits, DEFAULT_LIMIT_DAY_CURRENT)))
+        else min(filter(None, (query.limits, constant.buses.DEFAULT_LIMIT_DAY_CURRENT)))
     )
     find_day, after_time = (
         (day, query.time) if day != "current" else get_current_time_state()
@@ -144,17 +121,9 @@ def get_stop_bus(
     ],
 )
 def get_bus_detailed_schedule(
-    bus_type: schemas.buses.BusType = Query(
-        ..., example="main", description="車種選擇 校本部公車 或 南大區間車"
-    ),
-    day: schemas.buses.BusDayWithCurrent = Query(
-        ...,
-        example="weekday",
-        description=f"平日、假日或目前時刻。選擇 current 預設回傳 {DEFAULT_LIMIT_DAY_CURRENT} 筆資料。",
-    ),
-    direction: schemas.buses.BusDirection = Query(
-        ..., example="up", description="上山或下山"
-    ),
+    bus_type: schemas.buses.BusType = constant.buses.BUS_TYPE_QUERY,
+    day: schemas.buses.BusDayWithCurrent = constant.buses.BUS_DAY_QUERY,
+    direction: schemas.buses.BusDirection = constant.buses.BUS_DIRECTION_QUERY,
     query: schemas.buses.BusQuery = Depends(),
 ):
     """
@@ -165,7 +134,7 @@ def get_bus_detailed_schedule(
     return_limit = (
         query.limits
         if day != "current"
-        else min(filter(None, (query.limits, DEFAULT_LIMIT_DAY_CURRENT)))
+        else min(filter(None, (query.limits, constant.buses.DEFAULT_LIMIT_DAY_CURRENT)))
     )
     find_day, after_time = (
         (day, query.time) if day != "current" else get_current_time_state()

src/api/routers/courses.py

@@ -1,17 +1,16 @@
 from fastapi import APIRouter, Body, HTTPException, Path, Query, Response
 
-from src.api import schemas
+from src.api import constant, schemas
 from src.api.models.courses import Conditions, Processor
 
 router = APIRouter()
 courses = Processor(json_path="data/courses/11210.json")
-DESCRIPTION_OF_LIMITS = "最大回傳資料筆數"
 
 
 @router.get("/", response_model=list[schemas.courses.CourseData])
 async def get_all_courses_list(
     response: Response,
-    limits: int = Query(None, ge=1, example=5, description=DESCRIPTION_OF_LIMITS),
+    limits: int = constant.general.LIMITS_QUERY,
 ):
     """
     取得所有課程。
@@ -54,7 +53,7 @@ async def get_selected_fields_list(
     field_name: schemas.courses.CourseFieldName = Path(
         ..., example="id", description="欄位名稱"
     ),
-    limits: int = Query(None, ge=1, example=20, description=DESCRIPTION_OF_LIMITS),
+    limits: int = constant.general.LIMITS_QUERY,
 ):
     """
     取得指定欄位的列表。
@@ -71,7 +70,7 @@ async def get_selected_field_and_value_data(
         ..., example="chinese_title", description="搜尋的欄位名稱"
     ),
     value: str = Path(..., example="產業創新與生涯探索", description="搜尋的值"),
-    limits: int = Query(None, ge=1, example=5, description=DESCRIPTION_OF_LIMITS),
+    limits: int = constant.general.LIMITS_QUERY,
 ):
     """
     取得指定欄位滿足搜尋值的課程列表。
@@ -85,7 +84,7 @@ async def get_selected_field_and_value_data(
 async def get_courses_list(
     list_name: schemas.courses.CourseListName,
     response: Response,
-    limits: int = Query(None, ge=1, example=5, description=DESCRIPTION_OF_LIMITS),
+    limits: int = constant.general.LIMITS_QUERY,
 ) -> list[schemas.courses.CourseData]:
     """
     取得指定類型的課程列表。
@@ -111,7 +110,7 @@ async def search_by_field_and_value(
         description="搜尋的欄位名稱",
     ),
     value: str = Query(..., example="產業.+生涯", description="搜尋的值（可以使用 Regex，正則表達式）"),
-    limits: int = Query(None, ge=1, example=5, description=DESCRIPTION_OF_LIMITS),
+    limits: int = constant.general.LIMITS_QUERY,
 ):
     """
     取得指定欄位滿足搜尋值的課程列表。
@@ -184,7 +183,7 @@ async def get_courses_by_condition(
             },
         }
     ),
-    limits: int = Query(None, ge=1, example=5, description=DESCRIPTION_OF_LIMITS),
+    limits: int = constant.general.LIMITS_QUERY,
 ):
     """
     根據條件取得課程。