QStash Python SDK

QStash is the official Python SDK for Upstash QStash, an HTTP-based messaging and scheduling service built for serverless and edge runtimes. It gives Python applications a typed client to publish messages, create cron schedules, manage queues and URL groups, and verify incoming webhook signatures without running any message-broker infrastructure of your own.

The SDK wraps the QStash REST API behind ergonomic synchronous and asyncio clients, handling authentication, automatic retries with configurable backoff, dead-letter queue inspection, flow control, and content-based deduplication. It is a good fit for serverless functions that need reliable at-least-once delivery, delayed jobs, or scheduled callbacks.

What You Get

• Synchronous QStash client and a mirrored asyncio client for the same API surface
• Message publishing with delays, retries, callbacks, failure callbacks, and content-based deduplication
• Cron-based schedule creation and management for recurring HTTP jobs
• Queue, URL group, DLQ, flow-control, log, and signing-key management APIs
• A Receiver helper that verifies Upstash-Signature headers on incoming webhooks

Common Use Cases

• Offloading background work from serverless functions to a durable HTTP queue
• Scheduling recurring tasks with cron expressions without a dedicated scheduler
• Delivering delayed or callback-driven webhooks with automatic retries
• Verifying the authenticity of QStash-delivered requests in your handlers

Under The Hood

Architecture — The public entrypoint is the QStash class in qstash/client.py, which constructs a shared HttpClient (qstash/http.py) and composes a set of resource-specific API objects (MessageApi, ScheduleApi, QueueApi, UrlGroupApi, SigningKeyApi, LogApi, DlqApi, FlowControlApi). Each resource module translates method calls into REST requests against the QStash service, with dataclass/TypedDict response models such as DlqMessage. A parallel qstash/asyncio package mirrors every resource for async/await callers, and qstash/receiver.py implements JWT-based signature verification independently of the client.

Tech Stack — Pure Python (3.8+), packaged with Poetry. Runtime dependencies are minimal: httpx for the HTTP transport (sync and async) and pyjwt for signature verification. Dev tooling includes pytest with pytest-asyncio, mypy, and ruff.

Code Quality — The qstash package ships a py.typed marker and is fully type-annotated. A comprehensive tests/ suite covers messages, schedules, queues, URL groups, DLQ, flow control, signing keys, and the receiver, with a parallel tests/asyncio suite for the async client. Modules are small and single-responsibility, one file per QStash resource.

API Design — The client is deliberately ergonomic: a single token constructs the client, and resources are accessed as attributes (client.message.publish_json(...), client.schedule.create(...)). Keyword arguments map directly onto QStash features (delay, retries, callback, deduplication), and the README documents the common paths with runnable snippets.