bugcap 0.2.2__py3-none-any.whl

bugcap/ingest.py

@@ -0,0 +1,210 @@
+"""Bring existing images into the store: local paths, globs and http(s) URLs.
+
+Every input is validated by its magic bytes (never its extension or Content-Type), copied
+into the images directory under a fresh name (the original path is not kept), and written
+atomically. Network access is limited to plain http(s) GETs with no credentials."""
+from __future__ import annotations
+
+import glob
+import os
+import socket
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Optional
+
+from .errors import ServiceError
+from .paths import images_dir, to_data_relative
+
+MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024
+DOWNLOAD_TIMEOUT = 20
+MAX_REDIRECTS = 5
+
+_EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/gif": ".gif", "image/webp": ".webp"}
+
+
+@dataclass
+class StoredFile:
+    path: str  # data-relative (images/<uuid>.<ext>)
+    abs_path: Path
+    mime: str
+    size_bytes: int
+    source: str
+
+
+@dataclass
+class Item:
+    """One concrete input after glob expansion."""
+    source: str
+    label: Optional[str] = None
+    error: Optional[ServiceError] = None  # set when expansion itself failed
+
+
+@dataclass
+class IngestResult:
+    added: list = field(default_factory=list)  # [{"stored": StoredFile, "source", "label"}]
+    rejected: list = field(default_factory=list)  # [{"source", "reason", "code"}]
+
+
+def classify_source(src: str) -> Literal["url", "glob", "path"]:
+    lowered = src.lower()
+    if lowered.startswith("http://") or lowered.startswith("https://"):
+        return "url"
+    if any(ch in src for ch in "*?[") and not os.path.exists(os.path.expanduser(src)):
+        return "glob"
+    return "path"
+
+
+def sniff_image(data: bytes) -> str:
+    """The image mime type for PNG/JPEG/GIF/WebP magic bytes; ServiceError(invalid_image) otherwise."""
+    if data.startswith(b"\x89PNG\r\n\x1a\n") and len(data) >= 33:
+        return "image/png"
+    if data.startswith(b"\xff\xd8\xff") and len(data) >= 4:
+        return "image/jpeg"
+    if data[:6] in (b"GIF87a", b"GIF89a") and len(data) >= 10:
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP" and len(data) >= 16:
+        return "image/webp"
+    raise ServiceError("invalid_image", "not an image (PNG, JPEG, GIF or WebP expected)")
+
+
+def _store(data: bytes, source: str) -> StoredFile:
+    mime = sniff_image(data)
+    dest = images_dir() / f"{uuid.uuid4()}{_EXT[mime]}"
+    tmp = dest.with_name(dest.name + ".part")
+    try:
+        tmp.write_bytes(data)
+        os.replace(tmp, dest)
+    finally:
+        tmp.unlink(missing_ok=True)
+    return StoredFile(to_data_relative(dest), dest, mime, len(data), source)
+
+
+def import_local(path: Path) -> StoredFile:
+    path = Path(path).expanduser()
+    if path.is_dir():
+        raise ServiceError("invalid_image", "is a directory")
+    if not path.is_file():
+        raise ServiceError("not_found", "file not found")
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        raise ServiceError("invalid_image", f"cannot read file: {exc.strerror or exc}")
+    return _store(data, str(path))
+
+
+class _LimitedRedirects(urllib.request.HTTPRedirectHandler):
+    def __init__(self, max_redirects: int):
+        self.max_redirections = max_redirects
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if not newurl.lower().startswith(("http://", "https://")):
+            raise ServiceError("invalid_image", "redirect to a non-http(s) URL refused")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _clearly_not_image(content_type: str) -> bool:
+    """Reject text/HTML/JSON/XML responses early. Anything else (image/*, octet-stream, a
+    missing header) goes on to the magic-byte check, which is the final authority."""
+    if not content_type:
+        return False
+    main, _, sub = content_type.partition("/")
+    return main == "text" or any(k in sub for k in ("html", "json", "xml"))
+
+
+def download_url(
+    url: str,
+    *,
+    max_bytes: int = MAX_DOWNLOAD_BYTES,
+    timeout: float = DOWNLOAD_TIMEOUT,
+    max_redirects: int = MAX_REDIRECTS,
+) -> StoredFile:
+    if not url.lower().startswith(("http://", "https://")):
+        raise ServiceError("invalid_image", "only http(s) URLs are supported")
+    request = urllib.request.Request(url, headers={"User-Agent": "bugcap"}, method="GET")
+    opener = urllib.request.build_opener(_LimitedRedirects(max_redirects))
+    try:
+        with opener.open(request, timeout=timeout) as response:
+            hint = response.headers.get("Content-Type", "").split(";")[0].strip().lower()
+            if _clearly_not_image(hint):
+                raise ServiceError("invalid_image", f"not an image (content is {hint})")
+            declared = response.headers.get("Content-Length")
+            if declared and declared.isdigit() and int(declared) > max_bytes:
+                raise ServiceError("too_large", f"larger than {max_bytes // (1024 * 1024)} MB")
+            chunks: list[bytes] = []
+            total = 0
+            while True:
+                chunk = response.read(64 * 1024)
+                if not chunk:
+                    break
+                total += len(chunk)
+                if total > max_bytes:
+                    raise ServiceError("too_large", f"larger than {max_bytes // (1024 * 1024)} MB")
+                chunks.append(chunk)
+    except ServiceError:
+        raise
+    except urllib.error.HTTPError as exc:
+        if exc.code in (301, 302, 303, 307, 308):
+            raise ServiceError("invalid_image", "too many redirects") from exc
+        raise ServiceError("invalid_image", f"HTTP {exc.code}") from exc
+    except (socket.timeout, TimeoutError) as exc:
+        raise ServiceError("timeout", f"timed out after {timeout:g} s") from exc
+    except urllib.error.URLError as exc:
+        if isinstance(exc.reason, (socket.timeout, TimeoutError)):
+            raise ServiceError("timeout", f"timed out after {timeout:g} s") from exc
+        raise ServiceError("invalid_image", f"download failed: {exc.reason}") from exc
+    data = b"".join(chunks)
+    try:
+        return _store(data, url)
+    except ServiceError as exc:
+        suffix = f" (content is {hint})" if hint else ""
+        raise ServiceError(exc.code, exc.message + suffix) from None
+
+
+def resolve_glob(pattern: str) -> list[str]:
+    """All matches, sorted by name (directories included; they are rejected per item)."""
+    return sorted(glob.glob(os.path.expanduser(pattern)))
+
+
+def expand_sources(sources: list[str], labels: Optional[list[Optional[str]]] = None) -> list[Item]:
+    """Expand globs; `labels` pairs up with `sources` by position (empty/None = no label)."""
+    items: list[Item] = []
+    for position, source in enumerate(sources):
+        label = labels[position] if labels and position < len(labels) else None
+        label = label or None
+        kind = classify_source(source)
+        if kind == "glob":
+            matches = resolve_glob(source)
+            if not matches:
+                items.append(Item(source, label, ServiceError("not_found", f"no files match {source}")))
+            elif label and len(matches) > 1:
+                items.append(Item(source, label, ServiceError(
+                    "invalid_label", f"label {label!r} cannot apply to {source}, which matches {len(matches)} files")))
+            else:
+                items.extend(Item(m, label) for m in matches)
+        else:
+            items.append(Item(source, label))
+    return items
+
+
+def ingest_item(item: Item) -> StoredFile:
+    if item.error is not None:
+        raise item.error
+    if classify_source(item.source) == "url":
+        return download_url(item.source)
+    return import_local(Path(item.source))
+
+
+def ingest_sources(sources: list[str], labels: Optional[list[Optional[str]]] = None) -> IngestResult:
+    """Process each input independently (a failure never blocks the others)."""
+    result = IngestResult()
+    for item in expand_sources(sources, labels):
+        try:
+            stored = ingest_item(item)
+        except ServiceError as exc:
+            result.rejected.append({"source": item.source, "reason": exc.message, "code": exc.code})
+        else:
+            result.added.append({"stored": stored, "source": item.source, "label": item.label})
+    return result

bugcap/live.py

@@ -0,0 +1,292 @@
+"""`bugcap live`: a small always-on-top control window for reporting many bugs in a row.
+
+Thin Tk shell over `live_session.LiveSession`: Start runs the existing capture backend (the
+control window hides itself so it is not in the screenshot), a details window collects the
+title/notes/tags/status, and Save returns to the ready state."""
+from __future__ import annotations
+
+import os
+import queue
+import sys
+import threading
+from pathlib import Path
+
+from . import capture, drafts, refs, repo
+from .errors import ServiceError
+from .live_session import LiveSession, LiveState, initial_tags
+from .store import STATUSES
+
+TK_HINT = (
+    "Live mode needs tkinter. On Linux install your distro's python3-tk package "
+    "(e.g. sudo apt install python3-tk)."
+)
+NO_DESKTOP = "Live mode needs a desktop session (no DISPLAY or WAYLAND_DISPLAY is set)."
+THUMB = 420
+
+
+def check_environment() -> tuple[int, str]:
+    """(0, "") when a window can be opened, else (3, explanation)."""
+    if sys.platform not in ("win32", "darwin") and not (
+        os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")
+    ):
+        return 3, NO_DESKTOP
+    try:
+        import tkinter  # noqa: F401
+    except ImportError:
+        return 3, TK_HINT
+    return 0, ""
+
+
+def run(repo_dir=None) -> int:
+    code, message = check_environment()
+    if code:
+        print(f"error: {message}", file=sys.stderr)
+        return code
+    import tkinter as tk
+
+    try:
+        root = tk.Tk()
+    except tk.TclError as exc:
+        print(f"error: cannot open a window ({exc}). {NO_DESKTOP}", file=sys.stderr)
+        return 3
+
+    cfg = repo.load_repo_config(Path(repo_dir)) if repo_dir else repo.load_repo_config()
+    app = _App(root, LiveSession(cfg), cfg)
+    app.start_ui()
+    root.mainloop()
+    return 0
+
+
+class _App:
+    def __init__(self, root, session: LiveSession, cfg):
+        import tkinter as tk
+        from tkinter import ttk
+
+        self.tk, self.ttk = tk, ttk
+        self.root, self.session, self.cfg = root, session, cfg
+        self.results: "queue.Queue" = queue.Queue()
+        self.details = None
+        self.widgets: dict = {}
+        self.pending_drafts: list = []
+
+    # --- control window --------------------------------------------------------
+
+    def start_ui(self) -> None:
+        tk, ttk, root = self.tk, self.ttk, self.root
+        root.title("bugcap live")
+        root.resizable(False, False)
+        notice = ""
+        try:
+            root.attributes("-topmost", True)
+        except tk.TclError:
+            notice = "Always-on-top is not supported here; the window may be hidden by others."
+        frame = ttk.Frame(root, padding=12)
+        frame.grid()
+        self.start_button = ttk.Button(frame, text="Start", command=self.on_start)
+        self.start_button.grid(row=0, column=0, sticky="ew")
+        self.counter = ttk.Label(frame, text="0 saved this session")
+        self.counter.grid(row=1, column=0, pady=(8, 0))
+        self.status = ttk.Label(frame, text=notice, wraplength=240, foreground="#a15c00")
+        self.status.grid(row=2, column=0, pady=(4, 0))
+        root.protocol("WM_DELETE_WINDOW", self.on_close_control)
+        self.pending_drafts = drafts.list_drafts(self.cfg.key if self.cfg else None)
+        root.after(200, self.offer_drafts)
+
+    def set_status(self, text: str) -> None:
+        self.status.configure(text=text)
+
+    def refresh_counter(self) -> None:
+        self.counter.configure(text=f"{self.session.saved_count} saved this session")
+        self.start_button.state(["!disabled"] if self.session.state is LiveState.READY else ["disabled"])
+
+    def on_start(self) -> None:
+        if not self.session.start():
+            return
+        self.refresh_counter()
+        self.set_status("Capturing...")
+        self.root.withdraw()
+        self.root.after(350, self._launch_capture)
+
+    def _launch_capture(self) -> None:
+        def worker():
+            try:
+                self.results.put((str(capture.capture_screenshot()), None))
+            except capture.CaptureError as exc:
+                self.results.put((None, str(exc)))
+            except Exception as exc:  # never lose the window to a backend crash
+                self.results.put((None, f"capture failed: {exc}"))
+
+        threading.Thread(target=worker, daemon=True).start()
+        self.root.after(100, self._poll)
+
+    def _poll(self) -> None:
+        try:
+            path, message = self.results.get_nowait()
+        except queue.Empty:
+            self.root.after(100, self._poll)
+            return
+        self.root.deiconify()
+        self.session.capture_done(path, message)
+        self.refresh_counter()
+        if self.session.state is LiveState.DETAILS:
+            self.set_status("")
+            self.open_details()
+        else:
+            self.set_status(self.session.message)
+
+    # --- drafts ----------------------------------------------------------------
+
+    def offer_drafts(self) -> None:
+        from tkinter import messagebox
+
+        while self.pending_drafts and self.session.state is LiveState.READY:
+            draft = self.pending_drafts.pop(0)
+            title = draft.title or "(untitled)"
+            answer = messagebox.askyesnocancel(
+                "Unsaved draft", f"Restore the unsaved draft {title!r}?\n\nYes: restore   No: discard   Cancel: keep for later",
+                parent=self.root,
+            )
+            if answer is None:
+                continue
+            if answer:
+                self.session.restore(draft.png_path, draft.id)
+                self.refresh_counter()
+                self.open_details(draft.fields())
+                return
+            drafts.delete_draft(draft.id)
+
+    # --- details window --------------------------------------------------------
+
+    def open_details(self, prefill: dict | None = None) -> None:
+        tk, ttk = self.tk, self.ttk
+        win = tk.Toplevel(self.root)
+        self.details = win
+        win.title("New bug report")
+        try:
+            win.attributes("-topmost", True)
+        except tk.TclError:
+            pass
+        frame = ttk.Frame(win, padding=12)
+        frame.grid()
+        w = self.widgets = {}
+
+        try:
+            image = tk.PhotoImage(file=str(self.session.screenshot))
+            factor = max(1, -(-max(image.width(), image.height()) // THUMB))
+            w["photo"] = image.subsample(factor, factor) if factor > 1 else image
+            ttk.Label(frame, image=w["photo"]).grid(row=0, column=0, columnspan=2, pady=(0, 8))
+        except tk.TclError:
+            ttk.Label(frame, text="(preview unavailable)").grid(row=0, column=0, columnspan=2)
+
+        prefill = prefill or {}
+        ttk.Label(frame, text="Title").grid(row=1, column=0, sticky="w")
+        w["title"] = ttk.Entry(frame, width=48)
+        w["title"].grid(row=1, column=1, sticky="ew")
+        w["title"].insert(0, prefill.get("title", ""))
+        ttk.Label(frame, text="Notes").grid(row=2, column=0, sticky="nw")
+        w["notes"] = tk.Text(frame, width=48, height=6, wrap="word")
+        w["notes"].grid(row=2, column=1, sticky="ew")
+        w["notes"].insert("1.0", prefill.get("notes", ""))
+        w["notes"].bind("<KeyRelease>", lambda e: self.check_notes())
+        ttk.Label(frame, text="Tags").grid(row=3, column=0, sticky="w")
+        w["tags"] = ttk.Entry(frame, width=48)
+        w["tags"].grid(row=3, column=1, sticky="ew")
+        w["tags"].insert(0, ", ".join(initial_tags(self.cfg, prefill)))
+        ttk.Label(frame, text="Status").grid(row=4, column=0, sticky="w")
+        w["status"] = ttk.Combobox(frame, values=list(STATUSES), state="readonly", width=16)
+        w["status"].set(prefill.get("status", "open"))
+        w["status"].grid(row=4, column=1, sticky="w")
+        ttk.Label(frame, text="Repo").grid(row=5, column=0, sticky="w")
+        ttk.Label(frame, text=(self.cfg.key if self.cfg else "(none)")).grid(row=5, column=1, sticky="w")
+        w["error"] = ttk.Label(frame, text="", foreground="#b00020", wraplength=420)
+        w["error"].grid(row=6, column=0, columnspan=2, sticky="w", pady=(6, 0))
+        buttons = ttk.Frame(frame)
+        buttons.grid(row=7, column=0, columnspan=2, sticky="e", pady=(8, 0))
+        ttk.Button(buttons, text="Discard", command=self.on_discard).grid(row=0, column=0, padx=4)
+        ttk.Button(buttons, text="Save", command=self.on_save).grid(row=0, column=1)
+        win.protocol("WM_DELETE_WINDOW", self.on_close_details)
+        w["title"].focus_set()
+        self.check_notes()
+
+    def fields(self) -> dict:
+        w = self.widgets
+        return {
+            "title": w["title"].get().strip(),
+            "notes": w["notes"].get("1.0", "end-1c"),
+            "tags": [t.strip() for t in w["tags"].get().split(",") if t.strip()],
+            "status": w["status"].get() or "open",
+        }
+
+    def check_notes(self) -> bool:
+        """Show an inline message for an unknown `@` reference (image 1 is the screenshot)."""
+        from .store import Media
+
+        notes = self.widgets["notes"].get("1.0", "end-1c")
+        shot = [Media(0, 0, 1, None, "image", None, "image/png", 0, None, "")]
+        try:
+            refs.validate_references(notes, shot)
+        except ServiceError as exc:
+            self.widgets["error"].configure(
+                text=f"{exc.message} (valid: {', '.join(exc.details.get('valid', []))})"
+            )
+            return False
+        self.widgets["error"].configure(text="")
+        return True
+
+    def close_details(self) -> None:
+        if self.details is not None:
+            self.details.destroy()
+        self.details = None
+        self.widgets = {}
+        self.refresh_counter()
+
+    def on_save(self) -> None:
+        try:
+            report = self.session.save(self.fields())
+        except ServiceError as exc:
+            self.widgets["error"].configure(text=exc.message)
+            return
+        self.close_details()
+        self.set_status(f"Saved report #{report.id}")
+        self.offer_drafts()
+
+    def on_discard(self) -> None:
+        from tkinter import messagebox
+
+        ok = messagebox.askyesno("Discard", "Discard this capture and everything typed?", parent=self.details)
+        if self.session.discard(ok):
+            self.close_details()
+            self.set_status("Discarded.")
+            self.offer_drafts()
+
+    def _keep_as_draft(self) -> None:
+        if self.session.screenshot is None:
+            return
+        if self.session.draft_id:
+            drafts.delete_draft(self.session.draft_id)
+        drafts.save_draft(self.cfg.key if self.cfg else None, self.session.screenshot, self.fields())
+        self.session.screenshot = None
+        self.session.draft_id = None
+        self.session.state = LiveState.READY
+
+    def on_close_details(self) -> None:
+        from tkinter import messagebox
+
+        if self.session.request_close(True) == "needs_confirm":
+            ok = messagebox.askyesno("Close", "Save this report as a draft?", parent=self.details)
+            if self.session.confirm_close(ok) == "save_draft":
+                self._keep_as_draft()
+                self.close_details()
+                self.set_status("Draft saved.")
+
+    def on_close_control(self) -> None:
+        from tkinter import messagebox
+
+        if self.session.state is LiveState.DETAILS and self.details is not None:
+            decision = self.session.request_close(True)
+            if decision == "needs_confirm":
+                ok = messagebox.askyesno("Quit", "Save the open report as a draft and quit?", parent=self.details)
+                if self.session.confirm_close(ok) != "save_draft":
+                    return
+                self._keep_as_draft()
+        self.root.destroy()

bugcap/live_session.py

@@ -0,0 +1,125 @@
+"""The logic of `bugcap live`, without any GUI: a small state machine plus the save step.
+`live.py` is a thin Tk shell over this, so everything here is testable without a display."""
+from __future__ import annotations
+
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Callable, Optional
+
+from . import service
+from .store import Report, Store
+
+
+class LiveState(Enum):
+    READY = "ready"
+    CAPTURING = "capturing"
+    DETAILS = "details"
+
+
+def initial_tags(repo_cfg, prefill: Optional[dict] = None) -> list:
+    """Tags shown when the details window opens: a restored draft's own tags, otherwise
+    the launch repo's tag."""
+    if prefill and prefill.get("tags") is not None:
+        return list(prefill["tags"])
+    return [repo_cfg.tag] if repo_cfg is not None else []
+
+
+class LiveSession:
+    def __init__(self, repo_cfg=None, store_factory: Callable[[], Store] = Store):
+        self.repo_cfg = repo_cfg
+        self.store_factory = store_factory
+        self.state = LiveState.READY
+        self.saved_count = 0
+        self.screenshot: Optional[Path] = None
+        self.draft_id: Optional[str] = None
+        self.message = ""
+
+    # --- transitions -----------------------------------------------------------
+
+    def start(self) -> bool:
+        """Begin a capture. Ignored (False) unless READY, so a double click cannot start twice."""
+        if self.state is not LiveState.READY:
+            return False
+        self.state = LiveState.CAPTURING
+        self.message = ""
+        return True
+
+    def capture_done(self, path, message: Optional[str] = None) -> None:
+        if self.state is not LiveState.CAPTURING:
+            return
+        if path is None or not Path(path).is_file():
+            self.state = LiveState.READY
+            self.message = message or "Nothing was captured."
+            self.screenshot = None
+            return
+        self.screenshot = Path(path)
+        self.draft_id = None
+        self.state = LiveState.DETAILS
+
+    def restore(self, path, draft_id: str) -> None:
+        """Open the details step for a recovered draft."""
+        if self.state is LiveState.READY:
+            self.screenshot = Path(path)
+            self.draft_id = draft_id
+            self.state = LiveState.DETAILS
+
+    def save(self, fields: dict) -> Report:
+        """Save the report (screenshot is image 1). Raises ServiceError (empty title, bad
+        `@` reference, ...); the state stays DETAILS so the user can fix it."""
+        if self.state is not LiveState.DETAILS or self.screenshot is None:
+            raise RuntimeError("nothing to save")
+        tags = list(fields.get("tags") or [])
+        repo_key = None
+        if self.repo_cfg is not None:
+            repo_key = self.repo_cfg.key
+            if self.repo_cfg.tag not in tags:
+                tags.append(self.repo_cfg.tag)
+        with self.store_factory() as store:
+            report, _ = service.create_report(
+                store,
+                title=(fields.get("title") or "").strip(),
+                notes=fields.get("notes") or "",
+                tags=tags,
+                repo=repo_key,
+                status=fields.get("status") or "open",
+                sources=[str(self.screenshot)],
+            )
+        self._drop_screenshot()
+        self.saved_count += 1
+        self.state = LiveState.READY
+        self.message = f"Saved report #{report.id}"
+        return report
+
+    def discard(self, confirmed: bool) -> bool:
+        if self.state is not LiveState.DETAILS or not confirmed:
+            return False
+        self._drop_screenshot()
+        self.state = LiveState.READY
+        self.message = "Discarded."
+        return True
+
+    def request_close(self, has_unsaved: bool) -> str:
+        """'close' when nothing would be lost, otherwise 'needs_confirm'."""
+        if self.state is LiveState.DETAILS and has_unsaved:
+            return "needs_confirm"
+        return "close"
+
+    def confirm_close(self, confirmed: bool) -> str:
+        """After 'needs_confirm': 'save_draft' keeps the work, 'stay' keeps the window open."""
+        return "save_draft" if confirmed else "stay"
+
+    # --- helpers ---------------------------------------------------------------
+
+    def _drop_screenshot(self) -> None:
+        from . import drafts
+
+        if self.screenshot is not None:
+            try:
+                os.unlink(self.screenshot)
+            except OSError:
+                pass
+        if self.draft_id:
+            drafts.delete_draft(self.draft_id)
+        self.screenshot = None
+        self.draft_id = None