From 21279f747c114f609efa11eb28a1cbbf1bb824d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rn-Michael=20Miehe?= <jmm@yavook.de>
Date: Fri, 8 Sep 2023 19:44:41 +0000
Subject: [PATCH] documentation

---
 api/advent22_api/routers/_security.py | 29 +++++++++++++++++++--------
 api/advent22_api/routers/days.py      |  6 +++---
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/api/advent22_api/routers/_security.py b/api/advent22_api/routers/_security.py
index aff2ab5..1bfcbe2 100644
--- a/api/advent22_api/routers/_security.py
+++ b/api/advent22_api/routers/_security.py
@@ -11,13 +11,14 @@ security = HTTPBasic()
 
 async def user_is_admin(
     credentials: HTTPBasicCredentials = Depends(security),
-    config: Config = Depends(Config.get_config),
+    cfg: Config = Depends(Config.get_config),
 ) -> bool:
-    username_correct = secrets.compare_digest(credentials.username, config.admin.name)
+    """
+    True iff der user "admin" ist
+    """
 
-    password_correct = secrets.compare_digest(
-        credentials.password, config.admin.password
-    )
+    username_correct = secrets.compare_digest(credentials.username, cfg.admin.name)
+    password_correct = secrets.compare_digest(credentials.password, cfg.admin.password)
 
     return username_correct and password_correct
 
@@ -25,11 +26,19 @@ async def user_is_admin(
 async def require_admin(
     is_admin: bool = Depends(user_is_admin),
 ) -> None:
+    """
+    HTTP 401 iff der user nicht "admin" ist
+    """
+
     if not is_admin:
         raise HTTPException(status.HTTP_401_UNAUTHORIZED)
 
 
-async def user_visible_days() -> int:
+async def user_visible_doors() -> int:
+    """
+    Anzahl der user-sichtbaren Türchen
+    """
+
     today = date.today()
 
     if today.month == 12:
@@ -41,7 +50,11 @@ async def user_visible_days() -> int:
     return 0
 
 
-async def user_can_view_day(
+async def user_can_view_door(
     day: int,
 ) -> bool:
-    return day < await user_visible_days()
+    """
+    True iff das Türchen von Tag `day` user-sichtbar ist
+    """
+
+    return day < await user_visible_doors()
diff --git a/api/advent22_api/routers/days.py b/api/advent22_api/routers/days.py
index 991d66f..d74ae26 100644
--- a/api/advent22_api/routers/days.py
+++ b/api/advent22_api/routers/days.py
@@ -7,7 +7,7 @@ from PIL import Image
 from ..core.config import Config
 from ..core.depends import get_image, get_part, shuffle_solution
 from ..core.image_helpers import api_return_image
-from ._security import user_can_view_day, user_is_admin, user_visible_days
+from ._security import user_can_view_door, user_is_admin, user_visible_doors
 
 router = APIRouter(prefix="/days", tags=["days"])
 
@@ -36,7 +36,7 @@ async def get_visible_days() -> int:
     Sichtbare Türchen
     """
 
-    return await user_visible_days()
+    return await user_visible_doors()
 
 
 @router.get("/part/{day}")
@@ -56,7 +56,7 @@ async def get_part_for_day(
 )
 async def get_image_for_day(
     image: Image.Image = Depends(get_image),
-    can_view: bool = Depends(user_can_view_day),
+    can_view: bool = Depends(user_can_view_door),
     is_admin: bool = Depends(user_is_admin),
 ) -> StreamingResponse:
     """