raindrop-cli 0.5.2__py3-none-any.whl

rd_cli/output.py

@@ -0,0 +1,305 @@
+"""Terminal output helpers: colour, alignment, trees, and JSON emission.
+
+Colour is TTY-aware and opt-out: it is disabled automatically when stdout is
+not a terminal (so piped output stays clean), when ``NO_COLOR`` is set, or when
+the CLI is passed ``--no-color``. The palette leans on the Kanagawa Dragon
+family Brandon uses everywhere.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+# ANSI SGR codes.
+_CODES = {
+    "reset": "\033[0m",
+    "bold": "\033[1m",
+    "dim": "\033[2m",
+    "id": "\033[38;5;109m",  # muted blue — identifiers
+    "title": "\033[1m",  # bold — titles
+    "url": "\033[38;5;150m",  # green — links
+    "tag": "\033[38;5;179m",  # yellow — tags
+    "star": "\033[38;5;174m",  # red/pink — important
+    "muted": "\033[2m",  # dim — secondary text
+    "error": "\033[38;5;174m",  # red — errors
+    "ok": "\033[38;5;150m",  # green — success
+}
+
+_color_enabled = True
+
+
+def configure(*, no_color: bool = False, stream=None) -> None:
+    """Decide whether colour is on, based on flags, env, and TTY status."""
+    global _color_enabled
+    stream = stream or sys.stdout
+    _color_enabled = not (
+        no_color
+        or os.environ.get("NO_COLOR") is not None
+        or not hasattr(stream, "isatty")
+        or not stream.isatty()
+    )
+
+
+def color(text: str, name: str) -> str:
+    """Wrap ``text`` in the named colour when colour is enabled."""
+    if not _color_enabled:
+        return text
+    code = _CODES.get(name, "")
+    return f"{code}{text}{_CODES['reset']}" if code else text
+
+
+def emit_json(data: Any) -> None:
+    """Print ``data`` as compact-but-readable UTF-8 JSON."""
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def error(message: str) -> None:
+    print(color(f"error: {message}", "error"), file=sys.stderr)
+
+
+def success(message: str) -> None:
+    print(color(message, "ok"))
+
+
+def confirm(question: str, *, assume_yes: bool = False, stdin=None) -> bool:
+    """Ask ``question`` and return True only on an explicit yes.
+
+    The prompt goes to stderr, not stdout, so confirming does not pollute a
+    redirected or piped stdout. A non-interactive stdin refuses rather than
+    prompting: a blocked read would hang a script forever, and defaulting to
+    yes would delete things nobody agreed to. Callers pass ``assume_yes`` for
+    the ``--yes`` escape hatch.
+    """
+    if assume_yes:
+        return True
+    stdin = stdin or sys.stdin
+    if not hasattr(stdin, "isatty") or not stdin.isatty():
+        error(
+            "refusing to prompt with a non-interactive stdin; "
+            "pass --yes to confirm up front"
+        )
+        return False
+    print(color(question, "star") + " [y/N] ", end="", file=sys.stderr, flush=True)
+    try:
+        reply = stdin.readline()
+    except (EOFError, KeyboardInterrupt):
+        print(file=sys.stderr)
+        return False
+    if not reply:  # EOF (Ctrl-D)
+        print(file=sys.stderr)
+        return False
+    return reply.strip().lower() in ("y", "yes")
+
+
+# -- domain formatters --------------------------------------------------------
+
+
+def format_raindrop_line(item: dict, *, detailed: bool = False) -> str:
+    """One-line (or multi-line when detailed) rendering of a raindrop."""
+    rid = color(f"[{item.get('_id')}]", "id")
+    title = color(item.get("title") or "(no title)", "title")
+    star = " " + color("★", "star") if item.get("important") else ""
+    lines = [f"{rid} {title}{star}"]
+    link = item.get("link")
+    if link:
+        lines.append("      " + color(link, "url"))
+    if detailed:
+        excerpt = (item.get("excerpt") or "").strip()
+        if excerpt:
+            lines.append("      " + color(_truncate(excerpt, 200), "muted"))
+        note = (item.get("note") or "").strip()
+        if note:
+            lines.append("      " + color("note: " + _truncate(note, 200), "muted"))
+        tags = item.get("tags") or []
+        if tags:
+            lines.append("      " + " ".join(color(f"#{t}", "tag") for t in tags))
+    return "\n".join(lines)
+
+
+def format_raindrop_detail(item: dict) -> str:
+    rid = color(str(item.get("_id")), "id")
+    title = color(item.get("title") or "(no title)", "title")
+    lines = [f"{rid}  {title}"]
+    if item.get("important"):
+        lines[0] += " " + color("★", "star")
+    fields = [
+        ("link", item.get("link")),
+        ("domain", item.get("domain")),
+        ("type", item.get("type")),
+        ("created", item.get("created")),
+        ("updated", item.get("lastUpdate")),
+    ]
+    collection_id = _collection_id_of(item)
+    if collection_id is not None:
+        fields.append(("collection", collection_id))
+    for label, value in fields:
+        if value:
+            lines.append(f"  {color(label + ':', 'muted')} {value}")
+    excerpt = (item.get("excerpt") or "").strip()
+    if excerpt:
+        lines.append(f"  {color('excerpt:', 'muted')} {excerpt}")
+    note = (item.get("note") or "").strip()
+    if note:
+        lines.append(f"  {color('note:', 'muted')} {note}")
+    tags = item.get("tags") or []
+    if tags:
+        lines.append("  " + " ".join(color(f"#{t}", "tag") for t in tags))
+    highlights = item.get("highlights") or []
+    if highlights:
+        lines.append(f"  {color('highlights:', 'muted')}")
+        for hl in highlights:
+            lines.append(f"    {color('▍', hl.get('color', 'muted'))} {hl.get('text')}")
+    return "\n".join(lines)
+
+
+def format_collections_flat(items: list[dict]) -> str:
+    rows = [
+        (
+            color(f"[{c.get('_id')}]", "id"),
+            c.get("title") or "(untitled)",
+            str(c.get("count", 0)),
+        )
+        for c in items
+    ]
+    return _columns(rows, headers=None)
+
+
+def format_collection_tree(roots: list[dict], children: list[dict]) -> str:
+    """Render nested collections as an indented tree using ``parent.$id`` links."""
+    kids: dict[int, list[dict]] = {}
+    for child in children:
+        parent = (child.get("parent") or {}).get("$id")
+        if parent is not None:
+            kids.setdefault(parent, []).append(child)
+    for group in kids.values():
+        group.sort(key=lambda c: c.get("sort", 0))
+
+    lines: list[str] = []
+
+    def walk(node: dict, depth: int) -> None:
+        indent = "  " * depth
+        rid = color(f"[{node.get('_id')}]", "id")
+        count = color(f"({node.get('count', 0)})", "muted")
+        lines.append(f"{indent}{rid} {node.get('title') or '(untitled)'} {count}")
+        for child in kids.get(node.get("_id", 0), []):
+            walk(child, depth + 1)
+
+    for root in roots:
+        walk(root, 0)
+    return "\n".join(lines)
+
+
+def format_tags(items: list[dict]) -> str:
+    rows = [
+        (color(f"#{t.get('_id')}", "tag"), color(f"({t.get('count', 0)})", "muted"))
+        for t in items
+    ]
+    return _columns(rows, headers=None)
+
+
+def format_highlight_line(hl: dict) -> str:
+    marker = color("▍", hl.get("color", "muted"))
+    ref = hl.get("raindropRef")
+    hid = color(f"[{hl.get('_id')}]", "id")
+    ref_str = color(f"rd:{ref}", "muted") if ref else ""
+    lines = [f"{hid} {ref_str} {marker} {hl.get('text', '')}".rstrip()]
+    note = (hl.get("note") or "").strip()
+    if note:
+        lines.append("      " + color("note: " + note, "muted"))
+    return "\n".join(lines)
+
+
+# -- pinboard formatters ------------------------------------------------------
+
+
+def format_pinboard_post(post: dict, *, detailed: bool = False) -> str:
+    """One-line (or multi-line when detailed) rendering of a Pinboard bookmark.
+    Pinboard keys bookmarks by URL, so the URL is the identifier here."""
+    title = color(post.get("description") or "(no title)", "title")
+    flags = ""
+    if post.get("toread") == "yes":
+        flags += " " + color("●unread", "star")
+    if post.get("shared") == "no":
+        flags += " " + color("🔒", "muted")
+    lines = [f"{title}{flags}"]
+    link = post.get("href")
+    if link:
+        lines.append("      " + color(link, "url"))
+    extended = (post.get("extended") or "").strip()
+    if detailed and extended:
+        lines.append("      " + color(_truncate(extended, 200), "muted"))
+    tags = (post.get("tags") or "").split()
+    if tags:
+        lines.append("      " + " ".join(color(f"#{t}", "tag") for t in tags))
+    return "\n".join(lines)
+
+
+def format_pinboard_tags(tags: dict[str, int]) -> str:
+    rows = [
+        (color(f"#{tag}", "tag"), color(f"({count})", "muted"))
+        for tag, count in sorted(tags.items(), key=lambda kv: (-kv[1], kv[0]))
+    ]
+    return _columns(rows, headers=None)
+
+
+def format_note_line(note: dict) -> str:
+    nid = color(f"[{note.get('id')}]", "id")
+    title = color(note.get("title") or "(untitled)", "title")
+    length = color(f"({note.get('length', 0)} chars)", "muted")
+    updated = color(note.get("updated_at") or "", "muted")
+    return f"{nid} {title} {length} {updated}".rstrip()
+
+
+# -- generic helpers ----------------------------------------------------------
+
+
+def _columns(rows: list[tuple[str, ...]], headers: tuple[str, ...] | None) -> str:
+    """Left-align rows into columns. Widths are computed on visible width so
+    ANSI codes do not throw off alignment."""
+    all_rows = ([headers] if headers else []) + rows
+    if not all_rows:
+        return ""
+    ncols = max(len(r) for r in all_rows)
+    widths = [0] * ncols
+    for row in all_rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], _visible_len(cell))
+    out = []
+    for row in all_rows:
+        cells = []
+        for i, cell in enumerate(row):
+            pad = widths[i] - _visible_len(cell)
+            cells.append(cell + " " * pad if i < ncols - 1 else cell)
+        out.append("  ".join(cells).rstrip())
+    return "\n".join(out)
+
+
+def _visible_len(text: str) -> int:
+    """Length of ``text`` ignoring ANSI escape sequences."""
+    result = 0
+    i = 0
+    while i < len(text):
+        if text[i] == "\033":
+            end = text.find("m", i)
+            if end == -1:
+                break
+            i = end + 1
+        else:
+            result += 1
+            i += 1
+    return result
+
+
+def _truncate(text: str, limit: int) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def _collection_id_of(item: dict) -> int | None:
+    collection = item.get("collection")
+    if isinstance(collection, dict):
+        return collection.get("$id")
+    return item.get("collectionId")

rd_cli/pinboard.py

@@ -0,0 +1,275 @@
+"""``PinboardClient`` — a stdlib-only wrapper over the Pinboard API v1
+(https://api.pinboard.in/v1).
+
+Sibling to :class:`rd_cli.client.RaindropClient`, and deliberately the same
+shape (one ``_request`` chokepoint, injectable ``opener``/``sleep`` for tests,
+the shared typed-error family), but adapted to Pinboard's realities:
+
+- **Auth is a query parameter**, ``auth_token=user:HEX`` (not a Bearer header).
+- **Every endpoint is a GET**, including the mutating ones, so writes are marked
+  with ``write=True`` rather than inferred from the HTTP method (that is what
+  ``--dry-run`` keys off).
+- **JSON is opt-in** via ``format=json`` on every call.
+- **The rate limit is strict** (one call per ~3s, ``posts/all`` once per 5 min),
+  so the client paces itself with a minimum inter-request interval on top of the
+  usual ``429`` backoff.
+
+Pinboard's data model is flat: bookmarks keyed by URL (there are no numeric ids
+and no collections), tags, and notes. There is no full-text search endpoint;
+filtering is by tag and date only.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from . import __version__
+from .client import _backoff, _encode_params, _to_api_error
+from .errors import APIError
+
+BASE_URL = "https://api.pinboard.in/v1"
+USER_AGENT = f"rd-cli/{__version__} (+https://github.com/VirInvictus/rd-cli)"
+
+# Pinboard asks for at least three seconds between calls for most endpoints.
+MIN_INTERVAL = 3.0
+
+
+class PinboardClient:
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        min_interval: float = MIN_INTERVAL,
+        dry_run: bool = False,
+        opener: urllib.request.OpenerDirector | None = None,
+        sleep=time.sleep,
+        clock=time.monotonic,
+    ) -> None:
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.min_interval = min_interval
+        self.dry_run = dry_run
+        self._opener = opener or urllib.request.build_opener()
+        self._sleep = sleep
+        self._clock = clock
+        self._last_call: float | None = None
+
+    # -- core -----------------------------------------------------------------
+
+    def _request(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        write: bool = False,
+    ) -> Any:
+        query = dict(params or {})
+        query["auth_token"] = self.token
+        query["format"] = "json"
+
+        if self.dry_run and write:
+            shown = dict(params or {})
+            print(f"DRY RUN GET {path} {json.dumps(shown)}", file=sys.stderr)
+            return {"result_code": "done", "result": "done"}
+
+        url = f"{self.base_url}{path}?{_encode_params(query)}"
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        req = urllib.request.Request(url, headers=headers, method="GET")
+
+        attempt = 0
+        while True:
+            self._pace()
+            try:
+                with self._opener.open(req, timeout=self.timeout) as resp:
+                    body = resp.read()
+                self._last_call = self._clock()
+                return json.loads(body) if body else {}
+            except urllib.error.HTTPError as exc:
+                self._last_call = self._clock()
+                if (
+                    exc.code == 429 or 500 <= exc.code < 600
+                ) and attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise _to_api_error(exc) from exc
+            except urllib.error.URLError as exc:
+                if attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIError(f"Network error: {exc.reason}") from exc
+
+    def _pace(self) -> None:
+        """Sleep so consecutive calls are at least ``min_interval`` apart."""
+        if self._last_call is None or self.min_interval <= 0:
+            return
+        elapsed = self._clock() - self._last_call
+        if elapsed < self.min_interval:
+            self._sleep(self.min_interval - elapsed)
+
+    @staticmethod
+    def _check(data: dict) -> dict:
+        """Raise if a write response is not ``done``; else return it."""
+        code = data.get("result_code") or data.get("result")
+        if code and code != "done":
+            raise APIError(str(code))
+        return data
+
+    # -- posts ----------------------------------------------------------------
+
+    def last_update(self) -> str:
+        """Timestamp of the most recent bookmark change (cheap, for sync)."""
+        return self._request("/posts/update").get("update_time", "")
+
+    def get_all(
+        self,
+        *,
+        tags: list[str] | None = None,
+        start: int | None = None,
+        results: int | None = None,
+        fromdt: str = "",
+        todt: str = "",
+    ) -> list[dict]:
+        """All bookmarks (rate-limited to once per five minutes)."""
+        params: dict[str, Any] = {}
+        if tags:
+            params["tag"] = " ".join(tags)
+        if start is not None:
+            params["start"] = start
+        if results is not None:
+            params["results"] = results
+        if fromdt:
+            params["fromdt"] = fromdt
+        if todt:
+            params["todt"] = todt
+        data = self._request("/posts/all", params=params or None)
+        return data if isinstance(data, list) else data.get("posts", [])
+
+    def get_recent(
+        self, *, tags: list[str] | None = None, count: int = 15
+    ) -> list[dict]:
+        params: dict[str, Any] = {"count": min(count, 100)}
+        if tags:
+            params["tag"] = " ".join(tags)
+        return self._request("/posts/recent", params=params).get("posts", [])
+
+    def get_post(self, url: str, *, meta: bool = True) -> dict | None:
+        """The bookmark for ``url``, or ``None`` if it is not saved."""
+        params: dict[str, Any] = {"url": url}
+        if meta:
+            params["meta"] = "yes"
+        posts = self._request("/posts/get", params=params).get("posts", [])
+        return posts[0] if posts else None
+
+    def add_post(
+        self,
+        url: str,
+        title: str,
+        *,
+        extended: str = "",
+        tags: list[str] | None = None,
+        dt: str = "",
+        replace: bool = True,
+        shared: bool | None = None,
+        toread: bool | None = None,
+    ) -> dict:
+        params: dict[str, Any] = {"url": url, "description": title}
+        if extended:
+            params["extended"] = extended
+        if tags:
+            params["tags"] = " ".join(tags)
+        if dt:
+            params["dt"] = dt
+        params["replace"] = "yes" if replace else "no"
+        if shared is not None:
+            params["shared"] = "yes" if shared else "no"
+        if toread is not None:
+            params["toread"] = "yes" if toread else "no"
+        return self._check(self._request("/posts/add", params=params, write=True))
+
+    def delete_post(self, url: str) -> dict:
+        return self._check(
+            self._request("/posts/delete", params={"url": url}, write=True)
+        )
+
+    def suggest_tags(self, url: str) -> dict:
+        """``{"popular": [...], "recommended": [...]}`` for ``url``."""
+        raw = self._request("/posts/suggest", params={"url": url})
+        out: dict[str, list[str]] = {"popular": [], "recommended": []}
+        for group in raw if isinstance(raw, list) else []:
+            for key in out:
+                if key in group:
+                    out[key] = group[key]
+        return out
+
+    # -- tags -----------------------------------------------------------------
+
+    def get_tags(self) -> dict[str, int]:
+        """Map of tag -> count (Pinboard returns the counts as strings)."""
+        raw = self._request("/tags/get")
+        return {tag: int(count) for tag, count in raw.items()}
+
+    def rename_tag(self, old: str, new: str) -> dict:
+        return self._check(
+            self._request("/tags/rename", params={"old": old, "new": new}, write=True)
+        )
+
+    def delete_tag(self, tag: str) -> dict:
+        return self._check(
+            self._request("/tags/delete", params={"tag": tag}, write=True)
+        )
+
+    # -- notes ----------------------------------------------------------------
+
+    def list_notes(self) -> list[dict]:
+        return self._request("/notes/list").get("notes", [])
+
+    def get_note(self, note_id: str) -> dict:
+        return self._request(f"/notes/{note_id}")
+
+    # -- convenience (Pinboard has no PUT; edits re-add with replace) ---------
+
+    def edit_post(self, url: str, **changes: Any) -> dict:
+        """Fetch ``url``, apply ``changes`` (title, extended, tags, shared,
+        toread), and re-add it with ``replace=yes``. Pinboard has no update
+        endpoint, so a partial edit is a read-modify-write."""
+        current = self.get_post(url)
+        if current is None:
+            raise APIError(f"not saved: {url}")
+        title = changes.get("title")
+        if title is None:
+            title = current.get("description", "")
+        extended = changes.get("extended")
+        if extended is None:
+            extended = current.get("extended", "")
+        tags: list[str]
+        if "tags" in changes and changes["tags"] is not None:
+            tags = list(changes["tags"])
+        else:
+            tags = str(current.get("tags") or "").split()
+        shared = changes.get("shared")
+        if shared is None:
+            shared = current.get("shared") == "yes"
+        toread = changes.get("toread")
+        if toread is None:
+            toread = current.get("toread") == "yes"
+        return self.add_post(
+            url,
+            title,
+            extended=extended,
+            tags=tags,
+            replace=True,
+            shared=shared,
+            toread=toread,
+        )