devalerts 0.1.4__tar.gz → 0.1.5__tar.gz

{devalerts-0.1.4 → devalerts-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devalerts
-Version: 0.1.4
+Version: 0.1.5
 Summary: Send unhandled Python exceptions straight to a Telegram chat. No backend, no account, no database — just your own bot token.
 Keywords: telegram,error-tracking,exception-monitoring,alerts,logging,monitoring,asgi
 Author: sslinNn
@@ -28,8 +28,12 @@ Description-Content-Type: text/markdown
 # devalerts
 
 [![PyPI](https://img.shields.io/pypi/v/devalerts)](https://pypi.org/project/devalerts/)
+[![Downloads](https://img.shields.io/pypi/dm/devalerts)](https://pypi.org/project/devalerts/)
 [![Python versions](https://img.shields.io/pypi/pyversions/devalerts)](https://pypi.org/project/devalerts/)
 [![License: MIT](https://img.shields.io/pypi/l/devalerts)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/sslinNn/devalerts/test.yml?branch=main&label=tests)](https://github.com/sslinNn/devalerts/actions/workflows/test.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![mypy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy-lang.org/)
 
 [Русская версия](README.ru.md)
 
@@ -103,14 +107,7 @@ See what's grouped and what's currently rate-limited:
 uv run devalerts dashboard
 ```
 
-```
-  ID        TYPE          LOCATION                            LAST SEEN TOTAL   STATUS
-  ────────────────────────────────────────────────────────────────────────────────────
-  a1b2c3d4  ValueError    app/orders.py:42                     2m ago       14   ● limited
-  9f8e7d6c  KeyError      app/handlers/webhook.py:88            just now      1   ● sending
-
-  2 error groups, 1 currently rate-limited.
-```
+![devalerts dashboard output](https://raw.githubusercontent.com/sslinNn/devalerts/main/docs/dashboard.svg)
 
 ## Manually reporting a caught exception
 
@@ -151,11 +148,12 @@ 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.
 
-## devalerts vs. a full error tracker
+## Why not Sentry?
 
-If you already run Sentry/Rollbar/etc., keep using it — this isn't a
-replacement. devalerts is for the side project, internal tool, or small
-service that doesn't have (and doesn't want) that infrastructure yet:
+If you already run Sentry/Rollbar/etc., keep using it — devalerts isn't a
+replacement. It's for the side project, internal tool, or small service that
+doesn't have (and doesn't want) that infrastructure: no account to create, no
+SDK to configure, no server to trust — just a bot token you already control.
 
 |                          | devalerts          | Sentry-style tracker |
 |--------------------------|---------------------|-----------------------|
@@ -165,14 +163,63 @@ service that doesn't have (and doesn't want) that infrastructure yet:
 | Grouping / rate limiting | yes, local SQLite   | yes, server-side |
 | Search, trends, releases | no                  | yes |
 
+## FAQ
+
+**Works with FastAPI / Starlette?**
+Yes — use [`ASGIMiddleware`](#fastapi--starlette--any-asgi-app), since the
+default excepthook never sees request errors.
+
+**Works with Docker?**
+Yes, nothing container-specific. Just make sure `~/.devalerts/` (the dedup
+state file) is either writable inside the container or a mounted volume if
+you want dedup state to survive restarts — it self-recreates otherwise.
+
+**Works with threads?**
+Yes — `init()` installs both `sys.excepthook` and `threading.excepthook`.
+
+**Works with Celery / background workers?**
+Yes, `init()` in the worker process the same way as in a web process. For
+tasks you catch yourself, use `report()` or `@devalerts.capture()`.
+
+**Works on Windows / Linux / macOS?**
+Yes — stdlib only (`urllib`, `sqlite3`, `threading`), no OS-specific code
+paths.
+
+## Privacy & Security
+
+- The only network call devalerts makes is to `api.telegram.org` — no
+  telemetry, no analytics, nothing else phones home.
+- No third-party server and no devalerts-run backend — messages go straight
+  from your process to your own Telegram bot.
+- No accounts, no signup, no API key beyond the bot token you create and
+  control yourself.
+- Basic secret redaction only (a few common token/key patterns) — do not
+  rely on this for sensitive production data; scrub what you can before it
+  ever reaches an exception message.
+
 ## What this does NOT do (by design)
 
 - 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.
+
+## Roadmap
+
+- Web dashboard (hosted, optional — the local CLI dashboard stays either way)
+- Slack delivery
+- Discord delivery
+- Email delivery
+
+## Development
+
+    uv sync --group dev
+    uv run pre-commit install
+
+`pre-commit` runs `ruff check`, `ruff format`, and `mypy` before each commit.
+Run the full check manually with:
+
+    uv run pytest
+    uv run pre-commit run --all-files
 
 ## License
 

{devalerts-0.1.4 → devalerts-0.1.5}/README.md

@@ -1,8 +1,12 @@
 # devalerts
 
 [![PyPI](https://img.shields.io/pypi/v/devalerts)](https://pypi.org/project/devalerts/)
+[![Downloads](https://img.shields.io/pypi/dm/devalerts)](https://pypi.org/project/devalerts/)
 [![Python versions](https://img.shields.io/pypi/pyversions/devalerts)](https://pypi.org/project/devalerts/)
 [![License: MIT](https://img.shields.io/pypi/l/devalerts)](LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/sslinNn/devalerts/test.yml?branch=main&label=tests)](https://github.com/sslinNn/devalerts/actions/workflows/test.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![mypy](https://img.shields.io/badge/mypy-checked-blue)](https://mypy-lang.org/)
 
 [Русская версия](README.ru.md)
 
@@ -76,14 +80,7 @@ See what's grouped and what's currently rate-limited:
 uv run devalerts dashboard
 ```
 
-```
-  ID        TYPE          LOCATION                            LAST SEEN TOTAL   STATUS
-  ────────────────────────────────────────────────────────────────────────────────────
-  a1b2c3d4  ValueError    app/orders.py:42                     2m ago       14   ● limited
-  9f8e7d6c  KeyError      app/handlers/webhook.py:88            just now      1   ● sending
-
-  2 error groups, 1 currently rate-limited.
-```
+![devalerts dashboard output](https://raw.githubusercontent.com/sslinNn/devalerts/main/docs/dashboard.svg)
 
 ## Manually reporting a caught exception
 
@@ -124,11 +121,12 @@ 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.
 
-## devalerts vs. a full error tracker
+## Why not Sentry?
 
-If you already run Sentry/Rollbar/etc., keep using it — this isn't a
-replacement. devalerts is for the side project, internal tool, or small
-service that doesn't have (and doesn't want) that infrastructure yet:
+If you already run Sentry/Rollbar/etc., keep using it — devalerts isn't a
+replacement. It's for the side project, internal tool, or small service that
+doesn't have (and doesn't want) that infrastructure: no account to create, no
+SDK to configure, no server to trust — just a bot token you already control.
 
 |                          | devalerts          | Sentry-style tracker |
 |--------------------------|---------------------|-----------------------|
@@ -138,14 +136,63 @@ service that doesn't have (and doesn't want) that infrastructure yet:
 | Grouping / rate limiting | yes, local SQLite   | yes, server-side |
 | Search, trends, releases | no                  | yes |
 
+## FAQ
+
+**Works with FastAPI / Starlette?**
+Yes — use [`ASGIMiddleware`](#fastapi--starlette--any-asgi-app), since the
+default excepthook never sees request errors.
+
+**Works with Docker?**
+Yes, nothing container-specific. Just make sure `~/.devalerts/` (the dedup
+state file) is either writable inside the container or a mounted volume if
+you want dedup state to survive restarts — it self-recreates otherwise.
+
+**Works with threads?**
+Yes — `init()` installs both `sys.excepthook` and `threading.excepthook`.
+
+**Works with Celery / background workers?**
+Yes, `init()` in the worker process the same way as in a web process. For
+tasks you catch yourself, use `report()` or `@devalerts.capture()`.
+
+**Works on Windows / Linux / macOS?**
+Yes — stdlib only (`urllib`, `sqlite3`, `threading`), no OS-specific code
+paths.
+
+## Privacy & Security
+
+- The only network call devalerts makes is to `api.telegram.org` — no
+  telemetry, no analytics, nothing else phones home.
+- No third-party server and no devalerts-run backend — messages go straight
+  from your process to your own Telegram bot.
+- No accounts, no signup, no API key beyond the bot token you create and
+  control yourself.
+- Basic secret redaction only (a few common token/key patterns) — do not
+  rely on this for sensitive production data; scrub what you can before it
+  ever reaches an exception message.
+
 ## What this does NOT do (by design)
 
 - 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.
+
+## Roadmap
+
+- Web dashboard (hosted, optional — the local CLI dashboard stays either way)
+- Slack delivery
+- Discord delivery
+- Email delivery
+
+## Development
+
+    uv sync --group dev
+    uv run pre-commit install
+
+`pre-commit` runs `ruff check`, `ruff format`, and `mypy` before each commit.
+Run the full check manually with:
+
+    uv run pytest
+    uv run pre-commit run --all-files
 
 ## License
 

{devalerts-0.1.4 → devalerts-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devalerts"
-version = "0.1.4"
+version = "0.1.5"
 description = "Send unhandled Python exceptions straight to a Telegram chat. No backend, no account, no database — just your own bot token."
 readme = "README.md"
 license = "MIT"
@@ -43,8 +43,19 @@ Repository = "https://github.com/sslinNn/devalerts"
 devalerts = "devalerts.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.10.2,<0.11.0"]
+requires = ["uv_build>=0.10.2,<0.12.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
-dev = []
+dev = [
+    "mypy>=1.19.1",
+    "pre-commit>=4.3.0",
+    "pytest>=8.4.2",
+    "ruff>=0.15.22",
+]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint]
+extend-select = ["BLE"]

{devalerts-0.1.4 → devalerts-0.1.5}/src/devalerts/__init__.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import contextlib
 import sys
 import threading
+from types import TracebackType
+from typing import Callable, Literal, Optional, TypedDict
 
 from ._alert import _format_alert, _redact
 from ._store import _DEFAULT_RATE_LIMIT_SECONDS, _fingerprint, _should_send
@@ -12,19 +14,43 @@ from ._telegram import _send_telegram_message
 
 __all__: list[str] = ["init", "report", "capture", "ASGIMiddleware"]
 
-_state = {
+_ExceptHook = Callable[
+    [type[BaseException], BaseException, Optional[TracebackType]], object
+]
+_ThreadingExceptHook = Callable[[threading.ExceptHookArgs], object]
+
+
+class _State(TypedDict):
+    bot_token: str | None
+    chat_id: int | str | None
+    redact: bool
+    rate_limit_seconds: int
+    # Seeded with the real default hooks below (never None) -- _excepthook/
+    # _threading_excepthook can only ever fire after init() has replaced
+    # sys.excepthook/threading.excepthook, by which point these are always
+    # set, so keeping them non-Optional avoids an unreachable None check.
+    prev_excepthook: _ExceptHook
+    prev_threading_excepthook: _ThreadingExceptHook
+
+
+_state: _State = {
     "bot_token": None,
     "chat_id": None,
     "redact": True,
     "rate_limit_seconds": _DEFAULT_RATE_LIMIT_SECONDS,
-    "prev_excepthook": None,
-    "prev_threading_excepthook": None,
+    "prev_excepthook": sys.excepthook,
+    "prev_threading_excepthook": threading.excepthook,
 }
 
 
 def _send_exception(exc_type, exc_value, tb) -> None:
+    if _state["bot_token"] is None or _state["chat_id"] is None:
+        print("devalerts: init() was not called, dropping alert", file=sys.stderr)
+        return
     fingerprint, location = _fingerprint(exc_type, tb)
-    send, skipped = _should_send(fingerprint, exc_type.__name__, location, _state["rate_limit_seconds"])
+    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)
@@ -38,7 +64,10 @@ def _excepthook(exc_type, exc_value, tb) -> None:
         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)
+            print(
+                f"devalerts: internal error while sending alert: {error}",
+                file=sys.stderr,
+            )
     _state["prev_excepthook"](exc_type, exc_value, tb)
 
 
@@ -46,13 +75,15 @@ 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)
+        print(
+            f"devalerts: internal error while sending alert: {error}", file=sys.stderr
+        )
     _state["prev_threading_excepthook"](args)
 
 
 def init(
     bot_token: str,
-    chat_id,
+    chat_id: int | str,
     *,
     redact: bool = True,
     rate_limit_seconds: int = _DEFAULT_RATE_LIMIT_SECONDS,
@@ -78,7 +109,9 @@ def report(exc: BaseException | None = None) -> None:
     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")
+            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)
@@ -92,7 +125,7 @@ class capture(contextlib.ContextDecorator):
     def __enter__(self) -> "capture":
         return self
 
-    def __exit__(self, exc_type, exc_value, tb) -> bool:
+    def __exit__(self, exc_type, exc_value, tb) -> Literal[False]:
         if exc_type is not None:
             _send_exception(exc_type, exc_value, tb)
         return False

{devalerts-0.1.4 → devalerts-0.1.5}/src/devalerts/_alert.py

@@ -9,7 +9,7 @@ _MAX_MESSAGE_LENGTH = 4096
 
 
 def _format_alert(exc_type, exc_value, tb, skipped: int = 0) -> str:
-    header = f"\U0001F534 {exc_type.__name__}: {exc_value}"
+    header = f"\U0001f534 {exc_type.__name__}: {exc_value}"
     if skipped:
         header += f"\n⚠️ Повторилась ещё {skipped} раз(а) с последнего алерта"
     body = "".join(traceback.format_exception(exc_type, exc_value, tb))

{devalerts-0.1.4 → devalerts-0.1.5}/src/devalerts/_store.py

@@ -42,7 +42,9 @@ def _get_connection() -> sqlite3.Connection:
     return conn
 
 
-def _should_send(fingerprint: str, exc_type_name: str, location: str, rate_limit_seconds: int) -> tuple[bool, int]:
+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()
@@ -79,12 +81,18 @@ def _should_send(fingerprint: str, exc_type_name: str, location: str, rate_limit
                         """,
                         (now, fingerprint),
                     )
-                conn.execute("DELETE FROM error_groups WHERE last_seen < ?", (now - _RETENTION_SECONDS,))
+                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)
+        print(
+            f"devalerts: dedup/rate-limit state error, sending anyway: {error}",
+            file=sys.stderr,
+        )
         return True, 0

{devalerts-0.1.4 → devalerts-0.1.5}/src/devalerts/_telegram.py

@@ -10,7 +10,7 @@ import urllib.request
 _TIMEOUT_SECONDS = 5
 
 
-def _send_telegram_message(bot_token: str, chat_id, text: str) -> None:
+def _send_telegram_message(bot_token: str, chat_id: int | str, 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(

{devalerts-0.1.4 → devalerts-0.1.5}/src/devalerts/cli.py

@@ -118,7 +118,9 @@ def _dashboard() -> int:
         # 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
+        in_window = (
+            last_sent is not None and now - last_sent < _DEFAULT_RATE_LIMIT_SECONDS
+        )
         if in_window:
             limited_count += 1
             status = style.red(f"{dot_char} limited")