Metadata-Version: 2.4
Name: watchforge-sdk
Version: 0.1.1
Summary: WatchForge Python SDK
Author-email: WatchForge <support@watchforge.io>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# WatchForge Python SDK (`watchforge-sdk`)

Python SDK for WatchForge — errors, traces, structured logs, and releases. Aligned with `@watchforge/browser` (JavaScript) and the other WatchForge language SDKs.

## Install

```bash
pip install watchforge-sdk
```

## Quick start

```python
from watchforge_sdk import register
import logging

register(
    endpoint="https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID",
    app_env="production",
    release="my-api@1.0.0",  # for Releases / crash-free
    traces_sample_rate=1.0,  # 100% of traces (Sentry-style 0.0–1.0)
    enable_logs=True,        # structured logs (default True)
)

logging.info("hello")  # captured automatically when enable_logs + auto_capture_logging
```

## Feature matrix

| Feature | Supported | Notes |
| --- | --- | --- |
| **Errors** | Yes | Unhandled exceptions + `capture_exception` / `capture_message` |
| **Traces** | Yes | Integrations (e.g. Django) + `start_transaction`; sampled via `traces_sample_rate` |
| **Session Replay** | Not supported | Browser / mobile client SDKs only |
| **Logs** | Yes | `enable_logs` + stdlib `logging` (`auto_capture_logging`) + `capture_log` |
| **Releases** | Yes | Set `release` at `register()`; view under **Releases** (project-scoped) |

## Errors

With default settings, unhandled exceptions are captured automatically. For handled errors:

```python
from watchforge_sdk import capture_exception, capture_message

try:
    process()
except Exception as e:
    capture_exception(e)

capture_message("payment processed", level="info")
```

## Traces

Set `traces_sample_rate` once at register (Sentry-style **0.0–1.0**). Unsampled traces are dropped and not sent.

Prefer framework integrations (e.g. Django) so request traces are created automatically when the sample rate is &gt; 0. Manual instrumentation:

```python
from watchforge_sdk import start_transaction, finish_transaction

txn = start_transaction("/api/orders", "Create Order", op="http.server")
span = txn.start_span("db.query", "INSERT orders")
span.finish()
finish_transaction("ok")
```

## Session Replay

**Not supported** in the Python SDK. Use `@watchforge/browser` (or other client SDKs) for session replay.

## Logs

Like Sentry’s `enableLogs`: leave `enable_logs=True` (default). With `auto_capture_logging=True`, messages from Python’s `logging` module are sent automatically. You can also call `capture_log` directly. Set `enable_logs=False` to disable both auto capture and `capture_log`.

```python
import logging
from watchforge_sdk import capture_log, capture_api_log, flush_logs

logging.info("user signed in")  # auto-captured

capture_log("order created", level="info", attributes={"order_id": "123"})
capture_api_log("GET /orders", attributes={"status": 200})
flush_logs()
```

## Releases

Set `release` once at `register()` (e.g. `my-api@1.2.3`). Errors and traces tagged with that version appear under **Releases** for the project (sidebar → Releases). Omit `release` if you do not need release tracking.

## Config options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `endpoint` / `dsn` | str | required | Project DSN |
| `app_env` / `environment` | str | `"production"` | Environment name |
| `release` | str | `None` | Deploy version for **Releases** / crash-free (e.g. `my-api@1.2.3`) |
| `auto_capture_exceptions` | bool | `True` | Capture unhandled exceptions |
| `enable_logs` | bool | `True` | Gate structured logs (Sentry-style). When `False`, `capture_log` is a no-op and auto logging is skipped |
| `auto_capture_logging` | bool | `True` | Capture stdlib `logging` messages (requires `enable_logs=True`) |
| `logging_level` | int | `logging.INFO` | Minimum level for auto log capture |
| `debug` | bool | `False` | Verbose SDK logging |
| `integrations` | list | `None` | e.g. `[DjangoHandler()]` for request traces |
| `traces_sample_rate` | float | `1.0` | Fraction of traces to send (**0.0–1.0**). `1.0` = 100%, `0.1` = 10%, `0.0` = off. Values &gt; 1 are treated as percent (`100` → `1.0`). |

## Cron monitors

```python
from watchforge_sdk import capture_checkin

check_in_id = capture_checkin("nightly-job", status="in_progress", monitor_config={...})
capture_checkin("nightly-job", status="ok", check_in_id=check_in_id)
```

## License

MIT
