zotkit 0.1.0__py3-none-any.whl

zotkit/__init__.py

@@ -0,0 +1,5 @@
+"""zotkit — headless Zotero library management (Web API + WebDAV)."""
+from .core import Conventions, TagConventionError, Zot, lint_tags, load_conventions
+
+__all__ = ["Zot", "lint_tags", "load_conventions", "Conventions", "TagConventionError"]
+__version__ = "0.1.0"

zotkit/cli.py

@@ -0,0 +1,144 @@
+"""zotkit — CLI over zotkit.core.Zot.
+
+Subcommands: find, create, attach, fetch, tag, status, move, backup, lint.
+Write commands print what they did; `create` is dry-run unless --apply.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .core import Zot, lint_tags, load_conventions
+
+
+def _print_items(rows):
+    for r in rows:
+        print(f"{r['key']}  [{r['itemType']}]  {r['title'][:75]}")
+        print(f"    collections: {r['collections']}")
+        print(f"    tags: {r['tags']}")
+    print(f"\n{len(rows)} match(es)")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="zotkit", description="Headless Zotero library CLI")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("find", help="search items by title/tag/collection")
+    p.add_argument("--title"); p.add_argument("--tag"); p.add_argument("--collection")
+
+    p = sub.add_parser("create", help="create items from a JSON file (dry unless --apply)")
+    p.add_argument("--file", required=True); p.add_argument("--apply", action="store_true")
+    p.add_argument("--no-dedup", action="store_true")
+    p.add_argument("--loose-tags", action="store_true", help="warn instead of error on tag violations")
+
+    p = sub.add_parser("attach", help="attach a local file (WebDAV) to an item")
+    p.add_argument("--key"); p.add_argument("--pdf")
+    p.add_argument("--from", dest="src", help="a .created.json list (batch)")
+    p.add_argument("--all", action="store_true")
+
+    p = sub.add_parser("fetch", help="download attachment files from WebDAV")
+    p.add_argument("--key"); p.add_argument("--title"); p.add_argument("--collection")
+    p.add_argument("--out", default="downloads")
+
+    p = sub.add_parser("tag", help="add/remove tags on an item")
+    p.add_argument("key"); p.add_argument("tags", nargs="+")
+    p.add_argument("--rm", action="store_true", help="remove instead of add")
+
+    p = sub.add_parser("status", help="set reading status (replaces the status: tag)")
+    p.add_argument("key"); p.add_argument("value", help="e.g. to-read / reading / read")
+
+    p = sub.add_parser("move", help="move item to a collection (name or 'Parent :: Child')")
+    p.add_argument("key"); p.add_argument("collection")
+    p.add_argument("--add", action="store_true", help="add as extra home instead of replacing")
+
+    sub.add_parser("backup", help="full JSON backup to backups/ next to your .env")
+
+    p = sub.add_parser("lint", help="check tags against conventions.toml (no API calls)")
+    p.add_argument("tags", nargs="+")
+
+    a = ap.parse_args(argv)
+
+    if a.cmd == "lint":
+        conv = load_conventions()
+        if conv is None:
+            print("no conventions configured — add a conventions.toml next to your .env "
+                  "(see README); nothing to check")
+            return 0
+        problems = lint_tags(a.tags, conventions=conv, auto_load=False)
+        print("\n".join(problems) if problems else "OK")
+        return 1 if problems else 0
+
+    zot = Zot()
+
+    if a.cmd == "find":
+        _print_items(zot.find(a.title, a.tag, a.collection))
+
+    elif a.cmd == "create":
+        data = json.load(open(a.file))
+        items = data["items"] if isinstance(data, dict) else data
+        if not a.apply:
+            for d in items:
+                problems = lint_tags(d.get("tags", []), conventions=zot.conventions,
+                                     auto_load=False)
+                flag = ("  !! " + "; ".join(problems)) if problems else ""
+                print(f"  [dry] {d.get('collection')} | {d.get('title','')[:60]}{flag}")
+            print(f"{len(items)} item(s). DRY — add --apply to create.")
+            return 0
+        created = zot.create_items(items, dedup=not a.no_dedup, strict_tags=not a.loose_tags)
+        new = [c for c in created if c.get("key")]
+        out = Path(a.file).with_suffix(".created.json")
+        json.dump(new, open(out, "w"), ensure_ascii=False, indent=2)
+        print(f"created {len(new)} (skipped {len(created)-len(new)} dup) -> {out}")
+        if any(c.get("file_path") for c in new):
+            print(f"attach PDFs: zotkit attach --from {out} --all")
+
+    elif a.cmd == "attach":
+        if a.key and a.pdf:
+            print(zot.attach(a.key, a.pdf))
+        elif a.src:
+            rows = json.load(open(a.src))
+            done = 0
+            for m in rows:
+                if not m.get("file_path") or not Path(m["file_path"]).exists():
+                    print(f"  SKIP no file: {str(m.get('title'))[:55]}"); continue
+                if zot.has_attachment(m["key"]):
+                    print(f"  SKIP attached: {str(m.get('title'))[:55]}"); continue
+                if not a.all and done >= 1:
+                    break
+                print(f"- {str(m.get('title'))[:60]}")
+                zot.attach(m["key"], m["file_path"]); done += 1
+            print(f"attached {done}")
+        else:
+            ap.error("attach needs --key + --pdf, or --from <created.json>")
+
+    elif a.cmd == "fetch":
+        keys = [a.key] if a.key else [r["key"] for r in zot.find(a.title, None, a.collection)]
+        n = 0
+        for k in keys:
+            for p_ in zot.fetch(k, a.out):
+                print(f"  saved: {p_}"); n += 1
+        print(f"downloaded {n} file(s) to {a.out}")
+
+    elif a.cmd == "tag":
+        if a.rm:
+            zot.remove_tags(a.key, *a.tags); print(f"removed {a.tags} from {a.key}")
+        else:
+            zot.add_tags(a.key, *a.tags); print(f"added {a.tags} to {a.key}")
+
+    elif a.cmd == "status":
+        zot.set_status(a.key, a.value); print(f"{a.key} -> status:{a.value}")
+
+    elif a.cmd == "move":
+        zot.move(a.key, a.collection, add=a.add)
+        print(f"{a.key} -> '{a.collection}'{' (added)' if a.add else ''}")
+
+    elif a.cmd == "backup":
+        print("backup ->", zot.backup())
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

zotkit/core.py

@@ -0,0 +1,379 @@
+"""zotkit.core — headless Zotero library management (Web API + WebDAV).
+
+One class, `Zot`, wraps the Zotero Web API (pyzotero) and, for libraries whose
+attachment files sync to a personal WebDAV server, reads AND writes the WebDAV
+attachment store directly — no desktop app required (see docs/webdav-format.md).
+
+Credentials are read from an .env file (see `load_env` for the search order).
+Tag conventions can optionally be enforced in code via a conventions.toml file
+next to the .env (see `load_conventions`); without one, tags are unrestricted.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import mimetypes
+import os
+import re
+import tomllib
+import zipfile
+from pathlib import Path
+from typing import Any
+
+import httpx
+from pyzotero import zotero
+
+ENV_VARS = ("ZOTKIT_ENV", "ZOT_ENV")
+
+
+class TagConventionError(ValueError):
+    """Raised when tags violate the configured conventions."""
+
+
+# ---------- configuration ----------
+
+def _env_candidates(path: str | os.PathLike | None = None) -> list[Path]:
+    if path:
+        return [Path(path)]
+    cands = [Path(os.environ[v]) for v in ENV_VARS if os.environ.get(v)]
+    cands.append(Path.cwd() / ".env")
+    cands.append(Path.home() / ".config" / "zotkit" / "env")
+    return cands
+
+
+def load_env(path: str | os.PathLike | None = None) -> dict[str, str]:
+    """Load KEY=VALUE credentials. Search order: explicit path, $ZOTKIT_ENV,
+    ./.env, ~/.config/zotkit/env. Symlinks resolve to their target."""
+    cands = _env_candidates(path)
+    for p in cands:
+        if not p.is_file():
+            continue
+        env: dict[str, str] = {}
+        for line in p.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                k, v = line.split("=", 1)
+                env[k.strip()] = v.strip()
+        env["_env_path"] = str(p.resolve())
+        return env
+    raise FileNotFoundError(
+        "no zotkit config found — looked for: "
+        + ", ".join(str(p) for p in cands)
+        + ". Copy .env.example to one of these locations (see README → Configure).")
+
+
+class Conventions:
+    """Tag rules loaded from conventions.toml (all sections optional):
+
+    namespaces = ["field", "topic", "status"]   # allowed prefixes
+    require = ["field"]                         # every NEW item needs one such tag
+    [closed]                                    # namespaces with a fixed vocabulary
+    field = ["physics", "ml", "econ"]
+    status = ["to-read", "reading", "read"]
+    """
+
+    def __init__(self, data: dict):
+        self.namespaces: set[str] = set(data.get("namespaces", []))
+        self.require: set[str] = set(data.get("require", []))
+        self.closed: dict[str, set[str]] = {
+            ns: {f"{ns}:{v}" for v in vals}
+            for ns, vals in data.get("closed", {}).items()}
+
+
+def load_conventions(env_dir: str | os.PathLike | None = None) -> Conventions | None:
+    """Find conventions.toml: $ZOTKIT_CONVENTIONS, next to the .env in use,
+    then ~/.config/zotkit/. Returns None (= no enforcement) if absent."""
+    cands = []
+    if os.environ.get("ZOTKIT_CONVENTIONS"):
+        cands.append(Path(os.environ["ZOTKIT_CONVENTIONS"]))
+    if env_dir:
+        cands.append(Path(env_dir) / "conventions.toml")
+    else:
+        for p in _env_candidates():
+            if p.is_file():
+                cands.append(p.resolve().parent / "conventions.toml")
+                break
+    cands.append(Path.home() / ".config" / "zotkit" / "conventions.toml")
+    for p in cands:
+        if p.is_file():
+            return Conventions(tomllib.loads(p.read_text()))
+    return None
+
+
+def lint_tags(tags: list[str], *, for_new_item: bool = True,
+              conventions: Conventions | None = None,
+              auto_load: bool = True) -> list[str]:
+    """Return a list of convention problems (empty = OK).
+    With no conventions configured, everything passes."""
+    conv = conventions or (load_conventions() if auto_load else None)
+    if conv is None:
+        return []
+    problems = []
+    if for_new_item:
+        for ns in sorted(conv.require):
+            if not any(t.startswith(f"{ns}:") for t in tags):
+                vocab = sorted(conv.closed.get(ns, [])) or f"{ns}:*"
+                problems.append(f"missing a '{ns}:' tag (every new item needs one of {vocab})")
+    for t in tags:
+        if ":" not in t:
+            problems.append(f"'{t}' has no namespace (expected one of "
+                            f"{sorted(conv.namespaces) or 'ns:value'})")
+            continue
+        ns, _ = t.split(":", 1)
+        if conv.namespaces and ns not in conv.namespaces:
+            problems.append(f"'{t}' uses unknown namespace '{ns}:'")
+        if t != t.lower() or " " in t or "_" in t:
+            problems.append(f"'{t}' must be lowercase-hyphenated")
+        if ns in conv.closed and t not in conv.closed[ns]:
+            problems.append(f"'{t}' not in the configured '{ns}:' vocabulary "
+                            f"{sorted(conv.closed[ns])}")
+    return problems
+
+
+# ---------- helpers ----------
+
+def _norm_title(t: str | None) -> str:
+    return re.sub(r"\W+", " ", (t or "").lower()).strip()
+
+
+def _md5_file(p: Path) -> str:
+    h = hashlib.md5()
+    with open(p, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 16), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+class Zot:
+    """Unified library interface: search, create, tag, move, attach, fetch, backup."""
+
+    def __init__(self, env_path: str | os.PathLike | None = None):
+        self.env = load_env(env_path)
+        self.home = Path(self.env["_env_path"]).parent  # config dir: backups etc.
+        self.conventions = load_conventions(self.home)
+        self.z = zotero.Zotero(self.env["ZOTERO_LIBRARY_ID"],
+                               self.env.get("ZOTERO_LIBRARY_TYPE", "user"),
+                               self.env["ZOTERO_API_KEY"])
+        self._cols: list[dict] | None = None
+
+    def _lint(self, tags: list[str], *, for_new_item: bool) -> list[str]:
+        return lint_tags(tags, for_new_item=for_new_item,
+                         conventions=self.conventions, auto_load=False)
+
+    # ---------- collections ----------
+    def collections(self, refresh: bool = False) -> list[dict]:
+        if self._cols is None or refresh:
+            self._cols = self.z.everything(self.z.collections())
+        return self._cols
+
+    def collection_key(self, name: str) -> str | None:
+        """Resolve a collection by exact name, or 'Parent :: Child'."""
+        cols = self.collections()
+        if "::" in name:
+            parent, child = [s.strip() for s in name.split("::", 1)]
+            pk = next((c["key"] for c in cols if c["data"]["name"] == parent
+                       and not c["data"].get("parentCollection")), None)
+            return next((c["key"] for c in cols if c["data"]["name"] == child
+                         and c["data"].get("parentCollection") == pk), None)
+        return next((c["key"] for c in cols if c["data"]["name"] == name), None)
+
+    def collection_names(self) -> dict[str, str]:
+        return {c["key"]: c["data"]["name"] for c in self.collections()}
+
+    # ---------- search ----------
+    def find(self, title: str | None = None, tag: str | None = None,
+             collection: str | None = None) -> list[dict]:
+        """Search top-level items; returns slim records with key/type/title/collections/tags."""
+        ckey = self.collection_key(collection) if collection else None
+        if collection and not ckey:
+            raise KeyError(f"no collection named '{collection}'")
+        cname = self.collection_names()
+        out = []
+        for it in self.z.everything(self.z.top()):
+            d = it["data"]
+            tags = [t["tag"] for t in d.get("tags", [])]
+            if title and title.lower() not in d.get("title", "").lower():
+                continue
+            if tag and tag not in tags:
+                continue
+            if ckey and ckey not in d.get("collections", []):
+                continue
+            out.append({"key": it["key"], "itemType": d.get("itemType"),
+                        "title": d.get("title", ""),
+                        "collections": [cname.get(c, c) for c in d.get("collections", [])],
+                        "tags": tags, "version": d.get("version")})
+        return out
+
+    # ---------- create ----------
+    def create_items(self, items: list[dict[str, Any]], *, dedup: bool = True,
+                     strict_tags: bool = True) -> list[dict]:
+        """Create bibliographic items. Each dict: itemType/title/creators/... plus
+        tags: [str], collection: name, file_path: optional (carried through).
+        Validates tags against the configured conventions (raise if strict_tags)."""
+        existing = self.z.everything(self.z.top()) if dedup else []
+        seen_doi = {(it["data"].get("DOI") or "").strip().lower()
+                    for it in existing if it["data"].get("DOI")}
+        seen_title = {_norm_title(it["data"].get("title")) for it in existing}
+
+        templates: dict[str, dict] = {}
+        payloads, meta = [], []
+        for d in items:
+            tags = d.get("tags", [])
+            problems = self._lint(tags, for_new_item=True)
+            if problems:
+                msg = f"tags for '{d.get('title','')[:50]}': " + "; ".join(problems)
+                if strict_tags:
+                    raise TagConventionError(msg)
+                print("WARN", msg)
+            doi = (d.get("DOI") or "").strip().lower()
+            if dedup and ((doi and doi in seen_doi) or _norm_title(d.get("title")) in seen_title):
+                meta.append({"title": d.get("title"), "skipped": "duplicate"})
+                continue
+            t = d["itemType"]
+            templates.setdefault(t, self.z.item_template(t))
+            tmpl = json.loads(json.dumps(templates[t]))
+            for f, v in d.items():
+                if f not in ("tags", "collection", "file_path") and f in tmpl:
+                    tmpl[f] = v
+            tmpl["tags"] = [{"tag": x} for x in tags]
+            ck = self.collection_key(d["collection"]) if d.get("collection") else None
+            if d.get("collection") and not ck:
+                raise KeyError(f"no collection named '{d['collection']}'")
+            tmpl["collections"] = [ck] if ck else []
+            payloads.append(tmpl)
+            meta.append({"title": d.get("title"), "collection": d.get("collection"),
+                         "file_path": d.get("file_path")})
+
+        created, mi = [], iter([m for m in meta if "skipped" not in m])
+        for i in range(0, len(payloads), 50):
+            resp = self.z.create_items(payloads[i:i + 50])
+            if resp.get("failed"):
+                raise RuntimeError(f"create failed: {resp['failed']}")
+            batch_meta = [next(mi) for _ in range(len(payloads[i:i + 50]))]
+            for idx, obj in sorted(resp.get("successful", {}).items(), key=lambda x: int(x[0])):
+                created.append({**batch_meta[int(idx)], "key": obj["key"]})
+        skipped = [m for m in meta if m.get("skipped")]
+        return created + skipped
+
+    # ---------- tags / status / move ----------
+    def add_tags(self, item_key: str, *tags: str, strict: bool = True) -> None:
+        problems = self._lint(list(tags), for_new_item=False)
+        if problems and strict:
+            raise TagConventionError("; ".join(problems))
+        it = self.z.item(item_key)
+        have = {t["tag"] for t in it["data"].get("tags", [])}
+        new = [{"tag": t} for t in tags if t not in have]
+        if new:
+            it["data"]["tags"] = it["data"]["tags"] + new
+            self.z.update_item(it)
+
+    def remove_tags(self, item_key: str, *tags: str) -> None:
+        it = self.z.item(item_key)
+        it["data"]["tags"] = [t for t in it["data"].get("tags", []) if t["tag"] not in tags]
+        self.z.update_item(it)
+
+    def set_status(self, item_key: str, status: str) -> None:
+        """Replace the item's status: tag. Validated against the conventions'
+        closed 'status' vocabulary when one is configured."""
+        tag = status if status.startswith("status:") else f"status:{status}"
+        conv = self.conventions
+        if conv and "status" in conv.closed and tag not in conv.closed["status"]:
+            raise TagConventionError(f"'{tag}' not in {sorted(conv.closed['status'])}")
+        it = self.z.item(item_key)
+        kept = [t for t in it["data"].get("tags", []) if not t["tag"].startswith("status:")]
+        it["data"]["tags"] = kept + [{"tag": tag}]
+        self.z.update_item(it)
+
+    def move(self, item_key: str, collection: str, *, add: bool = False) -> None:
+        """Move item to a collection (replaces homes unless add=True)."""
+        ck = self.collection_key(collection)
+        if not ck:
+            raise KeyError(f"no collection named '{collection}'")
+        it = self.z.item(item_key)
+        cur = it["data"].get("collections", [])
+        it["data"]["collections"] = (cur + [ck]) if (add and ck not in cur) else [ck]
+        self.z.update_item(it)
+
+    # ---------- attachments (WebDAV) ----------
+    def _webdav(self) -> tuple[str, tuple[str, str]]:
+        try:
+            return (self.env["WEBDAV_URL"].rstrip("/"),
+                    (self.env["WEBDAV_USER"], self.env["WEBDAV_PASS"]))
+        except KeyError as e:
+            raise KeyError(f"{e.args[0]} missing from .env — attachment operations "
+                           "need WEBDAV_URL/WEBDAV_USER/WEBDAV_PASS") from None
+
+    def attach(self, item_key: str, file_path: str | os.PathLike) -> dict:
+        """Attach a local file to an item; bytes go to WebDAV (<key>.zip + .prop)."""
+        f = Path(file_path)
+        filename, md5 = f.name, _md5_file(f)
+        mtime = int(os.path.getmtime(f) * 1000)
+        ctype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        tmpl = self.z.item_template("attachment", "imported_file")
+        tmpl.update({"parentItem": item_key, "title": filename, "filename": filename,
+                     "contentType": ctype, "md5": md5, "mtime": mtime})
+        resp = self.z.create_items([tmpl])
+        if resp.get("failed"):
+            raise RuntimeError(f"attachment item failed: {resp['failed']}")
+        key = resp["successful"]["0"]["key"]
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+            z.write(f, arcname=filename)
+        prop = (f'<properties version="1"><mtime>{mtime}</mtime>'
+                f'<hash>{md5}</hash></properties>')
+        base, auth = self._webdav()
+        with httpx.Client(auth=auth, timeout=120) as c:
+            r1 = c.put(f"{base}/{key}.zip", content=buf.getvalue())
+            r2 = c.put(f"{base}/{key}.prop", content=prop.encode())
+        ok = r1.status_code in (200, 201, 204) and r2.status_code in (200, 201, 204)
+        if not ok:
+            raise RuntimeError(f"WebDAV PUT failed: zip={r1.status_code} prop={r2.status_code}")
+        return {"attachment_key": key, "filename": filename, "webdav_ok": ok}
+
+    def has_attachment(self, item_key: str) -> bool:
+        return any(k["data"].get("itemType") == "attachment"
+                   for k in self.z.children(item_key))
+
+    def fetch(self, item_key: str, out_dir: str | os.PathLike = "downloads") -> list[Path]:
+        """Download an item's attachment files from WebDAV; returns saved paths."""
+        out = Path(out_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        base, auth = self._webdav()
+        saved = []
+        with httpx.Client(auth=auth, timeout=120) as c:
+            for ch in self.z.children(item_key):
+                d = ch["data"]
+                if d.get("itemType") != "attachment" or not d.get("filename"):
+                    continue
+                r = c.get(f"{base}/{ch['key']}.zip")
+                if r.status_code != 200:
+                    continue
+                zipfile.ZipFile(io.BytesIO(r.content)).extractall(out)
+                saved.append(out / d["filename"])
+        return saved
+
+    # ---------- backup ----------
+    def backup(self, out_dir: str | os.PathLike | None = None) -> Path:
+        """Full JSON backup (items + collections + membership snapshots).
+        Default destination: backups/ next to the .env in use."""
+        version = self.z.last_modified_version()
+        items = self.z.everything(self.z.items())
+        collections = self.z.everything(self.z.collections())
+        try:
+            searches = self.z.everything(self.z.searches())
+        except Exception:
+            searches = []
+        backup = {
+            "last_modified_version": version,
+            "items": items, "collections": collections, "searches": searches,
+            "item_tags": {it["key"]: [t.get("tag") for t in it["data"].get("tags", [])]
+                          for it in items if "data" in it},
+            "item_collections": {it["key"]: it["data"].get("collections", [])
+                                 for it in items if "data" in it},
+        }
+        out = Path(out_dir or (self.home / "backups"))
+        out.mkdir(parents=True, exist_ok=True)
+        p = out / f"zotero_backup_v{version}.json"
+        p.write_text(json.dumps(backup, ensure_ascii=False, indent=2))
+        return p

zotkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: zotkit
+Version: 0.1.0
+Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
+Author: Shawn
+License-Expression: MIT
+Project-URL: Repository, https://github.com/oldantique/zotkit
+Project-URL: Issues, https://github.com/oldantique/zotkit/issues
+Keywords: zotero,reference-manager,webdav,bibliography,cli,headless
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyzotero
+Requires-Dist: httpx
+Dynamic: license-file
+
+# zotkit
+
+**Headless Zotero library management — no desktop app required.**
+
+zotkit is a Python library + CLI that manages a Zotero library entirely through the
+[Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start): search, create,
+tag, and organize items from a terminal or a server. Uniquely, if your attachments sync
+to a **personal WebDAV server**, zotkit can **upload and download the files themselves**
+by speaking Zotero's WebDAV storage format directly — the one capability the Web API
+does not provide, and (as far as we know) not offered by any other headless tool.
+
+Built for servers, scripts, and **LLM agents**: every write is dry-run by default,
+batched, and version-checked, and you can define a tag taxonomy that is *enforced in
+code* so an agent (or a tired human) can't pollute your library with inconsistent tags.
+
+## Why zotkit
+
+| | Desktop app | Other CLI/MCP tools | zotkit |
+|---|---|---|---|
+| Works headless (server, SSH, CI) | ❌ | ✅ read-mostly | ✅ |
+| Write items/tags/collections | ✅ | ⚠️ usually needs the desktop app running | ✅ |
+| Attachment files on **WebDAV** | ✅ | ⚠️ download at best | ✅ **upload + download** |
+| Tag conventions enforced in code | ❌ | ❌ | ✅ optional `conventions.toml` |
+
+## Install
+
+```bash
+pipx install zotkit        # or: uv tool install zotkit / pip install zotkit
+uvx zotkit --help          # …or try it without installing anything
+```
+
+## Configure
+
+Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any path in
+`$ZOTKIT_ENV`, and fill in:
+
+- **Zotero Web API**: create a key (with write access) at
+  <https://www.zotero.org/settings/keys> — your numeric `ZOTERO_LIBRARY_ID` is shown on
+  the same page.
+- **WebDAV** (only for `attach`/`fetch`): copy the exact values from the Zotero desktop
+  app on any of your machines — **Settings → Sync → File Syncing** — and append
+  `/zotero/` to the URL (the desktop does this implicitly).
+
+Optionally, copy [`conventions.example.toml`](conventions.example.toml) to
+`conventions.toml` next to your `.env` to define a namespaced tag taxonomy
+(`field:physics`, `status:to-read`, …). With it in place, `zotkit create` / `zotkit tag`
+**reject** violations; without it, tags are unrestricted.
+
+## Quickstart
+
+```bash
+zotkit find --title "boson sampling"        # search by title/tag/collection
+zotkit find --tag status:to-read
+
+zotkit create --file papers.json            # dry-run: shows what would be created
+zotkit create --file papers.json --apply    # create (dedups by DOI/title)
+zotkit attach --from papers.created.json --all   # upload the PDFs to WebDAV
+
+zotkit attach --key AB12CD34 --pdf paper.pdf     # single attach
+zotkit fetch --key AB12CD34 --out downloads      # download attachment from WebDAV
+
+zotkit tag AB12CD34 topic:qaoa prio:high    # validated against conventions.toml
+zotkit status AB12CD34 read                 # replaces the status: tag
+zotkit move AB12CD34 "Algorithms"           # or "Parent :: Child"; --add keeps old home
+
+zotkit backup                               # full JSON snapshot -> backups/
+zotkit lint field:physics topic:new-idea    # offline tag check
+```
+
+Item JSON for `zotkit create` (a list, one object per reference):
+
+```json
+[{"itemType": "journalArticle", "title": "…",
+  "creators": [{"creatorType": "author", "firstName": "A", "lastName": "B"}],
+  "date": "2024", "publicationTitle": "…", "DOI": "10.x/y",
+  "tags": ["field:physics", "status:to-read"],
+  "collection": "Algorithms", "file_path": "/abs/path/paper.pdf"}]
+```
+
+## From Python
+
+```python
+from zotkit import Zot
+
+z = Zot()                                   # reads .env automatically
+z.find(tag="status:to-read")
+z.create_items([...])                       # dedup + convention checks
+z.attach("AB12CD34", "paper.pdf")           # PDF -> WebDAV
+z.fetch("AB12CD34", "downloads")
+z.set_status("AB12CD34", "read")
+z.backup()
+```
+
+`z.z` is the underlying [pyzotero](https://github.com/urschrei/pyzotero) client for
+anything not wrapped.
+
+## Safety model
+
+- `create` is **dry-run by default**; `--apply` to execute.
+- Writes go through fetch→modify→update (carries the item version, so concurrent edits
+  fail loudly with 412 instead of clobbering), in batches of ≤ 50.
+- `zotkit backup` snapshots every item, collection, tag, and membership to one JSON
+  file — run it before bulk operations.
+- Remember: writes propagate to zotero.org and **all your synced devices**.
+
+## How WebDAV attachments work
+
+Zotero's WebDAV storage format is undocumented but simple: each attachment item `K` is
+stored as `K.zip` (the file, zipped) plus `K.prop` (its md5 + mtime). zotkit creates the
+attachment item via the Web API and PUTs both objects directly — after which every
+desktop client syncs the file down normally. Details in
+[`docs/webdav-format.md`](docs/webdav-format.md).
+
+The format was determined by interoperability inspection of the author's own library.
+This project is not affiliated with or endorsed by Zotero.
+
+## License
+
+[MIT](LICENSE). If you build on the WebDAV implementation, a link back is appreciated.

zotkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+zotkit/__init__.py,sha256=z1RrkPaeu2f3UugtDiDiusqNO72_lg_3f2debonpT1o,267
+zotkit/cli.py,sha256=xMC3v-Cl5IT5Ig8N_3aJrO4s3fI4x6-9E7mT-yWkPIo,5925
+zotkit/core.py,sha256=mq87oAL61UuBxpftfZkHpLndmJMISI8ajRjsYKwbz-U,17294
+zotkit-0.1.0.dist-info/licenses/LICENSE,sha256=mabKMS4Wfqdt7A0wB3chgG4BNfaVYO84xHK-ynNZRJ8,1062
+zotkit-0.1.0.dist-info/METADATA,sha256=xkIA-DRZfWx_aRWCOmg1lteyFmUZgwhC6ENdpiciMM0,5873
+zotkit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+zotkit-0.1.0.dist-info/entry_points.txt,sha256=pr3_2uuZH_RtWCHLb2m1Xe3cWxaJ8YqAB52thNNh7XE,43
+zotkit-0.1.0.dist-info/top_level.txt,sha256=rKtf4ccLNKFusfWu5_kFMDKPrktgQgNDhSjMDhjkPmU,7
+zotkit-0.1.0.dist-info/RECORD,,

zotkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zotkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zotkit = zotkit.cli:main

zotkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zotkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zotkit