Show actionable Hugging Face persistence errors

classroom_service.py

@@ -1,6 +1,6 @@
 """Browser-side multi-file Python classroom for the Telearn demo Space."""
 from __future__ import annotations
-import asyncio, hmac, io, json, os, re, sqlite3, threading, time, zipfile
+import asyncio, hmac, io, json, logging, os, re, sqlite3, threading, time, zipfile
 from pathlib import Path, PurePosixPath
 from typing import Any
 from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
@@ -9,9 +9,9 @@ from pydantic import BaseModel
 
 ROOT=Path(__file__).resolve().parent; STATIC=ROOT/"classroom_static"; DATA=ROOT/"classroom_data"; TEMPLATES=DATA/"templates"; PUBLISHED=ROOT/"projects"
 RUNTIME=Path(os.getenv("CLASSROOM_DATA_DIR","/tmp/telearn_classroom")); DB=RUNTIME/"classroom.sqlite3"
-PASSWORD=os.getenv("CLASSROOM_TEACHER_PASSWORD",""); REPO=os.getenv("CLASSROOM_DEMO_REPO",os.getenv("SPACE_ID","Telearn/Project_Demo")); DEMO_CLASS=os.getenv("CLASSROOM_DEMO_CLASS","2026Fall進階專題"); TOKEN=os.getenv("HF_TOKEN","")
+PASSWORD=os.getenv("CLASSROOM_TEACHER_PASSWORD",""); REPO=os.getenv("CLASSROOM_DEMO_REPO",os.getenv("SPACE_ID","Telearn/Project_Demo")).strip(); DEMO_CLASS=os.getenv("CLASSROOM_DEMO_CLASS","2026Fall進階專題"); TOKEN=os.getenv("HF_TOKEN","").strip()
 ALLOWED={".py",".json",".txt",".csv",".md",".toml",".yaml",".yml"}; ID_RE=re.compile(r"[^0-9A-Za-z_\-一-鿿]")
-router=APIRouter(); lock=threading.Lock(); students={}; teachers={}; live={}
+router=APIRouter(); lock=threading.Lock(); students={}; teachers={}; live={}; logger=logging.getLogger(__name__)
 
 class TeacherRequest(BaseModel): class_code:str; week_id:str; password:str
 class CourseCreate(BaseModel): class_code:str; course_name:str=""; password:str
@@ -86,6 +86,17 @@ def published_progress(display_name):
 def check_password(p):
     if not PASSWORD:raise HTTPException(503,"請先在 Space Secrets 設定 CLASSROOM_TEACHER_PASSWORD")
     if not hmac.compare_digest(p,PASSWORD):raise HTTPException(403,"教師密碼不正確")
+def hf_failure_message(exc):
+    """Return an actionable message without ever exposing a token."""
+    status=getattr(getattr(exc,"response",None),"status_code",None)
+    detail=getattr(exc,"server_message",None) or str(exc) or type(exc).__name__
+    detail=re.sub(r"hf_[A-Za-z0-9]+","hf_***",re.sub(r"\s+"," ",detail)).strip()[:220]
+    if status==401:reason="HF_TOKEN 未被 Space 正確載入、已失效或貼入值不正確"
+    elif status==403:reason=f"HF_TOKEN 已被載入，但對 {REPO} 的 Space 寫入驗證被拒絕"
+    elif status==404:reason=f"找不到目標 Space {REPO}，請檢查 CLASSROOM_DEMO_REPO 或 SPACE_ID"
+    else:reason=f"連線到 Hugging Face 時發生 {type(exc).__name__}"
+    suffix=f"HTTP {status}：{detail}" if status else detail
+    return f"課程已可使用，但尚未永久寫入 Space。{reason}。詳情：{suffix}"
 def finals(c,w):return [x for x in snapshot(c,w) if x.get("final_files")]
 def make_zip(c,w):
     b=io.BytesIO()
@@ -118,8 +129,9 @@ def create_class(req:CourseCreate):
             from huggingface_hub import CommitOperationAdd,HfApi
             payload=json.dumps([{"code":c,"name":n} for c,n in rows],ensure_ascii=False,indent=2)+"\n"
             HfApi(token=TOKEN).create_commit(repo_id=REPO,repo_type="space",operations=[CommitOperationAdd(path_in_repo="classroom_data/classes.json",path_or_fileobj=payload.encode())],commit_message=f"Add classroom course {code}")
-        except Exception:
-            warning="課程已可使用，但尚未永久寫入 Space；請檢查 HF_TOKEN 的寫入權限。"
+        except Exception as exc:
+            logger.exception("Could not persist classroom course catalog to %s",REPO)
+            warning=hf_failure_message(exc)
     else:warning="課程已可使用，但尚未永久寫入 Space；請設定 HF_TOKEN。"
     return {"ok":True,"class_code":code,"course_name":name,"already_exists":bool(existing),"warning":warning}
 @router.delete("/api/classroom/students")

tests/test_classroom.py

@@ -5,6 +5,7 @@ import tempfile
 import unittest
 import zipfile
 from pathlib import Path
+from types import SimpleNamespace
 
 import classroom_service as classroom
 
@@ -115,6 +116,20 @@ class ClassroomServiceTests(unittest.TestCase):
         course = next(item for item in classroom.catalog()["courses"] if item["class_code"] == "L6B")
         self.assertEqual(course["course_name"], "週六進階班")
 
+    def test_hf_failure_message_distinguishes_authentication_and_permission(self):
+        unauthorized = RuntimeError("token hf_should_never_leak was rejected")
+        unauthorized.response = SimpleNamespace(status_code=401)
+        forbidden = RuntimeError("Forbidden")
+        forbidden.response = SimpleNamespace(status_code=403)
+
+        unauthorized_message = classroom.hf_failure_message(unauthorized)
+        forbidden_message = classroom.hf_failure_message(forbidden)
+
+        self.assertIn("HF_TOKEN 未被 Space 正確載入", unauthorized_message)
+        self.assertNotIn("hf_should_never_leak", unauthorized_message)
+        self.assertIn(classroom.REPO, forbidden_message)
+        self.assertIn("寫入驗證被拒絕", forbidden_message)
+
     def test_published_final_can_be_loaded_after_runtime_restart(self):
         old_published = classroom.PUBLISHED
         try: