aa-tui 0.1.0__py3-none-any.whl

aa_tui/__init__.py

@@ -0,0 +1 @@
+"""Textual front-end for aa-meta."""

aa_tui/app.py

@@ -0,0 +1,422 @@
+"""The Textual application: search box, results table, and detail pane."""
+
+from __future__ import annotations
+
+import sys
+import threading
+import webbrowser
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, ClassVar
+from urllib.parse import urlencode
+
+from aa_meta.authors import format_authors
+from aa_meta.cli import format_ext, format_size
+from aa_meta.config import Settings
+from aa_meta.models import BookRecord
+from aa_meta.search import Book
+from loguru import logger
+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
+from textual.widgets import DataTable, Footer, Header, Input, Static
+from textual.worker import get_current_worker
+
+from . import service
+from .capture import ToastStream
+from .details_screen import DetailsScreen
+from .edit_screen import EditScreen
+from .error_screen import ErrorScreen
+from .loading_screen import LoadingScreen
+from .metadata import DEFAULT_STORE, EditableMeta, MetadataStore
+from .tags import TagError, write_tags
+
+# (label, width) of each results column; the MD5 stays last and full-width.
+COLUMNS: tuple[tuple[str, int | None], ...] = (
+    ("#", 3),
+    ("Ext", 6),
+    ("Title", 44),
+    ("Author", 26),
+    ("Size", 9),
+    ("Lang", 5),
+    ("Year", 5),
+    ("MD5", 32),
+)
+
+
+def _plain(value: str) -> Text:
+    """Return ``value`` in light grey, or a dim dash when empty."""
+    return Text(value, style="#C2C2C2") if value else Text("-", style="dim")
+
+
+def result_rows(books: list[Book]) -> list[tuple[Text | str, ...]]:
+    """Build one table row per book, splitting the parsed record into columns.
+
+    Books without a parsed record (bare links) fall back to their raw ``meta``
+    text in the Author column and dashes elsewhere.
+    """
+    authors = format_authors([b.record.author if b.record else b.meta for b in books])
+    rows: list[tuple[Text | str, ...]] = []
+    for i, (book, author) in enumerate(zip(books, authors, strict=True), 1):
+        rec = book.record
+        rows.append(
+            (
+                Text(str(i), style="dim italic"),
+                format_ext(rec.extension if rec else None),
+                Text(book.title, style="bold"),
+                author,
+                format_size(rec.size_text if rec else None),
+                _plain(rec.language if rec else ""),
+                _plain(str(rec.year) if rec and rec.year else ""),
+                Text(book.md5, style="#00ccff"),
+            )
+        )
+    return rows
+
+
+def apply_meta(rec: BookRecord, meta: EditableMeta) -> BookRecord:
+    """Return ``rec`` with its editable fields replaced by ``meta``."""
+    year = int(meta.year) if meta.year.isdigit() else None
+    identifiers = rec.identifiers
+    if meta.isbn != (rec.isbns[0] if rec.isbns else ""):
+        # ``isbns`` derives from the identifiers, so an edited ISBN replaces both.
+        identifiers = {k: v for k, v in rec.identifiers.items() if k[:4] != "isbn"}
+        if meta.isbn:
+            identifiers["isbn13"] = (meta.isbn,)
+    return replace(
+        rec,
+        title=meta.title,
+        author=meta.author,
+        publisher=meta.publisher,
+        series=meta.series,
+        series_index=meta.series_index,
+        year=year,
+        languages=(meta.language,) if meta.language else (),
+        identifiers=identifiers,
+        description=meta.description,
+    )
+
+
+def render_record(rec: BookRecord, *, edited: bool = False) -> Text:
+    """Format ``rec`` as styled text for the detail pane."""
+    text = Text()
+    if edited:
+        text.append("✎ edited locally\n", style="yellow")
+    text.append(f"{rec.title or rec.md5}\n", style="bold")
+    series = f"{rec.series} #{rec.series_index}" if rec.series_index else rec.series
+    fields = [
+        ("Author", rec.author),
+        ("Publisher", rec.publisher),
+        ("Series", series),
+        ("Year", str(rec.year) if rec.year else ""),
+        ("Language", ", ".join(rec.languages)),
+        ("Format", f"{rec.extension} {rec.size_text}".strip()),
+        ("ISBN", ", ".join(rec.isbns)),
+    ]
+    for label, value in fields:
+        if value:
+            text.append(f"{label}: ", style="cyan")
+            text.append(f"{value}\n")
+    if rec.description:
+        text.append(f"\n{rec.description}")
+    return text
+
+
+class AaApp(App[None]):
+    """Search Anna's Archive, inspect a result, and download it."""
+
+    CSS = """
+    #main { height: 1fr; }
+    DataTable { width: 2fr; height: 100%; }
+    #detail { width: 1fr; height: 100%; border-left: solid $primary; padding: 0 1;
+              overflow-y: auto; }
+    """
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("/", "focus_search", "Search"),
+        Binding("d", "download", "Download"),
+        Binding("o", "open_browser", "Open in browser"),
+        Binding("e", "edit", "Edit metadata"),
+        Binding("w", "write_tags", "Write tags"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(
+        self,
+        settings: Settings,
+        query: str | None = None,
+        store: MetadataStore | None = None,
+    ) -> None:
+        """Create the app with resolved ``settings``, a first query and edit store."""
+        super().__init__()
+        self._settings = settings
+        self._initial_query = query
+        self._store = store or MetadataStore(DEFAULT_STORE)
+        self._records: dict[str, BookRecord] = {}
+        self._last_query = ""
+        self._loading: LoadingScreen | None = None
+
+    def compose(self) -> ComposeResult:
+        """Lay out the widgets."""
+        yield Header()
+        yield Input(placeholder="Search Anna's Archive…", id="query")
+        with Horizontal(id="main"):
+            yield DataTable(id="results", cursor_type="row")
+            yield Static("Select a result to see its details.", id="detail")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Route stray output to toasts, prepare the table and run any first query."""
+        self._capture_output()
+        table = self.query_one(DataTable)
+        for label, width in COLUMNS:
+            table.add_column(label, width=width)
+        if self._initial_query:
+            self.query_one(Input).value = self._initial_query
+            self._last_query = self._initial_query
+            self._search(self._initial_query)
+
+    def _capture_output(self) -> None:
+        """Send stdout, stderr and loguru output to toasts instead of the screen."""
+        self._saved_streams = (sys.stdout, sys.stderr)
+        self._out = ToastStream(self.toast, "information")
+        self._err = ToastStream(self.toast, "error")
+        sys.stdout, sys.stderr = self._out, self._err
+        logger.remove()
+        self._log_id = logger.add(self._log_sink, level="INFO", format="{message}")
+
+    def on_unmount(self) -> None:
+        """Restore the real streams and flush any partial line."""
+        self._out.flush_partial()
+        self._err.flush_partial()
+        sys.stdout, sys.stderr = self._saved_streams
+        logger.remove(self._log_id)
+
+    def _log_sink(self, message: Any) -> None:
+        """Show a loguru record as a toast at the matching severity."""
+        level = message.record["level"].no
+        severity = (
+            "error" if level >= 40 else "warning" if level >= 30 else "information"
+        )
+        self.toast(message.record["message"], severity)
+
+    def toast(self, message: str, severity: str = "information") -> None:
+        """Show a toast from any thread (errors linger longer)."""
+        timeout = 10.0 if severity == "error" else 5.0
+        if self._thread_id == threading.get_ident():
+            self.notify(message, severity=severity, timeout=timeout)  # type: ignore[arg-type]
+        else:
+            self.call_from_thread(
+                self.notify, message, severity=severity, timeout=timeout
+            )
+
+    def _handle_exception(self, error: Exception) -> None:
+        """Show unexpected exceptions in a modal instead of exiting the app.
+
+        Overrides Textual's private hook, which would otherwise print the
+        traceback and quit. A failed background worker leaves the app fully
+        usable; an exception in a UI handler may leave that widget unresponsive,
+        so the modal says to restart if the app stops reacting.
+        """
+        from textual.worker import WorkerFailed
+
+        recoverable = isinstance(error, WorkerFailed)
+        cause = error.error if isinstance(error, WorkerFailed) else error
+        self._end_loading()
+        self.push_screen(ErrorScreen(cause, recoverable=recoverable))
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Search for the submitted text; ignore blank input."""
+        if query := event.value.strip():
+            self._last_query = query
+            self._search(query)
+
+    def on_data_table_row_highlighted(self, event: DataTable.RowHighlighted) -> None:
+        """Load details for the highlighted row."""
+        if event.row_key.value:
+            self._load_details(event.row_key.value)
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        """Pop up the full details for a clicked (or Enter-ed) row."""
+        md5 = event.row_key.value
+        if md5 is None:
+            return
+        if md5 not in self._records:
+            self.notify("Details are still loading…")
+            return
+        rec = self._records[md5]
+        edited = self._store_has_edits(md5)
+        if edited and (entry := self._store.get(md5)):
+            rec = apply_meta(rec, entry.meta)
+        self.push_screen(DetailsScreen(rec, edited=edited))
+
+    def action_open_browser(self) -> None:
+        """Open the current search's results page on the site in the browser."""
+        if not self._last_query:
+            self.notify("Run a search first.", severity="warning")
+            return
+        url = f"{self._settings.origin}/search?{urlencode({'q': self._last_query})}"
+        if not webbrowser.open(url):
+            self.notify(f"Could not open a browser. URL: {url}", severity="error")
+
+    def action_focus_search(self) -> None:
+        """Move focus to the search box."""
+        self.query_one(Input).focus()
+
+    def _highlighted_md5(self) -> str | None:
+        """MD5 of the highlighted row, or ``None`` when the table is empty."""
+        table = self.query_one(DataTable)
+        if not table.row_count:
+            return None
+        return table.coordinate_to_cell_key(table.cursor_coordinate).row_key.value
+
+    def action_download(self) -> None:
+        """Download the highlighted book."""
+        if md5 := self._highlighted_md5():
+            self._download(md5)
+
+    def action_edit(self) -> None:
+        """Open the metadata form for the highlighted book."""
+        md5 = self._highlighted_md5()
+        rec = self._records.get(md5 or "")
+        if md5 is None or rec is None:
+            self.notify("Wait for the details to load first.", severity="warning")
+            return
+        entry = self._store.get(md5)
+        meta = entry.meta if entry else EditableMeta.from_record(rec)
+
+        def done(new: EditableMeta | None) -> None:
+            if new is None:
+                return
+            entry = self._store.set_meta(md5, new)
+            self._show_record(md5)
+            if entry.file and entry.file.exists():
+                self._embed(entry.file, entry.meta)
+            else:
+                self.notify(
+                    "Saved. Tags are written when the file is downloaded (or press w)."
+                )
+
+        self.push_screen(EditScreen(meta), done)
+
+    def action_write_tags(self) -> None:
+        """Embed the stored metadata into the downloaded file."""
+        md5 = self._highlighted_md5()
+        entry = self._store.get(md5) if md5 else None
+        if entry is None or entry.file is None or not entry.file.exists():
+            self.notify(
+                "Edit metadata and download the file first.", severity="warning"
+            )
+            return
+        self._embed(entry.file, entry.meta)
+
+    def _embed(self, path: Path, meta: EditableMeta) -> None:
+        """Write ``meta`` into ``path`` and notify the outcome."""
+        try:
+            write_tags(path, meta)
+        except TagError as exc:
+            self.notify(str(exc), severity="error")
+        else:
+            self.notify(f"Tagged {path.name}")
+
+    def _show_record(self, md5: str) -> None:
+        """Render the record for ``md5`` with any local edits applied."""
+        rec = self._records[md5]
+        edited = self._store_has_edits(md5)
+        if edited and (entry := self._store.get(md5)):
+            rec = apply_meta(rec, entry.meta)
+        self.query_one("#detail", Static).update(render_record(rec, edited=edited))
+
+    def _search(self, query: str) -> None:
+        """Show the loading modal and start the search worker."""
+        self._loading = LoadingScreen(query)
+        self.push_screen(self._loading, self._on_loading_closed)
+        self._run_search(query)
+
+    def _on_loading_closed(self, cancelled: bool | None) -> None:
+        """Abandon the in-flight search if the user pressed ``esc``."""
+        self._loading = None
+        if cancelled:
+            self.workers.cancel_group(self, "search")
+
+    def _end_loading(self) -> None:
+        """Close the loading modal if it is still showing."""
+        if self._loading is not None:
+            loading, self._loading = self._loading, None
+            loading.dismiss(False)
+
+    @work(thread=True, exclusive=True, group="search")
+    def _run_search(self, query: str) -> None:
+        """Run a search off the UI thread and show the results or the error."""
+        worker = get_current_worker()
+        try:
+            books = service.search(self._settings, query)
+        except service.SERVICE_ERRORS as exc:
+            if not worker.is_cancelled:
+                self.call_from_thread(self._search_failed, str(exc))
+            return
+        if not worker.is_cancelled:
+            self.call_from_thread(self._show_results, books)
+
+    def _search_failed(self, message: str) -> None:
+        """Close the loading modal and report ``message``."""
+        self._end_loading()
+        self.notify(message, severity="error")
+
+    def _show_results(self, books: list[Book]) -> None:
+        """Replace the table rows with ``books`` and focus the table."""
+        self._end_loading()
+        table = self.query_one(DataTable)
+        table.clear()
+        for book, row in zip(books, result_rows(books), strict=True):
+            table.add_row(*row, key=book.md5)
+        if books:
+            table.focus()
+        else:
+            self.notify("No results.")
+
+    @work(thread=True, exclusive=True, group="details")
+    def _load_details(self, md5: str) -> None:
+        """Fetch a record off the UI thread and render it unless superseded."""
+        worker = get_current_worker()
+        try:
+            rec = service.details(self._settings, md5)
+        except service.SERVICE_ERRORS as exc:
+            if not worker.is_cancelled:
+                self.call_from_thread(self.notify, str(exc), severity="error")
+            return
+        if not worker.is_cancelled:
+            self.call_from_thread(self._remember, rec)
+
+    def _remember(self, rec: BookRecord) -> None:
+        """Cache ``rec`` and show it unless the cursor has moved on."""
+        self._records[rec.md5] = rec
+        if self._highlighted_md5() == rec.md5:
+            self._show_record(rec.md5)
+
+    @work(thread=True, group="download")
+    def _download(self, md5: str) -> None:
+        """Download ``md5`` off the UI thread and report the outcome."""
+        self.call_from_thread(self.notify, f"Downloading {md5}…")
+        try:
+            path = service.download(self._settings, md5, f"{md5}.bin")
+        except service.SERVICE_ERRORS as exc:
+            self.call_from_thread(self.notify, str(exc), severity="error")
+            return
+        self.call_from_thread(self._downloaded, md5, path)
+
+    def _downloaded(self, md5: str, path: Path) -> None:
+        """Record the saved ``path`` and embed any stored edits into it."""
+        rec = self._records.get(md5)
+        seed = EditableMeta.from_record(rec) if rec else EditableMeta()
+        entry = self._store.set_file(md5, path, seed)
+        self.notify(f"Saved {path}")
+        if self._store_has_edits(md5):
+            self._embed(path, entry.meta)
+
+    def _store_has_edits(self, md5: str) -> bool:
+        """Whether the user edited ``md5`` (as opposed to just recording a path)."""
+        rec = self._records.get(md5)
+        entry = self._store.get(md5)
+        return bool(entry and rec and entry.meta != EditableMeta.from_record(rec))

aa_tui/capture.py

@@ -0,0 +1,47 @@
+"""Turn writes to stdout/stderr and loguru messages into app toasts."""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Callable
+
+from rich.text import Text
+
+Severity = str  # a Textual notify severity: "information", "warning" or "error"
+Emit = Callable[[str, Severity], None]
+
+
+class ToastStream(io.TextIOBase):
+    """A text stream that emits each completed non-blank line to ``emit``.
+
+    ANSI colour codes (from Rich, loguru, ...) are stripped. A trailing partial
+    line is emitted by :meth:`flush_partial`, which the app calls on shutdown.
+    """
+
+    def __init__(self, emit: Emit, severity: Severity) -> None:
+        """Send lines to ``emit`` with the given ``severity``."""
+        self._emit = emit
+        self._severity = severity
+        self._buffer = ""
+
+    def writable(self) -> bool:
+        """This stream accepts writes."""
+        return True
+
+    def write(self, s: str) -> int:
+        """Buffer ``s`` and emit every complete line in it."""
+        self._buffer += s
+        *lines, self._buffer = self._buffer.split("\n")
+        for line in lines:
+            self._send(line)
+        return len(s)
+
+    def flush_partial(self) -> None:
+        """Emit whatever is left in the buffer."""
+        rest, self._buffer = self._buffer, ""
+        self._send(rest)
+
+    def _send(self, line: str) -> None:
+        """Emit ``line`` if it has visible content."""
+        if text := Text.from_ansi(line).plain.strip():
+            self._emit(text, self._severity)

aa_tui/cli.py

@@ -0,0 +1,37 @@
+"""Typer entry point: ``aa-tui [QUERY]``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from aa_meta.config import DEFAULT_BASE_URL, Settings
+from aa_meta.cookies import read_cookie_file
+
+from .app import AaApp
+
+DEFAULT_OUTPUT_DIR = Path.home() / "Downloads"
+
+app = typer.Typer(help="Terminal UI for searching and downloading from Anna's Archive.")
+
+
+@app.command()
+def main(
+    query: Annotated[str | None, typer.Argument(help="Search to run on start.")] = None,
+    base_url: Annotated[
+        str, typer.Option("--base-url", envvar="AA_BASE_URL", help="Mirror domain.")
+    ] = DEFAULT_BASE_URL,
+    cookie: Annotated[
+        str | None,
+        typer.Option("--cookie", envvar="AA_COOKIE", help="Browser Cookie header."),
+    ] = None,
+    output: Annotated[
+        Path, typer.Option("--output", "-o", help="Download directory.")
+    ] = DEFAULT_OUTPUT_DIR,
+) -> None:
+    """Launch the TUI, optionally running QUERY immediately."""
+    settings = Settings(
+        base_url=base_url, cookie=cookie or read_cookie_file(), download_dir=output
+    )
+    AaApp(settings, query).run()

aa_tui/details_screen.py

@@ -0,0 +1,100 @@
+"""Modal popup showing every field of a book record."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import ClassVar
+
+from aa_meta.models import BookRecord
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Static
+
+
+def _section(text: Text, title: str, rows: Mapping[str, tuple[str, ...]]) -> None:
+    """Append a titled ``label: a, b`` block to ``text`` unless ``rows`` is empty."""
+    rows = {k: v for k, v in rows.items() if v}
+    if not rows:
+        return
+    text.append(f"\n{title}\n", style="bold underline")
+    for label, values in rows.items():
+        text.append(f"{label}: ", style="cyan")
+        text.append("; ".join(values) + "\n")
+
+
+def render_full(rec: BookRecord, *, edited: bool = False) -> Text:
+    """Format every populated field of ``rec`` as styled text."""
+    text = Text()
+    if edited:
+        text.append("✎ edited locally\n", style="yellow")
+    text.append(f"{rec.title or rec.md5}\n", style="bold")
+    series = f"{rec.series} #{rec.series_index}" if rec.series_index else rec.series
+    fields = [
+        ("Author", rec.author),
+        ("Publisher", rec.publisher_line or rec.publisher),
+        ("Series", series),
+        ("Year", str(rec.year) if rec.year else ""),
+        ("Language", ", ".join(rec.languages)),
+        ("ISBN", ", ".join(rec.isbns)),
+        ("Format", f"{rec.extension} {rec.size_text}".strip()),
+        ("Type", rec.content_type),
+        ("Sources", ", ".join(rec.sources)),
+        ("Filename", rec.filename),
+        ("MD5", rec.md5),
+    ]
+    for label, value in fields:
+        if value:
+            text.append(f"{label}: ", style="cyan")
+            text.append(f"{value}\n")
+    if rec.description:
+        text.append(f"\n{rec.description}\n")
+    _section(text, "Identifiers", rec.identifiers)
+    _section(text, "Alternatives", rec.alternatives)
+    if rec.filepaths:
+        _section(text, "Paths", {"": rec.filepaths})
+    if not rec.detailed:
+        text.append("\n(search-card data only)\n", style="dim")
+    return text
+
+
+class DetailsScreen(ModalScreen[None]):
+    """Read-only popup for one record; ``e`` and ``d`` act on it via the app."""
+
+    DEFAULT_CSS = """
+    DetailsScreen { align: center middle; }
+    #popup { width: 85%; max-width: 110; height: 85%; border: thick $primary;
+             background: $surface; padding: 1 2; }
+    """
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("escape,q,enter", "close", "Close"),
+        Binding("e", "edit", "Edit"),
+        Binding("d", "download", "Download"),
+    ]
+
+    def __init__(self, rec: BookRecord, *, edited: bool = False) -> None:
+        """Show ``rec``; ``edited`` adds the local-edit marker."""
+        super().__init__()
+        self._rec = rec
+        self._edited = edited
+
+    def compose(self) -> ComposeResult:
+        """A scrollable text body."""
+        with VerticalScroll(id="popup"):
+            yield Static(render_full(self._rec, edited=self._edited))
+
+    def action_close(self) -> None:
+        """Dismiss the popup."""
+        self.dismiss(None)
+
+    def action_edit(self) -> None:
+        """Close, then open the app's edit form."""
+        self.dismiss(None)
+        self.app.call_later(self.app.run_action, "edit")
+
+    def action_download(self) -> None:
+        """Close, then download via the app."""
+        self.dismiss(None)
+        self.app.call_later(self.app.run_action, "download")

aa_tui/edit_screen.py

@@ -0,0 +1,88 @@
+"""Modal form for editing a book's metadata."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, fields
+from typing import ClassVar
+
+from textual.app import ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Horizontal, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, Input, Label
+
+from .metadata import EditableMeta
+
+LABELS = {
+    "title": "Title",
+    "author": "Author",
+    "publisher": "Publisher",
+    "series": "Series",
+    "series_index": "Series #",
+    "year": "Year",
+    "language": "Language",
+    "isbn": "ISBN",
+    "description": "Description",
+}
+
+
+class EditScreen(ModalScreen[EditableMeta | None]):
+    """Edit an :class:`EditableMeta`; dismisses with the new value, or ``None``."""
+
+    DEFAULT_CSS = """
+    EditScreen { align: center middle; }
+    #form { width: 80%; max-width: 100; height: 80%; border: thick $primary;
+            background: $surface; padding: 1 2; }
+    #form Label { margin-top: 1; }
+    #buttons { height: auto; margin-top: 1; }
+    #buttons Button { margin-right: 2; }
+    """
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("escape", "cancel", "Cancel"),
+        Binding("ctrl+s", "save", "Save"),
+    ]
+
+    def __init__(self, meta: EditableMeta) -> None:
+        """Start the form pre-filled from ``meta``."""
+        super().__init__()
+        self._meta = meta
+
+    def compose(self) -> ComposeResult:
+        """One labelled input per editable field, then Save/Cancel."""
+        values = asdict(self._meta)
+        with VerticalScroll(id="form"):
+            for f in fields(EditableMeta):
+                yield Label(LABELS[f.name])
+                yield Input(values[f.name], id=f"f-{f.name}")
+            with Horizontal(id="buttons"):
+                yield Button("Save (ctrl+s)", variant="primary", id="save")
+                yield Button("Cancel (esc)", id="cancel")
+
+    def _collect(self) -> EditableMeta:
+        """Read the inputs back into an :class:`EditableMeta`."""
+        return EditableMeta(
+            **{
+                f.name: self.query_one(f"#f-{f.name}", Input).value
+                for f in fields(EditableMeta)
+            }
+        ).normalized()
+
+    def action_save(self) -> None:
+        """Dismiss with the edited metadata."""
+        self.dismiss(self._collect())
+
+    def action_cancel(self) -> None:
+        """Dismiss without changes."""
+        self.dismiss(None)
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        """Enter in any field saves."""
+        event.stop()
+        self.action_save()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Route the Save/Cancel buttons."""
+        if event.button.id == "save":
+            self.action_save()
+        else:
+            self.action_cancel()

aa_tui/error_screen.py

@@ -0,0 +1,56 @@
+"""Modal for unexpected errors, with the full traceback."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rich.console import Group, RenderableType
+from rich.text import Text
+from rich.traceback import Traceback
+from textual.app import ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Static
+
+
+class ErrorScreen(ModalScreen[None]):
+    """Show an unhandled exception without exiting the app."""
+
+    DEFAULT_CSS = """
+    ErrorScreen { align: center middle; }
+    #error { width: 90%; max-width: 120; height: 80%; border: thick $error;
+             background: $surface; padding: 1 2; }
+    """
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("escape,enter,q", "close", "Close")
+    ]
+
+    def __init__(self, error: BaseException, *, recoverable: bool = True) -> None:
+        """Show ``error`` and its traceback; ``recoverable`` softens the hint."""
+        super().__init__()
+        self._error = error
+        self._recoverable = recoverable
+
+    def compose(self) -> ComposeResult:
+        """Headline, traceback, and a close hint."""
+        body: RenderableType = Group(
+            Text(f"{type(self._error).__name__}: {self._error}", style="bold red"),
+            Text(""),
+            Traceback.from_exception(
+                type(self._error), self._error, self._error.__traceback__, width=100
+            ),
+            Text(
+                "\nPress esc to close."
+                + (
+                    "" if self._recoverable else " Restart if the app stops responding."
+                ),
+                style="dim",
+            ),
+        )
+        with VerticalScroll(id="error"):
+            yield Static(body)
+
+    def action_close(self) -> None:
+        """Dismiss the modal."""
+        self.dismiss(None)

aa_tui/loading_screen.py

@@ -0,0 +1,39 @@
+"""Modal spinner shown while a search is in flight."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from textual.app import ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Label, LoadingIndicator
+
+
+class LoadingScreen(ModalScreen[bool]):
+    """Spinner popup; dismisses with ``True`` if the user cancels with ``esc``."""
+
+    DEFAULT_CSS = """
+    LoadingScreen { align: center middle; }
+    #loading { width: 44; height: 9; border: thick $primary; background: $surface;
+        padding: 1 2; align: center middle; }
+    #loading LoadingIndicator { height: 3; }
+    #loading Label { width: 100%; content-align: center middle; }
+    """
+    BINDINGS: ClassVar[list[BindingType]] = [Binding("escape", "cancel", "Cancel")]
+
+    def __init__(self, query: str) -> None:
+        """Show ``query`` in the message."""
+        super().__init__()
+        self._query = query
+
+    def compose(self) -> ComposeResult:
+        """Spinner above a one-line message."""
+        with Vertical(id="loading"):
+            yield LoadingIndicator()
+            yield Label(f"Searching for “{self._query}”… (esc to cancel)")
+
+    def action_cancel(self) -> None:
+        """Dismiss, flagging a user cancel."""
+        self.dismiss(True)

aa_tui/metadata.py

@@ -0,0 +1,121 @@
+"""Editable metadata and the local store that remembers edits per MD5."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, fields, replace
+from pathlib import Path
+from typing import Any
+
+from aa_meta.models import BookRecord
+
+DEFAULT_STORE = (
+    Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    / "aa-tui"
+    / "metadata.json"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class EditableMeta:
+    """The subset of a record the user can edit and embed in a file."""
+
+    title: str = ""
+    author: str = ""
+    publisher: str = ""
+    series: str = ""
+    series_index: str = ""
+    year: str = ""
+    language: str = ""
+    isbn: str = ""
+    description: str = ""
+
+    @classmethod
+    def from_record(cls, rec: BookRecord) -> EditableMeta:
+        """Seed editable fields from a scraped ``rec``."""
+        return cls(
+            title=rec.title,
+            author=rec.author,
+            publisher=rec.publisher,
+            series=rec.series,
+            series_index=rec.series_index,
+            year=str(rec.year) if rec.year else "",
+            language=rec.language,
+            isbn=rec.isbns[0] if rec.isbns else "",
+            description=rec.description,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> EditableMeta:
+        """Build from stored JSON, ignoring unknown keys."""
+        names = {f.name for f in fields(cls)}
+        return cls(**{k: str(v) for k, v in data.items() if k in names})
+
+    def normalized(self) -> EditableMeta:
+        """Return a copy with every field stripped of surrounding whitespace."""
+        return replace(self, **{k: v.strip() for k, v in asdict(self).items()})
+
+
+@dataclass(frozen=True, slots=True)
+class Entry:
+    """A stored edit: the metadata plus the downloaded file it applies to."""
+
+    meta: EditableMeta
+    file: Path | None = None
+
+
+class MetadataStore:
+    """JSON file mapping MD5 -> :class:`Entry`; written atomically on every change."""
+
+    def __init__(self, path: Path = DEFAULT_STORE) -> None:
+        """Use ``path`` as the backing file (created lazily)."""
+        self._path = path
+
+    def _load(self) -> dict[str, Any]:
+        """Read the whole file; a missing or corrupt file is an empty store."""
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except OSError, ValueError:
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def _save(self, data: dict[str, Any]) -> None:
+        """Atomically replace the backing file with ``data``."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        tmp.replace(self._path)
+
+    def get(self, md5: str) -> Entry | None:
+        """Return the entry for ``md5`` or ``None``."""
+        raw = self._load().get(md5)
+        if not isinstance(raw, dict):
+            return None
+        file = raw.get("file")
+        return Entry(
+            EditableMeta.from_dict(raw.get("meta", {})), Path(file) if file else None
+        )
+
+    def put(self, md5: str, entry: Entry) -> None:
+        """Insert or replace the entry for ``md5``."""
+        data = self._load()
+        data[md5] = {
+            "meta": asdict(entry.meta),
+            "file": str(entry.file) if entry.file else None,
+        }
+        self._save(data)
+
+    def set_meta(self, md5: str, meta: EditableMeta) -> Entry:
+        """Store ``meta`` for ``md5``, keeping any recorded file."""
+        old = self.get(md5)
+        entry = Entry(meta.normalized(), old.file if old else None)
+        self.put(md5, entry)
+        return entry
+
+    def set_file(self, md5: str, file: Path, fallback: EditableMeta) -> Entry:
+        """Record the downloaded ``file``; ``fallback`` seeds meta if none stored."""
+        old = self.get(md5)
+        entry = Entry(old.meta if old else fallback, file)
+        self.put(md5, entry)
+        return entry

aa_tui/service.py

@@ -0,0 +1,83 @@
+"""Thin synchronous wrappers over aa-meta, so the app talks to one module."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+import httpx
+from aa_meta.api import fast_download
+from aa_meta.config import USER_AGENT, Settings, read_secret_key
+from aa_meta.details import fetch_details
+from aa_meta.download import filename_from_response
+from aa_meta.models import BookRecord
+from aa_meta.search import Book, search_books
+
+# Everything the aa-meta layers raise (all ``RuntimeError`` subclasses) plus I/O.
+SERVICE_ERRORS = (RuntimeError, httpx.HTTPError, OSError)
+
+
+@contextmanager
+def _session(client: httpx.Client | None) -> Generator[httpx.Client]:
+    """Yield ``client``, or a fresh one that is closed afterwards."""
+    if client is not None:
+        yield client
+        return
+    with httpx.Client(timeout=30, follow_redirects=True) as owned:
+        yield owned
+
+
+def search(
+    settings: Settings,
+    query: str,
+    *,
+    limit: int = 20,
+    client: httpx.Client | None = None,
+) -> list[Book]:
+    """Search Anna's Archive for ``query``.
+
+    Raises:
+        SearchError: if the site blocks the request.
+    """
+    with _session(client) as c:
+        return search_books(c, settings, query, limit=limit)
+
+
+def details(
+    settings: Settings, md5: str, *, client: httpx.Client | None = None
+) -> BookRecord:
+    """Fetch the full metadata record for ``md5``."""
+    with _session(client) as c:
+        return fetch_details(c, settings, md5)
+
+
+def download(
+    settings: Settings,
+    md5: str,
+    fallback_name: str,
+    *,
+    client: httpx.Client | None = None,
+) -> Path:
+    """Download ``md5`` into ``settings.download_dir`` and return the saved path.
+
+    Streams without Rich progress output, which would corrupt the TUI screen.
+
+    Raises:
+        ConfigError: if the API key is unavailable.
+        ApiError: if the API refuses the download.
+        httpx.HTTPError: on a network failure.
+    """
+    key = read_secret_key(settings.op_ref)
+    with _session(client) as c:
+        fd = fast_download(c, settings, md5, key)
+        settings.download_dir.mkdir(parents=True, exist_ok=True)
+        with c.stream(
+            "GET", fd.url, headers={"User-Agent": USER_AGENT}, follow_redirects=True
+        ) as resp:
+            resp.raise_for_status()
+            path = settings.download_dir / filename_from_response(resp, fallback_name)
+            with path.open("wb") as fh:
+                for chunk in resp.iter_bytes(65536):
+                    fh.write(chunk)
+    return path

aa_tui/tags.py

@@ -0,0 +1,219 @@
+"""Write :class:`~aa_tui.metadata.EditableMeta` into EPUB, PDF, MP4/M4B and MP3 files."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+import zipfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import IO
+from xml.etree import ElementTree as ET
+
+from mutagen.id3 import ID3, TALB, TDRC, TIT2, TPE1, TPUB, ID3NoHeaderError
+from mutagen.mp4 import MP4
+from pypdf import PdfReader, PdfWriter
+
+from .metadata import EditableMeta
+
+DC = "http://purl.org/dc/elements/1.1/"
+OPF = "http://www.idpf.org/2007/opf"
+CONTAINER = "urn:oasis:names:tc:opendocument:xmlns:container"
+
+
+class TagError(RuntimeError):
+    """The file could not be tagged (unsupported type or malformed contents)."""
+
+
+def write_tags(path: Path, meta: EditableMeta) -> None:
+    """Embed ``meta`` into ``path``, dispatching on its extension.
+    Args:
+        path: The file path to write tags into.
+        meta: The metadata to embed.
+    Raises:
+        TagError: for an unsupported extension or an unreadable file.
+    """
+    writers = {
+        ".epub": _write_epub,
+        ".pdf": _write_pdf,
+        ".m4b": _write_mp4,
+        ".m4a": _write_mp4,
+        ".mp4": _write_mp4,
+        ".mp3": _write_mp3,
+    }
+    writer = writers.get(path.suffix.lower())
+    if writer is None:
+        raise TagError(f"Cannot embed metadata in {path.suffix or 'this'} files.")
+    try:
+        writer(path, meta)
+    except TagError:
+        raise
+    except Exception as exc:  # third-party parsers raise many unrelated types
+        raise TagError(f"{path.name}: {exc}") from exc
+
+
+def _write_mp4(path: Path, meta: EditableMeta) -> None:
+    """Set iTunes-style atoms on an MP4/M4B/M4A file.
+    Args:
+        path: The path to the MP4/M4B/M4A file.
+        meta: The metadata to embed.
+    """
+    tags = MP4(path)
+    if tags.tags is None:
+        tags.add_tags()
+    assert tags.tags is not None
+    t = tags.tags
+    for key, value in (
+        ("\xa9nam", meta.title),
+        ("\xa9alb", meta.title),
+        ("\xa9ART", meta.author),
+        ("aART", meta.author),
+        ("\xa9day", meta.year),
+        ("desc", meta.description),
+    ):
+        if value:
+            t[key] = [value]
+        else:
+            t.pop(key, None)
+    if meta.series:
+        t["\xa9grp"] = [meta.series]
+    tags.save()
+
+
+def _write_mp3(path: Path, meta: EditableMeta) -> None:
+    """Set ID3v2 frames on an MP3 file.
+    Args:
+        path: The path to the MP3 file.
+        meta: The metadata to embed.
+    """
+    try:
+        id3 = ID3(path)
+    except ID3NoHeaderError:
+        id3 = ID3()
+    for frame, value in (
+        (TIT2, meta.title),
+        (TALB, meta.title),
+        (TPE1, meta.author),
+        (TPUB, meta.publisher),
+        (TDRC, meta.year),
+    ):
+        id3.delall(frame.__name__)
+        if value:
+            id3.add(frame(encoding=3, text=[value]))
+    id3.save(path)
+
+
+def _write_pdf(path: Path, meta: EditableMeta) -> None:
+    """Rewrite the PDF with an updated document-information dictionary.
+    Args:
+        path: The path to the PDF file.
+        meta: The metadata to embed.
+    """
+    reader = PdfReader(path)
+    writer = PdfWriter(clone_from=reader)
+    info = {"/Title": meta.title, "/Author": meta.author, "/Subject": meta.description}
+    writer.add_metadata({k: v for k, v in info.items() if v})
+    _replace_via_temp(path, lambda fh: writer.write(fh) and None)
+
+
+def _replace_via_temp(path: Path, write: Callable[[IO[bytes]], None]) -> None:
+    """Run ``write(tmp_path)`` then atomically swap it over ``path``.
+    Args:
+        path: The path to the file to replace.
+        write: A function that writes to a file-like object.
+    """
+    with tempfile.NamedTemporaryFile(
+        dir=path.parent, suffix=path.suffix, delete=False
+    ) as tmp:
+        tmp_path = Path(tmp.name)
+    try:
+        with tmp_path.open("wb") as fh:
+            write(fh)
+        shutil.copymode(path, tmp_path)
+        tmp_path.replace(path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def _write_epub(path: Path, meta: EditableMeta) -> None:
+    """Update Dublin Core and calibre series entries in the EPUB's OPF package.
+    Args:
+        path: The path to the EPUB file.
+        meta: The metadata to embed.
+    """
+    with zipfile.ZipFile(path) as zin:
+        container = ET.fromstring(zin.read("META-INF/container.xml"))
+        rootfile = container.find(f".//{{{CONTAINER}}}rootfile")
+        if rootfile is None or not rootfile.get("full-path"):
+            raise TagError("EPUB has no package document.")
+        opf_name = rootfile.get("full-path", "")
+        opf_xml = _update_opf(zin.read(opf_name), meta)
+
+        def write(fh: IO[bytes]) -> None:
+            with zipfile.ZipFile(fh, "w") as zout:
+                # The mimetype entry must come first and be stored uncompressed.
+                for item in sorted(
+                    zin.infolist(), key=lambda i: i.filename != "mimetype"
+                ):
+                    data = (
+                        opf_xml
+                        if item.filename == opf_name
+                        else zin.read(item.filename)
+                    )
+                    zout.writestr(item, data, compress_type=item.compress_type)
+
+        _replace_via_temp(path, write)
+
+
+def _update_opf(xml: bytes, meta: EditableMeta) -> bytes:
+    """Return ``xml`` (an OPF package) with ``meta`` applied; empty fields are removed.
+    Args:
+        xml: The OPF package XML.
+        meta: The metadata to embed.
+    Returns:
+        The updated OPF package XML.
+    Raises:
+        TagError: If the EPUB package has no metadata block.
+    """
+    ET.register_namespace("dc", DC)
+    ET.register_namespace("opf", OPF)
+    root = ET.fromstring(xml)
+    md = root.find(f"{{{OPF}}}metadata")
+    if md is None:
+        raise TagError("EPUB package has no metadata block.")
+
+    def set_dc(tag: str, value: str) -> None:
+        for el in md.findall(f"{{{DC}}}{tag}"):
+            md.remove(el)
+        if value:
+            ET.SubElement(md, f"{{{DC}}}{tag}").text = value
+
+    set_dc("title", meta.title)
+    set_dc("creator", meta.author)
+    set_dc("publisher", meta.publisher)
+    set_dc("language", meta.language)
+    set_dc("description", meta.description)
+    set_dc("date", meta.year)
+    for el in md.findall(f"{{{DC}}}identifier"):
+        if (el.get(f"{{{OPF}}}scheme") or "").upper() == "ISBN":
+            md.remove(el)
+    if meta.isbn:
+        ET.SubElement(
+            md, f"{{{DC}}}identifier", {f"{{{OPF}}}scheme": "ISBN"}
+        ).text = meta.isbn
+
+    for el in md.findall(f"{{{OPF}}}meta"):
+        if el.get("name") in {"calibre:series", "calibre:series_index"}:
+            md.remove(el)
+    if meta.series:
+        ET.SubElement(
+            md, f"{{{OPF}}}meta", {"name": "calibre:series", "content": meta.series}
+        )
+        if meta.series_index:
+            ET.SubElement(
+                md,
+                f"{{{OPF}}}meta",
+                {"name": "calibre:series_index", "content": meta.series_index},
+            )
+    out: bytes = ET.tostring(root, encoding="utf-8", xml_declaration=True)
+    return out

aa_tui-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.3
+Name: aa-tui
+Version: 0.1.0
+Summary: Add your description here
+Author: Maxwell Ludden
+Author-email: Maxwell Ludden <maxludden@me.com>
+Requires-Dist: aa-meta
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mutagen>=1.48.1
+Requires-Dist: pypdf>=6.20.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: textual>=8.2.8
+Requires-Dist: typer>=0.27.3
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# aa-tui
+
+Textual front-end for [aa-meta](../aa-meta): search Anna's Archive, inspect a result, download it, and edit its metadata.
+
+```bash
+uv sync
+uv run aa-tui ["query"] [--base-url ...] [--cookie ...] [-o DIR]
+```
+
+Results are shown with `aa-meta`'s columns: #, Ext, Title, Author (colour-coded per author), Size, Lang, Year and MD5.
+
+Keys: `Enter` in the search box searches (a spinner popup shows while waiting; `esc` cancels); `/` focuses search; `↑/↓` selects (details load automatically); `Enter` or a click on a row opens a details popup (`e`/`d` work inside it, `esc` closes); `o` opens the current search on the site in your browser; `d` downloads (needs `AA_SECRET_KEY` or 1Password); `q` quits (when not typing).
+
+## Editing metadata
+
+`e` opens a form for the highlighted book (title, author, publisher, series, year, language, ISBN, description). `ctrl+s` saves, `esc` cancels.
+Edits are stored per MD5 in `~/.config/aa-tui/metadata.json` and shown in the detail pane. When the book has been downloaded, saving also embeds the tags in the file; otherwise they are embedded as soon as it downloads. `w` re-embeds on demand.
+
+Supported formats: EPUB (OPF Dublin Core + calibre series), PDF (info dictionary), M4B/M4A/MP4 (iTunes atoms), MP3 (ID3v2). Other formats are left untouched with an error notice.
+
+## Errors and output
+
+Nothing is printed over the TUI. Anything written to stdout/stderr or logged through `loguru` (including from `aa-meta`) appears as a toast: info for stdout and `INFO`, warning for `WARNING`, error (shown longer) for stderr and `ERROR`+. Expected failures (blocked search, API refusals, network errors, unsupported tag formats) are toasts too. An unexpected exception opens a modal with the full traceback instead of quitting; `esc` closes it.

aa_tui-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+aa_tui/__init__.py,sha256=GhZi1VKb4YRmqCeHzQi0l0_cvhQIJa3T5k7J8lWhk4Q,37
+aa_tui/app.py,sha256=fVQQ7ygcTc4kduhpAEWCEZetEzuut6yR43bbZPch-yY,16744
+aa_tui/capture.py,sha256=TnszhvAay8TeO00baxgBBYI1v4GEubscL9a35TRLbZ8,1512
+aa_tui/cli.py,sha256=qiBV2lSz_BaRb-6VqWvLfaVOVYybI44L0szLCwvmxTY,1152
+aa_tui/details_screen.py,sha256=b6eRXkfM2T4eTVKDCyLovq2KP60ppZrTOsPG0CAUeik,3599
+aa_tui/edit_screen.py,sha256=mY9Lb7gje1oU_F26ovrdZ6S_elbr5RXNjoBJZq3WAbg,2856
+aa_tui/error_screen.py,sha256=WtYTrrK5SRuPOei_84v2-xjcE5_QVpDB6rAcoKkrEYY,1897
+aa_tui/loading_screen.py,sha256=KgA_080ScvNURNu24hGZ_ccYiGxF_ZyV_PRg1lIxDpo,1364
+aa_tui/metadata.py,sha256=n_GPuOnUPLPUmO7lA1TCN4HmVomtnyTLrguRCsmhPSI,4045
+aa_tui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aa_tui/service.py,sha256=_DfshPkHl2gc1EzvFA8GBxdEN1aR1IZ81pAFoxtQ5Gw,2600
+aa_tui/tags.py,sha256=CdFdjNpYBdkysKlGPtkoXNqF-GSWBxMiLGscKQKE1dc,7133
+aa_tui-0.1.0.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+aa_tui-0.1.0.dist-info/entry_points.txt,sha256=RSrmSkw2AYYtcvOiqOvR3ilhaWlqb0XE1BqstM-_A6A,43
+aa_tui-0.1.0.dist-info/METADATA,sha256=hF5i-rZEu_5_iCEJ6UOqbPP-PGxwNYEo4XQZ1xQDhwY,2238
+aa_tui-0.1.0.dist-info/RECORD,,

aa_tui-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aa_tui-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+aa-tui = aa_tui.cli:app
+