1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What this is
Single-file Python script (`tg_backup.py`) that incrementally downloads media (photos + documents) from a Telegram chat/group via Telethon. No package, no tests, no build step. Keep it single-file unless there is a real reason not to.
`tg_backup.bash-completion` sits alongside it: an optional bash completion for the flags, with directory completion for `--archive-dir` (both `--opt value` and `--opt=value` forms) and no completion for `--target`, which would need a network round-trip. It relies on `_filedir` from the bash-completion package. Installed by hand to `/usr/share/bash-completion/completions/tg_backup.py`; nothing automates that. Adding a flag to the script means adding it to `opts` there too.
Dependency: `telethon` only.
## Running
```bash
./tg_backup.py --list-chats --archive-dir ./tg_archive # find IDs
./tg_backup.py --target @somegroup --archive-dir ./tg_archive
./tg_backup.py --target=-1001234567890 --archive-dir ./tg_archive
```
Negative chat IDs need `--target=<id>`; argparse reads a bare `-100...` as a flag. `--list-chats` prints ID, type, `@username` (or `-` when the chat has no public handle), and display name.
`parse_target` converts digit-only targets to `int` before `get_entity`. This is load-bearing: Telethon resolves a numeric *string* as a username and fails, while an `int` hits the session's entity cache. Usernames, `me`, and t.me links pass through as strings.
First run without a config writes a template to `~/.config/telegram_backup/config.json` and exits; the user fills in `api_id`/`api_hash` from my.telegram.org. Telethon then prompts interactively for phone/code on first auth, so the script cannot be run unattended the first time.
## Design invariants
Three things are load-bearing and easy to break:
1. **`reverse=True` on `iter_messages`** (`tg_backup.py:75`). Processing must be oldest-to-newest. `state['last_id']` is a high-water mark used as `min_id` on resume; iterating newest-first would make it skip unfetched history permanently.
2. **State saved after every message**, not at the end, via temp-file + `os.replace`. Cheap insurance against interruption; do not "optimize" into a batched write without keeping resume correctness, and keep the write atomic. A truncated `state.json` makes the next run unstartable.
3. **Two-level retry handling.** The inner `download_with_retry` retries a single file up to `MAX_RETRIES`: FloodWait sleeps the server-requested interval, other exceptions (network drops, expired file references, disk errors) get exponential backoff so one flaky socket can't kill an overnight run. The outer `while True` in `run_backup` catches FloodWait on history fetching, saves state, sleeps, and restarts the iterator from the saved id. A permanently failed download still advances state on purpose, so one broken file can't wedge the backup forever; the gap is recorded in `failures.json` (see below) rather than lost. `download_with_retry` returns the last exception, or `None` on success, so the caller has something to log.
4. **Media downloads to `{name}.part`, renamed on success.** The dedup check is `filepath.exists()`, so a truncated file at the final path would be skipped forever as if complete. The `.part` file is unlinked on failure and on interrupt, leaving the message to be retried on the next run.
Resume/dedup is also file-based: media is named `{message.id}_{sanitized_name}` (see `safe_filename`, which strips sender-controlled path components) and an existing path is skipped, so state loss degrades to a slow rescan rather than re-downloading everything.
## Checks
`python3 tg_backup.py --self-check` exercises `safe_filename` path-traversal handling and `save_state`/`load_state` round-tripping. No network, no login. It does import telethon, so it needs the dep installed.
## Layout
`--archive-dir` holds media files, `state.json`, and `failures.json`, and is created if missing (`parents=True`). It is per-chat: one dir per backed-up chat.
`state.json` also stores the `target` the dir was last backed up with, so subsequent runs need only `--archive-dir`. An explicit `--target` still wins; it is only required for a dir with no saved target (a first run, or one created before this was added). Pointing an existing dir at a *different* chat is refused before any network work (`same_target` in `run_backup`), because `last_id` from the old chat would be applied as `min_id` to the new one and skip its history while reporting success. The comparison is textual, ignoring case and a leading `@`; it cannot tell that `@foo` and `-100…` are the same chat, since resolving that needs a logged-in client, so that case refuses too. `--force-target` overrides and keeps the existing resume position.
`failures.json` is append-only JSONL, one `{"id", "file", "error"}` object per line, written only when a download exhausts `MAX_RETRIES`. JSONL rather than a JSON array so appending is a single write with no read-modify-write: a crash costs the last line, not the file. Read it with `jq -s`. Nothing reads or prunes it, and a message failing on two runs is logged twice.
Auth lives in `~/.config/telegram_backup/` (mode 0700): `config.json` with the api_id/api_hash, and `session.session`, a single Telethon session **shared by every archive dir**, so one login covers all chats. `migrate_session` relocates a pre-existing `<archive_dir>/session.session` to the shared path on first run rather than forcing a re-login; it is a no-op once the shared session exists. It uses `shutil.move`, not `os.replace`, because the two paths can be on different filesystems.
The session file is account credentials: anyone holding it can read the account's Telegram. Keep it 0600 and out of git.
|
