torrdown 0.1.0__py3-none-any.whl

torrdown/__init__.py

@@ -0,0 +1,3 @@
+"""TorrDown - a single-session libtorrent download CLI."""
+
+__version__ = "0.1.0"

torrdown/__main__.py

@@ -0,0 +1,5 @@
+"""Enables `python -m torrdown`."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

torrdown/cli.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""Command-line interface for TorrDown.
+
+Subcommands: add / batch / resume / status / list / config.
+Run bare (`torrdown` with no subcommand) for the interactive menu."""
+import argparse
+import signal
+import sys
+
+from . import __version__
+from .config import Config
+from .state import StateStore
+from .engine import TorrentEngine
+from .magnets import read_magnets_file, archive_results
+from .sources import resolve_token, resolve_many, list_torrent_files, SourceError
+
+
+# ---------------------------------------------------------------- engine glue
+
+def _make_engine(cfg):
+    state = StateStore(str(cfg.state_file))
+    state.load()
+
+    def archive_one(source, status, reason):
+        # Only rewrites lines that actually appear in the magnets file, so
+        # this is a no-op for add/interactive sources that aren't in it.
+        archive_results(str(cfg.magnets_file), {source: (status, reason)})
+
+    engine = TorrentEngine(
+        cfg.download_dir, state,
+        port=cfg.port, max_concurrent=cfg.max_concurrent,
+        metadata_timeout=cfg.metadata_timeout,
+        checkpoint_interval=cfg.checkpoint_interval,
+        heartbeat_delay=cfg.heartbeat_delay,
+        on_result=archive_one,
+    )
+    signal.signal(signal.SIGINT, lambda *_: engine.request_shutdown())
+    signal.signal(signal.SIGTERM, lambda *_: engine.request_shutdown())
+    return engine
+
+
+def _download(cfg, sources, resume=True):
+    """Shared path for every downloading command: resume interrupted work,
+    add the requested sources, run until done. `sources` is a list of
+    (source, label)."""
+    cfg.ensure_dirs()
+    engine = _make_engine(cfg)
+    try:
+        if resume:
+            engine.resume_from_state()
+        for source, label in sources:
+            engine.add_source(source, label)
+        if not engine.has_work():
+            print("Nothing to download.")
+            return
+        engine.run()
+    finally:
+        engine.close()
+
+
+# ------------------------------------------------------------------- commands
+
+def cmd_add(cfg, args):
+    sources, errors = resolve_many(args.sources, cfg.torrents_dir)
+    for err in errors:
+        print(f"Skipping: {err}")
+    if args.name and len(sources) == 1:
+        sources = [(sources[0][0], args.name)]
+    if not sources:
+        print("No valid sources to add.")
+        return 1
+    _download(cfg, sources)
+    return 0
+
+
+def cmd_batch(cfg, args):
+    path = args.file or str(cfg.magnets_file)
+    magnets = read_magnets_file(path)
+    if not magnets:
+        print(f"No magnet links found in {path}!")
+        return 1
+    print(f"\nFound {len(magnets)} magnet link(s) in {path} - "
+          f"downloading up to {cfg.max_concurrent} at a time.\n")
+    sources, _ = resolve_many(magnets, cfg.torrents_dir)
+    _download(cfg, sources)
+    return 0
+
+
+def cmd_resume(cfg, args):
+    _download(cfg, sources=[], resume=True)
+    return 0
+
+
+def _fmt_size(n):
+    if not n:
+        return ""
+    size = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024 or unit == "TB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+
+
+def _progress_cell(rec):
+    if rec.get("status") == "done":
+        return "100%"
+    prog = rec.get("progress")
+    if prog is None:
+        return "-"
+    pct = f"{prog * 100:.0f}%"
+    total = rec.get("total_bytes")
+    if total:
+        return f"{pct}  {_fmt_size(prog * total)}/{_fmt_size(total)}"
+    return pct
+
+
+def cmd_status(cfg, args):
+    cfg.ensure_config_dir()
+    state = StateStore(str(cfg.state_file))
+    records = state.load()
+    if not records:
+        print("No tracked torrents.")
+        return 0
+    try:
+        from rich.console import Console
+        from rich.table import Table
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("ID")
+        table.add_column("Label", overflow="fold", max_width=44)
+        table.add_column("Status")
+        table.add_column("Progress")
+        table.add_column("Updated")
+        table.add_column("Error", overflow="fold")
+        for info_hash, rec in records.items():
+            table.add_row(
+                info_hash[:8], rec.get("label", "?"), rec.get("status", "?"),
+                _progress_cell(rec), rec.get("updated_at", ""), rec.get("error") or "",
+            )
+        Console().print(table)
+    except Exception:
+        for info_hash, rec in records.items():
+            print(f"{info_hash[:8]}  {rec.get('status','?'):16} {_progress_cell(rec):8} "
+                  f"{rec.get('label','?')}"
+                  + (f"  ({rec.get('error')})" if rec.get("error") else ""))
+    print("\nTip: `torrdown resume` shows live speed for active downloads.")
+    return 0
+
+
+def cmd_remove(cfg, args):
+    cfg.ensure_config_dir()
+    state = StateStore(str(cfg.state_file))
+    records = state.load()
+    if not records:
+        print("No tracked torrents.")
+        return 0
+    removed_any = False
+    for token in args.ids:
+        matches = state.find(token)
+        if not matches:
+            print(f"No match for {token!r}.")
+            continue
+        if len(matches) > 1:
+            print(f"{token!r} matches {len(matches)} entries - use a longer info-hash prefix.")
+            continue
+        info_hash = matches[0]
+        label = records[info_hash].get("label", info_hash)
+        state.remove(info_hash)
+        removed_any = True
+        print(f"Removed {label}")
+    if removed_any:
+        state.save()
+        print("(download files on disk are left untouched)")
+    return 0
+
+
+def cmd_clear(cfg, args):
+    cfg.ensure_config_dir()
+    state = StateStore(str(cfg.state_file))
+    state.load()
+    count = state.clear(only_terminal=not args.all)
+    if count:
+        state.save()
+    kind = "" if args.all else "completed/failed "
+    noun = "entry" if count == 1 else "entries"
+    print(f"Cleared {count} {kind}{noun}. Download files are left untouched.")
+    return 0
+
+
+def cmd_list(cfg, args):
+    cfg.ensure_config_dir()
+    torrents = list_torrent_files(cfg.torrents_dir)
+    if not torrents:
+        print(f"No .torrent files found in '{cfg.torrents_dir}'.")
+        return 0
+    print(f"\nTorrent files in {cfg.torrents_dir}:\n")
+    for i, t in enumerate(torrents, 1):
+        print(f"{i}. {t}")
+    return 0
+
+
+def cmd_init(cfg, args):
+    cfg.ensure_dirs()
+    print("Initialized TorrDown directories:")
+    print(f"  Config dir:   {cfg.config_dir}")
+    print(f"  Download dir: {cfg.download_dir}")
+    print(f"  Torrents dir: {cfg.torrents_dir}")
+    return 0
+
+
+def cmd_config(cfg, args):
+    cfg.ensure_config_dir()
+    print(f"Config file: {cfg.config_file}")
+    print(f"State file:  {cfg.state_file}")
+    print(f"Magnets file: {cfg.magnets_file}")
+    print("\nResolved settings:")
+    for key, value in cfg.as_dict().items():
+        print(f"  {key}: {value}")
+    return 0
+
+
+# ---------------------------------------------------------------- interactive
+
+def cmd_interactive(cfg, args):
+    cfg.ensure_dirs()
+    torrents = list_torrent_files(cfg.torrents_dir)
+    if torrents:
+        print("\nAvailable Torrent Files:\n")
+        for i, t in enumerate(torrents, 1):
+            print(f"{i}. {t}")
+    else:
+        print(f"\nNo .torrent files found in '{cfg.torrents_dir}'.")
+
+    inp = input("\nSelect index (comma separated), paste Magnet link, or type "
+                "'m' to batch-download from magnets.txt: ").strip()
+
+    if inp.lower() == "m":
+        return cmd_batch(cfg, argparse.Namespace(file=None))
+
+    if not inp:
+        print("Nothing selected.")
+        return 0
+
+    tokens = [inp] if inp.startswith("magnet:?") else [t.strip() for t in inp.split(",")]
+    sources, errors = resolve_many(tokens, cfg.torrents_dir)
+    for err in errors:
+        print(err)
+    if not sources:
+        print("No valid selection.")
+        return 1
+    _download(cfg, sources)
+    return 0
+
+
+# -------------------------------------------------------------------- parsing
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="torrdown",
+        description="Single-session libtorrent download CLI.",
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"torrdown {__version__}")
+    parser.add_argument("--config-dir", help="Override the config/state directory.")
+    parser.add_argument("--download-dir", help="Override the download directory.")
+    parser.add_argument("--verbose", action="store_true",
+                        help="Print full tracebacks on error.")
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_add = sub.add_parser("add", help="Add magnet link(s) or .torrent path(s) and download.")
+    p_add.add_argument("sources", nargs="+", help="Magnet links, .torrent paths, or file indices.")
+    p_add.add_argument("--name", help="Label override (only when adding a single source).")
+    p_add.set_defaults(func=cmd_add)
+
+    p_batch = sub.add_parser("batch", help="Download all magnets in a file (default: magnets.txt).")
+    p_batch.add_argument("file", nargs="?", help="Path to a magnets file.")
+    p_batch.set_defaults(func=cmd_batch)
+
+    p_resume = sub.add_parser("resume", help="Resume interrupted downloads from saved state.")
+    p_resume.set_defaults(func=cmd_resume)
+
+    p_status = sub.add_parser("status", help="Show tracked torrents and their state.")
+    p_status.set_defaults(func=cmd_status)
+
+    p_remove = sub.add_parser("remove", help="Remove tracked entries by ID (info-hash prefix) or label.")
+    p_remove.add_argument("ids", nargs="+", help="Info-hash prefixes (see `status`) or exact labels.")
+    p_remove.set_defaults(func=cmd_remove)
+
+    p_clear = sub.add_parser("clear", help="Clear completed/failed entries (or all with --all).")
+    p_clear.add_argument("--all", action="store_true", help="Also clear active entries.")
+    p_clear.set_defaults(func=cmd_clear)
+
+    p_list = sub.add_parser("list", help="List local .torrent files.")
+    p_list.set_defaults(func=cmd_list)
+
+    p_config = sub.add_parser("config", help="Show resolved config and file locations.")
+    p_config.set_defaults(func=cmd_config)
+
+    p_init = sub.add_parser("init", help="Create the config/download/torrents directories.")
+    p_init.set_defaults(func=cmd_init)
+
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    cfg = Config(
+        config_dir=args.config_dir,
+        overrides={"download_dir": args.download_dir},
+    )
+
+    func = getattr(args, "func", None) or cmd_interactive
+    try:
+        return func(cfg, args)
+    except SourceError as exc:
+        print(f"Error: {exc}")
+        return 1
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:
+        if getattr(args, "verbose", False):
+            raise
+        print(f"Error: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

torrdown/config.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Resolves TorrDown's paths and tunables.
+
+Precedence, highest first: explicit CLI overrides > TORRDOWN_* env vars >
+config.json > built-in defaults. Config and state live in a per-user config
+dir (not the working directory), so the tool behaves the same regardless of
+where it's launched from."""
+import os
+import sys
+import json
+from pathlib import Path
+
+DEFAULTS = {
+    "download_dir": None,    # resolved lazily to ~/Downloads/torrdown
+    "torrents_dir": None,    # resolved lazily to download_dir (drop .torrent files there)
+    "port": 6881,
+    "max_concurrent": 3,
+    "metadata_timeout": 180,
+    "checkpoint_interval": 30,
+    "heartbeat_delay": 15,
+}
+
+# Keys the user may override via TORRDOWN_<KEY> env vars, with their types.
+_ENV_TYPES = {
+    "download_dir": str,
+    "torrents_dir": str,
+    "port": int,
+    "max_concurrent": int,
+    "metadata_timeout": int,
+    "checkpoint_interval": int,
+    "heartbeat_delay": int,
+}
+
+
+def default_config_dir():
+    """Per-user config/state dir. Honors XDG on Linux/macOS and APPDATA on
+    Windows, falling back to ~/.config/torrdown."""
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "torrdown"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "torrdown"
+    return Path.home() / ".config" / "torrdown"
+
+
+def _coerce(key, value):
+    caster = _ENV_TYPES.get(key, str)
+    return caster(value)
+
+
+class Config:
+    def __init__(self, config_dir=None, overrides=None):
+        self.config_dir = Path(config_dir) if config_dir else default_config_dir()
+        self._overrides = {k: v for k, v in (overrides or {}).items() if v is not None}
+        self._file_values = {}
+        self._resolved = None
+
+    # --- paths derived from the config dir ---
+    @property
+    def config_file(self):
+        return self.config_dir / "config.json"
+
+    @property
+    def state_file(self):
+        return self.config_dir / "state.json"
+
+    @property
+    def magnets_file(self):
+        return self.config_dir / "magnets.txt"
+
+    def ensure_config_dir(self):
+        """Create the config dir and a default config.json on first run.
+        Cheap - used by read-only commands (status/list/config) that shouldn't
+        create download directories as a side effect."""
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        if not self.config_file.exists():
+            self._write_default_config()
+
+    def ensure_dirs(self):
+        """ensure_config_dir plus the resolved download/torrents dirs - used by
+        commands that actually download."""
+        self.ensure_config_dir()
+        Path(self.download_dir).mkdir(parents=True, exist_ok=True)
+        Path(self.torrents_dir).mkdir(parents=True, exist_ok=True)
+
+    def _write_default_config(self):
+        template = {
+            "_comment": "TorrDown config. Delete a key to fall back to its default. "
+                        "CLI flags and TORRDOWN_* env vars override these.",
+            "download_dir": str(Path.home() / "Downloads" / "torrdown"),
+            "torrents_dir": "",
+            "port": DEFAULTS["port"],
+            "max_concurrent": DEFAULTS["max_concurrent"],
+            "metadata_timeout": DEFAULTS["metadata_timeout"],
+            "checkpoint_interval": DEFAULTS["checkpoint_interval"],
+            "heartbeat_delay": DEFAULTS["heartbeat_delay"],
+        }
+        tmp = self.config_file.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(template, indent=2))
+        os.replace(tmp, self.config_file)
+
+    def _load_file(self):
+        if not self.config_file.exists():
+            return {}
+        try:
+            data = json.loads(self.config_file.read_text())
+        except (json.JSONDecodeError, OSError, UnicodeDecodeError) as exc:
+            print(f"Warning: {self.config_file} is unreadable ({exc}); using defaults.")
+            return {}
+        return {k: v for k, v in data.items()
+                if k in DEFAULTS and v not in (None, "")}
+
+    def resolve(self):
+        """Merge the layers once and cache the result."""
+        if self._resolved is not None:
+            return self._resolved
+        self._file_values = self._load_file()
+
+        merged = dict(DEFAULTS)
+        merged.update(self._file_values)
+        for key in DEFAULTS:
+            env_val = os.environ.get(f"TORRDOWN_{key.upper()}")
+            if env_val:
+                merged[key] = _coerce(key, env_val)
+        merged.update(self._overrides)
+
+        # Lazy path defaults, applied only if still unset after all layers.
+        if not merged.get("download_dir"):
+            merged["download_dir"] = str(Path.home() / "Downloads" / "torrdown")
+        if not merged.get("torrents_dir"):
+            # Dedicated subfolder for source .torrent files, kept separate from
+            # downloaded content so the interactive menu / `list` stays clean.
+            merged["torrents_dir"] = str(Path(merged["download_dir"]) / "torrents")
+        merged["download_dir"] = str(Path(merged["download_dir"]).expanduser())
+        merged["torrents_dir"] = str(Path(merged["torrents_dir"]).expanduser())
+
+        self._resolved = merged
+        return merged
+
+    def __getattr__(self, name):
+        # Expose resolved settings (download_dir, port, ...) as attributes.
+        if name in DEFAULTS:
+            return self.resolve()[name]
+        raise AttributeError(name)
+
+    def as_dict(self):
+        return dict(self.resolve())

torrdown/engine.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+"""Drives a single shared libtorrent session for all concurrent downloads,
+replacing torrentp's one-session-per-torrent design. Metadata resolution and
+per-torrent status are event/poll-driven from the main thread only - no
+threads, no per-torrent ports.
+
+Note: libtorrent's session.get_torrent_status(predicate) is NOT used here -
+it invokes the Python predicate from a libtorrent-internal worker thread,
+which segfaults when that callback allocates a Python object outside the
+GIL (confirmed via a real crash report: the fault is in
+get_torrent_status -> wrap_pred -> PyType_GenericAlloc). Per-handle
+`handle.status()` calls from this thread are the safe equivalent for the
+small number of torrents this tool handles at once.
+"""
+import time
+import libtorrent as lt
+from dataclasses import dataclass
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TaskProgressColumn,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+
+from .state import StateStore
+
+ALERT_MASK = (lt.alert.category_t.status_notification
+              | lt.alert.category_t.error_notification)
+
+
+@dataclass
+class ActiveTorrent:
+    handle: object
+    label: str
+    source: str
+    info_hash: str
+    added_at: float
+    task_id: object = None
+    metadata_seen: bool = False
+    heartbeat_printed: bool = False
+
+
+def _build_params(source, save_path):
+    if source.startswith("magnet:"):
+        params = lt.parse_magnet_uri(source)
+    else:
+        params = lt.add_torrent_params()
+        params.ti = lt.torrent_info(source)
+    params.save_path = save_path
+    return params
+
+
+def info_hash_of(source):
+    if source.startswith("magnet:"):
+        return str(lt.parse_magnet_uri(source).info_hashes.v1)
+    return str(lt.torrent_info(source).info_hash())
+
+
+class TorrentEngine:
+    def __init__(self, target_dir, state_store, port=6881, max_concurrent=3,
+                 metadata_timeout=180, checkpoint_interval=30, heartbeat_delay=15,
+                 on_result=None):
+        self._target_dir = target_dir
+        self._state = state_store
+        self._metadata_timeout = metadata_timeout
+        self._checkpoint_interval = checkpoint_interval
+        self._heartbeat_delay = heartbeat_delay
+        self._max_concurrent_metadata = max_concurrent
+        self._on_result = on_result
+        self._session = lt.session({
+            "listen_interfaces": f"0.0.0.0:{port}",
+            "alert_mask": ALERT_MASK,
+            "enable_dht": True,
+            # Once metadata is known, libtorrent shares bandwidth across
+            # active downloads well on its own - this only needs to be
+            # generous enough not to become a second bottleneck. The real
+            # concurrency limit is applied at the pre-metadata queueing
+            # stage below, since that's where torrents actually starve each
+            # other of peer connections (confirmed empirically: torrents
+            # added simultaneously can sit at 0 peers for 30s+ even when
+            # nominally "active", regardless of queue position).
+            "active_downloads": max(20, max_concurrent * 4),
+        })
+        self._active = {}          # info_hash -> ActiveTorrent
+        self._pending = []         # list of (source, label) not yet added to session
+        self._source_by_hash = {}  # info_hash -> source, kept past completion
+        self._results = {}         # info_hash -> (status, reason)
+        self._shutdown_requested = False
+        self._last_checkpoint = time.monotonic()
+
+    def request_shutdown(self):
+        self._shutdown_requested = True
+
+    def has_work(self):
+        """True if any torrent is active or queued - lets callers skip the
+        run loop when there's nothing to do."""
+        return bool(self._active or self._pending)
+
+    def _pending_metadata_count(self):
+        return sum(1 for a in self._active.values() if not a.metadata_seen)
+
+    def add_source(self, source, label):
+        info_hash = info_hash_of(source)
+        if info_hash in self._active or any(s == source for s, _ in self._pending):
+            print(f"Skipping duplicate - {label} (already active or queued)")
+            return None
+        # Only let up to max_concurrent torrents compete for metadata/peer
+        # connections at once - anything beyond that waits in self._pending
+        # until a slot frees up, so its metadata-timeout clock doesn't start
+        # ticking until it's actually had a real chance.
+        if self._pending_metadata_count() >= self._max_concurrent_metadata:
+            self._pending.append((source, label))
+            print(f"Queued - {label} (waiting for a metadata slot)")
+            return None
+        return self._add_now(source, label)
+
+    def _add_now(self, source, label, resume_b64=None):
+        info_hash = info_hash_of(source)
+        try:
+            if resume_b64:
+                params = lt.read_resume_data(StateStore.decode_resume_data(resume_b64))
+            else:
+                params = _build_params(source, self._target_dir)
+            handle = self._session.add_torrent(params)
+        except Exception as exc:
+            print(f"Failed to add {label}: {exc}")
+            self._record_result(info_hash, source, "failed", str(exc))
+            return None
+        # .torrent files and resume-data blobs both carry full metadata
+        # already - only a bare magnet with no resume data needs to actually
+        # wait for metadata_received_alert.
+        active = ActiveTorrent(handle=handle, label=label, source=source,
+                                info_hash=info_hash, added_at=time.monotonic(),
+                                metadata_seen=bool(resume_b64) or not source.startswith("magnet:"))
+        self._active[info_hash] = active
+        self._source_by_hash[info_hash] = source
+        self._state.upsert(info_hash, source=source, label=label,
+                            save_path=self._target_dir, status="active",
+                            resume_data=resume_b64, error=None)
+        return active
+
+    def _promote_pending(self):
+        while self._pending and self._pending_metadata_count() < self._max_concurrent_metadata:
+            source, label = self._pending.pop(0)
+            self._add_now(source, label)
+
+    def _record_result(self, info_hash, source, status, reason):
+        """Persists a terminal outcome immediately - to state.json right
+        away, and via on_result (for magnets.txt archiving) if provided -
+        rather than waiting for the whole batch to finish."""
+        self._results[info_hash] = (status, reason)
+        self._source_by_hash[info_hash] = source
+        state_status = "skipped_timeout" if reason == "metadata timeout" else status
+        self._state.upsert(info_hash, status=state_status, error=reason)
+        self._state.save()
+        if self._on_result:
+            self._on_result(source, status, reason)
+
+    def resume_from_state(self):
+        for info_hash, record in self._state.active_records().items():
+            source = record.get("source")
+            label = record.get("label", info_hash[:8])
+            resume_b64 = record.get("resume_data")
+            # Resume data (or a non-magnet source) already carries metadata,
+            # so it can skip straight in regardless of the metadata-slot
+            # gate. A bare magnet with no resume data yet still needs to
+            # fetch metadata, so it competes for a slot exactly like a fresh
+            # request - otherwise resumed torrents could reintroduce the
+            # same starvation the gate exists to prevent.
+            if resume_b64 or not source.startswith("magnet:"):
+                active = self._add_now(source, label, resume_b64=resume_b64)
+            elif self._pending_metadata_count() >= self._max_concurrent_metadata:
+                self._pending.append((source, label))
+                print(f"Queued (resumed) - {label} (waiting for a metadata slot)")
+                continue
+            else:
+                active = self._add_now(source, label)
+            if active:
+                print(f"Resumed - {label}")
+
+    def get_results_by_source(self):
+        return {
+            self._source_by_hash[h]: outcome
+            for h, outcome in self._results.items()
+            if h in self._source_by_hash
+        }
+
+    def run(self):
+        progress = Progress(
+            TextColumn("[bold blue]{task.description}", justify="right"),
+            BarColumn(),
+            TaskProgressColumn(),
+            DownloadColumn(),
+            TransferSpeedColumn(),
+            TimeRemainingColumn(compact=True, elapsed_when_finished=True),
+        )
+        with progress:
+            while (self._active or self._pending) and not self._shutdown_requested:
+                self._session.wait_for_alert(500)
+                for alert in self._session.pop_alerts():
+                    self._handle_alert(alert, progress)
+                self._check_deadlines()
+                self._update_progress(progress)
+                self._promote_pending()
+                self._maybe_checkpoint()
+
+            if self._shutdown_requested:
+                self._graceful_shutdown()
+
+        self._state.save()
+
+    def _handle_alert(self, alert, progress):
+        handle = getattr(alert, "handle", None)
+        if handle is None:
+            return
+        info_hash = str(handle.info_hash())
+        active = self._active.get(info_hash)
+        if isinstance(alert, lt.metadata_received_alert):
+            if active:
+                active.metadata_seen = True
+        elif isinstance(alert, lt.torrent_finished_alert):
+            if active:
+                self._finish(info_hash, "done", None, progress)
+        elif isinstance(alert, lt.torrent_error_alert):
+            if active:
+                try:
+                    reason = alert.error.message() if alert.error else alert.message()
+                except Exception:
+                    reason = alert.message()
+                self._finish(info_hash, "failed", reason, progress)
+        elif isinstance(alert, lt.save_resume_data_alert):
+            resume_bytes = lt.write_resume_data_buf(alert.params)
+            self._state.upsert(info_hash, resume_data=StateStore.encode_resume_data(resume_bytes))
+        elif isinstance(alert, lt.save_resume_data_failed_alert):
+            pass  # best-effort; not fatal
+
+    def _finish(self, info_hash, status, reason, progress):
+        active = self._active.pop(info_hash, None)
+        if active is None:
+            return
+        if active.task_id is not None:
+            try:
+                st = active.handle.status()
+                progress.update(active.task_id, completed=st.total_wanted, total=st.total_wanted)
+            except Exception:
+                pass
+        if status == "done":
+            print(f"Completed - {active.label}")
+        else:
+            print(f"Failed - {active.label}: {reason}")
+        self._record_result(info_hash, active.source, status, reason)
+        try:
+            self._session.remove_torrent(active.handle)
+        except Exception:
+            pass
+
+    def _check_deadlines(self):
+        now = time.monotonic()
+        for info_hash, active in list(self._active.items()):
+            if active.metadata_seen:
+                continue
+            elapsed = now - active.added_at
+            if elapsed > self._metadata_timeout:
+                print(f"Timed out - {active.label} (no metadata after {self._metadata_timeout}s)")
+                self._active.pop(info_hash, None)
+                self._record_result(info_hash, active.source, "failed", "metadata timeout")
+                try:
+                    self._session.remove_torrent(active.handle)
+                except Exception:
+                    pass
+            elif elapsed > self._heartbeat_delay and not active.heartbeat_printed:
+                active.heartbeat_printed = True
+                print(f"  ...still working on {active.label} - normal while "
+                      f"resolving magnet metadata or waiting on peers")
+
+    def _update_progress(self, progress):
+        for info_hash, active in list(self._active.items()):
+            if not active.metadata_seen:
+                continue
+            if active.task_id is None:
+                st = active.handle.status()
+                active.task_id = progress.add_task(st.name, total=st.total_wanted)
+            st = active.handle.status()
+            progress.update(active.task_id, completed=st.total_done, total=st.total_wanted)
+            # Record progress into the in-memory state record so `torrdown
+            # status` can show how far along things are. Persisted on the
+            # existing checkpoint cadence - no extra disk writes here.
+            self._state.upsert(
+                info_hash,
+                progress=(st.total_done / st.total_wanted) if st.total_wanted else 0.0,
+                total_bytes=st.total_wanted,
+            )
+            if st.is_seeding:
+                # Covers torrents already fully-downloaded at add time, which
+                # never fire torrent_finished_alert since no transition occurs.
+                self._finish(info_hash, "done", None, progress)
+
+    def _maybe_checkpoint(self):
+        now = time.monotonic()
+        if now - self._last_checkpoint < self._checkpoint_interval:
+            return
+        self._last_checkpoint = now
+        for active in self._active.values():
+            if active.handle.need_save_resume_data():
+                active.handle.save_resume_data()
+        self._state.save()
+
+    def _graceful_shutdown(self):
+        print("Shutting down - saving progress...")
+        self._session.pause()
+        pending = set()
+        for active in self._active.values():
+            if active.handle.need_save_resume_data():
+                active.handle.save_resume_data()
+                pending.add(active.info_hash)
+        deadline = time.monotonic() + 10
+        while pending and time.monotonic() < deadline:
+            self._session.wait_for_alert(200)
+            for alert in self._session.pop_alerts():
+                if isinstance(alert, (lt.save_resume_data_alert, lt.save_resume_data_failed_alert)):
+                    handle = getattr(alert, "handle", None)
+                    if handle is None:
+                        continue
+                    ih = str(handle.info_hash())
+                    if isinstance(alert, lt.save_resume_data_alert):
+                        resume_bytes = lt.write_resume_data_buf(alert.params)
+                        self._state.upsert(ih, resume_data=StateStore.encode_resume_data(resume_bytes))
+                    pending.discard(ih)
+
+    def close(self):
+        del self._session

torrdown/magnets.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Reads magnet links from a file and archives completed/failed ones in
+place (commented out with the outcome and date) so re-running the tool
+doesn't redownload the same list. No auto-retry - a dead/zero-seed magnet
+shouldn't loop forever; uncomment the line manually to retry it."""
+import os
+import time
+
+
+def read_magnets_file(path):
+    if not os.path.exists(path):
+        return []
+    with open(path) as f:
+        return [
+            line.strip() for line in f
+            if line.strip() and not line.strip().startswith("#")
+        ]
+
+
+def archive_results(path, results):
+    """results: dict of {original magnet line: (status, reason)}, where
+    status is "done" or "failed" (skipped-on-timeout counts as failed).
+    Lines with no entry in results (still active, or not a tracked magnet)
+    are left untouched."""
+    if not results or not os.path.exists(path):
+        return
+
+    date = time.strftime("%Y-%m-%d")
+    with open(path) as f:
+        lines = f.readlines()
+
+    new_lines = []
+    for line in lines:
+        stripped = line.strip()
+        outcome = results.get(stripped)
+        if outcome is None:
+            new_lines.append(line)
+            continue
+        status, reason = outcome
+        if status == "done":
+            new_lines.append(f"# [done {date}] {stripped}\n")
+        else:
+            new_lines.append(f"# [failed {date}: {reason}] {stripped}\n")
+
+    with open(path, "w") as f:
+        f.writelines(new_lines)

torrdown/sources.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Turns user-provided tokens into concrete download sources.
+
+A "source" is either a magnet URI or a path to a local .torrent file - the two
+things engine.TorrentEngine.add_source knows how to consume. This module is the
+single place that decides what a token means, so the CLI, interactive mode, and
+(future) fetch adapters all resolve inputs the same way.
+
+Future extension point: a fetch adapter (e.g. Internet Archive search) would
+resolve a `search:<query>` token here into one or more magnet sources, without
+the engine or CLI needing to change. See ROADMAP.md."""
+import os
+
+
+class SourceError(ValueError):
+    """Raised when a token can't be resolved to a usable source."""
+
+
+def list_torrent_files(torrents_dir):
+    """Local .torrent files available for index selection, sorted for stable
+    numbering."""
+    if not os.path.isdir(torrents_dir):
+        return []
+    return sorted(f for f in os.listdir(torrents_dir) if f.endswith(".torrent"))
+
+
+def resolve_token(token, torrents_dir):
+    """Resolve a single token to a list of (source, label) tuples.
+
+    - magnet:?...            -> that magnet
+    - path to a .torrent     -> that file
+    - bare integer "N"       -> the Nth local .torrent file (1-based)
+    """
+    token = token.strip()
+    if not token:
+        return []
+
+    if token.startswith("magnet:?"):
+        return [(token, _magnet_label(token))]
+
+    if token.endswith(".torrent"):
+        path = os.path.expanduser(token)
+        if not os.path.isfile(path):
+            raise SourceError(f"No such .torrent file: {token}")
+        return [(path, os.path.basename(path))]
+
+    if token.isdigit():
+        torrents = list_torrent_files(torrents_dir)
+        idx = int(token)
+        if 1 <= idx <= len(torrents):
+            name = torrents[idx - 1]
+            return [(os.path.join(torrents_dir, name), name)]
+        raise SourceError(f"Invalid index: {idx} (have {len(torrents)} file(s))")
+
+    raise SourceError(
+        f"Unrecognized source: {token!r} "
+        "(expected a magnet link, a .torrent path, or a file index)"
+    )
+
+
+def resolve_many(tokens, torrents_dir):
+    """Resolve several tokens, collecting per-token errors instead of aborting
+    the whole batch. Returns (sources, errors)."""
+    sources, errors = [], []
+    for token in tokens:
+        try:
+            sources.extend(resolve_token(token, torrents_dir))
+        except SourceError as exc:
+            errors.append(str(exc))
+    return sources, errors
+
+
+def _magnet_label(magnet):
+    """Human-friendly label from a magnet's dn= field, if present."""
+    marker = "&dn="
+    if marker in magnet:
+        from urllib.parse import unquote
+        raw = magnet.split(marker, 1)[1].split("&", 1)[0]
+        return unquote(raw)
+    return "magnet"

torrdown/state.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Persists torrent download state to a JSON file, keyed by info-hash, so
+downloads can resume after Ctrl+C, a crash, or a restart instead of
+starting over."""
+import os
+import json
+import time
+import base64
+
+# Statuses that mean a torrent is finished with (in some way) and safe to clear.
+TERMINAL_STATUSES = frozenset({"done", "failed", "skipped_timeout"})
+
+
+class StateStore:
+    def __init__(self, path):
+        self._path = path
+        self._records = {}
+
+    def load(self):
+        if not os.path.exists(self._path):
+            self._records = {}
+            return self._records
+        try:
+            with open(self._path) as f:
+                self._records = json.load(f)
+        except (json.JSONDecodeError, OSError, UnicodeDecodeError) as exc:
+            bad_path = f"{self._path}.bad-{int(time.time())}"
+            try:
+                os.replace(self._path, bad_path)
+                print(f"Warning: {self._path} was corrupt ({exc}); moved "
+                      f"aside to {bad_path} and starting fresh.")
+            except OSError:
+                print(f"Warning: {self._path} was corrupt ({exc}); starting fresh.")
+            self._records = {}
+        return self._records
+
+    def save(self):
+        tmp_path = f"{self._path}.tmp"
+        with open(tmp_path, "w") as f:
+            json.dump(self._records, f, indent=2)
+        os.replace(tmp_path, self._path)
+
+    def upsert(self, info_hash, **fields):
+        record = self._records.setdefault(info_hash, {})
+        record.update(fields)
+        record["updated_at"] = time.strftime("%Y-%m-%d %H:%M:%S")
+        return record
+
+    def get(self, info_hash):
+        return self._records.get(info_hash)
+
+    def all_records(self):
+        return dict(self._records)
+
+    def active_records(self):
+        return {h: r for h, r in self._records.items() if r.get("status") == "active"}
+
+    def remove(self, info_hash):
+        self._records.pop(info_hash, None)
+
+    def find(self, token):
+        """Match records by exact label first, then by info-hash prefix.
+        Returns a list of matching info-hashes (empty if none)."""
+        token = token.strip()
+        exact = [h for h, r in self._records.items() if r.get("label") == token]
+        if exact:
+            return exact
+        low = token.lower()
+        return [h for h in self._records if h.lower().startswith(low)]
+
+    def clear(self, only_terminal=True):
+        """Drop tracking records. By default only completed/failed/timed-out
+        ones; with only_terminal=False, everything. Returns the count removed.
+        Never touches files on disk - this only edits the state records."""
+        if only_terminal:
+            targets = [h for h, r in self._records.items()
+                       if r.get("status") in TERMINAL_STATUSES]
+        else:
+            targets = list(self._records)
+        for h in targets:
+            del self._records[h]
+        return len(targets)
+
+    @staticmethod
+    def encode_resume_data(resume_bytes):
+        return base64.b64encode(resume_bytes).decode("ascii")
+
+    @staticmethod
+    def decode_resume_data(encoded):
+        return base64.b64decode(encoded.encode("ascii"))

torrdown-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: torrdown
+Version: 0.1.0
+Summary: A single-session libtorrent download CLI with resume, dedup, and batch support.
+Author: aryannxroot
+License: MIT
+License-File: LICENSE
+Keywords: bittorrent,cli,downloader,libtorrent,torrent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: Internet
+Requires-Python: <3.14,>=3.9
+Requires-Dist: libtorrent<2.1,>=2.0
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TorrDown
+
+A command-line torrent downloader built on a single shared `libtorrent` session.
+It downloads several torrents at once, survives restarts, and installs as a real
+`torrdown` command you can run from anywhere.
+
+TorrDown started as a Google Colab notebook (still in the repo as
+`legacy_download_gcollab.ipynb`) and grew into a proper, installable CLI.
+
+## Features
+
+- **Single shared libtorrent session** — all torrents run in one session (the way
+  libtorrent is meant to be used), not one session per torrent.
+- **Concurrent downloads** with a fairness gate — only a bounded number compete
+  for metadata/peers at once; the rest queue, so a stuck magnet can't starve the
+  others or unfairly burn its own timeout.
+- **Magnet links and `.torrent` files**, individually or in batches.
+- **Automatic resume** — Ctrl+C, a crash, or a reboot doesn't lose progress;
+  downloads pick up where they left off on the next run (libtorrent resume data
+  is checkpointed to disk).
+- **Info-hash dedup** — the same torrent won't be added twice.
+- **Metadata-fetch timeout** — a magnet with no metadata-holding peers is skipped
+  after a while instead of hanging forever.
+- **Batch mode** — download every magnet in a file; completed/failed entries are
+  commented out in place so re-runs don't repeat them.
+- **Graceful shutdown** — Ctrl+C saves state cleanly before exiting.
+- **Live progress bars** (via `rich`) for every active download.
+- **Per-user config** with sensible defaults and clear override precedence.
+
+## Requirements
+
+- **macOS or Linux.** (Windows isn't supported yet.)
+- **Python 3.9-3.13** somewhere on the machine. `libtorrent` publishes binary
+  wheels only for these versions, so TorrDown caps at `<3.14`. The installer
+  finds a compatible interpreter automatically; if you only have 3.14+, it tells
+  you how to get a supported one.
+
+## Install
+
+The easiest way, on a machine with Python 3.9-3.13:
+
+```bash
+pipx install torrdown        # isolated, puts `torrdown` on your PATH
+# or
+pip install torrdown
+```
+
+That's it — `torrdown` is now a command you can run from anywhere.
+
+### From source
+
+The source repo is currently private. If you have access, you can clone it and
+use the bundled installer (creates an isolated venv and symlinks the command):
+
+```bash
+git clone https://github.com/aryannxroot/TorrDown.git
+cd TorrDown
+./install.sh                 # then ./update.sh / ./uninstall.sh to manage it
+```
+
+For development:
+
+```bash
+python3.13 -m venv torr
+source torr/bin/activate
+pip install -e ".[dev]"      # editable install + test deps
+pytest                       # run the test suite
+```
+
+You can also run it without installing via `python -m torrdown`.
+
+## Usage
+
+```bash
+torrdown                       # interactive menu (list files / paste magnet / batch)
+torrdown add "magnet:?xt=..."  # add a magnet (quote it - the & chars matter)
+torrdown add movie.torrent     # add a local .torrent file
+torrdown add 1,3               # add local .torrent files by menu index
+torrdown batch                 # download every magnet in the configured magnets.txt
+torrdown batch links.txt       # ...or from a specific file
+torrdown resume                # resume downloads interrupted by a crash/Ctrl+C
+torrdown status                # show tracked torrents with progress (ID, %, size)
+torrdown remove <id>           # drop a tracked entry by ID (from status) or label
+torrdown clear                 # clear completed/failed entries (--all clears everything)
+torrdown list                  # list local .torrent files
+torrdown init                  # create the config/download/torrents directories
+torrdown config                # show resolved config and file locations
+```
+
+`status` shows how far each download got; `remove`/`clear` only edit the tracking
+records — your downloaded files are never touched. For live speed on an active
+download, use `torrdown resume` (it shows the running progress bars).
+
+Downloads and interrupted work resume automatically on the next run.
+
+## Configuration
+
+Defaults (all overridable):
+
+| Setting | Default |
+|---|---|
+| Download directory | `~/Downloads/torrdown` |
+| Torrents directory (`.torrent` files for the menu / `list`) | `~/Downloads/torrdown/torrents` |
+| Config / state directory | `~/.config/torrdown` (`%APPDATA%\torrdown` on Windows) |
+| Listen port | 6881 |
+| Max concurrent (metadata slots) | 3 |
+| Metadata fetch timeout | 180s |
+
+Drop `.torrent` files into the torrents directory to have them show up in the
+interactive menu and `torrdown list`. Magnet links don't need any folder — just
+`torrdown add "magnet:?..."`.
+
+Precedence, highest first: **CLI flags** (`--download-dir`, `--config-dir`) >
+**environment** (`TORRDOWN_DOWNLOAD_DIR`, `TORRDOWN_PORT`, ...) >
+**`config.json`** (in the config dir) > **built-in defaults**.
+
+Run `torrdown config` to see the resolved values and where the files live.
+
+## How it works
+
+- **`engine.py`** owns one `libtorrent` session and runs a single alert-driven
+  loop on the main thread: it adds torrents, watches libtorrent alerts
+  (metadata received, finished, error, resume-data saved), and polls each
+  torrent's status for the progress bars. Per-torrent status is read one handle
+  at a time on purpose — libtorrent's batched `get_torrent_status()` invokes a
+  Python callback from an internal worker thread and segfaults in this build.
+- **`state.py`** persists a small `state.json` keyed by info-hash, including
+  base64-encoded libtorrent resume data, so interrupted torrents resume without
+  re-fetching metadata or re-hashing completed pieces. Writes are atomic and a
+  corrupt file is set aside rather than silently wiped.
+- **`sources.py`** turns a user token (a magnet, a `.torrent` path, or a menu
+  index) into a concrete download source. This is the single seam where future
+  fetch adapters (e.g. searching a legitimate index) will plug in.
+- **`config.py`** resolves paths and tunables across the precedence layers above.
+- **`cli.py`** is the argparse front end (the subcommands above) plus the
+  interactive menu when run bare.
+
+## Project layout
+
+```
+torrdown/            the package
+  cli.py             argparse subcommands + interactive menu
+  config.py          path + settings resolution
+  sources.py         token -> download source (future fetch seam)
+  engine.py          the shared-session libtorrent engine
+  state.py           resume-state persistence
+  magnets.py         batch magnets file read + archive
+tests/               pure-logic pytest suite
+install.sh           installer (macOS + Linux)
+uninstall.sh         uninstaller
+update.sh            updater
+pyproject.toml       packaging + dependencies
+PLAN.md              what we're building
+PROGRESS.md          living status tracker
+ROADMAP.md           deferred work (auto-fetch, PyPI, perf notes)
+```
+
+## Notes & limitations
+
+- **Speed** is bounded by your internet connection and the swarm, not by
+  TorrDown — see [ROADMAP.md](ROADMAP.md) for the full performance discussion.
+- **Automated fetching** of torrents from external sources isn't built yet;
+  when it is, it will target only legitimate sources (Internet Archive, Linux
+  distros, Creative Commons). See [ROADMAP.md](ROADMAP.md).
+- **Windows** is not supported yet.

torrdown-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+torrdown/__init__.py,sha256=TqPymXrxElpB0BizEGFnqXg3dZOniu4thfa-0n1z6bs,82
+torrdown/__main__.py,sha256=d7Zm05MGZ8Rj9t5Vqo2kj4bzD4Dh9ZkZ2ClFjit90yQ,97
+torrdown/cli.py,sha256=7u0tMpdofilMGa02nIKB3XH_uxtBR6KDduehM6QZcqE,10911
+torrdown/config.py,sha256=6gpbtVn3IaCYyNwWgQ23P2sgyCCzEVgLfUKjxxwC3Ow,5497
+torrdown/engine.py,sha256=xkX0BEA7ZE30g-fOIepUzDaHn2X02x4MuJQ6fdevLis,14704
+torrdown/magnets.py,sha256=ZVTBbKapc7Dyq8k9Va3gZC68owFLfApv6HRzX2w2ekU,1485
+torrdown/sources.py,sha256=SUijk42KISW4W7lot7fvMdllzKpuEIsljTEh_DyTzhE,2782
+torrdown/state.py,sha256=qWbun1_Km5l5myv-8IV-Qzt4lKeibCIMdL-SKWQzAZQ,3193
+torrdown-0.1.0.dist-info/METADATA,sha256=8rRREGznzw2Jjx9gCOO2tCmPbRnjfQqMKN2B7nnXPpY,8354
+torrdown-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+torrdown-0.1.0.dist-info/entry_points.txt,sha256=IMAZe368bsWXfmExb5vgho53LL5ad5VUHJ3EksDXx7Q,47
+torrdown-0.1.0.dist-info/licenses/LICENSE,sha256=iJ_F87E3mFyw2PomWSmIjWhAympMG-7NLpf5DEoKhfI,1068
+torrdown-0.1.0.dist-info/RECORD,,

torrdown-0.1.0.dist-info/WHEEL

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

torrdown-0.1.0.dist-info/entry_points.txt

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

torrdown-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aryannxroot
+
+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.