zotkit 0.1.0__tar.gz → 0.2.0__tar.gz

{zotkit-0.1.0/zotkit.egg-info → zotkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -22,12 +22,14 @@ Dynamic: license-file
 
 **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.
+"Headless" simply means zotkit never needs the Zotero app (or any window) open: it is a
+Python library + CLI that talks straight to the
+[Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start), so you can
+search, create, tag, and organize items from any terminal — macOS, Windows, or Linux,
+your laptop or a remote 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
@@ -39,11 +41,15 @@ code* so an agent (or a tired human) can't pollute your library with inconsisten
 |---|---|---|---|
 | Works headless (server, SSH, CI) | ❌ | ✅ read-mostly | ✅ |
 | Write items/tags/collections | ✅ | ⚠️ usually needs the desktop app running | ✅ |
+| Attachment files (Zotero Storage) | ✅ | ⚠️ some | ✅ upload + download |
 | Attachment files on **WebDAV** | ✅ | ⚠️ download at best | ✅ **upload + download** |
 | Tag conventions enforced in code | ❌ | ❌ | ✅ optional `conventions.toml` |
 
 ## Install
 
+Pure Python (3.11+), no platform-specific bits — the same package works on macOS,
+Windows, and Linux:
+
 ```bash
 pipx install zotkit        # or: uv tool install zotkit / pip install zotkit
 uvx zotkit --help          # …or try it without installing anything
@@ -60,6 +66,9 @@ Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any
 - **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).
+- **Using Zotero Storage instead of WebDAV?** Just leave the `WEBDAV_*` lines out —
+  `attach`/`fetch` automatically use Zotero Storage through the Web API's upload/download
+  endpoints instead. The storage mode is detected from your `.env`, nothing to configure.
 
 Optionally, copy [`conventions.example.toml`](conventions.example.toml) to
 `conventions.toml` next to your `.env` to define a namespaced tag taxonomy
@@ -114,6 +123,22 @@ z.backup()
 `z.z` is the underlying [pyzotero](https://github.com/urschrei/pyzotero) client for
 anything not wrapped.
 
+## Using zotkit with AI agents
+
+zotkit is designed to be driven by coding agents (Claude Code and similar): dry-run
+defaults, code-enforced tag conventions, and a ready-made **Claude Code skill** in
+[`skills/zotkit/`](skills/zotkit/SKILL.md) — copy it to `~/.claude/skills/zotkit/` and
+any Claude session can search, file, and attach papers for you while respecting your
+taxonomy. (An MCP server is planned.)
+
+Want to clean up a messy library, not just maintain one? The battle-tested method —
+taxonomy design, parallel read-only analysis, serial reviewed writes — is written up in
+[`docs/organizing-with-agents.md`](docs/organizing-with-agents.md).
+
+```bash
+mkdir -p ~/.claude/skills && cp -r skills/zotkit ~/.claude/skills/
+```
+
 ## Safety model
 
 - `create` is **dry-run by default**; `--apply` to execute.
@@ -125,11 +150,12 @@ anything not wrapped.
 
 ## 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).
+(With Zotero Storage, zotkit simply uses the Web API's official file endpoints — this
+section is about the WebDAV mode.) 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.

{zotkit-0.1.0 → zotkit-0.2.0}/README.md

@@ -2,12 +2,14 @@
 
 **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.
+"Headless" simply means zotkit never needs the Zotero app (or any window) open: it is a
+Python library + CLI that talks straight to the
+[Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start), so you can
+search, create, tag, and organize items from any terminal — macOS, Windows, or Linux,
+your laptop or a remote 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
@@ -19,11 +21,15 @@ code* so an agent (or a tired human) can't pollute your library with inconsisten
 |---|---|---|---|
 | Works headless (server, SSH, CI) | ❌ | ✅ read-mostly | ✅ |
 | Write items/tags/collections | ✅ | ⚠️ usually needs the desktop app running | ✅ |
+| Attachment files (Zotero Storage) | ✅ | ⚠️ some | ✅ upload + download |
 | Attachment files on **WebDAV** | ✅ | ⚠️ download at best | ✅ **upload + download** |
 | Tag conventions enforced in code | ❌ | ❌ | ✅ optional `conventions.toml` |
 
 ## Install
 
+Pure Python (3.11+), no platform-specific bits — the same package works on macOS,
+Windows, and Linux:
+
 ```bash
 pipx install zotkit        # or: uv tool install zotkit / pip install zotkit
 uvx zotkit --help          # …or try it without installing anything
@@ -40,6 +46,9 @@ Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any
 - **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).
+- **Using Zotero Storage instead of WebDAV?** Just leave the `WEBDAV_*` lines out —
+  `attach`/`fetch` automatically use Zotero Storage through the Web API's upload/download
+  endpoints instead. The storage mode is detected from your `.env`, nothing to configure.
 
 Optionally, copy [`conventions.example.toml`](conventions.example.toml) to
 `conventions.toml` next to your `.env` to define a namespaced tag taxonomy
@@ -94,6 +103,22 @@ z.backup()
 `z.z` is the underlying [pyzotero](https://github.com/urschrei/pyzotero) client for
 anything not wrapped.
 
+## Using zotkit with AI agents
+
+zotkit is designed to be driven by coding agents (Claude Code and similar): dry-run
+defaults, code-enforced tag conventions, and a ready-made **Claude Code skill** in
+[`skills/zotkit/`](skills/zotkit/SKILL.md) — copy it to `~/.claude/skills/zotkit/` and
+any Claude session can search, file, and attach papers for you while respecting your
+taxonomy. (An MCP server is planned.)
+
+Want to clean up a messy library, not just maintain one? The battle-tested method —
+taxonomy design, parallel read-only analysis, serial reviewed writes — is written up in
+[`docs/organizing-with-agents.md`](docs/organizing-with-agents.md).
+
+```bash
+mkdir -p ~/.claude/skills && cp -r skills/zotkit ~/.claude/skills/
+```
+
 ## Safety model
 
 - `create` is **dry-run by default**; `--apply` to execute.
@@ -105,11 +130,12 @@ anything not wrapped.
 
 ## 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).
+(With Zotero Storage, zotkit simply uses the Web API's official file endpoints — this
+section is about the WebDAV mode.) 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.

{zotkit-0.1.0 → zotkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zotkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required"
 readme = "README.md"
 license = "MIT"

{zotkit-0.1.0 → zotkit-0.2.0}/zotkit/__init__.py

@@ -2,4 +2,4 @@
 from .core import Conventions, TagConventionError, Zot, lint_tags, load_conventions
 
 __all__ = ["Zot", "lint_tags", "load_conventions", "Conventions", "TagConventionError"]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{zotkit-0.1.0 → zotkit-0.2.0}/zotkit/cli.py

@@ -76,7 +76,7 @@ def main(argv=None):
         _print_items(zot.find(a.title, a.tag, a.collection))
 
     elif a.cmd == "create":
-        data = json.load(open(a.file))
+        data = json.load(open(a.file, encoding="utf-8"))
         items = data["items"] if isinstance(data, dict) else data
         if not a.apply:
             for d in items:
@@ -89,7 +89,7 @@ def main(argv=None):
         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)
+        json.dump(new, open(out, "w", encoding="utf-8"), 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")
@@ -98,7 +98,7 @@ def main(argv=None):
         if a.key and a.pdf:
             print(zot.attach(a.key, a.pdf))
         elif a.src:
-            rows = json.load(open(a.src))
+            rows = json.load(open(a.src, encoding="utf-8"))
             done = 0
             for m in rows:
                 if not m.get("file_path") or not Path(m["file_path"]).exists():

{zotkit-0.1.0 → zotkit-0.2.0}/zotkit/core.py

@@ -50,7 +50,7 @@ def load_env(path: str | os.PathLike | None = None) -> dict[str, str]:
         if not p.is_file():
             continue
         env: dict[str, str] = {}
-        for line in p.read_text().splitlines():
+        for line in p.read_text(encoding="utf-8").splitlines():
             line = line.strip()
             if line and not line.startswith("#") and "=" in line:
                 k, v = line.split("=", 1)
@@ -97,7 +97,7 @@ def load_conventions(env_dir: str | os.PathLike | None = None) -> Conventions |
     cands.append(Path.home() / ".config" / "zotkit" / "conventions.toml")
     for p in cands:
         if p.is_file():
-            return Conventions(tomllib.loads(p.read_text()))
+            return Conventions(tomllib.loads(p.read_text(encoding="utf-8")))
     return None
 
 
@@ -305,8 +305,19 @@ class Zot:
                            "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)."""
+        """Attach a local file to an item. Bytes go to WebDAV (<key>.zip + .prop)
+        when WEBDAV_* is configured, otherwise to Zotero Storage via the Web API."""
         f = Path(file_path)
+        if "WEBDAV_URL" not in self.env:
+            resp = self.z.attachment_simple([str(f)], item_key)
+            done = (resp.get("success") or []) + (resp.get("unchanged") or [])
+            if not done:
+                raise RuntimeError(f"Zotero Storage upload failed: {resp}")
+            entry = done[0]
+            key = ""
+            if isinstance(entry, dict):
+                key = entry.get("key") or entry.get("data", {}).get("key", "")
+            return {"attachment_key": key, "filename": f.name, "storage": "zotero"}
         filename, md5 = f.name, _md5_file(f)
         mtime = int(os.path.getmtime(f) * 1000)
         ctype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
@@ -329,28 +340,36 @@ class Zot:
         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}
+        return {"attachment_key": key, "filename": filename, "storage": "webdav"}
 
     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."""
+        """Download an item's attachment files (from WebDAV when configured,
+        otherwise from Zotero Storage); returns saved paths."""
         out = Path(out_dir)
         out.mkdir(parents=True, exist_ok=True)
+        saved: list[Path] = []
+        atts = [ch for ch in self.z.children(item_key)
+                if ch["data"].get("itemType") == "attachment" and ch["data"].get("filename")]
+        if "WEBDAV_URL" not in self.env:
+            for ch in atts:
+                try:
+                    self.z.dump(ch["key"], ch["data"]["filename"], str(out))
+                    saved.append(out / ch["data"]["filename"])
+                except Exception:
+                    continue
+            return saved
         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
+            for ch in atts:
                 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"])
+                saved.append(out / ch["data"]["filename"])
         return saved
 
     # ---------- backup ----------
@@ -375,5 +394,5 @@ class Zot:
         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))
+        p.write_text(json.dumps(backup, ensure_ascii=False, indent=2), encoding="utf-8")
         return p

{zotkit-0.1.0 → zotkit-0.2.0/zotkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -22,12 +22,14 @@ Dynamic: license-file
 
 **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.
+"Headless" simply means zotkit never needs the Zotero app (or any window) open: it is a
+Python library + CLI that talks straight to the
+[Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start), so you can
+search, create, tag, and organize items from any terminal — macOS, Windows, or Linux,
+your laptop or a remote 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
@@ -39,11 +41,15 @@ code* so an agent (or a tired human) can't pollute your library with inconsisten
 |---|---|---|---|
 | Works headless (server, SSH, CI) | ❌ | ✅ read-mostly | ✅ |
 | Write items/tags/collections | ✅ | ⚠️ usually needs the desktop app running | ✅ |
+| Attachment files (Zotero Storage) | ✅ | ⚠️ some | ✅ upload + download |
 | Attachment files on **WebDAV** | ✅ | ⚠️ download at best | ✅ **upload + download** |
 | Tag conventions enforced in code | ❌ | ❌ | ✅ optional `conventions.toml` |
 
 ## Install
 
+Pure Python (3.11+), no platform-specific bits — the same package works on macOS,
+Windows, and Linux:
+
 ```bash
 pipx install zotkit        # or: uv tool install zotkit / pip install zotkit
 uvx zotkit --help          # …or try it without installing anything
@@ -60,6 +66,9 @@ Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any
 - **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).
+- **Using Zotero Storage instead of WebDAV?** Just leave the `WEBDAV_*` lines out —
+  `attach`/`fetch` automatically use Zotero Storage through the Web API's upload/download
+  endpoints instead. The storage mode is detected from your `.env`, nothing to configure.
 
 Optionally, copy [`conventions.example.toml`](conventions.example.toml) to
 `conventions.toml` next to your `.env` to define a namespaced tag taxonomy
@@ -114,6 +123,22 @@ z.backup()
 `z.z` is the underlying [pyzotero](https://github.com/urschrei/pyzotero) client for
 anything not wrapped.
 
+## Using zotkit with AI agents
+
+zotkit is designed to be driven by coding agents (Claude Code and similar): dry-run
+defaults, code-enforced tag conventions, and a ready-made **Claude Code skill** in
+[`skills/zotkit/`](skills/zotkit/SKILL.md) — copy it to `~/.claude/skills/zotkit/` and
+any Claude session can search, file, and attach papers for you while respecting your
+taxonomy. (An MCP server is planned.)
+
+Want to clean up a messy library, not just maintain one? The battle-tested method —
+taxonomy design, parallel read-only analysis, serial reviewed writes — is written up in
+[`docs/organizing-with-agents.md`](docs/organizing-with-agents.md).
+
+```bash
+mkdir -p ~/.claude/skills && cp -r skills/zotkit ~/.claude/skills/
+```
+
 ## Safety model
 
 - `create` is **dry-run by default**; `--apply` to execute.
@@ -125,11 +150,12 @@ anything not wrapped.
 
 ## 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).
+(With Zotero Storage, zotkit simply uses the Web API's official file endpoints — this
+section is about the WebDAV mode.) 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.