devalerts 0.1.0__py3-none-any.whl

devalerts/__init__.py

@@ -0,0 +1,270 @@
+"""Throwaway prototype: send unhandled Python exceptions straight to a Telegram chat."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import re
+import sqlite3
+import sys
+import threading
+import time
+import traceback
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+__all__: list[str] = ["init", "report", "capture", "ASGIMiddleware"]
+
+_MAX_MESSAGE_LENGTH = 4096
+_DB_PATH = Path.home() / ".devalerts" / "state.db"
+_RETENTION_SECONDS = 7 * 24 * 3600
+_DEFAULT_RATE_LIMIT_SECONDS = 300
+
+
+def _format_alert(exc_type, exc_value, tb, skipped: int = 0) -> str:
+    header = f"\U0001F534 {exc_type.__name__}: {exc_value}"
+    if skipped:
+        header += f"\n⚠️ Повторилась ещё {skipped} раз(а) с последнего алерта"
+    body = "".join(traceback.format_exception(exc_type, exc_value, tb))
+    message = f"{header}\n\n{body}"
+    if len(message) <= _MAX_MESSAGE_LENGTH:
+        return message
+    marker = "\n\n...(truncated)...\n"
+    # ponytail: header itself can exceed the limit if exc_value's str() is huge
+    # (e.g. a validation error echoing a large payload) — keep can go negative,
+    # so clamp it and hard-truncate the final result as a backstop guarantee.
+    keep = max(_MAX_MESSAGE_LENGTH - len(header) - len(marker), 0)
+    truncated = f"{header}{marker}{body[-keep:]}" if keep else header
+    return truncated[:_MAX_MESSAGE_LENGTH]
+
+
+# ponytail: fixed pattern list, not exhaustive — catches common
+# token/key shapes only. Upgrade to entropy-based detection if
+# real users report leaked secrets slipping through.
+_REDACT_PATTERNS = [
+    (re.compile(r"AKIA[0-9A-Z]{16}"), "[REDACTED]"),
+    (re.compile(r"Bearer\s+[A-Za-z0-9\-_.]+", re.IGNORECASE), "Bearer [REDACTED]"),
+    (
+        re.compile(r"(?i)(api[_-]?key|secret|token|password)\s*[=:]\s*\S+"),
+        r"\1=[REDACTED]",
+    ),
+]
+
+
+def _redact(text: str) -> str:
+    for pattern, replacement in _REDACT_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+_TIMEOUT_SECONDS = 5
+
+
+def _send_telegram_message(bot_token: str, chat_id, text: str) -> None:
+    url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
+    payload = json.dumps({"chat_id": chat_id, "text": text}).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        urllib.request.urlopen(request, timeout=_TIMEOUT_SECONDS)
+    except (urllib.error.URLError, OSError, ValueError) as error:
+        print(f"devalerts: failed to send Telegram alert: {error}", file=sys.stderr)
+
+
+_state = {
+    "bot_token": None,
+    "chat_id": None,
+    "redact": True,
+    "rate_limit_seconds": _DEFAULT_RATE_LIMIT_SECONDS,
+    "prev_excepthook": None,
+    "prev_threading_excepthook": None,
+}
+
+
+def _fingerprint(exc_type, tb) -> tuple[str, str]:
+    frames = traceback.extract_tb(tb)
+    location = f"{frames[-1].filename}:{frames[-1].lineno}" if frames else "unknown"
+    raw = f"{exc_type.__name__}:{location}"
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16], location
+
+
+def _get_connection() -> sqlite3.Connection:
+    _DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(_DB_PATH, timeout=5)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS error_groups (
+            fingerprint TEXT PRIMARY KEY,
+            exc_type TEXT NOT NULL,
+            location TEXT NOT NULL,
+            first_seen REAL NOT NULL,
+            last_seen REAL NOT NULL,
+            last_sent REAL,
+            count_since_last_sent INTEGER NOT NULL DEFAULT 0,
+            total_count INTEGER NOT NULL DEFAULT 0
+        )
+        """
+    )
+    return conn
+
+
+def _should_send(fingerprint: str, exc_type_name: str, location: str, rate_limit_seconds: int) -> tuple[bool, int]:
+    now = time.time()
+    try:
+        conn = _get_connection()
+        try:
+            with conn:
+                row = conn.execute(
+                    "SELECT last_sent, count_since_last_sent FROM error_groups WHERE fingerprint = ?",
+                    (fingerprint,),
+                ).fetchone()
+                if row is None or row[0] is None or now - row[0] >= rate_limit_seconds:
+                    send, skipped = True, (row[1] if row else 0)
+                    conn.execute(
+                        """
+                        INSERT INTO error_groups
+                            (fingerprint, exc_type, location, first_seen, last_seen,
+                             last_sent, count_since_last_sent, total_count)
+                        VALUES (?, ?, ?, ?, ?, ?, 0, 1)
+                        ON CONFLICT(fingerprint) DO UPDATE SET
+                            last_seen = excluded.last_seen,
+                            last_sent = excluded.last_sent,
+                            count_since_last_sent = 0,
+                            total_count = total_count + 1
+                        """,
+                        (fingerprint, exc_type_name, location, now, now, now),
+                    )
+                else:
+                    send, skipped = False, 0
+                    conn.execute(
+                        """
+                        UPDATE error_groups
+                        SET last_seen = ?, count_since_last_sent = count_since_last_sent + 1,
+                            total_count = total_count + 1
+                        WHERE fingerprint = ?
+                        """,
+                        (now, fingerprint),
+                    )
+                conn.execute("DELETE FROM error_groups WHERE last_seen < ?", (now - _RETENTION_SECONDS,))
+            return send, skipped
+        finally:
+            conn.close()
+    except (sqlite3.Error, OSError) as error:
+        # ponytail: dedup/rate-limit state must never block an alert -- fail
+        # open (send, as if this were the first occurrence) on any DB error.
+        print(f"devalerts: dedup/rate-limit state error, sending anyway: {error}", file=sys.stderr)
+        return True, 0
+
+
+def _send_exception(exc_type, exc_value, tb) -> None:
+    fingerprint, location = _fingerprint(exc_type, tb)
+    send, skipped = _should_send(fingerprint, exc_type.__name__, location, _state["rate_limit_seconds"])
+    if not send:
+        return
+    message = _format_alert(exc_type, exc_value, tb, skipped=skipped)
+    if _state["redact"]:
+        message = _redact(message)
+    _send_telegram_message(_state["bot_token"], _state["chat_id"], message)
+
+
+def _excepthook(exc_type, exc_value, tb) -> None:
+    if exc_type is not KeyboardInterrupt:
+        try:
+            _send_exception(exc_type, exc_value, tb)
+        except Exception as error:  # noqa: BLE001 - crash handler must never raise
+            print(f"devalerts: internal error while sending alert: {error}", file=sys.stderr)
+    _state["prev_excepthook"](exc_type, exc_value, tb)
+
+
+def _threading_excepthook(args) -> None:
+    try:
+        _send_exception(args.exc_type, args.exc_value, args.exc_traceback)
+    except Exception as error:  # noqa: BLE001
+        print(f"devalerts: internal error while sending alert: {error}", file=sys.stderr)
+    _state["prev_threading_excepthook"](args)
+
+
+def init(
+    bot_token: str,
+    chat_id,
+    *,
+    redact: bool = True,
+    rate_limit_seconds: int = _DEFAULT_RATE_LIMIT_SECONDS,
+) -> None:
+    """Install a global exception hook that sends unhandled exceptions to Telegram."""
+    _state["bot_token"] = bot_token
+    _state["chat_id"] = chat_id
+    _state["redact"] = redact
+    _state["rate_limit_seconds"] = rate_limit_seconds
+    # ponytail: guard against calling init() twice capturing our own hook as
+    # "previous" -- that would make _excepthook chain to itself and recurse
+    # forever on the next crash, violating "must never raise".
+    if sys.excepthook is not _excepthook:
+        _state["prev_excepthook"] = sys.excepthook
+    if threading.excepthook is not _threading_excepthook:
+        _state["prev_threading_excepthook"] = threading.excepthook
+    sys.excepthook = _excepthook
+    threading.excepthook = _threading_excepthook
+
+
+def report(exc: BaseException | None = None) -> None:
+    """Manually send a caught exception to Telegram."""
+    if exc is None:
+        exc_type, exc_value, tb = sys.exc_info()
+        if exc_type is None:
+            raise RuntimeError("report() requires an active exception or an exc argument")
+    else:
+        exc_type, exc_value, tb = type(exc), exc, exc.__traceback__
+    _send_exception(exc_type, exc_value, tb)
+
+
+class capture(contextlib.ContextDecorator):
+    """Context manager / decorator: report any exception raised inside the block or
+    function, then re-raise it. Use ``@capture()`` on a function instead of wrapping
+    its body in a manual ``try/except`` or ``with`` block."""
+
+    def __enter__(self) -> "capture":
+        return self
+
+    def __exit__(self, exc_type, exc_value, tb) -> bool:
+        if exc_type is not None:
+            _send_exception(exc_type, exc_value, tb)
+        return False
+
+
+class ASGIMiddleware:
+    """ASGI middleware for FastAPI/Starlette (or any ASGI app): report any exception
+    that escapes a request, then re-raise it so the framework's own error handling
+    still runs unchanged.
+
+    Usage::
+
+        app.add_middleware(devalerts.ASGIMiddleware)
+
+    Only exceptions that actually reach here (unhandled server errors) get reported —
+    routing 404s and raised ``HTTPException``s are already turned into responses by
+    the framework before this middleware sees them, same as Sentry's ASGI integration.
+    """
+
+    def __init__(self, app) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send) -> None:
+        try:
+            await self.app(scope, receive, send)
+        except Exception:
+            exc_type, exc_value, tb = sys.exc_info()
+            # ponytail: fire-and-forget in a thread -- _send_exception is a
+            # blocking network call; awaiting it here would stall the event
+            # loop (and the error response) for up to _TIMEOUT_SECONDS.
+            threading.Thread(
+                target=_send_exception, args=(exc_type, exc_value, tb), daemon=True
+            ).start()
+            raise

devalerts/cli.py

@@ -0,0 +1,67 @@
+"""CLI: `devalerts dashboard` reports grouped/rate-limited errors from the local state DB."""
+
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import sys
+import time
+from datetime import datetime
+
+from . import _DB_PATH, _DEFAULT_RATE_LIMIT_SECONDS
+
+_LOCATION_WIDTH = 30
+
+
+def _truncate(text: str, width: int) -> str:
+    """Keep the tail (file:line matters more than leading directories)."""
+    return text if len(text) <= width else "…" + text[-(width - 1):]
+
+
+def _dashboard() -> int:
+    if not _DB_PATH.exists():
+        print("No errors recorded yet.")
+        return 0
+
+    conn = sqlite3.connect(_DB_PATH)
+    try:
+        rows = conn.execute(
+            "SELECT fingerprint, exc_type, location, last_seen, last_sent, total_count "
+            "FROM error_groups ORDER BY last_seen DESC"
+        ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        print("No errors recorded yet.")
+        return 0
+
+    now = time.time()
+    print(f"{'FINGERPRINT':<18}{'TYPE':<16}{'LOCATION':<30}{'LAST SEEN':<21}{'TOTAL':>7}  IN WINDOW")
+    for fingerprint, exc_type, location, last_seen, last_sent, total_count in rows:
+        last_seen_str = datetime.fromtimestamp(last_seen).strftime("%Y-%m-%d %H:%M:%S")
+        # ponytail: the dashboard runs in a separate process from init(), so it
+        # doesn't know the app's actual rate_limit_seconds -- uses the library
+        # default. Upgrade to persisting the configured value if apps commonly
+        # override it.
+        in_window = last_sent is not None and now - last_sent < _DEFAULT_RATE_LIMIT_SECONDS
+        print(
+            f"{fingerprint:<18}{exc_type:<16}{location:<30}{last_seen_str:<21}"
+            f"{total_count:>7}  {'yes' if in_window else 'no'}"
+        )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="devalerts")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("dashboard", help="Show grouped/rate-limited errors")
+    args = parser.parse_args(argv)
+
+    if args.command == "dashboard":
+        return _dashboard()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

devalerts-0.1.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.3
+Name: devalerts
+Version: 0.1.0
+Summary: Add your description here
+Author: sslinNn
+Author-email: sslinNn <morison1991@mail.ru>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# devalerts (throwaway prototype)
+
+[Русская версия](README.ru.md)
+
+Send unhandled Python exceptions straight to a Telegram chat. No backend,
+no account, no database — just your own bot token.
+
+## Install
+
+    uv add git+https://github.com/<you>/<repo>.git
+
+(or `pip install git+https://github.com/<you>/<repo>.git` if you're not using uv)
+
+## Usage
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) and get its token.
+2. Message your bot once (or add it to a group) so it's allowed to message you back.
+3. Get your chat id — message [@userinfobot](https://t.me/userinfobot), or call
+   `https://api.telegram.org/bot<TOKEN>/getUpdates` after step 2 and read `message.chat.id`.
+4. In your app, as early as possible:
+
+```python
+import devalerts
+
+devalerts.init(bot_token="123456:ABC-DEF...", chat_id=123456789)
+```
+
+That's it — any unhandled exception (including ones raised in threads) now
+also lands in your Telegram chat.
+
+## Grouping, rate limiting, and the dashboard
+
+Exceptions are grouped by fingerprint (exception type + file + line where it
+was raised) in a local SQLite file (`~/.devalerts/state.db`). Each group
+sends at most one Telegram message per `rate_limit_seconds` (default 300);
+repeats inside that window are counted but not sent, and the next message
+for that group says how many were skipped. Old groups (untouched for 7 days)
+are pruned automatically. Configure the window via `init()`:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789, rate_limit_seconds=60)
+```
+
+See what's grouped and what's currently rate-limited:
+
+```
+uv run devalerts dashboard
+```
+
+## Manually reporting a caught exception
+
+```python
+try:
+    risky_call()
+except Exception:
+    devalerts.report()  # sends the currently-handled exception
+```
+
+or:
+
+```python
+with devalerts.capture():
+    risky_call()  # reports on exception, then re-raises
+```
+
+`capture` also works as a decorator, so you don't need to touch a function's
+body at all:
+
+```python
+@devalerts.capture()
+def risky_call():
+    ...
+```
+
+## FastAPI / Starlette / any ASGI app
+
+`init()`'s excepthook won't see request errors — the framework already catches
+them internally to return a 500 response, so nothing "unhandled" ever reaches
+the process. Use the ASGI middleware instead:
+
+```python
+app.add_middleware(devalerts.ASGIMiddleware)
+```
+
+Only exceptions that actually escape as server errors get reported — routing
+404s and raised `HTTPException`s are already turned into responses by the
+framework before the middleware sees them.
+
+## What this does NOT do (by design — it's a throwaway prototype)
+
+- Grouping/rate limiting is local and in-process only (SQLite file, no
+  server) — the dashboard is a CLI table, not a web UI.
+- No backend, no accounts — each user runs their own bot.
+- Basic secret redaction only (a few common token patterns) — do not rely
+  on this for sensitive production data.
+- No automated test suite — verified manually during implementation only.

devalerts-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+devalerts/__init__.py,sha256=RYebKii-DW-We-CcgmyV9jwL-vfFO4gxqyhDNwmmf4w,10282
+devalerts/cli.py,sha256=h--jYC86_o7LPLMGOhgsL0eFUT3wCRPcuNIgtbyl_I0,2200
+devalerts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devalerts-0.1.0.dist-info/WHEEL,sha256=QnGI6l9Psotmz6XrseXTYT5jnZRJeTk4SwJP4aLtfdI,80
+devalerts-0.1.0.dist-info/entry_points.txt,sha256=G45eB-0ASM1EKddRxB6weifD1MomdTTkqNQKjuGztQc,50
+devalerts-0.1.0.dist-info/METADATA,sha256=JE0vsU34T208TJsAqYvZh-XZBi8g4QsN85MvpWkaeN4,3198
+devalerts-0.1.0.dist-info/RECORD,,

devalerts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.2
+Root-Is-Purelib: true
+Tag: py3-none-any

devalerts-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+devalerts = devalerts.cli:main
+