xkcdkit 0.1.0__py3-none-any.whl

xkcdkit/__init__.py

@@ -0,0 +1,56 @@
+"""xkcd comics as a library, a CLI and a TUI, with a local cache.
+
+Quick start::
+
+    from xkcdkit import AsyncXKCD
+
+    async with AsyncXKCD() as xk:
+        comic = await xk.get(614)
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING
+
+try:
+    __version__ = version("xkcdkit")
+except PackageNotFoundError:  # pragma: no cover - only when not installed
+    __version__ = "0.0.0"
+
+
+class XKCDError(Exception):
+    """Base class for every error raised by xkcdkit."""
+
+
+class ComicNotFound(XKCDError):  # noqa: N818 - the name reads better at call sites
+    """Raised when xkcd has no comic with the requested number."""
+
+
+if TYPE_CHECKING:
+    from xkcdkit.client import XKCD, AsyncXKCD
+    from xkcdkit.models import ArchiveEntry, Comic
+
+LAZY = {
+    "AsyncXKCD": "xkcdkit.client",
+    "XKCD": "xkcdkit.client",
+    "ArchiveEntry": "xkcdkit.models",
+    "Comic": "xkcdkit.models",
+}
+
+
+def __getattr__(name: str) -> object:
+    """Import the heavier submodules only when their names are first used."""
+    if name in LAZY:
+        module = __import__(LAZY[name], fromlist=[name])
+        return getattr(module, name)
+    raise AttributeError(f"module 'xkcdkit' has no attribute {name!r}")
+
+
+__all__ = [
+    "XKCD",
+    "ArchiveEntry",
+    "AsyncXKCD",
+    "Comic",
+    "ComicNotFound",
+    "XKCDError",
+    "__version__",
+]

xkcdkit/cli.py

@@ -0,0 +1,179 @@
+"""The ``xkcd`` command line interface."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from xkcdkit import XKCDError, __version__
+from xkcdkit.client import AsyncXKCD
+from xkcdkit.models import Comic
+from xkcdkit.render import can_draw, comic_image, comic_text
+from xkcdkit.sources import fetch_image
+
+app = typer.Typer(help="xkcd comics in your terminal.", no_args_is_help=True, add_completion=False)
+console = Console()
+errors = Console(stderr=True)
+Num = Annotated[int, typer.Argument(help="Comic number.")]
+Json = Annotated[bool, typer.Option("--json", help="Print JSON for piping.")]
+NoImage = Annotated[bool, typer.Option("--no-image", help="Do not draw the image.")]
+Explain = Annotated[bool, typer.Option("--explain", "-e", help="Include the explanation.")]
+
+
+@dataclass
+class Settings:
+    """Options shared by every command."""
+
+    db: str | None = None
+
+
+def open_client(db: str | None) -> AsyncXKCD:
+    """Create the client; tests replace this to inject fakes."""
+    return AsyncXKCD(db=db)
+
+
+def version(flag: bool) -> None:
+    """Print the version and exit when ``--version`` is given."""
+    if flag:
+        console.print(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    db: Annotated[str | None, typer.Option(help="Database file (default: user data dir).")] = None,
+    _: Annotated[bool, typer.Option("--version", callback=version, is_eager=True)] = False,
+) -> None:
+    """Fetch, browse and search xkcd comics with explanations from explainxkcd."""
+    ctx.obj = Settings(db=db)
+
+
+def run(ctx: typer.Context, action: Callable[[AsyncXKCD], Awaitable[Any]]) -> Any:
+    """Run an async action against a client, turning XKCDError into exit code 1."""
+
+    async def go() -> Any:
+        async with open_client(ctx.obj.db) as xk:
+            return await action(xk)
+
+    try:
+        return asyncio.run(go())
+    except XKCDError as exc:
+        errors.print(f"error: {exc}", markup=False, highlight=False)
+        raise typer.Exit(1) from exc
+
+
+@dataclass
+class View:
+    """How a comic should be presented."""
+
+    json: bool = False
+    image: bool = True
+    explain: bool = False
+
+
+async def present(xk: AsyncXKCD, pending: Awaitable[Comic], view: View) -> None:
+    """Await a comic and print it as JSON or as a card with an optional image."""
+    comic = await pending
+    if view.json:
+        console.print_json(comic.model_dump_json())
+        return
+    if view.image and can_draw():
+        console.print(comic_image(await fetch_image(xk.http, comic)))
+    console.print(comic_text(comic, explain=view.explain))
+
+
+@app.command()
+def show(
+    ctx: typer.Context, num: Num, no_image: NoImage = False, explain: Explain = False, json: Json = False
+) -> None:
+    """Show one comic by number."""
+    run(ctx, lambda xk: present(xk, xk.get(num), View(json, not no_image, explain)))
+
+
+@app.command()
+def latest(
+    ctx: typer.Context, no_image: NoImage = False, explain: Explain = False, json: Json = False
+) -> None:
+    """Show the newest comic."""
+    run(ctx, lambda xk: present(xk, xk.latest(), View(json, not no_image, explain)))
+
+
+@app.command()
+def random(
+    ctx: typer.Context, no_image: NoImage = False, explain: Explain = False, json: Json = False
+) -> None:
+    """Show a random comic."""
+    run(ctx, lambda xk: present(xk, xk.random(), View(json, not no_image, explain)))
+
+
+@app.command()
+def search(
+    ctx: typer.Context,
+    query: Annotated[str, typer.Argument(help="Words from the title, alt text or explanation.")],
+    limit: Annotated[int, typer.Option(help="Maximum number of hits.")] = 10,
+    json: Json = False,
+) -> None:
+    """Fuzzy-search cached comics. Run sync --full first for the whole archive."""
+    hits: list[Comic] = run(ctx, lambda xk: xk.search(query, limit))
+    if json:
+        console.print_json(data=[comic.model_dump(mode="json") for comic in hits])
+        return
+    for comic in hits:
+        console.print(
+            Text.assemble(
+                (f"{comic.num:>5}", "bold"), "  ", comic.title, "  ", (comic.date.isoformat(), "dim")
+            )
+        )
+
+
+@app.command()
+def explain(ctx: typer.Context, num: Num, json: Json = False) -> None:
+    """Print the explanation for a comic."""
+    text: str = run(ctx, lambda xk: xk.explain(num))
+    if json:
+        console.print_json(data={"num": num, "explanation": text})
+        return
+    console.print(text or "No explanation on explainxkcd yet.", markup=False)
+
+
+@app.command()
+def sync(
+    ctx: typer.Context,
+    full: Annotated[bool, typer.Option("--full", help="Fetch every comic and explanation.")] = False,
+) -> None:
+    """Refresh the archive index and latest comic; with --full, download everything."""
+    with console.status("Syncing") as status:
+        added: int = run(
+            ctx, lambda xk: xk.sync(full, lambda done, total: status.update(f"Syncing {done}/{total}"))
+        )
+    console.print(f"{added} new comic{'s' if added != 1 else ''} cached.")
+
+
+@app.command()
+def resync(
+    ctx: typer.Context,
+    max_age: Annotated[int, typer.Option(help="Refresh comics synced more than this many days ago.")] = 30,
+) -> None:
+    """Re-fetch stale comics and those still missing an explanation."""
+    with console.status("Resyncing") as status:
+        count: int = run(
+            ctx,
+            lambda xk: xk.resync(
+                timedelta(days=max_age), lambda done, total: status.update(f"Resyncing {done}/{total}")
+            ),
+        )
+    console.print(f"{count} comic{'s' if count != 1 else ''} refreshed.")
+
+
+@app.command()
+def tui(ctx: typer.Context) -> None:
+    """Open the interactive browser."""
+    from xkcdkit.tui import run_tui
+
+    run_tui(open_client(ctx.obj.db))

xkcdkit/client.py

@@ -0,0 +1,233 @@
+"""High-level clients: ``AsyncXKCD`` does the work, ``XKCD`` wraps it for sync code."""
+
+import asyncio
+import random
+from collections.abc import Callable
+from datetime import timedelta
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Self
+
+import httpx2
+
+from xkcdkit import ComicNotFound, XKCDError
+from xkcdkit.models import ArchiveEntry, Comic
+from xkcdkit.sources import fetch_archive, fetch_comic, fetch_explanation, user_agent
+from xkcdkit.store import Store, utc_now
+
+Progress = Callable[[int, int], None]
+RETRY_MISSING_AFTER = timedelta(days=1)
+
+
+class AsyncXKCD:
+    """Fetch, cache and search xkcd comics with explainxkcd explanations.
+
+    Example::
+
+        async with AsyncXKCD() as xk:
+            comic = await xk.get(614)
+            print(comic.title, comic.alt)
+
+    Args:
+        db: Database path. Defaults to the platform user data directory or ``$XKCDKIT_DB``.
+        client: An ``httpx2.AsyncClient`` to use instead of the built-in one.
+        timeout: Request timeout in seconds for the built-in client.
+        explain_delay: Seconds to wait between explainxkcd requests during bulk syncs.
+    """
+
+    def __init__(
+        self,
+        db: Path | str | None = None,
+        client: httpx2.AsyncClient | None = None,
+        timeout: float = 20.0,
+        explain_delay: float = 1.0,
+    ) -> None:
+        """Open the store and prepare the HTTP client."""
+        self.store = Store(db)
+        self.http = client or httpx2.AsyncClient(
+            timeout=timeout, headers={"User-Agent": user_agent()}, follow_redirects=True
+        )
+        self.explain_delay = explain_delay
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        """Close connections on exit."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP client and the database."""
+        await self.http.aclose()
+        self.store.close()
+
+    async def complete(self, comic: Comic) -> Comic:
+        """Attach the explainxkcd page when it exists and stamp the sync time."""
+        found = await fetch_explanation(self.http, comic.num)
+        wikitext, revid = found if found else (None, None)
+        return comic.model_copy(
+            update={
+                "explanation": wikitext,
+                "explanation_revid": revid,
+                "explanation_missing": wikitext is None,
+                "synced_at": utc_now(),
+            }
+        )
+
+    def fresh(self, comic: Comic) -> bool:
+        """A cached comic is fresh unless its explanation is absent and that is a day old."""
+        if comic.explanation is not None:
+            return True
+        if not comic.explanation_missing or comic.synced_at is None:
+            return False
+        return utc_now() - comic.synced_at < RETRY_MISSING_AFTER
+
+    async def get(self, num: int) -> Comic:
+        """Return comic ``num`` from the cache, fetching and caching it when needed.
+
+        Raises:
+            ComicNotFound: when xkcd has no such comic.
+            XKCDError: on network or server failures.
+        """
+        cached = self.store.get(num)
+        if cached and self.fresh(cached):
+            return cached
+        comic = await self.complete(await fetch_comic(self.http, num))
+        self.store.replace(comic)
+        return comic
+
+    async def latest(self) -> Comic:
+        """Return the newest comic, always checking xkcd.com for its number."""
+        comic = await fetch_comic(self.http, None)
+        self.store.set_meta("latest_num", str(comic.num))
+        if not self.store.has(comic.num):
+            self.store.put(await self.complete(comic))
+        return await self.get(comic.num)
+
+    async def random(self) -> Comic:
+        """Return a random comic, using the archive index for the number range."""
+        entries = self.store.archive() or await self.refresh_archive()
+        return await self.get(random.choice([entry.num for entry in entries]))
+
+    async def search(self, query: str, limit: int = 10) -> list[Comic]:
+        """Fuzzy-search cached comics by title, alt text, transcript and explanation."""
+        return [comic for comic, _ in self.store.search(query, limit)]
+
+    async def explain(self, num: int) -> str:
+        """The plain-text explanation for comic ``num``; empty when explainxkcd has none."""
+        return (await self.get(num)).explanation_text
+
+    async def refresh_archive(self) -> list[ArchiveEntry]:
+        """Fetch the archive page and store it as the index."""
+        entries = await fetch_archive(self.http)
+        self.store.put_archive(entries)
+        return entries
+
+    async def sync(self, full: bool = False, progress: Progress | None = None) -> int:
+        """Refresh the archive index and the latest comic; with ``full`` fetch every comic.
+
+        A full sync walks every number from 1 to the latest, so it does not depend
+        on the archive page. Returns the number of comics newly added to the cache.
+        """
+        before = self.store.count()
+        await self.refresh_archive()
+        latest = await self.latest()
+        if full:
+            cached = set(self.store.nums())
+            await self.fetch_many([n for n in range(1, latest.num + 1) if n not in cached], progress)
+            self.store.set_meta("last_full_sync_at", utc_now().isoformat())
+        self.store.set_meta("last_sync_at", utc_now().isoformat())
+        return self.store.count() - before
+
+    async def resync(self, max_age: timedelta = timedelta(days=30), progress: Progress | None = None) -> int:
+        """Re-fetch comics older than ``max_age`` or missing an explanation. Returns the count."""
+        return await self.fetch_many(self.store.stale(max_age), progress)
+
+    async def fetch_many(self, nums: list[int], progress: Progress | None) -> int:
+        """Fetch and store each comic in turn, politely paced, skipping numbers xkcd lacks."""
+        done = 0
+        for index, num in enumerate(nums, start=1):
+            try:
+                self.store.replace(await self.complete(await fetch_comic(self.http, num)))
+                done += 1
+            except ComicNotFound:
+                pass
+            if progress:
+                progress(index, len(nums))
+            await asyncio.sleep(self.explain_delay)
+        return done
+
+
+class XKCD:
+    """Blocking twin of ``AsyncXKCD`` for scripts and REPL use.
+
+    Each call runs on its own short-lived event loop, so it cannot be used
+    from code that is already inside one. Use ``AsyncXKCD`` there.
+    """
+
+    def __init__(
+        self,
+        db: Path | str | None = None,
+        client_factory: Callable[[], httpx2.AsyncClient] | None = None,
+        timeout: float = 20.0,
+        explain_delay: float = 1.0,
+    ) -> None:
+        """Remember the settings; connections are opened per call."""
+        self.db = db
+        self.client_factory = client_factory
+        self.timeout = timeout
+        self.explain_delay = explain_delay
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        """Nothing to close: each call closes its own resources."""
+
+    def run(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        """Run one ``AsyncXKCD`` method to completion on a fresh event loop."""
+
+        async def call() -> Any:
+            client = self.client_factory() if self.client_factory else None
+            async with AsyncXKCD(self.db, client, self.timeout, self.explain_delay) as xk:
+                return await getattr(xk, method)(*args, **kwargs)
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(call())
+        raise XKCDError("XKCD cannot run inside an event loop; use AsyncXKCD")
+
+    def get(self, num: int) -> Comic:
+        """See ``AsyncXKCD.get``."""
+        return self.run("get", num)  # type: ignore[no-any-return]
+
+    def latest(self) -> Comic:
+        """See ``AsyncXKCD.latest``."""
+        return self.run("latest")  # type: ignore[no-any-return]
+
+    def random(self) -> Comic:
+        """See ``AsyncXKCD.random``."""
+        return self.run("random")  # type: ignore[no-any-return]
+
+    def search(self, query: str, limit: int = 10) -> list[Comic]:
+        """See ``AsyncXKCD.search``."""
+        return self.run("search", query, limit)  # type: ignore[no-any-return]
+
+    def explain(self, num: int) -> str:
+        """See ``AsyncXKCD.explain``."""
+        return self.run("explain", num)  # type: ignore[no-any-return]
+
+    def sync(self, full: bool = False, progress: Progress | None = None) -> int:
+        """See ``AsyncXKCD.sync``."""
+        return self.run("sync", full, progress)  # type: ignore[no-any-return]
+
+    def resync(self, max_age: timedelta = timedelta(days=30), progress: Progress | None = None) -> int:
+        """See ``AsyncXKCD.resync``."""
+        return self.run("resync", max_age, progress)  # type: ignore[no-any-return]

xkcdkit/models.py

@@ -0,0 +1,108 @@
+"""Data models for comics and archive entries, plus a wikitext cleaner."""
+
+import datetime as dt
+import re
+
+from pydantic import BaseModel, field_validator
+
+TEMPLATE = re.compile(r"\{\{([^{}]*)\}\}")
+LINK = re.compile(r"\[\[([^\]|]*)(?:\|([^\]]*))?\]\]")
+EXTERNAL_LINK = re.compile(r"\[\w+://[^\s\]]+(?:\s+([^\]]*))?\]")
+TAG = re.compile(r"<ref[^>]*/>|<ref[^>]*>.*?</ref>|<[^>]+>", re.DOTALL)
+SECTION = re.compile(r"^==([^=].*?)==\s*$", re.MULTILINE)
+SUBHEADING = re.compile(r"^=+\s*(.*?)\s*=+\s*$", re.MULTILINE)
+
+
+class Comic(BaseModel):
+    """One xkcd comic, as served by xkcd.com, with explainxkcd data attached.
+
+    Field names match the xkcd JSON so the payload can be validated directly.
+    The explanation fields are filled from explainxkcd when available.
+    """
+
+    num: int
+    title: str
+    safe_title: str = ""
+    alt: str = ""
+    img: str = ""
+    transcript: str = ""
+    link: str = ""
+    news: str = ""
+    year: int
+    month: int
+    day: int
+    explanation: str | None = None
+    explanation_revid: int | None = None
+    explanation_missing: bool = False
+    synced_at: dt.datetime | None = None
+
+    @property
+    def date(self) -> dt.date:
+        """Publication date assembled from year, month and day."""
+        return dt.date(self.year, self.month, self.day)
+
+    @property
+    def url(self) -> str:
+        """The comic's page on xkcd.com."""
+        return f"https://xkcd.com/{self.num}/"
+
+    @property
+    def explanation_text(self) -> str:
+        """The explainxkcd Explanation section as plain text, or empty."""
+        return wikitext_to_text(self.explanation)
+
+
+class ArchiveEntry(BaseModel):
+    """One line of the xkcd archive page: number, date and title."""
+
+    num: int
+    date: dt.date
+    title: str
+
+    @field_validator("date", mode="before")
+    @classmethod
+    def parse_loose_date(cls, value: object) -> object:
+        """Accept the archive's unpadded dates such as ``2009-7-24``."""
+        if isinstance(value, str):
+            year, month, day = (int(part) for part in value.split("-"))
+            return dt.date(year, month, day)
+        return value
+
+
+def explanation_section(wikitext: str) -> str:
+    """Return the body of the Explanation section, or the whole text if unsectioned."""
+    headings = list(SECTION.finditer(wikitext))
+    if not headings:
+        return wikitext
+    for index, heading in enumerate(headings):
+        if heading.group(1).strip().lower() == "explanation":
+            end = headings[index + 1].start() if index + 1 < len(headings) else len(wikitext)
+            return wikitext[heading.end() : end]
+    return ""
+
+
+def expand_template(match: re.Match[str]) -> str:
+    """Replace a template: ``{{w|page|label}}`` becomes its label, others vanish."""
+    parts = match.group(1).split("|")
+    if parts[0].strip().lower() == "w" and len(parts) > 1:
+        return parts[-1].strip()
+    return ""
+
+
+def wikitext_to_text(wikitext: str | None) -> str:
+    """Reduce explainxkcd wikitext to readable plain text.
+
+    Keeps only the Explanation section, drops templates and tags, turns links
+    into their visible text and collapses whitespace into paragraphs.
+    """
+    if not wikitext:
+        return ""
+    text = SUBHEADING.sub(r"\1", explanation_section(wikitext))
+    while TEMPLATE.search(text):
+        text = TEMPLATE.sub(expand_template, text)
+    text = TAG.sub("", text)
+    text = LINK.sub(lambda m: m.group(2) or m.group(1), text)
+    text = EXTERNAL_LINK.sub(lambda m: m.group(1) or "", text)
+    text = text.replace("'''", "").replace("''", "")
+    lines = [re.sub(r"[ \t]+", " ", line).strip() for line in text.splitlines()]
+    return "\n\n".join(line for line in lines if line)

xkcdkit/render.py

@@ -0,0 +1,43 @@
+"""Terminal rendering: a text card for a comic and an image when the terminal can draw one."""
+
+import io
+import sys
+
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.text import Text
+
+from xkcdkit.models import Comic
+
+
+def comic_text(comic: Comic, explain: bool = False) -> RenderableType:
+    """A panel with number, title, date, alt text and optionally the explanation."""
+    header = Text.assemble(("#", "dim"), (str(comic.num), "bold"), "  ", (comic.title, "bold cyan"))
+    body: list[RenderableType] = [Text(comic.alt, style="italic"), Text(comic.url, style="dim")]
+    if explain:
+        body += [Text(""), Text("Explanation", style="bold underline"), explanation_text(comic)]
+    return Panel(Group(*body), title=header, subtitle=comic.date.isoformat(), title_align="left")
+
+
+def explanation_text(comic: Comic) -> Text:
+    """The explanation body, or a note when explainxkcd has no page."""
+    if comic.explanation_missing or not comic.explanation_text:
+        return Text("No explanation on explainxkcd yet.", style="dim")
+    return Text(comic.explanation_text)
+
+
+def comic_image(data: bytes) -> RenderableType:
+    """A Rich renderable for the image bytes using the best protocol the terminal supports.
+
+    textual-image probes the terminal on import, so it is imported here rather than
+    at module load.
+    """
+    from textual_image.renderable import Image
+
+    renderable: RenderableType = Image(io.BytesIO(data))
+    return renderable
+
+
+def can_draw() -> bool:
+    """Whether drawing an image makes sense: only when stdout is a terminal."""
+    return sys.stdout.isatty()