zop-cli 0.2.0__py3-none-any.whl

zop/commands/export.py

@@ -0,0 +1,71 @@
+"""Export CLI: export items in BibTeX, CSL-JSON, RIS."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from zop.core.config import load_config
+from zop.core.envelope import emit, emit_error
+from zop.core.errors import ZopError
+from zop.services.export import ExportService
+
+
+def _service() -> ExportService:
+    cfg = load_config()
+    if not cfg.data_dir:
+        raise click.UsageError("data_dir not configured")
+    return ExportService(db_path=Path(cfg.data_dir) / "zotero.sqlite")
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.command(name="export")
+@click.argument("item_keys", nargs=-1, required=True)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["csl-json", "bibtex", "ris"]),
+    default="bibtex",
+)
+@click.option("--out", "-o", type=click.Path(), help="Write to file instead of stdout.")
+def export_cmd(
+    item_keys: tuple[str, ...], fmt: str, out: str | None
+) -> None:
+    """Export items by KEY in the chosen format."""
+    try:
+        svc = _service()
+        items = [svc._reader.get_item(k) for k in item_keys]
+        if fmt == "csl-json":
+            payload: object = svc.to_csl_json(items)
+        elif fmt == "bibtex":
+            payload = svc.to_bibtex(items)
+        elif fmt == "ris":
+            payload = svc.to_ris(items)
+        else:
+            raise ZopError(f"Unknown format: {fmt}")
+        if out:
+            if fmt == "csl-json":
+                import json
+                Path(out).write_text(
+                    json.dumps(payload, indent=2, ensure_ascii=False),
+                    encoding="utf-8",
+                )
+            else:
+                Path(out).write_text(str(payload), encoding="utf-8")
+            emit({"written": out, "count": len(items)}, human=_human())
+        else:
+            if fmt == "csl-json":
+                import json
+                sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False))
+                sys.stdout.write("\n")
+            else:
+                sys.stdout.write(str(payload))
+            sys.stdout.flush()
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)

zop/commands/item.py

@@ -0,0 +1,176 @@
+"""Item CLI subcommands."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from zop.adapters.zotero_api import ApiCreds
+from zop.core.config import load_config
+from zop.core.envelope import emit, emit_batch, emit_error
+from zop.core.errors import ZopError
+from zop.services.items import ItemsService
+
+
+def _service() -> ItemsService:
+    cfg = load_config()
+    creds = (
+        ApiCreds(library_id=cfg.library_id, api_key=cfg.api_key)
+        if cfg.has_write_credentials
+        else None
+    )
+    if not cfg.data_dir:
+        raise click.UsageError("data_dir not configured")
+    return ItemsService(db_path=Path(cfg.data_dir) / "zotero.sqlite", creds=creds)
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.group(name="item")
+def item() -> None:
+    """Manage Zotero items."""
+
+
+@item.command("search")
+@click.argument("query")
+@click.option("--limit", default=50, type=int, help="Max results (default 50).")
+def search_cmd(query: str, limit: int) -> None:
+    """Search items by title, abstract, or author (LIKE substring)."""
+    try:
+        svc = _service()
+        results = svc.search(query, limit=limit)
+        emit(
+            [it.model_dump() for it in results],
+            human=_human(),
+            count=len(results),
+        )
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@item.command("read")
+@click.argument("key")
+def read_cmd(key: str) -> None:
+    """Get full metadata for an item (by KEY)."""
+    try:
+        svc = _service()
+        data = svc.get(key)
+        emit(data.model_dump(), human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@item.command("update")
+@click.argument("key")
+@click.option("--title", default=None)
+@click.option("--date", default=None)
+@click.option("--abstract", default=None)
+@click.option("--doi", default=None)
+@click.option("--url", default=None)
+@click.option("--set", "extras", multiple=True, help="Set extra field KEY=VALUE (repeatable).")
+def update_cmd(
+    key: str,
+    title: str | None,
+    date: str | None,
+    abstract: str | None,
+    doi: str | None,
+    url: str | None,
+    extras: tuple[str, ...],
+) -> None:
+    """Update an item's metadata. Only provided fields are changed."""
+    extra_dict: dict[str, str] = {}
+    for e in extras:
+        if "=" in e:
+            k, v = e.split("=", 1)
+            extra_dict[k.strip()] = v.strip()
+    try:
+        svc = _service()
+        result = asyncio.run(
+            svc.update(
+                key,
+                title=title,
+                date=date,
+                abstract=abstract,
+                doi=doi,
+                url=url,
+                extra=extra_dict or None,
+            )
+        )
+        emit(result.model_dump(), human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@item.command("delete")
+@click.argument("keys", nargs=-1, required=True)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation.")
+def delete_cmd(keys: tuple[str, ...], yes: bool) -> None:
+    """Delete one or more items."""
+    if not yes:
+        click.confirm(f"Delete {len(keys)} item(s)?", abort=True)
+    try:
+        svc = _service()
+
+        async def _all() -> list[tuple[str, Exception | None]]:
+            results = await asyncio.gather(
+                *[svc.delete(k) for k in keys], return_exceptions=True
+            )
+            out: list[tuple[str, Exception | None]] = []
+            for k, r in zip(keys, results, strict=True):
+                if isinstance(r, Exception):
+                    out.append((k, r))
+                else:
+                    out.append((k, None))
+            return out
+
+        outcomes = asyncio.run(_all())
+        ok = [k for k, e in outcomes if e is None]
+        fail = [(k, e) for k, e in outcomes if e is not None]
+        emit_batch(
+            [{"key": k} for k in ok],
+            [(k, _wrap(e)) for k, e in fail],
+            human=_human(),
+        )
+        if fail:
+            sys.exit(2)
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@item.command("add")
+@click.option("--doi", "dois", multiple=True, help="DOI(s) to add (repeatable).")
+@click.option("--from-file", "dois_file", type=click.Path(exists=True), help="File with one DOI per line.")
+def add_cmd(dois: tuple[str, ...], dois_file: str | None) -> None:
+    """Add item(s) by DOI."""
+    items: list[str] = list(dois)
+    if dois_file:
+        items.extend(Path(dois_file).read_text(encoding="utf-8").splitlines())
+    items = [d.strip() for d in items if d.strip() and not d.startswith("#")]
+    if not items:
+        raise click.UsageError("Provide --doi or --from-file")
+    try:
+        svc = _service()
+        created = asyncio.run(svc.add_many(items))
+        emit(
+            [it.model_dump() for it in created],
+            human=_human(),
+            count=len(created),
+        )
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+def _wrap(e: BaseException) -> ZopError:
+    if isinstance(e, ZopError):
+        return e
+    return ZopError(str(e))

zop/commands/library.py

@@ -0,0 +1,63 @@
+"""Top-level library commands: stats, recent, duplicates."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from zop.core.config import load_config
+from zop.core.envelope import emit, emit_error
+from zop.core.errors import ZopError
+from zop.services.library import LibraryService
+
+
+def _service() -> LibraryService:
+    cfg = load_config()
+    if not cfg.data_dir:
+        raise click.UsageError("data_dir not configured")
+    return LibraryService(db_path=Path(cfg.data_dir) / "zotero.sqlite")
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.command(name="stats")
+def stats_cmd() -> None:
+    """Show library statistics (items, types, top tags, collections)."""
+    try:
+        svc = _service()
+        data = svc.stats()
+        emit(data, human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@click.command(name="recent")
+@click.option("--days", default=7, type=int, help="Look back N days (default 7).")
+@click.option("--limit", default=50, type=int)
+def recent_cmd(days: int, limit: int) -> None:
+    """List recently added items."""
+    try:
+        svc = _service()
+        data = svc.recent(days=days, limit=limit)
+        emit([it.model_dump() for it in data], human=_human(), count=len(data))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@click.command(name="duplicates")
+@click.option("--by", type=click.Choice(["doi", "title"]), default="doi")
+def duplicates_cmd(by: str) -> None:
+    """Find potential duplicate items grouped by DOI (or title)."""
+    try:
+        svc = _service()
+        data = svc.duplicates(by=by)
+        emit(data, human=_human(), count=len(data))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)

zop/commands/note.py

@@ -0,0 +1,68 @@
+"""Note CLI subcommands."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from zop.adapters.zotero_api import ApiCreds
+from zop.core.config import load_config
+from zop.core.envelope import emit, emit_error
+from zop.core.errors import ZopError
+from zop.services.notes import NotesService
+
+
+def _service() -> NotesService:
+    cfg = load_config()
+    creds = (
+        ApiCreds(library_id=cfg.library_id, api_key=cfg.api_key)
+        if cfg.has_write_credentials
+        else None
+    )
+    if not cfg.data_dir:
+        raise click.UsageError("data_dir not configured")
+    return NotesService(db_path=Path(cfg.data_dir) / "zotero.sqlite", creds=creds)
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.group(name="note")
+def note() -> None:
+    """Manage notes."""
+
+
+@note.command("list")
+@click.argument("item_key")
+def list_cmd(item_key: str) -> None:
+    """List notes attached to an item (by KEY)."""
+    try:
+        svc = _service()
+        data = svc.list_for_item(item_key)
+        emit(data, human=_human(), count=len(data))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@note.command("add")
+@click.argument("item_key")
+@click.option("--text", "-t", required=True, help="Note text (Markdown/HTML allowed).")
+@click.option("--file", "file", type=click.Path(exists=True), help="Read note text from file.")
+def add_cmd(item_key: str, text: str | None, file: str | None) -> None:
+    """Add a note to an item (parent KEY)."""
+    if file:
+        text = Path(file).read_text(encoding="utf-8")
+    if not text:
+        raise click.UsageError("Provide --text or --file")
+    try:
+        svc = _service()
+        new_key = asyncio.run(svc.add(item_key, text))
+        emit({"created": new_key}, human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)

zop/commands/pdf.py

@@ -0,0 +1,71 @@
+"""PDF CLI subcommands."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from zop.core.config import load_config
+from zop.core.envelope import emit, emit_error
+from zop.core.errors import ZopError
+from zop.services.pdf import PdfService
+
+
+def _service() -> PdfService:
+    cfg = load_config()
+    if not cfg.data_dir:
+        raise click.UsageError("data_dir not configured")
+    return PdfService(db_path=Path(cfg.data_dir) / "zotero.sqlite")
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.group(name="pdf")
+def pdf() -> None:
+    """Read local PDF attachments."""
+
+
+@pdf.command("read")
+@click.argument("item_key")
+@click.option("--max-chars", default=200_000, type=int)
+def read_cmd(item_key: str, max_chars: int) -> None:
+    """Extract full text from the PDF attached to an item."""
+    try:
+        svc = _service()
+        text = svc.read_text(item_key, max_chars=max_chars)
+        emit({"text": text, "length": len(text)}, human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@pdf.command("outline")
+@click.argument("item_key")
+def outline_cmd(item_key: str) -> None:
+    """Show PDF outline (bookmarks)."""
+    try:
+        svc = _service()
+        outline = svc.get_outline(item_key)
+        emit(outline, human=_human(), count=len(outline))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@pdf.command("section")
+@click.argument("item_key")
+@click.argument("section_number", type=int)
+@click.option("--max-chars", default=100_000, type=int)
+def section_cmd(item_key: str, section_number: int, max_chars: int) -> None:
+    """Read a specific outline section (1-indexed)."""
+    try:
+        svc = _service()
+        text = svc.read_section(item_key, section_number, max_chars=max_chars)
+        emit({"text": text, "length": len(text)}, human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)

zop/commands/tag.py

@@ -0,0 +1,94 @@
+"""Tag CLI subcommands."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import click
+
+from zop.adapters.zotero_api import ApiCreds
+from zop.core.config import load_config
+from zop.core.envelope import emit, emit_batch, emit_error
+from zop.core.errors import ZopError
+from zop.services.tags import TagsService
+
+
+def _service() -> TagsService:
+    cfg = load_config()
+    creds = (
+        ApiCreds(library_id=cfg.library_id, api_key=cfg.api_key)
+        if cfg.has_write_credentials
+        else None
+    )
+    if not cfg.data_dir:
+        raise click.UsageError("data_dir not configured")
+    return TagsService(db_path=Path(cfg.data_dir) / "zotero.sqlite", creds=creds)
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.group(name="tag")
+def tag() -> None:
+    """Manage tags."""
+
+
+@tag.command("list")
+def list_cmd() -> None:
+    """List all tags with usage counts."""
+    try:
+        svc = _service()
+        data = svc.list_all()
+        emit(data, human=_human(), count=len(data))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@tag.command("add")
+@click.argument("item_keys", nargs=-1, required=True)
+@click.option("--tags", "tags", required=True, help="Comma-separated tags to add.")
+def add_cmd(item_keys: tuple[str, ...], tags: str) -> None:
+    """Add tags to items (preserves existing)."""
+    tag_list = [t.strip() for t in tags.split(",") if t.strip()]
+    try:
+        svc = _service()
+        ok, fail = asyncio.run(svc.add(list(item_keys), tag_list))
+        emit_batch(
+            [{"key": k} for k in ok],
+            [(k, _wrap(e)) for k, e in fail],
+            human=_human(),
+        )
+        if fail:
+            sys.exit(2)
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@tag.command("remove")
+@click.argument("item_keys", nargs=-1, required=True)
+@click.option("--tags", "tags", required=True, help="Comma-separated tags to remove.")
+def remove_cmd(item_keys: tuple[str, ...], tags: str) -> None:
+    """Remove tags from items."""
+    tag_list = [t.strip() for t in tags.split(",") if t.strip()]
+    try:
+        svc = _service()
+        ok, fail = asyncio.run(svc.remove(list(item_keys), tag_list))
+        emit_batch(
+            [{"key": k} for k in ok],
+            [(k, _wrap(e)) for k, e in fail],
+            human=_human(),
+        )
+        if fail:
+            sys.exit(2)
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+def _wrap(e: BaseException) -> ZopError:
+    return e if isinstance(e, ZopError) else ZopError(str(e))

zop/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core utilities (config, sqlite reader, http client)."""
+
+from zop.core.config import AppConfig, load_config
+
+__all__ = ["AppConfig", "load_config"]

zop/core/concurrency.py

@@ -0,0 +1,38 @@
+"""Bounded concurrency helper."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Iterable, Sequence
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+async def bounded_gather[T](
+    coros: Iterable[Awaitable[T]],
+    *,
+    concurrency: int = 8,
+) -> list[T]:
+    """Run async tasks with bounded concurrency.
+
+    Args:
+        coros: Iterable of awaitables (not yet started).
+        concurrency: Max number of tasks running at once.
+
+    Returns:
+        List of results in the same order as input.
+    """
+    sem = asyncio.Semaphore(concurrency)
+
+    async def _run(coro: Awaitable[T]) -> T:
+        async with sem:
+            return await coro
+
+    tasks = [asyncio.create_task(_run(c)) for c in coros]
+    return list(await asyncio.gather(*tasks, return_exceptions=False))
+
+
+def chunked[T](seq: Sequence[T], size: int) -> list[Sequence[T]]:
+    """Split a sequence into chunks of `size`."""
+    return [seq[i : i + size] for i in range(0, len(seq), size)]

zop/core/config.py

@@ -0,0 +1,66 @@
+"""Configuration loader.
+
+Reads ``~/.config/zop/config.toml`` (or an explicit path from the
+``ZOP_CONFIG`` env var). Supports a flat TOML schema only in v0.1 — a
+profile-based schema is on the roadmap.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+import platformdirs
+
+APP_NAME = "zop"
+CONFIG_FILE = Path(platformdirs.user_config_dir(APP_NAME, appauthor=False)) / "config.toml"
+
+
+@dataclass
+class AppConfig:
+    """Resolved configuration."""
+
+    data_dir: str = ""
+    library_id: str = ""
+    api_key: str = ""
+    semantic_scholar_api_key: str = ""
+
+    @property
+    def has_write_credentials(self) -> bool:
+        return bool(self.library_id and self.api_key)
+
+
+def _load_toml(path: Path) -> dict[str, object]:
+    if not path.exists():
+        return {}
+    with path.open("rb") as f:
+        return tomllib.load(f)
+
+
+def load_config(path: Path | None = None) -> AppConfig:
+    """Load configuration from disk.
+
+    Lookup order:
+    1. ``ZOP_CONFIG`` env var (explicit override path)
+    2. ``<config_dir>/zop/config.toml`` (default location)
+    """
+    if path is None:
+        path = Path(os.environ["ZOP_CONFIG"]) if "ZOP_CONFIG" in os.environ else None
+
+    data = _load_toml(path) if path is not None else _load_toml(CONFIG_FILE)
+
+    # Flat schema: [zotero] section.
+    z = data.get("zotero", {}) if isinstance(data, dict) else {}
+    if not isinstance(z, dict):
+        z = {}
+    return AppConfig(
+        data_dir=str(z.get("data_dir", "")),
+        library_id=str(z.get("library_id", "")),
+        api_key=str(z.get("api_key", "")),
+        semantic_scholar_api_key=str(z.get("semantic_scholar_api_key", "")),
+    )
+
+
+__all__ = ["CONFIG_FILE", "AppConfig", "load_config"]