zop-cli 0.2.0__py3-none-any.whl

zop/services/export.py

@@ -0,0 +1,187 @@
+"""Export service: BibTeX, CSL-JSON, RIS formatters."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.core.errors import ZopError
+from zop.models.item import Item
+
+
+class ExportService:
+    """Format items into citation formats."""
+
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        if db_path is None:
+            raise ZopError("db_path required")
+        self._reader = SqliteReader(db_path)
+
+    def to_csl_json(self, items: list[Item]) -> list[dict[str, object]]:
+        """Convert to CSL-JSON (Citation Style Language)."""
+        out: list[dict[str, object]] = []
+        for it in items:
+            entry: dict[str, object] = {
+                "id": it.key,
+                "type": _map_type_to_csl(it.item_type.value),
+                "title": it.title,
+            }
+            if it.creators:
+                entry["author"] = [
+                    {"family": _family(c), "given": _given(c)} for c in it.creators
+                ]
+            if it.date:
+                entry["issued"] = {"date-parts": [[_extract_year(it.date)]]}
+            if it.doi:
+                entry["DOI"] = it.doi
+            if it.url:
+                entry["URL"] = it.url
+            if it.abstract:
+                entry["abstract"] = it.abstract
+            out.append(entry)
+        return out
+
+    def to_bibtex(self, items: list[Item]) -> str:
+        """Convert to BibTeX."""
+        lines: list[str] = []
+        for it in items:
+            entry_type = _map_type_to_bibtex(it.item_type.value)
+            key = _make_bibtex_key(it)
+            lines.append(f"@{entry_type}{{{key},")
+            lines.append(f"  title = {{{_escape_bibtex(it.title)}}},")
+            if it.creators:
+                authors = " and ".join(it.creators)
+                lines.append(f"  author = {{{_escape_bibtex(authors)}}},")
+            if it.date:
+                year = _extract_year(it.date)
+                lines.append(f"  year = {{{year}}},")
+            if it.doi:
+                lines.append(f"  doi = {{{it.doi}}},")
+            if it.url:
+                lines.append(f"  url = {{{it.url}}},")
+            if it.abstract:
+                lines.append(f"  abstract = {{{_escape_bibtex(it.abstract)}}},")
+            lines.append("}")
+            lines.append("")
+        return "\n".join(lines)
+
+    def to_ris(self, items: list[Item]) -> str:
+        """Convert to RIS format."""
+        out: list[str] = []
+        for it in items:
+            out.append(_map_type_to_ris(it.item_type.value))
+            if it.title:
+                out.append(f"TI  - {it.title}")
+            for c in it.creators:
+                out.append(f"AU  - {c}")
+            if it.date:
+                out.append(f"PY  - {_extract_year(it.date)}")
+            if it.doi:
+                out.append(f"DO  - {it.doi}")
+            if it.url:
+                out.append(f"UR  - {it.url}")
+            if it.abstract:
+                out.append(f"AB  - {it.abstract}")
+            out.append("ER  - ")
+            out.append("")
+        return "\n".join(out)
+
+
+# ---- Helpers ----
+
+def _family(creator: str) -> str:
+    return creator.split(",", 1)[0].strip() if "," in creator else creator.split()[-1]
+
+
+def _given(creator: str) -> str:
+    return creator.split(",", 1)[1].strip() if "," in creator else " ".join(creator.split()[:-1])
+
+
+def _escape_bibtex(s: str) -> str:
+    return s.replace("{", "\\{").replace("}", "\\}").replace("$", "\\$")
+
+
+def _extract_year(date: str | None) -> str:
+    if date is None:
+        return ""
+    m = re.search(r"\d{4}", date)
+    return m.group(0) if m else ""
+
+
+def _make_bibtex_key(item: Item) -> str:
+    """Generate a citation key: firstAuthorLastName + Year + FirstTitleWord."""
+    auth = "anon"
+    if item.creators:
+        first_author = item.creators[0]
+        auth = _family(first_author).lower().replace(" ", "")
+    year = _extract_year(item.date) or "nodate"
+    title_word = ""
+    for w in re.split(r"\W+", item.title.lower()):
+        if w and w not in {"a", "an", "the", "on", "of", "in", "for", "to", "and", "or"}:
+            title_word = w
+            break
+    return f"{auth}{year}{title_word}"[:40]
+
+
+_TYPE_MAP_CSL = {
+    "book": "book",
+    "bookSection": "chapter",
+    "journalArticle": "article-journal",
+    "conferencePaper": "paper-conference",
+    "preprint": "article",
+    "report": "report",
+    "document": "document",
+    "dataset": "dataset",
+    "webpage": "webpage",
+    "computerProgram": "software",
+    "thesis": "thesis",
+    "manuscript": "manuscript",
+}
+
+
+def _map_type_to_csl(t: str) -> str:
+    return _TYPE_MAP_CSL.get(t, "article")
+
+
+_TYPE_MAP_BIBTEX = {
+    "book": "book",
+    "bookSection": "incollection",
+    "journalArticle": "article",
+    "conferencePaper": "inproceedings",
+    "preprint": "article",
+    "report": "techreport",
+    "document": "misc",
+    "dataset": "misc",
+    "webpage": "misc",
+    "computerProgram": "misc",
+    "thesis": "phdthesis",
+    "manuscript": "unpublished",
+}
+
+
+def _map_type_to_bibtex(t: str) -> str:
+    return _TYPE_MAP_BIBTEX.get(t, "misc")
+
+
+_TYPE_MAP_RIS = {
+    "book": "TY  - BOOK",
+    "bookSection": "TY  - CHAP",
+    "journalArticle": "TY  - JOUR",
+    "conferencePaper": "TY  - CONF",
+    "preprint": "TY  - GEN",
+    "report": "TY  - RPRT",
+    "document": "TY  - GEN",
+    "dataset": "TY  - DATA",
+    "webpage": "TY  - ELEC",
+    "computerProgram": "TY  - COMP",
+    "thesis": "TY  - THES",
+    "manuscript": "TY  - UNPB",
+}
+
+
+def _map_type_to_ris(t: str) -> str:
+    return _TYPE_MAP_RIS.get(t, "TY  - GEN")
+
+
+__all__ = ["ExportService"]

zop/services/items.py

@@ -0,0 +1,142 @@
+"""Item service: business logic for item operations."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.adapters.zotero_api import ApiCreds, ZoteroApi
+from zop.core.errors import AuthError, NotFoundError, ZopError
+from zop.models.item import Item, ItemSummary
+
+
+class ItemsService:
+    """High-level item operations."""
+
+    def __init__(
+        self,
+        db_path: Path | str | None = None,
+        *,
+        creds: ApiCreds | None = None,
+    ) -> None:
+        if db_path is None:
+            raise ZopError("db_path required")
+        self._db_path = Path(db_path)
+        self._creds = creds
+        self._reader = SqliteReader(self._db_path)
+
+    # ---- Read (local SQLite) ----
+
+    def get(self, key: str) -> Item:
+        return self._reader.get_item(key)
+
+    def search(self, query: str, *, limit: int = 50) -> list[ItemSummary]:
+        return self._reader.search_items(query, limit=limit)
+
+    # ---- Write (API) ----
+
+    def _require_api(self) -> ZoteroApi:
+        if not self._creds or not self._creds.api_key:
+            raise AuthError("API credentials required for write operations")
+        return ZoteroApi(self._creds)
+
+    async def update(
+        self,
+        key: str,
+        *,
+        title: str | None = None,
+        date: str | None = None,
+        abstract: str | None = None,
+        doi: str | None = None,
+        url: str | None = None,
+        extra: dict[str, str] | None = None,
+        collections: Sequence[str] | None = None,
+    ) -> Item:
+        """Patch an item's metadata. Pass only fields you want to change.
+
+        Use ``extra`` to set arbitrary fields (becomes Zotero's `extra` blob).
+        Use ``collections`` to set collection membership (replaces existing).
+        """
+        api = self._require_api()
+        # Get current state for the If-Unmodified-Since-Version header.
+        async with api:
+            current = await api.get_item(key)
+            version = current["version"]
+            payload: dict[str, object] = dict(current["data"])
+            if title is not None:
+                payload["title"] = title
+            if date is not None:
+                payload["date"] = date
+            if abstract is not None:
+                payload["abstractNote"] = abstract
+            if doi is not None:
+                payload["DOI"] = doi
+            if url is not None:
+                payload["url"] = url
+            if collections is not None:
+                payload["collections"] = list(collections)
+            if extra:
+                # Merge into existing extra blob (newline-separated key: value).
+                existing_extra = str(payload.get("extra", ""))
+                lines = [ln for ln in existing_extra.splitlines() if ln.strip()]
+                seen_keys = set()
+                for ln in lines:
+                    if ":" in ln:
+                        seen_keys.add(ln.split(":", 1)[0].strip())
+                for k, v in extra.items():
+                    line = f"{k}: {v}"
+                    if k in seen_keys:
+                        lines = [ln for ln in lines if not ln.startswith(f"{k}:")]
+                    lines.append(line)
+                payload["extra"] = "\n".join(lines)
+            # Strip fields the API doesn't accept in PATCH
+            payload.pop("key", None)
+            payload.pop("version", None)
+            payload.pop("dateAdded", None)
+            payload.pop("dateModified", None)
+
+            await api.update_item(key, payload, version=version)
+        # Re-fetch from local DB (will pick up after sync)
+        try:
+            return self._reader.get_item(key)
+        except NotFoundError:
+            return Item(
+                key=key,
+                item_type=self.get(key).item_type,
+                title=title or "",
+            )
+
+    async def delete(self, key: str) -> None:
+        api = self._require_api()
+        async with api:
+            current = await api.get_item(key)
+            await api.delete_item(key, version=current["version"])
+
+    async def add_by_doi(self, doi: str, *, collection_keys: Sequence[str] | None = None) -> Item:
+        """Create an item from a DOI. Uses Zotero's translation API endpoint."""
+        api = self._require_api()
+        payload: dict[str, object] = {
+            "itemType": "journalArticle",  # default; server may override
+            "DOI": doi,
+            "collections": list(collection_keys or []),
+        }
+        async with api:
+            created = await api.create_items([payload])
+        if not created:
+            raise ZopError(f"DOI '{doi}' not found or rejected by server")
+        return self.get(created[0]["key"])
+
+    async def add_many(self, dois: Sequence[str]) -> list[Item]:
+        """Add multiple items by DOI in a single batched POST."""
+        api = self._require_api()
+        payload = [
+            {"itemType": "journalArticle", "DOI": doi}
+            for doi in dois
+        ]
+        async with api:
+            created = await api.create_items(payload)
+        return [self.get(c["key"]) for c in created if c.get("key")]
+
+
+__all__ = ["ItemsService"]

zop/services/library.py

@@ -0,0 +1,30 @@
+"""Library service: stats, recent, duplicates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.core.errors import ZopError
+from zop.models.item import ItemSummary
+
+
+class LibraryService:
+    """Top-level library operations: stats, recent items, duplicate detection."""
+
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        if db_path is None:
+            raise ZopError("db_path required")
+        self._reader = SqliteReader(db_path)
+
+    def stats(self) -> dict[str, object]:
+        return self._reader.get_library_stats()
+
+    def recent(self, days: int = 7, limit: int = 50) -> list[ItemSummary]:
+        return self._reader.list_recent(days=days, limit=limit)
+
+    def duplicates(self, by: str = "doi") -> dict[str, list[str]]:
+        return self._reader.find_duplicates(by=by)
+
+
+__all__ = ["LibraryService"]

zop/services/notes.py

@@ -0,0 +1,47 @@
+"""Notes service."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.adapters.zotero_api import ApiCreds, ZoteroApi
+from zop.core.errors import AuthError, ZopError
+
+
+class NotesService:
+    """Notes operations: list notes on an item, add a new note."""
+
+    def __init__(
+        self,
+        db_path: Path | str | None = None,
+        *,
+        creds: ApiCreds | None = None,
+    ) -> None:
+        if db_path is None:
+            raise ZopError("db_path required")
+        self._db_path = Path(db_path)
+        self._creds = creds
+        self._reader = SqliteReader(self._db_path)
+
+    def list_for_item(self, item_key: str) -> list[dict[str, str]]:
+        return self._reader.get_item_notes(item_key)
+
+    def _require_api(self) -> ZoteroApi:
+        if not self._creds or not self._creds.api_key:
+            raise AuthError("API credentials required for write operations")
+        return ZoteroApi(self._creds)
+
+    async def add(self, item_key: str, text: str) -> str:
+        """Create a note attached to an item. Returns the new note key."""
+        api = self._require_api()
+        payload = [{"itemType": "note", "note": text, "parentItem": item_key}]
+        async with api:
+            created = await api.create_items(payload)
+        if not created:
+            raise ZopError("Note creation rejected by server")
+        return cast(str, created[0]["key"])
+
+
+__all__ = ["NotesService"]

zop/services/pdf.py

@@ -0,0 +1,130 @@
+"""PDF service: read local PDF attachments."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+from pypdf import PdfReader
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.core.errors import NotFoundError, ZopError
+
+
+class OutlineEntry(TypedDict):
+    """A flat PDF outline entry: one bookmark, indexed by depth."""
+
+    section: int
+    title: str
+    page: int | None
+    depth: int
+
+
+class PdfService:
+    """PDF operations: read text, extract outline."""
+
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        if db_path is None:
+            raise ZopError("db_path required")
+        self._reader = SqliteReader(db_path)
+
+    def get_attachment_path(self, item_key: str) -> Path:
+        """Find the local PDF path for an item."""
+        path = self._reader.get_attachment_path(item_key)
+        if path is None or not path.exists():
+            raise NotFoundError(f"No local PDF attachment for item '{item_key}'")
+        return path
+
+    def read_text(self, item_key: str, *, max_chars: int = 200_000) -> str:
+        """Extract full text from the PDF (truncated to max_chars)."""
+        path = self.get_attachment_path(item_key)
+        reader = PdfReader(str(path))
+        chunks: list[str] = []
+        total = 0
+        for page in reader.pages:
+            try:
+                txt = page.extract_text() or ""
+            except Exception:
+                txt = ""
+            if total + len(txt) > max_chars:
+                remaining = max_chars - total
+                chunks.append(txt[:remaining])
+                chunks.append("\n\n[...truncated at max_chars]")
+                break
+            chunks.append(txt)
+            total += len(txt)
+        return "\n\n".join(chunks)
+
+    def get_outline(self, item_key: str) -> list[OutlineEntry]:
+        """Return the PDF outline (bookmarks) as a flat list."""
+        path = self.get_attachment_path(item_key)
+        reader = PdfReader(str(path))
+        out: list[OutlineEntry] = []
+
+        def _walk(items: object, depth: int) -> None:
+            if not isinstance(items, list):
+                return
+            for item in items:
+                if not isinstance(item, list):
+                    continue
+                # item[0] is a dict like {'/Title': '...', '/Page': IndirectObject(...)}
+                raw_title = item[0] if len(item) > 0 else None
+                title = ""
+                if isinstance(raw_title, dict):
+                    title = str(raw_title.get("/Title", ""))
+                elif raw_title is not None:
+                    title = str(raw_title)
+                try:
+                    raw_page = reader.get_destination_page_number(item)  # type: ignore[arg-type]
+                    page_num: int | None = raw_page + 1 if raw_page is not None else None
+                except Exception:
+                    page_num = None
+                out.append(
+                    {"section": len(out) + 1, "title": title, "page": page_num, "depth": depth}
+                )
+                # Recurse into sub-items (last element is list of sub-outlines)
+                if len(item) > 1 and isinstance(item[-1], list):
+                    _walk(item[-1], depth + 1)
+
+        outline = reader.outline
+        _walk(outline, 0)
+        return out
+
+    def read_section(
+        self, item_key: str, section_number: int, *, max_chars: int = 100_000
+    ) -> str:
+        """Read text from a specific outline section (1-indexed)."""
+        outline = self.get_outline(item_key)
+        if section_number < 1 or section_number > len(outline):
+            raise NotFoundError(
+                f"Section {section_number} not in outline (1-{len(outline)})"
+            )
+        # Find the next sibling/depth-0 section to know where to stop
+        start_page: int | None = outline[section_number - 1]["page"]
+        end_page: int | None = None
+        for next_sec in outline[section_number:]:
+            if next_sec["depth"] <= outline[section_number - 1]["depth"]:
+                end_page = next_sec["page"]
+                break
+        path = self.get_attachment_path(item_key)
+        reader = PdfReader(str(path))
+        start_idx = 0 if start_page is None else start_page - 1
+        end_idx = len(reader.pages) if end_page is None else end_page - 1
+        chunks: list[str] = []
+        total = 0
+        for i in range(start_idx, min(end_idx, len(reader.pages))):
+            try:
+                txt = reader.pages[i].extract_text() or ""
+            except Exception:
+                txt = ""
+            if total + len(txt) > max_chars:
+                remaining = max_chars - total
+                chunks.append(txt[:remaining])
+                chunks.append("\n[...truncated]")
+                break
+            chunks.append(txt)
+            total += len(txt)
+        return f"# {outline[section_number - 1]['title']}\n\n" + "\n\n".join(chunks)
+
+
+__all__ = ["OutlineEntry", "PdfService"]

zop/services/tags.py

@@ -0,0 +1,99 @@
+"""Tag service: batch tag operations."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from pathlib import Path
+from typing import cast
+
+from zop.adapters.sqlite_reader import SqliteReader
+from zop.adapters.zotero_api import ApiCreds, ZoteroApi
+from zop.core.errors import AuthError, ZopError
+
+
+class TagsService:
+    """Tag operations: list all tags, add/remove tags from items in batch."""
+
+    def __init__(
+        self,
+        db_path: Path | str | None = None,
+        *,
+        creds: ApiCreds | None = None,
+    ) -> None:
+        if db_path is None:
+            raise ZopError("db_path required")
+        self._db_path = Path(db_path)
+        self._creds = creds
+        self._reader = SqliteReader(self._db_path)
+
+    def list_all(self) -> list[dict[str, int | str]]:
+        return self._reader.list_all_tags()
+
+    def _require_api(self) -> ZoteroApi:
+        if not self._creds or not self._creds.api_key:
+            raise AuthError("API credentials required for write operations")
+        return ZoteroApi(self._creds)
+
+    async def add(
+        self, item_keys: Sequence[str], tags: Sequence[str]
+    ) -> tuple[list[str], list[tuple[str, Exception]]]:
+        """Add tags to items. Preserves existing tags. Per-item failures isolated."""
+        if not item_keys or not tags:
+            return [], []
+        api = self._require_api()
+        new_tag_set = {t.strip() for t in tags if t.strip()}
+
+        async with api:
+            async def _one(k: str) -> str:
+                item = await api.get_item(k)
+                existing = {tg.get("tag", "") for tg in item["data"].get("tags", [])}
+                merged = list(existing | new_tag_set)
+                payload = {"tags": [{"tag": t} for t in sorted(merged)]}
+                await api.update_item(k, payload, version=item["version"])
+                return k
+
+            results = await asyncio.gather(
+                *[_one(k) for k in item_keys], return_exceptions=True
+            )
+        ok: list[str] = []
+        fail: list[tuple[str, Exception]] = []
+        for k, r in zip(item_keys, results, strict=True):
+            if isinstance(r, Exception):
+                fail.append((k, r))
+            else:
+                ok.append(cast(str, r))
+        return ok, fail
+
+    async def remove(
+        self, item_keys: Sequence[str], tags: Sequence[str]
+    ) -> tuple[list[str], list[tuple[str, Exception]]]:
+        """Remove tags from items. Per-item failures isolated."""
+        if not item_keys or not tags:
+            return [], []
+        remove_set = {t.strip() for t in tags if t.strip()}
+        api = self._require_api()
+
+        async with api:
+            async def _one(k: str) -> str:
+                item = await api.get_item(k)
+                existing = [tg.get("tag", "") for tg in item["data"].get("tags", [])]
+                kept = [t for t in existing if t not in remove_set]
+                payload = {"tags": [{"tag": t} for t in kept]}
+                await api.update_item(k, payload, version=item["version"])
+                return k
+
+            results = await asyncio.gather(
+                *[_one(k) for k in item_keys], return_exceptions=True
+            )
+        ok: list[str] = []
+        fail: list[tuple[str, Exception]] = []
+        for k, r in zip(item_keys, results, strict=True):
+            if isinstance(r, Exception):
+                fail.append((k, r))
+            else:
+                ok.append(cast(str, r))
+        return ok, fail
+
+
+__all__ = ["TagsService"]