xkcdkit 0.1.0__py3-none-any.whl

xkcdkit/sources.py

@@ -0,0 +1,89 @@
+"""Fetchers for xkcd.com and explainxkcd.com.
+
+Every function takes an ``httpx2.AsyncClient`` so callers control pooling,
+timeouts and, in tests, the transport.
+"""
+
+import html
+import re
+from typing import Any
+
+import httpx2
+
+from xkcdkit import ComicNotFound, XKCDError, __version__
+from xkcdkit.models import ArchiveEntry, Comic
+
+XKCD = "https://xkcd.com"
+EXPLAIN_API = "https://www.explainxkcd.com/wiki/api.php"
+ARCHIVE_LINK = re.compile(r'<a href="/(\d+)/" title="([^"]+)">(.*?)</a>', re.DOTALL)
+HTML_TAG = re.compile(r"</?[a-z][a-z0-9]*(?:\s[^>]*)?>")
+
+
+def user_agent() -> str:
+    """A User-Agent that names the project, as both sites ask of bots."""
+    return f"xkcdkit/{__version__} (+https://github.com/eivl/xkcdkit)"
+
+
+async def request(client: httpx2.AsyncClient, url: str, **params: Any) -> httpx2.Response:
+    """GET ``url`` and wrap transport failures in ``XKCDError``."""
+    try:
+        return await client.get(url, params=params or None)
+    except httpx2.HTTPError as exc:
+        raise XKCDError(f"{url}: {exc}") from exc
+
+
+async def fetch_comic(client: httpx2.AsyncClient, num: int | None) -> Comic:
+    """Fetch comic ``num`` from xkcd.com, or the latest comic when ``num`` is None."""
+    url = f"{XKCD}/info.0.json" if num is None else f"{XKCD}/{num}/info.0.json"
+    response = await request(client, url)
+    if response.status_code == 404:
+        raise ComicNotFound(f"xkcd has no comic {num}")
+    if response.status_code != 200:
+        raise XKCDError(f"{url}: HTTP {response.status_code}")
+    return Comic.model_validate(response.json())
+
+
+def parse_archive(page: str) -> list[ArchiveEntry]:
+    """Turn the archive page's anchors into entries, in page order (newest first)."""
+    return [
+        ArchiveEntry(num=int(num), date=date, title=html.unescape(HTML_TAG.sub("", title)))
+        for num, date, title in ARCHIVE_LINK.findall(page)
+    ]
+
+
+async def fetch_archive(client: httpx2.AsyncClient) -> list[ArchiveEntry]:
+    """Fetch and parse https://xkcd.com/archive/."""
+    response = await request(client, f"{XKCD}/archive/")
+    if response.status_code != 200:
+        raise XKCDError(f"archive: HTTP {response.status_code}")
+    return parse_archive(response.text)
+
+
+async def fetch_explanation(client: httpx2.AsyncClient, num: int) -> tuple[str, int] | None:
+    """Fetch the explainxkcd page for ``num`` as ``(wikitext, revid)``, or None if absent."""
+    response = await request(
+        client,
+        EXPLAIN_API,
+        action="parse",
+        page=str(num),
+        redirects=1,
+        prop="wikitext|revid",
+        format="json",
+        formatversion=2,
+    )
+    if response.status_code != 200:
+        raise XKCDError(f"explainxkcd: HTTP {response.status_code}")
+    payload = response.json()
+    if "error" in payload:
+        if payload["error"].get("code") == "missingtitle":
+            return None
+        raise XKCDError(f"explainxkcd: {payload['error'].get('info', 'unknown error')}")
+    return payload["parse"]["wikitext"], int(payload["parse"]["revid"])
+
+
+async def fetch_image(client: httpx2.AsyncClient, comic: Comic) -> bytes:
+    """Download the comic's image bytes."""
+    response = await request(client, comic.img)
+    if response.status_code != 200:
+        raise XKCDError(f"{comic.img}: HTTP {response.status_code}")
+    return response.content

xkcdkit/store.py

@@ -0,0 +1,156 @@
+"""Local SQLite cache of comics, the archive index and sync metadata."""
+
+import os
+import sqlite3
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+
+from platformdirs import user_data_path
+from rapidfuzz import fuzz
+
+from xkcdkit.models import ArchiveEntry, Comic
+
+COLUMNS = list(Comic.model_fields)
+SCHEMA = f"""
+CREATE TABLE IF NOT EXISTS comics ({", ".join(COLUMNS)}, PRIMARY KEY (num));
+CREATE TABLE IF NOT EXISTS archive (num INTEGER PRIMARY KEY, date TEXT, title TEXT);
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+"""
+SEARCH_CUTOFF = 60.0
+
+
+def default_path() -> Path:
+    """Database location: ``$XKCDKIT_DB`` or the platform user data directory."""
+    override = os.environ.get("XKCDKIT_DB")
+    if override:
+        return Path(override)
+    return user_data_path("xkcdkit") / "xkcd.sqlite3"
+
+
+def utc_now() -> datetime:
+    """Current time as a timezone-aware UTC datetime."""
+    return datetime.now(UTC)
+
+
+class Store:
+    """Insert-only cache of comics with fuzzy search.
+
+    Use as a context manager so the connection is closed::
+
+        with Store() as store:
+            comic = store.get(614)
+    """
+
+    def __init__(self, path: Path | str | None = None) -> None:
+        """Open (and create if needed) the database at ``path``."""
+        self.path = Path(path) if path else default_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.db = sqlite3.connect(self.path)
+        self.db.row_factory = sqlite3.Row
+        self.db.executescript(SCHEMA)
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(
+        self, *exc: tuple[type[BaseException] | None, BaseException | None, TracebackType | None]
+    ) -> None:
+        """Close the connection on exit."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self.db.close()
+
+    def write(self, comic: Comic, verb: str) -> None:
+        """Insert a comic using ``verb`` (``OR IGNORE`` or ``OR REPLACE``)."""
+        stamped = comic.model_copy(update={"synced_at": comic.synced_at or utc_now()})
+        row = stamped.model_dump(mode="json")
+        columns, marks = ", ".join(COLUMNS), ", ".join("?" for _ in COLUMNS)
+        sql = f"INSERT {verb} INTO comics ({columns}) VALUES ({marks})"  # noqa: S608 - all constants
+        with self.db:
+            self.db.execute(sql, [row[column] for column in COLUMNS])
+
+    def put(self, comic: Comic) -> None:
+        """Store a comic unless one with the same number already exists."""
+        self.write(comic, "OR IGNORE")
+
+    def replace(self, comic: Comic) -> None:
+        """Store a comic, overwriting any existing row with the same number."""
+        self.write(comic, "OR REPLACE")
+
+    def get(self, num: int) -> Comic | None:
+        """Return the cached comic ``num`` or None."""
+        row = self.db.execute("SELECT * FROM comics WHERE num = ?", (num,)).fetchone()
+        return Comic.model_validate(dict(row)) if row else None
+
+    def has(self, num: int) -> bool:
+        """Whether comic ``num`` is cached."""
+        return self.get(num) is not None
+
+    def nums(self) -> list[int]:
+        """All cached comic numbers, ascending."""
+        return [row[0] for row in self.db.execute("SELECT num FROM comics ORDER BY num")]
+
+    def count(self) -> int:
+        """Number of cached comics."""
+        return int(self.db.execute("SELECT COUNT(*) FROM comics").fetchone()[0])
+
+    def all(self) -> list[Comic]:
+        """Every cached comic, ascending by number."""
+        rows = self.db.execute("SELECT * FROM comics ORDER BY num")
+        return [Comic.model_validate(dict(row)) for row in rows]
+
+    def put_archive(self, entries: list[ArchiveEntry]) -> None:
+        """Replace the archive index with ``entries``."""
+        with self.db:
+            self.db.execute("DELETE FROM archive")
+            self.db.executemany(
+                "INSERT OR REPLACE INTO archive VALUES (?, ?, ?)",
+                [(e.num, e.date.isoformat(), e.title) for e in entries],
+            )
+
+    def archive(self) -> list[ArchiveEntry]:
+        """The archive index, newest first."""
+        rows = self.db.execute("SELECT * FROM archive ORDER BY num DESC")
+        return [ArchiveEntry.model_validate(dict(row)) for row in rows]
+
+    def set_meta(self, key: str, value: str) -> None:
+        """Store a metadata value such as ``last_sync_at``."""
+        with self.db:
+            self.db.execute("INSERT OR REPLACE INTO meta VALUES (?, ?)", (key, value))
+
+    def get_meta(self, key: str) -> str | None:
+        """Read a metadata value, or None when unset."""
+        row = self.db.execute("SELECT value FROM meta WHERE key = ?", (key,)).fetchone()
+        return str(row[0]) if row else None
+
+    def stale(self, max_age: timedelta) -> list[int]:
+        """Numbers of comics older than ``max_age`` or still missing an explanation."""
+        cutoff = (utc_now() - max_age).isoformat()
+        rows = self.db.execute(
+            "SELECT num FROM comics WHERE synced_at < ? OR explanation_missing ORDER BY num",
+            (cutoff,),
+        )
+        return [row[0] for row in rows]
+
+    def search(self, query: str, limit: int = 10) -> list[tuple[Comic, float]]:
+        """Fuzzy-search titles, alt text, transcripts and explanations.
+
+        Returns ``(comic, score)`` pairs, best first, scores from 0 to 100.
+        """
+        scored = [(comic, score_comic(comic, query)) for comic in self.all()]
+        hits = [(comic, score) for comic, score in scored if score >= SEARCH_CUTOFF]
+        hits.sort(key=lambda hit: (-hit[1], hit[0].num))
+        return hits[:limit]
+
+
+def score_comic(comic: Comic, query: str) -> float:
+    """Score a comic against a query: exact-ish titles win, long text counts a bit less."""
+    title = float(fuzz.WRatio(query, comic.title, processor=str.lower))
+    body = " ".join([comic.alt, comic.transcript, comic.explanation_text])
+    text = float(fuzz.token_set_ratio(query, body, processor=str.lower))
+    return max(title, 0.9 * text)

xkcdkit/tui.py

@@ -0,0 +1,188 @@
+"""A lazygit-style browser: archive on the left, image and text panes on the right."""
+
+import io
+from typing import ClassVar
+
+from PIL import Image as PILImage
+from rapidfuzz import fuzz
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.widgets import Footer, Header, Input, OptionList, Static, TabbedContent, TabPane
+from textual.widgets.option_list import Option
+from textual_image.widget import Image
+
+from xkcdkit import XKCDError
+from xkcdkit.client import AsyncXKCD
+from xkcdkit.models import ArchiveEntry, Comic
+from xkcdkit.sources import fetch_image
+
+HELP = "j/k move  / filter  enter open  r random  l latest  i image  s sync  q quit"
+
+
+def option(entry: ArchiveEntry) -> Option:
+    """An archive row: bold number, then the title, keyed by the comic number."""
+    return Option(Text.assemble((f"{entry.num:>5}", "bold"), "  ", entry.title), id=str(entry.num))
+
+
+class XKCDApp(App[None]):
+    """Browse the xkcd archive with images, alt text, transcripts and explanations."""
+
+    TITLE = "xkcd"
+    CSS = """
+    #archive-pane { width: 40; border: round $primary; }
+    #archive { height: 1fr; }
+    #image-pane { height: 2fr; border: round $secondary; align: center middle; }
+    TabbedContent { height: 1fr; }
+    .text { padding: 0 1; }
+    """
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("j", "cursor('down')", "Down"),
+        Binding("k", "cursor('up')", "Up"),
+        Binding("slash", "focus_filter", "Filter", key_display="/"),
+        Binding("r", "random", "Random"),
+        Binding("l", "latest", "Latest"),
+        Binding("i", "toggle_image", "Image"),
+        Binding("s", "sync", "Sync"),
+        Binding("question_mark", "help", "Help", key_display="?"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, client: AsyncXKCD) -> None:
+        """Keep the client; the store it holds feeds the archive list."""
+        super().__init__()
+        self.client = client
+        self.entries: list[ArchiveEntry] = []
+
+    def compose(self) -> ComposeResult:
+        """Build the two-column layout."""
+        yield Header()
+        with Horizontal():
+            with Vertical(id="archive-pane"):
+                yield Input(placeholder="filter titles", id="filter")
+                yield OptionList(id="archive")
+            with Vertical():
+                yield Vertical(Image(id="image"), id="image-pane")
+                with TabbedContent():
+                    with TabPane("Alt text", id="tab-alt"):
+                        yield VerticalScroll(Static(id="alt", classes="text", markup=False))
+                    with TabPane("Transcript", id="tab-transcript"):
+                        yield VerticalScroll(Static(id="transcript", classes="text", markup=False))
+                    with TabPane("Explanation", id="tab-explanation"):
+                        yield VerticalScroll(Static(id="explanation", classes="text", markup=False))
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Show the cached archive (syncing it on first run) and open the latest comic."""
+        self.query_one(OptionList).focus()
+        self.entries = self.client.store.archive()
+        self.show_entries(self.entries)
+        if not self.entries:
+            self.action_sync()
+        self.open(None)
+
+    def show_entries(self, entries: list[ArchiveEntry]) -> None:
+        """Replace the list contents."""
+        archive = self.query_one(OptionList)
+        archive.clear_options()
+        archive.add_options(option(entry) for entry in entries)
+        archive.highlighted = 0 if entries else None
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Fuzzy-filter the archive list as the user types."""
+        query = event.value.strip().lower()
+        if not query:
+            self.show_entries(self.entries)
+            return
+        scored = [(fuzz.WRatio(query, e.title.lower()), e) for e in self.entries]
+        self.show_entries([e for score, e in scored if score >= 70])
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Enter in the filter opens the first match."""
+        archive = self.query_one(OptionList)
+        if archive.option_count:
+            self.open(int(str(archive.get_option_at_index(0).id)))
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        """Enter on a row opens that comic."""
+        self.open(int(str(event.option.id)))
+
+    @work(exclusive=True, group="open")
+    async def open(self, num: int | None) -> None:
+        """Fetch comic ``num`` (or the latest, or a random one for -1) and show it."""
+        try:
+            if num is None:
+                comic = await self.client.latest()
+            elif num < 0:
+                comic = await self.client.random()
+            else:
+                comic = await self.client.get(num)
+            await self.show_comic(comic)
+        except XKCDError as exc:
+            self.notify(str(exc), severity="error")
+
+    async def show_comic(self, comic: Comic) -> None:
+        """Fill the panes from a comic."""
+        self.sub_title = f"#{comic.num}  {comic.title}  ({comic.date.isoformat()})"
+        self.query_one("#alt", Static).update(comic.alt)
+        self.query_one("#transcript", Static).update(comic.transcript or "No transcript.")
+        explanation = comic.explanation_text or "No explanation on explainxkcd yet."
+        self.query_one("#explanation", Static).update(explanation)
+        if self.query_one("#image-pane").display:
+            await self.show_image(comic)
+
+    async def show_image(self, comic: Comic) -> None:
+        """Download and display the comic image, reporting rather than crashing on bad data."""
+        try:
+            data = await fetch_image(self.client.http, comic)
+            self.query_one("#image", Image).image = PILImage.open(io.BytesIO(data))
+        except (XKCDError, OSError) as exc:
+            self.notify(f"Image unavailable: {exc}", severity="warning")
+
+    def action_cursor(self, direction: str) -> None:
+        """Move the archive cursor with j/k."""
+        archive = self.query_one(OptionList)
+        archive.action_cursor_down() if direction == "down" else archive.action_cursor_up()
+
+    def action_focus_filter(self) -> None:
+        """Jump to the filter box."""
+        self.query_one("#filter", Input).focus()
+
+    def action_random(self) -> None:
+        """Open a random comic."""
+        self.open(-1)
+
+    def action_latest(self) -> None:
+        """Open the newest comic."""
+        self.open(None)
+
+    def action_toggle_image(self) -> None:
+        """Show or hide the image pane."""
+        pane = self.query_one("#image-pane")
+        pane.display = not pane.display
+
+    @work(exclusive=True, group="sync")
+    async def action_sync(self) -> None:
+        """Refresh the archive and latest comic, then report."""
+        try:
+            added = await self.client.sync()
+        except XKCDError as exc:
+            self.notify(str(exc), severity="error")
+            return
+        self.entries = self.client.store.archive()
+        self.show_entries(self.entries)
+        self.notify(f"Synced: {added} new comic(s).")
+
+    def action_help(self) -> None:
+        """Show the key bindings."""
+        self.notify(HELP, title="Keys", timeout=8)
+
+
+def run_tui(client: AsyncXKCD) -> None:
+    """Start the browser and close the client when it exits."""
+    try:
+        XKCDApp(client).run()
+    finally:
+        client.store.close()