telethon-floodgate 0.1.0__tar.gz

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

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Build + twine check
+        run: |
+          python -m build
+          python -m twine check dist/*
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Pytest
+        run: python -m pytest -q

telethon_floodgate-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

telethon_floodgate-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial release — 1:1 extraction of the flood stack from the tg_content_factory
+project, plus per-peer send limits.
+
+- `TelegramRateLimitGate`: proactive per-(phone, category) sliding windows
+  plus per-peer send buckets `(phone, category, peer)` — independent from the
+  category budget, with `peer_key()` extraction from Telethon entities
+  (`peer.py`) and `TelegramPeerRateLimitedError`
+- `FloodCircuitBreaker`: pybreaker-based suspension per (operation, phone)
+- `ResolveRateLimiter`: sliding-window limiter for `auth.resolveUsername`
+- flood-wait helpers: `run_with_flood_wait`, `run_with_flood_wait_retry`,
+  transient/blocking classification, sleep helpers, `FloodWaitInfo`

telethon_floodgate-0.1.0/LICENSE

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

telethon_floodgate-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: telethon-floodgate
+Version: 0.1.0
+Summary: Flood-wait handling, proactive rate-limit gate and circuit breaker for Telethon user accounts
+Author: Axisrow
+License: MIT
+Project-URL: Homepage, https://github.com/axisrow/telethon-floodgate
+Project-URL: Repository, https://github.com/axisrow/telethon-floodgate
+Project-URL: Changelog, https://github.com/axisrow/telethon-floodgate/blob/main/CHANGELOG.md
+Keywords: telegram,telethon,flood-wait,rate-limit,floodwait,mtproto
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon<2,>=1.36
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pybreaker>=1.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# telethon-floodgate
+
+Flood-wait handling for Telethon user accounts: a proactive rate-limit gate, a
+reactive circuit breaker, and flood-wait sleep/retry helpers — three layers
+that keep a working account out of Telegram's multi-hour FLOOD_WAIT bans.
+
+Telegram does not publish rate limits. This library is the production flood
+stack of a multi-account Telegram content collector, calibrated against real
+incidents: a fresh session firing 160+ `auth.resolveUsername` calls in seconds
+escalated into 15–18 hour bans, and repeated `getDialogs` sweeps ran a account
+into a 14.8-hour ban. The defaults are deliberately conservative and every
+bucket is configurable.
+
+## Install
+
+```bash
+pip install telethon-floodgate
+```
+
+Requires Python 3.11+, [Telethon](https://github.com/LonamiWebs/Telethon) 1.x,
+pydantic 2.x and pybreaker.
+
+## The three layers
+
+### 1. Proactive rate-limit gate — before the call
+
+```python
+from telethon_floodgate import TelegramRateLimitGate, TelegramRateLimitedError
+
+gate = TelegramRateLimitGate()          # create once, next to your client pool
+
+def before_telegram_call(phone: str, operation: str) -> None:
+    category = gate.category_for(operation)   # "send", "history", "dialogs", ...
+    retry_after = gate.try_acquire(phone, category)
+    if retry_after > 0:
+        raise TelegramRateLimitedError(phone, category, retry_after)
+```
+
+Buckets are independent sliding windows keyed by `(phone, category)`:
+`dialogs` (1/min — the #1330 incident), `dialog_sweep`, `history`,
+`admin_action`, `send` (30/min), `channel_lifecycle` (3 per 5 min), plus a
+permissive `default`. Override any of them:
+
+```python
+from telethon_floodgate import RateLimitSpec, TelegramRateLimitGate
+
+gate = TelegramRateLimitGate(
+    category_limits={"send": RateLimitSpec(max_calls=10, window_sec=60.0)}
+)
+```
+
+`resolve` and `reaction` are intentionally no-op categories: in the origin
+project those paths have dedicated limiters (see `ResolveRateLimiter`, also
+shipped here).
+
+### Per-peer send limits
+
+Telegram throttles *sending* per peer, not just per account: roughly one
+message per second to the same private chat and about twenty per minute into
+the same group or channel. Pass a peer key to `try_acquire` and the gate
+checks a second, independent `(phone, category, peer)` bucket before the
+category one:
+
+```python
+from telethon_floodgate import peer_key
+
+retry_after = gate.try_acquire(phone, "send", peer=peer_key(entity))
+if retry_after > 0:
+    raise TelegramPeerRateLimitedError(phone, peer_key(entity), retry_after)
+```
+
+- A per-peer refusal does **not** consume the account-wide category slot, so a
+  burst aimed at one peer cannot burn the account budget.
+- `peer_key()` derives `"user:123"` / `"channel:-100123"` / `"chat:-456"` /
+  `"username:durov"` / `"id:123"` from ints, strings, Telethon TL peers, input
+  peers and full entities — purely local attribute access, never a network
+  round-trip.
+- Only `send:user`, `send:channel` and `send:chat` are configured by default;
+  unknown kinds pass through unthrottled. Override or disable via `peer_limits`
+  (a `"send:user"` entry with a permissive spec effectively turns it off) and
+  cap memory with `peer_max_buckets` (LRU, default 4096).
+
+```python
+gate = TelegramRateLimitGate(
+    peer_limits={"send:user": RateLimitSpec(max_calls=1, window_sec=5.0)},
+    peer_max_buckets=4096,
+)
+```
+
+`TelegramPeerRateLimitedError` subclasses `TelegramRateLimitedError`, so one
+"operation unavailable, move on" handler covers every layer.
+
+### 2. Reactive circuit breaker — when Telegram answers anyway
+
+```python
+from telethon_floodgate import FloodCircuitBreaker
+
+breaker = FloodCircuitBreaker(threshold=3, cooldown_seconds=300)
+
+breaker.check(operation, phone)            # raises TelegramOperationSuspendedError
+                                           # while the pair is suspended
+try:
+    await client.some_call()
+    breaker.record_success(operation, phone)
+except telethon.errors.FloodWaitError:
+    breaker.record_flood(operation, phone)
+```
+
+After `threshold` flood waits on the same `(operation, phone)` the pair is
+suspended for `cooldown_seconds`, then exactly one half-open trial call is
+allowed. `TelegramOperationSuspendedError` subclasses
+`TelegramRateLimitedError`, so a single "operation unavailable, move on"
+handler covers both layers.
+
+### 3. Flood-wait helpers — classify, sleep, retry, report
+
+```python
+from telethon_floodgate import (
+    HandledFloodWaitError, FloodWaitInfo,
+    handle_flood_wait, run_with_flood_wait, run_with_flood_wait_retry,
+    is_transient_flood_wait_seconds, is_blocking_flood_wait_until,
+)
+
+# wraps one awaitable: FloodWaitError -> HandledFloodWaitError (+ pool report)
+await run_with_flood_wait(client.get_dialogs(), operation="warm", phone=phone, pool=pool)
+
+# retries transient waits (<=60s) under a total budget (120s default)
+await run_with_flood_wait_retry(factory, operation="fetch", phone=phone, pool=pool)
+```
+
+`handle_flood_wait` reports the wait back to the pool via
+`await pool.report_flood(phone, seconds)` so account rotation can skip the
+flooded account — persist that to your own storage; the library is
+storage-agnostic.
+
+## Design notes
+
+- Everything runs on one event loop; the limiter state is plain in-memory
+  deques, no locks, no DB.
+- `try_acquire` never sleeps and never raises — it returns seconds to defer,
+  so callers decide whether to reschedule, skip or await.
+- Atomic multi-slot reservations (`try_acquire(..., slots=n)`) are supported
+  for compound operations.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Unofficial third-party library; not affiliated
+with the Telethon project.

telethon_floodgate-0.1.0/README.md

@@ -0,0 +1,148 @@
+# telethon-floodgate
+
+Flood-wait handling for Telethon user accounts: a proactive rate-limit gate, a
+reactive circuit breaker, and flood-wait sleep/retry helpers — three layers
+that keep a working account out of Telegram's multi-hour FLOOD_WAIT bans.
+
+Telegram does not publish rate limits. This library is the production flood
+stack of a multi-account Telegram content collector, calibrated against real
+incidents: a fresh session firing 160+ `auth.resolveUsername` calls in seconds
+escalated into 15–18 hour bans, and repeated `getDialogs` sweeps ran a account
+into a 14.8-hour ban. The defaults are deliberately conservative and every
+bucket is configurable.
+
+## Install
+
+```bash
+pip install telethon-floodgate
+```
+
+Requires Python 3.11+, [Telethon](https://github.com/LonamiWebs/Telethon) 1.x,
+pydantic 2.x and pybreaker.
+
+## The three layers
+
+### 1. Proactive rate-limit gate — before the call
+
+```python
+from telethon_floodgate import TelegramRateLimitGate, TelegramRateLimitedError
+
+gate = TelegramRateLimitGate()          # create once, next to your client pool
+
+def before_telegram_call(phone: str, operation: str) -> None:
+    category = gate.category_for(operation)   # "send", "history", "dialogs", ...
+    retry_after = gate.try_acquire(phone, category)
+    if retry_after > 0:
+        raise TelegramRateLimitedError(phone, category, retry_after)
+```
+
+Buckets are independent sliding windows keyed by `(phone, category)`:
+`dialogs` (1/min — the #1330 incident), `dialog_sweep`, `history`,
+`admin_action`, `send` (30/min), `channel_lifecycle` (3 per 5 min), plus a
+permissive `default`. Override any of them:
+
+```python
+from telethon_floodgate import RateLimitSpec, TelegramRateLimitGate
+
+gate = TelegramRateLimitGate(
+    category_limits={"send": RateLimitSpec(max_calls=10, window_sec=60.0)}
+)
+```
+
+`resolve` and `reaction` are intentionally no-op categories: in the origin
+project those paths have dedicated limiters (see `ResolveRateLimiter`, also
+shipped here).
+
+### Per-peer send limits
+
+Telegram throttles *sending* per peer, not just per account: roughly one
+message per second to the same private chat and about twenty per minute into
+the same group or channel. Pass a peer key to `try_acquire` and the gate
+checks a second, independent `(phone, category, peer)` bucket before the
+category one:
+
+```python
+from telethon_floodgate import peer_key
+
+retry_after = gate.try_acquire(phone, "send", peer=peer_key(entity))
+if retry_after > 0:
+    raise TelegramPeerRateLimitedError(phone, peer_key(entity), retry_after)
+```
+
+- A per-peer refusal does **not** consume the account-wide category slot, so a
+  burst aimed at one peer cannot burn the account budget.
+- `peer_key()` derives `"user:123"` / `"channel:-100123"` / `"chat:-456"` /
+  `"username:durov"` / `"id:123"` from ints, strings, Telethon TL peers, input
+  peers and full entities — purely local attribute access, never a network
+  round-trip.
+- Only `send:user`, `send:channel` and `send:chat` are configured by default;
+  unknown kinds pass through unthrottled. Override or disable via `peer_limits`
+  (a `"send:user"` entry with a permissive spec effectively turns it off) and
+  cap memory with `peer_max_buckets` (LRU, default 4096).
+
+```python
+gate = TelegramRateLimitGate(
+    peer_limits={"send:user": RateLimitSpec(max_calls=1, window_sec=5.0)},
+    peer_max_buckets=4096,
+)
+```
+
+`TelegramPeerRateLimitedError` subclasses `TelegramRateLimitedError`, so one
+"operation unavailable, move on" handler covers every layer.
+
+### 2. Reactive circuit breaker — when Telegram answers anyway
+
+```python
+from telethon_floodgate import FloodCircuitBreaker
+
+breaker = FloodCircuitBreaker(threshold=3, cooldown_seconds=300)
+
+breaker.check(operation, phone)            # raises TelegramOperationSuspendedError
+                                           # while the pair is suspended
+try:
+    await client.some_call()
+    breaker.record_success(operation, phone)
+except telethon.errors.FloodWaitError:
+    breaker.record_flood(operation, phone)
+```
+
+After `threshold` flood waits on the same `(operation, phone)` the pair is
+suspended for `cooldown_seconds`, then exactly one half-open trial call is
+allowed. `TelegramOperationSuspendedError` subclasses
+`TelegramRateLimitedError`, so a single "operation unavailable, move on"
+handler covers both layers.
+
+### 3. Flood-wait helpers — classify, sleep, retry, report
+
+```python
+from telethon_floodgate import (
+    HandledFloodWaitError, FloodWaitInfo,
+    handle_flood_wait, run_with_flood_wait, run_with_flood_wait_retry,
+    is_transient_flood_wait_seconds, is_blocking_flood_wait_until,
+)
+
+# wraps one awaitable: FloodWaitError -> HandledFloodWaitError (+ pool report)
+await run_with_flood_wait(client.get_dialogs(), operation="warm", phone=phone, pool=pool)
+
+# retries transient waits (<=60s) under a total budget (120s default)
+await run_with_flood_wait_retry(factory, operation="fetch", phone=phone, pool=pool)
+```
+
+`handle_flood_wait` reports the wait back to the pool via
+`await pool.report_flood(phone, seconds)` so account rotation can skip the
+flooded account — persist that to your own storage; the library is
+storage-agnostic.
+
+## Design notes
+
+- Everything runs on one event loop; the limiter state is plain in-memory
+  deques, no locks, no DB.
+- `try_acquire` never sleeps and never raises — it returns seconds to defer,
+  so callers decide whether to reschedule, skip or await.
+- Atomic multi-slot reservations (`try_acquire(..., slots=n)`) are supported
+  for compound operations.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Unofficial third-party library; not affiliated
+with the Telethon project.

telethon_floodgate-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telethon-floodgate"
+version = "0.1.0"
+description = "Flood-wait handling, proactive rate-limit gate and circuit breaker for Telethon user accounts"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Axisrow"}]
+requires-python = ">=3.11"
+keywords = ["telegram", "telethon", "flood-wait", "rate-limit", "floodwait", "mtproto"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "telethon>=1.36,<2",
+    "pydantic>=2.0,<3",
+    "pybreaker>=1.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/axisrow/telethon-floodgate"
+Repository = "https://github.com/axisrow/telethon-floodgate"
+Changelog = "https://github.com/axisrow/telethon-floodgate/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+    "build>=1.2",
+    "twine>=6.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+telethon_floodgate = ["py.typed"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+filterwarnings = ["error"]

telethon_floodgate-0.1.0/scripts/release_pypi.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="${ROOT_DIR}/.env"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/release_pypi.sh testpypi
+  scripts/release_pypi.sh pypi
+  scripts/release_pypi.sh all
+
+Behavior:
+  - loads .env from the repository root when present
+  - rebuilds dist artifacts from scratch
+  - runs twine checks before upload
+  - uploads to TestPyPI, PyPI, or both
+
+Required .env variables:
+  TWINE_USERNAME=__token__
+  TEST_PYPI_TOKEN=pypi-...   # for testpypi/all
+  PYPI_TOKEN=pypi-...        # for pypi/all
+EOF
+}
+
+if [[ $# -ne 1 ]]; then
+  usage
+  exit 1
+fi
+
+TARGET="$1"
+
+case "${TARGET}" in
+  testpypi|pypi|all)
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac
+
+if [[ -f "${ENV_FILE}" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "${ENV_FILE}"
+  set +a
+fi
+
+TWINE_USERNAME="${TWINE_USERNAME:-__token__}"
+
+require_var() {
+  local name="$1"
+  if [[ -z "${!name:-}" ]]; then
+    echo "Missing required environment variable: ${name}" >&2
+    exit 1
+  fi
+}
+
+require_command() {
+  local name="$1"
+  if ! command -v "${name}" >/dev/null 2>&1; then
+    echo "Required command not found: ${name}" >&2
+    exit 1
+  fi
+}
+
+build_artifacts() {
+  require_command python3
+
+  echo "Cleaning old build artifacts"
+  rm -rf "${ROOT_DIR}/dist" "${ROOT_DIR}/build" "${ROOT_DIR}"/*.egg-info
+
+  echo "Building package"
+  (
+    cd "${ROOT_DIR}"
+    python3 -m build --no-isolation
+  )
+
+  echo "Checking artifacts with twine"
+  (
+    cd "${ROOT_DIR}"
+    python3 -m twine check dist/*
+  )
+}
+
+upload_target() {
+  local repo_url="$1"
+  local password_var="$2"
+  local label="$3"
+
+  require_var "${password_var}"
+
+  echo "Uploading to ${label}"
+  (
+    cd "${ROOT_DIR}"
+    TWINE_USERNAME="${TWINE_USERNAME}" \
+    TWINE_PASSWORD="${!password_var}" \
+    python3 -m twine upload --non-interactive --repository-url "${repo_url}" dist/*
+  )
+}
+
+build_artifacts
+
+case "${TARGET}" in
+  testpypi)
+    upload_target "https://test.pypi.org/legacy/" "TEST_PYPI_TOKEN" "TestPyPI"
+    ;;
+  pypi)
+    upload_target "https://upload.pypi.org/legacy/" "PYPI_TOKEN" "PyPI"
+    ;;
+  all)
+    upload_target "https://test.pypi.org/legacy/" "TEST_PYPI_TOKEN" "TestPyPI"
+    upload_target "https://upload.pypi.org/legacy/" "PYPI_TOKEN" "PyPI"
+    ;;
+esac

telethon_floodgate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+