tinymonpy 0.1.0__py3-none-any.whl

tinymonpy/__init__.py

@@ -0,0 +1,82 @@
+"""tinymon — tiny error monitoring SDK for Python.
+
+The public API mirrors the TS SDK so customers can move between languages
+with no surprises::
+
+    import tinymon
+    tinymon.init(dsn="tm_pub_xxx", environment="production", release="1.0.0")
+    try:
+        risky_thing()
+    except Exception as e:
+        tinymon.capture_exception(e)
+
+Uncaught exceptions (main thread and workers) are captured automatically after
+``init``.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from .client import Client
+from .event_builder import build_event as _build_event  # public for contract tests
+from .integrations import install_global_handlers
+from .scope import scope
+from .stacktrace import parse_traceback as _parse_traceback  # public for contract tests
+
+__all__ = [
+    "init",
+    "capture_exception",
+    "capture_message",
+    "set_user",
+    "set_tag",
+    "add_breadcrumb",
+    "_build_event",
+    "_parse_traceback",
+]
+
+__version__ = "0.1.0"
+
+_client: Optional[Client] = None
+
+
+def init(
+    dsn: str,
+    *,
+    endpoint: Optional[str] = None,
+    environment: Optional[str] = None,
+    release: Optional[str] = None,
+    sample_rate: float = 1.0,
+    before_send: Optional[Callable[[Dict[str, Any]], Optional[Dict[str, Any]]]] = None,
+) -> None:
+    global _client
+    _client = Client(
+        dsn,
+        endpoint=endpoint,
+        environment=environment,
+        release=release,
+        sample_rate=sample_rate,
+        before_send=before_send,
+    )
+    install_global_handlers(_client)
+
+
+def capture_exception(exc: BaseException) -> None:
+    if _client is not None:
+        _client.capture_exception(exc)
+
+
+def capture_message(msg: str, level: str = "info") -> None:
+    if _client is not None:
+        _client.capture_message(msg, level)
+
+
+def set_user(user: Dict[str, Any]) -> None:
+    scope.set_user(user)
+
+
+def set_tag(key: str, value: str) -> None:
+    scope.set_tag(key, value)
+
+
+def add_breadcrumb(crumb: Dict[str, Any]) -> None:
+    scope.add_breadcrumb(crumb)

tinymonpy/client.py

@@ -0,0 +1,75 @@
+"""The Client orchestrates capture: build event, run beforeSend, enqueue."""
+from __future__ import annotations
+
+import random
+from typing import Any, Callable, Dict, Optional
+
+from .event_builder import build_event
+from .scope import scope
+from .transport import Transport
+
+_DEFAULT_ENDPOINT = "https://console.tinymon.dev/api/ingest"
+
+BeforeSend = Callable[[Dict[str, Any]], Optional[Dict[str, Any]]]
+
+
+class Client:
+    def __init__(
+        self,
+        dsn: str,
+        *,
+        endpoint: Optional[str] = None,
+        environment: Optional[str] = None,
+        release: Optional[str] = None,
+        sample_rate: float = 1.0,
+        before_send: Optional[BeforeSend] = None,
+    ) -> None:
+        self.dsn = dsn
+        self.endpoint = endpoint or _DEFAULT_ENDPOINT
+        self.environment = environment
+        self.release = release
+        self.sample_rate = sample_rate
+        self.before_send = before_send
+        self.transport = Transport(self.endpoint, dsn)
+
+    def capture_exception(self, exc: BaseException) -> None:
+        try:
+            if random.random() > self.sample_rate:
+                return
+            snap = scope.snapshot()
+            event = build_event(
+                exc,
+                release=self.release,
+                environment=self.environment,
+                user=snap["user"],
+                tags=snap["tags"],
+                breadcrumbs=snap["breadcrumbs"],
+            )
+            if self.before_send is not None:
+                result = self.before_send(event)
+                if result is None:
+                    return
+                event = result
+            self.transport.enqueue(event)
+        except Exception:
+            # SWALLOW. The SDK must never throw into the host app.
+            pass
+
+    def capture_message(self, message: str, level: str = "info") -> None:
+        try:
+            # Synthesize an exception without a stack — value carries the message.
+            synthetic = Exception(message)
+            snap = scope.snapshot()
+            event = build_event(
+                synthetic,
+                release=self.release,
+                environment=self.environment,
+                user=snap["user"],
+                tags=snap["tags"],
+                breadcrumbs=snap["breadcrumbs"],
+            )
+            event["level"] = level
+            event["exception"]["type"] = "Message"
+            self.transport.enqueue(event)
+        except Exception:
+            pass

tinymonpy/event_builder.py

@@ -0,0 +1,57 @@
+"""Pure construction of a wire-format event from a Python exception.
+
+Mirrors `packages/browser/src/eventBuilder.ts`. The schema source of truth is
+`spec/event.schema.json` — every field below maps to one defined there.
+"""
+from __future__ import annotations
+
+import re
+import time
+import uuid as _uuid
+from typing import Any, Dict, List, Optional
+
+from .stacktrace import parse_traceback
+
+SDK_NAME = "tinymon.python"
+SDK_VERSION = "0.1.0"
+
+# Substrings (case-insensitive) in tag keys that we redact before sending.
+_SENSITIVE = re.compile(r"password|token|secret|auth|card|cvv|ssn", re.IGNORECASE)
+
+
+def build_event(
+    exc: BaseException,
+    *,
+    release: Optional[str] = None,
+    environment: Optional[str] = None,
+    user: Optional[Dict[str, Any]] = None,
+    tags: Optional[Dict[str, str]] = None,
+    breadcrumbs: Optional[List[Dict[str, Any]]] = None,
+    url: Optional[str] = None,
+) -> Dict[str, Any]:
+    event: Dict[str, Any] = {
+        "event_id": str(_uuid.uuid4()),
+        "timestamp": time.time(),
+        "platform": "python",
+        "level": "error",
+        "sdk": {"name": SDK_NAME, "version": SDK_VERSION},
+        "exception": {
+            "type": type(exc).__name__,
+            "value": str(exc),
+            "stacktrace": {"frames": parse_traceback(exc.__traceback__)},
+        },
+        "breadcrumbs": list(breadcrumbs or []),
+        "user": dict(user or {}),
+        "tags": _scrub(tags or {}),
+    }
+    if release is not None:
+        event["release"] = release
+    if environment is not None:
+        event["environment"] = environment
+    if url is not None:
+        event["request"] = {"url": url}
+    return event
+
+
+def _scrub(tags: Dict[str, str]) -> Dict[str, str]:
+    return {k: ("[redacted]" if _SENSITIVE.search(k) else v) for k, v in tags.items()}

tinymonpy/integrations.py

@@ -0,0 +1,38 @@
+"""Auto-capture hooks: uncaught exceptions on main and worker threads."""
+from __future__ import annotations
+
+import sys
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+def install_global_handlers(client: "Client") -> None:
+    # Main-thread uncaught exceptions.
+    orig_excepthook = sys.excepthook
+
+    def _hook(exc_type, exc_value, exc_traceback):
+        try:
+            if exc_value is not None:
+                client.capture_exception(exc_value)
+        except Exception:
+            pass
+        orig_excepthook(exc_type, exc_value, exc_traceback)
+
+    sys.excepthook = _hook
+
+    # Worker-thread uncaught exceptions (Python 3.8+).
+    if hasattr(threading, "excepthook"):
+        orig_thread_hook = threading.excepthook
+
+        def _thread_hook(args):
+            try:
+                if args.exc_value is not None:
+                    client.capture_exception(args.exc_value)
+            except Exception:
+                pass
+            orig_thread_hook(args)
+
+        threading.excepthook = _thread_hook

tinymonpy/scope.py

@@ -0,0 +1,40 @@
+"""Process-wide user/tags/breadcrumbs context that rides along with events."""
+from __future__ import annotations
+
+import threading
+from typing import Any, Dict, List
+
+_MAX_BREADCRUMBS = 50
+
+
+class Scope:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.user: Dict[str, Any] = {}
+        self.tags: Dict[str, str] = {}
+        self.breadcrumbs: List[Dict[str, Any]] = []
+
+    def set_user(self, user: Dict[str, Any]) -> None:
+        with self._lock:
+            self.user = dict(user)
+
+    def set_tag(self, key: str, value: str) -> None:
+        with self._lock:
+            self.tags[key] = value
+
+    def add_breadcrumb(self, crumb: Dict[str, Any]) -> None:
+        with self._lock:
+            self.breadcrumbs.append(crumb)
+            if len(self.breadcrumbs) > _MAX_BREADCRUMBS:
+                self.breadcrumbs.pop(0)
+
+    def snapshot(self) -> Dict[str, Any]:
+        with self._lock:
+            return {
+                "user": dict(self.user),
+                "tags": dict(self.tags),
+                "breadcrumbs": list(self.breadcrumbs),
+            }
+
+
+scope = Scope()

tinymonpy/stacktrace.py

@@ -0,0 +1,46 @@
+"""Convert a Python traceback into wire-format stack frames.
+
+Frames are returned deepest-LAST, matching `spec/event.schema.json`. The deepest
+frame is where the exception was raised; ``extract_tb`` already produces this
+order so no reversal is needed.
+"""
+from __future__ import annotations
+
+import os
+import traceback as _tb
+from typing import Any, Dict, List, Optional
+
+# Third-party install path (site-packages / dist-packages) and the stdlib
+# directory are used to flag frames as NOT in_app — same intent as the JS SDK's
+# "not in node_modules" check.
+_STDLIB_PATH = os.path.dirname(os.__file__)
+_THIRD_PARTY_MARKERS = ("site-packages", "dist-packages")
+
+
+def parse_traceback(exc_traceback: Optional[Any]) -> List[Dict[str, Any]]:
+    if exc_traceback is None:
+        return []
+    frames: List[Dict[str, Any]] = []
+    for fs in _tb.extract_tb(exc_traceback):
+        filename = fs.filename or ""
+        frames.append(
+            {
+                "filename": filename,
+                "function": fs.name or "<anonymous>",
+                "lineno": fs.lineno or 0,
+                # Python <3.11 doesn't track columns; SDK sends 0.
+                "colno": 0,
+                "in_app": _is_in_app(filename),
+            }
+        )
+    return frames
+
+
+def _is_in_app(filename: str) -> bool:
+    if not filename or filename.startswith("<"):
+        return False
+    if any(marker in filename for marker in _THIRD_PARTY_MARKERS):
+        return False
+    if _STDLIB_PATH and filename.startswith(_STDLIB_PATH):
+        return False
+    return True

tinymonpy/transport.py

@@ -0,0 +1,82 @@
+"""Batched HTTP transport. stdlib-only — no `requests` dependency.
+
+Runs a daemon thread that flushes every 5 seconds. An ``atexit`` hook drains
+the queue on shutdown so errors during teardown don't get lost.
+"""
+from __future__ import annotations
+
+import atexit
+import json
+import threading
+from collections import deque
+from typing import Any, Dict, Deque
+from urllib import error, request
+
+_FLUSH_INTERVAL = 5.0  # seconds
+_MAX_BATCH = 10
+_MAX_QUEUE = 30
+_REQUEST_TIMEOUT = 5.0
+
+
+class Transport:
+    def __init__(self, endpoint: str, dsn: str) -> None:
+        self.endpoint = endpoint
+        self.dsn = dsn
+        self._queue: Deque[Dict[str, Any]] = deque(maxlen=_MAX_QUEUE)
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run, daemon=True, name="tinymon-transport"
+        )
+        self._thread.start()
+        atexit.register(self._on_exit)
+
+    def enqueue(self, event: Dict[str, Any]) -> None:
+        with self._lock:
+            self._queue.append(event)
+            should_flush = len(self._queue) >= _MAX_BATCH
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            batch = []
+            while self._queue and len(batch) < _MAX_BATCH:
+                batch.append(self._queue.popleft())
+        for event in batch:
+            self._send(event)
+
+    def _send(self, event: Dict[str, Any]) -> None:
+        body = json.dumps(event).encode("utf-8")
+        req = request.Request(
+            self.endpoint,
+            data=body,
+            headers={
+                "Content-Type": "application/json",
+                "X-Tinymon-Key": self.dsn,
+            },
+            method="POST",
+        )
+        try:
+            with request.urlopen(req, timeout=_REQUEST_TIMEOUT) as resp:
+                resp.read()
+        except (error.URLError, OSError):
+            # Network failed — re-enqueue if there's room. Drops oldest on overflow.
+            with self._lock:
+                if len(self._queue) < _MAX_QUEUE:
+                    self._queue.appendleft(event)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self._stop.wait(_FLUSH_INTERVAL)
+            try:
+                self.flush()
+            except Exception:
+                pass
+
+    def _on_exit(self) -> None:
+        self._stop.set()
+        try:
+            self.flush()
+        except Exception:
+            pass

tinymonpy-0.1.0.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: tinymonpy
+Version: 0.1.0
+Summary: Tiny error monitoring SDK for Python.
+Author: tinymon
+License: MIT
+Project-URL: Homepage, https://tinymon.dev
+Project-URL: Documentation, https://tinymon.dev/docs/python.html
+Keywords: error,monitoring,tracking,tinymon
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: jsonschema>=4; extra == "test"

tinymonpy-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tinymonpy/__init__.py,sha256=8W3HvQckqixKfj9BFURT1u50oSdkfJTAN6cK_k7An80,2030
+tinymonpy/client.py,sha256=2CWC3pH5Zk841VzIQsoT4C_XKD4Wo5nnNaJ6kCvihqM,2476
+tinymonpy/event_builder.py,sha256=lwnmweYZlbgAMXvTwVKEkCGu15sT8vBlnZD4EjPyVgU,1801
+tinymonpy/integrations.py,sha256=Ls0Kdrq6c7y7SXgK4k9n-bU-JOqq0e2NPYQy7RJjoOc,1074
+tinymonpy/scope.py,sha256=1fTB-FMAM8diOQQsPQdvxZ5cNIpSt1KaY3NuIpux7Ao,1119
+tinymonpy/stacktrace.py,sha256=SYull3hR84OaKvok4dklqGZIdPvjHQnw6hc7pOiBT4o,1558
+tinymonpy/transport.py,sha256=FgKAv9sx8xMiIsdfZEKw-sCyoKXCmZSk4T04_MrkKZ4,2495
+tinymonpy-0.1.0.dist-info/METADATA,sha256=QpBbFJP8LjyFhG4b5gn-8L9lATNAcMxwFMBm8LxsBRc,672
+tinymonpy-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tinymonpy-0.1.0.dist-info/top_level.txt,sha256=R_dMJyZ6QRuNru8nfOX-EkqNMtChIRV3cHqpYHltOOQ,10
+tinymonpy-0.1.0.dist-info/RECORD,,

tinymonpy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tinymonpy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tinymonpy