Metadata-Version: 2.4
Name: litestar-queues
Version: 0.4.0
Summary: Task queues, workers, schedules, and backend integrations for Litestar
Project-URL: Changelog, https://github.com/cofin/litestar-queues/releases/
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: 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: rabbitmq
Requires-Dist: aio-pika>=9.6; extra == 'rabbitmq'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: sqlspec
Requires-Dist: sqlspec>=0.55.0; extra == 'sqlspec'
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. The default in-memory
queue and in-app worker are ideal for this first run.

## Production boundary

Choose where tasks are stored separately from where they run. The default
memory backend stores tasks in one Python process. If the web app and worker
run in separate processes, 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. 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.
