watcherr 0.1.0__tar.gz

watcherr-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.pyc
+.env

watcherr-0.1.0/LICENSE

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

watcherr-0.1.0/Makefile

@@ -0,0 +1,26 @@
+.PHONY: install dev lint format test build publish clean
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+lint:
+	ruff check watcherr/ tests/
+
+format:
+	ruff format watcherr/ tests/
+	ruff check --fix watcherr/ tests/
+
+test:
+	pytest tests/ -v
+
+build:
+	python -m build
+
+publish:
+	twine upload dist/*
+
+clean:
+	rm -rf dist/ build/ *.egg-info

watcherr-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: watcherr
+Version: 0.1.0
+Summary: Lightweight error alerting via Telegram
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alerting,error,monitoring,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Provides-Extra: all
+Requires-Dist: aiogram>=3.0; extra == 'all'
+Requires-Dist: celery>=5.0; extra == 'all'
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Provides-Extra: bot
+Requires-Dist: aiogram>=3.0; extra == 'bot'
+Provides-Extra: celery
+Requires-Dist: celery>=5.0; extra == 'celery'
+Provides-Extra: dev
+Requires-Dist: aiogram>=3.0; extra == 'dev'
+Requires-Dist: celery>=5.0; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# watcherr
+
+Lightweight error alerting via Telegram for Python apps.
+
+## Install
+
+```bash
+pip install watcherr
+```
+
+Optional integrations:
+
+```bash
+pip install watcherr[fastapi]
+pip install watcherr[celery]
+pip install watcherr[all]
+```
+
+## Setup
+
+### 1. Get chat ID
+
+```bash
+WATCHERR_BOT_TOKEN=<your-token> watcherr
+```
+
+Send `/start` to the bot — it will reply with your `chat_id`.
+
+### 2. Configure
+
+Via code:
+
+```python
+import watcherr
+
+watcherr.configure(
+    bot_token="123456:ABC-DEF",
+    chat_id="-1001234567890",
+    service_name="my-api",
+)
+```
+
+Or via `.env`:
+
+```
+WATCHERR_BOT_TOKEN=123456:ABC-DEF
+WATCHERR_CHAT_ID=-1001234567890
+WATCHERR_SERVICE_NAME=my-api
+WATCHERR_ENVIRONMENT=production
+```
+
+## Usage
+
+```python
+import watcherr
+
+watcherr.send_alert("Database connection failed", exc=exception)
+watcherr.send_warning("Slow query", table="users", duration="5s")
+watcherr.send_info("Deployed", version="1.2.0")
+```
+
+### Logging handler
+
+```python
+import logging
+from watcherr.logging_handler import WatcherrHandler
+
+logging.getLogger("myapp").addHandler(WatcherrHandler())
+```
+
+### FastAPI middleware
+
+```python
+from watcherr.integrations.fastapi_middleware import WatcherrMiddleware
+
+app.add_middleware(WatcherrMiddleware)
+```
+
+### Celery signals
+
+```python
+from watcherr.integrations.celery_signals import setup_celery_alerts
+
+setup_celery_alerts()
+```
+
+## Config options
+
+| Env variable | Default | Description |
+|---|---|---|
+| `WATCHERR_BOT_TOKEN` | — | Telegram bot token |
+| `WATCHERR_CHAT_ID` | — | Telegram chat/group ID |
+| `WATCHERR_SERVICE_NAME` | `app` | Service name in alert title |
+| `WATCHERR_ENVIRONMENT` | `production` | Environment label |
+| `WATCHERR_RATE_LIMIT` | `60` | Dedup window in seconds |
+| `WATCHERR_ENABLED` | `true` | Enable/disable sending |

watcherr-0.1.0/README.md

@@ -0,0 +1,96 @@
+# watcherr
+
+Lightweight error alerting via Telegram for Python apps.
+
+## Install
+
+```bash
+pip install watcherr
+```
+
+Optional integrations:
+
+```bash
+pip install watcherr[fastapi]
+pip install watcherr[celery]
+pip install watcherr[all]
+```
+
+## Setup
+
+### 1. Get chat ID
+
+```bash
+WATCHERR_BOT_TOKEN=<your-token> watcherr
+```
+
+Send `/start` to the bot — it will reply with your `chat_id`.
+
+### 2. Configure
+
+Via code:
+
+```python
+import watcherr
+
+watcherr.configure(
+    bot_token="123456:ABC-DEF",
+    chat_id="-1001234567890",
+    service_name="my-api",
+)
+```
+
+Or via `.env`:
+
+```
+WATCHERR_BOT_TOKEN=123456:ABC-DEF
+WATCHERR_CHAT_ID=-1001234567890
+WATCHERR_SERVICE_NAME=my-api
+WATCHERR_ENVIRONMENT=production
+```
+
+## Usage
+
+```python
+import watcherr
+
+watcherr.send_alert("Database connection failed", exc=exception)
+watcherr.send_warning("Slow query", table="users", duration="5s")
+watcherr.send_info("Deployed", version="1.2.0")
+```
+
+### Logging handler
+
+```python
+import logging
+from watcherr.logging_handler import WatcherrHandler
+
+logging.getLogger("myapp").addHandler(WatcherrHandler())
+```
+
+### FastAPI middleware
+
+```python
+from watcherr.integrations.fastapi_middleware import WatcherrMiddleware
+
+app.add_middleware(WatcherrMiddleware)
+```
+
+### Celery signals
+
+```python
+from watcherr.integrations.celery_signals import setup_celery_alerts
+
+setup_celery_alerts()
+```
+
+## Config options
+
+| Env variable | Default | Description |
+|---|---|---|
+| `WATCHERR_BOT_TOKEN` | — | Telegram bot token |
+| `WATCHERR_CHAT_ID` | — | Telegram chat/group ID |
+| `WATCHERR_SERVICE_NAME` | `app` | Service name in alert title |
+| `WATCHERR_ENVIRONMENT` | `production` | Environment label |
+| `WATCHERR_RATE_LIMIT` | `60` | Dedup window in seconds |
+| `WATCHERR_ENABLED` | `true` | Enable/disable sending |

watcherr-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "watcherr"
+version = "0.1.0"
+description = "Lightweight error alerting via Telegram"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["error", "alerting", "telegram", "monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Monitoring",
+]
+
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+celery = ["celery>=5.0"]
+bot = ["aiogram>=3.0"]
+all = ["watcherr[fastapi,celery,bot]"]
+dev = [
+    "watcherr[all]",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+watcherr = "watcherr.bot.main:main"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

watcherr-0.1.0/tests/test_config.py

@@ -0,0 +1,45 @@
+import os
+from unittest.mock import patch
+
+from watcherr.config import WatcherrConfig, configure
+
+
+def test_default_config():
+    config = WatcherrConfig()
+    assert config.bot_token == ""
+    assert config.enabled is True
+    assert config.rate_limit_seconds == 60
+
+
+def test_configure_explicit():
+    config = configure(
+        bot_token="123:ABC",
+        chat_id="-100",
+        service_name="test-svc",
+        environment="test",
+        rate_limit_seconds=30,
+        enabled=True,
+    )
+    assert config.bot_token == "123:ABC"
+    assert config.chat_id == "-100"
+    assert config.service_name == "test-svc"
+
+
+def test_configure_from_env():
+    env = {
+        "WATCHERR_BOT_TOKEN": "env-token",
+        "WATCHERR_CHAT_ID": "-200",
+        "WATCHERR_SERVICE_NAME": "env-svc",
+        "WATCHERR_ENVIRONMENT": "staging",
+        "WATCHERR_RATE_LIMIT": "120",
+        "WATCHERR_ENABLED": "false",
+    }
+    with patch.dict(os.environ, env, clear=False):
+        config = configure()
+
+    assert config.bot_token == "env-token"
+    assert config.chat_id == "-200"
+    assert config.service_name == "env-svc"
+    assert config.environment == "staging"
+    assert config.rate_limit_seconds == 120
+    assert config.enabled is False

watcherr-0.1.0/tests/test_formatter.py

@@ -0,0 +1,46 @@
+from watcherr.formatter import _escape_html, format_message
+
+
+def test_format_error_message():
+    result = format_message(
+        level="error",
+        message="Something broke",
+        service_name="api",
+        environment="prod",
+    )
+    assert "ERROR" in result
+    assert "api" in result
+    assert "prod" in result
+    assert "Something broke" in result
+
+
+def test_format_with_exception():
+    try:
+        raise ValueError("test error")
+    except ValueError as e:
+        result = format_message(
+            level="error",
+            message="Caught",
+            service_name="worker",
+            environment="staging",
+            exc=e,
+        )
+    assert "ValueError" in result
+    assert "test error" in result
+
+
+def test_format_with_extra():
+    result = format_message(
+        level="warning",
+        message="Slow query",
+        service_name="db",
+        environment="prod",
+        extra={"table": "users", "duration": "5s"},
+    )
+    assert "table" in result
+    assert "users" in result
+
+
+def test_escape_html():
+    assert _escape_html("<script>") == "&lt;script&gt;"
+    assert _escape_html("a & b") == "a &amp; b"

watcherr-0.1.0/tests/test_logging_handler.py

@@ -0,0 +1,53 @@
+import logging
+from unittest.mock import patch
+
+from watcherr.config import configure
+from watcherr.logging_handler import WatcherrHandler
+
+
+def _setup():
+    configure(
+        bot_token="123:TEST",
+        chat_id="-999",
+        service_name="test",
+        rate_limit_seconds=0,
+    )
+
+
+@patch("watcherr.logging_handler.send_alert")
+def test_error_log_sends_alert(mock_send):
+    _setup()
+    logger = logging.getLogger("test.handler.error")
+    logger.addHandler(WatcherrHandler(level=logging.ERROR))
+    logger.setLevel(logging.ERROR)
+
+    logger.error("something failed")
+
+    mock_send.assert_called_once()
+    assert "something failed" in mock_send.call_args[0][0]
+
+
+@patch("watcherr.logging_handler.send_warning")
+def test_warning_log_sends_warning(mock_send):
+    _setup()
+    handler = WatcherrHandler(level=logging.WARNING)
+    logger = logging.getLogger("test.handler.warning")
+    logger.addHandler(handler)
+    logger.setLevel(logging.WARNING)
+
+    logger.warning("slow response")
+
+    mock_send.assert_called_once()
+
+
+@patch("watcherr.logging_handler.send_alert")
+def test_below_level_ignored(mock_send):
+    _setup()
+    handler = WatcherrHandler(level=logging.ERROR)
+    logger = logging.getLogger("test.handler.below")
+    logger.handlers = [handler]
+    logger.setLevel(logging.DEBUG)
+
+    logger.info("not important")
+
+    mock_send.assert_not_called()

watcherr-0.1.0/tests/test_rate_limiter.py

@@ -0,0 +1,27 @@
+import time
+
+from watcherr.rate_limiter import RateLimiter
+
+
+def test_first_message_allowed():
+    limiter = RateLimiter(window_seconds=60)
+    assert limiter.should_send("error: something") is True
+
+
+def test_duplicate_blocked():
+    limiter = RateLimiter(window_seconds=60)
+    assert limiter.should_send("error: same") is True
+    assert limiter.should_send("error: same") is False
+
+
+def test_different_messages_allowed():
+    limiter = RateLimiter(window_seconds=60)
+    assert limiter.should_send("error A") is True
+    assert limiter.should_send("error B") is True
+
+
+def test_expired_message_allowed_again():
+    limiter = RateLimiter(window_seconds=0)
+    assert limiter.should_send("error: expire") is True
+    time.sleep(0.01)
+    assert limiter.should_send("error: expire") is True

watcherr-0.1.0/tests/test_sender.py

@@ -0,0 +1,56 @@
+from unittest.mock import MagicMock, patch
+
+from watcherr.config import configure
+from watcherr.sender import send_alert, send_info, send_warning
+
+
+def _setup_config():
+    configure(
+        bot_token="123:TEST",
+        chat_id="-999",
+        service_name="test",
+        environment="test",
+        rate_limit_seconds=0,
+    )
+
+
+@patch("watcherr.sender._dispatch")
+def test_send_alert_dispatches(mock_dispatch: MagicMock):
+    _setup_config()
+    send_alert("test error")
+    mock_dispatch.assert_called_once()
+    text = mock_dispatch.call_args[0][0]
+    assert "ERROR" in text
+    assert "test error" in text
+
+
+@patch("watcherr.sender._dispatch")
+def test_send_warning_dispatches(mock_dispatch: MagicMock):
+    _setup_config()
+    send_warning("test warning")
+    mock_dispatch.assert_called_once()
+    text = mock_dispatch.call_args[0][0]
+    assert "WARNING" in text
+
+
+@patch("watcherr.sender._dispatch")
+def test_send_info_dispatches(mock_dispatch: MagicMock):
+    _setup_config()
+    send_info("deployed v1.2")
+    mock_dispatch.assert_called_once()
+    text = mock_dispatch.call_args[0][0]
+    assert "INFO" in text
+
+
+@patch("watcherr.sender._dispatch")
+def test_disabled_config_skips(mock_dispatch: MagicMock):
+    configure(bot_token="123:TEST", chat_id="-999", enabled=False)
+    send_alert("should not send")
+    mock_dispatch.assert_not_called()
+
+
+@patch("watcherr.sender._dispatch")
+def test_missing_token_skips(mock_dispatch: MagicMock):
+    configure(bot_token="", chat_id="-999")
+    send_alert("should not send")
+    mock_dispatch.assert_not_called()

watcherr-0.1.0/watcherr/__init__.py

@@ -0,0 +1,10 @@
+from watcherr.config import WatcherrConfig, configure
+from watcherr.sender import send_alert, send_info, send_warning
+
+__all__ = [
+    "WatcherrConfig",
+    "configure",
+    "send_alert",
+    "send_warning",
+    "send_info",
+]

watcherr-0.1.0/watcherr/bot/handlers.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from aiogram import Router
+from aiogram.filters import Command
+from aiogram.types import Message
+
+router = Router()
+
+
+@router.message(Command("start"))
+async def cmd_start(message: Message) -> None:
+    chat_id = message.chat.id
+    await message.answer(
+        f"<b>watcherr</b> bot activated.\n\n"
+        f"Your chat ID: <code>{chat_id}</code>\n\n"
+        f"Set this as <code>WATCHERR_CHAT_ID</code> in your environment.",
+        parse_mode="HTML",
+    )
+
+
+@router.message(Command("status"))
+async def cmd_status(message: Message) -> None:
+    await message.answer(
+        "<b>watcherr</b> is running and listening for alerts.",
+        parse_mode="HTML",
+    )
+
+
+@router.message(Command("ping"))
+async def cmd_ping(message: Message) -> None:
+    await message.answer("pong")
+
+
+@router.message(Command("help"))
+async def cmd_help(message: Message) -> None:
+    await message.answer(
+        "<b>Commands:</b>\n/start — Get chat ID\n/status — Check bot status\n/ping — Ping\n/help — This message",
+        parse_mode="HTML",
+    )

watcherr-0.1.0/watcherr/bot/main.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from watcherr.bot.handlers import router
+
+
+def main() -> None:
+    token = os.getenv("WATCHERR_BOT_TOKEN")
+    if not token:
+        print("Error: WATCHERR_BOT_TOKEN environment variable is required")
+        sys.exit(1)
+
+    asyncio.run(_run(token))
+
+
+async def _run(token: str) -> None:
+    from aiogram import Bot, Dispatcher
+
+    bot = Bot(token=token)
+    dp = Dispatcher()
+    dp.include_router(router)
+
+    print(f"watcherr bot started (token: ...{token[-6:]})")
+    try:
+        await dp.start_polling(bot)
+    finally:
+        await bot.session.close()
+
+
+if __name__ == "__main__":
+    main()

watcherr-0.1.0/watcherr/config.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_config: WatcherrConfig | None = None
+
+
+@dataclass
+class WatcherrConfig:
+    bot_token: str = ""
+    chat_id: str = ""
+    service_name: str = "app"
+    environment: str = "production"
+    rate_limit_seconds: int = 60
+    enabled: bool = True
+
+
+def configure(
+    bot_token: str | None = None,
+    chat_id: str | None = None,
+    service_name: str | None = None,
+    environment: str | None = None,
+    rate_limit_seconds: int | None = None,
+    enabled: bool | None = None,
+) -> WatcherrConfig:
+    global _config
+
+    _config = WatcherrConfig(
+        bot_token=bot_token or os.getenv("WATCHERR_BOT_TOKEN", ""),
+        chat_id=chat_id or os.getenv("WATCHERR_CHAT_ID", ""),
+        service_name=service_name or os.getenv("WATCHERR_SERVICE_NAME", "app"),
+        environment=environment or os.getenv("WATCHERR_ENVIRONMENT", "production"),
+        rate_limit_seconds=(
+            rate_limit_seconds if rate_limit_seconds is not None else int(os.getenv("WATCHERR_RATE_LIMIT", "60"))
+        ),
+        enabled=enabled if enabled is not None else os.getenv("WATCHERR_ENABLED", "true").lower() == "true",
+    )
+    return _config
+
+
+def get_config() -> WatcherrConfig:
+    global _config
+    if _config is None:
+        _config = configure()
+    return _config

watcherr-0.1.0/watcherr/formatter.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import traceback
+from datetime import datetime, timezone
+
+LEVEL_EMOJI = {
+    "error": "\U0001f534",
+    "warning": "\U0001f7e1",
+    "info": "\U0001f535",
+}
+
+
+def format_message(
+    level: str,
+    message: str,
+    service_name: str,
+    environment: str,
+    exc: BaseException | None = None,
+    extra: dict | None = None,
+) -> str:
+    emoji = LEVEL_EMOJI.get(level, "\u2753")
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    title = f"{emoji} <b>{level.upper()}</b> | <b>{service_name}</b> [{environment}]"
+
+    parts = [title, "", message]
+
+    if exc:
+        tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+        if len(tb) > 2000:
+            tb = tb[:2000] + "\n... (truncated)"
+        parts.append(f"\n<pre>{_escape_html(tb)}</pre>")
+
+    if extra:
+        lines = [f"  <b>{k}</b>: {_escape_html(str(v))}" for k, v in extra.items()]
+        parts.append("\n" + "\n".join(lines))
+
+    parts.append(f"\n<i>{now}</i>")
+
+    return "\n".join(parts)
+
+
+def _escape_html(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")

watcherr-0.1.0/watcherr/integrations/celery_signals.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from watcherr.sender import send_alert, send_warning
+
+
+def setup_celery_alerts() -> None:
+    from celery.signals import task_failure, task_retry
+
+    @task_failure.connect
+    def on_task_failure(sender=None, task_id=None, exception=None, traceback=None, **kwargs):
+        task_name = sender.name if sender else "unknown"
+        send_alert(
+            f"Celery task failed: <b>{task_name}</b>",
+            exc=exception,
+            task_id=task_id or "",
+            task=task_name,
+        )
+
+    @task_retry.connect
+    def on_task_retry(sender=None, request=None, reason=None, **kwargs):
+        task_name = sender.name if sender else "unknown"
+        send_warning(
+            f"Celery task retrying: <b>{task_name}</b>",
+            reason=str(reason) if reason else "",
+            task_id=request.id if request else "",
+            task=task_name,
+        )

watcherr-0.1.0/watcherr/integrations/fastapi_middleware.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from watcherr.sender import send_alert
+
+
+def WatcherrMiddleware(app):
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+    class _Middleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next) -> Response:
+            try:
+                return await call_next(request)
+            except Exception as exc:
+                send_alert(
+                    f"Unhandled exception in {request.method} {request.url.path}",
+                    exc=exc,
+                    method=request.method,
+                    path=request.url.path,
+                    client=request.client.host if request.client else "unknown",
+                )
+                raise
+
+    return _Middleware(app)

watcherr-0.1.0/watcherr/logging_handler.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import logging
+
+from watcherr.sender import send_alert, send_warning
+
+
+class WatcherrHandler(logging.Handler):
+    def __init__(self, level: int = logging.ERROR):
+        super().__init__(level)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            message = self.format(record) if self.formatter else record.getMessage()
+            extra = {
+                "logger": record.name,
+                "module": record.module,
+            }
+
+            if record.funcName:
+                extra["function"] = record.funcName
+
+            exc = record.exc_info[1] if record.exc_info and record.exc_info[1] else None
+
+            if record.levelno >= logging.ERROR:
+                send_alert(message, exc=exc, **extra)
+            elif record.levelno >= logging.WARNING:
+                send_warning(message, exc=exc, **extra)
+        except Exception:
+            self.handleError(record)

watcherr-0.1.0/watcherr/rate_limiter.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import hashlib
+import threading
+import time
+
+
+class RateLimiter:
+    def __init__(self, window_seconds: int = 60):
+        self._window = window_seconds
+        self._seen: dict[str, float] = {}
+        self._lock = threading.Lock()
+
+    def should_send(self, message: str) -> bool:
+        key = hashlib.md5(message.encode()).hexdigest()
+        now = time.monotonic()
+
+        with self._lock:
+            self._cleanup(now)
+            if key in self._seen:
+                return False
+            self._seen[key] = now
+            return True
+
+    def _cleanup(self, now: float) -> None:
+        expired = [k for k, t in self._seen.items() if now - t > self._window]
+        for k in expired:
+            del self._seen[k]
+
+
+_limiter: RateLimiter | None = None
+
+
+def get_rate_limiter(window: int) -> RateLimiter:
+    global _limiter
+    if _limiter is None or _limiter._window != window:
+        _limiter = RateLimiter(window)
+    return _limiter

watcherr-0.1.0/watcherr/sender.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import Any
+
+import httpx
+
+from watcherr.config import WatcherrConfig, get_config
+from watcherr.formatter import format_message
+from watcherr.rate_limiter import get_rate_limiter
+
+logger = logging.getLogger("watcherr")
+
+TELEGRAM_API = "https://api.telegram.org/bot{token}/sendMessage"
+
+
+def _send_sync(text: str, config: WatcherrConfig) -> bool:
+    url = TELEGRAM_API.format(token=config.bot_token)
+    try:
+        resp = httpx.post(url, json={"chat_id": config.chat_id, "text": text, "parse_mode": "HTML"}, timeout=10)
+        if not resp.is_success:
+            logger.warning("watcherr: telegram %s: %s", resp.status_code, resp.text[:200])
+        return resp.is_success
+    except Exception:
+        logger.debug("watcherr: send failed", exc_info=True)
+        return False
+
+
+async def _send_async(text: str, config: WatcherrConfig) -> bool:
+    url = TELEGRAM_API.format(token=config.bot_token)
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                url, json={"chat_id": config.chat_id, "text": text, "parse_mode": "HTML"}, timeout=10
+            )
+            if not resp.is_success:
+                logger.warning("watcherr: telegram %s: %s", resp.status_code, resp.text[:200])
+            return resp.is_success
+    except Exception:
+        logger.debug("watcherr: send failed", exc_info=True)
+        return False
+
+
+def _dispatch(text: str) -> None:
+    config = get_config()
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        loop.create_task(_send_async(text, config))
+    else:
+        threading.Thread(target=_send_sync, args=(text, config), daemon=True).start()
+
+
+def _send(level: str, message: str, exc: BaseException | None = None, extra: dict | None = None) -> None:
+    config = get_config()
+    if not config.enabled or not config.bot_token or not config.chat_id:
+        return
+
+    text = format_message(
+        level=level,
+        message=message,
+        service_name=config.service_name,
+        environment=config.environment,
+        exc=exc,
+        extra=extra,
+    )
+
+    limiter = get_rate_limiter(config.rate_limit_seconds)
+    if not limiter.should_send(text):
+        return
+
+    _dispatch(text)
+
+
+def send_alert(message: str, exc: BaseException | None = None, **extra: Any) -> None:
+    _send("error", message, exc=exc, extra=extra or None)
+
+
+def send_warning(message: str, exc: BaseException | None = None, **extra: Any) -> None:
+    _send("warning", message, exc=exc, extra=extra or None)
+
+
+def send_info(message: str, **extra: Any) -> None:
+    _send("info", message, extra=extra or None)