litestar-saq

library0.8.0pypypi✓ verified 85d ago

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.

web-framework workflow database

pip install litestar-saq

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · LITESTAR-SAQ

litestar-saq

web-frameworkpythonv0.8.0

Install

6.5s avg

Import

1341ms

Disk

72MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 1.362s · 72.3MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 6.5s · import 1.319s · 74MB

72MB installed

● package 72MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SAQPlugin

✓ from litestar_saq import SAQPlugin

Correct import path

SAQConfig

✓ from litestar_saq import SAQConfig

Configuration class for SAQ plugin

Queue

✓ from saq import Queue

✗ from litestar_saq import Queue

Queue class is from saq library, not from litestar-saq

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)

Debug

Known issues

gotchaThe 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.

affects: >=0.5.0

breakingVersion 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]`.

affects: 0.6.0+

gotchaThe `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.

affects: 0.7.1

deprecatedThe `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=...`.

affects: >=0.6.0

gotchaIf 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.

affects: >=0.6.2

Errors

Common errors & fixes

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

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.

TypeError: 'NoneType' object is not subscriptable

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)`.

ModuleNotFoundError: No module named 'saq'

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.

Upgrade

Version history

0.8.0latest on PyPI · released Jun 3, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cofin/litestar-saq ↗

packagehttps://pypi.org/project/litestar-saq/ ↗

homepagehttps://cofin.github.io/litesatr-saq/latest/ ↗

docshttps://cofin.github.io/litesatr-saq/latest/ ↗

changeloghttps://cofin.github.io/litesatr-saq/latest/changelog ↗