Python SDK

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

Install

Code

pip install trigv

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

Send a notification

Code

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

Code

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

Code

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

Code

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

Error handling

Code

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

Additional resources

PyPI package Install the official Trigv Python SDK from PyPI.

Source code View the Python SDK source on GitHub.