litestar-saq

0.7.1 verified Fri May 01 auth: no python

Litestar integration for SAQ (Simple Async Queue). Provides a plugin to easily add SAQ task queues to Litestar applications, with built-in dashboard and worker management. Current version 0.7.1, requires Python >=3.9.

pip install litestar-saq

Common errors

error TypeError: __init__() got an unexpected keyword argument 'queue' ↓

cause In SAQConfig, the 'queue' parameter was renamed to 'queues' and 'default_queue' in v0.6.0.

fix

Use queues=[your_queue] and default_queue=your_queue in SAQConfig.

error TypeError: 'NoneType' object is not subscriptable ↓

cause Shutdown_grace_period is None or not set, causing a bug in shutdown logic in v0.7.0/v0.7.1.

fix

Set shutdown_grace_period to a positive integer in SAQConfig, e.g., SAQConfig(shutdown_grace_period=60).

error ModuleNotFoundError: No module named 'saq' ↓

cause The `saq` package is not installed. litestar-saq depends on it but may not install it automatically without extras.

fix

Install saq: pip install saq or use the redis extra: pip install litestar-saq[redis] which includes saq.

Warnings

gotcha The SAQPlugin must be registered before any routes that use the queue, otherwise the dashboard may not work. ↓

fix Register the plugin when creating the Litestar app as shown in quickstart.

breaking Version 0.6.0 introduced breaking changes: `build_controller` now requires `web_guards` parameter as a list of callables instead of a single callable. Passing a single callable will raise TypeError. ↓

fix Wrap your guard in a list: `web_guards=[my_guard]`.

gotcha The `shutdown_grace_period` argument in SAQConfig must be a positive integer or None. Passing None or an integer less than 1 may cause a TypeError on shutdown. ↓

fix Ensure shutdown_grace_period is a positive integer (e.g., 60) or omit it.

deprecated The `queue` parameter in SAQConfig is deprecated in favor of `queues` (list) and `default_queue` as separate parameters. Using `queue` may be removed in future. ↓

fix Use `queues=[...]` and `default_queue=...` instead of `queue=...`.

gotcha If you use `structlog` for logging, the worker process may reconfigure logging in a way that breaks your application's logging setup. Set `worker_logging_config` to control this. ↓

fix Configure `worker_logging_config` in SAQConfig to match your logging setup.

Install

pip install litestar-saq[redis]

Imports

SAQPlugin
```
from litestar_saq import SAQPlugin
```
Correct import path
SAQConfig
```
from litestar_saq import SAQConfig
```
Configuration class for SAQ plugin
Queue
wrong
```
from litestar_saq import Queue
```
correct
```
from saq import Queue
```
Queue class is from saq library, not from litestar-saq

Quickstart

Basic Litestar app with SAQ plugin, one queue, one task.

import os
from litestar import Litestar
from litestar_saq import SAQPlugin, SAQConfig
from saq import Queue

queue = Queue.from_url(os.environ.get('REDIS_URL', 'redis://localhost:6379'))

async def hello(ctx):
    print("Hello, world!")

saq_config = SAQConfig(queues=[queue], default_queue=queue, worker_processes=1)
saq_plugin = SAQPlugin(config=saq_config)

app = Litestar(plugins=[saq_plugin])

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)