forge-ops-tracker 0.1.0__py3-none-any.whl

forge_ops_tracker/__init__.py

@@ -0,0 +1,103 @@
+"""ForgeOps error tracking client.
+
+    import forge_ops_tracker
+    forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+See the README for Django/Flask integration and what gets captured
+automatically vs. what needs an explicit capture_exception() call.
+"""
+
+import sys
+import threading
+
+from .client import Client
+from .configuration import Configuration
+from .delivery_queue import DeliveryQueue
+from .event_builder import EventBuilder
+from .reporter import Reporter
+
+__all__ = ["Configuration", "capture_exception", "init"]
+
+_configuration = None
+_reporter = None
+_lock = threading.Lock()
+_original_excepthook = None
+
+
+def _state():
+    global _configuration, _reporter
+    if _reporter is None:
+        with _lock:
+            if _reporter is None:
+                _configuration = Configuration()
+                client = Client(_configuration)
+                delivery_queue = DeliveryQueue(_configuration, client)
+                _reporter = Reporter(_configuration, EventBuilder(_configuration), delivery_queue)
+    return _configuration, _reporter
+
+
+def init(dsn=None, **overrides):
+    """Configure the client. Call once at startup (Django settings.py, or
+    right after creating a Flask app). Any Configuration attribute can be
+    overridden by keyword, e.g. init(dsn=..., release=..., environment=...).
+    """
+    configuration, _ = _state()
+    if dsn is not None:
+        configuration.dsn = dsn
+    for key, value in overrides.items():
+        if not hasattr(configuration, key):
+            raise TypeError(f"Configuration has no attribute {key!r}")
+        setattr(configuration, key, value)
+
+    if configuration.install_excepthook:
+        _install_excepthook()
+
+    return configuration
+
+
+def capture_exception(exc=None, context=None):
+    """Report an exception you've already caught. `exc` defaults to
+    whichever exception is currently being handled, so this can usually
+    just be called as capture_exception() from inside an `except:` block."""
+    if exc is None:
+        exc = sys.exc_info()[1]
+    if exc is None:
+        return
+
+    _, reporter = _state()
+    reporter.report(exc, context=context)
+
+
+def _install_excepthook():
+    # Reports anything that crashes the whole interpreter (a plain
+    # script, a management command, a worker's own top-level loop) with
+    # no further wiring -- the same "unhandled needs no wiring" case
+    # Rails.error/ASP.NET Core's middleware cover automatically. This does
+    # *not* catch a web request's unhandled exception under a WSGI
+    # server -- Django/Flask catch that themselves before it ever reaches
+    # here, which is what the integrations in forge_ops_tracker.integrations
+    # are for.
+    global _original_excepthook
+    if _original_excepthook is not None:
+        return  # already installed
+
+    _original_excepthook = sys.excepthook
+
+    def _excepthook(exc_type, exc_value, exc_tb):
+        try:
+            capture_exception(exc_value)
+        finally:
+            _original_excepthook(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _excepthook
+
+
+def _reset_for_testing():
+    """Not part of the public API -- resets module-level state between
+    test cases."""
+    global _configuration, _reporter, _original_excepthook
+    if _original_excepthook is not None:
+        sys.excepthook = _original_excepthook
+    _configuration = None
+    _reporter = None
+    _original_excepthook = None

forge_ops_tracker/client.py

@@ -0,0 +1,41 @@
+"""Delivers one payload over HTTP. Every failure mode -- DNS, connection,
+timeout, TLS, a non-2xx response -- is caught here and turned into a
+`False` return rather than a raised exception, since a broken or
+unreachable tracker must never be able to break the host app. Ported
+from gems/forge_ops_tracker/lib/forge_ops_tracker/client.rb.
+
+Uses only the standard library (urllib), not `requests` -- same reason
+the Ruby gem uses plain Net::HTTP rather than a gem dependency: this has
+to work in any host app without adding a dependency of its own.
+"""
+
+import json
+import urllib.error
+import urllib.request
+
+
+class Client:
+    def __init__(self, configuration):
+        self._configuration = configuration
+
+    def deliver(self, payload):
+        uri = self._configuration.ingestion_uri()
+        if not uri:
+            return False
+
+        try:
+            body = json.dumps(payload).encode("utf-8")
+            request = urllib.request.Request(
+                uri,
+                data=body,
+                method="POST",
+                headers={
+                    "Authorization": f"Bearer {self._configuration.api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+            with urllib.request.urlopen(request, timeout=self._configuration.timeout) as response:
+                return 200 <= response.status < 300
+        except Exception as e:  # noqa: BLE001 -- deliberately broad: a broken/unreachable tracker must never break the host app
+            self._configuration.logger.debug("[forge_ops_tracker] delivery failed: %s: %s", type(e).__name__, e)
+            return False

forge_ops_tracker/configuration.py

@@ -0,0 +1,82 @@
+"""Holds a single ForgeOps DSN plus everything else the client needs to
+build and deliver events. Mirrors gems/forge_ops_tracker's Configuration --
+a single Sentry-style DSN string carries both the ingestion URL and the
+project's api_key: "https://<api_key>@host/api/v1/events".
+"""
+
+import logging
+import os
+import socket
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+
+class Configuration:
+    def __init__(self):
+        self.dsn = os.environ.get("FORGE_OPS_DSN")
+        self.environment = os.environ.get("FORGE_OPS_ENVIRONMENT", "development")
+        self.release = os.environ.get("FORGE_OPS_RELEASE")
+        self.server_name = _safe_hostname()
+
+        # Used to decide whether a backtrace frame is "in_app": a frame's
+        # file path is compared against this root. Unlike the .NET SDK
+        # (where a compiled assembly's file path never matches its
+        # original source location), Python runs interpreted directly
+        # from real .py files on disk, so file-path matching is the
+        # correct approach here too, same as the Ruby gem's Rails.root
+        # comparison. Defaults to the current working directory; set
+        # explicitly if that doesn't match your app's actual layout (a
+        # WSGI server started from a different directory, for instance).
+        self.app_root = os.getcwd()
+
+        self.enabled_environments = {"production", "staging"}
+        self.queue_size = 1000
+        self.timeout = 2.0  # seconds
+        self.scrub_pii = True
+        self.logger = logging.getLogger("forge_ops_tracker")
+
+        # Reports anything that crashes the whole interpreter (a plain
+        # script, a management command) with zero extra wiring, the same
+        # way an unhandled Rails/ASP.NET Core request is covered
+        # automatically elsewhere -- see _install_excepthook in __init__.py.
+        # Doesn't change program behavior (the original hook still runs
+        # afterward), so on by default is safe; set False to opt out.
+        self.install_excepthook = True
+
+    @property
+    def api_key(self):
+        parsed = self._parsed_dsn()
+        if parsed is None or not parsed.username:
+            return None
+        return unquote(parsed.username)
+
+    def ingestion_uri(self):
+        """The ingestion URL with credentials stripped out (they travel as
+        the Authorization header instead, not embedded in the request
+        URI)."""
+        parsed = self._parsed_dsn()
+        if parsed is None:
+            return None
+
+        netloc = parsed.hostname or ""
+        if parsed.port:
+            netloc = f"{netloc}:{parsed.port}"
+        return urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, ""))
+
+    def is_enabled(self):
+        return bool(self.dsn) and bool(self.api_key) and self.environment in self.enabled_environments
+
+    def _parsed_dsn(self):
+        if not self.dsn:
+            return None
+        # urlsplit never raises on malformed input (verified directly,
+        # not assumed) -- a bad DSN just parses to an empty netloc, which
+        # api_key/ingestion_uri already handle by returning None.
+        result = urlsplit(self.dsn)
+        return result if result.scheme else None
+
+
+def _safe_hostname():
+    try:
+        return socket.gethostname()
+    except Exception:  # noqa: BLE001 -- hostname lookup must never be able to crash the host app
+        return None

forge_ops_tracker/delivery_queue.py

@@ -0,0 +1,55 @@
+"""A small in-process background thread + bounded queue, so delivery
+never blocks the caller that raised the error and never depends on the
+host app having any particular job backend configured. Ported from
+gems/forge_ops_tracker/lib/forge_ops_tracker/delivery_queue.rb.
+
+The worker thread is started lazily, on first push, not at import/
+construction time -- deliberately mirroring the Ruby gem rather than the
+.NET SDK's eager start. Gunicorn (prefork) and uWSGI commonly fork worker
+processes *after* the application (and this module) has already loaded,
+which would leave an eagerly-started thread dead in every forked child --
+the exact hazard the Ruby gem's own lazy start avoids for Puma. Starting
+fresh on first push means each forked worker gets its own live thread
+regardless of when it was forked relative to import time.
+"""
+
+import queue
+import threading
+
+
+class DeliveryQueue:
+    def __init__(self, configuration, client):
+        self._configuration = configuration
+        self._client = client
+        self._queue = queue.Queue(maxsize=max(1, configuration.queue_size))
+        self._thread = None
+        self._start_lock = threading.Lock()
+
+    def push(self, payload):
+        self._ensure_worker_started()
+        try:
+            self._queue.put_nowait(payload)
+            return True
+        except queue.Full:
+            self._configuration.logger.debug("[forge_ops_tracker] delivery queue full, dropping event")
+            return False
+
+    def _ensure_worker_started(self):
+        if self._thread is not None and self._thread.is_alive():
+            return
+
+        with self._start_lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+
+    def _run(self):
+        while True:
+            payload = self._queue.get()
+            try:
+                self._client.deliver(payload)
+            except Exception as e:  # noqa: BLE001 -- per-item, so one bad delivery can't kill the worker for every event after it
+                # Per-item, not wrapping the whole loop: one bad delivery
+                # must not kill the worker for every event after it.
+                self._configuration.logger.debug("[forge_ops_tracker] delivery worker error: %s: %s", type(e).__name__, e)

forge_ops_tracker/event_builder.py

@@ -0,0 +1,88 @@
+"""Turns a raised exception into the payload shape the ingestion API
+expects. Ported from
+gems/forge_ops_tracker/lib/forge_ops_tracker/event_builder.rb --
+backtrace frames come from traceback.extract_tb rather than regex-parsing
+MRI backtrace lines, but the resulting shape (file/line/method/in_app)
+is the same.
+"""
+
+import sysconfig
+import traceback
+from datetime import datetime, timezone
+
+from . import pii_scrubber
+
+MAX_FRAMES = 500
+
+_STDLIB_PATH = sysconfig.get_path("stdlib")
+
+
+class EventBuilder:
+    def __init__(self, configuration):
+        self._configuration = configuration
+
+    def build(self, exc, context=None):
+        payload = {
+            "exception_class": _exception_class_name(exc),
+            "message": str(exc),
+            "backtrace": self._backtrace(exc),
+            "occurred_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "environment": self._configuration.environment,
+            "release": self._configuration.release,
+            "server_name": self._configuration.server_name,
+            "context": dict(context) if context else {},
+            "tags": {},
+        }
+
+        if self._configuration.scrub_pii:
+            payload = self._scrub(payload)
+
+        return payload
+
+    # exception_class/occurred_at/environment/release/server_name are left
+    # alone -- structured fields this client or the host app sets
+    # deliberately, not free text an exception or its context could
+    # accidentally spill sensitive data into.
+    def _scrub(self, payload):
+        payload = dict(payload)
+        payload["message"] = pii_scrubber.scrub_string(payload["message"])
+        payload["backtrace"] = [
+            {
+                **frame,
+                "file": pii_scrubber.scrub_string(frame["file"]) if frame["file"] else frame["file"],
+                "method": pii_scrubber.scrub_string(frame["method"]) if frame["method"] else frame["method"],
+            }
+            for frame in payload["backtrace"]
+        ]
+        payload["context"] = pii_scrubber.scrub(payload["context"])
+        payload["tags"] = pii_scrubber.scrub(payload["tags"])
+        return payload
+
+    def _backtrace(self, exc):
+        frames = traceback.extract_tb(exc.__traceback__)[:MAX_FRAMES]
+        return [
+            {
+                "file": frame.filename,
+                "line": frame.lineno,
+                "method": frame.name,
+                "in_app": self._is_in_app(frame.filename),
+            }
+            for frame in frames
+        ]
+
+    def _is_in_app(self, filename):
+        root = self._configuration.app_root
+        if not root or not filename:
+            return False
+        if not filename.startswith(root):
+            return False
+        if _STDLIB_PATH and filename.startswith(_STDLIB_PATH):
+            return False
+        return "site-packages" not in filename and "dist-packages" not in filename
+
+
+def _exception_class_name(exc):
+    cls = type(exc)
+    if cls.__module__ in ("builtins", "__main__"):
+        return cls.__name__
+    return f"{cls.__module__}.{cls.__name__}"

forge_ops_tracker/integrations/django.py

@@ -0,0 +1,37 @@
+"""Django middleware. Add to MIDDLEWARE in settings.py:
+
+    MIDDLEWARE = [
+        ...,
+        "forge_ops_tracker.integrations.django.ForgeOpsTrackerMiddleware",
+    ]
+
+Not imported by forge_ops_tracker/__init__.py -- Django is an optional
+dependency, so importing this submodule specifically is what pulls it in,
+rather than every forge_ops_tracker user needing Django installed.
+"""
+
+from .. import capture_exception
+
+
+class ForgeOpsTrackerMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        return self.get_response(request)
+
+    def process_exception(self, request, exception):
+        # Reports, then returns None -- Django's own exception handling
+        # (DEBUG page, a custom handler500, whatever's configured) behaves
+        # exactly as if this middleware weren't installed. Only fires for
+        # an exception that actually escaped the view uncaught; anything
+        # your own code already catches never reaches here at all.
+        capture_exception(exception, context=_request_context(request))
+
+
+def _request_context(request):
+    return {
+        "path": request.path,
+        "method": request.method,
+        "query_string": request.META.get("QUERY_STRING", ""),
+    }

forge_ops_tracker/integrations/flask.py

@@ -0,0 +1,40 @@
+"""Flask integration. Call once after creating the app:
+
+    from forge_ops_tracker.integrations.flask import init_flask
+    app = Flask(__name__)
+    init_flask(app)
+
+Not imported by forge_ops_tracker/__init__.py -- Flask is an optional
+dependency, so importing this submodule specifically is what pulls it
+in, rather than every forge_ops_tracker user needing Flask installed.
+"""
+
+from flask import request
+from flask.signals import got_request_exception
+
+from .. import capture_exception
+
+
+def init_flask(app):
+    def _handle(sender, exception, **extra):
+        # Fires for a view's unhandled exception regardless of whether
+        # Flask's own error handling ultimately produces a response --
+        # reporting here doesn't change how Flask handles it afterward.
+        # Only fires for an exception that actually escaped the view
+        # uncaught; anything your own code already catches never reaches
+        # here at all.
+        capture_exception(exception, context=_request_context())
+
+    got_request_exception.connect(_handle, app)
+    # Blinker (Flask's signal library) uses weak references by default --
+    # keep a strong reference on the app itself so this handler isn't
+    # garbage collected right after init_flask returns.
+    app._forge_ops_tracker_signal_handler = _handle
+
+
+def _request_context():
+    return {
+        "path": request.path,
+        "method": request.method,
+        "query_string": request.query_string.decode("utf-8", "replace"),
+    }

forge_ops_tracker/pii_scrubber.py

@@ -0,0 +1,67 @@
+"""Redacts likely-sensitive content out of a payload before it ever leaves
+this process -- the same patterns ForgeOps itself applies again on
+arrival (defense in depth: this layer keeps the data off the wire and out
+of any request logging in between; the server-side layer is what actually
+protects the database, and doesn't depend on every reporting app running
+an up-to-date version of this client). Ported from
+gems/forge_ops_tracker/lib/forge_ops_tracker/pii_scrubber.rb -- kept
+standalone and dependency-free here for the same reason as the Ruby
+original: this has to work in any host app regardless of what's reporting
+into it.
+
+Can be turned off via Configuration.scrub_pii = False for a host app that
+already scrubs its own data before it ever reaches exception context, or
+that has its own reasons to want the raw payload. Off by default is not
+an option: the safe default has to be "on."
+"""
+
+import re
+
+REDACTED = "[FILTERED]"
+
+SENSITIVE_KEYS = {
+    "password", "passwd", "pwd",
+    "secret", "apisecret", "clientsecret", "secretkey",
+    "token", "accesstoken", "refreshtoken", "apikey", "apitoken", "authorization", "authtoken", "bearer",
+    "sessiontoken", "csrftoken",
+    "creditcard", "cardnumber", "cardnum", "cvv", "cvv2", "cvc",
+    "ssn", "socialsecuritynumber", "socialsecurity",
+    "privatekey",
+}
+
+_PATTERNS = (
+    ("EMAIL", re.compile(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")),
+    ("SSN", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
+    ("CREDIT CARD", re.compile(r"\b\d{4}[ -]\d{4}[ -]\d{4}[ -]\d{1,4}\b")),
+    ("BEARER TOKEN", re.compile(r"\bBearer\s+[A-Za-z0-9\-._~+/]+=*", re.IGNORECASE)),
+    ("JWT", re.compile(r"\bey[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b")),
+    ("AWS KEY", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("STRIPE KEY", re.compile(r"\b[sr]k_(?:live|test)_[A-Za-z0-9]{10,}\b")),
+    ("GITHUB TOKEN", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b")),
+)
+
+
+def scrub(value, key=None):
+    if _is_sensitive_key(key) and value is not None:
+        return REDACTED
+
+    if isinstance(value, dict):
+        return {k: scrub(v, key=k) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [scrub(v, key=key) for v in value]
+    if isinstance(value, str):
+        return scrub_string(value)
+    return value
+
+
+def scrub_string(text):
+    for label, pattern in _PATTERNS:
+        text = pattern.sub(f"[{label} FILTERED]", text)
+    return text
+
+
+def _is_sensitive_key(key):
+    if not key:
+        return False
+    normalized = "".join(ch for ch in str(key).lower() if ch.isalnum())
+    return any(sensitive in normalized for sensitive in SENSITIVE_KEYS)

forge_ops_tracker/reporter.py

@@ -0,0 +1,24 @@
+"""Ties Configuration, EventBuilder, and DeliveryQueue together into the
+one thing callers actually need: report an exception. Mirrors
+gems/forge_ops_tracker's ErrorSubscriber#report -- never raises. An error
+reporter that itself raises while reporting an error is the worst
+possible failure mode, so every path here is wrapped to guarantee this
+never propagates back into the host app.
+"""
+
+
+class Reporter:
+    def __init__(self, configuration, event_builder, delivery_queue):
+        self._configuration = configuration
+        self._event_builder = event_builder
+        self._delivery_queue = delivery_queue
+
+    def report(self, exc, context=None):
+        try:
+            if not self._configuration.is_enabled():
+                return
+
+            payload = self._event_builder.build(exc, context=context)
+            self._delivery_queue.push(payload)
+        except Exception as e:  # noqa: BLE001 -- deliberately broad: this must never raise back into the host app
+            self._configuration.logger.debug("[forge_ops_tracker] report failed: %s: %s", type(e).__name__, e)

forge_ops_tracker-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: forge-ops-tracker
+Version: 0.1.0
+Summary: ForgeOps error tracking client: captures unhandled exceptions (Django/Flask middleware, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP.
+Author: ForgeOps
+License-Expression: MIT
+Project-URL: Homepage, https://getforgeops.net
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Logging
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == "flask"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-django>=4.8; extra == "test"
+Requires-Dist: flask>=2.3; extra == "test"
+Requires-Dist: django>=4.2; extra == "test"
+Dynamic: license-file
+
+# forge-ops-tracker
+
+Python error reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
+Requires Python 3.9+. A from-scratch port of [`gems/forge_ops_tracker`](../../gems/forge_ops_tracker)
+(the Rails client) -- see that gem's README for the shared design rationale; this document only
+covers what's Python-specific.
+
+## Installation
+
+Not yet published to PyPI -- install directly from this path (or a local checkout, once split into
+its own repo):
+
+```bash
+pip install -e path/to/forge_ops/sdks/python
+```
+
+For Django or Flask integration, install the matching extra:
+
+```bash
+pip install -e "path/to/forge_ops/sdks/python[django]"
+pip install -e "path/to/forge_ops/sdks/python[flask]"
+```
+
+## Configuration
+
+Set a DSN (from a project's settings page in ForgeOps), either via the `FORGE_OPS_DSN` environment
+variable or explicitly:
+
+```python
+import forge_ops_tracker
+
+forge_ops_tracker.init(
+    dsn="https://<api_key>@your-forgeops-host/api/v1/events",  # or leave unset to read FORGE_OPS_DSN
+    release="...",
+    environment="production",
+)
+```
+
+Call `init()` once at startup -- Django's `settings.py`, or right after creating a Flask app. Any
+`Configuration` attribute can be overridden by keyword.
+
+### Django
+
+```python
+# settings.py
+import forge_ops_tracker
+
+forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+MIDDLEWARE = [
+    ...,
+    "forge_ops_tracker.integrations.django.ForgeOpsTrackerMiddleware",
+]
+```
+
+### Flask
+
+```python
+from flask import Flask
+import forge_ops_tracker
+from forge_ops_tracker.integrations.flask import init_flask
+
+forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+app = Flask(__name__)
+init_flask(app)
+```
+
+## What gets reported automatically, and what doesn't
+
+**An exception that crashes a request needs no further wiring at all.** The Django middleware's
+`process_exception` hook and Flask's `got_request_exception` signal both fire for anything that
+propagates uncaught out of a view, then let the framework handle it exactly as if this client
+weren't installed.
+
+**An exception your own code catches and handles is different -- neither integration ever sees
+it**, since it never propagates far enough to reach either hook:
+
+```python
+try:
+    charge_card(order)
+except CardError as e:
+    logger.warning("card declined: %s", e)
+    # ForgeOps never sees this -- caught locally, never reaches the
+    # middleware/signal at all.
+```
+
+There's no Django/Flask-wide equivalent to Rails' `Rails.error.handle` here -- report it explicitly
+instead, right at the catch site:
+
+```python
+except CardError as e:
+    forge_ops_tracker.capture_exception(e, context={"order_id": order.id})
+    logger.warning("card declined: %s", e)
+```
+
+Called with no arguments, `capture_exception()` picks up whichever exception is currently being
+handled (same as a bare `raise` inside an `except:` block), so it usually reads as just
+`forge_ops_tracker.capture_exception()` from inside the block that already caught it.
+
+### Outside a web request (scripts, management commands, workers)
+
+`init()` also installs a `sys.excepthook` wrapper by default (`Configuration.install_excepthook`,
+`True` unless set otherwise), which reports anything that crashes the whole interpreter -- a plain
+script, a Django management command, a worker's own top-level loop -- with no wiring needed, the
+same "unhandled needs no wiring" case the Django/Flask integrations cover for web requests. It
+still calls whatever `sys.excepthook` was already installed afterward, so it never changes program
+behavior. This does **not** catch a web request's unhandled exception under a real WSGI server
+(Gunicorn/uWSGI catch that themselves per-request, long before it would ever reach the interpreter
+level) -- that's what the Django/Flask integrations are for.
+
+Delivery happens on a background thread with a bounded queue and a short per-request HTTP timeout
+(`Configuration.timeout`, 2s default). Every failure mode -- network errors, timeouts, a full queue,
+a malformed DSN -- is caught and dropped rather than raised, so a broken or unreachable tracker can
+never take down the host app. The worker thread starts lazily, on first push, not at import time --
+Gunicorn (prefork) and uWSGI commonly fork worker processes *after* the application has already
+loaded, which would leave an eagerly-started thread dead in every forked child; starting fresh on
+first push means each forked worker gets its own live thread regardless of when it was forked
+relative to import.
+
+## `in_app` backtrace frames
+
+Unlike the .NET SDK (where a compiled assembly's file path never matches its original source
+location), Python runs interpreted directly from real `.py` files on disk, so file-path matching
+against `Configuration.app_root` works the same way it does in the Ruby gem's `Rails.root`
+comparison. Defaults to the current working directory; set it explicitly if that doesn't match your
+app's actual layout (a WSGI server started from a different directory than your app's root, for
+instance). Standard-library and installed-package (`site-packages`/`dist-packages`) frames are
+never marked `in_app`, regardless of `app_root`.
+
+## PII scrubbing
+
+Same behavior as the Ruby gem: the message, backtrace, and any context/tags you attach are scanned
+for likely personal data -- email addresses, formatted SSNs/credit cards, known API key/token
+formats, and anything under a suspiciously-named key (`password`, `api_key`, `ssn`, and similar) --
+and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival
+regardless, so this is a second, earlier layer, not the only one.
+
+To disable it:
+
+```python
+forge_ops_tracker.init(dsn="...", scrub_pii=False)
+```
+
+## Running the tests
+
+```bash
+cd sdks/python
+python3 -m venv .venv
+./.venv/bin/pip install -e ".[test]"
+./.venv/bin/python -m pytest
+./.venv/bin/ruff check src tests
+```

forge_ops_tracker-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+forge_ops_tracker/__init__.py,sha256=JMaWtRDUCJChTU6l4I6V3mx6zuhzJF3MyfHvlhvTe04,3422
+forge_ops_tracker/client.py,sha256=ozwtvEoFCfZhCulU1CPcxJCsPNuNzr5lS7_ez8ZAVNg,1638
+forge_ops_tracker/configuration.py,sha256=shHovnBAoyT6E9NR_AYgCqhUpKNs93GYq7v_HC87JSo,3373
+forge_ops_tracker/delivery_queue.py,sha256=0KPvTb0soojKgT5S_sBsyLL2L-GsOUo-VlyipFqU1ug,2361
+forge_ops_tracker/event_builder.py,sha256=ge3_2warzzU6QLjFx0VYfGvUgDTk7_Y8TBZvoDluQk0,3072
+forge_ops_tracker/pii_scrubber.py,sha256=J-1AdYR6uauE8Qfl_OYH7tUG-h5-lCVo4FIzG2gLqaw,2648
+forge_ops_tracker/reporter.py,sha256=CHhxHyHSEc0F3BzSYc8d1_pImn649no1c-MH6eYCM9o,1088
+forge_ops_tracker/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+forge_ops_tracker/integrations/django.py,sha256=368U_Ve5qcRyNxpXgM9HLbzLtwyTX5faPRsVeIVD42Q,1276
+forge_ops_tracker/integrations/flask.py,sha256=Sxrd5wr7u_TzBSZ2FgV0WhgHfdKZZ_DSdDpAvOzfHjU,1486
+forge_ops_tracker-0.1.0.dist-info/licenses/LICENSE.txt,sha256=hw7Ta2pN2nuLxH7hM_WS3-8-7uVVeT7gHRAoTqVk8lo,1065
+forge_ops_tracker-0.1.0.dist-info/METADATA,sha256=xwlo7yQy1kM7aKojN_7WbJbbK_JeNsai7JUaKtKIk6o,6908
+forge_ops_tracker-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+forge_ops_tracker-0.1.0.dist-info/top_level.txt,sha256=XhRWmUGp5jtH249ix2hvGJ_8LJbu1F_jFtU4CsPW1KY,18
+forge_ops_tracker-0.1.0.dist-info/RECORD,,

forge_ops_tracker-0.1.0.dist-info/WHEEL

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

forge_ops_tracker-0.1.0.dist-info/licenses/LICENSE.txt

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

forge_ops_tracker-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+forge_ops_tracker