tg-bulk-leave 0.1.0__tar.gz

tg_bulk_leave-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env and fill in. .env is gitignored — never commit real values.
+# Get credentials at https://my.telegram.org -> API development tools.
+TG_API_ID=1234567
+TG_API_HASH=your_api_hash_here
+
+# Optional: where the Telethon session is stored. Defaults to
+# ~/.config/tg_cleanup/tg_cleanup. This file grants full account access —
+# keep it outside the repo.
+# TG_SESSION=/Users/you/.config/tg_cleanup/tg_cleanup

tg_bulk_leave-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

tg_bulk_leave-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      # --locked fails if uv.lock is out of date with pyproject.toml, so a
+      # dependency bump can never land unlocked.
+      - name: Install
+        run: uv sync --locked --dev
+
+      # The 80% coverage gate lives in [tool.coverage.report] and fails here.
+      - name: Test
+        run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install
+        run: uv sync --locked --dev
+
+      # Lint only. There is deliberately no `ruff format` gate: several lines in
+      # cli.py are hand-wrapped so the rationale for a safety decision reads well.
+      - name: Ruff
+        run: uv run ruff check
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      # A broken entry point should fail here, not on a user's first install.
+      - name: Smoke-test the built wheel
+        run: |
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke/bin/python dist/*.whl
+          /tmp/smoke/bin/tg-bulk-leave --help

tg_bulk_leave-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing: PyPI verifies this workflow's OIDC identity, so no
+    # API token is stored in the repository or anywhere else.
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v7.0.0
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@v1.14.1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/download-artifact@v7.0.0
+        with:
+          name: dist
+          path: dist/
+
+      - uses: softprops/action-gh-release@v3.0.2
+        with:
+          files: dist/*
+          generate_release_notes: true

tg_bulk_leave-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# --- Secrets and account data -------------------------------------------
+# The Telethon session is a live credential: full account access, no login code.
+*.session
+*.session-journal
+
+# Credentials
+.env
+
+# Run reports enumerate every chat the account belongs to
+reports/
+telegram_matches_*.csv
+telegram_left_*.csv
+
+# --- Local-only working documents ---------------------------------------
+# Strategy research and the phased roadmap stay out of the public repo.
+PLAN.md
+strategy.md
+
+# Agent instructions (both spellings; the filesystem may be case-sensitive)
+CLAUDE.md
+claude.md
+CLAUDE.local.md
+
+# Analysis and audit output
+.reports/
+
+# --- Python --------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Packaging / build
+build/
+dist/
+sdist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+MANIFEST
+
+# Environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test, coverage, and tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.nox/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+*.cover
+.hypothesis/

tg_bulk_leave-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-27
+
+First packaged release. Previously a personal single-file script.
+
+### Added
+
+- Installable package `tg-bulk-leave` with a console entry point
+  (`src/` layout, hatchling build; install with `uv tool install`, `pipx`,
+  or `pip`). `python -m tg_bulk_leave` also works.
+- Keywords and the protected list moved out of the source into a TOML config
+  file (`config.toml` in the platform config directory, see
+  `config.example.toml`), plus repeatable `--keyword`/`--protected` flags and
+  `--config PATH`. `--keyword` replaces the config's keywords for that run;
+  `--protected` only ever adds protection.
+- Actionable first-run errors: a missing config with no `--keyword` explains
+  exactly what to create and where; a typoed config key is rejected instead of
+  silently matching nothing.
+- MIT license.
+- Project infrastructure for a public release: GitHub Actions CI (pytest on
+  Python 3.11–3.14, `ruff check`, and a build smoke test of the wheel's entry
+  point), a tag-triggered release workflow publishing to PyPI via Trusted
+  Publishing, `SECURITY.md` documenting the session-file threat model, and
+  `CONTRIBUTING.md` recording the safety invariants a change must not break.
+- Dependencies locked in `uv.lock`; the dev toolchain moved from
+  `requirements.txt` into a PEP 735 `dev` dependency group (`uv sync --dev`).
+
+### Unchanged (deliberately)
+
+- Dry run is still the default; `--execute` still requires typing `LEAVE`.
+- Session storage location (`~/.config/tg_cleanup/`, `TG_SESSION` override)
+  and its owner-only permission handling.
+- Rate-limit pacing (2.5–5.0s between leaves), the FloodWait abort cap, CSV
+  escaping, and per-iteration log flushing. These safety floors are not
+  configurable, by design.

tg_bulk_leave-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing
+
+Bug reports, fixes, and small features are welcome. Before a large change,
+open an issue — this tool leaves groups irreversibly, so scope creep has real
+consequences.
+
+## Setup
+
+```bash
+git clone https://github.com/soos3d/tg-bulk-leave && cd tg-bulk-leave
+uv sync --dev
+
+uv run pytest        # coverage gate at 80%; currently ~98%
+uv run ruff check
+```
+
+CI runs the suite on Python 3.11–3.14 plus `ruff check` and a build smoke test.
+There is deliberately **no `ruff format` gate** — several lines in `cli.py` are
+hand-wrapped so the rationale for a safety decision reads well. Don't reformat
+files you aren't otherwise changing.
+
+`uv.lock` is committed and CI installs with `--locked`, so a dependency change
+must include the regenerated lock.
+
+## Tests come first
+
+Write the failing test, then the fix. `tests/test_tg_bulk_leave.py` covers the
+logic that decides *what gets left*, and it does so with **real Telethon entity
+types** rather than stubs — a `Chat`, a `ChannelForbidden`, an actual gigagroup
+`Channel` — so classification bugs surface instead of being mocked away. Keep
+it that way. The destructive path uses a `FakeClient`; no test touches the
+network.
+
+Several tests are regression tests for defects that shipped: the gigagroup
+dispatch, the confirmation gate, the FloodWait retry cases. Don't weaken them
+to make a change pass.
+
+## Invariants
+
+**A PR must not change any of these without a failing test that justifies it.**
+Each one is here because getting it wrong cost something real.
+
+- **Entity dispatch is type-based, not flag-based.** `is_legacy_group()` uses
+  `isinstance(entity, (Chat, ChatForbidden))`. A gigagroup has `broadcast=False`
+  *and* `megagroup=False`, so inferring "legacy group" from those flags
+  misclassifies it and routes a channel id to `DeleteChatUserRequest` — which
+  can act on an entirely unrelated chat. Note that `ChatForbidden` and
+  `ChannelForbidden` are **not** subclasses of `Chat`/`Channel`, so all four
+  types must be named explicitly.
+
+- **`PROTECTED` is checked before keywords** in `matches()`. A protected title
+  always wins. Preserve that precedence.
+
+- **`--keyword` replaces the config's keywords; `--protected` only extends the
+  config's protected list.** Naming targets explicitly should not also match
+  everything in the config file, and a command-line flag must never silently
+  drop a configured safeguard. Both directions are pinned by tests; changing
+  them is a behaviour change, not a refactor.
+
+- **Unknown config keys are rejected, not ignored.** A typo like `keyword =`
+  silently matching nothing would defeat the point of having a config file.
+  "No keywords anywhere" is an actionable `ConfigError`, not a silent no-op.
+
+- **`DELAY_MIN`, `DELAY_MAX` (2.5–5.0s) and `MAX_FLOOD_WAIT` are not
+  configurable** via file, flag, or environment, and are never lowered. The
+  leave loop is never parallelized. Telegram rate-limits bulk leaves hard, and
+  the abort cap exists so the tool never silently parks for hours.
+
+- **`leave_with_retries()` keeps its retry loop flat.** Do not nest a retry
+  inside `except FloodWaitError`: an exception raised inside an `except` block
+  is not caught by the sibling `except Exception`, so a third FloodWait — or
+  any error on a retry — escaped `leave_all()` and killed the whole run.
+  Equally, keep `except FloodWaitTooLong: raise` *ahead* of the catch-all in
+  `leave_all()`; it subclasses `RuntimeError`, so without that clause a
+  deliberate abort gets silently filed as an ordinary per-chat failure.
+  One bad chat must never stop the run.
+
+- **`is_already_left()` and `is_defunct_group()` stay separate** — dead is not
+  the same as departed. Leaving a chat does *not* remove it from
+  `iter_dialogs()`, so presence in the dialog list says nothing about
+  membership; membership is read from the `left` flag and the
+  `ChatForbidden`/`ChannelForbidden` types. Separately, `deactivated` (deleted)
+  and `migrated_to` (upgraded to a supergroup) are `Chat`-only fields and
+  *neither sets `left`*, so without that check both get offered as candidates
+  and spend rate limit on a leave that cannot succeed. Do not replace either
+  with a dialog-list presence check.
+
+- **Chat titles are attacker-controlled.** Anything user-facing or written to
+  CSV goes through `csv_safe()` — a group can be named `=HYPERLINK(...)` and a
+  spreadsheet will execute it.
+
+- **Use `report_path()` and `open_report()` for every generated file**, never a
+  bare `open()`. Reports list every chat the user belongs to and must be `0600`
+  inside a `0700` directory. The per-chat log is flushed after every iteration
+  so a crash mid-run still leaves an accurate record — keep the flush.
+
+- **Don't drop `secure_session_storage()`** or move the session into the
+  working tree. See [SECURITY.md](SECURITY.md) for why the file is pre-created
+  and the modes re-applied on every run.
+
+- **The delay between leaves is skipped after the last chat only.** Don't
+  extend that skip to failures — a failed leave still consumed a request and
+  must be paced.
+
+- **Dry run stays the default, and `--execute` keeps the typed `LEAVE` gate.**
+
+- **Never ship a shared `api_id`/`api_hash`.** Credentials are per-user and
+  environment-only. That's a Telegram ToS line, not a preference.
+
+## Commits and PRs
+
+Conventional-commit subjects (`fix:`, `feat:`, `docs:`, `chore:`, `test:`,
+`refactor:`). Explain *why* in the body when the change touches anything above.
+PRs should describe how you tested; if you ran it against a real account, say
+so and say what you left.

tg_bulk_leave-0.1.0/LICENSE

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

tg_bulk_leave-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: tg-bulk-leave
+Version: 0.1.0
+Summary: Bulk-leave Telegram groups and channels whose title matches a keyword. Dry run by default.
+Project-URL: Homepage, https://github.com/soos3d/tg-bulk-leave
+Project-URL: Repository, https://github.com/soos3d/tg-bulk-leave
+Project-URL: Changelog, https://github.com/soos3d/tg-bulk-leave/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/soos3d/tg-bulk-leave/issues
+Author: Davide Zambiasi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bulk-leave,cleanup,cli,leave-groups,telegram,telethon
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+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 :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: telethon<2,>=1.44
+Description-Content-Type: text/markdown
+
+# tg-bulk-leave
+
+Bulk-leave Telegram groups and channels whose title matches a keyword.
+
+Built for the situation where you've accumulated hundreds of chats — partner
+groups, deal rooms, airdrop channels, one-off intro chats — and want them gone
+without clicking through each one.
+
+> **Leaving is irreversible.** For a private group you'd need a fresh invite to
+> get back in. The tool defaults to a dry run and requires an explicit typed
+> confirmation before it touches anything.
+
+---
+
+## How it works
+
+```
+scan all dialogs  →  title matches a keyword?  →  title matches protected?  →  leave
+                              │ no                        │ yes
+                              └── skip ───────────────────┴── skip
+```
+
+Matching is a **case-insensitive substring** test against the chat title. A chat
+is a candidate if *any* keyword appears in its title, unless *any* protected
+string does — protection always wins.
+
+DMs are never touched. Everything runs **locally on your machine**: your
+session and credentials never leave it.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uv tool install tg-bulk-leave        # recommended
+# or
+pipx install tg-bulk-leave
+```
+
+Until the first PyPI release, install from a clone instead:
+
+```bash
+git clone https://github.com/soos3d/tg-bulk-leave && cd tg-bulk-leave
+uv tool install .                    # or: pipx install .
+```
+
+## Setup
+
+### 1. Get API credentials
+
+Go to [my.telegram.org](https://my.telegram.org) → *API development tools* and
+create an app (any title, platform "Desktop" is fine). Note the `api_id` and
+`api_hash`.
+
+- The login code arrives **inside the Telegram app**, not by SMS.
+- The `api_hash` is a secret and cannot be revoked — treat it like a password.
+
+**Getting a bare "ERROR" on app creation?** This is a known my.telegram.org
+issue ([Telethon #4661](https://github.com/LonamiWebs/Telethon/issues/4661)):
+turn off any VPN/proxy/custom DNS, use a connection whose IP is in the same
+country as your phone number, try another browser or network, and retry later.
+
+### 2. Provide the credentials
+
+Export them, or put them in a `.env` file in the directory you run from
+(see `.env.example`; exported variables win over `.env`):
+
+```ini
+TG_API_ID=1234567
+TG_API_HASH=your_api_hash_here
+```
+
+### 3. Configure keywords
+
+Either per run, on the command line:
+
+```bash
+tg-bulk-leave --keyword acme --protected "Acme Alumni"
+```
+
+or persistently in a TOML config file (see [`config.example.toml`](config.example.toml)):
+
+```toml
+keywords  = ["acme", "airdrop"]   # leave chats matching any of these
+protected = ["Acme Alumni"]       # ...except these, always
+```
+
+The file lives in your platform's config directory — `tg-bulk-leave --help`
+prints the exact path (macOS: `~/Library/Application Support/tg-bulk-leave/config.toml`,
+Linux: `~/.config/tg-bulk-leave/config.toml`) — or pass `--config PATH`.
+
+Flags and file combine safely: `--keyword` **replaces** the file's keywords for
+that run, while `--protected` only ever **adds** protection — a command-line
+flag can never drop a safeguard you configured.
+
+## Usage
+
+```bash
+# 1. Dry run — lists every match, leaves nothing. Always start here.
+tg-bulk-leave
+
+# 2. Cautious first real run — leave only the first 5 matches.
+tg-bulk-leave --execute --limit 5
+
+# 3. The real thing.
+tg-bulk-leave --execute
+```
+
+`--execute` prints the full list, then requires you to type `LEAVE` (exact
+case) to proceed. Anything else aborts.
+
+**Read the dry run properly.** Substring matching casts a wide net, and a short
+keyword gets swallowed by longer words — `"art"` also matches *Smart Contract
+Devs*. Expand the protected list until the dry-run list contains only chats
+you're willing to lose, and use `--limit` for your first real run.
+
+### First run
+
+You'll be asked for your phone number and the login code Telegram sends you
+(plus your 2FA password, if set). A session file is then written to
+`~/.config/tg_cleanup/` (override with `TG_SESSION`) so later runs skip the
+login.
+
+## Output
+
+Every run writes timestamped CSVs into `reports/` (created in the directory you
+run from), `0600` inside a `0700` directory:
+
+| File | When | Columns |
+|---|---|---|
+| `reports/telegram_matches_<stamp>.csv` | every run | title, type, id, username |
+| `reports/telegram_left_<stamp>.csv` | `--execute` only | title, type, id, result |
+
+The leave log is flushed after every chat, so if the run dies partway you still
+have an accurate record of what actually happened.
+
+**Crashed run?** Just rerun it — chats you've already left are skipped.
+
+Note that leaving a group does *not* remove it from your Telegram dialog list;
+the conversation and its history stay until you delete it. Membership is
+therefore checked explicitly via the `left` flag (and the `ChatForbidden` /
+`ChannelForbidden` types), not by absence from the dialog list. Without that
+check a rerun would retry every chat you'd already left.
+
+Defunct legacy groups are skipped for the same reason: a deleted group
+(`deactivated`) and one upgraded to a supergroup (`migrated_to`) both linger in
+the dialog list without setting the `left` flag, and neither can be left — the
+supergroup appears separately and holds the real membership.
+
+## Rate limiting
+
+Telegram throttles bulk leaves hard. The tool sleeps a random 2.5–5.0s between
+chats and backs off when told to. These delays are deliberately **not
+configurable** — lowering them earns a much longer ban.
+
+If Telegram demands a wait longer than the abort cap (300s), the run **aborts**
+rather than silently parking for hours — rerun later to continue.
+
+## Security
+
+The Telethon session file is the sensitive artifact here — **it grants full
+access to your account with no login code**. It is deliberately stored outside
+any repository (`~/.config/tg_cleanup/`) and `*.session` is gitignored. Every
+run re-applies `0700` to that directory and `0600` to the session file, so it
+stays owner-only whatever your umask is — and an existing world-readable
+session from an older version is tightened on the next run. Treat it like a
+password; don't sync it or commit it.
+
+Credentials live only in `.env` or the environment, never in source. The
+generated CSVs list every chat you belong to, so they're written `0600` and
+gitignored too.
+
+Chat titles are attacker-controlled — anyone can name a group `=HYPERLINK(...)`.
+Titles are escaped before being written to CSV so they can't execute when you
+open the report in a spreadsheet.
+
+## Development
+
+```bash
+git clone https://github.com/soos3d/tg-bulk-leave && cd tg-bulk-leave
+uv sync --dev
+
+uv run pytest        # coverage gate at 80%, configured in pyproject.toml
+uv run ruff check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the safety invariants a change must
+not break, and [SECURITY.md](SECURITY.md) for the threat model.
+
+The suite covers the logic that decides *what gets left*: keyword/protected
+precedence, config loading and flag semantics, entity classification, the
+`DeleteChatUserRequest` vs `LeaveChannelRequest` dispatch, FloodWait backoff
+and abort, CSV escaping, file permissions, and the confirmation gate. Tests use
+real Telethon entity types rather than stubs, so classification bugs surface.
+
+One subtlety worth knowing if you touch `leave()`: **legacy groups and channels
+need different API calls**, and you can't tell them apart by flags. A
+*gigagroup* has both `broadcast=False` and `megagroup=False`, so flag-sniffing
+misclassifies it as a legacy group and sends a channel id to
+`DeleteChatUserRequest` — which can act on an unrelated chat. Dispatch on type
+(`isinstance`), and note that `ChatForbidden` / `ChannelForbidden` are *not*
+subclasses of `Chat` / `Channel`.
+
+## Roadmap
+
+This project is **free, open source, and local-first** — your session never
+leaves your machine, and that stays true.
+
+- **Now:** proper packaging (this release), then PyPI publication, CI, and a
+  `SECURITY.md`.
+- **Later, maybe:** an optional hosted service for *recurring* cleanup (e.g.
+  auto-leave groups with no activity for 30+ days), which needs an always-on
+  machine. If that ever ships, it will be a separate opt-in product; the CLI
+  remains free and fully local. If you'd want such a service, open an issue —
+  that's how demand gets measured.
+
+## Requirements
+
+Python 3.11+, [Telethon](https://docs.telethon.dev) 1.44.
+
+## License
+
+[MIT](LICENSE).