getfaultline 0.1.0__tar.gz

getfaultline-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+.coverage
+htmlcov/
+.DS_Store

getfaultline-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,194 @@
+# Architecture decision log: `getfaultline` (Python)
+
+## Layers
+
+```
+src/faultline/
+  domain/          pure Python: event contract (TypedDicts), Scope, options validation, limits,
+                   scrubbing, JSON normalization, event sanitization, dedupe key
+  application/     FaultlineClient, Hub (contextvars scopes), Integration protocol
+    ports.py       Transport, StackExtractor, SourceContextReader, Clock, IdGenerator,
+                   RandomSource, Logger, RuntimeInfo
+  infrastructure/  HttpTransport (worker thread), TracebackStackExtractor,
+                   LinecacheSourceReader, runtime adapters (clock, uuid, stderr logger, os)
+  integrations/    excepthook, threading, logging, http.client, wsgi, asgi, flask, fastapi,
+                   django
+  __init__.py      public API + composition root
+```
+
+Dependency rule: `domain <- application <- infrastructure | integrations <- faultline`.
+`infrastructure` and `integrations` are siblings and may not import each other. They meet only
+in `faultline/__init__.py`. This mirrors the Node SDK one to one.
+
+---
+
+### ADR-001: Enforce boundaries with import-linter plus an AST test
+
+- **Decision:** `pyproject.toml` declares three import-linter contracts: the layer order
+  (`integrations | infrastructure > application > domain`), a pure domain (no `os`, `sys`,
+  `socket`, `http`, `threading`, `asyncio`, `logging`, `contextvars`, ...), and "frameworks
+  only in their integration module". `tests/test_architecture.py` checks the same rules with
+  `ast`, so the rule also holds where import-linter is not run.
+- **Verification:** We added deliberate violations (`import os` and an infrastructure import
+  in `domain/limits.py`) and confirmed both contracts break.
+- **Note:** `urllib.parse` is allowed in the domain (it is pure and needed to decode query
+  keys while scrubbing). import-linter cannot tell `urllib.parse` from `urllib.request`, so the
+  AST test forbids `urllib.request` explicitly.
+
+### ADR-002: Zero runtime dependencies; hand-written options validator
+
+- **Decision:** `resolve_options()` validates `init()` options by hand and never raises. An
+  invalid optional value falls back to its default with a warning; only a missing `api_key`
+  or an unusable `endpoint` disables the SDK. Unknown keyword arguments are ignored with a
+  warning instead of raising `TypeError`.
+- **Why:** Same reasoning as the Node SDK's ADR-002. pydantic is a test-only dependency: every
+  produced event is validated against strict pydantic models that mirror CONTRACTS.md
+  (`tests/contract.py`).
+
+### ADR-003: `contextvars` used directly in the application layer
+
+- **Decision:** The `Hub` owns a `ContextVar[Scope]`. `with_scope()` forks the current scope
+  with `clone()` and sets it for the block; framework middleware does the same per request.
+- **Why not a port (as Node did with AsyncLocalStorage)?** `contextvars` is a pure language
+  primitive with no I/O and identical behavior on every supported Python, so a port adds
+  indirection without a second implementation. The domain still never touches it.
+- **Semantics:** asyncio tasks copy the context when created, so tasks spawned inside a scope
+  inherit it and concurrent tasks are isolated. New threads start from the root scope unless
+  started via `contextvars.copy_context().run`, matching the stdlib's own semantics.
+  `ContextVar.reset` failures (a block exited in another context) fall back to restoring the
+  previous value instead of raising.
+
+### ADR-004: Copy-on-write Scope
+
+- **Decision:** Every `Scope` mutation replaces its dict/tuple instead of changing it in place.
+  `clone()` and `get_data()` are O(1) reference copies.
+- **Why:** The root scope can be written from many threads at once. With copy-on-write a
+  snapshot taken by the client can never change underneath it, and no lock is needed in the
+  (pure) domain. Concurrent writers to the same scope may lose an update, but never crash.
+
+### ADR-005: Synchronous event processing, asynchronous delivery
+
+- **Node:** splits capture into a sync phase and an async phase (source reads use
+  `fs.promises`).
+- **Python:** everything up to `transport.send()` runs in the caller's thread: traceback
+  extraction, sampling, `ignore_errors`, dedupe, source context, sanitization, scrubbing and
+  `before_send`. Delivery (batching, gzip, HTTP, retries) runs on a worker thread.
+- **Why:** Traceback objects reference live frames and must be read before the caller moves
+  on; `linecache` is cached and in-memory after the first read. Doing it synchronously also
+  means `capture_exception` returns `None` when `before_send` drops the event (Node returns
+  the id anyway). Serialization happens in `send()` so the queued event is a frozen snapshot
+  and its size is known up front.
+
+### ADR-006: `before_send` receives scrubbed events; a raising `before_send` drops the event
+
+Identical to the Node SDK (ADR-005 there). The result is re-sanitized, so a buggy hook cannot
+produce a payload that violates the contract.
+
+### ADR-007: `send_default_pii` semantics
+
+- **`False` (default):** `user.ipAddress` is removed and the `cookie`, `set-cookie`,
+  `authorization`, `proxy-authorization`, `x-forwarded-for`, `x-real-ip` and `forwarded`
+  headers are removed entirely. Framework integrations do not collect the client IP.
+- **`True`:** the IP (`REMOTE_ADDR` / ASGI `client`) is collected and those headers are kept.
+  Values under sensitive keys are still replaced with `"[Filtered]"`.
+
+### ADR-008: Cause chain and exception groups
+
+- **Chain:** `__cause__`, else `__context__` unless `__suppress_context__`. At most 5
+  exceptions in total (root plus 4), as in Node's ADR-007. Cycles are broken with an
+  identity set.
+- **Exception groups:** the contract has a single `cause` slot, so a group is reported as one
+  exception whose `value` lists up to 10 sub-exceptions (`ValueError('x'), ...`) and whose
+  `cause` is its explicit cause/context or, failing that, its first sub-exception. Detection
+  is duck-typed, so the `exceptiongroup` backport on 3.9/3.10 works too.
+- **Non-exception values** (`capture_exception("text")`, a dict, ...) become a synthetic
+  `Error` with the caller's stack (SDK frames removed).
+
+### ADR-009: In-app rules and frame data
+
+- Not in-app: paths containing `/site-packages/` or `/dist-packages/`, paths under the
+  interpreter's stdlib (`sysconfig` `stdlib`/`platstdlib` and `base_prefix/lib/pythonX.Y`),
+  synthetic filenames starting with `<`, and modules named `faultline` / `faultline.*`.
+  Windows paths are normalized (`\` to `/`, drive paths lowercased).
+- `function` is `co_qualname` on 3.11+ (`Class.method`), `co_name` before. `colno` (1-based)
+  comes from `co_positions()` on 3.11+.
+- `filename` is the absolute path, as in the Node SDK.
+
+### ADR-010: Dedupe
+
+Same rule as Node's ADR-009 (consecutive events only, 1 s window from the last sent event;
+key = fingerprint, else type + value + newest 5 frames, else level + message), guarded by a
+lock because captures can come from many threads.
+
+### ADR-011: Transport
+
+- **Queue:** `deque`, max 100 events, drop oldest. Guarded by a `Condition`.
+- **Worker:** one daemon thread (`faultline-transport`), started lazily on the first event.
+  It sends when 20 events are queued, every 2 s, or when `flush()` asks. A send lock ensures a
+  single sender.
+- **Batches:** at most 50 events and 1 MB uncompressed, gzip-compressed. Oversized events are
+  trimmed (breadcrumbs, then source context, then extra) or dropped.
+- **Retries:** network errors, timeouts (5 s), `5xx` and `408` are retried inline with equal
+  jitter `min(30, 2^n)/2 + rand * min(30, 2^n)/2` seconds, up to 3 retries. Backoff sleeps use
+  an `Event` so `close()` interrupts them. `429` pauses the transport until `Retry-After`
+  (seconds or HTTP date, capped at 10 min) and requeues the batch at the front; an event is
+  dropped after 3 rate-limited attempts. `401`, `413` and other `4xx` drop the batch.
+- **HTTP client:** `urllib.request` (honors proxy environment variables). The SDK's own
+  requests are recognized by the http integration via the ingest URL and the worker thread
+  name and are never recorded as breadcrumbs.
+- **Shutdown:** `atexit` calls `close(2.0)`: flush with a deadline, then stop. Because the worker
+  is a daemon thread and every wait is bounded, exit never hangs (tested with a server that
+  never answers and with no server at all). If the worker cannot run (for example a thread
+  cannot be started during interpreter shutdown), `flush()` sends from the calling thread
+  with the same deadline.
+- **Fork safety:** `os.register_at_fork(after_in_child=...)` resets locks and the worker in
+  the child; queued events are kept and sent by a new worker.
+
+### ADR-012: Integrations patch politely and restore exactly
+
+- `sys.excepthook` / `threading.excepthook`: capture, then always call the previous hook.
+  `KeyboardInterrupt` and thread `SystemExit` are not captured.
+- `logging`: wraps `Logger.callHandlers` (sees every record that passes level checks, needs no
+  handler). A thread-local reentrancy guard and the ignored `faultline` logger prevent loops.
+- `http.client`: wraps `putrequest` / `getresponse` and never changes arguments, return values
+  or exceptions. The scope is captured at `putrequest`, so a response read in another context
+  still lands in the right scope.
+- `teardown()` restores the original only if our wrapper is still installed, so we never undo
+  somebody else's later patch.
+
+### ADR-013: Framework integrations
+
+- Each lives in its own module and imports its framework lazily (enforced by import-linter
+  and the AST test), so `import faultline` never imports Flask, Django or Starlette.
+- **WSGI:** each request runs in `contextvars.copy_context()`; the response iterable is
+  wrapped so streaming and `close()` run in the request context and streaming errors are
+  captured.
+- **ASGI:** the request runs inside `with_scope()`; `lifespan` passes through untouched.
+- **Flask:** WSGI middleware for scope and request data, plus `got_request_exception` for
+  capture (Flask turns exceptions into 500 responses before WSGI middleware can see them).
+- **Django:** sync and async capable middleware for the scope, plus Django's
+  `got_request_exception` signal for capture (fires only for real 500s).
+- An exception is marked once captured, so stacked integrations (Flask signal plus WSGI with
+  `PROPAGATE_EXCEPTIONS`) never report it twice.
+
+### ADR-014: Server-side caps enforced client-side
+
+The server's ingest schema also caps fingerprint parts (20), header/query keys (256) and values
+(8192), and `user.ipAddress` (64). These are not pinned in CONTRACTS.md, but sending more
+would get the event rejected, so the SDK truncates to them.
+
+### ADR-015: Toolchain
+
+- hatchling, src layout, version in `src/faultline/_version.py`.
+- ruff (lint + format), mypy `--strict` (tests and examples relax a few error codes for
+  deliberately malformed fixtures and untyped framework decorators; the package does not).
+- CI runs lint/typecheck/import contracts once and tests on 3.9 to 3.14 (plus Windows and
+  macOS on 3.13), then builds, runs `twine check --strict`, and smoke-tests the wheel in an
+  empty venv. Locally the suite was also run on 3.9.6 (Django 4.2) and 3.14.
+
+### Suggestions (not implemented, outside spec)
+
+- Offline persistence of the queue across restarts.
+- A `transport` option for custom transports (serverless, tests).
+- Celery / RQ integrations (per-task scope and capture).
+- Capturing local variables per frame (opt-in, PII-sensitive).

getfaultline-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `getfaultline` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - unreleased
+
+### Added
+
+- `init`, `capture_exception`, `capture_message`, `set_user`, `set_tag(s)`, `set_context`,
+  `set_extra`, `add_breadcrumb`, `with_scope`, `flush`, `close`, `is_enabled`.
+- Tracebacks ordered oldest to newest with in-app detection, source context and columns
+  (3.11+); `__cause__` / `__context__` chains (max 5); exception group support.
+- Background batched transport: gzip, retries with backoff and jitter, `429 Retry-After`,
+  drops on `401` / `413`, `atexit` flush, fork safety.
+- Client-side scrubbing identical to the server and the Node SDK; dedupe within 1 s.
+- Integrations: `sys.excepthook`, `threading.excepthook`, `logging`, `http.client`, WSGI,
+  ASGI, Flask, FastAPI / Starlette, Django.

getfaultline-0.1.0/LICENSE

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

getfaultline-0.1.0/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.5
+Name: getfaultline
+Version: 0.1.0
+Summary: Python SDK for Faultline error tracking
+Project-URL: Homepage, https://www.faultsline.dev
+Project-URL: Source, https://github.com/getfaultline/faultline-python
+Project-URL: Issues, https://github.com/getfaultline/faultline-python/issues
+Author: Faultline
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,error-tracking,fastapi,faultline,flask,monitoring,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: flask>=2.2; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pydantic>=2.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.2; extra == 'flask'
+Provides-Extra: test
+Requires-Dist: fastapi>=0.100; extra == 'test'
+Requires-Dist: flask>=2.2; extra == 'test'
+Requires-Dist: httpx>=0.24; extra == 'test'
+Requires-Dist: pydantic>=2.5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# getfaultline
+
+The Python SDK for [Faultline](https://www.faultsline.dev), a self-hostable error-tracking
+platform. It captures exceptions and messages, adds context (tracebacks with source,
+breadcrumbs, request data, user, tags), scrubs secrets, and sends batched, gzip-compressed
+events to the Faultline ingest API.
+
+- **No runtime dependencies.** Uses only the standard library (`urllib`, `gzip`, `threading`,
+  `contextvars`, `linecache`).
+- **Never crashes your app.** Every public function is exception-safe, and internal errors are
+  logged only when `debug=True`.
+- **Typed** (`py.typed`, `mypy --strict` clean). Runs on Python **3.9 to 3.14**.
+- **Async-safe and thread-safe scopes** built on `contextvars`.
+
+## Quickstart
+
+```bash
+pip install getfaultline
+```
+
+```python
+import faultline
+
+faultline.init(
+    api_key="flt_ingest_...",  # or os.environ["FAULTLINE_API_KEY"]
+    environment="production",
+    release="api@1.4.2",
+)
+
+try:
+    do_risky_thing()
+except Exception:
+    faultline.capture_exception(tags={"feature": "checkout"})  # defaults to sys.exc_info()
+
+faultline.capture_message("Payment webhook retried", "warning")
+```
+
+Uncaught exceptions (main thread and other threads) are captured automatically, and queued
+events are flushed when the interpreter exits.
+
+## API
+
+| Function | Description |
+| --- | --- |
+| `init(api_key=..., **options)` | Configure the SDK. Calling it again replaces the previous client. |
+| `capture_exception(exc=None, *, tags, extra, user, level, fingerprint, contexts)` | Capture an exception. `exc` defaults to the exception being handled (`sys.exc_info()`); an `exc_info` tuple or any other value also works. Returns the `event_id`, or `None` when dropped or disabled. |
+| `capture_message(message, level="info", *, tags, extra, user, fingerprint, contexts)` | Capture a message. |
+| `set_user({"id", "email", "username", "ipAddress"})` / `set_user(None)` | Set or clear the user on the current scope. |
+| `set_tag(key, value)` / `set_tags({...})` | Searchable string tags. |
+| `set_context(name, {...})` / `set_extra(key, value)` | Structured context or arbitrary extra data. |
+| `add_breadcrumb(type=, category=, message=, level=, data=)` | Manual breadcrumb (also accepts a dict). `type` is one of `default`, `http`, `log`, `query`, `navigation`. |
+| `with with_scope() as scope:` | Fork the current scope. Changes apply only inside the block, including asyncio tasks created inside it. |
+| `flush(timeout=2.0)` | Block until queued events are sent. Returns `False` on timeout and never raises. |
+| `close(timeout=2.0)` | Flush, remove the integrations, and disable the SDK. |
+| `is_enabled()` / `get_current_scope()` | Introspection helpers. |
+
+`set_user`, `set_tag`, `set_context`, `set_extra` and `add_breadcrumb` write to the **current**
+scope. Outside a request or `with_scope()` that is the global scope. Inside one, it is the
+forked scope.
+
+```python
+with faultline.with_scope() as scope:
+    scope.set_tag("job", "nightly-export")
+    faultline.set_user({"id": "42"})
+    run_job()  # anything captured here carries the tag and user
+# back to the previous scope here
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `api_key` | `str` | **required** | Public ingest key (`flt_ingest_...`). Sent as `X-Faultline-Key`. |
+| `endpoint` | `str` | `https://www.faultsline.dev` | Base URL of the Faultline server. Override it when self-hosting. |
+| `environment` | `str` | `None` | e.g. `production`, `staging`. |
+| `release` | `str` | `None` | e.g. `api@1.4.2` or a git sha. |
+| `server_name` | `str` | `socket.gethostname()` | Reported as `serverName`. |
+| `sample_rate` | `float` 0..1 | `1.0` | Fraction of events to send. |
+| `max_breadcrumbs` | `int` | `50` | Breadcrumbs kept per scope (capped at 100). |
+| `send_default_pii` | `bool` | `False` | When `False`, the user IP and the `cookie`, `set-cookie`, `authorization`, `proxy-authorization`, `x-forwarded-for`, `x-real-ip` and `forwarded` headers are removed. |
+| `before_send` | `(event) -> event \| None` | `None` | Modify or drop (`None`) an event. Runs after scrubbing. If it raises, the event is dropped. |
+| `ignore_errors` | `list[str \| re.Pattern \| type[BaseException]]` | `[]` | Strings match as substrings and patterns are searched, both against the exception type, the message and `"Type: message"`. Exception classes match with `isinstance`. |
+| `integrations` | `dict` | all `True` | `{"excepthook", "threading", "logging", "http"}` mapped to `True`, `False` or a configured instance (see below). |
+| `enabled` | `bool` | `True` | `False` turns the SDK into a no-op (`api_key` is then not required). |
+| `debug` | `bool` | `False` | Print SDK internals (dropped events, retries, invalid options) to stderr. |
+
+Invalid options never raise:
+
+- An invalid optional value falls back to its default.
+- A missing `api_key` or an unusable `endpoint` disables the SDK.
+- Run with `debug=True` to see why.
+
+### Built-in integrations
+
+- **excepthook**: `sys.excepthook` captures uncaught exceptions at level `fatal`, flushes for
+  up to 2 s, then calls the previous hook, so the traceback is still printed and the exit code
+  is unchanged. `KeyboardInterrupt` is ignored.
+- **threading**: `threading.excepthook` captures exceptions that escape a thread (level
+  `error`), then calls the previous hook.
+- **logging**: log records at `INFO` and above become `log` breadcrumbs. Records with
+  `exc_info` at `ERROR` and above can also be captured as events, which is off by default:
+
+  ```python
+  from faultline import LoggingIntegration
+
+  faultline.init(
+      api_key=...,
+      integrations={
+          "logging": LoggingIntegration(capture_errors=True, breadcrumb_level=logging.DEBUG)
+      },
+  )
+  ```
+
+  The integration wraps `logging.Logger.callHandlers`, so it needs no handler and never
+  changes your logging configuration. The SDK's own `faultline` logger is ignored.
+- **http**: outgoing `http.client` requests, which covers `urllib.request`, `urllib3` and
+  `requests`, become `http` breadcrumbs (method, URL, status). The instrumentation is passive,
+  and the SDK's own ingest requests are never recorded.
+
+## Framework guides
+
+Every framework integration forks a scope per request, attaches the request (method, URL,
+headers, query; scrubbed as described below), adds a `request` breadcrumb, and captures
+unhandled exceptions with `tags: {mechanism, handled: "no"}`. Framework packages are imported
+lazily, only when you import the integration module.
+
+### Flask
+
+```python
+from flask import Flask
+import faultline
+from faultline.integrations.flask import init_app
+
+faultline.init(api_key=os.environ["FAULTLINE_API_KEY"])
+app = init_app(Flask(__name__))
+```
+
+Unhandled exceptions that become a 500 are captured through Flask's `got_request_exception`
+signal. `HTTPException` (`abort(404)`, 405, ...) is not captured. Runnable demo:
+[`examples/flask_app.py`](examples/flask_app.py).
+
+### FastAPI / Starlette
+
+```python
+from fastapi import FastAPI
+import faultline
+from faultline.integrations.fastapi import init_app
+
+faultline.init(api_key=os.environ["FAULTLINE_API_KEY"])
+app = init_app(FastAPI())  # same as app.add_middleware(FaultlineAsgiMiddleware)
+```
+
+`HTTPException` and exceptions handled by your exception handlers are not captured. Sync
+endpoints that run in the threadpool keep the request scope. Runnable demo:
+[`examples/fastapi_app.py`](examples/fastapi_app.py).
+
+### Django
+
+```python
+# settings.py
+import faultline
+
+faultline.init(api_key=os.environ["FAULTLINE_API_KEY"], environment="production")
+
+MIDDLEWARE = [
+    "faultline.integrations.django.FaultlineMiddleware",  # first
+    # ...
+]
+```
+
+Works under WSGI and ASGI. Exceptions are captured through Django's `got_request_exception`
+signal, so `Http404`, `PermissionDenied`, `BadRequest` and `SuspiciousOperation` are not
+reported.
+
+### Any ASGI or WSGI app
+
+```python
+from faultline.integrations.asgi import FaultlineAsgiMiddleware
+
+app = FaultlineAsgiMiddleware(app)  # Quart, Litestar, raw ASGI, ...
+
+from faultline.integrations.wsgi import FaultlineWsgiMiddleware
+
+application = FaultlineWsgiMiddleware(application)  # Bottle, Pyramid, raw WSGI, ...
+```
+
+### Celery, scripts and serverless
+
+The SDK delivers from a background daemon thread and flushes at interpreter exit. Workers
+that are killed or frozen (serverless) should call `faultline.flush()` at the end of each
+invocation.
+
+## Self-hosting
+
+Set `endpoint` to your server's base URL. The SDK posts to `{endpoint}/api/v1/ingest/events`:
+
+```python
+faultline.init(api_key="flt_ingest_...", endpoint="http://localhost:4000")  # local faultline-server
+faultline.init(api_key="flt_ingest_...", endpoint="https://faultline.internal.example.com")
+```
+
+The examples read `FAULTLINE_API_KEY` and `FAULTLINE_ENDPOINT` (default
+`http://localhost:4000`). Proxies configured with `HTTPS_PROXY` / `HTTP_PROXY` are honored.
+
+## What gets sent
+
+Each event follows the shared Faultline event contract: `eventId` (uuid v4), `timestamp`,
+`level`, `platform: "python"`, `exception` (type, value, frames ordered oldest to newest,
+`cause` chain), `message`, `tags`, `user`, `request`, `contexts` (`runtime`, `os`, plus your
+own), `breadcrumbs`, `extra`, `fingerprint`, `environment`, `release`, `serverName`, and
+`sdk: { name: "getfaultline", version }`.
+
+- **Frames** come from the traceback, oldest to newest. A frame is `inApp` unless it lives
+  under `site-packages` / `dist-packages`, the standard library, a synthetic file
+  (`<frozen ...>`, `<string>`), or the SDK itself. In-app frames get +-5 lines of source
+  context (`linecache`, so zip apps work too) and, on Python 3.11+, a column number.
+- **Cause chain**: `__cause__`, otherwise `__context__` unless suppressed with
+  `raise ... from None`. At most 5 exceptions in total; cycles are broken.
+- **Exception groups** are reported as the group itself (its message lists the
+  sub-exceptions) with the first sub-exception as its cause.
+- **Non-exception values** passed to `capture_exception` become a synthetic `Error` with the
+  caller's stack.
+
+The SDK enforces the pinned limits before sending:
+
+| Field | Limit |
+| --- | --- |
+| Frames | 100 (newest kept) |
+| Breadcrumbs | 100 |
+| Tags | 50 (key <= 32 chars, value <= 200 chars) |
+| `message` / `exception.value` | 8192 chars |
+| Source context | +-5 lines, each <= 300 chars |
+| `exception.cause` chain | 5 exceptions in total |
+| Batch | <= 50 events and <= 1 MB |
+
+**Scrubbing (client side, same rules as the server and the Node SDK):**
+
+- Values under keys matching
+  `(authorization|cookie|set-cookie|password|passwd|secret|token|api[_-]?key|x-faultline-key)`
+  (case-insensitive) become `"[Filtered]"`. This applies to request headers and query,
+  `extra`, `contexts`, tags and breadcrumb data.
+- Credit-card-like strings (`\b(?:\d[ -]*?){13,16}\b`) in request, `extra` and breadcrumb data
+  are also filtered, as are sensitive URL query parameters.
+
+**Delivery:**
+
+- Events wait in an in-memory queue of at most 100 events; the oldest is dropped when full.
+- A daemon worker thread sends a batch every 2 s, or as soon as 20 events are queued, gzip
+  compressed. Each request times out after 5 s.
+- Network errors, timeouts, `5xx` and `408` are retried with exponential backoff and jitter
+  (up to 3 retries). A `429` pauses delivery for its `Retry-After`.
+- A `401` or `413` response drops the batch. With `debug=True` the SDK logs the reason.
+- At interpreter exit an `atexit` hook flushes for up to 2 s, then gives up. The SDK never
+  keeps your process alive. After `os.fork()` the child starts a fresh worker.
+- Identical consecutive errors within 1 s are sent once.
+
+## Architecture
+
+The SDK follows Clean Architecture. Dependencies point inward only, and
+[import-linter](https://import-linter.readthedocs.io) enforces this in CI (plus an AST-based
+test in `tests/test_architecture.py`).
+
+```mermaid
+flowchart LR
+  subgraph root["faultline/__init__.py (public API, composition root)"]
+  end
+  subgraph integrations["integrations/"]
+    X[excepthook, threading] --- L[logging] --- H[http.client] --- F[wsgi, asgi, flask, fastapi, django]
+  end
+  subgraph infrastructure["infrastructure/"]
+    T[HttpTransport] --- S[TracebackStackExtractor] --- C[LinecacheSourceReader] --- R[runtime adapters]
+  end
+  subgraph application["application/"]
+    CL[FaultlineClient] --- HB["Hub (contextvars scopes)"] --- PO[ports]
+  end
+  subgraph domain["domain/ (pure Python)"]
+    EV[event contract] --- SC[Scope] --- OP[options] --- SR[scrubbing, limits, normalization]
+  end
+  root --> integrations
+  root --> infrastructure
+  integrations --> application
+  infrastructure --> application
+  application --> domain
+```
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Hub
+  participant Client as FaultlineClient
+  participant Worker as HttpTransport (thread)
+  participant Server as Faultline ingest
+  App->>Hub: capture_exception(exc)
+  Hub->>Client: exc + current scope snapshot (contextvars)
+  Client->>Client: traceback, cause chain, sample, ignore_errors, dedupe
+  Client->>Client: source context, limits, scrub, before_send
+  Client->>Worker: send(event) (non-blocking)
+  Client-->>App: event_id
+  Worker->>Server: POST /api/v1/ingest/events (gzip batch <= 50)
+  Server-->>Worker: 202 / 429 Retry-After / 401 / 413
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the decision log.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]" django
+```
+
+| Command | What it does |
+| --- | --- |
+| `ruff check . && ruff format --check .` | Lint and formatting. |
+| `mypy` | Strict type checking of `src`, `tests` and `examples`. |
+| `lint-imports` | Clean Architecture layer contracts. |
+| `pytest` | Unit, contract-conformance (pydantic), local `http.server` transport, framework and subprocess tests. |
+| `python -m build && twine check dist/*` | Build the sdist and wheel. |
+
+### Releasing
+
+1. Bump `src/faultline/_version.py` and add a `CHANGELOG.md` entry.
+2. Tag `vX.Y.Z` and push the tag.
+3. `.github/workflows/release.yml` runs the checks, builds, and publishes to PyPI with
+   trusted publishing (no API token; configure the trusted publisher on PyPI once).
+
+## License
+
+MIT