xkcdkit 0.1.0__tar.gz → 0.3.0__tar.gz

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xkcdkit
-Version: 0.1.0
+Version: 0.3.0
 Summary: xkcd comics as a Python library, a CLI and a TUI, with a local cache and explainxkcd explanations.
 Keywords: xkcd,comics,cli,tui,textual
 Author: Eivind Teig
@@ -113,7 +113,8 @@ xkcd random              # a random comic
 xkcd search "woodpecker" # fuzzy search over cached titles, alt text, transcripts and explanations
 xkcd explain 614         # just the explanation, as plain text
 xkcd sync                # refresh the archive index and the latest comic
-xkcd sync --full         # download every comic and explanation (about an hour, see below)
+xkcd sync --full         # download every comic and explanation (under an hour, see below)
+xkcd sync --full --no-explain  # comics only, a minute or two; explanations come later
 xkcd resync              # re-fetch comics older than 30 days or still missing an explanation
 xkcd tui                 # open the browser
 ```
@@ -130,6 +131,40 @@ xkcd search "sandwich" --json | jq '.[].num'
 `--no-image` skips the picture. Images are also skipped automatically when
 stdout is not a terminal, so pipes always get clean text.
 
+Images are drawn at the size the terminal reports for them, which can be
+small on a high-resolution screen. `--scale 2` (or `-s 3`, any factor) makes
+them bigger, and `--fit` fills the terminal while keeping the aspect ratio:
+
+```sh
+xkcd show 614 --scale 2
+xkcd latest --fit
+```
+
+### Settings file
+
+Defaults for these live in a small TOML file. `xkcd config` prints its
+location and the current values; `xkcd config --init` writes a commented
+file with every key:
+
+| Platform | Location |
+| -------- | -------- |
+| Linux    | `~/.config/xkcdkit/config.toml` |
+| macOS    | `~/Library/Application Support/xkcdkit/config.toml` |
+| Windows  | `%APPDATA%\xkcdkit\config.toml` |
+
+Set `XKCDKIT_CONFIG` to use another path.
+
+```toml
+[image]
+scale = 2.0      # CLI image size multiplier
+fit = false      # CLI: fill the terminal instead
+
+[tui]
+image_pane = 3   # browser: image pane height relative to the text pane (1 to 8)
+```
+
+Command line flags always win over the file.
+
 ### The browser
 
 `xkcd tui` opens a two-pane browser in the spirit of lazygit: the archive on
@@ -139,15 +174,20 @@ explanation.
 | Key     | Action                           |
 | ------- | -------------------------------- |
 | `j`/`k` | move through the archive         |
-| `/`     | filter the archive by title      |
+| `/`     | filter the archive by title; up/down still move the list, Esc returns to it |
 | `Enter` | open the selected comic          |
 | `r`     | random comic                     |
 | `l`     | latest comic                     |
 | `i`     | show or hide the image pane      |
+| `+`/`-` | grow or shrink the image pane    |
 | `s`     | sync the archive index           |
 | `?`     | key help                         |
 | `q`     | quit                             |
 
+The image always fills its pane while keeping its aspect ratio, so the pane
+height is the zoom. The starting height comes from `image_pane` in the
+settings file.
+
 ## Library
 
 The async client is the primary API. It is built for I/O bound programs such
@@ -232,10 +272,23 @@ async def xkcd(ctx, num: int):
 ### Being polite to explainxkcd
 
 explainxkcd is a volunteer-run wiki. Its robots policy asks for one request
-per second, so a full sync fetches one explanation per second and sends a
-User-Agent that names this project and its repository. A complete first
-`sync --full` therefore takes about an hour. On-demand lookups are not
-delayed.
+per second, so a full sync sends at most one explainxkcd request per second
+and a User-Agent that names this project and its repository. xkcd.com has no
+such limit and is fetched by several workers at once, so explanations are the
+pacing item: a complete first `sync --full` takes a little under an hour for
+the whole archive.
+
+Two ways to shorten the wait:
+
+- `xkcd sync --full --no-explain` fetches only the comics, which takes a
+  minute or two. Explanations are then filled in on demand when you open a
+  comic, or in bulk with `xkcd resync`, which is paced the same way.
+- Ctrl-C at any point is safe. Every comic is committed to the database the
+  moment it is fetched, and the next `sync --full` skips everything already
+  cached, so you can sync in several sittings.
+
+The sync walks every number from 1 to the latest comic, so it does not depend
+on the archive page. On-demand lookups are never delayed.
 
 ## Terminal image support
 

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/README.md

@@ -81,7 +81,8 @@ xkcd random              # a random comic
 xkcd search "woodpecker" # fuzzy search over cached titles, alt text, transcripts and explanations
 xkcd explain 614         # just the explanation, as plain text
 xkcd sync                # refresh the archive index and the latest comic
-xkcd sync --full         # download every comic and explanation (about an hour, see below)
+xkcd sync --full         # download every comic and explanation (under an hour, see below)
+xkcd sync --full --no-explain  # comics only, a minute or two; explanations come later
 xkcd resync              # re-fetch comics older than 30 days or still missing an explanation
 xkcd tui                 # open the browser
 ```
@@ -98,6 +99,40 @@ xkcd search "sandwich" --json | jq '.[].num'
 `--no-image` skips the picture. Images are also skipped automatically when
 stdout is not a terminal, so pipes always get clean text.
 
+Images are drawn at the size the terminal reports for them, which can be
+small on a high-resolution screen. `--scale 2` (or `-s 3`, any factor) makes
+them bigger, and `--fit` fills the terminal while keeping the aspect ratio:
+
+```sh
+xkcd show 614 --scale 2
+xkcd latest --fit
+```
+
+### Settings file
+
+Defaults for these live in a small TOML file. `xkcd config` prints its
+location and the current values; `xkcd config --init` writes a commented
+file with every key:
+
+| Platform | Location |
+| -------- | -------- |
+| Linux    | `~/.config/xkcdkit/config.toml` |
+| macOS    | `~/Library/Application Support/xkcdkit/config.toml` |
+| Windows  | `%APPDATA%\xkcdkit\config.toml` |
+
+Set `XKCDKIT_CONFIG` to use another path.
+
+```toml
+[image]
+scale = 2.0      # CLI image size multiplier
+fit = false      # CLI: fill the terminal instead
+
+[tui]
+image_pane = 3   # browser: image pane height relative to the text pane (1 to 8)
+```
+
+Command line flags always win over the file.
+
 ### The browser
 
 `xkcd tui` opens a two-pane browser in the spirit of lazygit: the archive on
@@ -107,15 +142,20 @@ explanation.
 | Key     | Action                           |
 | ------- | -------------------------------- |
 | `j`/`k` | move through the archive         |
-| `/`     | filter the archive by title      |
+| `/`     | filter the archive by title; up/down still move the list, Esc returns to it |
 | `Enter` | open the selected comic          |
 | `r`     | random comic                     |
 | `l`     | latest comic                     |
 | `i`     | show or hide the image pane      |
+| `+`/`-` | grow or shrink the image pane    |
 | `s`     | sync the archive index           |
 | `?`     | key help                         |
 | `q`     | quit                             |
 
+The image always fills its pane while keeping its aspect ratio, so the pane
+height is the zoom. The starting height comes from `image_pane` in the
+settings file.
+
 ## Library
 
 The async client is the primary API. It is built for I/O bound programs such
@@ -200,10 +240,23 @@ async def xkcd(ctx, num: int):
 ### Being polite to explainxkcd
 
 explainxkcd is a volunteer-run wiki. Its robots policy asks for one request
-per second, so a full sync fetches one explanation per second and sends a
-User-Agent that names this project and its repository. A complete first
-`sync --full` therefore takes about an hour. On-demand lookups are not
-delayed.
+per second, so a full sync sends at most one explainxkcd request per second
+and a User-Agent that names this project and its repository. xkcd.com has no
+such limit and is fetched by several workers at once, so explanations are the
+pacing item: a complete first `sync --full` takes a little under an hour for
+the whole archive.
+
+Two ways to shorten the wait:
+
+- `xkcd sync --full --no-explain` fetches only the comics, which takes a
+  minute or two. Explanations are then filled in on demand when you open a
+  comic, or in bulk with `xkcd resync`, which is paced the same way.
+- Ctrl-C at any point is safe. Every comic is committed to the database the
+  moment it is fetched, and the next `sync --full` skips everything already
+  cached, so you can sync in several sittings.
+
+The sync walks every number from 1 to the latest comic, so it does not depend
+on the archive page. On-demand lookups are never delayed.
 
 ## Terminal image support
 

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xkcdkit"
-version = "0.1.0"
+version = "0.3.0"
 description = "xkcd comics as a Python library, a CLI and a TUI, with a local cache and explainxkcd explanations."
 readme = "README.md"
 license = "MIT"

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xkcdkit"
-version = "0.1.0"
+version = "0.3.0"
 description = "xkcd comics as a Python library, a CLI and a TUI, with a local cache and explainxkcd explanations."
 readme = "README.md"
 license = "MIT"

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/src/xkcdkit/cli.py

@@ -12,6 +12,7 @@ from rich.text import Text
 
 from xkcdkit import XKCDError, __version__
 from xkcdkit.client import AsyncXKCD
+from xkcdkit.config import config_path, load_settings, write_default
 from xkcdkit.models import Comic
 from xkcdkit.render import can_draw, comic_image, comic_text
 from xkcdkit.sources import fetch_image
@@ -21,6 +22,8 @@ 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.")]
+Scale = Annotated[float | None, typer.Option("--scale", "-s", help="Image size multiplier.")]
+Fit = Annotated[bool, typer.Option("--fit", help="Fill the terminal with the image.")]
 NoImage = Annotated[bool, typer.Option("--no-image", help="Do not draw the image.")]
 Explain = Annotated[bool, typer.Option("--explain", "-e", help="Include the explanation.")]
 
@@ -66,6 +69,12 @@ def run(ctx: typer.Context, action: Callable[[AsyncXKCD], Awaitable[Any]]) -> An
     except XKCDError as exc:
         errors.print(f"error: {exc}", markup=False, highlight=False)
         raise typer.Exit(1) from exc
+    except KeyboardInterrupt:
+        errors.print(
+            "Interrupted. Everything fetched so far is saved; run the command again to continue.",
+            soft_wrap=True,
+        )
+        raise typer.Exit(130) from None
 
 
 @dataclass
@@ -75,6 +84,14 @@ class View:
     json: bool = False
     image: bool = True
     explain: bool = False
+    scale: float = 1.0
+    fit: bool = False
+
+
+def view(json: bool, no_image: bool, explain: bool, scale: float | None, fit: bool) -> View:
+    """Combine command flags with the settings file; flags win."""
+    image = load_settings().image
+    return View(json, not no_image, explain, scale or image.scale, fit or image.fit)
 
 
 async def present(xk: AsyncXKCD, pending: Awaitable[Comic], view: View) -> None:
@@ -84,32 +101,48 @@ async def present(xk: AsyncXKCD, pending: Awaitable[Comic], view: View) -> None:
         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_image(await fetch_image(xk.http, comic), view.scale, view.fit))
     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
+    ctx: typer.Context,
+    num: Num,
+    no_image: NoImage = False,
+    explain: Explain = False,
+    json: Json = False,
+    scale: Scale = None,
+    fit: Fit = False,
 ) -> None:
     """Show one comic by number."""
-    run(ctx, lambda xk: present(xk, xk.get(num), View(json, not no_image, explain)))
+    run(ctx, lambda xk: present(xk, xk.get(num), view(json, no_image, explain, scale, fit)))
 
 
 @app.command()
 def latest(
-    ctx: typer.Context, no_image: NoImage = False, explain: Explain = False, json: Json = False
+    ctx: typer.Context,
+    no_image: NoImage = False,
+    explain: Explain = False,
+    json: Json = False,
+    scale: Scale = None,
+    fit: Fit = False,
 ) -> None:
     """Show the newest comic."""
-    run(ctx, lambda xk: present(xk, xk.latest(), View(json, not no_image, explain)))
+    run(ctx, lambda xk: present(xk, xk.latest(), view(json, no_image, explain, scale, fit)))
 
 
 @app.command()
 def random(
-    ctx: typer.Context, no_image: NoImage = False, explain: Explain = False, json: Json = False
+    ctx: typer.Context,
+    no_image: NoImage = False,
+    explain: Explain = False,
+    json: Json = False,
+    scale: Scale = None,
+    fit: Fit = False,
 ) -> None:
     """Show a random comic."""
-    run(ctx, lambda xk: present(xk, xk.random(), View(json, not no_image, explain)))
+    run(ctx, lambda xk: present(xk, xk.random(), view(json, no_image, explain, scale, fit)))
 
 
 @app.command()
@@ -146,11 +179,17 @@ def explain(ctx: typer.Context, num: Num, json: Json = False) -> None:
 def sync(
     ctx: typer.Context,
     full: Annotated[bool, typer.Option("--full", help="Fetch every comic and explanation.")] = False,
+    no_explain: Annotated[
+        bool, typer.Option("--no-explain", help="Skip explainxkcd for now (much faster); resync fills it in.")
+    ] = 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}"))
+            ctx,
+            lambda xk: xk.sync(
+                full, lambda done, total: status.update(f"Syncing {done}/{total}"), explain=not no_explain
+            ),
         )
     console.print(f"{added} new comic{'s' if added != 1 else ''} cached.")
 
@@ -176,4 +215,19 @@ def tui(ctx: typer.Context) -> None:
     """Open the interactive browser."""
     from xkcdkit.tui import run_tui
 
-    run_tui(open_client(ctx.obj.db))
+    run_tui(open_client(ctx.obj.db), load_settings())
+
+
+@app.command()
+def config(
+    init: Annotated[bool, typer.Option("--init", help="Create the file with defaults.")] = False,
+) -> None:
+    """Show where settings live and what they are; --init writes a commented default file."""
+    path = config_path()
+    if init:
+        console.print(
+            f"{'created' if write_default(path) else 'exists'}: {path}", markup=False, soft_wrap=True
+        )
+        return
+    console.print(f"settings file: {path}", markup=False, soft_wrap=True)
+    console.print_json(load_settings(path).model_dump_json())

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/src/xkcdkit/client.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import random
+import time
 from collections.abc import Callable
 from datetime import timedelta
 from pathlib import Path
@@ -17,6 +18,7 @@ from xkcdkit.store import Store, utc_now
 
 Progress = Callable[[int, int], None]
 RETRY_MISSING_AFTER = timedelta(days=1)
+WORKERS = 8
 
 
 class AsyncXKCD:
@@ -32,7 +34,7 @@ class AsyncXKCD:
         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.
+        explain_delay: Minimum seconds between explainxkcd requests during bulk syncs.
     """
 
     def __init__(
@@ -48,6 +50,8 @@ class AsyncXKCD:
             timeout=timeout, headers={"User-Agent": user_agent()}, follow_redirects=True
         )
         self.explain_delay = explain_delay
+        self.explain_lock = asyncio.Lock()
+        self.last_explain = 0.0
 
     async def __aenter__(self) -> Self:
         """Enter the async context manager."""
@@ -67,6 +71,7 @@ class AsyncXKCD:
     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)
+        self.last_explain = time.monotonic()
         wikitext, revid = found if found else (None, None)
         return comic.model_copy(
             update={
@@ -126,39 +131,66 @@ class AsyncXKCD:
         self.store.put_archive(entries)
         return entries
 
-    async def sync(self, full: bool = False, progress: Progress | None = None) -> int:
+    async def sync(self, full: bool = False, progress: Progress | None = None, explain: bool = True) -> 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.
+        on the archive page. With ``explain=False`` it skips explainxkcd, which is
+        much faster; ``resync`` or a later ``get`` fills the explanations in.
+        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)
+            nums = [n for n in range(1, latest.num + 1) if n not in cached]
+            await self.fetch_many(nums, progress, explain)
             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."""
+        """Re-fetch comics older than ``max_age`` or without explanation data. 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)))
+    async def fetch_many(self, nums: list[int], progress: Progress | None, explain: bool = True) -> int:
+        """Fetch and store comics with several workers; explainxkcd is paced to one request at a time.
+
+        xkcd.com requests overlap freely. Each stored comic is committed at once, so an
+        interrupted run keeps everything finished so far. Numbers xkcd lacks are skipped.
+        """
+        pending, done, fetched = list(reversed(nums)), 0, 0
+
+        async def worker() -> None:
+            nonlocal done, fetched
+            while pending:
+                num = pending.pop()
+                try:
+                    comic = await fetch_comic(self.http, num)
+                    if explain:
+                        await self.pace()
+                        comic = await self.complete(comic)
+                    self.store.replace(comic)
+                    fetched += 1
+                except ComicNotFound:
+                    pass
                 done += 1
-            except ComicNotFound:
-                pass
-            if progress:
-                progress(index, len(nums))
-            await asyncio.sleep(self.explain_delay)
-        return done
+                if progress:
+                    progress(done, len(nums))
+
+        async with asyncio.TaskGroup() as group:
+            for _ in range(min(WORKERS, len(nums))):
+                group.create_task(worker())
+        return fetched
+
+    async def pace(self) -> None:
+        """Wait until ``explain_delay`` has passed since the previous explainxkcd request."""
+        async with self.explain_lock:
+            wait = self.last_explain + self.explain_delay - time.monotonic()
+            if wait > 0:
+                await asyncio.sleep(wait)
+            self.last_explain = time.monotonic()
 
 
 class XKCD:
@@ -224,9 +256,9 @@ class XKCD:
         """See ``AsyncXKCD.explain``."""
         return self.run("explain", num)  # type: ignore[no-any-return]
 
-    def sync(self, full: bool = False, progress: Progress | None = None) -> int:
+    def sync(self, full: bool = False, progress: Progress | None = None, explain: bool = True) -> int:
         """See ``AsyncXKCD.sync``."""
-        return self.run("sync", full, progress)  # type: ignore[no-any-return]
+        return self.run("sync", full, progress, explain)  # type: ignore[no-any-return]
 
     def resync(self, max_age: timedelta = timedelta(days=30), progress: Progress | None = None) -> int:
         """See ``AsyncXKCD.resync``."""

xkcdkit-0.3.0/src/xkcdkit/config.py

@@ -0,0 +1,76 @@
+"""User settings from a small TOML file in the platform config directory."""
+
+import os
+import tomllib
+from pathlib import Path
+
+from platformdirs import user_config_path
+from pydantic import BaseModel, Field, ValidationError
+
+from xkcdkit import XKCDError
+
+DEFAULT_TOML = """# xkcdkit settings. Every key is optional; these are the defaults.
+
+[image]
+# CLI: multiply the image's natural terminal size (1 = as the terminal sizes it, 2 = twice as big).
+scale = 1.0
+# CLI: ignore scale and fill the terminal, keeping the aspect ratio.
+fit = false
+
+[tui]
+# Height of the image pane relative to the text pane (1 to 8). Change live with + and -.
+image_pane = 2
+"""
+
+
+class ImageSettings(BaseModel):
+    """How the CLI draws images."""
+
+    scale: float = Field(default=1.0, gt=0, le=16)
+    fit: bool = False
+
+
+class TuiSettings(BaseModel):
+    """How the browser lays itself out."""
+
+    image_pane: int = Field(default=2, ge=1, le=8)
+
+
+class Settings(BaseModel):
+    """All settings, mirroring the sections of the TOML file."""
+
+    image: ImageSettings = ImageSettings()
+    tui: TuiSettings = TuiSettings()
+
+
+def config_path() -> Path:
+    """Settings file location: ``$XKCDKIT_CONFIG`` or the platform user config directory."""
+    override = os.environ.get("XKCDKIT_CONFIG")
+    if override:
+        return Path(override)
+    return user_config_path("xkcdkit") / "config.toml"
+
+
+def load_settings(path: Path | None = None) -> Settings:
+    """Read the settings file, falling back to defaults when it does not exist.
+
+    Raises:
+        XKCDError: when the file is not valid TOML or holds an invalid value.
+    """
+    path = path or config_path()
+    if not path.exists():
+        return Settings()
+    try:
+        return Settings.model_validate(tomllib.loads(path.read_text(encoding="utf-8")))
+    except (tomllib.TOMLDecodeError, ValidationError) as exc:
+        raise XKCDError(f"{path}: {exc}") from exc
+
+
+def write_default(path: Path | None = None) -> bool:
+    """Create the settings file with documented defaults. Returns False if it already exists."""
+    path = path or config_path()
+    if path.exists():
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(DEFAULT_TOML, encoding="utf-8")
+    return True

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/src/xkcdkit/render.py

@@ -3,10 +3,12 @@
 import io
 import sys
 
+from PIL import Image as PILImage
 from rich.console import Group, RenderableType
 from rich.panel import Panel
 from rich.text import Text
 
+from xkcdkit import XKCDError
 from xkcdkit.models import Comic
 
 
@@ -26,15 +28,29 @@ def explanation_text(comic: Comic) -> Text:
     return Text(comic.explanation_text)
 
 
-def comic_image(data: bytes) -> RenderableType:
+def comic_image(data: bytes, scale: float = 1.0, fit: bool = False) -> 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.
+    ``scale`` multiplies the image's natural terminal size; ``fit`` instead fills the
+    terminal while keeping the aspect ratio. textual-image probes the terminal on
+    import, so it is imported here rather than at module load.
+
+    Raises:
+        XKCDError: when the bytes are not an image.
     """
     from textual_image.renderable import Image
 
-    renderable: RenderableType = Image(io.BytesIO(data))
+    try:
+        picture: PILImage.Image = PILImage.open(io.BytesIO(data))
+        picture.load()
+    except OSError as exc:
+        raise XKCDError(f"not an image: {exc}") from exc
+    if fit:
+        renderable: RenderableType = Image(picture, width="auto", height="auto")
+        return renderable
+    if scale != 1:
+        picture = picture.resize((round(picture.width * scale), round(picture.height * scale)))
+    renderable = Image(picture)
     return renderable
 
 

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/src/xkcdkit/store.py

@@ -129,10 +129,10 @@ class Store:
         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."""
+        """Numbers of comics older than ``max_age`` or without explanation data yet."""
         cutoff = (utc_now() - max_age).isoformat()
         rows = self.db.execute(
-            "SELECT num FROM comics WHERE synced_at < ? OR explanation_missing ORDER BY num",
+            "SELECT num FROM comics WHERE synced_at < ? OR explanation IS NULL ORDER BY num",
             (cutoff,),
         )
         return [row[0] for row in rows]

{xkcdkit-0.1.0 → xkcdkit-0.3.0}/src/xkcdkit/tui.py

@@ -16,10 +16,12 @@ from textual_image.widget import Image
 
 from xkcdkit import XKCDError
 from xkcdkit.client import AsyncXKCD
+from xkcdkit.config import Settings
 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"
+HELP = "j/k move  / filter  enter open  r random  l latest  i image  +/- zoom  s sync  q quit"
+MAX_PANE = 8
 
 
 def option(entry: ArchiveEntry) -> Option:
@@ -35,6 +37,7 @@ class XKCDApp(App[None]):
     #archive-pane { width: 40; border: round $primary; }
     #archive { height: 1fr; }
     #image-pane { height: 2fr; border: round $secondary; align: center middle; }
+    #image { width: auto; height: auto; }
     TabbedContent { height: 1fr; }
     .text { padding: 0 1; }
     """
@@ -45,15 +48,21 @@ class XKCDApp(App[None]):
         Binding("r", "random", "Random"),
         Binding("l", "latest", "Latest"),
         Binding("i", "toggle_image", "Image"),
+        Binding("plus,equals_sign", "zoom(1)", "Zoom", key_display="+/-"),
+        Binding("minus", "zoom(-1)", "Zoom out", show=False),
         Binding("s", "sync", "Sync"),
+        Binding("down", "cursor('down')", "Down", show=False),
+        Binding("up", "cursor('up')", "Up", show=False),
+        Binding("escape", "focus_list", "List", show=False),
         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."""
+    def __init__(self, client: AsyncXKCD, settings: Settings | None = None) -> None:
+        """Keep the client (its store feeds the archive list) and the user's settings."""
         super().__init__()
         self.client = client
+        self.settings = settings or Settings()
         self.entries: list[ArchiveEntry] = []
 
     def compose(self) -> ComposeResult:
@@ -77,6 +86,7 @@ class XKCDApp(App[None]):
     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.query_one("#image-pane").styles.height = f"{self.settings.tui.image_pane}fr"
         self.entries = self.client.store.archive()
         self.show_entries(self.entries)
         if not self.entries:
@@ -100,10 +110,10 @@ class XKCDApp(App[None]):
         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."""
+        """Enter in the filter opens the highlighted match (the first unless moved)."""
         archive = self.query_one(OptionList)
         if archive.option_count:
-            self.open(int(str(archive.get_option_at_index(0).id)))
+            self.open(int(str(archive.get_option_at_index(archive.highlighted or 0).id)))
 
     def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
         """Enter on a row opens that comic."""
@@ -150,6 +160,16 @@ class XKCDApp(App[None]):
         """Jump to the filter box."""
         self.query_one("#filter", Input).focus()
 
+    def action_focus_list(self) -> None:
+        """Return to the archive list."""
+        self.query_one(OptionList).focus()
+
+    def action_zoom(self, step: int) -> None:
+        """Grow or shrink the image pane relative to the text pane."""
+        pane = self.query_one("#image-pane")
+        self.settings.tui.image_pane = min(MAX_PANE, max(1, self.settings.tui.image_pane + step))
+        pane.styles.height = f"{self.settings.tui.image_pane}fr"
+
     def action_random(self) -> None:
         """Open a random comic."""
         self.open(-1)
@@ -180,9 +200,9 @@ class XKCDApp(App[None]):
         self.notify(HELP, title="Keys", timeout=8)
 
 
-def run_tui(client: AsyncXKCD) -> None:
+def run_tui(client: AsyncXKCD, settings: Settings | None = None) -> None:
     """Start the browser and close the client when it exits."""
     try:
-        XKCDApp(client).run()
+        XKCDApp(client, settings).run()
     finally:
         client.store.close()