torrdown 0.1.0__tar.gz

torrdown-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+Movies/
+Torrents/
+torr/
+.venv/
+magnets.txt
+state.json
+__pycache__/
+*.pyc
+.DS_Store
+
+# build artifacts
+build/
+dist/
+*.egg-info/
+.pytest_cache/

torrdown-0.1.0/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.

torrdown-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,165 @@
+# 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/ROADMAP.md

@@ -0,0 +1,79 @@
+# Roadmap / deferred work
+
+Things intentionally left for later, with the reasoning, so picking them up
+doesn't mean re-deriving the context. Current status lives in
+[PROGRESS.md](PROGRESS.md); the CLI plan is in [PLAN.md](PLAN.md).
+
+## Deferred: auto-fetch torrents from external sources
+
+Today sources are supplied manually (magnet link, `.torrent` file, or file
+index). The next big feature is a `search` subcommand that fetches magnets from
+**legitimate** sources and hands them to the existing engine.
+
+- **Where it plugs in**: `torrdown/sources.py` already centralizes "token →
+  `[(source, label)]`" resolution. A fetch adapter resolves a `search:<query>`
+  token (or a dedicated `torrdown search` subcommand) into magnet sources - no
+  change to `engine.py` or the download path is needed.
+- **Sources to target** (legal/legitimately-distributable only):
+  - **Internet Archive** (archive.org) - the standout: millions of public-domain
+    and openly-licensed items, every item exposes a torrent, and it has a real
+    documented search API. Best fit for a clean search→download flow.
+  - **Linux distribution torrents** - Ubuntu/Debian/Fedora/Arch official ISOs;
+    stable URLs, no unified API.
+  - **Creative Commons / open media** - Blender open movies, Librivox, Wikimedia.
+- **Explicitly out of scope**: general piracy index sites (1337x, YTS, TPB, RARBG
+  successors, etc.). This tool will not integrate scraping/searching those.
+- **Why deferred**: it's a substantially larger task (HTTP clients, per-source
+  adapters, result ranking/selection UX) and was split off deliberately to ship
+  the CLI first without losing momentum.
+
+## Done: publish to PyPI (pipx install)
+
+Published to PyPI, so `pipx install torrdown` / `pip install torrdown` works for
+anyone without the repo being public. Remaining optional follow-ups:
+- Make the repo public and add `[project.urls]` (Homepage/Repository/Issues) so the
+  PyPI page links back to real source (currently omitted — the repo is private).
+- Automate releases via a GitHub Actions workflow (build + `twine upload` on tag).
+- Revisit Windows support.
+
+## Deferred: broader hardening
+
+- Richer `status` output (live dashboard rather than a snapshot table).
+- Full engine/network **integration tests** (the current suite covers pure logic
+  only; end-to-end download tests need real torrents/network).
+- Rotating-file **logging** for diagnostics, alongside the current console UX.
+
+## Performance tuning (revisit only if evidence changes)
+
+From an earlier investigation into why downloads cap around ~4 MB/s.
+
+**Diagnosis**: measured home connection was **35.75 Mbps down / 36.62 Mbps up**
+(≈4.47 MB/s ceiling); ~4 MB/s is ~89% of that - i.e. already near the physical
+line limit, not a code/settings problem. The old Google Colab notebook's
+10-40 MB/s came from the swarm transfer happening on Google Cloud's network (to a
+Colab VM / Google Drive), which never touched the home connection - so that number
+reflects Google's bandwidth, not this client or connection.
+
+**Settings checked (libtorrent 2.0.13, live introspection) - no hidden slack**:
+rate limits already unlimited; `enable_upnp`/`enable_natpmp`/`enable_lsd` already
+on; TCP and uTP both enabled; `connections_limit` 200 (generous for personal use).
+
+**Candidate tweaks, not applied - each with its trade-off**:
+
+1. **Raise `connections_limit`** (200 → ~400): free, harmless, but unlikely to
+   matter - a single well-seeded torrent rarely has 200+ usable peers anyway.
+2. **Force encryption** (`out_enc_policy`/`in_enc_policy`: `pe_enabled` →
+   `pe_forced`, `allowed_enc_level` → `pe_rc4`): some ISPs throttle recognizable
+   plaintext BitTorrent handshakes via DPI; forcing encrypted-only can sometimes
+   evade that. **Cost**: rejects peers that don't support obfuscation, shrinking
+   the usable pool. Not justified now (already ~89% of line speed = no clear
+   throttling). Also note this is legacy RC4 traffic-obfuscation, not real
+   security.
+3. **`mixed_mode_algorithm` → `prefer_tcp`**: *not recommended* - lets torrenting
+   monopolize the connection at the expense of other traffic (calls, browsing),
+   for a gain unlikely to matter since the bottleneck is total bandwidth.
+
+**When to revisit**: the internet plan/ISP changes or the line gets materially
+faster; or torrent speeds start showing up *consistently well below* a fresh
+speedtest number (that pattern - not the current one - indicates real throttling
+worth evading via forced encryption).

torrdown-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "torrdown"
+dynamic = ["version"]
+description = "A single-session libtorrent download CLI with resume, dedup, and batch support."
+readme = "README.md"
+requires-python = ">=3.9,<3.14"
+license = { text = "MIT" }
+authors = [{ name = "aryannxroot" }]
+keywords = ["torrent", "bittorrent", "libtorrent", "cli", "downloader"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet",
+    "Topic :: Communications :: File Sharing",
+]
+dependencies = [
+    # libtorrent ships binary wheels only for CPython 3.9-3.13, which is why
+    # requires-python caps at <3.14 (there is no 3.14 wheel).
+    "libtorrent>=2.0,<2.1",
+    "rich>=13",
+]
+
+[project.scripts]
+torrdown = "torrdown.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.version]
+path = "torrdown/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["torrdown"]
+
+[tool.hatch.build.targets.sdist]
+# Keep the source distribution to just what belongs in a release - not the
+# legacy Colab notebook or any local working files.
+include = [
+    "torrdown",
+    "tests",
+    "README.md",
+    "ROADMAP.md",
+    "LICENSE",
+    "pyproject.toml",
+]

torrdown-0.1.0/tests/test_config.py

@@ -0,0 +1,57 @@
+import json
+from pathlib import Path
+
+from torrdown.config import Config
+
+
+def test_defaults_when_no_file(tmp_path):
+    cfg = Config(config_dir=tmp_path)
+    d = cfg.as_dict()
+    assert d["port"] == 6881
+    assert d["max_concurrent"] == 3
+    assert d["download_dir"].endswith("Downloads/torrdown") or "torrdown" in d["download_dir"]
+    # torrents_dir defaults to a dedicated subfolder of download_dir
+    assert d["torrents_dir"] == str(Path(d["download_dir"]) / "torrents")
+
+
+def test_config_file_overrides_defaults(tmp_path):
+    (tmp_path / "config.json").write_text(json.dumps({"port": 7000, "max_concurrent": 9}))
+    cfg = Config(config_dir=tmp_path)
+    d = cfg.as_dict()
+    assert d["port"] == 7000
+    assert d["max_concurrent"] == 9
+
+
+def test_env_overrides_file(tmp_path, monkeypatch):
+    (tmp_path / "config.json").write_text(json.dumps({"port": 7000}))
+    monkeypatch.setenv("TORRDOWN_PORT", "8123")
+    cfg = Config(config_dir=tmp_path)
+    assert cfg.as_dict()["port"] == 8123
+
+
+def test_cli_override_beats_env_and_file(tmp_path, monkeypatch):
+    (tmp_path / "config.json").write_text(json.dumps({"download_dir": "/from/file"}))
+    monkeypatch.setenv("TORRDOWN_DOWNLOAD_DIR", "/from/env")
+    cfg = Config(config_dir=tmp_path, overrides={"download_dir": "/from/cli"})
+    assert cfg.as_dict()["download_dir"] == "/from/cli"
+
+
+def test_none_override_is_ignored(tmp_path):
+    # argparse passes None for unspecified flags - must not clobber lower layers.
+    (tmp_path / "config.json").write_text(json.dumps({"port": 7001}))
+    cfg = Config(config_dir=tmp_path, overrides={"download_dir": None})
+    assert cfg.as_dict()["port"] == 7001
+
+
+def test_corrupt_config_falls_back_to_defaults(tmp_path, capsys):
+    (tmp_path / "config.json").write_text("{ not json !!!")
+    cfg = Config(config_dir=tmp_path)
+    assert cfg.as_dict()["port"] == 6881  # default, no crash
+
+
+def test_ensure_config_dir_writes_default(tmp_path):
+    cfg = Config(config_dir=tmp_path / "new")
+    cfg.ensure_config_dir()
+    assert cfg.config_file.exists()
+    data = json.loads(cfg.config_file.read_text())
+    assert "download_dir" in data

torrdown-0.1.0/tests/test_magnets.py

@@ -0,0 +1,48 @@
+from torrdown.magnets import read_magnets_file, archive_results
+
+
+def test_read_skips_comments_and_blanks(tmp_path):
+    f = tmp_path / "magnets.txt"
+    f.write_text(
+        "# a comment\n"
+        "\n"
+        "magnet:?xt=urn:btih:AAA&dn=one\n"
+        "   \n"
+        "magnet:?xt=urn:btih:BBB&dn=two\n"
+    )
+    assert read_magnets_file(str(f)) == [
+        "magnet:?xt=urn:btih:AAA&dn=one",
+        "magnet:?xt=urn:btih:BBB&dn=two",
+    ]
+
+
+def test_read_missing_file_returns_empty(tmp_path):
+    assert read_magnets_file(str(tmp_path / "nope.txt")) == []
+
+
+def test_archive_comments_done_and_failed_leaves_others(tmp_path):
+    f = tmp_path / "magnets.txt"
+    one = "magnet:?xt=urn:btih:AAA&dn=one"
+    two = "magnet:?xt=urn:btih:BBB&dn=two"
+    three = "magnet:?xt=urn:btih:CCC&dn=three"
+    f.write_text(f"# keep me\n{one}\n{two}\n{three}\n")
+
+    archive_results(str(f), {
+        one: ("done", None),
+        two: ("failed", "metadata timeout"),
+        # three intentionally left active
+    })
+
+    lines = f.read_text().splitlines()
+    assert lines[0] == "# keep me"
+    assert lines[1].startswith("# [done ") and one in lines[1]
+    assert lines[2].startswith("# [failed ") and "metadata timeout" in lines[2] and two in lines[2]
+    assert lines[3] == three  # untouched
+
+
+def test_archive_noop_on_empty_results(tmp_path):
+    f = tmp_path / "magnets.txt"
+    original = "magnet:?xt=urn:btih:AAA&dn=one\n"
+    f.write_text(original)
+    archive_results(str(f), {})
+    assert f.read_text() == original