insider-python 0.1.0__tar.gz

insider_python-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: insider-python
+Version: 0.1.0
+Summary: Python SDK for Insider — ship Beacons to your Insider server.
+Author: Insider
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Insider-Inc/insider-python
+Keywords: insider,telemetry,errors,monitoring,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3>=1.26
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: django>=4.2; extra == "dev"
+
+# insider-python
+
+The Python SDK for [Insider](https://insider.moraks.cloud/).
+
+Beam Beacons from your Python service to your Insider server with a
+one-line setup. No runtime overhead on your request path. Never raises
+into your code, no matter what.
+
+## Install
+
+```bash
+pip install insider-python
+```
+
+For the Django integration:
+
+```bash
+pip install "insider-python[django]"
+```
+
+## Quick start
+
+### Plain Python
+
+```python
+import insider
+
+insider.init(
+    dsn="https://<beacon_token>@insider.example.com/<project_uuid>",
+    environment="production",
+    release="1.2.3",
+)
+
+try:
+    risky()
+except Exception as exc:
+    insider.capture_exception(exc)
+
+insider.capture_message("cache miss spiked", level="warning")
+```
+
+### Django
+
+Add the integration to `INSTALLED_APPS` and configure via settings:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "insider.contrib.django",
+]
+
+MIDDLEWARE = [
+    # ...
+    "insider.contrib.django.middleware.InsiderMiddleware",
+]
+
+INSIDER_DSN = "https://<beacon_token>@insider.example.com/<project_uuid>"
+INSIDER_ENVIRONMENT = "production"
+INSIDER_RELEASE = "1.2.3"
+```
+
+That's the whole setup. Every unhandled exception in a view is now a
+Beacon in your dashboard.
+
+## Configuration
+
+Order of precedence (first wins):
+
+1. Keyword args to `insider.init(...)`.
+2. `INSIDER_*` environment variables.
+3. Django settings (when the Django integration is active).
+4. Hard-coded defaults.
+
+If no DSN is found anywhere, the SDK enters **disabled mode**: every
+public call is a no-op, no thread starts, no socket opens.
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `dsn` | env `INSIDER_DSN` | If absent, SDK is disabled |
+| `environment` | `"production"` | Top-level Beacon field |
+| `release` | `None` | Top-level Beacon field |
+| `send_default_pii` | `False` | Required to capture `user.id`, request bodies |
+| `before_send` | `None` | `(beacon) -> beacon | None` hook |
+| `scrub_keys` | `None` | Extra keys to filter (added to the default deny-list) |
+| `in_app_include` | `None` | Filename prefixes considered "your code" |
+| `transport_queue_size` | `1000` | Bounded; drops on overflow |
+| `transport_flush_timeout` | `2.0` | Seconds. Used by `close()` / `flush()` |
+| `debug` | `False` | Print SDK's own warnings to stderr |
+
+## Promise
+
+The SDK never raises into your code. Every public function catches
+`Exception` at its boundary; if something goes wrong inside the SDK,
+you get nothing back and a debug log (if enabled). Your app keeps
+running.
+
+## License
+
+MIT

insider_python-0.1.0/README.md

@@ -0,0 +1,99 @@
+# insider-python
+
+The Python SDK for [Insider](https://insider.moraks.cloud/).
+
+Beam Beacons from your Python service to your Insider server with a
+one-line setup. No runtime overhead on your request path. Never raises
+into your code, no matter what.
+
+## Install
+
+```bash
+pip install insider-python
+```
+
+For the Django integration:
+
+```bash
+pip install "insider-python[django]"
+```
+
+## Quick start
+
+### Plain Python
+
+```python
+import insider
+
+insider.init(
+    dsn="https://<beacon_token>@insider.example.com/<project_uuid>",
+    environment="production",
+    release="1.2.3",
+)
+
+try:
+    risky()
+except Exception as exc:
+    insider.capture_exception(exc)
+
+insider.capture_message("cache miss spiked", level="warning")
+```
+
+### Django
+
+Add the integration to `INSTALLED_APPS` and configure via settings:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "insider.contrib.django",
+]
+
+MIDDLEWARE = [
+    # ...
+    "insider.contrib.django.middleware.InsiderMiddleware",
+]
+
+INSIDER_DSN = "https://<beacon_token>@insider.example.com/<project_uuid>"
+INSIDER_ENVIRONMENT = "production"
+INSIDER_RELEASE = "1.2.3"
+```
+
+That's the whole setup. Every unhandled exception in a view is now a
+Beacon in your dashboard.
+
+## Configuration
+
+Order of precedence (first wins):
+
+1. Keyword args to `insider.init(...)`.
+2. `INSIDER_*` environment variables.
+3. Django settings (when the Django integration is active).
+4. Hard-coded defaults.
+
+If no DSN is found anywhere, the SDK enters **disabled mode**: every
+public call is a no-op, no thread starts, no socket opens.
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `dsn` | env `INSIDER_DSN` | If absent, SDK is disabled |
+| `environment` | `"production"` | Top-level Beacon field |
+| `release` | `None` | Top-level Beacon field |
+| `send_default_pii` | `False` | Required to capture `user.id`, request bodies |
+| `before_send` | `None` | `(beacon) -> beacon | None` hook |
+| `scrub_keys` | `None` | Extra keys to filter (added to the default deny-list) |
+| `in_app_include` | `None` | Filename prefixes considered "your code" |
+| `transport_queue_size` | `1000` | Bounded; drops on overflow |
+| `transport_flush_timeout` | `2.0` | Seconds. Used by `close()` / `flush()` |
+| `debug` | `False` | Print SDK's own warnings to stderr |
+
+## Promise
+
+The SDK never raises into your code. Every public function catches
+`Exception` at its boundary; if something goes wrong inside the SDK,
+you get nothing back and a debug log (if enabled). Your app keeps
+running.
+
+## License
+
+MIT

insider_python-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "insider-python"
+version = "0.1.0"
+description = "Python SDK for Insider — ship Beacons to your Insider server."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Insider" }]
+keywords = ["insider", "telemetry", "errors", "monitoring", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "urllib3>=1.26",
+]
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
+dev = [
+    "pytest>=8",
+    "pytest-django>=4.8",
+    "django>=4.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Insider-Inc/insider-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+insider = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+filterwarnings = ["ignore::DeprecationWarning"]
+DJANGO_SETTINGS_MODULE = "tests.django_settings"
+django_find_project = false

insider_python-0.1.0/setup.cfg

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

insider_python-0.1.0/src/insider/__init__.py

@@ -0,0 +1,37 @@
+"""
+Insider — Python SDK.
+
+Public API:
+
+    insider.init(dsn=..., environment=..., release=..., ...)
+    insider.capture_exception(exc, level="error", tags=..., extra=...)
+    insider.capture_message("text", level="info", tags=..., extra=...)
+    insider.flush(timeout=2.0)
+    insider.close(timeout=2.0)
+
+Nothing else is part of the public contract. Anything imported below
+`_` is internal and may change without notice.
+"""
+
+from ._version import __version__
+from .client import (
+    Client,
+    capture_exception,
+    capture_message,
+    close,
+    flush,
+    init,
+)
+from .dsn import DSN, InvalidDSNError
+
+__all__ = [
+    "Client",
+    "DSN",
+    "InvalidDSNError",
+    "__version__",
+    "capture_exception",
+    "capture_message",
+    "close",
+    "flush",
+    "init",
+]

insider_python-0.1.0/src/insider/_envelope.py

@@ -0,0 +1,189 @@
+"""
+Beacon envelope construction + size-budget enforcement.
+
+`build_envelope` is called from the capture functions in `client.py`. It
+takes the raw bits (kind, level, message, exception payload, scope,
+tags, extra) and produces the top-level dict the transport will ship.
+
+`enforce_size_budget` is the second-to-last step before submit. It
+truncates progressively until the JSON-encoded envelope fits under the
+server's 256 KB cap. The truncation order is intentional and matches
+docs/python-sdk-plan -> "Payload size budget":
+
+    1. message capped to 8 KB
+    2. frame `vars` capped to 2 KB each   (v1 has no vars, future-proof)
+    3. request.body capped to 32 KB
+    4. request.headers capped to 4 KB (after deny-listed keys are masked
+       by scrub.py upstream)
+    5. drop frames from the outermost end of the stack until envelope fits,
+       keeping the innermost frames (closest to the error)
+    6. drop payload.request entirely
+    7. ship minimal envelope with payload.truncated = True
+
+Step 7's existence is the property: we ship *something* truthful rather
+than nothing.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional
+
+from .safety import debug
+
+MAX_ENVELOPE_BYTES = 256 * 1024
+MAX_MESSAGE_BYTES = 8 * 1024
+MAX_REQUEST_BODY_BYTES = 32 * 1024
+MAX_REQUEST_HEADERS_BYTES = 4 * 1024
+
+
+def _now_iso() -> str:
+    """ISO-8601 UTC timestamp with microseconds, used as `occurred_at`."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_envelope(
+    *,
+    kind: str,
+    level: str,
+    message: Optional[str],
+    source: Optional[str],
+    environment: str,
+    release: Optional[str],
+    trace_id: Optional[str],
+    payload: Optional[Dict[str, Any]] = None,
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    occurred_at: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Assemble the Beacon envelope. Pure: no I/O, no globals."""
+    body: Dict[str, Any] = dict(payload or {})
+    if tags:
+        body["tags"] = tags
+    if extra:
+        body["extra"] = extra
+    return {
+        "kind": kind,
+        "level": level,
+        "environment": environment,
+        "release": release,
+        "source": source,
+        "message": message,
+        "occurred_at": occurred_at or _now_iso(),
+        "trace_id": trace_id,
+        "payload": body,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Size budget
+# ---------------------------------------------------------------------------
+
+
+def _byte_len(obj: Any) -> int:
+    """Best-effort serialized size. Encode errors → infinity to force trim."""
+    try:
+        return len(json.dumps(obj, default=str, ensure_ascii=False).encode("utf-8"))
+    except Exception:
+        return 10**9
+
+
+def _truncate_str_to_bytes(value: str, limit: int) -> str:
+    encoded = value.encode("utf-8")
+    if len(encoded) <= limit:
+        return value
+    return encoded[:limit].decode("utf-8", errors="ignore")
+
+
+def enforce_size_budget(envelope: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Apply the truncation rules in order. Returns the same envelope dict,
+    mutated. The caller is expected to discard the original reference
+    after this call.
+    """
+    # 1. message
+    msg = envelope.get("message")
+    if isinstance(msg, str):
+        envelope["message"] = _truncate_str_to_bytes(msg, MAX_MESSAGE_BYTES)
+
+    payload = envelope.get("payload") or {}
+
+    # 3. request.body
+    request_ctx = payload.get("request")
+    if isinstance(request_ctx, dict):
+        body = request_ctx.get("body")
+        if isinstance(body, str):
+            request_ctx["body"] = _truncate_str_to_bytes(body, MAX_REQUEST_BODY_BYTES)
+        elif body is not None:
+            # Non-string body: dump to string and cap.
+            try:
+                as_str = json.dumps(body, default=str)
+            except Exception:
+                as_str = str(body)
+            request_ctx["body"] = _truncate_str_to_bytes(as_str, MAX_REQUEST_BODY_BYTES)
+
+        # 4. request.headers
+        headers = request_ctx.get("headers")
+        if isinstance(headers, dict):
+            if _byte_len(headers) > MAX_REQUEST_HEADERS_BYTES:
+                # Drop the largest-value headers until under budget. We drop
+                # whole entries rather than truncating individual values to
+                # avoid producing partial / misleading header strings.
+                items = sorted(
+                    headers.items(),
+                    key=lambda kv: _byte_len(kv[1]),
+                    reverse=True,
+                )
+                trimmed = dict(items)
+                while items and _byte_len(trimmed) > MAX_REQUEST_HEADERS_BYTES:
+                    k, _ = items.pop(0)
+                    trimmed.pop(k, None)
+                request_ctx["headers"] = trimmed
+
+    # 5. drop frames from the outside until envelope fits
+    exception = payload.get("exception")
+    if isinstance(exception, dict) and isinstance(exception.get("frames"), list):
+        while _byte_len(envelope) > MAX_ENVELOPE_BYTES and exception["frames"]:
+            # Keep the *innermost* frames (the end of the list).
+            exception["frames"].pop(0)
+
+    # 6. drop payload.request entirely if still too big
+    if _byte_len(envelope) > MAX_ENVELOPE_BYTES and "request" in payload:
+        payload.pop("request", None)
+        debug("size budget: dropped payload.request")
+
+    # 7. minimal envelope of last resort
+    if _byte_len(envelope) > MAX_ENVELOPE_BYTES:
+        minimal_exception: Optional[Dict[str, Any]] = None
+        if isinstance(exception, dict):
+            minimal_exception = {
+                "type": exception.get("type"),
+                "value": _truncate_str_to_bytes(
+                    str(exception.get("value", "")), 1024
+                ),
+            }
+        minimal_payload: Dict[str, Any] = {"truncated": True}
+        if minimal_exception is not None:
+            minimal_payload["exception"] = minimal_exception
+        envelope["payload"] = minimal_payload
+        debug("size budget: emitting minimal envelope")
+
+    return envelope
+
+
+def safe_frame_subset(
+    frames: List[Dict[str, Any]],
+    in_app_only: bool = False,
+) -> List[Dict[str, Any]]:
+    """Optional filter for dashboards; unused in v1 but kept for callers."""
+    if not in_app_only:
+        return frames
+    return [f for f in frames if f.get("in_app")]
+
+
+__all__: Iterable[str] = (
+    "MAX_ENVELOPE_BYTES",
+    "build_envelope",
+    "enforce_size_budget",
+)

insider_python-0.1.0/src/insider/_version.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the SDK version.
+
+Kept separate from `pyproject.toml` at runtime to avoid an `importlib.metadata`
+lookup on every beacon. Bump this and `[project].version` together when
+cutting a release.
+"""
+
+__version__ = "0.1.0"