zotrm 0.1.0__py3-none-any.whl

zotrm/__init__.py

@@ -0,0 +1,3 @@
+"""zotrm — bridge a Zotero collection to a reMarkable Paper Pro and back."""
+
+__version__ = "0.1.0"

zotrm/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m zotrm`` (a sturdy fallback for cron jobs)."""
+
+from zotrm.cli import main
+
+if __name__ == "__main__":
+    main()

zotrm/cli.py

@@ -0,0 +1,244 @@
+"""Command-line interface: argument parsing and command dispatch.
+
+Subcommands (push / pull / status / sync) and the global --config / --dry-run
+flags mirror the original single-file tool exactly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import tempfile
+from configparser import ConfigParser
+from pathlib import Path
+
+from zotrm.config import DEFAULT_CONFIG, TAG_DONE, TAG_SYNCED, load_config, log
+from zotrm.remarkable import ensure_remote_folder, rmapi
+from zotrm.zotero import (
+    connect,
+    find_collection_key,
+    iter_items,
+    local_pdf_path,
+    pdf_child,
+    tags_of,
+)
+
+
+def _truthy(value: str) -> bool:
+    return value.lower() in ("1", "true", "yes")
+
+
+def _interactive() -> bool:
+    """True when we have a real terminal (so it's safe to prompt)."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def cmd_push(cfg: ConfigParser, dry_run: bool) -> None:
+    zot = connect(cfg)
+    rm = cfg["remarkable"]
+    base = rm.get("folder", "/Papers")
+    mirror = _truthy(rm.get("mirror_subcollections", "true"))
+    coll_key = find_collection_key(zot, rm["collection"])
+
+    pushed = 0
+    for item, folder in iter_items(zot, coll_key, base, mirror):
+        key = item["key"]
+        title = item["data"].get("title", key)[:70]
+        if TAG_SYNCED in tags_of(item):
+            continue
+
+        child = pdf_child(zot, key)
+        if not child:
+            log(f"  skip (no PDF)   {title}")
+            continue
+        att_key, filename = child
+
+        if dry_run:
+            log(f"  would push      {title}  ->  {folder}/{filename}")
+            pushed += 1
+            continue
+
+        ensure_remote_folder(folder)
+
+        # Prefer the locally-synced PDF; fall back to the Zotero API.
+        local = local_pdf_path(cfg, att_key, filename)
+        tmp = None
+        if local:
+            src = str(local)
+        else:
+            tmp = Path(tempfile.gettempdir()) / filename
+            tmp.write_bytes(zot.file(att_key))
+            src = str(tmp)
+
+        res = rmapi("put", src, folder, capture=True)
+        if res.returncode != 0:
+            log(f"  FAILED upload   {title}\n{res.stderr.strip()}")
+        else:
+            zot.add_tags(item, TAG_SYNCED)
+            log(f"  pushed          {title}  ->  {folder}")
+            pushed += 1
+        if tmp:
+            tmp.unlink(missing_ok=True)
+
+    log(
+        f"\npush complete: {pushed} paper(s) "
+        f"{'would be ' if dry_run else ''}sent to the reMarkable."
+    )
+
+
+def cmd_pull(cfg: ConfigParser, dry_run: bool) -> None:
+    zot = connect(cfg)
+    rm = cfg["remarkable"]
+    base = rm.get("folder", "/Papers")
+    mirror = _truthy(rm.get("mirror_subcollections", "true"))
+    out_dir = Path(rm.get("output_dir", str(Path.home() / "zotrm-annotated")))
+    reattach = _truthy(rm.get("reattach", "true"))
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    coll_key = find_collection_key(zot, rm["collection"])
+
+    pulled = 0
+    for item, folder in iter_items(zot, coll_key, base, mirror):
+        key = item["key"]
+        title = item["data"].get("title", key)[:70]
+        item_tags = tags_of(item)
+        if TAG_SYNCED not in item_tags or TAG_DONE in item_tags:
+            continue
+
+        child = pdf_child(zot, key)
+        if not child:
+            continue
+        _, filename = child
+        stem = Path(filename).stem
+        remote = f"{folder.rstrip('/')}/{stem}"
+        dest = out_dir / f"{stem} (annotated).pdf"
+
+        if dry_run:
+            log(f"  would pull      {title}  ->  {dest}")
+            pulled += 1
+            continue
+
+        # geta = "get annotated": render scribbles onto the original PDF.
+        res = rmapi("geta", remote, str(dest), capture=True)
+        if res.returncode != 0 or not dest.exists():
+            log(f"  no annotations yet / failed   {title}")
+            continue
+
+        if reattach:
+            try:
+                zot.attachment_simple([str(dest)], key)
+            except Exception as e:
+                log(f"    (re-attach skipped: {e}; file saved to {dest})")
+
+        zot.add_tags(item, TAG_DONE)
+        log(f"  pulled          {title}  ->  {dest}")
+        pulled += 1
+
+    log(f"\npull complete: {pulled} annotated paper(s) {'would be ' if dry_run else ''}retrieved.")
+
+
+def cmd_status(cfg: ConfigParser, dry_run: bool) -> None:
+    zot = connect(cfg)
+    rm = cfg["remarkable"]
+    base = rm.get("folder", "/Papers")
+    mirror = _truthy(rm.get("mirror_subcollections", "true"))
+    coll_key = find_collection_key(zot, rm["collection"])
+
+    queued: list[str] = []
+    on_device: list[str] = []
+    done: list[str] = []
+    for item, folder in iter_items(zot, coll_key, base, mirror):
+        t = tags_of(item)
+        title = item["data"].get("title", item["key"])[:60]
+        row = f"{title}   [{folder}]"
+        if TAG_DONE in t:
+            done.append(row)
+        elif TAG_SYNCED in t:
+            on_device.append(row)
+        else:
+            queued.append(row)
+
+    def block(name: str, rows: list[str]) -> None:
+        log(f"\n{name} ({len(rows)})")
+        for r in rows:
+            log(f"  - {r}")
+
+    log(f"Collection: {rm['collection']}  (mirror={mirror})")
+    block("Queued (will push)", queued)
+    block("On reMarkable (reading)", on_device)
+    block("Annotated (back in Zotero)", done)
+
+
+def main(argv: list[str] | None = None) -> None:
+    p = argparse.ArgumentParser(
+        prog="zotrm",
+        description="Bridge a Zotero collection to a reMarkable Paper Pro and back.",
+    )
+    p.add_argument(
+        "--config",
+        type=Path,
+        default=DEFAULT_CONFIG,
+        help=f"config file (default: {DEFAULT_CONFIG})",
+    )
+    p.add_argument("--dry-run", action="store_true", help="show what would happen, change nothing")
+    sub = p.add_subparsers(dest="command", required=True)
+    sub.add_parser("push", help="send queued papers to the reMarkable")
+    sub.add_parser("pull", help="bring annotated papers back into Zotero")
+    sub.add_parser("status", help="show the queue / on-device / done lists")
+    sub.add_parser("sync", help="pull then push, in one go")
+    config_p = sub.add_parser("config", help="create or edit your configuration")
+    config_p.add_argument(
+        "--show", action="store_true", help="print the current config location and values"
+    )
+    cron_p = sub.add_parser("cron", help="schedule an automatic sync")
+    cron_p.add_argument("--remove", action="store_true", help="remove the scheduled sync")
+    cron_p.add_argument("--show", action="store_true", help="show the scheduled sync, if any")
+
+    args = p.parse_args(argv)
+
+    if args.command == "config":
+        from zotrm.wizard import run_config_wizard, show_config
+
+        if args.show:
+            show_config(args.config)
+        else:
+            run_config_wizard(args.config)
+        return
+
+    if args.command == "cron":
+        from zotrm.cron import remove_cron_job, run_cron_setup, show_cron_job
+
+        if args.remove:
+            log("Removed the scheduled sync." if remove_cron_job() else "No scheduled sync found.")
+        elif args.show:
+            line = show_cron_job()
+            log(line if line else "No scheduled sync found.")
+        else:
+            run_cron_setup(args.config)
+        return
+
+    # push / pull / status / sync all need a config. On first run, if we have a
+    # terminal, launch the wizard; otherwise fall through to a clean error.
+    if not args.config.exists() and _interactive():
+        log("No config found yet — let's set it up first.\n")
+        from zotrm.wizard import run_config_wizard
+
+        if not run_config_wizard(args.config):
+            return
+        log("")
+
+    cfg = load_config(args.config)
+
+    if args.command == "push":
+        cmd_push(cfg, args.dry_run)
+    elif args.command == "pull":
+        cmd_pull(cfg, args.dry_run)
+    elif args.command == "status":
+        cmd_status(cfg, args.dry_run)
+    else:  # sync = pull then push
+        cmd_pull(cfg, args.dry_run)
+        cmd_push(cfg, args.dry_run)
+
+
+if __name__ == "__main__":
+    main()

zotrm/config.py

@@ -0,0 +1,42 @@
+"""Configuration loading, validation, and small shared helpers.
+
+State for the whole tool lives in Zotero tags (see the tag constants below),
+so there is no extra database. Configuration is a plain INI file; see the
+README for the template.
+"""
+
+from __future__ import annotations
+
+import configparser
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+# Tags used to track per-item state, entirely inside Zotero.
+TAG_SYNCED = "rm:synced"  # pushed to the device
+TAG_DONE = "rm:annotated"  # annotated copy pulled back
+
+DEFAULT_CONFIG = Path.home() / ".config" / "zotrm" / "config.ini"
+
+
+def die(msg: str, code: int = 1) -> NoReturn:
+    """Print an error to stderr and exit with a non-zero status."""
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def log(msg: str) -> None:
+    """Print a line of progress output, flushing so cron logs stay live."""
+    print(msg, flush=True)
+
+
+def load_config(path: Path) -> configparser.ConfigParser:
+    """Load and minimally validate the INI config, or exit with an error."""
+    if not path.exists():
+        die(f"config not found at {path}\n       create it (see the README for a template).")
+    cfg = configparser.ConfigParser()
+    cfg.read(path)
+    for section in ("zotero", "remarkable"):
+        if section not in cfg:
+            die(f"[{section}] section missing from {path}")
+    return cfg

zotrm/cron.py

@@ -0,0 +1,176 @@
+"""Friendly cron-job setup for automatic sync (the ``zotrm cron`` command).
+
+The interactive parts use questionary; the schedule/cron-line building and the
+crontab merge logic are kept as plain functions so they are easy to test.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import questionary
+
+from zotrm.config import DEFAULT_CONFIG, die, log
+
+MARKER = "# zotrm-sync"
+
+# Friendly label -> fixed cron expression (None means "needs follow-up questions").
+PRESETS: dict[str, str | None] = {
+    "Every hour": "0 * * * *",
+    "Every 6 hours": "0 */6 * * *",
+    "Once a day": None,
+    "Once a week": None,
+    "Advanced (cron expression)": None,
+}
+
+_WEEKDAYS = [
+    ("Monday", 1),
+    ("Tuesday", 2),
+    ("Wednesday", 3),
+    ("Thursday", 4),
+    ("Friday", 5),
+    ("Saturday", 6),
+    ("Sunday", 0),
+]
+
+_TIME_RE = re.compile(r"^([01]?\d|2[0-3]):([0-5]\d)$")
+_CRON_RE = re.compile(r"^\S+(\s+\S+){4}$")
+
+
+def build_schedule(
+    preset: str,
+    *,
+    time: str | None = None,
+    weekday: int | None = None,
+    custom: str | None = None,
+) -> str:
+    """Turn a friendly choice into a 5-field cron expression."""
+    fixed = PRESETS.get(preset)
+    if fixed is not None:
+        return fixed
+    if preset == "Advanced (cron expression)":
+        if not custom or not _CRON_RE.match(custom.strip()):
+            die(f"invalid cron expression: {custom!r}")
+        return custom.strip()
+    if time is None or not _TIME_RE.match(time):
+        die(f"invalid time (expected HH:MM): {time!r}")
+    hour, minute = (int(part) for part in time.split(":"))
+    if preset == "Once a day":
+        return f"{minute} {hour} * * *"
+    if preset == "Once a week":
+        return f"{minute} {hour} * * {weekday}"
+    die(f"unknown schedule: {preset!r}")
+
+
+def zotrm_command(config_path: Path) -> str:
+    """Build the absolute command cron should run."""
+    exe = shutil.which("zotrm")
+    parts = [exe] if exe else [sys.executable, "-m", "zotrm"]
+    if config_path != DEFAULT_CONFIG:
+        parts += ["--config", str(config_path)]
+    parts.append("sync")
+    return " ".join(parts)
+
+
+def build_cron_line(schedule: str, command: str, logfile: str) -> str:
+    return f"{schedule} {command} >> {logfile} 2>&1  {MARKER}"
+
+
+def _crontab(*args: str, stdin: str | None = None) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            ["crontab", *args],
+            input=stdin,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        die("crontab not found on PATH; this command needs cron (macOS/Linux).")
+
+
+def _read_crontab() -> list[str]:
+    res = _crontab("-l")
+    if res.returncode != 0:  # no crontab installed yet
+        return []
+    return res.stdout.splitlines()
+
+
+def _write_crontab(lines: list[str]) -> None:
+    res = _crontab("-", stdin="\n".join(lines) + "\n")
+    if res.returncode != 0:
+        die(f"could not write crontab: {res.stderr.strip()}")
+
+
+def _without_marker(lines: list[str]) -> list[str]:
+    return [line for line in lines if MARKER not in line]
+
+
+def install_cron_line(line: str) -> None:
+    """Add our cron line, replacing any previous zotrm-sync line."""
+    lines = _without_marker(_read_crontab())
+    lines.append(line)
+    _write_crontab(lines)
+
+
+def remove_cron_job() -> bool:
+    """Remove our cron line. Returns True if one was present."""
+    lines = _read_crontab()
+    kept = _without_marker(lines)
+    if len(kept) == len(lines):
+        return False
+    _write_crontab(kept)
+    return True
+
+
+def show_cron_job() -> str | None:
+    for line in _read_crontab():
+        if MARKER in line:
+            return line
+    return None
+
+
+def _ask(question: Any) -> Any:
+    answer = question.ask()
+    if answer is None:
+        die("cancelled")
+    return answer
+
+
+def run_cron_setup(config_path: Path) -> None:
+    """Interactively schedule an automatic ``zotrm sync`` via cron."""
+    if not config_path.exists():
+        log(f"No config at {config_path}. Run 'zotrm config' first.")
+        return
+
+    preset = str(_ask(questionary.select("How often should it sync?", choices=list(PRESETS))))
+
+    time: str | None = None
+    weekday: int | None = None
+    custom: str | None = None
+    if preset == "Once a day":
+        time = str(_ask(questionary.text("What time? (24h, e.g. 07:30)", default="07:00")))
+    elif preset == "Once a week":
+        day = str(_ask(questionary.select("Which day?", choices=[name for name, _ in _WEEKDAYS])))
+        weekday = dict(_WEEKDAYS)[day]
+        time = str(_ask(questionary.text("What time? (24h, e.g. 07:30)", default="07:00")))
+    elif preset == "Advanced (cron expression)":
+        custom = str(_ask(questionary.text("Cron expression (5 fields)", default="*/30 * * * *")))
+
+    schedule = build_schedule(preset, time=time, weekday=weekday, custom=custom)
+    logfile = str(config_path.parent / "sync.log")
+    line = build_cron_line(schedule, zotrm_command(config_path), logfile)
+
+    log(f"\nThis line will be added to your crontab:\n\n  {line}\n")
+    if not bool(_ask(questionary.confirm("Install it?", default=True))):
+        log("Aborted; crontab unchanged.")
+        return
+
+    install_cron_line(line)
+    log(f"  ✓ Scheduled. Logs will go to {logfile}")
+    log("  Check it any time with 'crontab -l' or 'zotrm cron --show'.")

zotrm/remarkable.py

@@ -0,0 +1,37 @@
+"""Thin wrapper around the external ``rmapi`` binary (the ddvk fork).
+
+``rmapi`` is a runtime system prerequisite, not a Python dependency. If it is
+not on PATH we fail with a clear, actionable message instead of a traceback.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from zotrm.config import die
+
+# Remote folders created this process; avoids redundant mkdir calls.
+_MADE_FOLDERS: set[str] = set()
+
+
+def rmapi(*args: str, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    """Run an rmapi sub-command non-interactively."""
+    try:
+        return subprocess.run(
+            ["rmapi", *args],
+            check=False,
+            text=True,
+            capture_output=capture,
+        )
+    except FileNotFoundError:
+        die("rmapi not found on PATH. Install the ddvk fork: brew install rmapi")
+
+
+def ensure_remote_folder(folder: str) -> None:
+    """Create a (possibly nested) reMarkable folder, one level at a time."""
+    path = ""
+    for part in (p for p in folder.strip("/").split("/") if p):
+        path = f"{path}/{part}"
+        if path not in _MADE_FOLDERS:
+            rmapi("mkdir", path, capture=True)  # harmless if it already exists
+            _MADE_FOLDERS.add(path)

zotrm/wizard.py

@@ -0,0 +1,194 @@
+"""Interactive setup wizard for the config file (the ``zotrm config`` command).
+
+Uses ``questionary`` for arrow-key menus, masked secret entry, and validation.
+It is only ever run interactively, so importing this module (and therefore
+questionary) is deferred until a wizard command is actually used.
+"""
+
+from __future__ import annotations
+
+import configparser
+import shutil
+from configparser import ConfigParser
+from pathlib import Path
+from typing import Any
+
+import questionary
+
+from zotrm.config import die, log
+from zotrm.zotero import connect
+
+
+def _ask(question: Any) -> Any:
+    """Run a questionary prompt, aborting cleanly if the user cancels (Ctrl-C)."""
+    answer = question.ask()
+    if answer is None:
+        die("setup cancelled")
+    return answer
+
+
+def _text(message: str, default: str = "", required: bool = False) -> str:
+    validate: Any = None
+    if required:
+        validate = lambda v: True if v.strip() else "This field is required."  # noqa: E731
+    return str(_ask(questionary.text(message, default=default, validate=validate))).strip()
+
+
+def _password(message: str, default: str = "") -> str:
+    # questionary.password cannot show a default; offer to keep the existing value.
+    if default and _confirm("Keep the existing API key?", default=True):
+        return default
+    return str(_ask(questionary.password(message))).strip()
+
+
+def _select(message: str, choices: list[str], default: str) -> str:
+    return str(_ask(questionary.select(message, choices=choices, default=default)))
+
+
+def _confirm(message: str, default: bool) -> bool:
+    return bool(_ask(questionary.confirm(message, default=default)))
+
+
+def _path(message: str, default: str = "") -> str:
+    return str(_ask(questionary.path(message, default=default))).strip()
+
+
+def _existing(path: Path) -> dict[str, str]:
+    """Flatten an existing config into a single dict for use as defaults."""
+    if not path.exists():
+        return {}
+    cfg = ConfigParser()
+    cfg.read(path)
+    values: dict[str, str] = {}
+    for section in ("zotero", "remarkable"):
+        if section in cfg:
+            values.update(cfg[section])
+    return values
+
+
+def _as_bool(value: str | None, default: bool) -> bool:
+    if value is None:
+        return default
+    return value.strip().lower() in ("1", "true", "yes")
+
+
+def _to_configparser(values: dict[str, dict[str, str]]) -> ConfigParser:
+    cfg = ConfigParser()
+    for section, kv in values.items():
+        cfg[section] = {k: v for k, v in kv.items() if v != ""}
+    return cfg
+
+
+def _verify_zotero(cfg: ConfigParser) -> tuple[bool, str]:
+    try:
+        zot = connect(cfg)
+        count = zot.num_items()
+        return True, f"Zotero connection OK ({count} items)"
+    except Exception as e:
+        return False, f"Zotero check failed: {e}"
+
+
+def _render(values: dict[str, dict[str, str]]) -> str:
+    """Render a self-documenting INI file from the collected values."""
+    z = values["zotero"]
+    r = values["remarkable"]
+    lines = [
+        "[zotero]",
+        f"library_id   = {z['library_id']}",
+        f"api_key      = {z['api_key']}",
+        f"library_type = {z['library_type']}",
+    ]
+    if z.get("storage_dir"):
+        lines.append("# Local Zotero storage, to avoid re-downloading PDFs.")
+        lines.append(f"storage_dir  = {z['storage_dir']}")
+    lines += [
+        "",
+        "[remarkable]",
+        "# The Zotero collection whose items get pushed to the tablet.",
+        f"collection            = {r['collection']}",
+        "# Folder on the reMarkable where papers land (created if missing).",
+        f"folder                = {r['folder']}",
+        "# Recreate Zotero sub-collections as nested folders on the tablet?",
+        f"mirror_subcollections = {r['mirror_subcollections']}",
+        "# Where annotated PDFs are written locally when pulled back.",
+        f"output_dir            = {r['output_dir']}",
+        "# Re-attach the annotated PDF to the Zotero item?",
+        f"reattach              = {r['reattach']}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def run_config_wizard(path: Path) -> bool:
+    """Collect settings interactively and write them to ``path``.
+
+    Returns True if a config file was written, False if the user aborted.
+    """
+    prior = _existing(path)
+    log("Let's set up zotrm.\n" if not prior else f"Editing {path}\n")
+
+    home_annotated = str(Path.home() / "Zotero" / "annotated")
+    values: dict[str, dict[str, str]] = {
+        "zotero": {
+            "library_id": _text("Zotero library ID", prior.get("library_id", ""), required=True),
+            "api_key": _password("Zotero API key", prior.get("api_key", "")),
+            "library_type": _select(
+                "Library type", ["user", "group"], prior.get("library_type", "user")
+            ),
+            "storage_dir": _path(
+                "Local Zotero storage dir (optional, Enter to skip)",
+                prior.get("storage_dir", ""),
+            ),
+        },
+        "remarkable": {
+            "collection": _text("Zotero collection to sync", prior.get("collection", "reMarkable")),
+            "folder": _text("reMarkable folder", prior.get("folder", "/Papers")),
+            "mirror_subcollections": str(
+                _confirm(
+                    "Mirror sub-collections as nested folders?",
+                    _as_bool(prior.get("mirror_subcollections"), True),
+                )
+            ).lower(),
+            "output_dir": _path(
+                "Where to save annotated PDFs", prior.get("output_dir", home_annotated)
+            ),
+            "reattach": str(
+                _confirm(
+                    "Re-attach the annotated PDF to the Zotero item?",
+                    _as_bool(prior.get("reattach"), True),
+                )
+            ).lower(),
+        },
+    }
+
+    log("")
+    ok, message = _verify_zotero(_to_configparser(values))
+    log(f"  {'✓' if ok else '✗'} {message}")
+    if shutil.which("rmapi"):
+        log("  ✓ rmapi found on PATH")
+    else:
+        log("  ✗ rmapi not found — install the ddvk fork: brew install rmapi")
+
+    if not ok and not _confirm("Zotero check failed. Save the config anyway?", default=True):
+        log("Aborted; nothing written.")
+        return False
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(_render(values))
+    log(f"  ✓ Wrote {path}")
+    return True
+
+
+def show_config(path: Path) -> None:
+    """Print the config location and its values, masking the API key."""
+    if not path.exists():
+        log(f"No config at {path}. Run 'zotrm config' to create one.")
+        return
+    cfg = configparser.ConfigParser()
+    cfg.read(path)
+    log(f"Config: {path}\n")
+    for section in cfg.sections():
+        log(f"[{section}]")
+        for key, value in cfg[section].items():
+            shown = "********" if key == "api_key" and value else value
+            log(f"  {key} = {shown}")

zotrm/zotero.py

@@ -0,0 +1,76 @@
+"""pyzotero wrapper: connection, collection walk, and tag helpers.
+
+``pyzotero`` ships no type stubs, so the live Zotero client is typed as
+``Any``; the helpers below pin down the small slices of its API we use.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from configparser import ConfigParser
+from pathlib import Path
+from typing import Any
+
+from zotrm.config import die
+
+
+def connect(cfg: ConfigParser) -> Any:
+    """Build a pyzotero client from the [zotero] config section."""
+    from pyzotero import zotero  # imported lazily so --help works without it
+
+    z = cfg["zotero"]
+    return zotero.Zotero(
+        z["library_id"],
+        z.get("library_type", "user"),
+        z["api_key"],
+    )
+
+
+def find_collection_key(zot: Any, name: str) -> str:
+    """Return the key of the collection named ``name``, or exit if missing."""
+    for c in zot.everything(zot.collections()):
+        if c["data"]["name"] == name:
+            return str(c["key"])
+    die(f"no Zotero collection named {name!r} found")
+
+
+def pdf_child(zot: Any, item_key: str) -> tuple[str, str] | None:
+    """Return (attachment_key, filename) of the first PDF attachment, or None."""
+    for child in zot.children(item_key):
+        data = child["data"]
+        if data.get("contentType") == "application/pdf" and data.get("filename"):
+            return str(child["key"]), str(data["filename"])
+    return None
+
+
+def local_pdf_path(cfg: ConfigParser, att_key: str, filename: str) -> Path | None:
+    """Return the locally-synced PDF path if it exists, else None."""
+    storage = cfg["zotero"].get("storage_dir", "").strip()
+    if storage:
+        p = Path(storage) / att_key / filename
+        if p.exists():
+            return p
+    return None
+
+
+def tags_of(item: Any) -> set[str]:
+    """Return the set of tag strings on a Zotero item."""
+    return {t["tag"] for t in item["data"].get("tags", [])}
+
+
+def iter_items(
+    zot: Any, coll_key: str, base_folder: str, mirror: bool
+) -> Iterator[tuple[Any, str]]:
+    """Yield (item, remote_folder) for every item under a collection.
+
+    If mirror is True, Zotero sub-collections are recreated as nested
+    reMarkable folders (e.g. reMarkable/Multimodal/Retrieval). If False,
+    everything lands flat in base_folder.
+    """
+    for item in zot.everything(zot.collection_items_top(coll_key)):
+        yield item, base_folder
+    if not mirror:
+        return
+    for sub in zot.everything(zot.collections_sub(coll_key)):
+        sub_folder = f"{base_folder.rstrip('/')}/{sub['data']['name']}"
+        yield from iter_items(zot, sub["key"], sub_folder, mirror)

zotrm-0.1.0.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: zotrm
+Version: 0.1.0
+Summary: Bridge a Zotero collection to a reMarkable Paper Pro: push PDFs, pull annotations.
+Project-URL: Homepage, https://roydipta.com
+Project-URL: Repository, https://github.com/dipta007/zotRm
+Author: Shubhashis Roy Dipta
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotations,pdf,remarkable,rmapi,zotero
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: pyzotero>=1.5
+Requires-Dist: questionary>=2.0
+Description-Content-Type: text/markdown
+
+# zotrm
+
+[![CI](https://github.com/dipta007/zotRm/actions/workflows/ci.yml/badge.svg)](https://github.com/dipta007/zotRm/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/zotrm.svg)](https://pypi.org/project/zotrm/)
+[![Python](https://img.shields.io/pypi/pyversions/zotrm.svg)](https://pypi.org/project/zotrm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/dipta007/zotRm/blob/main/LICENSE)
+
+Read your Zotero papers on a **reMarkable Paper Pro**, then get your handwritten
+notes back into Zotero — with one command.
+
+## Demo
+
+![zotrm in action: push papers, annotate on the tablet, pull them back](https://raw.githubusercontent.com/dipta007/zotRm/main/docs/demo.gif)
+
+> _Recording the GIF: see [how to record the demo](https://github.com/dipta007/zotRm/blob/main/docs/advanced-usage.md#recording-the-demo-gif)._
+
+**What it does, in plain words:**
+
+- **push** — sends the PDFs from one Zotero collection to your reMarkable tablet.
+- **pull** — brings the marked-up PDFs back and attaches them to the same Zotero papers.
+- **status** — shows which papers are waiting, on the tablet, or already done.
+- **sync** — does a pull and then a push, together.
+
+You never push or pull the same paper twice by mistake — the tool remembers what it has
+done. It is safe to run again and again.
+
+> **One honest limit (this is reMarkable's behavior, not a bug here):**
+> Your highlights and handwriting come back as part of the PDF image — "painted onto"
+> the page. They do **not** come back as clickable Zotero highlights.
+
+## Why zotrm?
+
+If you read research papers on a reMarkable, getting them on and off the tablet is fiddly:
+export each PDF, drag it into the reMarkable app, and later dig the annotated copy back
+out and re-file it in Zotero. zotrm makes that **one command in each direction**, driven by
+the collection you already curate in Zotero:
+
+- **No manual file shuffling** — it reads your Zotero collection and uploads the PDFs for you.
+- **Folders match your library** — Zotero sub-collections become nested folders on the tablet.
+- **Nothing pushed or pulled twice** — progress is tracked with Zotero tags, so it's safe to
+  re-run or schedule with `zotrm cron`.
+- **No extra database or account** — just your Zotero API key and the `rmapi` tool.
+
+It's a small, focused CLI — not a sync daemon or a cloud service.
+
+---
+
+## Before you start (what you need)
+
+1. A **Zotero** account with some PDFs in it.
+2. A **reMarkable** tablet, turned on and connected to WiFi.
+3. A **reMarkable Connect** subscription — this is what lets files move to and from the
+   tablet over the internet. Without it, push and pull may not work.
+4. A computer (Mac or Linux) where you can open a **Terminal** (a window where you type
+   commands). On a Mac, open the app called **Terminal**.
+
+You will copy and paste a few commands. That is all.
+
+---
+
+## Setup (about 10 minutes)
+
+### Step 1 — Install `uv`
+
+`uv` installs this tool for you. Paste this into the Terminal and press Enter:
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Close the Terminal and open it again so the change takes effect.
+
+### Step 2 — Install `rmapi` and connect it to your tablet
+
+`rmapi` is a separate program that talks to your reMarkable:
+
+```sh
+brew install rmapi
+```
+
+(No Homebrew? See <https://github.com/ddvk/rmapi> for other ways. Use the **ddvk**
+version — the original does not work with new tablets.)
+
+Now connect it to your tablet **one time**:
+
+```sh
+rmapi
+```
+
+It shows a web address and asks for a code. Open
+<https://my.remarkable.com/device/desktop>, copy the code shown there, and paste it into
+the Terminal. Done — you won't do this again.
+
+### Step 3 — Install `zotrm`
+
+```sh
+uv tool install zotrm
+```
+
+### Step 4 — Set up your account (answer a few questions)
+
+Just run:
+
+```sh
+zotrm config
+```
+
+It asks you a few simple questions (use the arrow keys and Enter), then checks that your
+details work. To answer the two Zotero questions:
+
+- Open <https://www.zotero.org/settings/keys>.
+- Your **library ID** is the number shown as "Your userID".
+- Click **Create new private key**, allow read **and write**, and copy the key it gives
+  you.
+
+> **Tip:** In Zotero, make a collection (for example named `reMarkable`) and drag the
+> papers you want to read into it. Give that same name when the wizard asks for the
+> collection.
+
+That's it — your settings are saved automatically. (The very first time you run any
+command, this wizard starts on its own if you haven't set up yet.)
+
+### Step 5 — Use it
+
+Send your papers to the tablet:
+
+```sh
+zotrm push
+```
+
+Read and annotate them on the reMarkable. When you're done, bring them back:
+
+```sh
+zotrm pull
+```
+
+That's the whole loop. 🎉
+
+### Step 6 (optional) — Make it automatic
+
+Want it to sync by itself on a schedule? Run:
+
+```sh
+zotrm cron
+```
+
+Pick how often (every hour, daily, etc.) and it sets everything up for you. Remove it
+later with `zotrm cron --remove`.
+
+---
+
+## Everyday commands
+
+```sh
+zotrm push      # send waiting papers to the tablet
+zotrm pull      # bring marked-up papers back into Zotero
+zotrm status    # see what is waiting / on the tablet / done
+zotrm sync      # pull, then push, in one step
+
+zotrm config    # change your settings any time
+zotrm cron      # set up (or change) automatic syncing
+```
+
+Not sure what a command will do? Add `--dry-run` to see without changing anything:
+
+```sh
+zotrm --dry-run push
+```
+
+---
+
+## If something goes wrong
+
+- **"rmapi not found"** → Step 2 was missed, or reopen the Terminal.
+- **"config not found"** → Run `zotrm config` to set up your account.
+- **"no Zotero collection named ..."** → The collection name in your settings doesn't
+  exactly match a collection in Zotero. Check spelling and capital letters
+  (`zotrm config --show` prints your current settings).
+- **Pull finds nothing** → Make sure the tablet is online and finished syncing, and that
+  you have a reMarkable Connect subscription.
+
+Run any command with `--dry-run` first if you're unsure — it changes nothing.
+
+---
+
+## FAQ
+
+**Do I need a reMarkable Connect subscription?**
+Yes, in practice. `zotrm` talks to the reMarkable **cloud** through `rmapi`, and two-way
+document sync (uploading PDFs and downloading annotated ones) needs Connect.
+
+**Why don't my highlights come back as real Zotero highlights?**
+The reMarkable returns a flattened PDF — your marks are baked into the page image. That's a
+reMarkable limitation, not something `zotrm` can change. You get a faithful annotated PDF
+re-attached to the item, just not editable highlight objects.
+
+**Does it duplicate files if I run it again?**
+No. It tags items `rm:synced` once pushed and `rm:annotated` once pulled back, and skips
+anything already done. Re-run it (or schedule it) freely.
+
+**Can I use it with more than one Zotero library?**
+Yes — keep separate config files and pass `--config`. See
+[advanced usage](https://github.com/dipta007/zotRm/blob/main/docs/advanced-usage.md#global-flags).
+
+**Does it work on Windows?**
+Not currently. `zotrm` targets macOS and Linux (the `cron` scheduler is Unix-only).
+
+**Is my Zotero API key safe?**
+It's stored only in your local config file (`~/.config/zotrm/config.ini`) and never sent
+anywhere except Zotero's own API. `zotrm config --show` masks it.
+
+---
+
+## More
+
+- **[Advanced usage](https://github.com/dipta007/zotRm/blob/main/docs/advanced-usage.md)** —
+  editing the config file by hand, the full settings reference, how the scheduled sync
+  works, multiple configs, and deeper troubleshooting.
+- **[Contributing](https://github.com/dipta007/zotRm/blob/main/CONTRIBUTING.md)** — set up
+  the project for development and run the tests.
+
+## License
+
+MIT — see [LICENSE](https://github.com/dipta007/zotRm/blob/main/LICENSE).

zotrm-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+zotrm/__init__.py,sha256=dQSrozlQVGQ5OEjriTHU0U8bI3uAqOMaN4FvDKCLv6g,102
+zotrm/__main__.py,sha256=EPqmnVMXDviTpUsyw3XV30-0aokC4yei14C8bbSdptM,135
+zotrm/cli.py,sha256=l18Gp1uPISHwNqU5INUR2ZubsQqO5Xtoo0S3pu5h5Cw,8058
+zotrm/config.py,sha256=mnzwo5UCZlwRwdJ---4Pa2LWnz2K568uTuxFs5BBAZM,1376
+zotrm/cron.py,sha256=hZghpPk8nARLdLTuc9Mle2c7ohrPSejB73rciDq0Jtw,5428
+zotrm/remarkable.py,sha256=GpBuN2MRaQv3Pwy2kj6nNz6kQd4jU_NVHnvIQvrKrQA,1221
+zotrm/wizard.py,sha256=JW1ZF4TXzqAevbtOPXV0bXnjws8sYNzx1gbUHRfuJOg,6894
+zotrm/zotero.py,sha256=Gz0qJ91hrBCUz7IjaVn_aaW8PrSWBNtbbBvczDVrHgI,2621
+zotrm-0.1.0.dist-info/METADATA,sha256=QoKq40upwmr7WUydDUWpbJrMkv1PxlAqW6TGMqjMf5s,8863
+zotrm-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+zotrm-0.1.0.dist-info/entry_points.txt,sha256=b-7bS0Byeu3-VIxXGdISRKdpsNhKwLmCA-pKbjmv5io,41
+zotrm-0.1.0.dist-info/licenses/LICENSE,sha256=IqkO3GTk9vcWZBUMHYTbz9K7mEngJAWfRy7ohgzicIU,1077
+zotrm-0.1.0.dist-info/RECORD,,

zotrm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

zotrm-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zotrm = zotrm.cli:main

zotrm-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubhashis Roy Dipta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.