raindrop-cli 0.5.2__py3-none-any.whl

rd_cli/completion.py

@@ -0,0 +1,225 @@
+"""Shell completion generated from the argument parser itself.
+
+The parser is the single source of truth for what commands and flags exist, so
+completion is derived from it rather than maintained beside it. A hand-kept
+table would be correct exactly until the next command lands and then quietly rot,
+and a stale completion is worse than none: it offers flags that no longer work.
+
+This means reading argparse's private structures (``_actions``,
+``_SubParsersAction``). That is a deliberate trade. The alternative is a second
+declaration of every command, and the risk is bounded: ``probe_argparse_internals``
+states exactly what is being relied on, and ``tests/test_completion.py`` calls it
+so a Python upgrade that moves any of it fails loudly with a pointed message
+instead of silently emitting empty scripts.
+
+No third-party dependency is involved (rd-cli is stdlib-only), which also rules
+out argcomplete.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+SHELLS = ("bash", "zsh", "fish")
+
+
+class ArgparseLayoutError(RuntimeError):
+    """argparse no longer exposes what the completion walker needs."""
+
+
+def probe_argparse_internals() -> None:
+    """Fail loudly if the private argparse API this module walks has moved.
+
+    Called by the test suite. Everything asserted here is exactly what `_walk`
+    below depends on; if this passes, the walker can run.
+    """
+    p = argparse.ArgumentParser(prog="probe")
+    p.add_argument("--flag")
+    sub = p.add_subparsers()
+    child = sub.add_parser("child")
+    child.add_argument("--inner")
+
+    if not hasattr(p, "_actions"):
+        raise ArgparseLayoutError("ArgumentParser._actions is gone")
+    if not hasattr(argparse, "_SubParsersAction"):
+        raise ArgparseLayoutError("argparse._SubParsersAction is gone")
+
+    subs = [a for a in p._actions if isinstance(a, argparse._SubParsersAction)]
+    if not subs:
+        raise ArgparseLayoutError("subparser actions are no longer in _actions")
+    if not isinstance(getattr(subs[0], "choices", None), dict):
+        raise ArgparseLayoutError(
+            "_SubParsersAction.choices is no longer a name->parser dict"
+        )
+    if subs[0].choices.get("child") is not child:
+        raise ArgparseLayoutError(
+            "_SubParsersAction.choices no longer maps to the child parser"
+        )
+
+    flags = [a for a in p._actions if a.option_strings]
+    if not any("--flag" in a.option_strings for a in flags):
+        raise ArgparseLayoutError("Action.option_strings no longer lists flags")
+
+
+def _walk(parser: argparse.ArgumentParser) -> dict:
+    """Reduce a parser to ``{"options", "values", "subcommands"}``."""
+    options: list[str] = []
+    values: list[str] = []
+    subcommands: dict[str, dict] = {}
+
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            for name, child in action.choices.items():
+                subcommands[name] = _walk(child)
+        elif action.option_strings:
+            options.extend(action.option_strings)
+        elif action.choices:
+            # A positional with a fixed choice list, e.g. `rd completion bash`.
+            # Worth completing and easy to miss: subparsers are also positionals
+            # carrying `choices`, so they have to be taken off the table first or
+            # every command name lands here as a value too.
+            values.extend(str(c) for c in action.choices)
+
+    return {
+        "options": sorted(set(options)),
+        "values": sorted(set(values)),
+        "subcommands": subcommands,
+    }
+
+
+def describe(parser: argparse.ArgumentParser) -> dict:
+    """The completion model for a parser: the shape every emitter renders."""
+    return _walk(parser)
+
+
+def _bash(tree: dict, prog: str) -> str:
+    top = " ".join(sorted(tree["subcommands"]))
+    root_opts = " ".join(tree["options"])
+
+    # One case arm per command carrying its own flags and nested subcommands.
+    arms: list[str] = []
+    for name in sorted(tree["subcommands"]):
+        node = tree["subcommands"][name]
+        nested = " ".join(sorted(node["subcommands"]) + node["values"])
+        opts = " ".join(node["options"])
+        arms.append(
+            f"        {name})\n"
+            f"            __rd_sub='{nested}'\n"
+            f"            __rd_opts='{opts}'\n"
+            f"            ;;"
+        )
+    arm_text = "\n".join(arms)
+
+    return f"""# {prog} completion for bash. Generated by `{prog} completion bash`.
+# Install: {prog} completion bash > ~/.local/share/bash-completion/completions/{prog}
+_{prog}_complete() {{
+    local cur prev cmd i
+    cur="${{COMP_WORDS[COMP_CWORD]}}"
+    local __rd_sub='' __rd_opts=''
+
+    # First non-flag word after the program name is the command.
+    cmd=''
+    for (( i=1; i < COMP_CWORD; i++ )); do
+        case "${{COMP_WORDS[i]}}" in
+            -*) ;;
+            *) cmd="${{COMP_WORDS[i]}}"; break ;;
+        esac
+    done
+
+    if [ -z "$cmd" ]; then
+        COMPREPLY=( $(compgen -W '{top} {root_opts}' -- "$cur") )
+        return 0
+    fi
+
+    case "$cmd" in
+{arm_text}
+        *) ;;
+    esac
+
+    COMPREPLY=( $(compgen -W "$__rd_sub $__rd_opts" -- "$cur") )
+    return 0
+}}
+complete -F _{prog}_complete {prog}
+"""
+
+
+def _zsh(tree: dict, prog: str) -> str:
+    lines: list[str] = [
+        f"#compdef {prog}",
+        f"# {prog} completion for zsh. Generated by `{prog} completion zsh`.",
+        f'# Install: {prog} completion zsh > "${{fpath[1]}}/_{prog}"',
+        "# (then restart zsh)",
+        "",
+        f"_{prog}() {{",
+        "    local -a cmds",
+        "    cmds=(" + " ".join(f"'{n}'" for n in sorted(tree["subcommands"])) + ")",
+        "    local -a opts",
+        "    opts=(" + " ".join(f"'{o}'" for o in tree["options"]) + ")",
+        "",
+        "    if (( CURRENT == 2 )); then",
+        "        _describe -t commands 'command' cmds",
+        "        compadd -a opts",
+        "        return",
+        "    fi",
+        "",
+        "    case ${words[2]} in",
+    ]
+    for name in sorted(tree["subcommands"]):
+        node = tree["subcommands"][name]
+        sub = " ".join(f"'{s}'" for s in sorted(node["subcommands"]) + node["values"])
+        opt = " ".join(f"'{o}'" for o in node["options"])
+        lines.append(f"        {name})")
+        if sub:
+            lines.append(f"            local -a s; s=({sub}); compadd -a s")
+        lines.append(f"            local -a o; o=({opt}); compadd -a o")
+        lines.append("            ;;")
+    lines += [
+        "    esac",
+        "}",
+        "",
+        f'_{prog} "$@"',
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _fish(tree: dict, prog: str) -> str:
+    lines: list[str] = [
+        f"# {prog} completion for fish. Generated by `{prog} completion fish`.",
+        f"# Install: {prog} completion fish > ~/.config/fish/completions/{prog}.fish",
+        "",
+        # Without this, fish offers file paths alongside every command.
+        f"complete -c {prog} -f",
+        "",
+    ]
+    for name in sorted(tree["subcommands"]):
+        lines.append(f"complete -c {prog} -n __fish_use_subcommand -a {name}")
+    lines.append("")
+    for name in sorted(tree["subcommands"]):
+        node = tree["subcommands"][name]
+        for s in sorted(node["subcommands"]) + node["values"]:
+            lines.append(
+                f"complete -c {prog} -n '__fish_seen_subcommand_from {name}' -a {s}"
+            )
+        for o in node["options"]:
+            seen = f"-n '__fish_seen_subcommand_from {name}'"
+            if o.startswith("--"):
+                lines.append(f"complete -c {prog} {seen} -l {o[2:]}")
+            elif len(o) == 2:
+                lines.append(f"complete -c {prog} {seen} -s {o[1:]}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+_EMITTERS = {"bash": _bash, "zsh": _zsh, "fish": _fish}
+
+
+def generate(shell: str, parser: argparse.ArgumentParser, prog: str = "rd") -> str:
+    """The completion script for ``shell``, derived from ``parser``."""
+    try:
+        emit = _EMITTERS[shell]
+    except KeyError:
+        raise ValueError(
+            f"unknown shell {shell!r} (expected one of: {', '.join(SHELLS)})"
+        ) from None
+    return emit(describe(parser), prog)

rd_cli/config.py

@@ -0,0 +1,162 @@
+"""Token and configuration resolution.
+
+Resolution order for the access token (first hit wins):
+
+1. ``RAINDROP_TOKEN`` environment variable.
+2. ``RAINDROP_TEST_TOKEN`` environment variable (back-compat alias).
+3. ``token`` key in ``$XDG_CONFIG_HOME/rd-cli/config.toml``.
+4. ``RAINDROP_TOKEN`` / ``RAINDROP_TEST_TOKEN`` in a ``.env`` file, searched in
+   the current directory then ``$XDG_CONFIG_HOME/rd-cli/.env``.
+
+The ``.env`` reader is a deliberately tiny stdlib parser so we carry no
+``python-dotenv`` dependency. It only loads keys that are not already in the
+environment, matching python-dotenv's default and keeping real env vars
+authoritative.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+from .errors import ConfigError
+
+ENV_VARS = ("RAINDROP_TOKEN", "RAINDROP_TEST_TOKEN")
+PINBOARD_ENV_VARS = ("PINBOARD_TOKEN", "PINBOARD_API_TOKEN")
+
+
+def config_dir() -> Path:
+    """Return the rd-cli config directory (respects ``XDG_CONFIG_HOME``)."""
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+    return root / "rd-cli"
+
+
+def config_path() -> Path:
+    """Path to ``config.toml`` (may not exist)."""
+    return config_dir() / "config.toml"
+
+
+def parse_env(text: str) -> dict[str, str]:
+    """Parse ``.env`` text into a dict. Supports ``KEY=value``, ``export KEY=v``,
+    ``#`` comments, blank lines, and single/double quoted values."""
+    result: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        key, sep, value = line.partition("=")
+        if not sep:
+            continue
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        if key:
+            result[key] = value
+    return result
+
+
+def load_env_files(paths: list[Path] | None = None) -> None:
+    """Load the first existing ``.env`` file into ``os.environ`` (non-clobbering)."""
+    if paths is None:
+        paths = [Path.cwd() / ".env", config_dir() / ".env"]
+    for path in paths:
+        if not path.is_file():
+            continue
+        for key, value in parse_env(path.read_text(encoding="utf-8")).items():
+            os.environ.setdefault(key, value)
+        return
+
+
+def read_config() -> dict:
+    """Read ``config.toml`` as a dict; empty dict if it does not exist."""
+    path = config_path()
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"Could not read {path}: {exc}") from exc
+
+
+def resolve_token() -> str:
+    """Resolve the access token, or raise :class:`ConfigError` if none is found."""
+    load_env_files()
+    for var in ENV_VARS:
+        token = os.environ.get(var)
+        if token:
+            return token.strip()
+    token = read_config().get("token")
+    if isinstance(token, str) and token.strip():
+        return token.strip()
+    raise ConfigError(
+        "No Raindrop token found. Set RAINDROP_TOKEN, add it to "
+        f"{config_path()} via `rd config set-token <token>`, or put it in a "
+        ".env file. Get a test token at "
+        "https://app.raindrop.io/settings/integrations"
+    )
+
+
+def resolve_pinboard_token() -> str:
+    """Resolve the Pinboard API token (format ``user:HEX``), or raise.
+
+    Same precedence as :func:`resolve_token` but for the ``PINBOARD_TOKEN`` /
+    ``PINBOARD_API_TOKEN`` env vars and the ``pinboard_token`` config key.
+    """
+    load_env_files()
+    for var in PINBOARD_ENV_VARS:
+        token = os.environ.get(var)
+        if token:
+            return token.strip()
+    token = read_config().get("pinboard_token")
+    if isinstance(token, str) and token.strip():
+        return token.strip()
+    raise ConfigError(
+        "No Pinboard token found. Set PINBOARD_TOKEN, add it to "
+        f"{config_path()} via `rd config set-pinboard-token <token>`, or put it "
+        "in a .env file. Your token (format user:HEX) is at "
+        "https://pinboard.in/settings/password"
+    )
+
+
+def write_token(token: str) -> Path:
+    """Persist the Raindrop ``token`` to ``config.toml`` (0600), keeping others."""
+    return _write_config_key("token", token)
+
+
+def write_pinboard_token(token: str) -> Path:
+    """Persist ``pinboard_token`` to ``config.toml`` (0600), keeping others."""
+    return _write_config_key("pinboard_token", token)
+
+
+def _write_config_key(key: str, value: str) -> Path:
+    """Set one string key in ``config.toml`` (0600), preserving every other key.
+    The written key is emitted first; order is cosmetic."""
+    value = value.strip()
+    if not value:
+        raise ConfigError(f"Refusing to write an empty {key}.")
+    data = read_config()
+    data[key] = value
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [_toml_line(key, value)]
+    for other, val in data.items():
+        if other == key:
+            continue
+        lines.append(_toml_line(other, val))
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    path.chmod(0o600)
+    return path
+
+
+def _toml_line(key: str, value: object) -> str:
+    if isinstance(value, bool):
+        return f"{key} = {str(value).lower()}"
+    if isinstance(value, (int, float)):
+        return f"{key} = {value}"
+    return f'{key} = "{value}"'

rd_cli/errors.py

@@ -0,0 +1,56 @@
+"""Exception hierarchy for rd-cli.
+
+Every failure the CLI can surface derives from :class:`RaindropError`, so the
+top-level handler in ``cli.py`` catches one type and prints one clean message.
+API failures carry the parsed ``errorMessage`` the Raindrop API returns, rather
+than the bare HTTP status ``urllib`` would otherwise raise.
+"""
+
+from __future__ import annotations
+
+
+class RaindropError(Exception):
+    """Base class for every rd-cli error."""
+
+
+class ConfigError(RaindropError):
+    """A token could not be resolved, or config on disk is unreadable."""
+
+
+class APIError(RaindropError):
+    """The Raindrop API returned a non-success response.
+
+    Attributes:
+        status: HTTP status code, or ``None`` for transport-level failures.
+        message: Human-readable message (the API's ``errorMessage`` when present).
+        payload: The decoded JSON body, if any.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        payload: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.payload = payload or {}
+
+    def __str__(self) -> str:
+        if self.status is not None:
+            return f"HTTP {self.status}: {self.message}"
+        return self.message
+
+
+class AuthError(APIError):
+    """Authentication failed (HTTP 401/403) — token missing, wrong, or expired."""
+
+
+class NotFoundError(APIError):
+    """The requested resource does not exist (HTTP 404)."""
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded (HTTP 429) and retries were exhausted."""