zotcli 0.1.0__py3-none-any.whl

zotcli/__init__.py

@@ -0,0 +1,3 @@
+"""zotcli — A read-only CLI for browsing and exporting a Zotero library."""
+
+__version__ = "0.1.0"

zotcli/__main__.py

@@ -0,0 +1,4 @@
+from zotcli.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

zotcli/cli/attachments.py

@@ -0,0 +1,125 @@
+"""CLI — `zot attachments` subcommands."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import click
+from rich.table import Table
+
+from zotcli.cli.main import pass_ctx, Context
+from zotcli.cli.render import make_console
+from zotcli.models import Attachment
+from zotcli.queries.attachments import enrich_attachment_paths
+from zotcli.queries.items import get_item
+
+
+@click.group()
+def attachments():
+    """Browse and open Zotero attachments."""
+
+
+@attachments.command("list")
+@click.option("--missing", is_flag=True, help="Only show missing files")
+@click.option("--type", "content_type", default=None, help="Filter by content type (e.g. pdf)")
+@pass_ctx
+def list_attachments(ctx: Context, missing: bool, content_type: str | None):
+    """List all attachments."""
+    console = make_console(ctx.color)
+    data_dir = ctx.db.path.parent
+
+    rows = ctx.db.fetchall(
+        """
+        SELECT i.itemID, i.key, ia.parentItemID, ia.linkMode,
+               ia.contentType, ia.path
+        FROM itemAttachments ia
+        JOIN items i ON ia.itemID = i.itemID
+        WHERE ia.parentItemID IS NOT NULL
+        ORDER BY ia.contentType
+        """
+    )
+
+    atts = [
+        Attachment(
+            item_id=r["itemID"],
+            key=r["key"],
+            parent_item_id=r["parentItemID"],
+            link_mode=r["linkMode"] if r["linkMode"] is not None else 0,
+            content_type=r["contentType"] or "",
+            path=r["path"],
+        )
+        for r in rows
+    ]
+    enrich_attachment_paths(atts, data_dir)
+
+    if content_type:
+        atts = [a for a in atts if content_type.lower() in a.content_type.lower()]
+    if missing:
+        atts = [a for a in atts if not a.file_exists]
+
+    if not atts:
+        console.print("[dim]No attachments found.[/dim]")
+        return
+
+    t = Table(title=f"{len(atts)} attachments")
+    t.add_column("Key", style="cyan", width=10)
+    t.add_column("Type", width=20)
+    t.add_column("Mode", width=14)
+    t.add_column("Exists", width=7)
+    t.add_column("Path")
+
+    for att in atts[:500]:
+        exists = "[green]✓[/green]" if att.file_exists else "[red]✗[/red]"
+        path_str = str(att.absolute_path) if att.absolute_path else att.path or ""
+        t.add_row(att.key, att.content_type, att.link_mode_name, exists, path_str[:80])
+    console.print(t)
+    if len(atts) > 500:
+        console.print(f"[dim]... and {len(atts) - 500} more[/dim]")
+
+
+@attachments.command("path")
+@click.argument("id_or_key")
+@pass_ctx
+def attachment_path(ctx: Context, id_or_key: str):
+    """Print the resolved absolute path(s) for an item's attachments."""
+    item_id_val = int(id_or_key) if id_or_key.isdigit() else id_or_key
+    item = get_item(ctx.db, item_id_val)
+    if item is None:
+        raise click.ClickException(f"Item not found: {id_or_key!r}")
+
+    for att in item.attachments:
+        if att.absolute_path:
+            click.echo(str(att.absolute_path))
+
+
+@attachments.command("open")
+@click.argument("id_or_key")
+@pass_ctx
+def open_attachment(ctx: Context, id_or_key: str):
+    """Open the first attachment with the system default application."""
+    item_id_val = int(id_or_key) if id_or_key.isdigit() else id_or_key
+    item = get_item(ctx.db, item_id_val)
+    if item is None:
+        raise click.ClickException(f"Item not found: {id_or_key!r}")
+
+    existing = [a for a in item.attachments if a.file_exists and a.absolute_path]
+    if not existing:
+        raise click.ClickException("No local files found for this item.")
+
+    path = existing[0].absolute_path
+    click.echo(f"Opening: {path}")
+
+    if sys.platform == "win32":
+        import os
+        os.startfile(str(path))
+    elif sys.platform == "darwin":
+        subprocess.run(["open", str(path)])
+    else:
+        opener = "wslview" if _which("wslview") else "xdg-open"
+        subprocess.run([opener, str(path)])
+
+
+def _which(cmd: str) -> bool:
+    import shutil
+    return shutil.which(cmd) is not None

zotcli/cli/collections.py

@@ -0,0 +1,100 @@
+"""CLI — `zot collections` subcommands."""
+
+from __future__ import annotations
+
+import click
+from rich.table import Table
+
+from zotcli.cli.main import pass_ctx, Context
+from zotcli.cli.render import make_console, collection_tree, items_table
+from zotcli.queries.collections import (
+    get_all_collections,
+    get_collection_tree,
+    get_collection_by_id,
+    get_collection_by_name,
+    get_items_in_collection,
+)
+
+
+@click.group()
+def collections():
+    """Browse Zotero collections."""
+
+
+@collections.command("list")
+@click.option("--flat", is_flag=True, help="Flat list with IDs instead of tree view")
+@pass_ctx
+def list_collections(ctx: Context, flat: bool):
+    """Print the collection tree."""
+    console = make_console(ctx.color)
+    if flat:
+        cols = get_all_collections(ctx.db, ctx.library_id)
+        t = Table(show_header=True)
+        t.add_column("ID", style="dim", width=8)
+        t.add_column("Key", style="cyan", width=10)
+        t.add_column("Name")
+        t.add_column("Parent", width=8)
+        t.add_column("Items", width=7)
+        for c in cols:
+            t.add_row(
+                str(c.collection_id),
+                c.key,
+                c.name,
+                str(c.parent_collection_id or ""),
+                str(c.item_count),
+            )
+        console.print(t)
+    else:
+        roots = get_collection_tree(ctx.db, ctx.library_id)
+        tree = collection_tree(roots)
+        console.print(tree)
+
+
+@collections.command("show")
+@click.argument("id_or_name")
+@pass_ctx
+def show_collection(ctx: Context, id_or_name: str):
+    """Show details for a collection."""
+    console = make_console(ctx.color)
+    col = _resolve_collection(ctx, id_or_name)
+    if col is None:
+        raise click.ClickException(f"Collection not found: {id_or_name!r}")
+    console.print(f"[bold]{col.name}[/bold]  ID={col.collection_id}  Key={col.key}")
+    console.print(f"Parent: {col.parent_collection_id or '(root)'}")
+    console.print(f"Items: {col.item_count}")
+
+
+@collections.command("items")
+@click.argument("id_or_name")
+@click.option("--recursive", "-r", is_flag=True, help="Include sub-collections")
+@click.option("--type", "item_type", default=None, help="Filter to item type (e.g. journalArticle)")
+@pass_ctx
+def collection_items(ctx: Context, id_or_name: str, recursive: bool, item_type: str | None):
+    """List items in a collection."""
+    console = make_console(ctx.color)
+    col = _resolve_collection(ctx, id_or_name)
+    if col is None:
+        raise click.ClickException(f"Collection not found: {id_or_name!r}")
+
+    items = get_items_in_collection(ctx.db, col.collection_id, recursive=recursive)
+    if item_type:
+        items = [i for i in items if i.item_type.lower() == item_type.lower()]
+
+    if not items:
+        console.print(f"[dim]No items in collection {col.name!r}[/dim]")
+        return
+
+    t = items_table(items, title=f"{col.name} ({len(items)} items)")
+    console.print(t)
+
+
+def _resolve_collection(ctx: Context, id_or_name: str):
+    """Resolve a collection ID (int) or name (str)."""
+    from zotcli.queries.collections import get_collection_by_id, get_collection_by_name
+
+    if id_or_name.isdigit():
+        return get_collection_by_id(ctx.db, int(id_or_name))
+    matches = get_collection_by_name(ctx.db, id_or_name, fuzzy=False)
+    if not matches:
+        matches = get_collection_by_name(ctx.db, id_or_name, fuzzy=True)
+    return matches[0] if matches else None

zotcli/cli/export.py

@@ -0,0 +1,111 @@
+"""CLI — `zot export` subcommands."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from zotcli.cli.main import pass_ctx, Context
+from zotcli.cli.render import make_console
+from zotcli.queries.items import get_items
+from zotcli.queries.collections import get_collection_by_name, get_collection_by_id, get_items_in_collection
+
+
+def _get_items(ctx: Context, collection: str | None, all_items: bool) -> tuple[list, object | None]:
+    """Return (items, collection_obj|None)."""
+    if collection:
+        if collection.isdigit():
+            col = get_collection_by_id(ctx.db, int(collection))
+        else:
+            matches = get_collection_by_name(ctx.db, collection, fuzzy=True)
+            col = matches[0] if matches else None
+        if col is None:
+            raise click.ClickException(f"Collection not found: {collection!r}")
+        return get_items_in_collection(ctx.db, col.collection_id), col
+    if all_items:
+        return get_items(ctx.db, library_id=ctx.library_id), None
+    raise click.UsageError("Provide --collection NAME or --all.")
+
+
+@click.group("export")
+def export():
+    """Export items to various formats."""
+
+
+@export.command("json")
+@click.option("--collection", "-c", default=None, help="Export a specific collection")
+@click.option("--all", "all_items", is_flag=True, help="Export entire library")
+@click.option("--output", "-o", default=None, help="Output file (default: stdout)")
+@pass_ctx
+def export_json(ctx: Context, collection: str | None, all_items: bool, output: str | None):
+    """Export items as JSON."""
+    from zotcli.export.json_ import items_to_json
+    items, _ = _get_items(ctx, collection, all_items)
+    fp = open(output, "w", encoding="utf-8") if output else sys.stdout
+    try:
+        items_to_json(items, fp)
+        if output:
+            make_console(ctx.color).print(f"[green]Exported {len(items)} items to {output}[/green]")
+    finally:
+        if output:
+            fp.close()
+
+
+@export.command("csv")
+@click.option("--collection", "-c", default=None)
+@click.option("--all", "all_items", is_flag=True)
+@click.option("--output", "-o", default=None)
+@pass_ctx
+def export_csv(ctx: Context, collection: str | None, all_items: bool, output: str | None):
+    """Export items as CSV."""
+    from zotcli.export.csv_ import items_to_csv
+    items, _ = _get_items(ctx, collection, all_items)
+    fp = open(output, "w", newline="", encoding="utf-8") if output else sys.stdout
+    try:
+        items_to_csv(items, fp)
+        if output:
+            make_console(ctx.color).print(f"[green]Exported {len(items)} items to {output}[/green]")
+    finally:
+        if output:
+            fp.close()
+
+
+@export.command("bib")
+@click.option("--collection", "-c", default=None)
+@click.option("--all", "all_items", is_flag=True)
+@click.option("--output", "-o", default=None)
+@pass_ctx
+def export_bib(ctx: Context, collection: str | None, all_items: bool, output: str | None):
+    """Export items as BibTeX."""
+    from zotcli.export.bibtex import items_to_bibtex
+    items, _ = _get_items(ctx, collection, all_items)
+    fp = open(output, "w", encoding="utf-8") if output else sys.stdout
+    try:
+        items_to_bibtex(items, fp)
+        if output:
+            make_console(ctx.color).print(f"[green]Exported {len(items)} items to {output}[/green]")
+    finally:
+        if output:
+            fp.close()
+
+
+@export.command("markdown")
+@click.option("--collection", "-c", default=None)
+@click.option("--all", "all_items", is_flag=True)
+@click.option("--output", "-o", default=None)
+@click.option("--notes", is_flag=True, help="Include notes sections")
+@pass_ctx
+def export_markdown(ctx: Context, collection: str | None, all_items: bool, output: str | None, notes: bool):
+    """Export items as a Markdown report."""
+    from zotcli.export.markdown import items_to_markdown
+    items, col = _get_items(ctx, collection, all_items)
+    fp = open(output, "w", encoding="utf-8") if output else sys.stdout
+    try:
+        items_to_markdown(items, collection=col, include_notes=notes, fp=fp)
+        if output:
+            make_console(ctx.color).print(f"[green]Exported {len(items)} items to {output}[/green]")
+    finally:
+        if output:
+            fp.close()

zotcli/cli/items.py

@@ -0,0 +1,111 @@
+"""CLI — `zot items` subcommands."""
+
+from __future__ import annotations
+
+import click
+from rich.panel import Panel
+from rich.table import Table
+
+from zotcli.cli.main import pass_ctx, Context
+from zotcli.cli.render import make_console, item_panel, items_table
+from zotcli.queries.items import get_items, get_item
+from zotcli.queries.collections import get_collection_by_name, get_items_in_collection
+
+
+@click.group()
+def items():
+    """Browse Zotero items."""
+
+
+@items.command("list")
+@click.option("--type", "item_type", default=None, help="Filter by item type")
+@click.option("--collection", "col_name", default=None, help="Filter by collection name/ID")
+@click.option("--limit", default=50, show_default=True, help="Max items to show")
+@pass_ctx
+def list_items(ctx: Context, item_type: str | None, col_name: str | None, limit: int):
+    """List items (paginated)."""
+    console = make_console(ctx.color)
+
+    if col_name:
+        if col_name.isdigit():
+            from zotcli.queries.collections import get_collection_by_id
+            col = get_collection_by_id(ctx.db, int(col_name))
+        else:
+            matches = get_collection_by_name(ctx.db, col_name, fuzzy=True)
+            col = matches[0] if matches else None
+        if col is None:
+            raise click.ClickException(f"Collection not found: {col_name!r}")
+        result = get_items_in_collection(ctx.db, col.collection_id)
+        if item_type:
+            result = [i for i in result if i.item_type.lower() == item_type.lower()]
+        result = result[:limit]
+        title = f"{col.name} — {len(result)} items"
+    else:
+        result = get_items(ctx.db, library_id=ctx.library_id, item_type=item_type, limit=limit)
+        title = f"{len(result)} items"
+
+    if not result:
+        console.print("[dim]No items found.[/dim]")
+        return
+    console.print(items_table(result, title=title))
+
+
+@items.command("show")
+@click.argument("id_or_key")
+@pass_ctx
+def show_item(ctx: Context, id_or_key: str):
+    """Show full details for an item."""
+    console = make_console(ctx.color)
+    item_id = int(id_or_key) if id_or_key.isdigit() else id_or_key
+    item = get_item(ctx.db, item_id)
+    if item is None:
+        raise click.ClickException(f"Item not found: {id_or_key!r}")
+    # attachments and notes already populated by _build_items
+    console.print(item_panel(item))
+
+
+@items.command("attachments")
+@click.argument("id_or_key")
+@pass_ctx
+def item_attachments(ctx: Context, id_or_key: str):
+    """List attachments for an item."""
+    console = make_console(ctx.color)
+    item_id_val = int(id_or_key) if id_or_key.isdigit() else id_or_key
+    item = get_item(ctx.db, item_id_val)
+    if item is None:
+        raise click.ClickException(f"Item not found: {id_or_key!r}")
+
+    if not item.attachments:
+        console.print("[dim]No attachments.[/dim]")
+        return
+
+    t = Table(title=f"Attachments for {item.key}")
+    t.add_column("Key", style="cyan")
+    t.add_column("Type")
+    t.add_column("Mode")
+    t.add_column("Exists")
+    t.add_column("Path")
+    for att in item.attachments:
+        exists = "[green]✓[/green]" if att.file_exists else "[red]✗[/red]"
+        path_str = str(att.absolute_path) if att.absolute_path else att.path or ""
+        t.add_row(att.key, att.content_type, att.link_mode_name, exists, path_str[:80])
+    console.print(t)
+
+
+@items.command("notes")
+@click.argument("id_or_key")
+@pass_ctx
+def item_notes(ctx: Context, id_or_key: str):
+    """Show notes attached to an item."""
+    console = make_console(ctx.color)
+    item_id_val = int(id_or_key) if id_or_key.isdigit() else id_or_key
+    item = get_item(ctx.db, item_id_val)
+    if item is None:
+        raise click.ClickException(f"Item not found: {id_or_key!r}")
+
+    if not item.notes:
+        console.print("[dim]No notes.[/dim]")
+        return
+
+    for note in item.notes:
+        console.print(Panel(note.plain_text[:2000], title=note.title or "Note"))

zotcli/cli/main.py

@@ -0,0 +1,71 @@
+"""Root Click group and shared context."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+import click
+
+from zotcli.db import ZoteroDatabase, discover_db
+from zotcli.config import get_db_path, get_library_id
+
+
+class Context:
+    def __init__(self, db: ZoteroDatabase, library_id: int, fmt: str, color: bool):
+        self.db = db
+        self.library_id = library_id
+        self.fmt = fmt
+        self.color = color
+
+
+pass_ctx = click.make_pass_decorator(Context)
+
+
+@click.group()
+@click.option("--db", "db_path", default=None, help="Path to zotero.sqlite")
+@click.option("--library", "library_id", default=None, type=int, help="Library ID (default: 1)")
+@click.option(
+    "--format",
+    "fmt",
+    default="table",
+    type=click.Choice(["table", "json", "csv"]),
+    help="Output format",
+)
+@click.option("--no-color", is_flag=True, default=False, help="Disable colour output")
+@click.pass_context
+def cli(ctx: click.Context, db_path: str | None, library_id: int | None, fmt: str, no_color: bool):
+    """zot — read-only CLI for your Zotero library."""
+    resolved_path = get_db_path(db_path)
+    if resolved_path is None:
+        try:
+            resolved_path = discover_db()
+        except FileNotFoundError as e:
+            raise click.ClickException(str(e))
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        db = ZoteroDatabase(resolved_path, warn_if_open=True)
+
+    for w in caught:
+        click.echo(f"[warning] {w.message}", err=True)
+
+    lib_id = get_library_id(library_id)
+    ctx.obj = Context(db=db, library_id=lib_id, fmt=fmt, color=not no_color)
+    ctx.call_on_close(db.close)
+
+
+# Import and register subcommand groups
+from zotcli.cli import collections as _col_mod  # noqa: E402
+from zotcli.cli import items as _items_mod  # noqa: E402
+from zotcli.cli import attachments as _att_mod  # noqa: E402
+from zotcli.cli import search as _search_mod  # noqa: E402
+from zotcli.cli import stats as _stats_mod  # noqa: E402
+from zotcli.cli import export as _export_mod  # noqa: E402
+
+cli.add_command(_col_mod.collections)
+cli.add_command(_items_mod.items)
+cli.add_command(_att_mod.attachments)
+cli.add_command(_search_mod.search)
+cli.add_command(_stats_mod.stats)
+cli.add_command(_export_mod.export)

zotcli/cli/render.py

@@ -0,0 +1,93 @@
+"""Shared Rich rendering helpers."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.tree import Tree
+
+from zotcli.models import Collection, Item
+
+
+def make_console(color: bool = True, width: int = 160) -> Console:
+    return (
+        Console(highlight=False, markup=True, width=width)
+        if color
+        else Console(highlight=False, no_color=True, width=width)
+    )
+
+
+def items_table(items: list[Item], title: str = "Items") -> Table:
+    t = Table(title=title, show_lines=False, highlight=False)
+    t.add_column("#", style="dim", no_wrap=True, width=6)
+    t.add_column("Key", style="cyan", no_wrap=True, width=9)
+    t.add_column("Type", style="magenta", no_wrap=True, width=18)
+    t.add_column("Title")
+    t.add_column("Authors", width=24)
+    t.add_column("Year", width=6)
+
+    for i, item in enumerate(items, start=1):
+        t.add_row(
+            str(i),
+            item.key,
+            item.item_type,
+            item.title[:80],
+            item.authors_short,
+            item.year or "",
+        )
+    return t
+
+
+def item_panel(item: Item) -> Panel:
+    lines: list[str] = []
+    lines.append(f"[bold]Title[/bold]    {item.title}")
+    if item.authors:
+        lines.append(f"[bold]Authors[/bold]  {'; '.join(item.authors[:5])}")
+    if item.year:
+        lines.append(f"[bold]Year[/bold]     {item.year}")
+    if "publicationTitle" in item.fields:
+        lines.append(f"[bold]Journal[/bold]  {item.fields['publicationTitle']}")
+    if item.doi:
+        lines.append(f"[bold]DOI[/bold]      {item.doi}")
+    if item.tags:
+        tag_str = " ".join(f"[{t}]" for t in item.tags[:10])
+        lines.append(f"[bold]Tags[/bold]     {tag_str}")
+
+    for field, value in sorted(item.fields.items()):
+        if field in ("title", "DOI", "publicationTitle", "date", "citationKey"):
+            continue
+        if value:
+            lines.append(f"[dim]{field:12}[/dim] {value[:80]}")
+
+    if item.attachments:
+        lines.append("\n[bold]Attachments[/bold]")
+        for att in item.attachments:
+            icon = "[green]✓[/green]" if att.file_exists else "[red]✗[/red]"
+            name = att.filename or att.content_type or "?"
+            lines.append(f"  {icon} {name}  [dim]({att.link_mode_name})[/dim]")
+
+    if item.notes:
+        lines.append(f"\n[bold]Notes[/bold] ({len(item.notes)})")
+        for note in item.notes[:3]:
+            snippet = (note.plain_text or "")[:120].replace("\n", " ")
+            lines.append(f"  • {snippet}")
+
+    body = "\n".join(lines)
+    return Panel(
+        body,
+        title=f"[bold cyan]{item.item_type}[/bold cyan] [dim]#{item.item_id}[/dim]  [bold]{item.key}[/bold]",
+        expand=False,
+    )
+
+
+def collection_tree(roots: list[Collection], tree: Tree | None = None) -> Tree:
+    if tree is None:
+        tree = Tree("[bold blue]Collections[/bold blue]")
+    for col in roots:
+        label = f"[green]{col.name}[/green] [dim]({col.item_count})[/dim]"
+        branch = tree.add(label)
+        if col.children:
+            collection_tree(col.children, branch)
+    return tree