tinymonpy 0.1.0__tar.gz

tinymonpy-0.1.0/PKG-INFO

@@ -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/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tinymonpy"
+version = "0.1.0"
+description = "Tiny error monitoring SDK for Python."
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "tinymon" }]
+keywords = ["error", "monitoring", "tracking", "tinymon"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Bug Tracking",
+]
+# Zero runtime dependencies — uses stdlib only (urllib, threading, atexit).
+
+[project.urls]
+Homepage = "https://tinymon.dev"
+Documentation = "https://tinymon.dev/docs/python.html"
+
+[project.optional-dependencies]
+test = ["jsonschema>=4"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tinymonpy*"]

tinymonpy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tinymonpy-0.1.0/tests/test_contract.py

@@ -0,0 +1,87 @@
+"""Contract test: the Python SDK must emit events that validate against
+``spec/event.schema.json``. Run from the repo root::
+
+    pip install jsonschema
+    python -m unittest packages/python/tests/test_contract.py
+"""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+# Import from the in-repo source.
+HERE = Path(__file__).resolve()
+sys.path.insert(0, str(HERE.parents[1]))
+
+from tinymon.event_builder import build_event  # noqa: E402
+
+try:
+    from jsonschema import Draft202012Validator
+except ImportError:  # pragma: no cover
+    print(
+        "ERROR: jsonschema not installed. Run: pip install jsonschema",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+REPO_ROOT = HERE.parents[3]
+SPEC = REPO_ROOT / "spec"
+SCHEMA = json.loads((SPEC / "event.schema.json").read_text())
+
+
+class TestContract(unittest.TestCase):
+    def setUp(self) -> None:
+        self.validator = Draft202012Validator(SCHEMA)
+
+    def _validate(self, event):
+        errors = list(self.validator.iter_errors(event))
+        if errors:
+            self.fail(
+                "schema errors:\n  " + "\n  ".join(e.message for e in errors)
+            )
+
+    def test_canonical_wire_fixture_is_valid(self):
+        fx = json.loads(
+            (SPEC / "fixtures" / "wire" / "canonical_event.json").read_text()
+        )
+        self._validate(fx["event"])
+
+    def test_minimal_wire_fixture_is_valid(self):
+        fx = json.loads(
+            (SPEC / "fixtures" / "wire" / "minimal_event.json").read_text()
+        )
+        self._validate(fx["event"])
+
+    def test_sdk_output_validates_against_schema(self):
+        try:
+            raise ValueError("boom")
+        except ValueError as e:
+            event = build_event(
+                e,
+                release="1.0.0",
+                environment="test",
+                user={"id": "u1"},
+                tags={"feature": "checkout", "password": "shh"},
+            )
+        self._validate(event)
+
+        self.assertEqual(event["platform"], "python")
+        self.assertEqual(event["sdk"]["name"], "tinymon.python")
+        self.assertEqual(event["exception"]["type"], "ValueError")
+        self.assertEqual(event["exception"]["value"], "boom")
+        self.assertEqual(event["tags"]["password"], "[redacted]")
+
+        frames = event["exception"]["stacktrace"]["frames"]
+        self.assertGreaterEqual(len(frames), 1, "expected at least one frame")
+        deepest = frames[-1]
+        self.assertTrue(
+            deepest["in_app"],
+            f"expected the deepest frame to be in_app, got {deepest}",
+        )
+        self.assertEqual(deepest["function"], "test_sdk_output_validates_against_schema")
+
+
+if __name__ == "__main__":
+    unittest.main()

tinymonpy-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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/tinymonpy.egg-info/PKG-INFO

@@ -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/tinymonpy.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+pyproject.toml
+tests/test_contract.py
+tinymonpy/__init__.py
+tinymonpy/client.py
+tinymonpy/event_builder.py
+tinymonpy/integrations.py
+tinymonpy/scope.py
+tinymonpy/stacktrace.py
+tinymonpy/transport.py
+tinymonpy.egg-info/PKG-INFO
+tinymonpy.egg-info/SOURCES.txt
+tinymonpy.egg-info/dependency_links.txt
+tinymonpy.egg-info/requires.txt
+tinymonpy.egg-info/top_level.txt

tinymonpy-0.1.0/tinymonpy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tinymonpy-0.1.0/tinymonpy.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+jsonschema>=4

tinymonpy-0.1.0/tinymonpy.egg-info/top_level.txt

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