bugsradar 3.0.0__py3-none-any.whl

bugsradar/__init__.py

@@ -0,0 +1,169 @@
+"""
+BugsRadar: errors of your Python application in Telegram, Discord or Pushover.
+
+    import bugsradar
+    bugsradar.init(api_key=os.environ["BUGSRADAR_KEY"])
+
+Documentation: https://bugsradar.com/docs/python/
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import threading
+import time
+from datetime import timedelta
+from typing import Any, Mapping, Optional, Union
+
+from . import _client, _hooks, _logging
+from ._client import Client
+from ._logging import LoggingHandler
+from ._version import __version__
+
+__all__ = ["init", "send", "send_exception", "flush", "LoggingHandler", "__version__"]
+
+Seconds = Union[float, timedelta]
+
+_init_lock = threading.Lock()
+_exit_hook_registered = False
+_last_not_initialized_warning = 0.0
+
+
+def init(
+    api_key: str,
+    *,
+    environment: Optional[str] = None,
+    host: Optional[str] = None,
+    app_version: Optional[str] = None,
+    logging_level: Union[int, str, None] = logging.ERROR,
+    capture_uncaught: bool = True,
+    repeat_interval: Seconds = 5.0,
+    queue_capacity: int = 1000,
+    shutdown_timeout: Seconds = 5.0,
+    request_timeout: Seconds = 15.0,
+    api_url: Optional[str] = None,
+) -> None:
+    """
+    Connects BugsRadar to logging and to uncaught exceptions; the application's logging setup stays as it is.
+    Call it once, at the start of the program; a second call replaces the settings of the first.
+    An empty api_key or an unknown logging_level raises ValueError.
+    """
+    global _exit_hook_registered
+
+    level = None if logging_level is None else _logging.level_number(logging_level)
+    client = Client(
+        api_key,
+        environment=environment,
+        host=host,
+        app_version=app_version,
+        repeat_interval=repeat_interval,
+        queue_capacity=queue_capacity,
+        shutdown_timeout=shutdown_timeout,
+        request_timeout=request_timeout,
+        api_url=api_url,
+    )
+
+    with _init_lock:
+        previous = _client.set_default(client)
+        if previous is not None:
+            # Whatever the previous client still holds goes out from its own thread.
+            previous.close()
+
+        _logging.install(level)
+        _hooks.install(capture_uncaught)
+
+        if not _exit_hook_registered:
+            _exit_hook_registered = True
+            atexit.register(_flush_at_exit)
+
+
+def send(
+    *,
+    exception: Any = None,
+    level: Union[str, int, None] = None,
+    message_template: Optional[str] = None,
+    message: Optional[str] = None,
+    properties: Optional[Mapping[str, Any]] = None,
+    category: Optional[str] = None,
+    module: Optional[str] = None,
+    fingerprint: Optional[str] = None,
+    environment: Optional[str] = None,
+    host: Optional[str] = None,
+    app_version: Optional[str] = None,
+) -> None:
+    """
+    Queues an event and returns at once. Never raises.
+
+    message_template is the text with placeholders, the same for every occurrence ("Order {order_id} failed"): it
+    groups repeats. fingerprint is your own grouping key. level: "error" by default, or "critical", "warning",
+    "information", "debug", "trace", or a logging level.
+    """
+    client = _client.get_default()
+    if client is None:
+        _warn_not_initialized()
+        return
+    client._send(
+        "Direct",
+        exception=exception,
+        level=level,
+        message_template=message_template,
+        message=message,
+        properties=properties,
+        category=category,
+        module=module,
+        fingerprint=fingerprint,
+        environment=environment,
+        host=host,
+        app_version=app_version,
+    )
+
+
+def send_exception(
+    error: BaseException,
+    *,
+    level: Union[str, int, None] = None,
+    message_template: Optional[str] = None,
+    message: Optional[str] = None,
+    properties: Optional[Mapping[str, Any]] = None,
+    category: Optional[str] = None,
+    module: Optional[str] = None,
+    fingerprint: Optional[str] = None,
+) -> None:
+    """Queues the exception, with its traceback and chain, and returns at once. Never raises."""
+    send(
+        exception=error,
+        level=level,
+        message_template=message_template,
+        message=message,
+        properties=properties,
+        category=category,
+        module=module,
+        fingerprint=fingerprint,
+    )
+
+
+def flush(timeout: Optional[Seconds] = None) -> bool:
+    """
+    Waits until everything queued so far has left, at most `timeout` seconds (shutdown_timeout by default).
+    True when the queue drained in time.
+    """
+    client = _client.get_default()
+    if client is None:
+        return True
+    return client.flush(timeout)
+
+
+def _flush_at_exit() -> None:
+    client = _client.get_default()
+    if client is not None:
+        client.flush()
+
+
+def _warn_not_initialized() -> None:
+    global _last_not_initialized_warning
+    now = time.monotonic()
+    if _last_not_initialized_warning and now - _last_not_initialized_warning < _client.WARNING_INTERVAL:
+        return
+    _last_not_initialized_warning = now
+    _client.log.warning("BugsRadar: call bugsradar.init() first; the event was not sent")

bugsradar/_client.py

@@ -0,0 +1,448 @@
+"""The client: a queue, a daemon thread and the rules of delivery shared with the .NET and Node.js packages."""
+
+from __future__ import annotations
+
+import logging
+import os
+import socket
+import ssl
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+import weakref
+from collections import deque
+from datetime import timedelta
+from typing import Any, Deque, Dict, Optional, Tuple
+
+from ._duplicates import DuplicateFilter
+from ._event import Event, capture, level_name, repeat_key, stringify_properties, text, utc
+from ._payload import serialize
+from ._version import __version__
+
+DEFAULT_API_URL = "https://api.bugsradar.com/api/v3/python/SendException"
+# The server learns the package version from User-Agent.
+USER_AGENT = "BugsRadar.Python/" + __version__
+MAX_ATTEMPTS = 3
+RETRY_DELAYS = (1.0, 5.0, 30.0)
+DEFAULT_RETRY_AFTER = 5.0
+WARNING_INTERVAL = 600.0
+# How often the sending thread looks at the repeat windows when the queue is empty.
+WINDOW_CHECK = 1.0
+
+# The package's own diagnostics. Records of this logger are never sent: a delivery problem never becomes an event.
+log = logging.getLogger("bugsradar")
+
+_DELIVERED, _RETRY, _RATE_LIMITED, _DROP = range(4)
+
+_clients: "weakref.WeakSet[Client]" = weakref.WeakSet()
+_start_lock = threading.Lock()
+
+
+class _Item:
+    """An event to send, or the marker flush() puts behind everything queued so far."""
+
+    __slots__ = ("event", "count", "marker")
+
+    def __init__(self, event: Optional[Event], count: int, marker: Optional[threading.Event]) -> None:
+        self.event = event
+        self.count = count
+        self.marker = marker
+
+
+class _Window:
+    __slots__ = ("opened_at", "count", "latest")
+
+    def __init__(self, opened_at: float, latest: Event) -> None:
+        self.opened_at = opened_at
+        self.count = 0
+        self.latest = latest
+
+
+class Client:
+    """
+    The one place events leave the process. Sending never waits for the network: the event is checked for
+    duplicates, folded with repeats of the same error and queued; a daemon thread posts to the server, respects 429
+    and retries transient failures. flush() waits for the queue, at most shutdown_timeout.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        environment: Optional[str] = None,
+        host: Optional[str] = None,
+        app_version: Optional[str] = None,
+        repeat_interval: float = 5.0,
+        queue_capacity: int = 1000,
+        shutdown_timeout: float = 5.0,
+        request_timeout: float = 15.0,
+        api_url: Optional[str] = None,
+    ) -> None:
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("BugsRadar: api_key is required")
+
+        self.api_key = api_key.strip()
+        self.api_url = text(api_url) or DEFAULT_API_URL
+        self.environment = text(environment)
+        self.host = _hostname() if host is None else text(host)
+        self.app_version = text(app_version)
+        self.repeat_interval = _number(repeat_interval, 5.0)
+        self.queue_capacity = int(_number(queue_capacity, 1000))
+        self.shutdown_timeout = _number(shutdown_timeout, 5.0)
+        self.request_timeout = _number(request_timeout, 15.0)
+
+        self._paused_until = 0.0
+        self._gone = False
+        self._deprecation_warned = False
+        self._last_warning: Dict[str, float] = {}
+        # Built by the sending thread before its first request; None is urllib's default.
+        self._tls: Optional[ssl.SSLContext] = None
+        self._tls_ready = False
+        self._reset()
+        _clients.add(self)
+        self._start()
+
+    def _reset(self) -> None:
+        """Fresh queue, locks and windows: at creation, and in the child after a fork, where the thread is gone."""
+        self._condition = threading.Condition()
+        self._queue: Deque[_Item] = deque()
+        self._pending = 0
+        self._closing = False
+        self._windows: Dict[str, _Window] = {}
+        self._windows_lock = threading.Lock()
+        self._duplicates = DuplicateFilter()
+        self._thread: Optional[threading.Thread] = None
+        self._thread_pid: Optional[int] = None
+
+    def _send(
+        self,
+        source: str,
+        *,
+        exception: Any = None,
+        level: Any = None,
+        message_template: Any = None,
+        message: Any = None,
+        properties: Any = None,
+        category: Any = None,
+        environment: Any = None,
+        host: Any = None,
+        app_version: Any = None,
+        module: Any = None,
+        fingerprint: Any = None,
+        timestamp: Any = None,
+    ) -> None:
+        """Entry point of init's functions, the logging handler and the hooks. Never raises."""
+        try:
+            if self._gone or self._closing:
+                return
+
+            level = level_name(level)
+            message_template = text(message_template)
+            message = text(message)
+            # Nothing to show: no exception, no text, no template.
+            if exception is None and message is None and message_template is None:
+                return
+            if self._duplicates.is_duplicate(exception, level, message_template, message, time.monotonic()):
+                return
+
+            self._enqueue(
+                Event(
+                    timestamp=utc(timestamp),
+                    level=level,
+                    message_template=message_template,
+                    message=message,
+                    properties=stringify_properties(properties),
+                    exceptions=capture(exception),
+                    category=text(category),
+                    environment=text(environment) or self.environment,
+                    host=text(host) or self.host,
+                    app_version=text(app_version) or self.app_version,
+                    module=text(module),
+                    fingerprint=text(fingerprint),
+                    source=source,
+                )
+            )
+        except Exception:
+            self._warn("queue", "BugsRadar: failed to queue an event", exc_info=True)
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        """
+        Waits until everything queued so far has left, at most `timeout` seconds (shutdown_timeout by default).
+        True when the queue drained in time.
+        """
+        limit = self.shutdown_timeout if timeout is None else _number(timeout, self.shutdown_timeout)
+        if threading.current_thread() is self._thread:
+            return False
+        self._flush_windows(True)
+
+        marker = threading.Event()
+        with self._condition:
+            self._queue.append(_Item(None, 0, marker))
+            self._condition.notify()
+        try:
+            self._start()
+        except Exception:
+            return False
+        return marker.wait(limit)
+
+    def close(self) -> None:
+        """Takes no new events; the thread sends what is queued and ends. Does not wait."""
+        self._flush_windows(True)
+        with self._condition:
+            self._closing = True
+            self._condition.notify()
+
+    def _enqueue(self, event: Event) -> None:
+        key = repeat_key(event)
+        with self._windows_lock:
+            window = self._windows.get(key)
+            if window is not None:
+                # A repeat inside the interval only bumps the counter; it leaves with the next request of this window.
+                window.count += 1
+                window.latest = event
+                return
+            self._windows[key] = _Window(time.monotonic(), event)
+
+        self._post(event, 1)
+
+    def _flush_windows(self, force: bool) -> None:
+        """Windows whose interval passed: repeats go out as one request with a count, idle windows close."""
+        try:
+            now = time.monotonic()
+            due = []
+            with self._windows_lock:
+                for key, window in list(self._windows.items()):
+                    if not force and now - window.opened_at < self.repeat_interval:
+                        continue
+                    if window.count > 0:
+                        due.append((window.latest, window.count))
+                        window.count = 0
+                        window.opened_at = now
+                    else:
+                        del self._windows[key]
+
+            for event, count in due:
+                self._post(event, count)
+        except Exception:
+            self._warn("windows", "BugsRadar: failed to flush repeat windows", exc_info=True)
+
+    def _post(self, event: Event, count: int) -> None:
+        with self._condition:
+            if self._closing:
+                return
+            full = self._pending >= self.queue_capacity
+            if not full:
+                self._pending += 1
+                self._queue.append(_Item(event, count, None))
+                self._condition.notify()
+
+        if full:
+            self._warn("queue-full", "BugsRadar: the outgoing queue is full (%d), events are being dropped", self.queue_capacity)
+            return
+        self._start()
+
+    def _start(self) -> None:
+        """The sending thread of this process. After a fork the child has none: the first event starts it."""
+        pid = os.getpid()
+        if self._thread_pid == pid:
+            return
+        with _start_lock:
+            if self._thread_pid == pid:
+                return
+            thread = threading.Thread(target=self._run, name="bugsradar", daemon=True)
+            thread.start()
+            self._thread = thread
+            self._thread_pid = pid
+
+    def _run(self) -> None:
+        """One thread sends the queue in order; markers of flush() are released when the thread reaches them."""
+        while True:
+            with self._condition:
+                if not self._queue and not self._closing:
+                    self._condition.wait(WINDOW_CHECK)
+                item = self._queue.popleft() if self._queue else None
+                if item is not None and item.marker is None:
+                    self._pending -= 1
+                if item is None and self._closing:
+                    return
+
+            self._flush_windows(False)
+            if item is None:
+                continue
+            if item.marker is not None:
+                item.marker.set()
+                continue
+
+            try:
+                self._deliver(item)
+            except Exception:
+                self._warn("send", "BugsRadar: failed to send an event", exc_info=True)
+
+    def _deliver(self, item: _Item) -> None:
+        if self._gone or item.event is None:
+            return
+
+        body = serialize(item.event, item.count)
+        for attempt in range(MAX_ATTEMPTS):
+            pause = self._paused_until - time.monotonic()
+            if pause > 0:
+                time.sleep(pause)
+
+            outcome, retry_after = self._post_once(body)
+            if outcome in (_DELIVERED, _DROP):
+                return
+            if outcome == _RATE_LIMITED:
+                self._paused_until = time.monotonic() + retry_after
+            elif attempt + 1 < MAX_ATTEMPTS:
+                time.sleep(RETRY_DELAYS[attempt])
+
+        self._warn("dropped", "BugsRadar: an event was dropped after %d failed attempts", MAX_ATTEMPTS)
+
+    def _post_once(self, body: bytes) -> Tuple[int, float]:
+        request = urllib.request.Request(
+            self.api_url,
+            data=body,
+            method="POST",
+            headers={"Content-Type": "application/json", "X-Api-Key": self.api_key, "User-Agent": USER_AGENT},
+        )
+        if not self._tls_ready:
+            self._tls = _tls_context()
+            self._tls_ready = True
+        try:
+            with urllib.request.urlopen(request, timeout=self.request_timeout, context=self._tls) as response:
+                # The body is not needed; reading it frees the connection.
+                response.read()
+                if response.headers.get("Deprecation") is not None and not self._deprecation_warned:
+                    self._deprecation_warned = True
+                    log.warning("BugsRadar: this version of the bugsradar package is deprecated. Update it: pip install --upgrade bugsradar")
+                return _DELIVERED, 0.0
+        except urllib.error.HTTPError as error:
+            try:
+                error.read()
+            except Exception:
+                pass
+            finally:
+                error.close()
+            return self._interpret(error.code, error.headers)
+        except Exception:
+            # Network failure or timeout: worth a retry, not worth a warning every time.
+            log.debug("BugsRadar: request failed, will retry", exc_info=True)
+            return _RETRY, 0.0
+
+    def _interpret(self, status: int, headers: Any) -> Tuple[int, float]:
+        if status == 410:
+            # Nothing this version sends will ever be accepted: stop trying, tell the developer once.
+            if not self._gone:
+                self._gone = True
+                log.error("BugsRadar: this version of the bugsradar package is no longer supported, events are not delivered. Update it: pip install --upgrade bugsradar")
+            return _DROP, 0.0
+        if status == 401:
+            self._warn("auth", "BugsRadar: the server rejected the API key (401). Check api_key in bugsradar.init()")
+            return _DROP, 0.0
+        if status == 429:
+            return _RATE_LIMITED, _retry_after(headers.get("Retry-After") if headers is not None else None)
+        if status >= 500:
+            return _RETRY, 0.0
+
+        self._warn("rejected", "BugsRadar: the event was not accepted, the server returned %d", status)
+        return _DROP, 0.0
+
+    def _warn(self, kind: str, message: str, *args: Any, exc_info: bool = False) -> None:
+        """Warnings of one kind at most every ten minutes: a broken network must not flood the application's log."""
+        try:
+            now = time.monotonic()
+            last = self._last_warning.get(kind)
+            if last is not None and now - last < WARNING_INTERVAL:
+                return
+            self._last_warning[kind] = now
+            log.warning(message, *args, exc_info=exc_info)
+        except Exception:
+            # Diagnostics must never break the application.
+            pass
+
+
+def _tls_context() -> Optional[ssl.SSLContext]:
+    """
+    None keeps urllib's default: the certificates the system trusts. On Windows that default also trusts the "CA"
+    store, where Windows keeps every intermediate certificate it has met, expired ones included. An expired
+    cross-signed ISRG Root X2 left there since 2025 breaks the current Let's Encrypt chain of api.bugsradar.com with
+    "certificate has expired", while .NET and browsers build the chain themselves and never notice. The server sends
+    all its intermediates, so on Windows the trusted roots are enough.
+    """
+    if sys.platform != "win32":
+        return None
+    try:
+        context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        context.minimum_version = ssl.TLSVersion.TLSv1_2
+        context.set_alpn_protocols(["http/1.1"])
+        loaded = 0
+        for cert, encoding, trust in ssl.enum_certificates("ROOT"):
+            # trust is True for any purpose, or the set of purposes the root is trusted for.
+            if encoding != "x509_asn" or (trust is not True and ssl.Purpose.SERVER_AUTH.oid not in trust):
+                continue
+            try:
+                context.load_verify_locations(cadata=cert)
+                loaded += 1
+            except ssl.SSLError:
+                pass
+        # No roots at all is not a normal Windows: Python's default is the better guess then.
+        return context if loaded > 0 else None
+    except Exception:
+        return None
+
+
+def _hostname() -> Optional[str]:
+    try:
+        return text(socket.gethostname())
+    except Exception:
+        return None
+
+
+def _number(value: Any, fallback: float) -> float:
+    if isinstance(value, timedelta):
+        value = value.total_seconds()
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value != value or value < 0:
+        return fallback
+    return float(value)
+
+
+def _retry_after(value: Any) -> float:
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_RETRY_AFTER
+    if seconds != seconds or seconds <= 0:
+        return DEFAULT_RETRY_AFTER
+    return max(1.0, seconds)
+
+
+_default: Optional[Client] = None
+_default_lock = threading.Lock()
+
+
+def get_default() -> Optional[Client]:
+    """The client created by bugsradar.init()."""
+    return _default
+
+
+def set_default(client: Optional[Client]) -> Optional[Client]:
+    """Makes `client` the default one and returns the previous."""
+    global _default
+    with _default_lock:
+        previous, _default = _default, client
+    return previous
+
+
+def _after_fork_in_child() -> None:
+    # A lock held by another thread at the moment of the fork would stay locked in the child forever.
+    global _start_lock, _default_lock
+    _start_lock = threading.Lock()
+    _default_lock = threading.Lock()
+    for client in list(_clients):
+        client._reset()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork_in_child)

bugsradar/_duplicates.py

@@ -0,0 +1,58 @@
+"""The same failure reaching the package twice is sent once."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, Optional
+
+TEXT_WINDOW = 2.0
+MAX_TEXT_ENTRIES = 1000
+_MARK = "_bugsradar_seen"
+
+
+class DuplicateFilter:
+    """
+    The same failure often reaches the package twice: logged with logger.exception and also reported by hand.
+    An exception object is marked when first seen, so the mark lives and dies with it and holds no memory;
+    events without an exception are remembered for two seconds by level, template and text.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._texts: Dict[str, float] = {}
+
+    def is_duplicate(self, exception: Any, level: str, message_template: Optional[str], message: Optional[str], now: float) -> bool:
+        if isinstance(exception, BaseException):
+            if getattr(exception, _MARK, False) is True:
+                return True
+            try:
+                setattr(exception, _MARK, True)
+            except Exception:
+                # An exception that takes no attributes cannot be recognised again: it is never a duplicate.
+                pass
+            return False
+
+        thrown = "" if exception is None else _safe_str(exception)
+        key = f"{level}|{message_template or ''}|{message or ''}|{thrown}"
+        with self._lock:
+            seen_at = self._texts.get(key)
+            if seen_at is not None and now - seen_at < TEXT_WINDOW:
+                return True
+            if len(self._texts) >= MAX_TEXT_ENTRIES:
+                self._sweep(now)
+            self._texts[key] = now
+            return False
+
+    def _sweep(self, now: float) -> None:
+        for key in [key for key, seen_at in self._texts.items() if now - seen_at >= TEXT_WINDOW]:
+            del self._texts[key]
+        # A flood of distinct texts within two seconds: forget everything rather than grow without bound.
+        if len(self._texts) >= MAX_TEXT_ENTRIES:
+            self._texts.clear()
+
+
+def _safe_str(value: Any) -> str:
+    try:
+        return str(value)
+    except Exception:
+        return type(value).__name__

bugsradar/_event.py

@@ -0,0 +1,198 @@
+"""
+Events are built in the caller's thread. The exception becomes plain data at once, frames without source lines,
+so the queue never keeps frames and their locals alive; the source lines are read later, in the sending thread.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import traceback
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+MAX_EXCEPTIONS = 10
+MAX_FRAMES = 100
+MAX_PROPERTIES = 50
+
+# Level names the server knows. Anything else becomes Error there too.
+_LEVEL_NAMES = {
+    "trace": "Trace",
+    "debug": "Debug",
+    "info": "Information",
+    "information": "Information",
+    "warn": "Warning",
+    "warning": "Warning",
+    "error": "Error",
+    "exception": "Error",
+    "fatal": "Critical",
+    "critical": "Critical",
+}
+
+
+@dataclass
+class CapturedException:
+    type: str
+    message: Optional[str]
+    frames: Optional[traceback.StackSummary]
+
+    def top_frame(self) -> str:
+        if not self.frames:
+            return ""
+        frame = self.frames[-1]
+        return f"{frame.filename}:{frame.lineno}:{frame.name}"
+
+
+@dataclass
+class Event:
+    timestamp: datetime
+    level: str
+    message_template: Optional[str]
+    message: Optional[str]
+    properties: Optional[Dict[str, str]]
+    exceptions: Optional[List[CapturedException]]
+    category: Optional[str]
+    environment: Optional[str]
+    host: Optional[str]
+    app_version: Optional[str]
+    module: Optional[str]
+    fingerprint: Optional[str]
+    source: str
+
+
+def capture(error: Any) -> Optional[List[CapturedException]]:
+    """The exception and its chain (raise ... from, or an exception raised while handling another), outermost first."""
+    if error is None:
+        return None
+
+    result: List[CapturedException] = []
+    seen = set()
+    current = error
+    while current is not None and len(result) < MAX_EXCEPTIONS and id(current) not in seen:
+        seen.add(id(current))
+        result.append(_capture_one(current))
+        current = _next(current)
+    return result
+
+
+def _capture_one(error: Any) -> CapturedException:
+    if not isinstance(error, BaseException):
+        # send(exception="text"): no class of its own and no traceback.
+        return CapturedException(type(error).__name__, _safe_str(error), None)
+
+    # The frames closest to the error; a RecursionError alone would bring a thousand.
+    frames = list(traceback.walk_tb(error.__traceback__))[-MAX_FRAMES:]
+    summary = traceback.StackSummary.extract(iter(frames), lookup_lines=False) if frames else None
+    message = _safe_str(error)
+    return CapturedException(type_name(error), message or None, summary)
+
+
+def _next(error: Any) -> Any:
+    if not isinstance(error, BaseException):
+        return None
+    if error.__cause__ is not None:
+        return error.__cause__
+    # raise ... from None hides the exception that was being handled.
+    if error.__suppress_context__:
+        return None
+    return error.__context__
+
+
+def repeat_key(event: Event) -> str:
+    """
+    Key for folding repeats inside the package: exception type, top frame, template or text. Coarser than the
+    server's fingerprint on purpose: it only decides which events travel together in one request.
+    """
+    if event.fingerprint:
+        return "f|" + event.fingerprint
+    if event.exceptions:
+        first = event.exceptions[0]
+        # Without a traceback, the text tells errors of one type apart.
+        where = first.top_frame() or (first.message or "")
+        return f"e|{first.type}|{where}|{event.message_template or ''}"
+    return f"m|{event.level}|{event.message_template or event.message or ''}"
+
+
+def type_name(error: BaseException) -> str:
+    """ValueError for built-ins and __main__, myapp.errors.OrderError for the rest."""
+    cls = type(error)
+    name = getattr(cls, "__qualname__", None) or cls.__name__
+    module = getattr(cls, "__module__", None)
+    if not module or module in ("builtins", "__main__"):
+        return name
+    return f"{module}.{name}"
+
+
+def level_name(level: Any) -> str:
+    """'warning' or logging.WARNING → 'Warning'; empty or unknown → 'Error'."""
+    if isinstance(level, bool):
+        return "Error"
+    if isinstance(level, int):
+        if level >= logging.CRITICAL:
+            return "Critical"
+        if level >= logging.ERROR:
+            return "Error"
+        if level >= logging.WARNING:
+            return "Warning"
+        if level >= logging.INFO:
+            return "Information"
+        if level >= logging.DEBUG:
+            return "Debug"
+        return "Trace"
+    if isinstance(level, str):
+        return _LEVEL_NAMES.get(level.strip().lower(), "Error")
+    return "Error"
+
+
+def stringify_properties(values: Any) -> Optional[Dict[str, str]]:
+    """Values travel as strings: dicts and lists as JSON, exceptions as "Type: message"."""
+    if not values:
+        return None
+    try:
+        items = list(values.items())
+    except AttributeError:
+        return None
+
+    result: Dict[str, str] = {}
+    for key, value in items:
+        if len(result) == MAX_PROPERTIES:
+            break
+        result[_safe_str(key)] = _stringify(value)
+    return result or None
+
+
+def text(value: Any) -> Optional[str]:
+    """None, an empty string and a string of spaces are the same as no value."""
+    if value is None:
+        return None
+    result = value if isinstance(value, str) else _safe_str(value)
+    result = result.strip()
+    return result or None
+
+
+def utc(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        # A naive datetime is taken as local time, as datetime itself does.
+        return value.astimezone(timezone.utc)
+    return datetime.now(timezone.utc)
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, BaseException):
+        return f"{type_name(value)}: {_safe_str(value)}"
+    if isinstance(value, (dict, list, tuple)):
+        try:
+            return json.dumps(value, ensure_ascii=False, default=str)
+        except Exception:
+            pass
+    return _safe_str(value)
+
+
+def _safe_str(value: Any) -> str:
+    try:
+        return str(value)
+    except Exception:
+        return f"<{type(value).__name__}>"

bugsradar/_hooks.py

@@ -0,0 +1,61 @@
+"""Uncaught exceptions: sys.excepthook for the program, threading.excepthook for threads."""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import Any, Dict, Optional
+
+from . import _client
+
+_lock = threading.Lock()
+_installed = False
+_enabled = False
+
+
+def install(enabled: bool) -> None:
+    """
+    The hooks are set once per process and report to whichever client init() created last; each calls the hook it
+    replaced, so the traceback is still printed and other tools keep working. init(capture_uncaught=False) turns
+    reporting off without taking the hooks down.
+    """
+    global _installed, _enabled
+    with _lock:
+        _enabled = enabled
+        if _installed or not enabled:
+            return
+        _installed = True
+
+        previous_excepthook = sys.excepthook
+        previous_threading_excepthook = threading.excepthook
+
+        def excepthook(exc_type: Any, exc_value: Any, exc_traceback: Any) -> None:
+            # Ctrl+C is the user's decision, not an error.
+            if not (isinstance(exc_type, type) and issubclass(exc_type, KeyboardInterrupt)):
+                _report(exc_value, "critical", None)
+            previous_excepthook(exc_type, exc_value, exc_traceback)
+
+        def threading_excepthook(args: Any) -> None:
+            # SystemExit ends a thread quietly; Python's own hook ignores it too.
+            if not (isinstance(args.exc_type, type) and issubclass(args.exc_type, SystemExit)):
+                thread = args.thread
+                _report(args.exc_value, "error", {"thread": thread.name} if thread is not None else None)
+            previous_threading_excepthook(args)
+
+        sys.excepthook = excepthook
+        threading.excepthook = threading_excepthook
+
+
+def _report(error: Any, level: str, properties: Optional[Dict[str, Any]]) -> None:
+    """Reports and waits up to shutdown_timeout for the report to leave: the program or the thread is ending."""
+    if not _enabled:
+        return
+    try:
+        client = _client.get_default()
+        if client is None:
+            return
+        client._send("Uncaught", exception=error, level=level, properties=properties)
+        client.flush()
+    except Exception:
+        # A hook must never make the crash worse.
+        pass

bugsradar/_logging.py

@@ -0,0 +1,139 @@
+"""Records of the standard logging module → BugsRadar events."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, Union
+
+from . import _client
+
+# Attributes every LogRecord has; the rest came from extra={...}.
+_RECORD_FIELDS = frozenset(vars(logging.LogRecord("", logging.ERROR, "", 0, "", (), None))) | {"message", "asctime"}
+# Set on a record once it is sent: the hook and a LoggingHandler never send one record twice.
+_SENT = "_bugsradar_sent"
+
+_lock = threading.Lock()
+_level: Optional[int] = None
+_patched = False
+_sending = threading.local()
+
+
+class LoggingHandler(logging.Handler):
+    """
+    Sends log records to BugsRadar through the client of bugsradar.init(). Needed only with
+    init(logging_level=None): add it to the loggers you choose, in code or in a dictConfig.
+    """
+
+    def __init__(self, level: Union[int, str] = logging.ERROR) -> None:
+        super().__init__(level)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            _send(record)
+        except Exception:
+            self.handleError(record)
+
+
+def install(level: Optional[int]) -> None:
+    """
+    Records of every logger at `level` and above go to BugsRadar, whatever handlers the application's logging setup
+    has. Logger.callHandlers is wrapped once per process, as Sentry does, and no handler is added anywhere, so
+    logging.basicConfig and Python's last-resort output to stderr work as before. None turns it off.
+    """
+    global _level, _patched
+    with _lock:
+        _level = level
+        if _patched or level is None:
+            return
+        _patched = True
+        original = logging.Logger.callHandlers
+
+        def call_handlers(self: logging.Logger, record: logging.LogRecord) -> Any:
+            try:
+                return original(self, record)
+            finally:
+                # After the application's own handlers: its log output comes first.
+                _hook(record)
+
+        logging.Logger.callHandlers = call_handlers  # type: ignore[method-assign]
+
+
+def level_number(level: Union[int, str]) -> int:
+    """logging.WARNING or "WARNING" → 30."""
+    if isinstance(level, int) and not isinstance(level, bool):
+        return level
+    if isinstance(level, str):
+        number = logging.getLevelName(level.strip().upper())
+        if isinstance(number, int):
+            return number
+    raise ValueError(f"BugsRadar: unknown logging_level {level!r}")
+
+
+def _hook(record: logging.LogRecord) -> None:
+    level = _level
+    if level is None or record.levelno < level:
+        return
+    try:
+        _send(record)
+    except Exception:
+        # Reporting must never break logging.
+        pass
+
+
+def _send(record: logging.LogRecord) -> None:
+    # The package's own warnings are never sent: a broken network must not feed on itself.
+    if record.name == "bugsradar" or record.name.startswith("bugsradar."):
+        return
+    # Logging done while a record is being sent (a __str__ of a value in extra, say) is not sent.
+    if getattr(record, _SENT, False) or getattr(_sending, "active", False):
+        return
+    client = _client.get_default()
+    if client is None:
+        return
+
+    try:
+        setattr(record, _SENT, True)
+    except Exception:
+        pass
+
+    _sending.active = True
+    try:
+        exception = _exception(record)
+        client._send(
+            "logging",
+            exception=exception,
+            level=record.levelno,
+            # "Order %s failed": failures of different orders are one error with a count.
+            message_template=str(record.msg) if record.args else None,
+            # logger.error(error) makes the exception itself the message: it is already in the exception.
+            message=None if exception is not None and exception is record.msg else _message(record),
+            properties=_extra(record),
+            category=record.name,
+            timestamp=datetime.fromtimestamp(record.created, timezone.utc),
+        )
+    finally:
+        _sending.active = False
+
+
+def _exception(record: logging.LogRecord) -> Optional[BaseException]:
+    # logger.exception and exc_info=True bring the exception being handled.
+    if record.exc_info and isinstance(record.exc_info[1], BaseException):
+        return record.exc_info[1]
+    if isinstance(record.msg, BaseException):
+        return record.msg
+    return None
+
+
+def _message(record: logging.LogRecord) -> str:
+    try:
+        return record.getMessage()
+    except Exception:
+        # Arguments that do not fit the format string: the format string itself is better than nothing.
+        return str(record.msg)
+
+
+def _extra(record: logging.LogRecord) -> Optional[Dict[str, Any]]:
+    extra = {key: value for key, value in vars(record).items() if key not in _RECORD_FIELDS and not key.startswith("_")}
+    return extra or None

bugsradar/_payload.py

@@ -0,0 +1,47 @@
+"""Body of api/v3/python/SendException, built in the sending thread."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict
+
+from ._event import CapturedException, Event
+
+
+def serialize(event: Event, count: int) -> bytes:
+    """Fields without a value are left out."""
+    body = {
+        "timestamp": _iso(event.timestamp),
+        "level": event.level,
+        "messageTemplate": event.message_template,
+        "message": event.message,
+        "properties": event.properties,
+        "exceptions": [_exception(e) for e in event.exceptions] if event.exceptions else None,
+        "category": event.category,
+        "environment": event.environment,
+        "host": event.host,
+        "appVersion": event.app_version,
+        "module": event.module,
+        "source": event.source,
+        "fingerprint": event.fingerprint,
+        "count": count if count > 1 else 1,
+    }
+    text = json.dumps({key: value for key, value in body.items() if value is not None}, ensure_ascii=False, separators=(",", ":"))
+    # A lone surrogate (a file name decoded with surrogateescape, say) has no UTF-8 form: it becomes "?".
+    return text.encode("utf-8", errors="replace")
+
+
+def _exception(captured: CapturedException) -> Dict[str, Any]:
+    result: Dict[str, Any] = {"type": captured.type}
+    if captured.message is not None:
+        result["message"] = captured.message
+    if captured.frames:
+        # traceback.format_tb lines, from the outer call to the error; source lines are read here.
+        result["traceback"] = "".join(captured.frames.format())
+    return result
+
+
+def _iso(value: datetime) -> str:
+    moment = value.astimezone(timezone.utc)
+    return moment.strftime("%Y-%m-%dT%H:%M:%S.") + f"{moment.microsecond // 1000:03d}Z"

bugsradar/_version.py

@@ -0,0 +1,9 @@
+"""The package version comes from its metadata, so pyproject.toml is the only place to change it."""
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("bugsradar")
+except metadata.PackageNotFoundError:
+    # Running from a source checkout that was never installed.
+    __version__ = "0.0.0"

bugsradar-3.0.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: bugsradar
+Version: 3.0.0
+Summary: Errors of your Python application in Telegram, Discord or Pushover: logging, uncaught exceptions and direct calls in one package.
+Project-URL: Homepage, https://bugsradar.com/docs/python/
+Author: Bistriy Sp. z o.o.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alerts,bugsradar,discord,error,exception,logging,pushover,telegram
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# BugsRadar for Python
+
+Errors of your Python application in Telegram, Discord or Pushover: the standard `logging` module, uncaught exceptions and direct calls in one package. Python 3.9 and later, no dependencies outside the standard library.
+
+Full documentation: https://bugsradar.com/docs/python/
+
+You need a BugsRadar project with a channel and the project's API key: create them at https://app.bugsradar.com/.
+
+## Install
+
+```
+pip install bugsradar
+```
+
+## Set it up
+
+Once, at the start of the program:
+
+```python
+import os
+import bugsradar
+
+bugsradar.init(
+    api_key=os.environ["BUGSRADAR_KEY"],
+    environment="Production",  # optional
+)
+```
+
+> **The API key is secret: use it only in code that runs on your servers.** Never put it in a desktop app you ship to others (PyInstaller, PySide or PyQt builds) or in a public repository: anyone can take the key out of them. For such apps, public keys are on the way: https://bugsradar.com/docs/#public-keys
+
+From here on, records at `ERROR` and above from every logger and uncaught exceptions go to BugsRadar. `init` adds no handlers: your logging setup works as before. Django, Flask and Uvicorn log unhandled exceptions of requests, so `init` covers them too.
+
+## logging
+
+```python
+logger.exception("Order %s failed", order_id)
+```
+
+The format string becomes the message template, so failures of different orders are one error with a count.
+
+## Direct calls
+
+```python
+try:
+    create_order(order_id)
+except Exception as error:
+    bugsradar.send_exception(error, module="Orders")
+```
+
+`send` and `send_exception` queue the event and return at once; nothing raises.
+
+## Before the program exits
+
+`init` registers an `atexit` hook that waits up to `shutdown_timeout` (5 s) for queued reports. In a short script you can also wait yourself:
+
+```python
+bugsradar.flush()
+```
+
+Questions: support@bistriy.com

bugsradar-3.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+bugsradar/__init__.py,sha256=NFE8cR0heYa6BA4ua7aOlEAEtzFXutOcFNE1GE-YmAg,5080
+bugsradar/_client.py,sha256=Be9UGEhNaLfF4RhDmIFrFCZXN0JsmA2cgpDFqW4geYc,17163
+bugsradar/_duplicates.py,sha256=apKvOCbTPsOua8CyoLuqzxYH7qN9Llry3q7f2mbVhbE,2151
+bugsradar/_event.py,sha256=_2cyT2ZiYSxXpdZ7f7f8oKE_A6ZhRIh_sV_jIwhViao,6238
+bugsradar/_hooks.py,sha256=XfIcO5h5bs6mmA9EpaL9Tq_JmEA4xcoIR6YPBV8djFo,2268
+bugsradar/_logging.py,sha256=MbOZX-shOIj5UKw3ul5f2hiM3frImQ3gCT607Q_ohpw,4893
+bugsradar/_payload.py,sha256=8wjF0t3n7D1ma_15M3apENJLRC2nhn2q8Whtd2aZnE4,1805
+bugsradar/_version.py,sha256=jMDiRdtqbg0Es8WA64pnNLvYhASMPk6yqRqktrEMo9o,314
+bugsradar/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bugsradar-3.0.0.dist-info/METADATA,sha256=4SDG-9TWpm4rLl7Ci9zkwuS6pTyhR27U1_cPV721YYs,2587
+bugsradar-3.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bugsradar-3.0.0.dist-info/licenses/LICENSE,sha256=i-sSF-C-tqqEgbASCdz2eMVgDg7fjlnTyoUZ9VSfsRM,1075
+bugsradar-3.0.0.dist-info/RECORD,,

bugsradar-3.0.0.dist-info/WHEEL

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

bugsradar-3.0.0.dist-info/licenses/LICENSE

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