bb-sync 1.9.0__py3-none-any.whl

bb_sync/__init__.py

@@ -0,0 +1,23 @@
+"""bb-sync — Blackboard 课程资源自动同步。
+
+对外暴露版本号与核心异常，具体功能走各子包：
+
+- :mod:`bb_sync.cli`            Typer 命令行入口
+- :mod:`bb_sync.core`           配置、输出、异常等基础设施
+- :mod:`bb_sync.blackboard`     Blackboard 站点交互（登录 / 抓取 / 下载）
+- :mod:`bb_sync.browser`        Steel 浏览器后端
+"""
+
+from __future__ import annotations
+
+import importlib.metadata as metadata
+
+try:
+    __version__ = metadata.version("bb-sync")
+except metadata.PackageNotFoundError:  # 源码直跑、未安装时
+    __version__ = "0.0.0.dev0"
+
+#: 问题反馈入口；错误提示统一引用，避免多处硬编码
+ISSUES_URL = "https://github.com/asdukw/cuhk-shenzhen-blackboard-sync/issues"
+
+__all__ = ["ISSUES_URL", "__version__"]

bb_sync/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m bb_sync` 等价于 `bb-sync`。"""
+
+from __future__ import annotations
+
+from bb_sync.cli import main
+
+if __name__ == "__main__":
+    main()

bb_sync/blackboard/__init__.py

@@ -0,0 +1,5 @@
+"""Blackboard 站点交互：登录、课程抓取、文件下载。"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

bb_sync/blackboard/downloader.py

@@ -0,0 +1,348 @@
+"""附件下载：文件名推断、类型嗅探、增量去重、浏览器原生流式落盘。
+
+服务器常返回 ``application/octet-stream``，且 BB 条目标题往往没有扩展名
+（就叫 "Lec 01"），所以文件名按以下优先级推断：
+
+1. 链接文本
+2. ``Content-Disposition`` 里的 ``filename``
+3. URL 末段
+
+再依次用 ``Content-Type`` → **文件头嗅探** → URL 末段后缀 补全扩展名。
+
+下载分两步走：
+
+- **探测**：``HEAD`` 廉价拿文件名与大小，先做增量去重；名字缺扩展名时才补读文件头。
+- **下载**：确实需要新文件时，用页面里的 ``<a download>`` 触发 Chrome 自身下载，
+  由浏览器把文件**直接流式写到磁盘**（不再把整个文件读进内存）。落盘统一先写
+  ``.part`` 再 ``os.replace`` 原子替换。
+
+选择浏览器通道而不是自建 HTTP 客户端的原因：下载与登录共用同一套浏览器网络栈和
+cookie，不会出现「浏览器能下、脚本直连被 TLS/代理拒绝」这类不一致（实测踩到过）。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import mimetypes
+import os
+import re
+from pathlib import Path
+from urllib.parse import unquote
+
+from bb_sync.blackboard.models import FileItem
+from bb_sync.blackboard.scraper import sanitize_filename
+from bb_sync.core.errors import NetworkError
+
+#: 作业编号，用于归入 ``assignments/hwN/``
+HW_NUM = re.compile(r"(?:hw|home\s*work|set|assignment)\D{0,3}(\d{1,2})", re.I)
+
+#: 大于该体积的文件才参与「体积+后缀」去重
+SIZE_DEDUP_THRESHOLD = 50_000
+
+#: 视为「没给出真实扩展名」的后缀
+_UNKNOWN_SUFFIXES = {".bin", ".exe", ".dat"}
+
+#: 未完成下载的临时文件后缀；``build_index`` 会忽略它
+PART_SUFFIX = ".part"
+
+#: 判断类型/去重所需的最少字节数（覆盖 ipynb 的 ``"cells"`` 探测窗口）
+SNIFF_BYTES = 4096
+
+#: HEAD 探测 / 嗅探文件头的超时（毫秒）
+PROBE_TIMEOUT_MS = 30_000
+
+#: 等待浏览器「开始下载」的超时（毫秒）；超时即认为浏览器通道不可用并熔断
+DOWNLOAD_START_TIMEOUT_MS = 15_000
+
+#: 兜底路线整块读取的超时（毫秒）
+BUFFERED_TIMEOUT_MS = 60_000
+
+#: 在页面里触发浏览器下载：同源 URL + download 属性，无论服务端是否 attachment 都会下载
+_TRIGGER_DOWNLOAD_JS = """
+(url) => {
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = '';
+  a.style.display = 'none';
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}
+"""
+
+
+def sniff_ext(body: bytes) -> str | None:
+    """按文件头嗅探真实类型（服务器常返回 application/octet-stream）。"""
+    if body.startswith(b"%PDF"):
+        return ".pdf"
+    if body.startswith(b"PK\x03\x04"):
+        return ".zip"
+    if body.startswith(b"\xd0\xcf\x11\xe0"):
+        return ".doc"
+    head = body[:400].lstrip()
+    if head.startswith(b"{"):
+        if b'"cells"' in body[:4000]:
+            return ".ipynb"
+        return ".json"
+    if head.startswith(b"<?xml") or head.lower().startswith(b"<html"):
+        return ".xml"
+    if body.startswith(b"\x1f\x8b"):
+        return ".gz"
+    return None
+
+
+def _name_from_disposition(headers) -> str | None:
+    """从 ``Content-Disposition`` 提取文件名。"""
+    cd = str(headers.get("content-disposition", "") or "")
+    m = re.search(r"filename\*?=(?:UTF-8'')?\"?([^\";]+)", cd, re.I)
+    return unquote(m.group(1)) if m else None
+
+
+def _guess_extension(ctype: str, body: bytes, url: str) -> str | None:
+    """推断扩展名：Content-Type → 文件头 → URL 末段。"""
+    guess = mimetypes.guess_extension(ctype) if ctype else None
+    if guess in {None, ".bin", ".exe"}:
+        guess = sniff_ext(body)
+    if not guess:
+        tail = unquote(url.split("?")[0].rsplit("/", 1)[-1])
+        if "." in tail[-6:]:
+            guess = "." + tail.rsplit(".", 1)[-1].lower()
+    return guess
+
+
+def _finalize_name(item: FileItem, headers, head: bytes, url: str) -> str:
+    """由链接文本 / Content-Disposition / URL 推断并补全最终文件名。"""
+    name = (item.name or "").strip()
+    if not name or name.lower() in {"download", "untitled", "link"}:
+        name = _name_from_disposition(headers) or sanitize_filename(
+            unquote(url.split("?")[0].rsplit("/", 1)[-1]) or "file"
+        )
+
+    if not Path(name).suffix or Path(name).suffix.lower() in _UNKNOWN_SUFFIXES:
+        ctype = str(headers.get("content-type", "") or "").split(";")[0].strip()
+        guess = _guess_extension(ctype, head, url)
+        if guess:
+            base = name.rsplit(".", 1)[0] if Path(name).suffix else name
+            name = base + guess
+
+    return sanitize_filename(name)
+
+
+def _name_needs_sniff(name: str) -> bool:
+    """文件名是否还缺一个可信扩展名（需要读文件头来嗅探）。"""
+    suffix = Path(name).suffix.lower()
+    return not suffix or suffix in _UNKNOWN_SUFFIXES
+
+
+def build_index(course_dir: Path) -> dict[str, Path]:
+    """索引课程目录下已有文件，用于增量去重。
+
+    - 键 1：``文件名（小写）`` → 路径
+    - 键 2：``__size__<体积><后缀>`` → 路径（仅大文件，应对「同名不同内容/不同名同内容」）
+
+    ``.part`` 等未完成的临时文件不参与索引，避免被误判成「已存在」。
+    """
+    index: dict[str, Path] = {}
+    if not course_dir.exists():
+        return index
+    for path in course_dir.rglob("*"):
+        if not path.is_file() or ".git" in path.parts or ".venv" in path.parts:
+            continue
+        if path.name.endswith(PART_SUFFIX):
+            continue
+        index.setdefault(path.name.lower(), path)
+        try:
+            size = path.stat().st_size
+        except OSError:
+            continue
+        if size > SIZE_DEDUP_THRESHOLD:
+            index.setdefault(f"__size__{size}{path.suffix.lower()}", path)
+    return index
+
+
+def _remember(index: dict[str, Path] | None, name: str, path: Path, size: int) -> None:
+    """把本次新落盘的文件写回索引，供同一轮后续条目去重。"""
+    if index is None:
+        return
+    index.setdefault(name.lower(), path)
+    if size > SIZE_DEDUP_THRESHOLD:
+        index.setdefault(f"__size__{size}{path.suffix.lower()}", path)
+
+
+def _index_match(index: dict[str, Path] | None, name: str, size: int | None) -> Path | None:
+    """按「文件名」或「体积+后缀」在索引里找已存在文件。"""
+    if not index:
+        return None
+    found = index.get(name.lower())
+    if found is not None:
+        return found
+    if size is not None and size > SIZE_DEDUP_THRESHOLD:
+        return index.get(f"__size__{size}{Path(name).suffix.lower()}")
+    return None
+
+
+def _content_length(headers) -> int | None:
+    """读取 ``Content-Length``；缺失或非法时返回 None。"""
+    raw = headers.get("content-length")
+    if raw is None:
+        return None
+    try:
+        return int(str(raw).strip())
+    except ValueError:
+        return None
+
+
+def _category_dir(course_dir: Path, item: FileItem) -> Path:
+    """条目落盘目录；作业按 hwN 归档，对齐已有目录习惯。"""
+    cat_dir = course_dir / item.category
+    if item.category == "assignments" and item.name:
+        m = HW_NUM.search(item.name)
+        if m:
+            cat_dir = cat_dir / f"hw{int(m.group(1))}"
+    return cat_dir
+
+
+def _relpath(path: Path, course_dir: Path) -> str:
+    """相对课程目录的展示路径；跨盘等取不到相对路径时退回文件名。"""
+    try:
+        return str(path.relative_to(course_dir)).replace("\\", "/")
+    except ValueError:
+        return path.name
+
+
+class DownloadSession:
+    """一次同步复用的下载器（浏览器原生通道 + 整块读取兜底）。
+
+    - ``probe`` 只用 HEAD 拿文件名/大小，命中已有文件时**完全不下载体**
+    - 需要新下载时优先用浏览器原生下载，由 Chrome 直接流式写盘
+    - 浏览器下载在本轮首次失败后熔断，后续文件直接走整块读取，不再重复等待超时
+    """
+
+    def __init__(self, page, request_ctx) -> None:
+        self.page = page
+        self.request = request_ctx
+        self.browser_download_failed = False
+
+    def probe(self, item: FileItem) -> tuple[str, int | None]:
+        """探测文件名与大小：HEAD 优先，名字缺扩展名时才补读文件头。"""
+        headers: dict = {}
+        try:
+            resp = self.request.fetch(item.url, method="HEAD", timeout=PROBE_TIMEOUT_MS)
+            if resp.status < 400:
+                headers = dict(resp.headers)
+        except Exception:
+            headers = {}
+
+        head = b""
+        name = _finalize_name(item, headers, head, item.url)
+        if _name_needs_sniff(name):
+            head = self._peek_head(item.url)
+            if head:
+                name = _finalize_name(item, headers, head, item.url)
+        return name, _content_length(headers)
+
+    def _peek_head(self, url: str) -> bytes:
+        """读取文件头用于嗅探；服务端支持 Range 时只取几 KB。"""
+        try:
+            resp = self.request.get(
+                url, headers={"Range": f"bytes=0-{SNIFF_BYTES - 1}"}, timeout=PROBE_TIMEOUT_MS
+            )
+            return resp.body()[:SNIFF_BYTES]
+        except Exception:
+            return b""
+
+    def download_item(
+        self,
+        item: FileItem,
+        course_dir: Path,
+        dry_run: bool,
+        index: dict[str, Path] | None = None,
+    ) -> tuple[str, str]:
+        """下载单个条目，返回 ``(状态, 名称)``。
+
+        状态取值：``downloaded`` / ``exists`` / ``would-download`` / ``empty``。
+        """
+        cat_dir = _category_dir(course_dir, item)
+        name, size = self.probe(item)
+
+        already = _index_match(index, name, size)
+        if already is not None:
+            return ("exists", _relpath(already, course_dir))
+        target = cat_dir / name
+        if target.exists():
+            return ("exists", target.name)
+        if dry_run:
+            return ("would-download", name)
+        if size == 0:
+            return ("empty", name)
+
+        part = target.with_name(target.name + PART_SUFFIX)
+        part.parent.mkdir(parents=True, exist_ok=True)
+        with contextlib.suppress(OSError):
+            part.unlink()
+
+        if not self._fetch_body(item.url, part):
+            raise NetworkError(f"下载失败：{name}", "检查网络或登录态后重试 bb-sync run")
+
+        written = part.stat().st_size
+        if written == 0:
+            with contextlib.suppress(OSError):
+                part.unlink()
+            return ("empty", name)
+        if size is not None and written != size:
+            with contextlib.suppress(OSError):
+                part.unlink()
+            raise NetworkError(
+                f"下载不完整：{name}（预期 {size} 字节，实际 {written} 字节）",
+                "文件未落盘，重试 bb-sync run 即可",
+            )
+
+        os.replace(part, target)
+        _remember(index, name, target, written)
+        return ("downloaded", name)
+
+    def _fetch_body(self, url: str, part: Path) -> bool:
+        """取回文件体：优先浏览器原生下载，失败后本轮改用整块读取。"""
+        if not self.browser_download_failed:
+            if self._try_browser_download(url, part):
+                return True
+            self.browser_download_failed = True
+        return self._try_buffered(url, part)
+
+    def _try_browser_download(self, url: str, part: Path) -> bool:
+        """用页面里的 ``<a download>`` 触发浏览器下载，由 Chrome 流式写盘。"""
+        try:
+            with self.page.expect_download(timeout=DOWNLOAD_START_TIMEOUT_MS) as info:
+                self.page.evaluate(_TRIGGER_DOWNLOAD_JS, url)
+            download = info.value
+            download.save_as(str(part))
+            if download.failure() or not part.exists():
+                raise OSError("浏览器下载未完成")
+            return True
+        except Exception:
+            with contextlib.suppress(OSError):
+                part.unlink()
+            return False
+
+    def _try_buffered(self, url: str, part: Path) -> bool:
+        """兜底：用请求上下文整块读取后写盘。"""
+        try:
+            resp = self.request.get(url, timeout=BUFFERED_TIMEOUT_MS)
+            part.write_bytes(resp.body())
+        except Exception:
+            return False
+        return True
+
+
+__all__ = [
+    "BUFFERED_TIMEOUT_MS",
+    "DOWNLOAD_START_TIMEOUT_MS",
+    "DownloadSession",
+    "HW_NUM",
+    "PART_SUFFIX",
+    "PROBE_TIMEOUT_MS",
+    "SIZE_DEDUP_THRESHOLD",
+    "SNIFF_BYTES",
+    "build_index",
+    "sniff_ext",
+]

bb_sync/blackboard/login.py

@@ -0,0 +1,190 @@
+"""ADFS SSO 登录与登录态维护。
+
+Blackboard 的登录按钮跳到 ADFS（STS）OAuth2；ADFS 登录页是**分页式**的：
+第一页填账号 → 点「下一步」→ 第二页填密码 → 点「登录」。少数配置会显示在同一页，
+所以这里两种形态都兼容。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import getpass
+from pathlib import Path
+
+from playwright.sync_api import Page
+from playwright.sync_api import TimeoutError as PWTimeout
+
+from bb_sync import ISSUES_URL, paths
+from bb_sync.blackboard.models import (
+    _PORTAL_HOME,
+    ADFS_NEXT,
+    ADFS_PASS,
+    ADFS_SUBMIT,
+    ADFS_USER,
+    LOGIN_URL,
+)
+from bb_sync.core.errors import AuthError
+from bb_sync.core.output import Console
+from bb_sync.creds import Credentials, load_credentials, save_credentials
+
+#: Blackboard 主机名；用于判断当前页面是否已回到站点
+BB_HOST = "bb.cuhk.edu.cn"
+
+
+def _on_blackboard(page: Page) -> bool:
+    """当前是否已停在 Blackboard（而非登录页 / ADFS / STS）。"""
+    url = page.url.lower()
+    return BB_HOST in url and not any(marker in url for marker in ("login", "adfs", "sts."))
+
+
+def is_logged_in(page: Page) -> bool:
+    """访问门户首页，判断登录态是否有效。
+
+    判定依据是「有没有被踢回登录 / ADFS 页」，而不是页面文案：门户首页正文由 JS
+    异步渲染，按 ``Courses`` / ``课程`` 等关键词判断会在**已登录时误报未登录**（实测踩到），
+    导致多跑一遍登录流程、点完登录按钮又回到门户，最后卡在 ADFS 选择器上。
+    """
+    try:
+        page.goto(_PORTAL_HOME, wait_until="domcontentloaded", timeout=30000)
+        page.wait_for_timeout(2000)
+        return _on_blackboard(page)
+    except PWTimeout:
+        return False
+
+
+def _safe_url(page: Page) -> str:
+    """取当前 URL；页面已关闭等情况下退回占位文本，保证报错本身不二次失败。"""
+    try:
+        return page.url
+    except Exception:
+        return "(URL 不可用)"
+
+
+def _dump_login_debug(page: Page) -> Path:
+    """保存登录失败现场（截图 + 页面源码），返回产物目录；写盘失败不中断报错。"""
+    home = paths.BB_SYNC_HOME
+    with contextlib.suppress(OSError):
+        home.mkdir(parents=True, exist_ok=True)
+    with contextlib.suppress(Exception):
+        page.screenshot(path=str(home / "debug_login.png"), full_page=True, timeout=5000)
+    with contextlib.suppress(Exception):
+        (home / "debug_login.html").write_text(page.content(), encoding="utf-8")
+    return home
+
+
+def do_login(page: Page, username: str, password: str) -> None:
+    """执行一次完整登录；**任何一步**失败都保存调试产物并抛 :class:`AuthError`。
+
+    登录链路上每一步都可能因站点改版、MFA、网络或选择器漂移而卡住。这里统一兜底：
+    把当前 URL 写进错误信息，并落一份截图 + HTML，避免退化成「未预期错误 + 堆栈」
+    这种既没有可操作提示、又没有现场可查的形态。
+    """
+    try:
+        _perform_login(page, username, password)
+    except Exception as exc:
+        home = _dump_login_debug(page)
+        detail = str(exc).strip() or exc.__class__.__name__
+        raise AuthError(
+            f"登录失败（当前 URL: {_safe_url(page)}）：{detail}",
+            f"已保存登录现场到 {home}（debug_login.png / debug_login.html）。"
+            "若页面停在 ADFS / MFA / 验证码，请用 bb-sync run --headed 手动完成；"
+            f"若怀疑是登录流程改版或 bb-sync 的问题，欢迎到 {ISSUES_URL} 提 issue，"
+            "并附上 debug_login.html（以及上面这行 URL）。",
+        ) from exc
+
+
+def _perform_login(page: Page, username: str, password: str) -> None:
+    """实际登录流程（由 :func:`do_login` 统一兜底与落现场）。"""
+    page.goto(LOGIN_URL, wait_until="domcontentloaded")
+    # 主按钮跳转 ADFS OAuth2
+    page.wait_for_selector("input[name='login'], #login input.submit", timeout=10000)
+    with page.expect_navigation(wait_until="domcontentloaded", timeout=30000):
+        page.click("input[name='login']")
+
+    # 点「登录」后有两种走向：
+    #  1) SSO 已生效 → 直接回到 BB 门户（登录态有效却被误判为未登录时会走这里）
+    #  2) 未登录 → 跳 ADFS，需要填账号 / 密码
+    if not _on_blackboard(page):
+        # ADFS 登录页（分页式：先账号 → 提交 → 再密码；少数配置同页显示）
+        page.wait_for_selector(ADFS_USER, timeout=20000)
+        page.fill(ADFS_USER, username)
+
+        if not page.locator(ADFS_PASS).first.is_visible():
+            # 第一页只有账号：点「下一步」翻到密码页
+            try:
+                page.click(ADFS_NEXT, timeout=8000)
+            except PWTimeout:
+                page.press(ADFS_USER, "Enter")
+            page.wait_for_selector(ADFS_PASS, state="visible", timeout=20000)
+
+        page.fill(ADFS_PASS, password)
+        try:
+            with page.expect_navigation(wait_until="domcontentloaded", timeout=30000):
+                page.click(ADFS_SUBMIT, timeout=8000)
+        except PWTimeout:
+            page.press(ADFS_PASS, "Enter")
+            page.wait_for_load_state("domcontentloaded", timeout=20000)
+
+    # 等待回到 Blackboard
+    for _ in range(30):
+        page.wait_for_timeout(1000)
+        if _on_blackboard(page):
+            break
+
+    if not is_logged_in(page):
+        raise AuthError("已填写凭据，但未回到 Blackboard（可能是账号/密码错误，或需要 MFA）")
+
+
+def prompt_credentials(console: Console) -> Credentials:
+    """交互式录入凭据并保存到系统钥匙串（密码不回显）。"""
+    console.step("[login] 未找到已保存的凭据，请录入（保存后无需重复输入）")
+    student_id = input("学号（学生）/ 邮箱前缀（教职工）: ").strip()
+    if not student_id:
+        raise AuthError("学号不能为空")
+    password = getpass.getpass("密码（输入不回显）: ")
+    if not password:
+        raise AuthError("密码不能为空")
+    backend = save_credentials(student_id, password)
+    console.success(f"凭据已保存到系统钥匙串（{backend}），明文不再落盘")
+    return Credentials(student_id, password, "keyring")
+
+
+def resolve_credentials(console: Console) -> Credentials:
+    """取得可用凭据：优先系统钥匙串，缺失时交互录入（并保存）。"""
+    creds = load_credentials()
+    if creds.ok:
+        console.log(f"[login] 凭据来源: {creds.source}")
+        return creds
+    return prompt_credentials(console)
+
+
+def ensure_login(page: Page, console: Console, *, headed: bool = False) -> None:
+    """确保处于登录态（复用 profile → 静默登录 → 有头模式等人工过 MFA）。"""
+    if is_logged_in(page):
+        console.log("[login] 已有有效登录态（复用 Steel profile）")
+        return
+
+    creds = resolve_credentials(console)
+    try:
+        do_login(page, creds.student_id, creds.password)
+    except AuthError:
+        if not headed:
+            raise  # 静默模式失败就直接报错，提示改用 --headed
+        # 有头模式：可能需要人工过 MFA，留时间给用户在窗口里操作
+        console.step("[login] 等待人工完成 MFA / 验证码（最多 120 秒）...")
+        for _ in range(60):
+            page.wait_for_timeout(2000)
+            if is_logged_in(page):
+                console.success("检测到登录成功")
+                return
+        raise
+    console.success("登录成功")
+
+
+__all__ = [
+    "do_login",
+    "ensure_login",
+    "is_logged_in",
+    "prompt_credentials",
+    "resolve_credentials",
+]