canvas-pull 2.4.0__py3-none-any.whl

canvas_pull/manifest.py

@@ -0,0 +1,132 @@
+"""Local record of what has been synced, keyed by Canvas file id.
+
+Stored as JSON in <save_dir>/.canvas-pull/ so it is readable and diffs well in git.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+STATE_DIR = ".canvas-pull"
+MANIFEST_VERSION = 1
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+@dataclass
+class Entry:
+    id: int
+    course_id: int
+    course: str
+    path: str
+    size: int
+    stamp: str | None
+    sha256: str
+    synced_at: str
+    deleted: bool = False
+
+
+class Manifest:
+    def __init__(
+        self,
+        path: Path,
+        entries: dict[int, Entry] | None = None,
+        archived: dict[int, list[str]] | None = None,
+    ) -> None:
+        self.path = path
+        self.entries: dict[int, Entry] = entries or {}
+        # Completed courses already synced in full: course id -> sources used then.
+        self.archived: dict[int, list[str]] = archived or {}
+
+    @classmethod
+    def load(cls, save_dir: Path) -> Manifest:
+        path = save_dir / STATE_DIR / "manifest.json"
+        if not path.is_file():
+            return cls(path)
+        data = json.loads(path.read_text(encoding="utf-8"))
+        entries = {e["id"]: Entry(**e) for e in data.get("files", [])}
+        archived = {int(k): list(v) for k, v in data.get("archived_courses", {}).items()}
+        return cls(path, entries, archived)
+
+    def is_archived(self, course_id: int, sources: list[str]) -> bool:
+        """True if this completed course was fully synced with (at least) these sources."""
+        done = self.archived.get(course_id)
+        return done is not None and set(sources) <= set(done)
+
+    def mark_archived(self, course_id: int, sources: list[str]) -> None:
+        self.archived[course_id] = sorted(sources)
+
+    def get(self, file_id: int) -> Entry | None:
+        return self.entries.get(file_id)
+
+    def upsert(self, entry: Entry) -> None:
+        self.entries[entry.id] = entry
+
+    def mark_deleted(self, file_id: int) -> None:
+        if file_id in self.entries:
+            self.entries[file_id].deleted = True
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "version": MANIFEST_VERSION,
+            "files": [asdict(e) for e in sorted(self.entries.values(), key=lambda e: e.id)],
+            "archived_courses": {str(k): v for k, v in sorted(self.archived.items())},
+        }
+        tmp = self.path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(data, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
+        os.replace(tmp, self.path)
+
+
+def append_log(save_dir: Path, record: dict) -> None:
+    path = save_dir / STATE_DIR / "log.jsonl"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def read_log(save_dir: Path, limit: int | None = 10) -> list[dict]:
+    """Sync records, oldest first; the last `limit` of them (all if None)."""
+    path = save_dir / STATE_DIR / "log.jsonl"
+    if not path.is_file():
+        return []
+    lines = [line for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+    return [json.loads(line) for line in (lines if limit is None else lines[-limit:])]
+
+
+class SyncLocked(Exception):
+    """Another canvas-pull sync is already running on this save folder."""
+
+
+@contextmanager
+def sync_lock(save_dir: Path) -> Iterator[None]:
+    """Exclusive, non-blocking lock on the save folder (flock on Unix, msvcrt on Windows)."""
+    path = save_dir / STATE_DIR / "lock"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a+") as fh:
+        try:
+            if os.name == "nt":
+                import msvcrt
+
+                fh.seek(0)
+                msvcrt.locking(fh.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            raise SyncLocked from None
+        try:
+            yield
+        finally:
+            if os.name == "nt":
+                fh.seek(0)
+                msvcrt.locking(fh.fileno(), msvcrt.LK_UNLCK, 1)

canvas_pull/models.py

@@ -0,0 +1,61 @@
+"""Canvas API objects (only the fields canvas-pull uses)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class Term(_Model):
+    id: int | None = None
+    name: str | None = None
+    start_at: datetime | None = None
+    end_at: datetime | None = None
+
+
+class Course(_Model):
+    id: int
+    name: str | None = None
+    course_code: str | None = None
+    term: Term | None = None
+    start_at: datetime | None = None
+    end_at: datetime | None = None
+    # Courses outside their access dates come back with only id + this flag.
+    access_restricted_by_date: bool = False
+    # Set by canvas-pull (not Canvas) for courses from completed enrollments.
+    completed: bool = False
+
+    @property
+    def label(self) -> str:
+        return self.name or self.course_code or f"Course {self.id}"
+
+
+class Folder(_Model):
+    id: int
+    full_name: str
+    name: str = ""
+    parent_folder_id: int | None = None
+
+
+class CanvasFile(_Model):
+    id: int
+    display_name: str
+    filename: str = ""
+    folder_id: int | None = None
+    size: int = 0
+    content_type: str = Field(default="", alias="content-type")
+    url: str = ""
+    updated_at: datetime | None = None
+    modified_at: datetime | None = None
+    locked_for_user: bool = False
+
+    @property
+    def stamp(self) -> str | None:
+        """Timestamp of the last content change (modified_at ignores renames)."""
+        ts = self.modified_at or self.updated_at
+        return ts.isoformat() if ts else None

canvas_pull/notify.py

@@ -0,0 +1,46 @@
+"""Desktop notifications (macOS Notification Center, or notify-send on Linux)."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from collections import Counter, defaultdict
+from collections.abc import Iterable
+
+from .sync import Change
+
+TITLE = "Canvas Pull"
+
+
+def send(message: str, title: str = TITLE) -> bool:
+    """Show a notification. Returns False when no notifier is available."""
+    try:
+        if sys.platform == "darwin":
+            # Pass text as argv so quotes in file names cannot break the script.
+            script = [
+                "-e", "on run argv",
+                "-e", "display notification (item 2 of argv) with title (item 1 of argv)",
+                "-e", "end run",
+            ]  # fmt: skip
+            cmd = ["osascript", *script, title, message]
+        elif shutil.which("notify-send"):
+            cmd = ["notify-send", "--app-name=canvas-pull", title, message]
+        else:
+            return False
+        return subprocess.run(cmd, capture_output=True, timeout=10, check=False).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def describe(changes: Iterable[Change], limit: int = 220) -> str:
+    """'Signals: 2 new, 1 modified · OS: 1 deleted' (truncated)."""
+    per_course: dict[str, Counter[str]] = defaultdict(Counter)
+    for c in changes:
+        per_course[c.course][str(c.kind)] += 1
+    parts = [
+        f"{course}: " + ", ".join(f"{n} {k}" for k, n in counts.items())
+        for course, counts in per_course.items()
+    ]
+    text = " · ".join(parts)
+    return text if len(text) <= limit else text[: limit - 1] + "…"

canvas_pull/schedule.py

@@ -0,0 +1,215 @@
+"""Run `canvas-pull sync --notify` on a schedule.
+
+macOS: a launchd user agent in ~/Library/LaunchAgents.
+Linux: a systemd user timer in ~/.config/systemd/user.
+A Mac that was asleep at the scheduled time runs the missed sync when it wakes.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import re
+import shlex
+import subprocess
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+LABEL = "io.github.gxxxr-111.canvas-pull"
+UNIT = "canvas-pull"
+DEFAULT_PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+
+Runner = Callable[[Sequence[str]], subprocess.CompletedProcess[str]]
+
+
+class ScheduleError(Exception):
+    pass
+
+
+def _run(cmd: Sequence[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(list(cmd), capture_output=True, text=True, check=False)
+
+
+@dataclass
+class Spec:
+    times: list[tuple[int, int]]  # (hour, minute) every day
+    every: int | None = None  # seconds; used instead of times
+
+    def describe(self) -> str:
+        if self.every:
+            mins = self.every // 60
+            return f"every {mins // 60}h" if mins % 60 == 0 else f"every {mins}m"
+        return "daily at " + ", ".join(f"{h:02d}:{m:02d}" for h, m in self.times)
+
+
+def parse_spec(at: Sequence[str], every: str | None) -> Spec:
+    if every and at:
+        raise ScheduleError("Use either --at or --every, not both.")
+    if every:
+        m = re.fullmatch(r"\s*(\d+)\s*([mh])\s*", every.lower())
+        if not m:
+            raise ScheduleError("--every looks like 30m or 6h.")
+        seconds = int(m[1]) * (60 if m[2] == "m" else 3600)
+        if seconds < 15 * 60:
+            raise ScheduleError("Please sync at most every 15 minutes.")
+        return Spec(times=[], every=seconds)
+    times = []
+    for value in at or ["09:00"]:
+        m = re.fullmatch(r"\s*(\d{1,2}):(\d{2})\s*", value)
+        if not m or int(m[1]) > 23 or int(m[2]) > 59:
+            raise ScheduleError(f"Invalid time {value!r}; use HH:MM, e.g. 08:30.")
+        times.append((int(m[1]), int(m[2])))
+    return Spec(times=sorted(set(times)))
+
+
+def command() -> list[str]:
+    """How the scheduler should start canvas-pull: the same install that is running now."""
+    argv0 = Path(sys.argv[0])
+    if argv0.name == "canvas-pull" and argv0.exists():
+        return [str(argv0.resolve()), "sync", "--notify"]
+    return [sys.executable, "-m", "canvas_pull", "sync", "--notify"]
+
+
+def log_file() -> Path:
+    if sys.platform == "darwin":
+        return Path.home() / "Library/Logs/canvas-pull.log"
+    state = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local/state"))
+    return state / "canvas-pull/canvas-pull.log"
+
+
+# -- macOS ---------------------------------------------------------------------
+
+
+def plist_path() -> Path:
+    return Path.home() / "Library/LaunchAgents" / f"{LABEL}.plist"
+
+
+def build_plist(spec: Spec, cmd: list[str], workdir: Path, log: Path) -> dict:
+    plist: dict = {
+        "Label": LABEL,
+        "ProgramArguments": cmd,
+        "WorkingDirectory": str(workdir),
+        "StandardOutPath": str(log),
+        "StandardErrorPath": str(log),
+        "EnvironmentVariables": {"PATH": DEFAULT_PATH, "PYTHONUNBUFFERED": "1"},
+        "ProcessType": "Background",
+        "RunAtLoad": False,
+    }
+    if spec.every:
+        plist["StartInterval"] = spec.every
+    else:
+        plist["StartCalendarInterval"] = [{"Hour": h, "Minute": m} for h, m in spec.times]
+    return plist
+
+
+# -- Linux ---------------------------------------------------------------------
+
+
+def systemd_dir() -> Path:
+    base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / "systemd/user"
+
+
+def build_systemd(spec: Spec, cmd: list[str], workdir: Path, log: Path) -> tuple[str, str]:
+    service = (
+        "[Unit]\nDescription=Sync Canvas course files\n"
+        "Wants=network-online.target\nAfter=network-online.target\n\n"
+        "[Service]\nType=oneshot\n"
+        f"WorkingDirectory={workdir}\n"
+        f"ExecStart={shlex.join(cmd)}\n"
+        f"StandardOutput=append:{log}\nStandardError=append:{log}\n"
+    )
+    if spec.every:
+        when = f"OnBootSec=5min\nOnUnitActiveSec={spec.every}s\n"
+    else:
+        when = "".join(f"OnCalendar=*-*-* {h:02d}:{m:02d}:00\n" for h, m in spec.times)
+    timer = (
+        f"[Unit]\nDescription=Run canvas-pull ({spec.describe()})\n\n"
+        f"[Timer]\n{when}Persistent=true\n\n[Install]\nWantedBy=timers.target\n"
+    )
+    return service, timer
+
+
+# -- public --------------------------------------------------------------------
+
+
+def _check(proc: subprocess.CompletedProcess[str], what: str) -> None:
+    if proc.returncode != 0:
+        raise ScheduleError(f"{what} failed: {(proc.stderr or proc.stdout).strip()}")
+
+
+def enable(spec: Spec, *, workdir: Path, run: Runner = _run) -> Path:
+    """Install (or replace) the schedule. Returns the file written."""
+    cmd, log = command(), log_file()
+    log.parent.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "darwin":
+        path = plist_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        domain = f"gui/{os.getuid()}"
+        run(["launchctl", "bootout", domain, str(path)])  # ignore "not loaded"
+        path.write_bytes(plistlib.dumps(build_plist(spec, cmd, workdir, log)))
+        _check(run(["launchctl", "bootstrap", domain, str(path)]), "launchctl bootstrap")
+        return path
+    if sys.platform.startswith("linux"):
+        d = systemd_dir()
+        d.mkdir(parents=True, exist_ok=True)
+        service, timer = build_systemd(spec, cmd, workdir, log)
+        (d / f"{UNIT}.service").write_text(service, encoding="utf-8")
+        (d / f"{UNIT}.timer").write_text(timer, encoding="utf-8")
+        _check(run(["systemctl", "--user", "daemon-reload"]), "systemctl daemon-reload")
+        _check(run(["systemctl", "--user", "enable", "--now", f"{UNIT}.timer"]), "systemctl enable")
+        return d / f"{UNIT}.timer"
+    raise ScheduleError(
+        "Scheduling is supported on macOS and Linux. On Windows use Task Scheduler."
+    )
+
+
+def disable(*, run: Runner = _run) -> bool:
+    """Remove the schedule. Returns False if none was installed."""
+    if sys.platform == "darwin":
+        path = plist_path()
+        if not path.exists():
+            return False
+        run(["launchctl", "bootout", f"gui/{os.getuid()}", str(path)])
+        path.unlink()
+        return True
+    if sys.platform.startswith("linux"):
+        d = systemd_dir()
+        timer = d / f"{UNIT}.timer"
+        if not timer.exists():
+            return False
+        run(["systemctl", "--user", "disable", "--now", f"{UNIT}.timer"])
+        timer.unlink()
+        (d / f"{UNIT}.service").unlink(missing_ok=True)
+        run(["systemctl", "--user", "daemon-reload"])
+        return True
+    return False
+
+
+def current() -> str | None:
+    """Human-readable description of the installed schedule, or None."""
+    if sys.platform == "darwin" and plist_path().exists():
+        data = plistlib.loads(plist_path().read_bytes())
+        if "StartInterval" in data:
+            return Spec(times=[], every=int(data["StartInterval"])).describe()
+        cal = data.get("StartCalendarInterval", [])
+        cal = cal if isinstance(cal, list) else [cal]
+        return Spec(times=[(c.get("Hour", 0), c.get("Minute", 0)) for c in cal]).describe()
+    timer = systemd_dir() / f"{UNIT}.timer"
+    if sys.platform.startswith("linux") and timer.exists():
+        m = re.search(r"Description=Run canvas-pull \((.*)\)", timer.read_text())
+        return m[1] if m else "installed"
+    return None
+
+
+def run_now(*, run: Runner = _run) -> None:
+    """Trigger the scheduled job once, as the scheduler would."""
+    if sys.platform == "darwin":
+        target = f"gui/{os.getuid()}/{LABEL}"
+        _check(run(["launchctl", "kickstart", target]), "launchctl kickstart")
+    elif sys.platform.startswith("linux"):
+        _check(run(["systemctl", "--user", "start", f"{UNIT}.service"]), "systemctl start")
+    else:
+        raise ScheduleError("No schedule support on this platform.")

canvas_pull/summary.py

@@ -0,0 +1,72 @@
+"""Merge many sync records into one net summary ("what changed this week")."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+
+_UNITS = {"h": "hours", "d": "days", "w": "weeks"}
+
+
+def parse_since(value: str, now: datetime | None = None) -> datetime:
+    """'7d', '24h', '2w', 'today' or a date like '2026-10-01' -> aware datetime."""
+    now = now or datetime.now(UTC)
+    text = value.strip().lower()
+    if text == "today":
+        local = datetime.now().astimezone()
+        return local.replace(hour=0, minute=0, second=0, microsecond=0).astimezone(UTC)
+    m = re.fullmatch(r"(\d+)\s*([hdw])", text)
+    if m:
+        return now - timedelta(**{_UNITS[m[2]]: int(m[1])})
+    try:
+        dt = datetime.fromisoformat(value.strip())
+    except ValueError:
+        raise ValueError(f"Can't read {value!r}; try 7d, 24h, 2w, today or 2026-10-01.") from None
+    return (
+        dt.astimezone(UTC) if dt.tzinfo else dt.replace(tzinfo=datetime.now().astimezone().tzinfo)
+    )
+
+
+@dataclass
+class NetChange:
+    kind: str  # new | modified | moved | deleted
+    course: str
+    path: str
+    old_path: str | None = None
+    time: str = ""
+
+
+def summarize(records: list[dict], since: datetime) -> list[NetChange]:
+    """Net effect of all changes after `since`, oldest record first in `records`.
+
+    new→modified stays new, new→deleted disappears, a moved file keeps its first path.
+    """
+    state: dict[str, NetChange] = {}
+    for rec in records:
+        if datetime.fromisoformat(rec["time"]) < since:
+            continue
+        for c in rec["changes"]:
+            kind, path, course, t = c["kind"], c["path"], c["course"], rec["time"]
+            if kind == "restored":  # a local event, not a Canvas change
+                continue
+            if kind == "new":
+                state[path] = NetChange("new", course, path, time=t)
+                continue
+            old = c.get("old_path") or path
+            prev = state.pop(old, None)
+            if kind == "deleted":
+                if not (prev and prev.kind == "new"):  # added then removed: no net change
+                    state[path] = NetChange("deleted", course, path, time=t)
+                continue
+            # modified or moved
+            origin = prev.old_path if prev and prev.old_path else old
+            origin = origin if origin != path else None
+            if prev and prev.kind == "new":
+                state[path] = NetChange("new", course, path, time=t)
+            elif kind == "modified" or (prev and prev.kind == "modified"):
+                state[path] = NetChange("modified", course, path, origin, t)
+            elif origin:  # moved, and not back to where it started
+                state[path] = NetChange("moved", course, path, origin, t)
+    order = {"new": 0, "modified": 1, "moved": 2, "deleted": 3}
+    return sorted(state.values(), key=lambda n: (n.course.lower(), order[n.kind], n.path.lower()))