Metadata-Version: 2.4
Name: apidepth
Version: 0.1.0
Summary: Apidepth SDK for Python — track outbound API latency, error rates, and rate limit quota.
Project-URL: Homepage, https://www.apidepth.io
Project-URL: Source, https://github.com/apidepth/apidepth-python
Project-URL: Issues, https://github.com/apidepth/apidepth-python/issues
License: MIT License
        
        Copyright (c) 2026 Apidepth
        
        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.
License-File: LICENSE
Keywords: api,apidepth,http,monitoring,observability
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: django>=3.2; extra == 'all'
Requires-Dist: flask>=2.0; extra == 'all'
Requires-Dist: httpx>=0.23; extra == 'all'
Requires-Dist: requests>=2.20; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.23; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: requests>=2.20; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=3.2; extra == 'django'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Provides-Extra: httpx
Requires-Dist: httpx>=0.23; extra == 'httpx'
Provides-Extra: requests
Requires-Dist: requests>=2.20; extra == 'requests'
Description-Content-Type: text/markdown

# apidepth-python

Track outbound API latency, error rates, and rate limit quota across your third-party vendors — Stripe, OpenAI, Anthropic, Twilio, GitHub, and more.

Zero config for supported vendors. No code changes to your existing HTTP calls.

---

## Installation

```bash
pip install apidepth
```

For `requests` instrumentation (most common):
```bash
pip install "apidepth[requests]"
```

For `httpx` instrumentation:
```bash
pip install "apidepth[httpx]"
```

---

## Quick start

### Django

Add to `INSTALLED_APPS` and configure in `settings.py`:

```python
INSTALLED_APPS = [
    ...
    "apidepth.integrations.django",
]

APIDEPTH = {
    "api_key": env("APIDEPTH_API_KEY"),
    "environment": env("DJANGO_ENV", default="development"),
}
```

### Flask

```python
from flask import Flask
from apidepth.integrations.flask import Apidepth

app = Flask(__name__)
app.config["APIDEPTH_API_KEY"] = os.environ["APIDEPTH_API_KEY"]
app.config["APIDEPTH_ENVIRONMENT"] = "production"

Apidepth(app)
```

### Standalone / scripts

```python
import apidepth
from apidepth import registry_loader

apidepth.configure(
    api_key=os.environ["APIDEPTH_API_KEY"],
    environment="production",
)
apidepth.instrument()       # call before any outbound HTTP
registry_loader.load_and_start()  # loads remote vendor registry + starts refresh thread

import requests
resp = requests.get("https://api.stripe.com/v1/charges/ch_abc123", ...)
```

`load_and_start()` fetches the latest vendor registry from the network (with a local disk cache fallback) and starts a background refresh thread. Without it, only the six bundled vendors are recognised. Django and Flask integrations call this automatically.

For **Gunicorn / uWSGI**, call `Collector.register_fork_safety()` once before the server forks so each worker gets its own flush thread:

```python
from apidepth.collector import Collector
Collector.register_fork_safety()
```

---

## Configuration

| Option | Default | Description |
|---|---|---|
| `api_key` | `None` | **Required.** Your Apidepth API key. |
| `environment` | `None` | Deployment environment tag, e.g. `"production"`. |
| `enabled` | `True` | Set `False` to disable all instrumentation. |
| `sample_rate` | `1.0` | Float 0.0–1.0. Fraction of requests to capture. |
| `ignored_hosts` | `[]` | List of hostnames to never record. |
| `extra_vendors` | `{}` | Map `{"vendor-name": "host"}` for in-house APIs. |
| `flush_interval` | `20` | Background flush interval in seconds. |
| `registry_cache_path` | `/tmp/apidepth_registry.json` | Disk cache for the vendor registry. |
| `registry_refresh_interval` | `21600` | Registry refresh interval in seconds (6 h). |
| `on_flush_error` | `None` | `Callable(exc, ctx)` for routing errors to Sentry etc. |
| `collector_url` | production endpoint | Override for self-hosted collectors. |

---

## What gets captured

Every outbound HTTP request to a recognised vendor produces one event:

| Field | Example |
|---|---|
| `vendor` | `"stripe"` |
| `endpoint` | `"/v1/charges/:id"` |
| `method` | `"POST"` |
| `status` | `200` |
| `outcome` | `"success"` / `"client_error"` / `"server_error"` / `"timeout"` |
| `duration_ms` | `234` |
| `cold_start` | `false` (always — see [Known differences](#known-differences-from-the-ruby-gem)) |
| `env` | `"production"` |
| `ts` | `1747008000000` (epoch ms) |
| `rl_remaining` | `4999` (when rate limit headers present) |
| `rl_limit` | `5000` |
| `rl_reset_at` | `1747008060000` (epoch ms) |

**Never captured:** request/response bodies, headers, query parameters, credentials.

---

## Supported vendors

| Vendor | Host |
|---|---|
| Stripe | `api.stripe.com` |
| OpenAI | `api.openai.com` |
| Anthropic | `api.anthropic.com` |
| Twilio | `api.twilio.com` |
| Resend | `api.resend.com` |
| GitHub | `api.github.com` |

Additional vendors are loaded from the remote registry every 6 hours.

### Custom vendors

```python
apidepth.configure(
    extra_vendors={"payments-api": "api.payments.internal"},
)
```

---

## Rate limit tracking

The SDK extracts quota state from response headers and includes it in every event.
Supported header families (checked in priority order):

- **OpenAI / Anthropic**: `x-ratelimit-remaining-requests`, `x-ratelimit-limit-requests`, `x-ratelimit-reset-requests`
- **GitHub**: `x-ratelimit-remaining`, `x-ratelimit-limit`, `x-ratelimit-reset`
- **IETF draft / HubSpot**: `ratelimit-remaining`, `ratelimit-limit`, `ratelimit-reset`
- **Stripe / generic 429**: `retry-after`

Reset values are normalised to epoch milliseconds regardless of the source format (Unix timestamp, seconds-from-now, OpenAI duration strings like `"1m30s"`).

---

## Debugging

```python
from apidepth.collector import Collector

print(Collector.instance().stats())
# {
#   'queue_size': 0,
#   'consecutive_failures': 0,
#   'total_dropped': 0,
#   'last_flush_at': 1747008000.123,
# }
```

---

## Framework compatibility

| Framework | Version | Integration |
|---|---|---|
| Django | 3.2+ | `apidepth.integrations.django` in `INSTALLED_APPS` |
| Flask | 2.0+ | `Apidepth(app)` |
| FastAPI / Starlette | any | Call `apidepth.instrument()` at startup |
| Scripts / workers | — | Call `apidepth.instrument()` at startup |

---

## Python compatibility

Python 3.9–3.13. No required runtime dependencies (stdlib only). `requests` and `httpx` are optional instrumentation targets detected at runtime.

---

## Known differences from the Ruby gem

### `cold_start` is always `false`

The Ruby gem tags the **first** outbound request on each TCP connection with `cold_start: true` using `Net::HTTP#started?`. The Apidepth collector uses this flag to exclude DNS + TCP + TLS handshake overhead from latency percentile calculations (p50/p95/p99), keeping those metrics representative of steady-state vendor performance.

Neither `requests` (backed by urllib3) nor `httpx` exposes a public API for detecting whether the underlying socket is a keep-alive reuse. The Python SDK therefore always sends `cold_start: false`.

**Practical impact depends on your traffic pattern:**

| Traffic pattern | Impact |
|---|---|
| High-throughput web service | **Negligible** — cold starts are a tiny fraction of total requests; percentile inflation is unmeasurable |
| Low-throughput service / cron job | **Noticeable** — the first request per run pays ~50–200 ms of connection overhead that isn't excluded from percentiles; p95/p99 may read slightly higher than in Ruby |
| Serverless / short-lived worker | **Material** — every invocation starts cold; all latency data includes connection overhead; comparisons against Ruby-instrumented services will show the Python side as systematically higher |

The raw duration values are accurate — only the percentile statistics are affected. If cold-start exclusion matters for your environment, filter those events manually in your dashboard (e.g. a warm-up request flag in thread-local state) until the underlying libraries expose the required connection-state API.
