{"id":44603208,"url":"https://github.com/obeone/rss-watcher","last_synced_at":"2026-02-14T10:09:18.359Z","repository":{"id":336252884,"uuid":"1148884233","full_name":"obeone/rss-watcher","owner":"obeone","description":"Monitor RSS/Atom feeds and receive Telegram notifications with advanced filtering, media downloads, proxy support, and persistent storage","archived":false,"fork":false,"pushed_at":"2026-02-03T22:52:59.000Z","size":151,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T04:24:09.292Z","etag":null,"topics":["asyncio","docker","feed-reader","notifications","python","rss","rss-feed","telegram-bot"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/obeone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-03T13:33:43.000Z","updated_at":"2026-02-03T22:42:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/obeone/rss-watcher","commit_stats":null,"previous_names":["obeone/rss-watcher"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/obeone/rss-watcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obeone%2Frss-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obeone%2Frss-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obeone%2Frss-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obeone%2Frss-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obeone","download_url":"https://codeload.github.com/obeone/rss-watcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obeone%2Frss-watcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29442365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","docker","feed-reader","notifications","python","rss","rss-feed","telegram-bot"],"created_at":"2026-02-14T10:09:17.303Z","updated_at":"2026-02-14T10:09:18.350Z","avatar_url":"https://github.com/obeone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📡 RSS Watcher\n\n\u003e Monitor RSS/Atom feeds and receive Telegram notifications with advanced filtering\n\n![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776ab?style=flat-square\u0026logo=python\u0026logoColor=white)\n![Docker Ready](https://img.shields.io/badge/docker-ready-2496ed?style=flat-square\u0026logo=docker\u0026logoColor=white)\n![Telegram Bot](https://img.shields.io/badge/telegram-bot-26a5e4?style=flat-square\u0026logo=telegram\u0026logoColor=white)\n![MIT License](https://img.shields.io/badge/license-MIT-green?style=flat-square)\n![Async Powered](https://img.shields.io/badge/async-powered-ff6b6b?style=flat-square)\n\n---\n\n## ✨ Features\n\n| Feature                | Description                                                          |\n| ---------------------- | -------------------------------------------------------------------- |\n| 📡 **Multiple Feeds**  | Monitor unlimited RSS/Atom feeds simultaneously                      |\n| 🔍 **Smart Filtering** | Keywords, categories, authors, and regex patterns with AND/OR logic  |\n| 📱 **Telegram Alerts** | Beautifully formatted notifications via Telegram bot                 |\n| 💾 **Persistence**     | SQLite storage prevents duplicates across restarts                   |\n| 🐳 **Docker Ready**    | One-command deployment with docker compose                           |\n| 🎬 **Media Download**  | Automatically download videos from feed entries                      |\n| 🌐 **Proxy Support**   | SOCKS4/5 and HTTP proxy for all requests                             |\n| 🍪 **Auth Cookies**    | Per-feed cookie support for authenticated feeds                      |\n| ⚙️ **Configurable**    | YAML config with environment variable substitution                   |\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** (local) or **Docker** (containerized)\n- **Telegram Bot** token from [@BotFather](https://t.me/BotFather)\n- **Chat ID** from [@userinfobot](https://t.me/userinfobot)\n\n### 🐳 Docker (Recommended)\n\nPre-built images are available on [GitHub Container Registry](https://ghcr.io/obeone/rss-watcher) and [Docker Hub](https://hub.docker.com/r/obeoneorg/rss-watcher).\n\n```bash\n# Clone and configure\ngit clone https://github.com/obeone/rss-watcher.git\ncd rss-watcher\ncp config.example.yaml config.yaml\ncp .env.example .env\n\n# Edit .env with your Telegram credentials\n# TELEGRAM_BOT_TOKEN=your_bot_token\n# TELEGRAM_CHAT_ID=your_chat_id\n\n# Launch (uses pre-built image)\ndocker compose up -d\n\n# Or build locally\ndocker compose up -d --build\n```\n\n**Available images:**\n\n- `ghcr.io/obeone/rss-watcher:latest` (recommended)\n- `obeoneorg/rss-watcher:latest` (Docker Hub mirror)\n\n### 🐍 Local Installation\n\n```bash\n# Clone and setup\ngit clone https://github.com/obeone/rss-watcher.git\ncd rss-watcher\n\n# Create environment with uv\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install .\n\n# Configure\ncp config.example.yaml config.yaml\nexport TELEGRAM_BOT_TOKEN=\"your_bot_token\"\nexport TELEGRAM_CHAT_ID=\"your_chat_id\"\n\n# Run\nrss-watcher -c config.yaml\n```\n\n---\n\n## ⚙️ Configuration\n\nConfiguration uses YAML with environment variable substitution (`${VAR}` or `${VAR:-default}`).\n\n### 📋 Basic Structure\n\n```yaml\ntelegram:\n  bot_token: \"${TELEGRAM_BOT_TOKEN}\"\n  chat_id: \"${TELEGRAM_CHAT_ID}\"\n  parse_mode: \"HTML\"  # or \"Markdown\"\n\ndefaults:\n  check_interval: 300  # seconds between checks\n  request_timeout: 30\n  max_retries: 3\n  proxy: \"socks5://user:pass@proxy:1080\"  # optional\n  media_dir: \"media\"  # optional, for video downloads\n\nstorage:\n  database_path: \"data/rss_watcher.db\"\n\nfeeds:\n  - name: \"Tech News\"\n    url: \"https://example.com/feed.xml\"\n    check_interval: 600  # override default\n    filters:\n      keywords:\n        include: [\"python\", \"rust\"]\n```\n\n### 🔍 Filter Options\n\nAll filters combine with **AND** logic (all must pass). Within each filter, include rules use **OR** logic (any match passes).\n\n#### 📝 Keywords Filter\n\nFilter by words in title/content:\n\n```yaml\nfilters:\n  keywords:\n    include: [\"python\", \"rust\"]  # Match if contains ANY\n    exclude: [\"spam\", \"ad\"]      # Reject if contains ANY\n    case_sensitive: false\n```\n\n#### 🏷️ Categories Filter\n\nFilter by RSS categories/tags:\n\n```yaml\nfilters:\n  categories:\n    include: [\"tech\", \"programming\"]\n    exclude: [\"offtopic\"]\n    case_sensitive: false\n```\n\n#### 👤 Authors Filter\n\nFilter by author name:\n\n```yaml\nfilters:\n  authors:\n    include: [\"john\", \"jane\"]\n    exclude: [\"bot\"]\n    case_sensitive: false\n```\n\n#### 🔤 Regex Filter\n\nFilter using regular expressions:\n\n```yaml\nfilters:\n  regex:\n    title: \"^\\\\[IMPORTANT\\\\]\"      # Match title pattern\n    content: \"release.*v[0-9]+\"    # Match content pattern\n```\n\n### 🌐 Proxy Configuration\n\nRoute all requests through a proxy server:\n\n```yaml\ndefaults:\n  proxy: \"socks5://user:pass@proxy.example.com:1080\"\n```\n\n\u003e **Supported protocols:** `socks4://`, `socks5://`, `http://`\n\u003e\n\u003e Applies to both RSS fetching and Telegram API requests.\n\n### 🍪 Cookie Authentication\n\nFor feeds requiring authentication:\n\n```yaml\nfeeds:\n  - name: \"Private Feed\"\n    url: \"https://example.com/private-feed.xml\"\n    cookies:\n      session_id: \"${RSS_SESSION_ID}\"\n      auth_token: \"your-auth-token\"\n```\n\n### 🎬 Media Downloads\n\nAutomatically download videos from feed entries:\n\n```yaml\ndefaults:\n  media_dir: \"media\"  # Global default\n\nfeeds:\n  - name: \"Video Feed\"\n    url: \"https://example.com/videos.xml\"\n    media_dir: \"videos/special\"  # Override per feed\n    media_all_entries: true      # Download from all entries, not just filtered\n```\n\n\u003e Videos are extracted from HTML `\u003cvideo\u003e` tags, RSS enclosures, and Media RSS extensions.\n\n---\n\n## 📖 Usage\n\n### Command Line\n\n```text\nrss-watcher [-h] [-c CONFIG] [-v]\n\nOptions:\n  -h, --help            Show help message\n  -c, --config CONFIG   Config file path (default: config.yaml)\n  -v, --verbose         Enable debug logging\n```\n\n### Docker Commands\n\n| Command                        | Description         |\n| ------------------------------ | ------------------- |\n| `docker compose up -d`         | Start service       |\n| `docker compose logs -f`       | View live logs      |\n| `docker compose down`          | Stop service        |\n| `docker compose up -d --build` | Rebuild and restart |\n\n### 📬 Message Format\n\nNotifications are sent in HTML format:\n\n```text\n[Feed Name]\n📰 Entry Title (linked)\n👤 by Author Name\n🏷️ #tag1 #tag2\n\nEntry summary/content...\n```\n\n---\n\n## 🛠️ Development\n\n### Setup\n\n```bash\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e \".[dev]\"\n```\n\n### Commands\n\n| Task             | Command                          |\n| ---------------- | -------------------------------- |\n| Run tests        | `pytest`                         |\n| Single test file | `pytest tests/test_filters.py -v`|\n| Lint code        | `ruff check .`                   |\n| Format code      | `ruff format .`                  |\n\n### Architecture\n\n```mermaid\nflowchart TB\n    A[config.yaml] --\u003e B[RSSWatcher.start]\n\n    B --\u003e F1[Feed 1]\n    B --\u003e F2[Feed 2]\n    B --\u003e FN[Feed N]\n\n    F1 \u0026 F2 \u0026 FN --\u003e P1[Fetch]\n    P1 --\u003e P2[Filter]\n    P2 --\u003e P3[Dedupe]\n    P3 --\u003e P4[Download Media]\n    P4 --\u003e P5[Telegram Notify]\n```\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\nMade with ❤️ by [Grégoire Compagnon](mailto:obeone@obeone.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobeone%2Frss-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobeone%2Frss-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobeone%2Frss-watcher/lists"}