aperioflow 0.1.0__py3-none-any.whl

aperioflow/__init__.py

@@ -0,0 +1,264 @@
+"""AperioFlow error reporting for Python. No dependencies: it posts events to your project's ingest URL with urllib.
+
+    import aperioflow
+    aperioflow.init(ingest_url="https://app.aperioflow.co.uk/ingest/YOUR_KEY", release="1.4.0", environment="production")
+    try:
+        ...
+    except Exception as exc:
+        aperioflow.capture_exception(exc)
+
+It never collects the IP address or anything about the user on its own: a user id is sent only when you call set_user(id=...).
+Obvious secrets (password, token, cookie, authorization and similar keys, Bearer credentials, email addresses, card numbers) are
+taken out before an event leaves the process; the server scrubs again before it stores anything.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json as _json
+import random as _random
+import re as _re
+import sys as _sys
+import threading as _threading
+import traceback as _traceback
+import urllib.request as _request
+
+__all__ = [
+    "init", "close", "capture_exception", "capture_message", "add_breadcrumb", "set_user", "set_tag", "Client",
+    "scrub_text", "scrub_value", "is_secret_key", "MAX_BREADCRUMBS",
+]
+
+SDK_NAME = "aperioflow.python"
+SDK_VERSION = "0.1.0"
+MAX_BREADCRUMBS = 50
+_MAX_MESSAGE = 10000
+_MAX_STACK = 50000
+_MAX_CONTEXT_BYTES = 20000
+_LEVELS = {"fatal", "error", "warning", "info"}
+
+# ---------- client-side scrubbing of obvious secrets ----------
+
+_SECRET_PARTS = ("password", "passwd", "secret", "token", "authorization", "cookie", "apikey", "privatekey", "sessionid", "csrf")
+_SECRET_EXACT = {"auth", "session", "pin", "otp", "jwt"}
+_PAIR = _re.compile(r"([A-Za-z0-9_.-]{1,100})=([^&\s#;\"',]+)")
+_AUTH = _re.compile(r"\b(Bearer|Basic|Token)(\s+)[A-Za-z0-9._~+/=-]{8,}", _re.IGNORECASE)
+_EMAIL = _re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}")
+_CARD = _re.compile(r"(?<![\d.])[2-6](?:[ -]?\d){12,18}(?![\d.])")
+
+
+def is_secret_key(key) -> bool:
+    k = _re.sub(r"[-_\s]", "", str(key).lower())
+    return k in _SECRET_EXACT or any(part in k for part in _SECRET_PARTS)
+
+
+def _luhn(digits: str) -> bool:
+    total = 0
+    for i, ch in enumerate(reversed(digits)):
+        d = int(ch)
+        if i % 2:
+            d = d * 2 - 9 if d * 2 > 9 else d * 2
+        total += d
+    return total % 10 == 0
+
+
+def scrub_text(text):
+    if not isinstance(text, str):
+        return text
+    text = _PAIR.sub(lambda m: f"{m.group(1)}=[redacted]" if is_secret_key(m.group(1)) else m.group(0), text)
+    text = _AUTH.sub(lambda m: f"{m.group(1)}{m.group(2)}[redacted token]", text)
+    text = _EMAIL.sub("[redacted email]", text)
+    return _CARD.sub(lambda m: "[redacted card]" if _luhn(_re.sub(r"\D", "", m.group(0))) else m.group(0), text)
+
+
+def scrub_value(value, depth: int = 0):
+    if isinstance(value, str):
+        return scrub_text(value)
+    if depth > 10:
+        return "[redacted]"
+    if isinstance(value, dict):
+        return {
+            k: ("[redacted]" if is_secret_key(k) and v not in (None, "") else scrub_value(v, depth + 1))
+            for k, v in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        return [scrub_value(v, depth + 1) for v in value]
+    return value
+
+
+def _clip(value, limit):
+    return value[:limit] if isinstance(value, str) and len(value) > limit else value
+
+
+def _http_transport(timeout: float):
+    def send(url: str, event: dict) -> None:
+        data = _json.dumps(event, default=str).encode("utf-8")
+        req = _request.Request(url, data=data, method="POST", headers={"Content-Type": "application/json"})
+        with _request.urlopen(req, timeout=timeout) as res:  # noqa: S310 - the URL is the project's own ingest address
+            res.read()
+
+    return send
+
+
+class Client:
+    """A client with its own settings. Most apps use the module functions, which share one client."""
+
+    def __init__(self, ingest_url=None, release=None, environment=None, sample_rate=1.0, before_send=None,
+                 platform="python", transport=None, timeout=5.0, rand=None, background=False):
+        self.ingest_url = ingest_url
+        self.release = release
+        self.environment = environment
+        self.sample_rate = min(1.0, max(0.0, float(sample_rate)))
+        self.before_send = before_send
+        self.platform = platform
+        self.transport = transport or _http_transport(timeout)
+        self.rand = rand or _random.random
+        self.background = background
+        self._breadcrumbs: list = []
+        self._user = None
+        self._tags: dict = {}
+        self._lock = _threading.Lock()
+        self._threads: list = []
+
+    def add_breadcrumb(self, message=None, category=None, level=None, data=None):
+        crumb = scrub_value({"category": category, "message": _clip(message, 500), "level": level, "data": data})
+        crumb = {"timestamp": _dt.datetime.now(_dt.timezone.utc).isoformat(), **{k: v for k, v in crumb.items() if v is not None}}
+        with self._lock:
+            self._breadcrumbs.append(crumb)
+            del self._breadcrumbs[:-MAX_BREADCRUMBS]
+
+    def set_user(self, id=None, **_ignored):  # noqa: A002 - "id" is the public name
+        """Only an id is kept: no name, email or IP address, whatever else is passed."""
+        self._user = {"id": str(id)[:200]} if id is not None else None
+
+    def set_tag(self, key, value):
+        if isinstance(key, str) and key:
+            self._tags[key[:100]] = str(value)[:200]
+
+    def build(self, base: dict, level=None, fingerprint=None, url=None, extra=None) -> dict:
+        context = {}
+        with self._lock:
+            if self._breadcrumbs:
+                context["breadcrumbs"] = list(self._breadcrumbs)
+        if self._user:
+            context["user"] = dict(self._user)
+        if self._tags:
+            context["tags"] = dict(self._tags)
+        if isinstance(extra, dict):
+            context["extra"] = extra
+        event = dict(base)
+        event["level"] = level if level in _LEVELS else base.get("level", "error")
+        event["platform"] = self.platform
+        if self.release:
+            event["release"] = str(self.release)[:200]
+        if self.environment:
+            event["environment"] = str(self.environment)[:100]
+        if fingerprint:
+            event["fingerprint"] = str(fingerprint)[:200]
+        if url:
+            event["url"] = _re.split(r"[?#]", str(url))[0][:2000]
+        event["message"] = _clip(scrub_text(event.get("message") or ""), _MAX_MESSAGE) or "(no message)"
+        if event.get("stack"):
+            event["stack"] = _clip(scrub_text(event["stack"]), _MAX_STACK)
+        if context:
+            context = scrub_value(context)
+            # Keep within the server's 20 KB: the oldest breadcrumbs go first, then the extra data.
+            while len(_json.dumps(context, default=str)) > _MAX_CONTEXT_BYTES and context.get("breadcrumbs"):
+                context["breadcrumbs"].pop(0)
+            if len(_json.dumps(context, default=str)) > _MAX_CONTEXT_BYTES:
+                context.pop("extra", None)
+            event["context"] = context
+        return event
+
+    def _send(self, event: dict) -> bool:
+        if not self.ingest_url or self.rand() >= self.sample_rate:
+            return False
+        if self.before_send:
+            try:
+                event = self.before_send(event)
+            except Exception:  # noqa: BLE001 - reporting must never break the app
+                return False
+            if not event:
+                return False
+
+        def deliver():
+            try:
+                self.transport(self.ingest_url, event)
+                return True
+            except Exception:  # noqa: BLE001 - reporting must never break the app
+                return False
+
+        if self.background:
+            thread = _threading.Thread(target=deliver, daemon=True)
+            thread.start()
+            self._threads.append(thread)
+            return True
+        return deliver()
+
+    def capture_exception(self, exc=None, level=None, fingerprint=None, url=None, extra=None) -> bool:
+        if exc is None:
+            exc = _sys.exc_info()[1]
+        if exc is None:
+            return False
+        stack = "".join(_traceback.format_exception(type(exc), exc, exc.__traceback__))
+        base = {"type": type(exc).__name__, "message": str(exc) or type(exc).__name__, "stack": stack}
+        return self._send(self.build(base, level=level, fingerprint=fingerprint, url=url, extra=extra))
+
+    def capture_message(self, message, level="info", fingerprint=None, url=None, extra=None) -> bool:
+        return self._send(self.build({"message": str(message), "level": "info"}, level=level, fingerprint=fingerprint, url=url, extra=extra))
+
+    def flush(self, timeout: float = 2.0) -> None:
+        for thread in list(self._threads):
+            thread.join(timeout)
+        self._threads = [t for t in self._threads if t.is_alive()]
+
+
+_client = Client()
+_previous_hook = None
+
+
+def init(ingest_url, release=None, environment=None, sample_rate=1.0, before_send=None, capture_uncaught=True, **kwargs) -> Client:
+    """Sets up the shared client. capture_uncaught (default True) reports uncaught exceptions through sys.excepthook, then calls the
+    previous hook, so the program still prints the traceback and exits as it would have."""
+    global _client, _previous_hook
+    close()
+    _client = Client(ingest_url=ingest_url, release=release, environment=environment, sample_rate=sample_rate, before_send=before_send, **kwargs)
+    if capture_uncaught:
+        _previous_hook = _sys.excepthook
+
+        def hook(exc_type, exc, tb):
+            try:
+                _client.capture_exception(exc, level="fatal")
+                _client.flush()
+            finally:
+                (_previous_hook or _sys.__excepthook__)(exc_type, exc, tb)
+
+        _sys.excepthook = hook
+    return _client
+
+
+def close() -> None:
+    """Puts back the excepthook init replaced."""
+    global _previous_hook
+    if _previous_hook is not None:
+        _sys.excepthook = _previous_hook
+        _previous_hook = None
+
+
+def capture_exception(exc=None, **kwargs) -> bool:
+    return _client.capture_exception(exc, **kwargs)
+
+
+def capture_message(message, level="info", **kwargs) -> bool:
+    return _client.capture_message(message, level=level, **kwargs)
+
+
+def add_breadcrumb(message=None, category=None, level=None, data=None) -> None:
+    _client.add_breadcrumb(message=message, category=category, level=level, data=data)
+
+
+def set_user(id=None, **kwargs) -> None:  # noqa: A002
+    _client.set_user(id=id, **kwargs)
+
+
+def set_tag(key, value) -> None:
+    _client.set_tag(key, value)

aperioflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: aperioflow
+Version: 0.1.0
+Summary: Report errors from Python to AperioFlow. No dependencies.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# AperioFlow for Python
+
+Report errors from Python 3.8 or later to an AperioFlow project. No dependencies: events go to your project's ingest URL with
+`urllib`.
+
+Not on PyPI yet. Until it is, copy the `aperioflow` folder into your project.
+
+## Set up
+
+Open the project in AperioFlow, choose **Set up reporting** and copy the ingest URL.
+
+```python
+import aperioflow
+
+aperioflow.init(
+    "https://app.aperioflow.co.uk/ingest/YOUR_KEY",
+    release="1.4.0",          # optional, groups events by release and finds regressions
+    environment="production",  # optional
+)
+```
+
+After `init`, uncaught exceptions are reported through `sys.excepthook`; the previous hook still runs, so the traceback is printed and
+the program exits as before (`capture_uncaught=False` turns that off).
+
+## Report errors yourself
+
+```python
+try:
+    charge_card(order)
+except Exception as exc:
+    aperioflow.capture_exception(exc, fingerprint="card-charge", extra={"order_id": order.id})
+
+aperioflow.capture_message("Queue is backing up", level="warning")
+aperioflow.add_breadcrumb("Started nightly import", category="job")
+aperioflow.set_tag("region", "eu-west-2")
+aperioflow.set_user(id=user.id)  # only the id is sent
+```
+
+`capture_exception()` with no argument reports the exception being handled. Sends wait for the answer (5 seconds at most); pass
+`background=True` to `init` to send on a thread, and call `aperioflow._client.flush()` before the program exits.
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `ingest_url` | Required. The project's ingest URL. |
+| `release`, `environment` | Sent with every event. |
+| `sample_rate` | 0 to 1 (default 1). The share of events sent. |
+| `before_send(event)` | Change an event, or return `None` to drop it. |
+| `capture_uncaught` | Default `True`. |
+| `timeout`, `background` | How long one send may take (default 5 seconds), and whether to send on a thread. |
+
+## Privacy
+
+- Nothing about the user, the machine or its IP address is collected on its own. A user id is sent only when you call `set_user`, and
+  only the id, whatever else you pass.
+- Before an event leaves the process, values of keys that name a secret (password, token, cookie, authorization, api_key and the like),
+  Bearer and Basic credentials, email addresses and card numbers are replaced with `[redacted]` markers. The server scrubs again before
+  it stores anything.
+- Breadcrumbs are limited to the latest 50, and the event's extra data to the server's 20 KB.
+- A failed send never raises into your app.
+
+## Tests
+
+```bash
+python3 -m unittest
+```

aperioflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+aperioflow/__init__.py,sha256=y7zU8YDAHteVLw6L4NTvljIOZtvWpJbjThUnwWnGoYE,10853
+aperioflow-0.1.0.dist-info/METADATA,sha256=is2M9xPDUqJXB4UXLWuu2l636jy8rkFGS50ZfNxscwk,2933
+aperioflow-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+aperioflow-0.1.0.dist-info/top_level.txt,sha256=EFr_iOTZDBwrvwG7S6bcgax4D18_KRPZ-hVj_hb9j2U,11
+aperioflow-0.1.0.dist-info/RECORD,,

aperioflow-0.1.0.dist-info/WHEEL

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

aperioflow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aperioflow