switching from optional response_model to mandatory return type

src/db/crud.py

@@ -87,10 +87,10 @@ def count_by_user_since(db: Session, seconds_delta: int = 15):
 
 
 def base_query(db: Session):
-    # TODO: allow only some fields to be returned, for example author should remain hidden
+    #NOTE: load_only is for optimization and not obfuscation, use .with_entities() if needed
     return db.query(models.Archive)\
-        .options(load_only(models.Archive.id, models.Archive.created_at, models.Archive.url, models.Archive.result))\
+        .filter(models.Archive.deleted == False)\
-        .filter(models.Archive.deleted == False)
+        .options(load_only(models.Archive.id, models.Archive.created_at, models.Archive.url, models.Archive.result))
 
 # --------------- TAG
 

src/db/schemas.py

@@ -45,6 +45,13 @@ class SubmitManual(BaseModel):
     group_id: str | None = None
     tags: set[str] | None = set()
 
+# API RESPONSES BELOW
+class ArchiveResult(BaseModel):
+    id: str
+    url: str
+    result: dict
+    created_at: datetime
+
 class Task(BaseModel):
     id: str
 

src/endpoints/default.py

@@ -30,13 +30,13 @@ async def health():
     return JSONResponse({"status": "ok"})
 
 
-@default_router.get("/user/active", summary="Check if the user is active and can use the tool.", response_model=schemas.ActiveUser)
+@default_router.get("/user/active", summary="Check if the user is active and can use the tool.")
-async def active(db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)):
+async def active(db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)) -> schemas.ActiveUser:
     return {"active": crud.is_active_user(db, email)}
 
 
-@default_router.get("/groups", response_model=list[str])
+@default_router.get("/groups")
-def get_user_groups(db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)):
+def get_user_groups(db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)) -> list[str]:
     return crud.get_user_groups(db, email)
 
 

src/endpoints/sheet.py

@@ -12,8 +12,8 @@ from worker.main import create_sheet_task
 sheet_router = APIRouter(prefix="/sheet", tags=["Google Spreadsheet operations"])
 
 
-@sheet_router.post("/archive", status_code=201, summary="Submit a Google Sheet archive request, starts a sheet archiving task.", response_model=schemas.Task, response_description="task_id for the archiving task.")
+@sheet_router.post("/archive", status_code=201, summary="Submit a Google Sheet archive request, starts a sheet archiving task.", response_description="task_id for the archiving task.")
-def archive_sheet(sheet:schemas.SubmitSheet, email = Depends(get_token_or_user_auth)):
+def archive_sheet(sheet:schemas.SubmitSheet, email = Depends(get_token_or_user_auth)) -> schemas.Task:
     logger.info(f"SHEET TASK for {sheet=}")
     if email == ALLOW_ANY_EMAIL:
         email = sheet.author_id or "api-endpoint"

src/endpoints/task.py

@@ -14,8 +14,8 @@ from worker.main import celery
 task_router = APIRouter(prefix="/task", tags=["Async task operations"])
 
 
-@task_router.get("/{task_id}", response_model=schemas.TaskResult, summary="Check the status of an async task by its id, works for URLs and Sheet tasks.")
+@task_router.get("/{task_id}", summary="Check the status of an async task by its id, works for URLs and Sheet tasks.")
-def get_status(task_id, email=Depends(get_token_or_user_auth)):
+def get_status(task_id, email=Depends(get_token_or_user_auth)) -> schemas.TaskResult:
     logger.info(f"status check for user {email} task {task_id}")
     task = AsyncResult(task_id, app=celery)
     try:

src/endpoints/url.py

@@ -15,8 +15,8 @@ from worker.main import create_archive_task
 url_router = APIRouter(prefix="/url", tags=["Single URL operations"])
 
 
-@url_router.post("/archive", status_code=201, summary="Submit a single URL archive request, starts an archiving task.", response_model=schemas.Task, response_description="task_id for the archiving task, will match the archive id.")
+@url_router.post("/archive", status_code=201, summary="Submit a single URL archive request, starts an archiving task.", response_description="task_id for the archiving task, will match the archive id.")
-def archive_url(archive: schemas.ArchiveCreate, email=Depends(get_token_or_user_auth)):
+def archive_url(archive: schemas.ArchiveCreate, email=Depends(get_token_or_user_auth)) -> schemas.Task:
     archive.author_id = email
     url = archive.url
     logger.info(f"new {archive.public=} task for {email=} and {archive.group_id=}: {url}")
@@ -28,30 +28,31 @@ def archive_url(archive: schemas.ArchiveCreate, email=Depends(get_token_or_user_
     return JSONResponse(task_response.model_dump(), status_code=201)
 
 
-@url_router.get("/search", response_model=list[schemas.Archive], summary="Search for archive entries by URL.")
+@url_router.get("/search", summary="Search for archive entries by URL.")
 def search_by_url(
         url: str, skip: int = 0, limit: int = 25,
         archived_after: datetime = None, archived_before: datetime = None,
         db: Session = Depends(get_db_dependency),
-        email=Depends(get_token_or_user_auth)):
+        email=Depends(get_token_or_user_auth)
+) -> list[schemas.ArchiveResult]:
     return crud.search_archives_by_url(db, url.strip(), email, skip=skip, limit=limit, archived_after=archived_after, archived_before=archived_before)
 
 
-@url_router.get("/latest", response_model=list[schemas.Archive], summary="Fetch latest URL archives for the authenticated user.")
+@url_router.get("/latest", summary="Fetch latest URL archives for the authenticated user.")
-def latest(skip: int = 0, limit: int = 25, db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)):
+def latest(skip: int = 0, limit: int = 25, db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)) -> list[schemas.ArchiveResult]:
     return crud.search_archives_by_email(db, email, skip=skip, limit=limit)
 
 
-@url_router.get("/{id}", response_model=schemas.Archive, summary="Fetch a single URL archive by the associated id.")
+@url_router.get("/{id}", summary="Fetch a single URL archive by the associated id.")
-def lookup(id, db: Session = Depends(get_db_dependency), email=Depends(get_token_or_user_auth)):
+def lookup(id, db: Session = Depends(get_db_dependency), email=Depends(get_token_or_user_auth)) -> schemas.ArchiveResult:
     archive = crud.get_archive(db, id, email)
     if archive is None:
         raise HTTPException(status_code=404, detail="Archive not found")
     return archive
 
 
-@url_router.delete("/{id}", response_model=schemas.TaskDelete, summary="Delete a single URL archive by id.")
+@url_router.delete("/{id}", summary="Delete a single URL archive by id.")
-def delete_task(id, db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)):
+def delete_task(id, db: Session = Depends(get_db_dependency), email=Depends(get_user_auth)) -> schemas.TaskDelete:
     logger.info(f"deleting url archive task {id} request by {email}")
     return JSONResponse({
         "id": id,

src/tests/endpoints/test_url.py

@@ -38,7 +38,7 @@ def test_search_by_url(client_with_auth, db_session):
     assert response.status_code == 200
     assert response.json() == []
 
-    from db import crud
+    from db import crud, schemas
     for i in range(11):
         crud.create_task(db_session, ArchiveCreate(id=f"url-456-{i}", url="https://example.com" if i < 10 else "https://something-else.com", result={}, public=True, author_id="rick@example.com", group_id=None), [], [])
         #NB: this insertion is too fast for the ordering to be correct as they are within the same second
@@ -49,6 +49,7 @@ def test_search_by_url(client_with_auth, db_session):
     assert "url-456-0" in [i["id"] for i in j]
     assert "url-456-9" in [i["id"] for i in j]
     assert "url-456-10" not in [i["id"] for i in j]
+    assert j[0].keys() == schemas.ArchiveResult.model_fields.keys()
 
     response = client_with_auth.get("/url/search?url=https://example.com&limit=5")
     assert response.status_code == 200
@@ -76,7 +77,7 @@ def test_latest(client_with_auth, db_session):
     assert response.status_code == 200
     assert response.json() == []
 
-    from db import crud
+    from db import crud, schemas
     for i in range(11):
         crud.create_task(db_session, ArchiveCreate(id=f"latest-456-{i}", url="https://example.com", result={}, public=True, author_id="morty@example.com" if i < 10 else "rick@example.com", group_id=None), [], [])
         #NB: this insertion is too fast for the ordering to be correct as they are within the same second
@@ -90,6 +91,7 @@ def test_latest(client_with_auth, db_session):
     assert "latest-456-0" in [i["id"] for i in j]
     assert "latest-456-9" in [i["id"] for i in j]
     assert "latest-456-10" not in [i["id"] for i in j]
+    assert j[0].keys() == schemas.ArchiveResult.model_fields.keys()
 
     response = client_with_auth.get("/url/latest?limit=5")
     assert response.status_code == 200
@@ -109,21 +111,16 @@ def test_lookup(client_with_auth, db_session):
     assert response.status_code == 404
     assert response.json() == {"detail": "Archive not found"}
 
-    from db import crud
+    from db import crud, schemas
     crud.create_task(db_session, ArchiveCreate(id="lookup-123-456-789", url="https://example.com", result={}, public=True, author_id="rick@example.com", group_id=None), [], [])
 
     response = client_with_auth.get("/url/lookup-123-456-789")
     assert response.status_code == 200
     j = response.json()
+    assert j.keys() == schemas.ArchiveResult.model_fields.keys()
     assert j["id"] == "lookup-123-456-789"
     assert j["url"] == "https://example.com"
     assert j["result"] == {}
-    assert j["public"] == True
-    assert j["author_id"] == "rick@example.com"
-    assert j["group_id"] == None
-    assert j["tags"] == []
-    assert j["updated_at"] == None
-    assert j["rearchive"] == True
 
 
 def test_delete_task_unauthenticated(client, test_no_auth):