zotkit 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -20,7 +20,12 @@ Dynamic: license-file
 
 # zotkit
 
+[![PyPI](https://img.shields.io/pypi/v/zotkit)](https://pypi.org/project/zotkit/)
+[![Python](https://img.shields.io/pypi/pyversions/zotkit)](https://pypi.org/project/zotkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 **Headless Zotero library management — no desktop app required.**
+[中文速览 →](README.zh-CN.md)
 
 "Headless" simply means zotkit never needs the Zotero app (or any window) open: it is a
 Python library + CLI that talks straight to the
@@ -70,6 +75,9 @@ Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any
   `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.
 
+After filling it in, run **`zotkit doctor`** — it validates the config file, API
+access, and attachment storage, and tells you exactly what to fix if anything fails.
+
 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`
@@ -160,6 +168,14 @@ 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.
 
+## Limits & roadmap
+
+- `find` currently lists the library client-side — instant for hundreds of items,
+  sluggish for many thousands. Server-side search is planned.
+- Group libraries should work for item operations (untested); WebDAV file sync is
+  personal-libraries-only (a Zotero limitation).
+- Planned: an MCP server wrapper, server-side search, DOI/arXiv one-shot import.
+
 ## License
 
 [MIT](LICENSE). If you build on the WebDAV implementation, a link back is appreciated.

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

@@ -1,6 +1,11 @@
 # zotkit
 
+[![PyPI](https://img.shields.io/pypi/v/zotkit)](https://pypi.org/project/zotkit/)
+[![Python](https://img.shields.io/pypi/pyversions/zotkit)](https://pypi.org/project/zotkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 **Headless Zotero library management — no desktop app required.**
+[中文速览 →](README.zh-CN.md)
 
 "Headless" simply means zotkit never needs the Zotero app (or any window) open: it is a
 Python library + CLI that talks straight to the
@@ -50,6 +55,9 @@ Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any
   `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.
 
+After filling it in, run **`zotkit doctor`** — it validates the config file, API
+access, and attachment storage, and tells you exactly what to fix if anything fails.
+
 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`
@@ -140,6 +148,14 @@ 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.
 
+## Limits & roadmap
+
+- `find` currently lists the library client-side — instant for hundreds of items,
+  sluggish for many thousands. Server-side search is planned.
+- Group libraries should work for item operations (untested); WebDAV file sync is
+  personal-libraries-only (a Zotero limitation).
+- Planned: an MCP server wrapper, server-side search, DOI/arXiv one-shot import.
+
 ## License
 
 [MIT](LICENSE). If you build on the WebDAV implementation, a link back is appreciated.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zotkit"
-version = "0.2.0"
+version = "0.3.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.2.0 → zotkit-0.3.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.2.0"
+__version__ = "0.3.0"

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

@@ -10,7 +10,8 @@ import json
 import sys
 from pathlib import Path
 
-from .core import Zot, lint_tags, load_conventions
+from . import __version__
+from .core import Zot, lint_tags, load_conventions, load_env
 
 
 def _print_items(rows):
@@ -21,10 +22,58 @@ def _print_items(rows):
     print(f"\n{len(rows)} match(es)")
 
 
+def _doctor() -> int:
+    """Validate the whole setup; each failing check explains how to fix it."""
+    import httpx
+    from urllib.parse import urlsplit
+    print(f"zotkit {__version__}")
+    try:
+        env = load_env()
+    except FileNotFoundError as e:
+        print(f"✗ config: {e}")
+        return 1
+    print(f"✓ config: {env['_env_path']}")
+    conv = load_conventions()
+    print(f"✓ conventions: {'enforced' if conv else 'none configured (tags unrestricted)'}")
+    try:
+        z = Zot()
+        access = z.z.key_info().get("access", {}).get("user", {})
+        n = z.z.count_items()
+        print(f"✓ Zotero API: library {env['ZOTERO_LIBRARY_ID']} reachable, {n} items, "
+              f"write access: {bool(access.get('write'))}")
+    except Exception as e:
+        print(f"✗ Zotero API: {e}\n  check ZOTERO_LIBRARY_ID (numeric userID) and "
+              f"ZOTERO_API_KEY at https://www.zotero.org/settings/keys")
+        return 1
+    if "WEBDAV_URL" in env:
+        base, auth = z._webdav()
+        host = urlsplit(base).netloc
+        try:
+            with httpx.Client(auth=auth, timeout=30) as c:
+                r1 = c.put(f"{base}/zotkit-doctor-probe.txt", content=b"zotkit doctor probe")
+                c.delete(f"{base}/zotkit-doctor-probe.txt")
+            if r1.status_code in (200, 201, 204):
+                print(f"✓ WebDAV: {host} writable — attachments use WebDAV")
+            else:
+                print(f"✗ WebDAV: PUT returned {r1.status_code} — check credentials and "
+                      f"that WEBDAV_URL ends with /zotero/")
+                return 1
+        except Exception as e:
+            print(f"✗ WebDAV: {e}")
+            return 1
+    else:
+        print("✓ attachments: Zotero Storage mode (no WEBDAV_* configured)")
+    print("all good ✓")
+    return 0
+
+
 def main(argv=None):
     ap = argparse.ArgumentParser(prog="zotkit", description="Headless Zotero library CLI")
+    ap.add_argument("--version", action="version", version=f"zotkit {__version__}")
     sub = ap.add_subparsers(dest="cmd", required=True)
 
+    sub.add_parser("doctor", help="validate setup: config, API access, attachment storage")
+
     p = sub.add_parser("find", help="search items by title/tag/collection")
     p.add_argument("--title"); p.add_argument("--tag"); p.add_argument("--collection")
 
@@ -60,6 +109,9 @@ def main(argv=None):
 
     a = ap.parse_args(argv)
 
+    if a.cmd == "doctor":
+        return _doctor()
+
     if a.cmd == "lint":
         conv = load_conventions()
         if conv is None:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -20,7 +20,12 @@ Dynamic: license-file
 
 # zotkit
 
+[![PyPI](https://img.shields.io/pypi/v/zotkit)](https://pypi.org/project/zotkit/)
+[![Python](https://img.shields.io/pypi/pyversions/zotkit)](https://pypi.org/project/zotkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 **Headless Zotero library management — no desktop app required.**
+[中文速览 →](README.zh-CN.md)
 
 "Headless" simply means zotkit never needs the Zotero app (or any window) open: it is a
 Python library + CLI that talks straight to the
@@ -70,6 +75,9 @@ Copy [`.env.example`](.env.example) to `./.env`, `~/.config/zotkit/env`, or any
   `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.
 
+After filling it in, run **`zotkit doctor`** — it validates the config file, API
+access, and attachment storage, and tells you exactly what to fix if anything fails.
+
 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`
@@ -160,6 +168,14 @@ 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.
 
+## Limits & roadmap
+
+- `find` currently lists the library client-side — instant for hundreds of items,
+  sluggish for many thousands. Server-side search is planned.
+- Group libraries should work for item operations (untested); WebDAV file sync is
+  personal-libraries-only (a Zotero limitation).
+- Planned: an MCP server wrapper, server-side search, DOI/arXiv one-shot import.
+
 ## License
 
 [MIT](LICENSE). If you build on the WebDAV implementation, a link back is appreciated.