bookery-cli 2026.10.1__py3-none-any.whl

bookery/__init__.py

@@ -0,0 +1,6 @@
+# ABOUTME: Bookery - a CLI-first ebook library manager inspired by beets.
+# ABOUTME: Package root. Exposes version info.
+
+from importlib.metadata import version
+
+__version__ = version("bookery-cli")

bookery/__main__.py

@@ -0,0 +1,7 @@
+# ABOUTME: Entry point for `python -m bookery` invocation.
+# ABOUTME: Delegates to the Click CLI group.
+
+from bookery.cli import cli
+
+if __name__ == "__main__":
+    cli()

bookery/cli/__init__.py

@@ -0,0 +1,95 @@
+# ABOUTME: CLI package for Bookery, built on Click.
+# ABOUTME: Defines the root command group and registers subcommands.
+
+import logging
+from pathlib import Path
+
+import click
+
+from bookery.cli.commands import (
+    add_cmd,
+    authors_cmd,
+    collection_cmd,
+    convert_cmd,
+    genre_cmd,
+    info_cmd,
+    inventory_cmd,
+    ls_cmd,
+    mark_cmd,
+    match_cmd,
+    prune_cmd,
+    rematch_cmd,
+    remove_cmd,
+    reveal_cmd,
+    search_cmd,
+    series_cmd,
+    serve_cmd,
+    sync_cmd,
+    tag_cmd,
+    vault_export_cmd,
+    verify_cmd,
+)
+from bookery.cli.deprecation import deprecated_command_alias
+
+
+@click.group()
+@click.version_option(package_name="bookery-cli")
+@click.option("-v", "--verbose", count=True, help="Increase verbosity (-v info, -vv debug).")
+@click.option(
+    "--db",
+    "db_path",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Path to library database. Subcommand --db overrides this.",
+)
+@click.pass_context
+def cli(ctx: click.Context, verbose: int, db_path: Path | None) -> None:
+    """Bookery - a CLI-first ebook library manager."""
+    ctx.ensure_object(dict)
+    if db_path is not None:
+        ctx.obj["db_path"] = db_path
+    if verbose >= 2:
+        level = logging.DEBUG
+    elif verbose >= 1:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(name)s %(levelname)s: %(message)s",
+    )
+
+
+cli.add_command(add_cmd.add_command)
+cli.add_command(authors_cmd.authors)
+cli.add_command(collection_cmd.collections)
+cli.add_command(convert_cmd.convert)
+cli.add_command(genre_cmd.genre)
+cli.add_command(info_cmd.info)
+cli.add_command(inventory_cmd.inventory)
+cli.add_command(ls_cmd.ls)
+cli.add_command(mark_cmd.mark)
+cli.add_command(match_cmd.match)
+cli.add_command(prune_cmd.prune)
+cli.add_command(rematch_cmd.rematch)
+cli.add_command(remove_cmd.remove)
+cli.add_command(reveal_cmd.reveal)
+cli.add_command(search_cmd.search)
+cli.add_command(series_cmd.series)
+cli.add_command(serve_cmd.serve)
+cli.add_command(sync_cmd.sync)
+cli.add_command(tag_cmd.tag)
+cli.add_command(vault_export_cmd.vault_export)
+cli.add_command(verify_cmd.verify)
+
+# Deprecated alias for the old `folder` command name. Remove after one release.
+deprecated_command_alias(cli, alias="folder", canonical="reveal")
+
+# Deprecated alias for the old `import` command name. Unified under `add`,
+# which now dispatches on file-vs-directory paths. Remove after one release.
+deprecated_command_alias(cli, alias="import", canonical="add")
+
+# Deprecated alias for the old `inspect` command name. Unified under `info`,
+# which now dispatches on cataloged-ID vs path-to-loose-file. Remove after
+# one release.
+deprecated_command_alias(cli, alias="inspect", canonical="info")

bookery/cli/_dispatch.py

@@ -0,0 +1,42 @@
+# ABOUTME: Detects source book format (epub / kindle / pdf) by suffix + magic bytes.
+# ABOUTME: Used by add and import commands to route non-EPUB inputs through converters.
+
+from pathlib import Path
+from typing import Literal
+
+SourceFormat = Literal["epub", "mobi", "pdf"]
+
+# Kindle containers that KindleUnpack reads; all route through the MOBI pipeline.
+KINDLE_SUFFIXES = frozenset({".mobi", ".azw", ".azw3"})
+
+
+class UnknownFormatError(ValueError):
+    """Raised when a file's extension and magic bytes don't match a supported format."""
+
+
+def detect_source_format(path: Path) -> SourceFormat:
+    """Return the file's format based on suffix + small magic-byte sanity check."""
+    suffix = path.suffix.lower()
+    if suffix == ".epub":
+        return "epub"
+    if suffix in KINDLE_SUFFIXES:
+        return "mobi"
+    if suffix == ".pdf":
+        try:
+            with path.open("rb") as fh:
+                head = fh.read(5)
+        except OSError as exc:
+            raise UnknownFormatError(f"cannot read {path}: {exc}") from exc
+        if not head.startswith(b"%PDF-"):
+            raise UnknownFormatError(f"{path.name} has a .pdf suffix but is not a PDF file.")
+        return "pdf"
+    raise UnknownFormatError(
+        f"{path.name}: unsupported format (expected .epub, .mobi, .azw, .azw3, or .pdf)."
+    )
+
+
+def find_kindle_files(directory: Path) -> list[Path]:
+    """Recursively find Kindle files (any suffix case) under a directory."""
+    return sorted(
+        p for p in directory.rglob("*") if p.is_file() and p.suffix.lower() in KINDLE_SUFFIXES
+    )

bookery/cli/_match_helpers.py

@@ -0,0 +1,201 @@
+# ABOUTME: Shared helpers for building match and progress callbacks.
+# ABOUTME: Used by both `import` and `add` commands so behavior stays in one place.
+
+from pathlib import Path
+
+from rich.console import Console
+
+from bookery.core.importer import ImportResult, MatchFn, MatchResult, ProgressFn
+from bookery.metadata.provider import MetadataProvider
+from bookery.metadata.types import BookMetadata
+
+
+def build_active_providers(*, use_cache: bool = True) -> dict[str, MetadataProvider]:
+    """Build a mapping of active MetadataProviders from configuration.
+
+    Reads ``[matching].providers`` and instantiates each listed provider in
+    priority order. Unknown names log a warning and are skipped. Falls back
+    to a single Open Library provider when nothing else is configured.
+
+    Each provider's HTTP client is wrapped in a :class:`CachingHttpClient`
+    when ``use_cache`` is true so repeated lookups (e.g. the web enrich
+    flow) hit the local cache.
+
+    Returns a dict keyed by provider name so callers can preserve order
+    and look providers up by key.
+    """
+    from bookery.core.config import get_data_dir, get_matching_config
+    from bookery.metadata.cache import MetadataCache
+    from bookery.metadata.http import BookeryHttpClient, CachingHttpClient
+    from bookery.metadata.registry import PROVIDER_FACTORIES, ProviderContext
+
+    matching = get_matching_config()
+    provider_names = matching.providers or ("openlibrary",)
+
+    cache: MetadataCache | None = None
+    if use_cache:
+        cache = MetadataCache(
+            get_data_dir() / "metadata_cache.db",
+            ttl_seconds=matching.cache_ttl_days * 86400.0,
+        )
+
+    def _http_for(provider_name: str):
+        # ponytail: one library-wide interval for every provider, not per-provider
+        # config — both providers want the same throttle today (#267).
+        client: object = BookeryHttpClient(min_request_interval=matching.min_request_interval)
+        if cache is not None:
+            client = CachingHttpClient(
+                client,  # type: ignore[arg-type]
+                cache,
+                provider=provider_name,
+            )
+        return client
+
+    ctx = ProviderContext(http_client_for=_http_for)
+
+    providers: dict[str, MetadataProvider] = {}
+    for name in provider_names:
+        factory = PROVIDER_FACTORIES.get(name)
+        if factory is None:
+            import logging
+
+            logging.getLogger(__name__).warning("Unknown metadata provider %r; skipping", name)
+            continue
+        providers[name] = factory(ctx)
+
+    if not providers:
+        providers["openlibrary"] = PROVIDER_FACTORIES["openlibrary"](ctx)
+
+    return providers
+
+
+def build_metadata_provider(*, use_cache: bool = True) -> MetadataProvider:
+    """Build the configured metadata provider with optional response caching.
+
+    Wraps :func:`build_active_providers` so legacy single-provider/consensus
+    behavior is preserved. A single active provider is returned directly;
+    multiple providers are wrapped in a :class:`ConsensusProvider` that
+    merges per-field values and prefers cross-provider agreement.
+    """
+    from bookery.metadata.consensus import ConsensusProvider
+
+    providers = list(build_active_providers(use_cache=use_cache).values())
+    if len(providers) == 1:
+        return providers[0]
+    return ConsensusProvider(providers)
+
+
+def build_match_fn(
+    console: Console,
+    output_dir: Path,
+    quiet: bool,
+    threshold: float,
+    *,
+    use_cache: bool = True,
+    fetch_covers: bool = True,
+) -> MatchFn:
+    """Build a match callback that runs the full metadata pipeline.
+
+    Imports match-pipeline dependencies lazily so callers don't pay for
+    them when matching is not used.
+    """
+    from bookery.cli.review import ReviewSession
+    from bookery.core.pipeline import match_one
+
+    provider = build_metadata_provider(use_cache=use_cache)
+    review = ReviewSession(
+        console=console,
+        quiet=quiet,
+        threshold=threshold,
+        lookup_fn=provider.lookup_by_url,
+    )
+
+    def match_fn(
+        _extracted: BookMetadata,
+        epub_path: Path,
+    ) -> MatchResult | None:
+        del _extracted  # signature required by MatchFn protocol
+        result = match_one(epub_path, provider, review, output_dir, fetch_covers=fetch_covers)
+
+        if result.cover_skipped:
+            console.print(
+                "  [yellow]warning:[/yellow] cover fetch failed; "
+                "applied text metadata without cover"
+            )
+
+        if not quiet and result.normalization and result.normalization.was_modified:
+            console.print(f"  [dim]Normalized:[/dim] {result.normalization.normalized.title}")
+
+        if result.status == "matched" and result.metadata is not None:
+            if not quiet:
+                console.print(f"  [green]Written:[/green] {result.output_path}")
+            return MatchResult(
+                metadata=result.metadata,
+                output_path=result.output_path,
+            )
+
+        if result.status == "error" and not quiet:
+            console.print(f"  [red]Write failed:[/red] {result.error}")
+
+        return None
+
+    return match_fn
+
+
+def build_progress_fn(console: Console) -> ProgressFn:
+    """Build a per-file progress callback for Rich console output."""
+
+    def on_progress(
+        path: Path,
+        title: str,
+        author: str,
+        status: str,
+        reason: str | None,
+        existing_id: int | None,
+    ) -> None:
+        label = f"{title} — {author}" if title and author else path.name
+        if status == "added":
+            console.print(f"  [green]✓[/green] {label}")
+        elif status == "skipped" and reason:
+            reason_label = reason.replace("_", "+")
+            id_suffix = f", #{existing_id}" if existing_id else ""
+            console.print(
+                f"  [yellow]⊘[/yellow] {label} — "
+                f"[dim]skipped (duplicate: {reason_label}{id_suffix})[/dim]"
+            )
+        elif status == "forced" and reason:
+            reason_label = reason.replace("_", "+")
+            id_suffix = f", #{existing_id}" if existing_id else ""
+            console.print(
+                f"  [yellow]⚠[/yellow] {label} — "
+                f"[dim]imported (duplicate: {reason_label}{id_suffix})[/dim]"
+            )
+        elif status == "error":
+            console.print(f"  [red]✗[/red] {path.name} — [red]{reason}[/red]")
+        elif status == "move_failed":
+            console.print(
+                f"  [yellow]⚠[/yellow] {path.name} — "
+                f"[dim]cataloged but source not removed: {reason}[/dim]"
+            )
+
+    return on_progress
+
+
+def format_skip_breakdown(result: ImportResult) -> str:
+    """Format a skip count with breakdown by reason."""
+    if result.skipped == 0:
+        return ""
+
+    parts = []
+    if result.skipped_hash:
+        parts.append(f"{result.skipped_hash} hash")
+    if result.skipped_metadata:
+        reason_counts: dict[str, int] = {}
+        for detail in result.skip_details:
+            if detail.reason in ("isbn", "title_author"):
+                label = detail.reason.replace("_", "+")
+                reason_counts[label] = reason_counts.get(label, 0) + 1
+        parts.extend(f"{count} {reason}" for reason, count in reason_counts.items())
+
+    breakdown = f" ({', '.join(parts)})" if parts else ""
+    return f"{result.skipped} skipped{breakdown}"

bookery/cli/_pdf_support.py

@@ -0,0 +1,21 @@
+# ABOUTME: Shared helper for wiring PDF conversion into add/import commands.
+# ABOUTME: Wraps convert_pdf and surfaces any warnings to the console.
+
+from pathlib import Path
+
+from rich.console import Console
+
+from bookery.core.pdf_converter import convert_pdf
+
+
+def convert_pdf_to_epub(
+    source: Path,
+    out_dir: Path,
+    *,
+    console: Console,
+) -> Path:
+    """Run the PDF→EPUB pipeline; return the produced EPUB path."""
+    result = convert_pdf(source, out_dir, console=console)
+    for warning in result.warnings:
+        console.print(f"  [yellow]warning:[/yellow] {warning}")
+    return result.epub_path

bookery/cli/commands/__init__.py

@@ -0,0 +1,2 @@
+# ABOUTME: CLI command modules for Bookery.
+# ABOUTME: Each module registers one or more Click commands.