Metadata-Version: 2.4
Name: litestar-queues
Version: 0.8.0
Summary: Task queues, workers, schedules, and backend integrations for Litestar
Project-URL: Changelog, https://cofin.github.io/litestar-queues/changelog
Project-URL: Discord, https://discord.gg/litestar-919193495116337154
Project-URL: Documentation, https://cofin.github.io/litestar-queues/
Project-URL: Homepage, https://cofin.github.io/litestar-queues/
Project-URL: Issue, https://github.com/cofin/litestar-queues/issues/
Project-URL: Source, https://github.com/cofin/litestar-queues
Author-email: Cody Fincher <cody@litestar.dev>
License: MIT
License-File: LICENSE
Keywords: advanced-alchemy,background-jobs,cloud-run,litestar,queue,redis,scheduled-tasks,sqlspec,task-queue,tasks,valkey,workers
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: litestar>=2.24.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: advanced-alchemy
Requires-Dist: advanced-alchemy>=1.10.0; extra == 'advanced-alchemy'
Provides-Extra: cloud-tasks
Requires-Dist: google-cloud-tasks>=2.23.0; extra == 'cloud-tasks'
Provides-Extra: cloudrun
Requires-Dist: google-cloud-run>=0.10.0; extra == 'cloudrun'
Provides-Extra: otel
Requires-Dist: opentelemetry-api; extra == 'otel'
Requires-Dist: opentelemetry-sdk; extra == 'otel'
Provides-Extra: prometheus
Requires-Dist: prometheus-client; extra == 'prometheus'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: sqlspec
Requires-Dist: sqlspec>=0.58.0; extra == 'sqlspec'
Provides-Extra: sqs
Requires-Dist: aiobotocore>=3.8.0; extra == 'sqs'
Provides-Extra: valkey
Requires-Dist: valkey>=6.0.0; extra == 'valkey'
Description-Content-Type: text/markdown

# Litestar Queues

[![PyPI](https://img.shields.io/pypi/v/litestar-queues)](https://pypi.org/project/litestar-queues/)
[![Python](https://img.shields.io/pypi/pyversions/litestar-queues)](https://pypi.org/project/litestar-queues/)
[![License](https://img.shields.io/pypi/l/litestar-queues)](https://github.com/cofin/litestar-queues/blob/main/LICENSE)
[![CI](https://github.com/cofin/litestar-queues/actions/workflows/ci.yml/badge.svg)](https://github.com/cofin/litestar-queues/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-cofin.github.io-blue)](https://cofin.github.io/litestar-queues/)

Litestar Queues lets a Litestar application persist work, run it in a worker,
and inspect the result. Use it for work that should outlive the request that
started it: sending email, importing files, refreshing reports, or calling a
slow service.

## Quickstart

Install the package:

```bash
pip install litestar-queues
```

Create `app.py`:

```python
from litestar import Litestar, post
from litestar.di import NamedDependency

from litestar_queues import QueueConfig, QueuePlugin, QueueService, task


@task("accounts.sync", queue="accounts", timeout=30)
async def sync_account(account_id: str) -> dict[str, str]:
    return {"account_id": account_id, "status": "synced"}


@post("/accounts/{account_id:str}/sync")
async def create_sync_job(
    account_id: str,
    queue_service: NamedDependency[QueueService],
) -> dict[str, str]:
    result = await queue_service.enqueue(sync_account, account_id)
    return {"task_id": str(result.id), "status": result.status or "pending"}


app = Litestar(
    route_handlers=[create_sync_job],
    plugins=[QueuePlugin(config=QueueConfig())],
)
```

Run the application:

```bash
LITESTAR_APP=app:app litestar run --reload
```

Enqueue a task:

```bash
curl -X POST http://127.0.0.1:8000/accounts/acct-123/sync
```

The response contains a task ID and an initial status. `QueueConfig()` starts
one fresh queue-worker child for this `litestar run` invocation and shares a
private temporary SQLite file with it. No queue socket or port is exposed, and
the temporary queue is removed on normal shutdown; it is not durable across
server restarts.

## Production boundary

Choose where tasks are stored separately from where they run. For durable
deployments use a shared backend such as SQLSpec, Advanced Alchemy, Redis, or
Valkey. Use standalone workers when the web app and task workers must scale
separately. The process-local memory backend remains useful for inline tests
or an explicitly single-ASGI-process worker. Cloud Run runs tasks; it does not
store them.

## Next steps

- [Start here](https://cofin.github.io/litestar-queues/getting_started/index.html)
- [Understand the model](https://cofin.github.io/litestar-queues/usage/concepts.html)
- [Follow a how-to guide](https://cofin.github.io/litestar-queues/usage/index.html)
- [Choose backends](https://cofin.github.io/litestar-queues/usage/backends.html)
- [Run an example](https://cofin.github.io/litestar-queues/examples/index.html)
- [Browse the API reference](https://cofin.github.io/litestar-queues/reference/index.html)

Litestar Queues supports Python 3.10 through 3.14 and is licensed under MIT.
