zop-cli 0.2.0__py3-none-any.whl

zop/adapters/zotero_api.py

@@ -0,0 +1,315 @@
+"""Async Zotero Web API client (batch-capable).
+
+Differences from pyzotero-based tools (e.g. zot):
+- Real batch POST for collection creation
+- Bounded-concurrency PATCH for item moves (pyzotero's addto_collection is single-item per call)
+- True reparent via PATCH /collections/{key} with parentCollection=false (pyzotero doesn't expose this)
+- Per-item error isolation: one failure doesn't abort the batch
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+import httpx
+
+from zop.core.concurrency import chunked
+from zop.core.errors import ApiError, AuthError, ConflictError, NotFoundError
+
+_SENTINEL = object()
+
+
+@dataclass
+class ApiCreds:
+    library_id: str
+    api_key: str
+    library_type: str = "user"  # "user" or "group"
+
+
+class ZoteroApi:
+    """Thin async wrapper over the Zotero Web API."""
+
+    BASE_URL = "https://api.zotero.org"
+    USER_AGENT = "zop/0.1 (+https://github.com/anomalyco/zop)"
+
+    # API limits per Zotero docs
+    BATCH_WRITE_LIMIT = 50  # max objects per POST/PATCH
+    BATCH_READ_LIMIT = 100  # max items per GET
+
+    def __init__(
+        self,
+        creds: ApiCreds,
+        *,
+        concurrency: int = 8,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not creds.library_id or not creds.api_key:
+            raise AuthError("library_id and api_key are required")
+        self.creds = creds
+        self.concurrency = concurrency
+        self._client = httpx.AsyncClient(
+            base_url=self.BASE_URL,
+            headers={
+                "Zotero-API-Key": creds.api_key,
+                "Zotero-API-Version": "3",
+                "User-Agent": self.USER_AGENT,
+            },
+            timeout=timeout,
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> ZoteroApi:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # ---- URL helpers ----
+
+    def _root(self) -> str:
+        return f"/{self.creds.library_type}s/{self.creds.library_id}"
+
+    def _coll_url(self, key: str | None = None) -> str:
+        base = f"{self._root()}/collections"
+        return f"{base}/{key}" if key else base
+
+    def _items_url(self, key: str | None = None) -> str:
+        base = f"{self._root()}/items"
+        return f"{base}/{key}" if key else base
+
+    # ---- Response handling ----
+
+    def _check(self, resp: httpx.Response) -> Any:
+        """Parse response or raise structured error."""
+        if resp.status_code == 404:
+            raise NotFoundError(f"Not found: {resp.url}")
+        if resp.status_code in (409, 412):
+            raise ConflictError(f"Conflict (HTTP {resp.status_code}): {resp.text[:200]}")
+        if resp.status_code in (401, 403):
+            raise AuthError(f"Auth failed (HTTP {resp.status_code})")
+        if resp.status_code >= 400:
+            raise ApiError(resp.status_code, resp.text[:200])
+        if not resp.content:
+            return None
+        return resp.json()
+
+    # ---- Collections ----
+
+    async def list_collections(self, *, limit: int = 100) -> list[dict[str, Any]]:
+        """Fetch all collections for the library (paginated)."""
+        out: list[dict[str, Any]] = []
+        start = 0
+        while True:
+            resp = await self._client.get(
+                self._coll_url(),
+                params={"limit": min(limit, self.BATCH_READ_LIMIT), "start": start},
+            )
+            data = self._check(resp)
+            if not data:
+                break
+            out.extend(data)
+            if len(data) < self.BATCH_READ_LIMIT:
+                break
+            start += len(data)
+        return out
+
+    async def create_collections(
+        self, payloads: Sequence[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Create up to BATCH_WRITE_LIMIT collections per request.
+
+        Returns the created collection objects (each with `key`, `version`, etc.)
+        in the same order as the input. The Zotero API returns:
+        `{"successful": {...}, "unchanged": {...}, "failed": {...}, "success": {...}}`
+        """
+        if not payloads:
+            return []
+        results: list[dict[str, Any]] = []
+        for batch in chunked(list(payloads), self.BATCH_WRITE_LIMIT):
+            resp = await self._client.post(self._coll_url(), json=list(batch))
+            data = self._check(resp)
+            if isinstance(data, dict):
+                # data has keys: successful (dict by index), unchanged, failed, success
+                # Reconstruct ordered list of created collections.
+                created = data.get("successful", {})
+                if isinstance(created, dict):
+                    results.extend(created.values())
+                else:
+                    results.extend(created)
+            elif isinstance(data, list):
+                results.extend(data)
+        return results
+
+    async def update_collection(
+        self,
+        key: str,
+        *,
+        name: str | None = None,
+        parent_key: str | None | object = _SENTINEL,
+        version: int | None = None,
+    ) -> dict[str, Any]:
+        """Update a collection.
+
+        Args:
+            key: Collection key.
+            name: New name (optional).
+            parent_key: New parent key. Pass ``None`` or ``False`` to detach to
+                top-level. Default (sentinel) leaves parent unchanged.
+            version: If-Unmodified-Since-Version for optimistic locking.
+        """
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if parent_key is not _SENTINEL:
+            payload["parentCollection"] = parent_key if parent_key else False
+        headers: dict[str, str] = {}
+        if version is not None:
+            headers["If-Unmodified-Since-Version"] = str(version)
+        resp = await self._client.patch(self._coll_url(key), json=payload, headers=headers)
+        return cast("dict[str, Any]", self._check(resp))
+
+    async def delete_collection(self, key: str, *, version: int | None = None) -> None:
+        """Delete a collection. CASCADE: deletes all subcollections."""
+        headers: dict[str, str] = {}
+        if version is not None:
+            headers["If-Unmodified-Since-Version"] = str(version)
+        resp = await self._client.delete(self._coll_url(key), headers=headers)
+        self._check(resp)
+
+    # ---- Items ----
+
+    async def get_item(self, key: str) -> dict[str, Any]:
+        resp = await self._client.get(self._items_url(key))
+        return cast("dict[str, Any]", self._check(resp))
+
+    async def update_item_collections(
+        self, key: str, collections: list[str], *, version: int | None = None
+    ) -> dict[str, Any]:
+        """Set an item's collection membership (replaces existing)."""
+        headers: dict[str, str] = {}
+        if version is not None:
+            headers["If-Unmodified-Since-Version"] = str(version)
+        resp = await self._client.patch(
+            self._items_url(key), json={"collections": collections}, headers=headers
+        )
+        return cast("dict[str, Any]", self._check(resp))
+
+    async def batch_update_item_collections(
+        self,
+        updates: Sequence[tuple[str, list[str], int | None]],
+        *,
+        concurrency: int | None = None,
+    ) -> tuple[list[str], list[tuple[str, Exception]]]:
+        """Move many items concurrently with bounded parallelism.
+
+        Args:
+            updates: Sequence of ``(item_key, target_collections, version)``.
+            concurrency: Override default concurrency.
+
+        Returns:
+            ``(success_keys, failures)`` where ``failures`` is a list of
+            ``(item_key, exception)`` pairs.
+        """
+        if not updates:
+            return [], []
+        sem = asyncio.Semaphore(concurrency or self.concurrency)
+
+        async def _one(item_key: str, colls: list[str], ver: int | None) -> str:
+            async with sem:
+                await self.update_item_collections(item_key, colls, version=ver)
+                return item_key
+
+        results = await asyncio.gather(
+            *(_one(k, c, v) for k, c, v in updates), return_exceptions=True
+        )
+        successes: list[str] = []
+        failures: list[tuple[str, Exception]] = []
+        for (k, _, _), r in zip(updates, results, strict=True):
+            if isinstance(r, Exception):
+                failures.append((k, r))
+            else:
+                successes.append(cast(str, r))
+        return successes, failures
+
+    async def update_item(
+        self,
+        key: str,
+        data: dict[str, Any],
+        *,
+        version: int | None = None,
+    ) -> dict[str, Any]:
+        """Patch an item's fields.
+
+        Args:
+            key: Item key.
+            data: Partial item payload (e.g. ``{"tags": [...]}`` or
+                ``{"title": ...}``). Replaces the listed fields server-side.
+            version: ``If-Unmodified-Since-Version`` for optimistic locking.
+
+        Returns:
+            The updated item dict, or an empty dict on an empty response.
+        """
+        headers: dict[str, str] = {}
+        if version is not None:
+            headers["If-Unmodified-Since-Version"] = str(version)
+        resp = await self._client.patch(self._items_url(key), json=data, headers=headers)
+        result = self._check(resp)
+        return result if isinstance(result, dict) else {}
+
+    async def delete_item(self, key: str, *, version: int | None = None) -> None:
+        """Delete an item.
+
+        Args:
+            key: Item key.
+            version: ``If-Unmodified-Since-Version``. Zotero requires this for
+                item DELETE in practice.
+        """
+        headers: dict[str, str] = {}
+        if version is not None:
+            headers["If-Unmodified-Since-Version"] = str(version)
+        resp = await self._client.delete(self._items_url(key), headers=headers)
+        self._check(resp)
+
+    async def create_items(
+        self, payloads: Sequence[dict[str, Any]]
+    ) -> list[dict[str, Any]]:
+        """Create items via batch POST /items.
+
+        Sends payloads as a single POST body (list), chunked at
+        ``BATCH_WRITE_LIMIT``. Returns the created item dicts extracted from
+        the server's ``successful`` envelope (each contains ``key``,
+        ``version``, etc.), in the order the server reports them.
+
+        Args:
+            payloads: Item template dicts (e.g.
+                ``[{"itemType": "journalArticle", "DOI": "..."}]``).
+
+        Returns:
+            List of created items. Empty if the server rejected all entries;
+            the caller decides whether empty means an error.
+        """
+        if not payloads:
+            return []
+        results: list[dict[str, Any]] = []
+        for batch in chunked(list(payloads), self.BATCH_WRITE_LIMIT):
+            resp = await self._client.post(self._items_url(), json=list(batch))
+            data = self._check(resp)
+            if isinstance(data, dict):
+                created = data.get("successful", {})
+                if isinstance(created, dict):
+                    results.extend(created.values())
+                else:
+                    results.extend(created)
+            elif isinstance(data, list):
+                results.extend(data)
+        return results
+
+
+__all__ = ["ApiCreds", "ZoteroApi"]

zop/cli.py

@@ -0,0 +1,96 @@
+"""CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+from typing import NoReturn
+
+import click
+
+from zop import __version__
+from zop.commands.collection import collection as collection_cmd
+from zop.commands.export import export_cmd
+from zop.commands.item import item as item_cmd
+from zop.commands.library import duplicates_cmd, recent_cmd, stats_cmd
+from zop.commands.note import note as note_cmd
+from zop.commands.pdf import pdf as pdf_cmd
+from zop.commands.tag import tag as tag_cmd
+
+
+@click.group(
+    name="zop",
+    help="High-throughput Zotero CLI. Reads from local SQLite; writes via Web API.",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(__version__, "-V", "--version")
+@click.option(
+    "--json",
+    "force_json",
+    is_flag=True,
+    default=False,
+    help="Force JSON envelope output.",
+)
+@click.option(
+    "--human",
+    "force_human",
+    is_flag=True,
+    default=False,
+    help="Force human-readable output.",
+)
+@click.option(
+    "-q",
+    "--quiet",
+    is_flag=True,
+    default=False,
+    help="Suppress non-essential output (errors only).",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    count=True,
+    help="Increase verbosity (-v, -vv).",
+)
+@click.pass_context
+def main(
+    ctx: click.Context,
+    force_json: bool,
+    force_human: bool,
+    quiet: bool,
+    verbose: int,
+) -> None:
+    """Entry point."""
+    if force_json and force_human:
+        raise click.UsageError("--json and --human are mutually exclusive")
+    if force_json:
+        human = False
+    elif force_human:
+        human = True
+    else:
+        human = sys.stdout.isatty()
+    ctx.ensure_object(dict)
+    ctx.obj["human"] = human
+    ctx.obj["quiet"] = quiet
+    ctx.obj["verbose"] = verbose
+
+
+main.add_command(collection_cmd, name="collection")
+main.add_command(item_cmd, name="item")
+main.add_command(tag_cmd, name="tag")
+main.add_command(note_cmd, name="note")
+main.add_command(pdf_cmd, name="pdf")
+main.add_command(export_cmd, name="export")
+main.add_command(stats_cmd, name="stats")
+main.add_command(recent_cmd, name="recent")
+main.add_command(duplicates_cmd, name="duplicates")
+
+
+def run() -> NoReturn:
+    """Entry point for setuptools/uv script wrapper."""
+    try:
+        main(standalone_mode=True)
+    except click.ClickException as exc:
+        exc.show()
+        sys.exit(exc.exit_code)
+    except click.exceptions.Abort:
+        sys.exit(1)
+    sys.exit(0)

zop/commands/__init__.py

@@ -0,0 +1,21 @@
+"""CLI command groups."""
+
+from zop.commands.collection import collection
+from zop.commands.export import export_cmd
+from zop.commands.item import item
+from zop.commands.library import duplicates_cmd, recent_cmd, stats_cmd
+from zop.commands.note import note
+from zop.commands.pdf import pdf
+from zop.commands.tag import tag
+
+__all__ = [
+    "collection",
+    "duplicates_cmd",
+    "export_cmd",
+    "item",
+    "note",
+    "pdf",
+    "recent_cmd",
+    "stats_cmd",
+    "tag",
+]

zop/commands/collection.py

@@ -0,0 +1,221 @@
+"""Collection CLI subcommands."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+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.collections import CollectionsService, PlanNode
+
+
+def _service(ctx: click.Context) -> CollectionsService:
+    cfg = load_config()
+    creds: ApiCreds | None = None
+    if cfg.has_write_credentials:
+        creds = ApiCreds(library_id=cfg.library_id, api_key=cfg.api_key)
+    if not cfg.data_dir:
+        raise click.UsageError(
+            "data_dir not configured. Run 'zop config init' or set in "
+            "~/.config/zop/config.toml"
+        )
+    return CollectionsService(db_path=Path(cfg.data_dir) / "zotero.sqlite", creds=creds)
+
+
+def _human() -> bool:
+    return sys.stdout.isatty()
+
+
+@click.group(name="collection")
+def collection() -> None:
+    """Manage Zotero collections."""
+
+
+@collection.command("list")
+@click.option("--tree", is_flag=True, help="Show as parent/child tree.")
+@click.option("--flat", is_flag=True, help="Show as flat list (default).")
+@click.pass_context
+def list_cmd(ctx: click.Context, tree: bool, flat: bool) -> None:
+    """List all collections."""
+    try:
+        svc = _service(ctx)
+        if tree:
+            nodes = svc.list_tree()
+            data = [n.model_dump() for n in nodes]
+        else:
+            data = [c.model_dump() for c in svc.list_all()]
+        emit(data, human=_human(), count=len(data))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@collection.command("items")
+@click.argument("key")
+@click.pass_context
+def items_cmd(ctx: click.Context, key: str) -> None:
+    """List item keys in a collection (by KEY)."""
+    try:
+        svc = _service(ctx)
+        data = svc.items(key)
+        emit(data, human=_human(), count=len(data))
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@collection.command("create")
+@click.argument("name")
+@click.option("--parent", "parent_name", default=None, help="Parent collection NAME.")
+@click.pass_context
+def create_cmd(ctx: click.Context, name: str, parent_name: str | None) -> None:
+    """Create a collection (NAME). Requires API key."""
+    try:
+        svc = _service(ctx)
+        result = asyncio.run(svc.create(name, parent=parent_name))
+        emit([result.model_dump()], human=_human(), count=1)
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@collection.command("delete")
+@click.argument("key")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation.")
+@click.pass_context
+def delete_cmd(ctx: click.Context, key: str, yes: bool) -> None:
+    """Delete a collection (cascades to subcollections). Requires API key."""
+    if not yes:
+        click.confirm(f"Delete collection {key} (and all subcollections)?", abort=True)
+    try:
+        svc = _service(ctx)
+        asyncio.run(svc.delete(key))
+        emit({"deleted": key}, human=_human())
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@collection.command("reparent")
+@click.argument("key")
+@click.option("--parent", "parent_name", default=None, help="New parent NAME (omit for top-level).")
+@click.pass_context
+def reparent_cmd(ctx: click.Context, key: str, parent_name: str | None) -> None:
+    """Move a collection under a new parent (or to top-level). Requires API key."""
+    try:
+        svc = _service(ctx)
+        result = asyncio.run(svc.reparent(key, parent_name))
+        emit([result.model_dump()], human=_human(), count=1)
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+@collection.command("move")
+@click.argument("item_keys", nargs=-1, required=True)
+@click.option("--to", "to_collection_key", required=True, help="Target collection KEY.")
+@click.pass_context
+def move_cmd(
+    ctx: click.Context,
+    item_keys: tuple[str, ...],
+    to_collection_key: str,
+) -> None:
+    """Move items into a collection. Bounded-concurrent PATCH."""
+    try:
+        svc = _service(ctx)
+        ok, fail = asyncio.run(svc.move_items(list(item_keys), to_collection_key))
+        emit_batch(
+            [{"key": k} for k in ok],
+            [(k, _wrapped(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)
+
+
+@collection.command("plan")
+@click.argument("plan_file", type=click.Path(exists=True, path_type=Path))
+@click.option("--dry-run", is_flag=True, help="Validate without executing.")
+@click.option("--execute", "do_execute", is_flag=True, help="Actually execute.")
+@click.pass_context
+def plan_cmd(
+    ctx: click.Context,
+    plan_file: Path,
+    dry_run: bool,
+    do_execute: bool,
+) -> None:
+    """Batch reorg from a plan JSON file.
+
+    Plan format::
+
+        {
+          "collections": [
+            {"name": "Topic A", "parent": "ExistingParent", "items": ["KEY1", "KEY2"]},
+            {"name": "Topic B", "items": []}
+          ]
+        }
+    """
+    if dry_run == do_execute:
+        raise click.UsageError("Specify exactly one of --dry-run or --execute")
+    try:
+        with plan_file.open("r", encoding="utf-8") as f:
+            raw = json.load(f)
+        plan = [
+            PlanNode(
+                name=p["name"],
+                parent=p.get("parent"),
+                items=p.get("items", []),
+            )
+            for p in raw.get("collections", [])
+        ]
+        svc = _service(ctx)
+        report = svc.validate_plan(plan)
+        out = {
+            "to_create": [
+                {"name": n.name, "parent": n.parent, "items": n.items}
+                for n in report.to_create
+            ],
+            "assignments": [{"item": k, "collection": c} for k, c in report.item_assignments],
+            "conflicts": report.conflicts,
+            "unresolved_parents": report.unresolved_parents,
+            "ok": report.ok,
+        }
+        if dry_run:
+            emit(out, human=_human())
+            if not report.ok:
+                sys.exit(2)
+            return
+        # execute
+        if not report.ok:
+            emit(out, human=_human())
+            sys.exit(2)
+        created = asyncio.run(svc.create_many(plan))
+        emit(
+            {
+                "created": [c.model_dump() for c in created],
+                "assignments_pending": report.item_assignments,
+            },
+            human=_human(),
+            count=len(created),
+        )
+        # Note: item assignment to newly-created collections would go here
+        # in a follow-up step (separate API call after collections exist).
+    except ZopError as e:
+        emit_error(e, human=_human())
+        sys.exit(1)
+
+
+def _wrapped(e: BaseException) -> ZopError:
+    if isinstance(e, ZopError):
+        return e
+    return ZopError(str(e))