ankiweb-api 1.0.0__py3-none-any.whl

ankicli.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Terminal CLI for AnkiWeb: info, download, mine, + full /svc/* access.
+
+  ./ankicli.py info 805854302
+  ./ankicli.py download 805854302 -o /tmp/test.ankiaddon
+  ./ankicli.py mine                 # your shared decks + add-ons (needs login)
+  ./ankicli.py call shared_item_info --query sharedId=805854302
+  ./ankicli.py call shared_list_addons
+  ./ankicli.py endpoints            # list all 41 endpoints
+
+Uploads go through ./upload.py (thin wrapper over the forked upstream action).
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import os
+import sys
+from pathlib import Path
+
+from ankiweb_auth import AuthError, default_env_file, load_dotenv, login
+from terminal_ankiweb import (
+    AnkiWebError,
+    NotFoundError,
+    download_addon,
+    fetch_item_info,
+    fetch_list_mine,
+)
+
+HERE = Path(__file__).resolve().parent
+
+
+def cmd_info(args) -> int:
+    try:
+        info = fetch_item_info(args.addon_id)
+    except NotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except AnkiWebError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(f"id:           {info['shared_id']}")
+    print(f"title:        {info['title']}")
+    if info.get("tags"):
+        print(f"tags:         {info['tags'].strip()}")
+    if info.get("support_url"):
+        print(f"support:      {info['support_url']}")
+    print(f"size:         {info['size']}")
+    if info["last_updated"]:
+        dt = datetime.datetime.fromtimestamp(info["last_updated"], datetime.timezone.utc)
+        print(f"last_updated: {info['last_updated']} ({dt.isoformat()})")
+    else:
+        print("last_updated: 0")
+    if info["versions"]:
+        print(f"versions:     {', '.join(info['versions'])}")
+    print("description:")
+    print(info["description"] or "(empty)")
+    # AnkiWeb caches item-info for 10 minutes, so the page link needs the same
+    # `cb` cache-buster the CLI just read with, or the browser shows stale data.
+    cb = info.get("cache_bust")
+    if cb:
+        print(f"verify:   https://ankiweb.net/shared/info/{info['shared_id']}?cb={cb}")
+    if args.verbose:
+        print(f"timestamps_seen: {info['timestamps_seen']}")
+    return 0
+
+
+def cmd_download(args) -> int:
+    try:
+        meta = download_addon(args.addon_id, dest=args.output, point_version=args.point_version)
+    except AnkiWebError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(f"saved:    {meta['path']}")
+    print(f"filename: {meta['filename']}")
+    print(f"size:     {meta['size']}")
+    print(f"t={meta['t']} minpt={meta['minpt']} maxpt={meta['maxpt']} bidx={meta['bidx']}")
+    print(f"via:      {meta['final_url']}")
+    return 0
+
+
+def load_creds(env_file: str = "") -> tuple[str, str]:
+    env_path = Path(env_file).expanduser() if env_file else default_env_file()
+    load_dotenv(env_path)
+    u = os.environ.get("ANKIWEB_USERNAME", "")
+    p = os.environ.get("ANKIWEB_PASSWORD", "")
+    missing = [n for n, v in (("ANKIWEB_USERNAME", u), ("ANKIWEB_PASSWORD", p)) if not v]
+    if missing:
+        raise AuthError(
+            f"missing {' and '.join(missing)} — set them in {env_path} or the environment"
+        )
+    return u, p
+
+
+def cmd_mine(args) -> int:
+    try:
+        user, password = load_creds(args.env_file)
+        cookie = login(user, password)
+        data = fetch_list_mine(cookie)
+    except (AuthError, AnkiWebError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    items = data["items"]
+    if not items:
+        print("no shared items")
+        return 0
+
+    header = f"{'ID':>12}  {'UPD':<10}  {'DL':>6}  {'+':>3} {'-':>3}  TITLE"
+    print(f"{len(items)} shared item(s), {data.get('review_count', 0)} review(s):\n")
+    print(header)
+    print("-" * len(header))
+    for it in items:
+        mtime = (
+            datetime.datetime.fromtimestamp(it["mtime"], datetime.timezone.utc).strftime("%Y-%m-%d")
+            if it["mtime"] else "n/a"
+        )
+        print(
+            f"{it['id']:>12}  {mtime:<10}  {it['downloads']:>6}  "
+            f"{it['thumbs_up']:>3} {it['thumbs_down']:>3}  {it['title']}"
+        )
+    if args.json:
+        import json as _json
+
+        print("\n" + _json.dumps(items, indent=2))
+    return 0
+
+
+def cmd_endpoints(args) -> int:
+    from ankiweb_schema import public_endpoints
+    for ep in public_endpoints():
+        print(f"{ep['method']:4} {ep['path']:40} req={ep['request']} resp={ep['response']}")
+    return 0
+
+
+def cmd_call(args) -> int:
+    import json as _json
+    from ankiweb_client import AnkiWebClient, AnkiWebError, _method_name
+    from ankiweb_schema import endpoint as _endpoint, public_endpoints
+
+    # find endpoint by method name
+    target = None
+    for ep in public_endpoints():
+        if _method_name(ep["path"]) == args.method or ep["path"] == args.method:
+            target = ep
+            break
+    if target is None:
+        print(f"error: unknown method '{args.method}' (see: ankicli.py endpoints)",
+              file=sys.stderr)
+        return 1
+    query = {}
+    for kv in args.query:
+        if "=" not in kv:
+            print(f"error: --query must be K=V, got '{kv}'", file=sys.stderr)
+            return 1
+        k, v = kv.split("=", 1)
+        try:
+            v = int(v)
+        except ValueError:
+            pass
+        query[k] = v
+    request = _json.loads(args.request) if args.request else None
+    client = AnkiWebClient(cookie=args.cookie or None,
+                           env_file=args.env_file or None)
+    try:
+        out = client._call(target["path"], request,
+                           query=query or None)
+    except AnkiWebError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(_json.dumps(out, indent=2, default=str))
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="AnkiWeb terminal: full /svc/* access")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("info", help="fetch public title/description/size via svc/shared/item-info")
+    p.add_argument("addon_id", type=int)
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.set_defaults(fn=cmd_info)
+
+    p = sub.add_parser("download", help="download .ankiaddon via /shared/download/<id>")
+    p.add_argument("addon_id", type=int)
+    p.add_argument("-o", "--output", default=None)
+    p.add_argument("--point-version", type=int, default=250902,
+                   help="Anki int_version, e.g. 250902 for 25.09.02 (default: 250902)")
+    p.set_defaults(fn=cmd_download)
+
+    p = sub.add_parser("mine", help="list items shared by your account (needs login)")
+    p.add_argument("--env-file", default="", help="default: ./.env")
+    p.add_argument("--json", action="store_true", help="also print raw JSON")
+    p.set_defaults(fn=cmd_mine)
+
+    p = sub.add_parser("endpoints", help="list all 41 public endpoints")
+    p.set_defaults(fn=cmd_endpoints)
+
+    p = sub.add_parser("call", help="call any public endpoint by method name")
+    p.add_argument("method", help="e.g. shared_item_info, shared_list_addons, decks_create_deck")
+    p.add_argument("--request", default="", help="request body as JSON (for POST)")
+    p.add_argument("--query", action="append", default=[], metavar="K=V",
+                   help="query param (repeatable; for GET)")
+    p.add_argument("--env-file", default="", help="default: ./.env (only needed for auth endpoints)")
+    p.add_argument("--cookie", default="", help="session cookie (else login via .env for auth endpoints)")
+    p.set_defaults(fn=cmd_call)
+
+    args = ap.parse_args()
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())