---
title: Python SDK
description: Install and use the official Trigv Python client for scripts, cron jobs, workers, backend services, and CI pipelines.
---
# Python SDK

Use the official Trigv Python SDK to send push notifications from scripts, cron jobs, backend services, automation workers, and CI pipelines.

## Install

```
pip install trigv
```

Requires Python 3.10 or newer and has no runtime dependencies beyond the standard library.

## Send a notification

```
import os
from trigv import Trigv

trigv = Trigv(api_key=os.environ["TRIGV_API_KEY"])

result = trigv.send_event(
		{
			"channel": "general",
			"title": "Script finished",
			"description": "Nightly import completed",
			"level": "success",
			"event_type": "script.completed",
		}
)

print(result.event.public_id, result.event.status)
```

## Event fields

| Field | Required | Description |
| --- | :---: | --- |
| `channel` | Yes | Channel slug, such as `general`, `deploys`, or `payments`. |
| `title` | Yes | Push notification title. |
| `description` | No | Body text shown in the notification. |
| `image_url` | No | HTTPS image URL for screenshots, charts, camera snapshots, or previews. |
| `url` | No | Destination URL opened from the notification. |
| `level` | No | `info`, `success`, `warning`, or `error`. Defaults to `info`. |
| `delivery_urgency` | No | `standard` or `time_sensitive`. Defaults to `standard`. |
| `event_type` | No | Free-form event label such as `deploy.completed` or `cron.failed`. |
| `idempotency_key` | No | Deduplication key for safe retries. |

Do not send `api_key` in the payload. The SDK sends it through the `Authorization` header.

## Safe retries with idempotency

```
result = trigv.send_event(
		{
			"channel": "deploys",
			"title": "Production deploy complete",
			"idempotency_key": "deploy-prod-42",
		}
)

if result.duplicate:
		print("Already sent:", result.event.public_id)
```

## Configuration

```
trigv = Trigv(
			api_key="trgv_your_api_key",
			base_url="https://api.trigv.com/api",
			timeout=30.0,
			max_retries=2,
)
```

| Option | Default | Description |
| --- | --- | --- |
| `api_key` | `TRIGV_API_KEY` | Workspace API key. |
| `base_url` | `https://api.trigv.com/api` | API base URL. |
| `timeout` | `30.0` | Request timeout in seconds. |
| `max_retries` | `2` | Retry count for retryable failures. |

## Verify the API key

```
connection = trigv.verify_connection()
print(connection.workspace.name)
print(connection.api_key.prefix)
```

## Error handling

```
from trigv import (
		AuthenticationError,
		AuthorizationError,
		NotFoundError,
		RateLimitError,
		Trigv,
		ValidationError,
)

trigv = Trigv()

try:
		trigv.send_event({"channel": "general", "title": "Hello"})
except ValidationError as exc:
		print(exc.errors)
except AuthenticationError:
		print("Check your API key")
except AuthorizationError:
		print("Key is valid but not allowed")
except NotFoundError:
		print("Channel does not exist")
except RateLimitError as exc:
		print("Retry shortly" if exc.retryable else "Monthly cap reached")
```

## Good places to use it

- Cron jobs and scheduled scripts
- Data pipelines, model training runs, and long-running workers
- Django, Flask, FastAPI, or backend automation code

<DocsResourceLinks
  packageHref="https://pypi.org/project/trigv/"
  packageTitle="PyPI package"
  packageDescription="Install the official Trigv Python SDK from PyPI."
  packageLabel="PyPI"
  sourceHref="https://github.com/Trigv/trigv-python"
  sourceDescription="View the Python SDK source on GitHub."
/>