Metadata-Version: 2.4
Name: wardenpoint
Version: 0.1.0
Summary: Official Python SDK for WardenPoint incident alerting
Project-URL: Homepage, https://wardenpoint.com
Project-URL: Repository, https://github.com/WardenPoint/wardenpoint-python
Author: WardenPoint
License: MIT
License-File: LICENSE
Keywords: alerting,devops,incident,on-call,pagerduty,sdk,sre
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# WardenPoint Python SDK

[![CI](https://github.com/WardenPoint/wardenpoint-python/actions/workflows/ci.yml/badge.svg)](https://github.com/WardenPoint/wardenpoint-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/wardenpoint.svg)](https://pypi.org/project/wardenpoint/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Official Python SDK for [WardenPoint](https://wardenpoint.com) — incident
alerting and on-call escalation. Fire and manage alerts from your apps,
jobs and pipelines; page on-call automatically when code fails.

## Install

```sh
pip install wardenpoint
```

## Quickstart

```python
from wardenpoint import WardenPoint

wp = WardenPoint(api_key="wp_live_xxx")        # or set WARDENPOINT_API_KEY

# send to a recipient (UUID or exact name) at a priority
wp.alerts.send(recipient="ops-oncall", message="DB primary down", priority="high")

# send to a whole group
wp.alerts.send_to_group(group="<group-uuid>", message="API SLO burn", priority="critical")

# fire a pre-configured template
wp.templates.fire("disk-full", vars={"host": "web-3", "pct": 95}, override={"priority": "high"})

# inspect / acknowledge / cancel
wp.alerts.list()
wp.alerts.status("<id>")
wp.alerts.acknowledge("<uuid>")
wp.alerts.cancel("<uuid>")
wp.recipients.list()
```

Priorities: `low`, `normal`, `high`, `critical`.

`templates.fire(...)` requires alert templates to be enabled for your company
(a per-tenant setting in the dashboard); otherwise the call returns an
`APIError`.

## Page automatically when code fails

The context manager and decorator alert on-call with the exception and
traceback if the wrapped code raises — then re-raise, so behaviour is
unchanged otherwise. A delivery failure never masks your original error.

```python
# context manager
with wp.guard(group="sre", title="nightly ETL"):
    run_etl()

# decorator for jobs
@wp.on_failure(to="ops-oncall", priority="high")
def reconcile_invoices():
    ...
```

## Configuration

| Setting | Argument | Environment |
|---|---|---|
| API key | `api_key=` | `WARDENPOINT_API_KEY` |
| Base URL | `base_url=` | `WARDENPOINT_BASE_URL` (default `https://wardenpoint.com/api/v1`) |
| TLS verify | `verify=` | — (set `False` only for self-hosted/staging with self-signed certs) |

`WardenPoint` is also a context manager (closes the HTTP client on exit):

```python
with WardenPoint(api_key="...") as wp:
    wp.alerts.send(recipient="...", message="...")
```

## Errors

- `wardenpoint.APIError` — non-2xx response (`.status`, `.message`, `.body`).
- `wardenpoint.WardenPointError` — config / validation / resolution errors.

## Development

```sh
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## License

MIT — see [LICENSE](LICENSE).
