{"id":23971,"library":"litestar-saq","title":"litestar-saq","description":"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.","status":"active","version":"0.7.1","language":"python","source_language":"en","source_url":"https://github.com/cofin/litestar-saq","tags":["litestar","saq","queue","async","redis","task-queue"],"install":[{"cmd":"pip install litestar-saq","lang":"bash","label":"Standard install"},{"cmd":"pip install litestar-saq[redis]","lang":"bash","label":"Install with Redis support (recommended)"}],"dependencies":[],"imports":[{"note":"Correct import path","symbol":"SAQPlugin","correct":"from litestar_saq import SAQPlugin"},{"note":"Configuration class for SAQ plugin","symbol":"SAQConfig","correct":"from litestar_saq import SAQConfig"},{"note":"Queue class is from saq library, not from litestar-saq","wrong":"from litestar_saq import Queue","symbol":"Queue","correct":"from saq import Queue"}],"quickstart":{"code":"import os\nfrom litestar import Litestar\nfrom litestar_saq import SAQPlugin, SAQConfig\nfrom saq import Queue\n\nqueue = Queue.from_url(os.environ.get('REDIS_URL', 'redis://localhost:6379'))\n\nasync def hello(ctx):\n    print(\"Hello, world!\")\n\nsaq_config = SAQConfig(queues=[queue], default_queue=queue, worker_processes=1)\nsaq_plugin = SAQPlugin(config=saq_config)\n\napp = Litestar(plugins=[saq_plugin])\n\nif __name__ == \"__main__\":\n    import uvicorn\n    uvicorn.run(app, host=\"0.0.0.0\", port=8000)","lang":"python","description":"Basic Litestar app with SAQ plugin, one queue, one task."},"warnings":[{"fix":"Register the plugin when creating the Litestar app as shown in quickstart.","message":"The SAQPlugin must be registered before any routes that use the queue, otherwise the dashboard may not work.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Wrap your guard in a list: `web_guards=[my_guard]`.","message":"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.","severity":"breaking","affected_versions":"0.6.0+"},{"fix":"Ensure shutdown_grace_period is a positive integer (e.g., 60) or omit it.","message":"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.","severity":"gotcha","affected_versions":"0.7.1"},{"fix":"Use `queues=[...]` and `default_queue=...` instead of `queue=...`.","message":"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.","severity":"deprecated","affected_versions":">=0.6.0"},{"fix":"Configure `worker_logging_config` in SAQConfig to match your logging setup.","message":"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.","severity":"gotcha","affected_versions":">=0.6.2"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `queues=[your_queue]` and `default_queue=your_queue` in SAQConfig.","cause":"In SAQConfig, the 'queue' parameter was renamed to 'queues' and 'default_queue' in v0.6.0.","error":"TypeError: __init__() got an unexpected keyword argument 'queue'"},{"fix":"Set shutdown_grace_period to a positive integer in SAQConfig, e.g., `SAQConfig(shutdown_grace_period=60)`.","cause":"Shutdown_grace_period is None or not set, causing a bug in shutdown logic in v0.7.0/v0.7.1.","error":"TypeError: 'NoneType' object is not subscriptable"},{"fix":"Install saq: `pip install saq` or use the redis extra: `pip install litestar-saq[redis]` which includes saq.","cause":"The `saq` package is not installed. litestar-saq depends on it but may not install it automatically without extras.","error":"ModuleNotFoundError: No module named 'saq'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}