debugbundle-python 0.1.5__py3-none-any.whl → 0.1.8__py3-none-any.whl

debugbundle/integrations/__init__.py

@@ -1,9 +1,24 @@
-from .django import DebugBundleDjangoMiddleware
-from .fastapi import DebugBundleFastAPIMiddleware, instrument_fastapi
-from .flask import instrument_flask
-from .relay_django import create_django_relay_view
-from .relay_fastapi import create_fastapi_relay_handler
-from .relay_flask import create_flask_relay_handler
+import importlib
+from typing import Any
+
+_OPTIONAL_EXPORTS = {
+    "DebugBundleDjangoMiddleware": (".django", "DebugBundleDjangoMiddleware"),
+    "DebugBundleFastAPIMiddleware": (".fastapi", "DebugBundleFastAPIMiddleware"),
+    "create_django_relay_view": (".relay_django", "create_django_relay_view"),
+    "create_fastapi_relay_handler": (".relay_fastapi", "create_fastapi_relay_handler"),
+    "create_flask_relay_handler": (".relay_flask", "create_flask_relay_handler"),
+    "instrument_fastapi": (".fastapi", "instrument_fastapi"),
+    "instrument_flask": (".flask", "instrument_flask"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _OPTIONAL_EXPORTS:
+        raise AttributeError(f"module 'debugbundle.integrations' has no attribute {name!r}")
+
+    module_name, attribute_name = _OPTIONAL_EXPORTS[name]
+    module = importlib.import_module(module_name, __name__)
+    return getattr(module, attribute_name)
 
 __all__ = [
     "DebugBundleDjangoMiddleware",

debugbundle/integrations/relay_django.py

@@ -11,12 +11,30 @@ def create_django_relay_view(
     max_body_bytes: int = 262_144,
     rate_limit_per_minute: int = 60,
     on_accept: Any = None,
+    project_mode: str | None = None,
+    project_token: str | None = None,
+    endpoint: str | None = None,
+    local_events_dir: str | None = None,
+    spool_dir: str | None = None,
+    durable_write: bool = True,
+    service: str | None = None,
+    environment: str | None = None,
+    forward_transport: Any = None,
 ) -> Any:
     handler = BrowserRelayHandler(
         allowed_origins=allowed_origins or [],
         max_body_bytes=max_body_bytes,
         rate_limit_per_minute=rate_limit_per_minute,
         on_accept=on_accept,
+        project_mode=project_mode,
+        project_token=project_token,
+        endpoint=endpoint,
+        local_events_dir=local_events_dir,
+        spool_dir=spool_dir,
+        durable_write=durable_write,
+        service=service,
+        environment=environment,
+        forward_transport=forward_transport,
     )
 
     def view(request: Any) -> Any:

debugbundle/integrations/relay_fastapi.py

@@ -14,6 +14,15 @@ def create_fastapi_relay_handler(
     max_body_bytes: int = 262_144,
     rate_limit_per_minute: int = 60,
     on_accept: Any = None,
+    project_mode: str | None = None,
+    project_token: str | None = None,
+    endpoint: str | None = None,
+    local_events_dir: str | None = None,
+    spool_dir: str | None = None,
+    durable_write: bool = True,
+    service: str | None = None,
+    environment: str | None = None,
+    forward_transport: Any = None,
     route_path: str = "/debugbundle/browser",
 ) -> Any:
     handler = BrowserRelayHandler(
@@ -21,6 +30,15 @@ def create_fastapi_relay_handler(
         max_body_bytes=max_body_bytes,
         rate_limit_per_minute=rate_limit_per_minute,
         on_accept=on_accept,
+        project_mode=project_mode,
+        project_token=project_token,
+        endpoint=endpoint,
+        local_events_dir=local_events_dir,
+        spool_dir=spool_dir,
+        durable_write=durable_write,
+        service=service,
+        environment=environment,
+        forward_transport=forward_transport,
     )
 
     def register(app: Any) -> None:

debugbundle/integrations/relay_flask.py

@@ -11,6 +11,15 @@ def create_flask_relay_handler(
     max_body_bytes: int = 262_144,
     rate_limit_per_minute: int = 60,
     on_accept: Any = None,
+    project_mode: str | None = None,
+    project_token: str | None = None,
+    endpoint: str | None = None,
+    local_events_dir: str | None = None,
+    spool_dir: str | None = None,
+    durable_write: bool = True,
+    service: str | None = None,
+    environment: str | None = None,
+    forward_transport: Any = None,
     route_path: str = "/debugbundle/browser",
 ) -> Any:
     handler = BrowserRelayHandler(
@@ -18,6 +27,15 @@ def create_flask_relay_handler(
         max_body_bytes=max_body_bytes,
         rate_limit_per_minute=rate_limit_per_minute,
         on_accept=on_accept,
+        project_mode=project_mode,
+        project_token=project_token,
+        endpoint=endpoint,
+        local_events_dir=local_events_dir,
+        spool_dir=spool_dir,
+        durable_write=durable_write,
+        service=service,
+        environment=environment,
+        forward_transport=forward_transport,
     )
 
     def register(app: Any) -> None:

debugbundle/relay.py

@@ -2,10 +2,18 @@ from __future__ import annotations
 
 import json
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from typing import Any
 
+from .relay_delivery import (
+    AtomicRelayFileTransport,
+    RelayForwardTransport,
+    mark_spool_file_delivered,
+    resolve_default_local_events_dir,
+    resolve_default_relay_spool_dir,
+)
+
 DEFAULT_MAX_BODY_BYTES = 262_144
 DEFAULT_RATE_LIMIT_PER_MINUTE = 60
 BROWSER_SDK_NAME = "@debugbundle/sdk-browser"
@@ -41,12 +49,32 @@ class BrowserRelayHandler:
     max_body_bytes: int = DEFAULT_MAX_BODY_BYTES
     rate_limit_per_minute: int = DEFAULT_RATE_LIMIT_PER_MINUTE
     on_accept: Callable[[BrowserRelayAcceptedBatch], None] | None = None
+    project_mode: str | None = None
+    project_token: str | None = None
+    endpoint: str | None = None
+    local_events_dir: str | None = None
+    spool_dir: str | None = None
+    durable_write: bool = True
+    service: str | None = None
+    environment: str | None = None
+    forward_transport: Callable[[Mapping[str, object]], object] | None = None
 
     def __post_init__(self) -> None:
         self.allowed_origins = [o for o in self.allowed_origins if o]
         self.max_body_bytes = max(1, self.max_body_bytes)
         self.rate_limit_per_minute = max(1, self.rate_limit_per_minute)
+        normalized_project_mode = (self.project_mode or "").strip().lower()
+        self.project_mode = normalized_project_mode or None
+        if self.project_mode not in {None, "connected", "local-only"}:
+            self.project_mode = None
         self._rate_limit_state: dict[str, list[int]] = {}
+        self._local_transports: dict[str, AtomicRelayFileTransport] = {}
+        self._spool_transports: dict[str, AtomicRelayFileTransport] = {}
+        self._forwarder = (
+            RelayForwardTransport(self.endpoint, self.forward_transport)
+            if self.project_mode == "connected" and self.endpoint is not None
+            else None
+        )
 
     def handle(self, request: dict[str, Any]) -> BrowserRelayResponse:
         method = str(request.get("method", "POST")).upper()
@@ -106,22 +134,29 @@ class BrowserRelayHandler:
                 errors.append(f"batch[{index}]: Unsupported browser relay event type {type_label}.")
                 continue
 
-            sanitized = _sanitize_event(candidate)
+            sanitized = _sanitize_event(candidate, service_override=self.service, environment_override=self.environment)
             if sanitized is None:
                 errors.append(f"batch[{index}]: Invalid browser relay event payload.")
                 continue
 
             accepted_events.append(sanitized)
 
-        if accepted_events and self.on_accept is not None:
-            self.on_accept(
-                BrowserRelayAcceptedBatch(
-                    events=accepted_events,
-                    headers=_strip_sensitive_headers(headers),
-                    ip_address=ip_address,
-                    received_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
-                )
-            )
+        if accepted_events:
+            try:
+                if not self._deliver_events(accepted_events):
+                    return BrowserRelayResponse(500)
+
+                if self.on_accept is not None:
+                    self.on_accept(
+                        BrowserRelayAcceptedBatch(
+                            events=accepted_events,
+                            headers=_strip_sensitive_headers(headers),
+                            ip_address=ip_address,
+                            received_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                        )
+                    )
+            except Exception:
+                return BrowserRelayResponse(500)
 
         if errors:
             return BrowserRelayResponse(
@@ -134,6 +169,54 @@ class BrowserRelayHandler:
             {"accepted": len(accepted_events), "rejected": 0, "errors": []},
         )
 
+    def _deliver_events(self, accepted_events: list[dict[str, Any]]) -> bool:
+        if self.project_mode is None:
+            return True
+
+        service_name = self.service or str(accepted_events[0]["service"]["name"])
+
+        if self.project_mode == "local-only":
+            local_transport = self._local_transports.get(service_name)
+            if local_transport is None:
+                local_transport = AtomicRelayFileTransport(
+                    self.local_events_dir or resolve_default_local_events_dir(),
+                    service_name,
+                )
+                self._local_transports[service_name] = local_transport
+
+            return local_transport.write(accepted_events).status_code == 202
+
+        if self.project_mode != "connected":
+            return True
+
+        if self.durable_write:
+            spool_transport = self._spool_transports.get(service_name)
+            if spool_transport is None:
+                spool_transport = AtomicRelayFileTransport(
+                    self.spool_dir or resolve_default_relay_spool_dir(),
+                    service_name,
+                )
+                self._spool_transports[service_name] = spool_transport
+
+            spool_write_result = spool_transport.write(accepted_events)
+            if spool_write_result.status_code != 202:
+                return False
+
+            configured, succeeded = self._forward_connected_events(accepted_events)
+            if succeeded and spool_write_result.written_file_path is not None:
+                mark_spool_file_delivered(spool_write_result.written_file_path)
+
+            return True if configured or spool_write_result.written_file_path is not None else False
+
+        configured, succeeded = self._forward_connected_events(accepted_events)
+        return configured and succeeded
+
+    def _forward_connected_events(self, accepted_events: list[dict[str, Any]]) -> tuple[bool, bool]:
+        if self._forwarder is None or not self.project_token:
+            return (False, False)
+
+        return self._forwarder.send(self.project_token, accepted_events)
+
     def _is_origin_allowed(self, headers: dict[str, str]) -> bool:
         origin = _source_origin(headers)
         if origin is None:
@@ -210,7 +293,11 @@ def _strip_sensitive_headers(headers: dict[str, str]) -> dict[str, str]:
     return sanitized
 
 
-def _sanitize_event(event: dict[str, Any]) -> dict[str, Any] | None:
+def _sanitize_event(
+    event: dict[str, Any],
+    service_override: str | None = None,
+    environment_override: str | None = None,
+) -> dict[str, Any] | None:
     schema_version = event.get("schema_version")
     event_id = event.get("event_id")
     event_type = event.get("event_type")
@@ -239,6 +326,11 @@ def _sanitize_event(event: dict[str, Any]) -> dict[str, Any] | None:
     if not isinstance(service_name, str) or not service_name or not isinstance(environment, str) or not environment:
         return None
 
+    normalized_service_name = service_override or service_name
+    normalized_environment = environment_override or environment
+    if not normalized_service_name or not normalized_environment:
+        return None
+
     sanitized: dict[str, Any] = {
         "schema_version": schema_version,
         "event_id": event_id,
@@ -247,16 +339,29 @@ def _sanitize_event(event: dict[str, Any]) -> dict[str, Any] | None:
         "sdk_name": BROWSER_SDK_NAME,
         "sdk_version": sdk_version,
         "service": {
-            "name": service_name,
-            "environment": environment,
+            "name": normalized_service_name,
+            "environment": normalized_environment,
         },
         "payload": payload,
     }
 
+    runtime = service.get("runtime")
+    if isinstance(runtime, str) or runtime is None:
+        sanitized["service"]["runtime"] = runtime
+
+    framework = service.get("framework")
+    if isinstance(framework, str) or framework is None:
+        sanitized["service"]["framework"] = framework
+
     correlation = event.get("correlation")
     if isinstance(correlation, dict):
-        trace_id = correlation.get("trace_id")
-        if isinstance(trace_id, str) or trace_id is None:
-            sanitized["correlation"] = {"trace_id": trace_id}
+        normalized_correlation: dict[str, Any] = {}
+        for key in ("request_id", "trace_id", "session_id", "user_id_hash"):
+            value = correlation.get(key)
+            if isinstance(value, str) or value is None:
+                normalized_correlation[key] = value
+
+        if normalized_correlation:
+            sanitized["correlation"] = normalized_correlation
 
     return sanitized

debugbundle/relay_delivery.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import threading
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .transport import HttpTransport, coerce_transport_response
+
+LOCAL_EVENTS_DIRECTORY_MODE = 0o700
+LOCAL_EVENT_FILE_MODE = 0o600
+RELAY_SPOOL_DELIVERED_MARKER_SUFFIX = ".delivered"
+OPTIONAL_NOFOLLOW_FLAG = getattr(os, "O_NOFOLLOW", 0)
+
+
+@dataclass(frozen=True)
+class RelayWriteResult:
+    status_code: int
+    written_file_path: str | None = None
+
+
+def resolve_default_local_events_dir(cwd: str | None = None) -> str:
+    return os.path.join(cwd or os.getcwd(), ".debugbundle", "local", "events")
+
+
+def resolve_default_relay_spool_dir(cwd: str | None = None) -> str:
+    return os.path.join(cwd or os.getcwd(), ".debugbundle", "local", "browser-relay-spool")
+
+
+def attach_project_token(events: list[dict[str, Any]], project_token: str) -> list[dict[str, Any]]:
+    return [{**event, "project_token": project_token} for event in events]
+
+
+def mark_spool_file_delivered(written_file_path: str) -> None:
+    try:
+        with open(f"{written_file_path}{RELAY_SPOOL_DELIVERED_MARKER_SUFFIX}", "w", encoding="utf-8"):
+            pass
+    except OSError:
+        # Durable acceptance already happened at the spool write; marker creation is maintenance metadata only.
+        return
+
+
+class AtomicRelayFileTransport:
+    def __init__(self, events_dir: str, service_name: str) -> None:
+        self._events_dir = os.path.abspath(os.path.normpath(events_dir))
+        self._service_name = _sanitize_service_name(service_name)
+        self._sequence = 0
+        self._dir_ensured = False
+        self._lock = threading.Lock()
+
+    def write(self, events: list[dict[str, Any]]) -> RelayWriteResult:
+        if not events:
+            return RelayWriteResult(status_code=202)
+
+        try:
+            with self._lock:
+                if not self._dir_ensured:
+                    os.makedirs(self._events_dir, mode=LOCAL_EVENTS_DIRECTORY_MODE, exist_ok=True)
+                    self._dir_ensured = True
+
+                timestamp = int(time.time() * 1000)
+                self._sequence += 1
+                filename = f"{timestamp}-{self._sequence}-{self._service_name}.events.json"
+                final_path = os.path.join(self._events_dir, filename)
+                tmp_path = f"{final_path}.tmp-{secrets.token_hex(8)}"
+
+                _assert_not_symlink(final_path)
+                _write_secure_temp_file(tmp_path, json.dumps(events, separators=(",", ":")))
+                os.replace(tmp_path, final_path)
+                return RelayWriteResult(status_code=202, written_file_path=final_path)
+        except OSError:
+            _cleanup_temp_files(self._events_dir)
+            return RelayWriteResult(status_code=500)
+
+
+class RelayForwardTransport:
+    def __init__(self, endpoint: str, transport: Callable[[Mapping[str, object]], object] | None = None) -> None:
+        self._transport = transport or HttpTransport(endpoint)
+
+    def send(self, project_token: str, events: list[dict[str, Any]]) -> tuple[bool, bool]:
+        if not project_token:
+            return (False, False)
+
+        try:
+            response = coerce_transport_response(
+                self._transport(
+                    {
+                        "project_token": project_token,
+                        "events": attach_project_token(events, project_token),
+                    }
+                )
+            )
+        except Exception:
+            return (True, False)
+
+        return (True, 200 <= response.status_code < 300)
+
+
+def _sanitize_service_name(service_name: str) -> str:
+    normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", service_name.strip())
+    normalized = re.sub(r"-+", "-", normalized).strip("-")
+    return normalized or "service"
+
+
+def _assert_not_symlink(target_path: str) -> None:
+    try:
+        if os.path.islink(target_path):
+            raise OSError("symlink_path_rejected")
+    except OSError:
+        raise
+
+
+def _write_secure_temp_file(tmp_path: str, payload: str) -> None:
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | OPTIONAL_NOFOLLOW_FLAG
+    encoded = payload.encode("utf-8")
+    fd = os.open(tmp_path, flags, LOCAL_EVENT_FILE_MODE)
+    try:
+        os.write(fd, encoded)
+    finally:
+        os.close(fd)
+
+
+def _cleanup_temp_files(events_dir: str) -> None:
+    try:
+        for entry in os.listdir(events_dir):
+            if ".tmp-" not in entry:
+                continue
+            try:
+                os.remove(os.path.join(events_dir, entry))
+            except OSError:
+                continue
+    except OSError:
+        return

debugbundle_python-0.1.8.dist-info/METADATA

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: debugbundle-python
+Version: 0.1.8
+Summary: DebugBundle SDK for Python
+Author: DebugBundle
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://debugbundle.com/docs/sdks/python
+Project-URL: Repository, https://github.com/debugbundle/debugbundle-python
+Project-URL: Issues, https://github.com/debugbundle/debugbundle-python/issues
+Keywords: debugbundle,debugging,ai-agent,error-tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.27
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: django<6,>=5; extra == "dev"
+Requires-Dist: fastapi<1,>=0.115; extra == "dev"
+Requires-Dist: flask<4,>=3; extra == "dev"
+Requires-Dist: jsonschema<5,>=4.23; extra == "dev"
+Requires-Dist: loguru<1,>=0.7; extra == "dev"
+Requires-Dist: mypy<2,>=1.15; extra == "dev"
+Requires-Dist: pytest<9,>=8.3; extra == "dev"
+Requires-Dist: pytest-cov<7,>=5; extra == "dev"
+Requires-Dist: ruff<0.12,>=0.11; extra == "dev"
+Requires-Dist: structlog<26,>=24; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Dynamic: license-file
+
+# debugbundle-python
+
+Python SDK for DebugBundle.
+
+![PyPI](https://img.shields.io/pypi/v/debugbundle-python?label=pypi)
+![CI](https://img.shields.io/github/actions/workflow/status/debugbundle/debugbundle-python/ci.yml?branch=main&label=ci)
+![License](https://img.shields.io/badge/license-AGPL--3.0--only-blue)
+
+Use this package to capture Python backend exceptions, request metadata, structured logs, runtime context, and probe data. It supports vanilla Python plus Django, Flask, FastAPI, Python logging, structlog, loguru, and browser relay helpers.
+
+Requires Python 3.10 or newer.
+
+## Installation
+
+```bash
+pip install debugbundle-python
+```
+
+Install the SDK alongside the framework you actually run:
+
+```bash
+pip install debugbundle-python django
+pip install debugbundle-python flask
+pip install debugbundle-python fastapi uvicorn
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import os
+import debugbundle
+
+debugbundle.init(
+    project_token=os.environ["DEBUGBUNDLE_PROJECT_TOKEN"],
+    service="checkout-api",
+    environment="production",
+)
+
+debugbundle.capture_exceptions()
+debugbundle.capture_logging()
+```
+
+Capture handled errors, logs, messages, and probes explicitly:
+
+```python
+debugbundle.capture_exception(error)
+debugbundle.capture_log("payment retry failed", level="warning", context={"order_id": order_id})
+debugbundle.capture_message("worker started")
+debugbundle.probe("checkout.cart", {"item_count": len(cart.items)})
+
+debugbundle.flush()
+```
+
+## Framework Integrations
+
+| Framework | Integration |
+| --- | --- |
+| Django | `DebugBundleDjangoMiddleware` |
+| Flask | `instrument_flask(app)` |
+| FastAPI | `DebugBundleFastAPIMiddleware` or `instrument_fastapi(app)` |
+| Python logging | `capture_logging()` |
+| asyncio | `capture_async()` |
+| structlog/loguru | Auto-detected when log capture is enabled and the libraries are installed |
+
+## Browser Relay
+
+Python backends can host the browser relay endpoint used by `@debugbundle/sdk-browser`.
+
+| Framework | Helper |
+| --- | --- |
+| Django | `create_django_relay_view()` |
+| Flask | `create_flask_relay_handler()` |
+| FastAPI | `create_fastapi_relay_handler()` |
+
+The relay validates JSON batches, enforces same-origin or allowed origins, strips trust-sensitive browser fields, keeps the server-side project token private, and supports both local-only file writes and connected forwarding.
+
+Relay defaults and limits:
+
+- Same-origin requests are allowed by default when `allowed_origins` is omitted.
+- Split frontend/backend deployments should set explicit `allowed_origins` values.
+- Relay requests must use `Content-Type: application/json` and stay below `max_body_bytes` (default `262144`).
+- Relay rate limiting defaults to `60` requests per IP per minute.
+- `project_mode="local-only"` writes accepted browser events to `.debugbundle/local/events` or your configured `local_events_dir`.
+- `project_mode="connected"` writes durable spool files by default and forwards with the server-side `project_token` only.
+- Leaving relay `project_mode` unset disables local writes and forwarding; accepted batches are only surfaced through `on_accept`.
+- Connected relay mode without a usable `project_token` keeps accepting and optionally spooling events, but forwarding remains disabled until the server provides credentials.
+
+## Configuration Reference
+
+Configuration sources and precedence:
+
+- The SDK only reads the keyword arguments passed to `debugbundle.init(...)`.
+- Environment variables, Django settings, Flask config, or FastAPI settings are convenience sources that your application maps into `debugbundle.init(...)`; the SDK does not read them directly.
+- Explicit `debugbundle.init(...)` arguments always win because they are the only configuration source the runtime consumes.
+- Capture-policy fields are server-owned and are not accepted in local SDK config. The SDK learns capture policy through `GET /v1/sdk/config` and applies it locally before transport.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `project_token` | required for connected capture | Write-only DebugBundle project token. Blank or missing tokens disable connected capture and leave the SDK status at `disconnected`. |
+| `service` | auto/default service | Service name shown on incidents and bundles. |
+| `environment` | `development` | Runtime environment such as `production`, `staging`, or `development`. |
+| `endpoint` | `https://api.debugbundle.com/v1/events` | Ingestion endpoint for connected mode or self-hosting. |
+| `enabled` | `True` | Disable all capture without removing instrumentation. |
+| `log_level` | `warning` | Minimum captured log severity. |
+| `sample_rate` | `1.0` | Fraction of events to keep before transport. |
+| `batch_size` | `25` | Events per batch before flushing. |
+| `flush_interval` | `5.0` | Flush interval in seconds. |
+| `redact_fields` | common sensitive fields | Additional field names to redact. |
+| `max_probe_labels` | `50` | Maximum distinct probe labels buffered in memory. |
+| `max_probe_entries_per_label` | `10` | Maximum entries retained per probe label. |
+| `probe_flush_on_error` | `True` | Attach buffered probe data to captured exceptions. |
+| `probes_poll_interval` | `60000` | Remote probe config poll interval in milliseconds. |
+| `fetch_impl` | internal HTTP fetch | Custom remote-config fetch function for tests or advanced routing. |
+| `on_diagnostic` | none | Callback for SDK internal diagnostics. |
+
+Framework-native wiring:
+
+- Django: initialize the SDK during startup, then add `DebugBundleDjangoMiddleware` to `MIDDLEWARE`.
+- Flask: initialize the SDK during app creation, then call `instrument_flask(app)`.
+- FastAPI: initialize the SDK during startup, then add `DebugBundleFastAPIMiddleware` or call `instrument_fastapi(app)`.
+- There is no separate package-manager plugin, settings loader, or framework-only config surface in V1.
+
+## Install Examples by Mode
+
+Vanilla Python:
+
+```python
+import os
+import debugbundle
+
+debugbundle.init(
+    project_token=os.environ["DEBUGBUNDLE_PROJECT_TOKEN"],
+    service="worker",
+    environment="production",
+)
+
+debugbundle.capture_exceptions()
+debugbundle.capture_logging()
+```
+
+Flask:
+
+```python
+import os
+from flask import Flask
+import debugbundle
+
+app = Flask(__name__)
+debugbundle.init(
+    project_token=os.environ["DEBUGBUNDLE_PROJECT_TOKEN"],
+    service="checkout-api",
+    environment="production",
+)
+debugbundle.instrument_flask(app)
+```
+
+FastAPI:
+
+```python
+import os
+from fastapi import FastAPI
+import debugbundle
+
+app = FastAPI()
+debugbundle.init(
+    project_token=os.environ["DEBUGBUNDLE_PROJECT_TOKEN"],
+    service="checkout-api",
+    environment="production",
+)
+debugbundle.instrument_fastapi(app)
+```
+
+Logger integration:
+
+```python
+import logging
+import debugbundle
+
+debugbundle.capture_logging(logging.getLogger("checkout"))
+```
+
+Connected browser relay:
+
+```python
+from flask import Flask
+import debugbundle
+
+app = Flask(__name__)
+debugbundle.create_flask_relay_handler(
+    allowed_origins=["https://app.example.com"],
+    project_mode="connected",
+    project_token="dbundle_proj_...",
+    endpoint="https://api.debugbundle.com/v1/events",
+)(app)
+```
+
+Local-only browser relay:
+
+```python
+from flask import Flask
+import debugbundle
+
+app = Flask(__name__)
+debugbundle.create_flask_relay_handler(
+    allowed_origins=["http://localhost:3000"],
+    project_mode="local-only",
+    local_events_dir=".debugbundle/local/events",
+)(app)
+```
+
+There is no zero-install fallback for the Python SDK itself in V1. The nearest low-friction path is the browser relay mounted on an existing Python web app.
+
+## Runtime and Framework Support
+
+| Surface | Minimum compatibility version | Recommended production version | Installed-base compatibility lane | Rolling CI lane | Out of scope |
+| --- | --- | --- | --- | --- | --- |
+| Python runtime | 3.10 | 3.12 | 3.10 and 3.11 remain supported for installed-base coverage | 3.12 | 3.9 and older |
+| Django | 5.x | latest 5.x patch | 5.x compatibility support | repo release smoke and tests install Django 5.x | Django 4.x and older |
+| Flask | 3.x | latest 3.x patch | 3.x compatibility support | repo release smoke installs Flask 3.x | Flask 2.x and older |
+| FastAPI | 0.115+ | latest 0.115+ patch line | 0.115+ compatibility support | repo tests install FastAPI 0.115+ | standalone Starlette, older FastAPI lines |
+
+Post-V1 planned expansions from `spec/sdk-language-targets.md` remain out of scope here: Celery, RQ, Dramatiq, standalone Starlette, Gunicorn/Uvicorn server hooks, and AWS Lambda Python.
+
+## Dependency Alignment
+
+`debugbundle-python` ships as one package in V1, so there is no multi-package version-alignment step like a BOM or plugin family lock.
+
+- Pin one `debugbundle-python` version across your service and worker repos when you want identical SDK behavior everywhere.
+- Keep framework dependencies inside the supported lanes above: Django 5.x, Flask 3.x, and FastAPI 0.115+.
+- The packaged HTTP client dependency is `httpx>=0.27,<0.29`; if you override transport behavior in tests or wrappers, stay inside that range unless you retest the SDK.
+
+## Safety Defaults
+
+- SDK failures are caught internally and do not crash the host process.
+- Sensitive fields are redacted before transport.
+- Duplicate event storms are suppressed locally.
+- Runtime context excludes environment variables.
+- Browser relay requests cannot smuggle server-side credentials.
+
+## Service Naming
+
+- Use one stable backend service name per deployable, such as `checkout-api`, `billing-worker`, or `admin-api`.
+- Keep browser relay traffic on the browser-owned service name by default, for example `checkout-web`; the Python relay preserves the browser service unless you explicitly override `service=` or `environment=` on the relay helper.
+- When multiple Python deployables share one DebugBundle project, give each deployable its own `service` value instead of reusing one generic name.
+- Reuse the same environment label across related surfaces, for example `production` on both `checkout-web` and `checkout-api`, so incident and bundle correlation stays readable.
+
+## Safe Startup and Status
+
+- The SDK never crashes the host process when configuration is invalid, transport calls fail, or remote config responses are malformed.
+- `debugbundle.init(project_token="")` or any missing/blank connected token leaves capture disabled and `debugbundle.get_status()` returns `disconnected`.
+- Rate-limited transports move the status to `degraded` until the retry window expires.
+- Three consecutive transport failures also move the status to `disconnected` until a later successful flush.
+- `debugbundle.get_last_event_at()` returns the Unix timestamp of the last successful delivery, or `None` before the first success.
+
+## First-Event Verification
+
+Use the repo-local smoke target to prove a fresh install end to end against a mock ingestion endpoint:
+
+```bash
+make smoke
+```
+
+That command builds the wheel, installs it into a fresh virtualenv, runs a Flask app that emits an application-owned `capture_message()` event, sends a browser relay batch through `/debugbundle/browser`, validates the emitted Python events against the SDK event-envelope fixture, and confirms both paths reach the mock ingestion endpoint with the expected `service`, `environment`, SDK metadata, and correlation fields.
+
+For a manual verification snippet inside your own app:
+
+```python
+import os
+import debugbundle
+
+debugbundle.init(
+    project_token=os.environ["DEBUGBUNDLE_PROJECT_TOKEN"],
+    service="checkout-api",
+    environment="staging",
+)
+
+debugbundle.capture_message("debugbundle first-event verification", level="error")
+debugbundle.flush()
+print(debugbundle.get_status(), debugbundle.get_last_event_at())
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy src
+pytest
+python -m build
+```
+
+CI validates Ruff, mypy, pytest, package build, event schema fixtures, and coverage gates.
+
+## Documentation
+
+- Python SDK docs: <https://debugbundle.com/docs/sdks/python>
+- SDK overview: <https://debugbundle.com/docs/sdks>
+- Browser relay: <https://debugbundle.com/docs/sdks/browser-relay>
+- Repository: <https://github.com/debugbundle/debugbundle-python>
+
+## License
+
+AGPL-3.0-only. See `LICENSE`.

{debugbundle_python-0.1.5.dist-info → debugbundle_python-0.1.8.dist-info}/RECORD

@@ -4,20 +4,21 @@ debugbundle/core.py,sha256=YQFQax6EhjnN7SKFMXq_AohHZyFqxx18Az1ezIZiaDg,35772
 debugbundle/logger_integrations.py,sha256=RuTNaD9RRVmiE-BBkksAXWVEGaMzLrWavVpQdgGZBpE,4564
 debugbundle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 debugbundle/redaction.py,sha256=QTaPkSsYv54yR1mz8SB6Q4vWjvp7Ddcui4WXaH2RVz8,736
-debugbundle/relay.py,sha256=TUzlUsTtDKDVVHj0RvYgQVmxy-Jl3Sp8BMBT033mGDM,8703
+debugbundle/relay.py,sha256=BssBwjAp3usfZ3HPrFD1QpW7i7FPT_jf8fqyhocRZ_w,13143
+debugbundle/relay_delivery.py,sha256=VL-nIgJR6mYXqKy-EbA0USWeY_iS_uAr1KBzrnwBnnk,4676
 debugbundle/suppression.py,sha256=XMn0GfF_-WZk2wHWk3KfbO5_u5QhEunues5h3jOInLs,4098
 debugbundle/transport.py,sha256=oOk0xazHxq9h4CneJdRODKtwDciwikvpHVJM_6iBYXU,1791
 debugbundle/trigger_token.py,sha256=YUwIWnnxu1klAVaB8Ltgk_PwWW_PPjq9rzmEbWXeFeM,4455
-debugbundle/integrations/__init__.py,sha256=VVNoL30a9yd26U9oH1CQMw0_0O0Apo-ZNK1dyrMjTQg,551
+debugbundle/integrations/__init__.py,sha256=Jr87ImWXzUXOuFP4WlGleK14VARajSSdGZN_nHt5emw,1161
 debugbundle/integrations/common.py,sha256=iiwf5wDlpujFuWfbO-ziFTn4MtiHBXSIZNXtamhCavg,2014
 debugbundle/integrations/django.py,sha256=vDQGc0ObcHCe4NQbC0ijcXUM-y9GzOVBjDtcHzxyrxw,1828
 debugbundle/integrations/fastapi.py,sha256=-054Z6MogkZIqKR8DHR4jm2nNC5yyZ5vtanpw6g-voE,3414
 debugbundle/integrations/flask.py,sha256=cgyHbsAH96gpNPf_5IGJYzp2va28JdDgXROBsF-Fbyo,2390
-debugbundle/integrations/relay_django.py,sha256=_2TiH-oS0DOwThyfMJZ6ZJr5MkXEekEDaBUfPapMxt8,1523
-debugbundle/integrations/relay_fastapi.py,sha256=Z2spWy3wufVrBjYwRDDOL5Dsjgwcd5g72L23_sdulvo,1512
-debugbundle/integrations/relay_flask.py,sha256=WHk_ALOtT0xUuI1eINWFyLig9eRjSmIBpQ39xdkV608,1329
-debugbundle_python-0.1.5.dist-info/licenses/LICENSE,sha256=AKZZ5DQAHrOKGwt24VoRd-SXJLM9OloxlsX8ZgENdEY,735
-debugbundle_python-0.1.5.dist-info/METADATA,sha256=Y_moPWkJytlJI71XSFm2Y7q9X4pjQjhFoh25Vv6IwtA,3589
-debugbundle_python-0.1.5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-debugbundle_python-0.1.5.dist-info/top_level.txt,sha256=RCB9STTFnl1OKdojxz-xhaks2zkRFs1meZXsKnm18LM,12
-debugbundle_python-0.1.5.dist-info/RECORD,,
+debugbundle/integrations/relay_django.py,sha256=MMuh1Grdfk5IPUkAHqny6rkHb0cPfUXQDOi7w6Rxkuk,2152
+debugbundle/integrations/relay_fastapi.py,sha256=AW6XA1FzFvjh2mD_gmhdIRgXp5YRUuVV7Cdy7H7_92M,2141
+debugbundle/integrations/relay_flask.py,sha256=oJY0KLDB5fnIHjbZfcRL0X2zzSbCmAagKYLwK8mD_Bo,1958
+debugbundle_python-0.1.8.dist-info/licenses/LICENSE,sha256=AKZZ5DQAHrOKGwt24VoRd-SXJLM9OloxlsX8ZgENdEY,735
+debugbundle_python-0.1.8.dist-info/METADATA,sha256=e34e1npCR_fWBRSuDgUzRTN3H6NItj_Qt-_qXLzdFSU,13829
+debugbundle_python-0.1.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+debugbundle_python-0.1.8.dist-info/top_level.txt,sha256=RCB9STTFnl1OKdojxz-xhaks2zkRFs1meZXsKnm18LM,12
+debugbundle_python-0.1.8.dist-info/RECORD,,

debugbundle_python-0.1.5.dist-info/METADATA

@@ -1,86 +0,0 @@
-Metadata-Version: 2.4
-Name: debugbundle-python
-Version: 0.1.5
-Summary: DebugBundle SDK for Python
-Author: DebugBundle
-License-Expression: AGPL-3.0-only
-Project-URL: Homepage, https://debugbundle.com/docs/sdk-python
-Project-URL: Repository, https://github.com/debugbundle/debugbundle-python
-Project-URL: Issues, https://github.com/debugbundle/debugbundle-python/issues
-Keywords: debugbundle,debugging,ai-agent,error-tracking
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: Django
-Classifier: Framework :: FastAPI
-Classifier: Framework :: Flask
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx<0.29,>=0.27
-Provides-Extra: dev
-Requires-Dist: build<2,>=1; extra == "dev"
-Requires-Dist: django<6,>=5; extra == "dev"
-Requires-Dist: fastapi<1,>=0.115; extra == "dev"
-Requires-Dist: flask<4,>=3; extra == "dev"
-Requires-Dist: jsonschema<5,>=4.23; extra == "dev"
-Requires-Dist: loguru<1,>=0.7; extra == "dev"
-Requires-Dist: mypy<2,>=1.15; extra == "dev"
-Requires-Dist: pytest<9,>=8.3; extra == "dev"
-Requires-Dist: pytest-cov<7,>=5; extra == "dev"
-Requires-Dist: ruff<0.12,>=0.11; extra == "dev"
-Requires-Dist: structlog<26,>=24; extra == "dev"
-Requires-Dist: twine<7,>=5; extra == "dev"
-Dynamic: license-file
-
-# debugbundle-python
-
-DebugBundle SDK for Python.
-
-## Installation
-
-```bash
-pip install debugbundle-python
-```
-
-## Quick Start
-
-```python
-import debugbundle
-
-debugbundle.init(project_token="dbundle_proj_test", service="checkout-api")
-debugbundle.capture_exception(RuntimeError("boom"))
-debugbundle.flush()
-```
-
-## Status
-
-This repository currently contains the full Phase 18 Python SDK scope in eleven implementation slices: core SDK surface, buffering, redaction, duplicate suppression, probe buffering, vanilla runtime hooks, framework integrations for Django, Flask, and FastAPI, remote config polling and capture-policy enforcement, optional `structlog` and `loguru` auto-detection when `capture_logging()` is enabled, contract-aligned `EventEnvelope` emission for log, request, exception, suppression, and probe payloads, explicit public wrapper signatures and a validated buildable typed package artifact, real HTTP integration coverage against a lightweight mock ingestion server, vendored machine-readable schema validation for all event types the Python SDK currently emits, a standalone CI workflow that validates Ruff, mypy, pytest, and package builds for the Python 3.10+ support floor actually used by the package, an enforced per-file coverage gate that keeps every shipped Python SDK module at or above the required 80% minimum, request-local framework correlation binding so `X-DebugBundle-Trace-Id` flows through Django, Flask, and FastAPI into the emitted event correlation metadata for cross-context linking, and safe backend runtime process facts on exception payloads without reading environment variables.
-
-## Runtime Context
-
-Backend exception events now include safe runtime process facts when the host exposes them, including:
-
-- Python version
-- platform
-- architecture
-- pid
-- cwd
-- uptime
-- hostname
-- thread id
-- best-effort memory metadata
-
-The SDK does not read or emit environment variables in this runtime block.
-
-## Docs
-
-https://debugbundle.com/docs/sdk-python
-
-## License
-
-AGPL-3.0-only