xkcdkit 0.1.0__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xkcdkit
-Version: 0.1.0
+Version: 0.2.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
@@ -130,6 +130,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 +173,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

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

@@ -98,6 +98,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 +141,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

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

@@ -1,6 +1,6 @@
 [project]
 name = "xkcdkit"
-version = "0.1.0"
+version = "0.2.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.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xkcdkit"
-version = "0.1.0"
+version = "0.2.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.2.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.")]
 
@@ -75,6 +78,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 +95,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()
@@ -176,4 +203,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.2.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.2.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.2.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()