aa-meta 0.1.0__py3-none-any.whl

aa_meta/__init__.py

@@ -0,0 +1,3 @@
+"""aa-meta: search and download books from Anna's Archive."""
+
+__version__ = "0.1.0"

aa_meta/api.py

@@ -0,0 +1,55 @@
+"""Client for the Anna's Archive fast-download JSON API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .config import USER_AGENT, Settings
+
+
+class ApiError(RuntimeError):
+    """Raised when the API returns an error or no download URL."""
+
+
+@dataclass(frozen=True)
+class FastDownload:
+    """Successful fast-download response."""
+
+    url: str
+    info: dict[str, Any]
+
+
+def fast_download(
+    client: httpx.Client,
+    settings: Settings,
+    md5: str,
+    key: str,
+    path_index: int | None = None,
+    domain_index: int | None = None,
+) -> FastDownload:
+    """Resolve a member fast-download URL for ``md5``.
+
+    Raises:
+        ApiError: on a non-2xx response or a null ``download_url``.
+    """
+    params: dict[str, str | int] = {"md5": md5, "key": key}
+    if path_index is not None:
+        params["path_index"] = path_index
+    if domain_index is not None:
+        params["domain_index"] = domain_index
+    resp = client.get(
+        f"{settings.origin}/dyn/api/fast_download.json",
+        params=params,
+        headers={"User-Agent": USER_AGENT},
+    )
+    try:
+        data: dict[str, Any] = resp.json()
+    except ValueError as exc:
+        raise ApiError(f"HTTP {resp.status_code}: non-JSON response") from exc
+    url = data.get("download_url")
+    if resp.status_code not in (200, 204) or not url:
+        raise ApiError(data.get("error") or f"HTTP {resp.status_code}")
+    return FastDownload(url=url, info=data.get("account_fast_download_info") or {})

aa_meta/authors.py

@@ -0,0 +1,69 @@
+"""Colour-code the authors of search results with a ``rich_gradient`` Spectrum."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from rich.style import Style
+from rich.text import Text
+from rich_gradient.spectrum import COLOR_STOPS, Spectrum
+
+
+def split_authors(raw: str) -> list[str]:
+    """Split a site author string into individual names (heuristic).
+
+    The site separates authors with ``;``. Some sources use commas instead, which
+    is ambiguous with ``Last, First``: a single comma is treated as one
+    ``Last, First`` name, two or more as a comma-separated list.
+    """
+    if ";" in raw:
+        parts = raw.split(";")
+    elif raw.count(",") >= 2:
+        parts = raw.split(",")
+    else:
+        parts = [raw]
+    return [p.strip() for p in parts if p.strip()]
+
+
+def author_key(name: str) -> str:
+    """Normalise a name so ``Herbert, Frank`` and ``Frank Herbert`` match."""
+    if "," in name:
+        last, _, first = name.partition(",")
+        name = f"{first} {last}"
+    return " ".join(name.replace(".", "").casefold().split())
+
+
+def format_authors(raw_authors: Sequence[str], *, seed: int = 0) -> list[Text]:
+    """Return one colour-coded :class:`~rich.text.Text` per author string.
+
+    Every distinct author (by :func:`author_key`) gets one colour from a
+    :class:`~rich_gradient.spectrum.Spectrum`, so the same person looks the same
+    in every row. ``Spectrum`` yields consecutive colours around the ring, so the
+    full ring is built and colours are picked evenly spaced to keep a handful of
+    authors visually distinct; with more authors than colours, colours repeat.
+
+    Args:
+        raw_authors: The author field of each result, in row order.
+        seed: Rotates where the colour ring starts; same seed, same colours.
+
+    Returns:
+        A list the same length as ``raw_authors``; empty authors render as a dim
+        ``Unknown``.
+    """
+    rows = [split_authors(raw) for raw in raw_authors]
+    keys = list(dict.fromkeys(author_key(n) for names in rows for n in names))
+    ring = Spectrum(hues=len(COLOR_STOPS), seed=seed).styles
+    step = max(len(ring) / max(len(keys), 1), 1.0)
+    style_of = {k: ring[int(i * step) % len(ring)] for i, k in enumerate(keys)}
+
+    texts: list[Text] = []
+    for names in rows:
+        text = Text(no_wrap=False)
+        if not names:
+            text.append("Unknown", style="dim")
+        for i, name in enumerate(names):
+            if i:
+                text.append("; ", style="dim")
+            text.append(name, style=style_of[author_key(name)] + Style(bold=True))
+        texts.append(text)
+    return texts

aa_meta/cli.py

@@ -0,0 +1,520 @@
+"""Typer command-line interface: ``aa search`` and ``aa download``."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import httpx
+import typer
+from loguru import logger
+from rich.box import ROUNDED
+from rich.console import Console
+from rich.markup import escape
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+from rich.prompt import Confirm, IntPrompt
+from rich.table import Table
+from rich.text import Text as RichText
+from rich_gradient import Text
+
+from .api import ApiError, fast_download
+from .authors import format_authors
+from .config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_OP_REF,
+    ConfigError,
+    Settings,
+    read_secret_key,
+)
+from .cookies import BROWSERS, CookieError, read_cookie_file, refresh_cookies
+from .details import fetch_details
+from .download import download_file
+from .models import BookRecord
+from .search import Book, SearchError, search_books
+
+app = typer.Typer(
+    help="Search and download books from Anna's Archive.", no_args_is_help=True
+)
+console = Console()
+err = Console(stderr=True)
+
+BaseUrl = Annotated[
+    str, typer.Option("--base-url", envvar="AA_BASE_URL", help="Mirror domain.")
+]
+OpRef = Annotated[
+    str,
+    typer.Option("--op-ref", envvar="AA_OP_REF", help="1Password secret reference."),
+]
+Cookie = Annotated[
+    str | None,
+    typer.Option(
+        "--cookie",
+        envvar="AA_COOKIE",
+        help="Browser Cookie header to pass the site's browser check.",
+    ),
+]
+
+
+BrowserOpt = Annotated[
+    str,
+    typer.Option(
+        "--browser",
+        envvar="AA_BROWSER",
+        help=f"Browser to pull cookies from: {', '.join(BROWSERS)}.",
+    ),
+]
+
+DEFAULT_OUTPUT_DIR = Path().home() / "Downloads"
+
+@contextmanager
+def _busy(description: str) -> Iterator[Callable[[str], None]]:
+    """Show a spinner with elapsed time while a request runs.
+
+    Yields a function that replaces the spinner text (used to report a cookie
+    refresh). The spinner is transient, so it disappears before results print.
+    """
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        TimeElapsedColumn(),
+        transient=True,
+        console=console,
+    ) as progress:
+        task = progress.add_task(description, total=None)
+        yield lambda text: progress.update(task, description=text)
+
+
+def _fail(msg: str) -> typer.Exit:
+    err.print(f"[bold red]Error:[/] {msg}")
+    return typer.Exit(1)
+
+
+def _with_cookies[T](
+    call: Callable[[httpx.Client, Settings], T],
+    base_url: str,
+    cookie: str | None,
+    browser: str,
+    refresh: bool,
+    status: Callable[[str], None] = lambda text: err.print(f"[yellow]{text}[/]"),
+) -> T:
+    """Run ``call``; on a blocked request re-read browser cookies and retry once.
+
+    ``status`` reports the refresh (it replaces the spinner text when one is shown).
+    """
+    settings = Settings(base_url=base_url, cookie=cookie or read_cookie_file())
+    with httpx.Client(timeout=30, follow_redirects=True) as client:
+        try:
+            return call(client, settings)
+        except SearchError:
+            if not (refresh and cookie is None):
+                raise
+            status("Cookies expired; refreshing from browser…")
+            fresh = refresh_cookies(client, settings, browser)
+            return call(client, Settings(base_url=base_url, cookie=fresh))
+
+
+@app.callback()
+def main(verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False) -> None:
+    """Configure logging."""
+    logger.remove()
+    if verbose:
+        logger.add(sys.stderr, level="DEBUG")
+
+
+@app.command()
+def search(
+    query: Annotated[str, typer.Argument(help="Title, author, or ISBN.")],
+    ext: Annotated[
+        str | None, typer.Option("--ext", "-e", help="File type, e.g. epub.")
+    ] = None,
+    limit: Annotated[int, typer.Option("--limit", "-n")] = 20,
+    lang: Annotated[
+        str | None, typer.Option("--lang", "-l", help="Language code, e.g. en.")
+    ] = None,
+    content: Annotated[
+        str | None,
+        typer.Option("--content", "-c", help="e.g. book_fiction, book_nonfiction."),
+    ] = None,
+    sort: Annotated[
+        str | None, typer.Option("--sort", help="e.g. newest, largest, oldest.")
+    ] = None,
+    base_url: BaseUrl = DEFAULT_BASE_URL,
+    cookie: Cookie = None,
+    browser: BrowserOpt = "chrome",
+    refresh: Annotated[
+        bool, typer.Option(help="Re-read browser cookies on a 403 and retry.")
+    ] = True,
+    prompt: Annotated[
+        bool,
+        typer.Option(
+            "--prompt/--no-prompt",
+            help="Offer to download a result (interactive terminals only).",
+        ),
+    ] = True,
+    output: Annotated[
+        Path, typer.Option("--output", "-o", help="Download directory.")
+    ] = DEFAULT_OUTPUT_DIR,
+    op_ref: OpRef = DEFAULT_OP_REF,
+) -> None:
+    """Search for books and print their MD5 hashes, then offer to download one."""
+    try:
+        with _busy(f"Searching for [bold]{escape(query)}[/]…") as status:
+            books = _with_cookies(
+                lambda c, s: search_books(
+                    c, s, query, ext, limit, lang=lang, content=content, sort=sort
+                ),
+                base_url,
+                cookie,
+                browser,
+                refresh,
+                status,
+            )
+    except (SearchError, CookieError, httpx.HTTPError) as exc:
+        raise _fail(str(exc)) from exc
+    if not books:
+        console.print("[yellow]No results.[/]")
+        raise typer.Exit(1)
+    console.print(_results_table(books, console.width))
+    if prompt and _interactive():
+        _offer_download(books, output=output, base_url=base_url, op_ref=op_ref)
+
+
+def _interactive() -> bool:
+    """Return whether we can prompt: both stdin and stdout are a terminal."""
+    return sys.stdin.isatty() and console.is_terminal
+
+
+def _download_md5(
+    md5: str,
+    *,
+    output: Path,
+    base_url: str,
+    op_ref: str,
+    path_index: int | None = None,
+    domain_index: int | None = None,
+    fallback_name: str | None = None,
+) -> Path:
+    """Resolve a member fast-download URL for ``md5`` and save the file.
+
+    Raises:
+        ConfigError: if the API key is unavailable.
+        ApiError: if the API refuses the download.
+        httpx.HTTPError: on a network failure.
+    """
+    settings = Settings(base_url=base_url, op_ref=op_ref, download_dir=output)
+    key = read_secret_key(op_ref)
+    with httpx.Client(timeout=30, follow_redirects=True) as client:
+        fd = fast_download(client, settings, md5, key, path_index, domain_index)
+        if left := fd.info.get("downloads_left"):
+            console.print(f"[dim]Fast downloads left today: {left}/25[/]")
+        return download_file(client, fd.url, output, fallback_name or f"{md5}.bin")
+
+
+def _offer_download(
+    books: list[Book], *, output: Path, base_url: str, op_ref: str
+) -> None:
+    """Ask whether to download a result and, if so, which one, then fetch it."""
+    try:
+        if not Confirm.ask(
+            "\nWould you like to download one of these results?",
+            console=console,
+            default=False,
+        ):
+            return
+        number = IntPrompt.ask(
+            f"Which result? [dim](1-{len(books)})[/]",
+            console=console,
+            choices=[str(i) for i in range(1, len(books) + 1)],
+            show_choices=False,
+        )
+    except EOFError:  # stdin closed mid-prompt: treat as "no"
+        return
+    book = books[number - 1]
+    ext = book.record.extension if book.record and book.record.extension else "bin"
+    console.print(f"Downloading [bold]{escape(book.title)}[/]…")
+    try:
+        path = _download_md5(
+            book.md5,
+            output=output,
+            base_url=base_url,
+            op_ref=op_ref,
+            fallback_name=f"{book.md5}.{ext}",
+        )
+    except (ConfigError, ApiError, httpx.HTTPError) as exc:
+        raise _fail(str(exc)) from exc
+    console.print(f"[b i #00ff00]Saved[/] [b #af00ff]{escape(str(path))}[/]")
+
+
+def format_ext(ext: str | None) -> RichText:
+    """Style the format of the book's extension.
+    Args:
+        ext (str | None): The file extension.
+    Returns:
+        RichText: The styled extension text.
+    """
+    if not ext:
+        return RichText("Unknown", style="dim")
+    _ext: str = ext.upper()
+    styles = {
+        "EPUB": "bold #99ff00",
+        "PDF": "bold #ff0000",
+        "MOBI": "bold #69C3FF",
+        "FB2": "bold #0000ff",
+        "TXT": "bold #FFFF00",
+    }
+    if _ext in styles:
+        return RichText(_ext, style=styles[_ext])
+    return RichText(_ext, style="none")
+
+
+_UNIT_STYLES = {
+    "B": "#999999",
+    "KB": "#69C3FF",
+    "MB": "#99ff00",
+    "GB": "#ff9900",
+    "TB": "#ff0055",
+}
+
+
+def format_size(size: str | None) -> RichText:
+    """Style a size such as ``9.8MB``: the number bold white, the unit coloured.
+
+    The unit colour grows warmer with magnitude (KB blue, MB green, GB orange).
+    Unparseable or missing sizes render as a dim dash.
+
+    Args:
+        size (str | None): Size text like ``600.0KB``.
+    Returns:
+        RichText: ``<number> <unit>`` with each part in its own style.
+    """
+    match = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*([A-Za-z]+)\s*", size or "")
+    if not match:
+        return RichText("-", style="dim")
+    number, unit = match.group(1), match.group(2).upper()
+    # Plain rich Text: rich_gradient's Text would rainbow-colour the number.
+    text = RichText(number, style="bold #ffffff")
+    text.append(f" {unit}", style=f"bold {_UNIT_STYLES.get(unit, '#C2C2C2')}")
+    return text
+
+
+# Header gradient, left to right: each column's start picks up where the previous
+# column's end left off, so the headers read as one rainbow across the table.
+_HEADER_GRADIENT: list[tuple[str, str, str]] = [
+    ("Extension", "#ff9900", "#ffcc00"),
+    ("Title", "#ffff00", "#00ff00"),
+    ("Author", "#00ff99", "#00ffff"),
+    ("Size", "#00ddff", "#00aaff"),
+    ("Language", "#0099ff", "#3380ff"),
+    ("Year", "#5066ff", "#8055ff"),
+    ("MD5", "#a044ff", "#ff00ff"),
+]
+
+
+def _header(label: str, start: str, end: str) -> Text:
+    """Return a bold gradient column header running from ``start`` to ``end``."""
+    return Text(text=f"[b]{label}[/]", colors=[start, end])
+
+
+def _plain(value: str) -> RichText:
+    """Return ``value`` in a neutral light grey, or a dim dash when empty."""
+    return RichText(value, style="#C2C2C2") if value else RichText("-", style="dim")
+
+
+# Minimum content width of each column; used to decide what fits. Title and
+# Author need a few characters to stay readable, the MD5 must never be cut.
+_MIN_WIDTH = {
+    "#": 2,
+    "Extension": 9,
+    "Title": 16,
+    "Author": 14,
+    "Size": 8,
+    "Language": 8,
+    "Year": 4,
+    "MD5": 32,
+}
+# Columns dropped first when the terminal is too narrow, least important first.
+_DROP_ORDER = ["Year", "Language", "Size", "Extension"]
+
+
+def _visible_columns(width: int | None) -> list[str]:
+    """Return the column names that fit in ``width`` (all of them if ``None``).
+
+    Each column costs its content width plus 3 (padding and one border); the table
+    has one more border on the left. Columns are dropped in ``_DROP_ORDER`` until
+    the rest fit; Title, Author and MD5 are always kept.
+    """
+    shown = list(_MIN_WIDTH)
+    for name in _DROP_ORDER:
+        if width is None or 1 + sum(_MIN_WIDTH[c] + 3 for c in shown) <= width:
+            break
+        shown.remove(name)
+    return shown
+
+
+def _results_table(books: list[Book], width: int | None = None) -> Table:
+    """Build the search results table: one row per book, full MD5 last.
+
+    ``width`` is the terminal width; on narrow terminals the least important
+    columns (Year, Language, Size, Extension) are left out rather than squeezing
+    Title and Author to a few characters. Title and author fold onto extra lines
+    when space is tight, so the MD5 (which must stay copy-pasteable) is never
+    truncated.
+    """
+    show = _visible_columns(width)
+    table = Table(
+        title=Text("Search Results", rainbow=True, style="bold"),
+        title_justify="center",
+        caption=f"{len(books)} result{'s' if len(books) != 1 else ''}",
+        box=ROUNDED,
+        row_styles=["on #2b2b2b", "on #444444"],
+        title_style="bold",
+    )
+    gradient = {
+        label: _header(label, start, end) for label, start, end in _HEADER_GRADIENT
+    }
+    table.add_column("[b #ff0000]#[/]", style="dim italic", justify="center")
+    if "Extension" in show:
+        table.add_column(
+            gradient["Extension"], justify="center", overflow="ignore", style="bold"
+        )
+    table.add_column(gradient["Title"], overflow="fold", style="bold #ffffff")
+    table.add_column(gradient["Author"], ratio=2, overflow="fold")
+    if "Size" in show:
+        table.add_column(gradient["Size"], justify="center", no_wrap=True)
+    if "Language" in show:
+        table.add_column(gradient["Language"], justify="center", no_wrap=True)
+    if "Year" in show:
+        table.add_column(gradient["Year"], justify="center", no_wrap=True)
+    table.add_column(gradient["MD5"], style="#00ccff", no_wrap=True, min_width=32)
+    authors = format_authors([r.author if (r := b.record) else b.meta for b in books])
+    for i, (b, author) in enumerate(zip(books, authors, strict=True), 1):
+        r = b.record  # bare links have no record, only raw text in ``meta``
+        cells: dict[str, RichText | str] = {
+            "#": str(i),
+            "Extension": format_ext(r.extension if r else None),
+            "Title": f"[bold #ffffff]{escape(b.title)}",
+            "Author": author,
+            "Size": format_size(r.size_text if r else None),
+            "Language": _plain(r.language if r else ""),
+            "Year": _plain(str(r.year) if r and r.year else ""),
+            "MD5": b.md5,
+        }
+        table.add_row(*(cells[name] for name in _MIN_WIDTH if name in show))
+    return table
+
+
+def _print_record(rec: BookRecord) -> None:
+    """Render a detailed record as rich tables."""
+    summary = Table(show_header=False, box=ROUNDED, title=escape(rec.title))
+    summary.add_column(style="bold #C2C2C2")
+    summary.add_column(overflow="fold")
+    rows = {
+        "Author": rec.author,
+        "Publisher": rec.publisher,
+        "Series": f"{rec.series} #{rec.series_index}" if rec.series else "",
+        "Year": str(rec.year or ""),
+        "Language": ", ".join(rec.languages),
+        "Format": f"{rec.extension} · {rec.size_text}" if rec.extension else "",
+        "Type": rec.content_type,
+        "Sources": ", ".join(rec.sources),
+        "MD5": rec.md5,
+        "File": rec.filename,
+        "Cover": rec.cover_url,
+    }
+    for label, value in rows.items():
+        if value:
+            summary.add_row(label, escape(value))
+    console.print(summary)
+    if rec.identifiers:
+        ids = Table(show_header=False, box=ROUNDED, title="Identifiers")
+        ids.add_column(style="bold #C2C2C2")
+        ids.add_column(overflow="fold")
+        for key, values in rec.identifiers.items():
+            ids.add_row(key, escape(", ".join(values)))
+        console.print(ids)
+    if rec.description:
+        console.print(f"\n[dim]{escape(rec.description[:600])}[/]")
+
+
+@app.command()
+def info(
+    md5: Annotated[str, typer.Argument(help="MD5 hash of the record.")],
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Print the full record as JSON.")
+    ] = False,
+    base_url: BaseUrl = DEFAULT_BASE_URL,
+    cookie: Cookie = None,
+    browser: BrowserOpt = "chrome",
+    refresh: Annotated[
+        bool, typer.Option(help="Re-read browser cookies on a 403 and retry.")
+    ] = True,
+) -> None:
+    """Show everything parsed from a record's details page."""
+    try:
+        with _busy(f"Fetching [bold]{md5}[/]…") as status:
+            rec = _with_cookies(
+                lambda c, s: fetch_details(c, s, md5),
+                base_url,
+                cookie,
+                browser,
+                refresh,
+                status,
+            )
+    except (SearchError, CookieError, httpx.HTTPError) as exc:
+        raise _fail(str(exc)) from exc
+    if as_json:
+        typer.echo(json.dumps(rec.to_dict(), ensure_ascii=False, indent=2))
+    else:
+        _print_record(rec)
+
+
+@app.command()
+def cookies(
+    browser: BrowserOpt = "chrome",
+    base_url: BaseUrl = DEFAULT_BASE_URL,
+) -> None:
+    """Refresh cookies.sh from your browser's signed-in session."""
+    settings = Settings(base_url=base_url)
+    try:
+        with httpx.Client(timeout=30, follow_redirects=True) as client:
+            refresh_cookies(client, settings, browser)
+    except (CookieError, httpx.HTTPError) as exc:
+        raise _fail(str(exc)) from exc
+    console.print("[green]Cookies refreshed.[/]")
+
+
+@app.command()
+def download(
+    md5: Annotated[str, typer.Argument(help="MD5 hash of the file.")],
+    output: Annotated[
+        Path, typer.Option("--output", "-o", help="Destination directory.")
+    ] = Path("downloads"),
+    path_index: Annotated[int | None, typer.Option(help="Collection index.")] = None,
+    domain_index: Annotated[
+        int | None, typer.Option(help="Download server index.")
+    ] = None,
+    base_url: BaseUrl = DEFAULT_BASE_URL,
+    op_ref: OpRef = DEFAULT_OP_REF,
+) -> None:
+    """Download a book by MD5 using the member fast-download API."""
+    try:
+        path = _download_md5(
+            md5,
+            output=output,
+            base_url=base_url,
+            op_ref=op_ref,
+            path_index=path_index,
+            domain_index=domain_index,
+        )
+    except (ConfigError, ApiError, httpx.HTTPError) as exc:
+        raise _fail(str(exc)) from exc
+    console.print(f"[b i #00ff00]Saved[/] [b #af00ff]{escape(str(path))}[/]")
+
+
+if __name__ == "__main__":
+    app()