WardenPoint Python SDK

Official Python SDK for WardenPoint — incident alerting and on-call escalation. Fire and manage alerts from your apps, jobs and pipelines; page on-call automatically when code fails.

Install

pip install wardenpoint

Quickstart

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.

# 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():
    ...

Get paged from your logs — one line

Attach WardenPointHandler to any logger and ERROR-level records page on-call through WardenPoint — phone call, Telegram voice, escalation chain, all of it.

import logging
from wardenpoint import WardenPointHandler

logging.getLogger().addHandler(WardenPointHandler(group="oncall"))

logging.error("payments DB is down")     # -> pages on-call

It is built to stay out of your application's way:

• Non-blocking — records go to a background worker thread, so the logging call returns immediately; the bounded queue drops on overload instead of stalling your app.
• Throttled — the same error pages at most once per throttle_window (default 300s); suppressed repeats are counted on the next alert.
• Bulletproof — never raises into your code, surfaces delivery failures on stderr, and ignores its own log records (no feedback loop).

WardenPointHandler(
    recipient="Ops On-Call",   # or group="<group-uuid>"
    level=logging.ERROR,       # minimum level to page on
    throttle_window=300,       # seconds; 0 disables dedup
    include_traceback=True,    # attach traceback when exc_info is set
)

Pairs well with guard()/on_failure() above: use those for the blocks you care about, and the handler as a catch-all for everything that hits ERROR.

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):

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

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

License

MIT — see LICENSE.