debugbundle-python 0.1.0__tar.gz

debugbundle_python-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2024-present DebugBundle
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.

debugbundle_python-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: debugbundle-python
+Version: 0.1.0
+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, and 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.
+
+## Docs
+
+https://debugbundle.com/docs/sdk-python

debugbundle_python-0.1.0/README.md

@@ -0,0 +1,27 @@
+# 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, and 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.
+
+## Docs
+
+https://debugbundle.com/docs/sdk-python

debugbundle_python-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "debugbundle-python"
+version = "0.1.0"
+description = "DebugBundle SDK for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "AGPL-3.0-only"
+authors = [{ name = "DebugBundle" }]
+keywords = ["debugbundle", "debugging", "ai-agent", "error-tracking"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Django",
+  "Framework :: FastAPI",
+  "Framework :: Flask",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed"
+]
+dependencies = [
+  "httpx>=0.27,<0.29"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1,<2",
+  "django>=5,<6",
+  "fastapi>=0.115,<1",
+  "flask>=3,<4",
+  "jsonschema>=4.23,<5",
+  "loguru>=0.7,<1",
+  "mypy>=1.15,<2",
+  "pytest>=8.3,<9",
+  "pytest-cov>=5,<7",
+  "ruff>=0.11,<0.12",
+  "structlog>=24,<26",
+  "twine>=5,<7"
+]
+
+[project.urls]
+Homepage = "https://debugbundle.com/docs/sdk-python"
+Repository = "https://github.com/debugbundle/debugbundle-python"
+Issues = "https://github.com/debugbundle/debugbundle-python/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+check_untyped_defs = true
+no_implicit_optional = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+pretty = true
+
+[tool.coverage.run]
+source = ["src/debugbundle"]
+
+[tool.coverage.report]
+show_missing = true

debugbundle_python-0.1.0/setup.cfg

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

debugbundle_python-0.1.0/src/debugbundle/__init__.py

@@ -0,0 +1,165 @@
+"""DebugBundle Python SDK."""
+
+import asyncio
+import importlib
+import logging
+from collections.abc import Callable, Mapping
+from contextvars import Token
+from typing import Any
+
+from .config import RemoteProbeDirective
+from .core import ConfigFetchResponse, DebugBundleSdk
+from .relay import BrowserRelayAcceptedBatch, BrowserRelayHandler, BrowserRelayResponse
+
+_sdk = DebugBundleSdk()
+
+
+def init(
+    project_token: str,
+    environment: str | None = None,
+    service: str | None = None,
+    enabled: bool = True,
+    redact_fields: list[str] | None = None,
+    sample_rate: float = 1.0,
+    batch_size: int = 25,
+    flush_interval: float = 5.0,
+    endpoint: str = "https://api.debugbundle.com/v1/events",
+    log_level: str = "warning",
+    max_probe_labels: int = 50,
+    max_probe_entries_per_label: int = 10,
+    probe_flush_on_error: bool = True,
+    fetch_impl: Callable[[str, dict[str, object]], ConfigFetchResponse] | None = None,
+    on_diagnostic: Callable[[dict[str, object]], None] | None = None,
+    probes_poll_interval: int = 60_000,
+) -> None:
+    _sdk.init(
+        project_token=project_token,
+        environment=environment,
+        service=service,
+        enabled=enabled,
+        redact_fields=redact_fields,
+        sample_rate=sample_rate,
+        batch_size=batch_size,
+        flush_interval=flush_interval,
+        endpoint=endpoint,
+        log_level=log_level,
+        max_probe_labels=max_probe_labels,
+        max_probe_entries_per_label=max_probe_entries_per_label,
+        probe_flush_on_error=probe_flush_on_error,
+        fetch_impl=fetch_impl,
+        on_diagnostic=on_diagnostic,
+        probes_poll_interval=probes_poll_interval,
+    )
+
+
+def capture_exception(error: BaseException, context: dict[str, object] | None = None) -> None:
+    _sdk.capture_exception(error, context=context)
+
+
+def capture_error(error: BaseException, context: dict[str, object] | None = None) -> None:
+    _sdk.capture_error(error, context=context)
+
+
+def capture_log(message: str, level: str = "warning", context: dict[str, object] | None = None) -> None:
+    _sdk.capture_log(message, level=level, context=context)
+
+
+def capture_request(
+    request: Mapping[str, object],
+    response: Mapping[str, object] | None = None,
+    context: Mapping[str, object] | None = None,
+) -> None:
+    _sdk.capture_request(request, response=response, context=context)
+
+
+def capture_message(message: str, level: str | None = None, context: dict[str, object] | None = None) -> None:
+    _sdk.capture_message(message, level=level, context=context)
+
+
+def set_context(key: str, value: object) -> None:
+    _sdk.set_context(key, value)
+
+
+def flush() -> None:
+    _sdk.flush()
+
+
+def get_status() -> str:
+    return _sdk.status
+
+
+def get_last_event_at() -> float | None:
+    return _sdk.last_event_at
+
+
+def probe(label: str, data: object | Callable[[], object], opts: Mapping[str, object] | None = None) -> None:
+    _sdk.probe(label, data, opts=opts)
+
+
+def capture_exceptions() -> None:
+    _sdk.capture_exceptions()
+
+
+def capture_logging(logger: logging.Logger | None = None) -> None:
+    _sdk.capture_logging(logger=logger)
+
+
+def capture_async(loop: asyncio.AbstractEventLoop | None = None) -> None:
+    _sdk.capture_async(loop=loop)
+
+
+def begin_request(request: dict) -> object:
+    return _sdk.begin_request(request)
+
+
+def end_request(token: Token[list[RemoteProbeDirective] | None]) -> None:
+    _sdk.end_request(token)
+
+
+_OPTIONAL_EXPORTS = {
+    "DebugBundleDjangoMiddleware": (".integrations.django", "DebugBundleDjangoMiddleware"),
+    "DebugBundleFastAPIMiddleware": (".integrations.fastapi", "DebugBundleFastAPIMiddleware"),
+    "create_django_relay_view": (".integrations.relay_django", "create_django_relay_view"),
+    "create_fastapi_relay_handler": (".integrations.relay_fastapi", "create_fastapi_relay_handler"),
+    "create_flask_relay_handler": (".integrations.relay_flask", "create_flask_relay_handler"),
+    "instrument_fastapi": (".integrations.fastapi", "instrument_fastapi"),
+    "instrument_flask": (".integrations.flask", "instrument_flask"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _OPTIONAL_EXPORTS:
+        raise AttributeError(f"module 'debugbundle' 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__ = [
+    "BrowserRelayAcceptedBatch",
+    "BrowserRelayHandler",
+    "BrowserRelayResponse",
+    "DebugBundleSdk",
+    "DebugBundleDjangoMiddleware",
+    "DebugBundleFastAPIMiddleware",
+    "begin_request",
+    "capture_async",
+    "capture_error",
+    "capture_exception",
+    "capture_exceptions",
+    "capture_log",
+    "capture_logging",
+    "capture_message",
+    "capture_request",
+    "create_django_relay_view",
+    "create_fastapi_relay_handler",
+    "create_flask_relay_handler",
+    "end_request",
+    "flush",
+    "init",
+    "instrument_fastapi",
+    "instrument_flask",
+    "probe",
+    "set_context",
+]

debugbundle_python-0.1.0/src/debugbundle/config.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_PROBES_POLL_INTERVAL_MS = 60_000
+
+
+@dataclass(frozen=True)
+class CapturePolicy:
+    preset: str
+    capture_logs: str
+    capture_request_events: str
+    capture_breadcrumbs: str
+    capture_probe_events: str
+
+
+@dataclass(frozen=True)
+class RemoteProbeDirective:
+    id: str
+    label_pattern: str
+    service: str
+    environment: str
+    expires_at: str
+
+
+@dataclass(frozen=True)
+class RemoteConfigSnapshot:
+    probes_enabled: bool
+    remote_probes_enabled: bool
+    directives: list[RemoteProbeDirective]
+    poll_interval_ms: int
+    capture_policy: CapturePolicy
+    trigger_token_key: str | None = None
+
+
+BALANCED_CAPTURE_POLICY = CapturePolicy(
+    preset="balanced",
+    capture_logs="warning",
+    capture_request_events="all",
+    capture_breadcrumbs="local_only",
+    capture_probe_events="standalone_when_activated",
+)
+
+MINIMAL_CAPTURE_POLICY = CapturePolicy(
+    preset="minimal",
+    capture_logs="warning",
+    capture_request_events="off",
+    capture_breadcrumbs="local_only",
+    capture_probe_events="buffer_only",
+)
+
+
+def parse_remote_config(payload: object, fallback_poll_interval_ms: int, now_ms: int) -> RemoteConfigSnapshot | None:
+    if not isinstance(payload, dict):
+        return None
+
+    probes_enabled = payload.get("probes_enabled") is True
+    remote_probes_enabled = payload.get("remote_probes_enabled") is True
+    poll_interval_candidate = payload.get("poll_interval_ms")
+    poll_interval_ms = (
+        int(poll_interval_candidate)
+        if isinstance(poll_interval_candidate, (int, float)) and int(poll_interval_candidate) > 0
+        else fallback_poll_interval_ms
+    )
+
+    directives: list[RemoteProbeDirective] = []
+    active_probes = payload.get("active_probes")
+    if isinstance(active_probes, list):
+        for directive in active_probes:
+            parsed = _parse_directive(directive)
+            if parsed is not None and _expires_at_ms(parsed.expires_at) > now_ms:
+                directives.append(parsed)
+
+    capture_policy = _parse_capture_policy(payload.get("capture_policy"))
+    if capture_policy is None:
+        return None
+
+    return RemoteConfigSnapshot(
+        probes_enabled=probes_enabled,
+        remote_probes_enabled=remote_probes_enabled,
+        directives=directives,
+        poll_interval_ms=poll_interval_ms if remote_probes_enabled else DEFAULT_PROBES_POLL_INTERVAL_MS,
+        capture_policy=capture_policy,
+        trigger_token_key=_as_non_empty_string(payload.get("trigger_token_key")),
+    )
+
+
+def find_matching_remote_probe_directives(
+    directives: list[RemoteProbeDirective],
+    label: str,
+    service: str,
+    environment: str,
+    now_ms: int,
+) -> list[RemoteProbeDirective]:
+    matches: list[RemoteProbeDirective] = []
+    for directive in directives:
+        if _expires_at_ms(directive.expires_at) <= now_ms:
+            continue
+        if directive.service != "*" and directive.service != service:
+            continue
+        if directive.environment != "*" and directive.environment != environment:
+            continue
+        if _matches_label_pattern(directive.label_pattern, label):
+            matches.append(directive)
+    return matches
+
+
+def _parse_capture_policy(payload: object) -> CapturePolicy | None:
+    if payload is None:
+        return BALANCED_CAPTURE_POLICY
+    if not isinstance(payload, dict):
+        return None
+
+    preset = _as_non_empty_string(payload.get("preset")) or BALANCED_CAPTURE_POLICY.preset
+    capture_logs = _as_non_empty_string(payload.get("capture_logs"))
+    capture_request_events = _as_non_empty_string(payload.get("capture_request_events"))
+    capture_breadcrumbs = _as_non_empty_string(payload.get("capture_breadcrumbs"))
+    capture_probe_events = _as_non_empty_string(payload.get("capture_probe_events"))
+
+    if capture_logs not in {"off", "error", "warning", "info"}:
+        return None
+    if capture_request_events not in {"off", "failures_only", "filtered", "all"}:
+        return None
+    if capture_breadcrumbs not in {"local_only", "exception_only", "standalone"}:
+        return None
+    if capture_probe_events not in {"buffer_only", "standalone_when_activated"}:
+        return None
+
+    return CapturePolicy(
+        preset=preset,
+        capture_logs=capture_logs,
+        capture_request_events=capture_request_events,
+        capture_breadcrumbs=capture_breadcrumbs,
+        capture_probe_events=capture_probe_events,
+    )
+
+
+def _parse_directive(payload: object) -> RemoteProbeDirective | None:
+    if not isinstance(payload, dict):
+        return None
+
+    directive_id = _as_non_empty_string(payload.get("id"))
+    label_pattern = _as_non_empty_string(payload.get("label_pattern"))
+    service = _as_non_empty_string(payload.get("service"))
+    environment = _as_non_empty_string(payload.get("environment"))
+    expires_at = _as_non_empty_string(payload.get("expires_at"))
+
+    if directive_id is None:
+        return None
+    if label_pattern is None:
+        return None
+    if service is None:
+        return None
+    if environment is None:
+        return None
+    if expires_at is None:
+        return None
+    if _expires_at_ms(expires_at) == 0:
+        return None
+
+    return RemoteProbeDirective(
+        id=directive_id,
+        label_pattern=label_pattern,
+        service=service,
+        environment=environment,
+        expires_at=expires_at,
+    )
+
+
+def _matches_label_pattern(pattern: str, label: str) -> bool:
+    if pattern == "*":
+        return True
+    if pattern.endswith(".*"):
+        prefix = pattern[:-2]
+        return label == prefix or label.startswith(f"{prefix}.")
+    return pattern == label
+
+
+def _expires_at_ms(value: str) -> int:
+    from datetime import datetime
+
+    try:
+        if value.endswith("Z"):
+            value = value[:-1] + "+00:00"
+        return int(datetime.fromisoformat(value).timestamp() * 1000)
+    except ValueError:
+        return 0
+
+
+def _as_non_empty_string(value: Any) -> str | None:
+    return value if isinstance(value, str) and len(value) > 0 else None