e3cli 0.3.1__py3-none-any.whl

e3cli/__init__.py

@@ -0,0 +1,3 @@
+"""E3CLI — NYCU E3 Moodle Automation CLI Tool"""
+
+__version__ = "0.3.1"

e3cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m e3cli`."""
+
+from e3cli.cli import app
+
+app()

e3cli/ai/__init__.py

@@ -0,0 +1 @@
+"""AI 整合模組 (未來擴充)。"""

e3cli/api/assignments.py

@@ -0,0 +1,38 @@
+"""作業相關 API。"""
+
+from __future__ import annotations
+
+from e3cli.api.client import MoodleClient
+
+
+def get_assignments(client: MoodleClient, courseids: list[int]) -> dict:
+    """
+    取得指定課程的所有作業。
+
+    回傳: {"courses": [{"id": ..., "assignments": [{...}]}]}
+    """
+    params = {f"courseids[{i}]": cid for i, cid in enumerate(courseids)}
+    return client.call("mod_assign_get_assignments", **params)
+
+
+def get_submission_status(client: MoodleClient, assignid: int) -> dict:
+    """取得某作業的提交狀態。"""
+    return client.call("mod_assign_get_submission_status", assignid=assignid)
+
+
+def save_submission(client: MoodleClient, assignid: int, draft_itemid: int, text: str = "") -> dict:
+    """
+    提交作業（檔案已上傳到 draft area 後）。
+
+    draft_itemid: upload_file 回傳的 itemid
+    text: 可選的線上文字內容
+    """
+    params = {
+        "assignmentid": assignid,
+        "plugindata[files_filemanager]": draft_itemid,
+    }
+    if text:
+        params["plugindata[onlinetext_editor][text]"] = text
+        params["plugindata[onlinetext_editor][format]"] = 1  # HTML
+        params["plugindata[onlinetext_editor][itemid]"] = draft_itemid
+    return client.call("mod_assign_save_submission", **params)

e3cli/api/client.py

@@ -0,0 +1,77 @@
+"""Moodle REST API 客戶端。"""
+
+from __future__ import annotations
+
+import requests
+
+
+class MoodleAPIError(Exception):
+    """Moodle API 回傳錯誤。"""
+
+    def __init__(self, errorcode: str, message: str):
+        self.errorcode = errorcode
+        super().__init__(f"[{errorcode}] {message}")
+
+
+class MoodleClient:
+    """封裝 Moodle Web Service REST API 呼叫。"""
+
+    def __init__(self, base_url: str, token: str):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.session = requests.Session()
+        self.rest_endpoint = f"{self.base_url}/webservice/rest/server.php"
+        self.upload_endpoint = f"{self.base_url}/webservice/upload.php"
+
+    def call(self, wsfunction: str, **kwargs) -> dict | list:
+        """
+        呼叫 Moodle Web Service 函式。
+
+        所有參數以 POST form data 傳送，Moodle 使用 bracket notation
+        處理巢狀參數（如 courseids[0]=123）。
+        """
+        params = {
+            "wstoken": self.token,
+            "wsfunction": wsfunction,
+            "moodlewsrestformat": "json",
+            **kwargs,
+        }
+        resp = self.session.post(self.rest_endpoint, data=params, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Moodle 錯誤格式: {"exception": ..., "errorcode": ..., "message": ...}
+        if isinstance(data, dict) and "exception" in data:
+            raise MoodleAPIError(data.get("errorcode", "unknown"), data.get("message", "未知錯誤"))
+
+        return data
+
+    def upload_file(self, filepath, itemid: int = 0) -> list[dict]:
+        """
+        上傳檔案到使用者的 draft area。
+
+        回傳包含 itemid, filename 等資訊的 list。
+        """
+        from pathlib import Path
+        filepath = Path(filepath)
+
+        with open(filepath, "rb") as f:
+            resp = self.session.post(
+                self.upload_endpoint,
+                params={"token": self.token},
+                data={"itemid": itemid, "filepath": "/"},
+                files={"file_1": (filepath.name, f)},
+                timeout=120,
+            )
+        resp.raise_for_status()
+        data = resp.json()
+
+        if isinstance(data, dict) and "exception" in data:
+            raise MoodleAPIError(data.get("errorcode", "unknown"), data.get("message", "上傳失敗"))
+
+        return data
+
+    def download_url(self, fileurl: str) -> str:
+        """為檔案 URL 附加 token 參數以供下載。"""
+        sep = "&" if "?" in fileurl else "?"
+        return f"{fileurl}{sep}token={self.token}"

e3cli/api/courses.py

@@ -0,0 +1,27 @@
+"""課程相關 API。"""
+
+from __future__ import annotations
+
+from e3cli.api.client import MoodleClient
+
+
+def get_enrolled_courses(client: MoodleClient, userid: int) -> list[dict]:
+    """取得使用者已註冊的課程列表。"""
+    return client.call("core_enrol_get_users_courses", userid=userid)
+
+
+def get_course_contents(client: MoodleClient, courseid: int) -> list[dict]:
+    """
+    取得課程內容（章節 → 模組 → 檔案）。
+
+    回傳結構：
+    [
+      {
+        "id": section_id, "name": "第一週", "modules": [
+          {"id": mod_id, "modname": "resource", "name": "...",
+           "contents": [{"filename": "...", "fileurl": "...", "filesize": ..., "timemodified": ...}]}
+        ]
+      }
+    ]
+    """
+    return client.call("core_course_get_contents", courseid=courseid)

e3cli/api/files.py

@@ -0,0 +1,25 @@
+"""檔案下載功能。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from e3cli.api.client import MoodleClient
+
+
+def download_file(client: MoodleClient, fileurl: str, dest: Path) -> Path:
+    """
+    從 Moodle 下載檔案到本地路徑。
+
+    自動建立目標目錄，串流下載大檔案。
+    """
+    url = client.download_url(fileurl)
+    resp = client.session.get(url, stream=True, timeout=120)
+    resp.raise_for_status()
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with open(dest, "wb") as f:
+        for chunk in resp.iter_content(chunk_size=8192):
+            f.write(chunk)
+
+    return dest

e3cli/api/site.py

@@ -0,0 +1,10 @@
+"""站點資訊 API。"""
+
+from __future__ import annotations
+
+from e3cli.api.client import MoodleClient
+
+
+def get_site_info(client: MoodleClient) -> dict:
+    """取得站點資訊，包含 userid、username、sitename 等。"""
+    return client.call("core_webservice_get_site_info")

e3cli/auth.py

@@ -0,0 +1,33 @@
+"""認證模組 — 透過 login/token.php 取得 Moodle Web Service token。"""
+
+from __future__ import annotations
+
+import requests
+
+
+class AuthError(Exception):
+    """認證失敗。"""
+
+
+def get_token(base_url: str, username: str, password: str, service: str = "moodle_mobile_app") -> str:
+    """
+    向 Moodle 取得 Web Service token。
+
+    POST {base_url}/login/token.php
+    成功回傳 token 字串，失敗拋出 AuthError。
+    """
+    url = f"{base_url.rstrip('/')}/login/token.php"
+    resp = requests.post(url, data={
+        "username": username,
+        "password": password,
+        "service": service,
+    }, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()
+
+    if "token" in data:
+        return data["token"]
+
+    error_msg = data.get("error", "未知錯誤")
+    error_code = data.get("errorcode", "")
+    raise AuthError(f"登入失敗 [{error_code}]: {error_msg}")

e3cli/cli.py

@@ -0,0 +1,61 @@
+"""E3CLI 主入口 — 組裝所有子指令。"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from e3cli import __version__
+from e3cli.commands.assignments import app as assignments_app
+from e3cli.commands.courses import app as courses_app
+from e3cli.commands.download import app as download_app
+from e3cli.commands.login import app as login_app
+from e3cli.commands.logout import app as logout_app
+from e3cli.commands.schedule import app as schedule_app
+from e3cli.commands.setup import app as setup_app
+from e3cli.commands.setup import is_first_run, run_setup_wizard
+from e3cli.commands.submit import app as submit_app
+from e3cli.commands.sync import app as sync_app
+from e3cli.i18n import t
+
+app = typer.Typer(
+    name="e3cli",
+    help=t("cli.help"),
+    no_args_is_help=True,
+)
+
+app.add_typer(login_app, name="login", help=t("cli.login"))
+app.add_typer(logout_app, name="logout", help=t("cli.logout"))
+app.add_typer(courses_app, name="courses", help=t("cli.courses"))
+app.add_typer(assignments_app, name="assignments", help=t("cli.assignments"))
+app.add_typer(download_app, name="download", help=t("cli.download"))
+app.add_typer(submit_app, name="submit", help=t("cli.submit"))
+app.add_typer(sync_app, name="sync", help=t("cli.sync"))
+app.add_typer(schedule_app, name="schedule", help=t("cli.schedule"))
+app.add_typer(setup_app, name="setup", help=t("cli.setup"))
+
+
+@app.command()
+def version():
+    """Show version."""
+    typer.echo(f"e3cli {__version__}")
+
+
+_original_app_call = app.__call__
+
+
+def _app_with_first_run(*args, **kwargs):
+    skip_keywords = {"--help", "-h", "version", "setup", "--show-completion", "--install-completion"}
+    if (
+        is_first_run()
+        and sys.stdin.isatty()
+        and not any(arg in skip_keywords for arg in sys.argv[1:])
+    ):
+        run_setup_wizard()
+        if len(sys.argv) <= 1:
+            return
+    return _original_app_call(*args, **kwargs)
+
+
+app.__call__ = _app_with_first_run

e3cli/commands/_common.py

@@ -0,0 +1,29 @@
+"""Commands 共用工具。"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from e3cli.api.client import MoodleClient
+from e3cli.config import load_config, load_token
+from e3cli.i18n import t
+from e3cli.storage.db import Database
+
+console = Console()
+
+
+def get_client() -> MoodleClient:
+    """取得已認證的 MoodleClient，token 不存在則提示登入。"""
+    cfg = load_config()
+    token = load_token()
+    if not token:
+        console.print(f"[red]{t('common.not_logged_in')}[/red]")
+        raise typer.Exit(1)
+    return MoodleClient(cfg.moodle.url, token)
+
+
+def get_db() -> Database:
+    """取得 SQLite Database 實例。"""
+    cfg = load_config()
+    return Database(cfg.storage.db_path)

e3cli/commands/assignments.py

@@ -0,0 +1,91 @@
+"""e3cli assignments"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from e3cli.api.assignments import get_assignments
+from e3cli.api.courses import get_enrolled_courses
+from e3cli.api.site import get_site_info
+from e3cli.commands._common import get_client, get_db
+from e3cli.i18n import t
+
+console = Console()
+app = typer.Typer()
+
+
+def _format_duedate(ts: int) -> str:
+    if ts == 0:
+        return t("assign.no_deadline")
+    dt = datetime.fromtimestamp(ts)
+    remaining = ts - int(time.time())
+    days = remaining // 86400
+    if remaining < 0:
+        return f"[red]{dt:%Y-%m-%d %H:%M} ({t('assign.expired')})[/red]"
+    if days <= 3:
+        return f"[red]{dt:%Y-%m-%d %H:%M} ({t('assign.days_left', n=days)})[/red]"
+    if days <= 7:
+        return f"[yellow]{dt:%Y-%m-%d %H:%M} ({t('assign.days_left', n=days)})[/yellow]"
+    return f"{dt:%Y-%m-%d %H:%M} ({t('assign.days_left', n=days)})"
+
+
+@app.callback(invoke_without_command=True)
+def assignments(
+    due_soon: int = typer.Option(None, "--due-soon", help=t("assign.opt_due_soon")),
+):
+    """List assignments and deadlines."""
+    client = get_client()
+    db = get_db()
+
+    info = get_site_info(client)
+    course_list = get_enrolled_courses(client, info["userid"])
+    courseids = [c["id"] for c in course_list]
+    course_names = {c["id"]: c.get("shortname", "") for c in course_list}
+
+    if not courseids:
+        console.print(f"[yellow]{t('common.no_courses')}[/yellow]")
+        raise typer.Exit()
+
+    data = get_assignments(client, courseids)
+    now = int(time.time())
+
+    table = Table(title=t("assign.title"))
+    table.add_column(t("courses.col_id"), style="dim")
+    table.add_column(t("assign.col_course"), style="cyan")
+    table.add_column(t("assign.col_name"), style="bold")
+    table.add_column(t("assign.col_due"))
+    table.add_column(t("assign.col_status"))
+
+    count = 0
+    for course in data.get("courses", []):
+        cid = course["id"]
+        cname = course_names.get(cid, "")
+        for a in course.get("assignments", []):
+            duedate = a.get("duedate", 0)
+
+            if due_soon is not None:
+                if duedate == 0 or duedate - now > due_soon * 86400 or duedate < now:
+                    continue
+
+            db.upsert_assignment(a["id"], cid, cname, a["name"], duedate, now)
+
+            table.add_row(
+                str(a["id"]),
+                cname,
+                a["name"],
+                _format_duedate(duedate),
+                a.get("submissionstatus", "new") if "submissionstatus" in a else "—",
+            )
+            count += 1
+
+    if count == 0:
+        console.print(f"[green]{t('assign.empty')}[/green]")
+    else:
+        console.print(table)
+
+    db.close()

e3cli/commands/courses.py

@@ -0,0 +1,39 @@
+"""e3cli courses"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from e3cli.api.courses import get_enrolled_courses
+from e3cli.api.site import get_site_info
+from e3cli.commands._common import get_client
+from e3cli.i18n import t
+
+console = Console()
+app = typer.Typer()
+
+
+@app.callback(invoke_without_command=True)
+def courses():
+    """List all enrolled courses."""
+    client = get_client()
+    info = get_site_info(client)
+    userid = info["userid"]
+
+    course_list = get_enrolled_courses(client, userid)
+
+    if not course_list:
+        console.print(f"[yellow]{t('courses.empty')}[/yellow]")
+        raise typer.Exit()
+
+    table = Table(title=f"{t('courses.title')} ({info['fullname']})")
+    table.add_column(t("courses.col_id"), style="dim")
+    table.add_column(t("courses.col_code"), style="cyan")
+    table.add_column(t("courses.col_name"), style="bold")
+
+    for c in course_list:
+        table.add_row(str(c["id"]), c.get("shortname", ""), c.get("fullname", ""))
+
+    console.print(table)

e3cli/commands/download.py

@@ -0,0 +1,105 @@
+"""e3cli download"""
+
+from __future__ import annotations
+
+import re
+import time
+
+import typer
+from rich.console import Console
+from rich.progress import Progress
+
+from e3cli.api.courses import get_course_contents, get_enrolled_courses
+from e3cli.api.files import download_file
+from e3cli.api.site import get_site_info
+from e3cli.commands._common import get_client, get_db
+from e3cli.config import load_config
+from e3cli.i18n import t
+
+console = Console()
+app = typer.Typer()
+
+
+def _sanitize(name: str) -> str:
+    return re.sub(r'[<>:"/\\|?*]', "_", name).strip().rstrip(".")
+
+
+@app.callback(invoke_without_command=True)
+def download(
+    course: str = typer.Option(None, "--course", "-c", help=t("dl.opt_course")),
+    all_courses: bool = typer.Option(False, "--all", "-a", help=t("dl.opt_all")),
+):
+    """Download course materials."""
+    if not course and not all_courses:
+        console.print(f"[yellow]{t('dl.need_flag')}[/yellow]")
+        raise typer.Exit(1)
+
+    client = get_client()
+    db = get_db()
+    cfg = load_config()
+    download_dir = cfg.storage.download_dir
+
+    info = get_site_info(client)
+    course_list = get_enrolled_courses(client, info["userid"])
+
+    if course:
+        course_lower = course.lower()
+        course_list = [
+            c for c in course_list
+            if course_lower in c.get("shortname", "").lower()
+            or course_lower in c.get("fullname", "").lower()
+        ]
+        if not course_list:
+            console.print(f"[red]{t('dl.no_match', q=course)}[/red]")
+            raise typer.Exit(1)
+
+    total_new = 0
+    total_skipped = 0
+
+    for c in course_list:
+        cid = c["id"]
+        cname = _sanitize(c.get("shortname", str(cid)))
+        db.upsert_course(cid, c.get("shortname", ""), c.get("fullname", ""))
+
+        console.print(f"\n[bold cyan]{c.get('fullname', cname)}[/bold cyan]")
+
+        contents = get_course_contents(client, cid)
+        files_to_download = []
+
+        for section in contents:
+            section_name = _sanitize(section.get("name", "unnamed"))
+            for module in section.get("modules", []):
+                mid = module.get("id", 0)
+                for file_info in module.get("contents", []):
+                    fname = file_info.get("filename", "")
+                    furl = file_info.get("fileurl", "")
+                    fsize = file_info.get("filesize", 0)
+                    ftime = file_info.get("timemodified", 0)
+
+                    if not fname or not furl:
+                        continue
+
+                    if db.is_downloaded(cid, mid, fname, ftime):
+                        total_skipped += 1
+                        continue
+
+                    dest = download_dir / cname / section_name / fname
+                    files_to_download.append((cid, mid, fname, furl, fsize, ftime, dest))
+
+        if not files_to_download:
+            console.print(f"  [dim]{t('dl.no_new')}[/dim]")
+            continue
+
+        with Progress(console=console) as progress:
+            task = progress.add_task(f"  {t('dl.progress')}", total=len(files_to_download))
+            for cid, mid, fname, furl, fsize, ftime, dest in files_to_download:
+                download_file(client, furl, dest)
+                db.record_download(
+                    cid, mid, fname, furl, fsize, ftime,
+                    str(dest), int(time.time()),
+                )
+                total_new += 1
+                progress.advance(task)
+
+    console.print(f"\n[green]{t('dl.done', new=total_new, skip=total_skipped)}[/green]")
+    db.close()

e3cli/commands/login.py

@@ -0,0 +1,68 @@
+"""e3cli login"""
+
+from __future__ import annotations
+
+import getpass
+
+import typer
+from rich.console import Console
+
+from e3cli.auth import AuthError, get_token
+from e3cli.config import load_config, save_token
+from e3cli.credential import has_credentials, load_credentials, save_credentials
+from e3cli.i18n import t
+
+console = Console()
+app = typer.Typer()
+
+
+@app.callback(invoke_without_command=True)
+def login(
+    username: str = typer.Option(None, "--username", "-u", help=t("login.opt_username")),
+    save_password: bool = typer.Option(False, "--save", "-s", help=t("login.opt_save")),
+    refresh: bool = typer.Option(False, "--refresh", "-r", help=t("login.opt_refresh")),
+):
+    """Login to NYCU E3 Moodle and save token."""
+    cfg = load_config()
+
+    if refresh:
+        creds = load_credentials()
+        if not creds:
+            console.print(f"[red]{t('login.no_saved')}[/red]")
+            raise typer.Exit(1)
+        username, password = creds
+        console.print(f"[dim]{t('login.refreshing', user=username)}[/dim]")
+    else:
+        if not username and has_credentials():
+            creds = load_credentials()
+            if creds:
+                use_saved = typer.confirm(t("login.use_saved", user=creds[0]), default=True)
+                if use_saved:
+                    username, password = creds
+                else:
+                    username = typer.prompt(t("login.prompt_user"))
+                    password = getpass.getpass(t("login.prompt_pass"))
+            else:
+                username = typer.prompt(t("login.prompt_user"))
+                password = getpass.getpass(t("login.prompt_pass"))
+        else:
+            if not username:
+                username = typer.prompt(t("login.prompt_user"))
+            password = getpass.getpass(t("login.prompt_pass"))
+
+    console.print(f"[dim]{t('login.connecting', url=cfg.moodle.url)}[/dim]")
+
+    try:
+        token = get_token(cfg.moodle.url, username, password, cfg.moodle.service)
+    except AuthError as e:
+        console.print(f"[red]✗ {e}[/red]")
+        raise typer.Exit(1)
+
+    save_token(token)
+
+    if save_password or refresh:
+        save_credentials(username, password)
+        console.print(f"[green]{t('login.success_saved')}[/green]")
+    else:
+        console.print(f"[green]{t('login.success')}[/green]")
+        console.print(f"[dim]{t('login.hint_save')}[/dim]")

e3cli/commands/logout.py

@@ -0,0 +1,19 @@
+"""e3cli logout"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from e3cli.credential import clear_credentials
+from e3cli.i18n import t
+
+console = Console()
+app = typer.Typer()
+
+
+@app.callback(invoke_without_command=True)
+def logout():
+    """Clear all stored credentials and tokens."""
+    clear_credentials()
+    console.print(f"[green]{t('logout.done')}[/green]")