Metadata-Version: 2.4
Name: asyncmq
Version: 0.9.0
Summary: Async task queue with BullMQ-like features
Project-URL: Homepage, https://github.com/dymmond/asyncmq
Project-URL: Documentation, https://asyncmq.dymmond.com
Project-URL: Changelog, https://asyncmq.dymmond.com/release-notes/
Project-URL: Funding, https://github.com/sponsors/tarsil
Project-URL: Source, https://github.com/dymmond/asyncmq
Author-email: Tiago Silva <tiago@tarsild.io>
License-File: LICENSE
Keywords: anyio,asyncio,background-jobs,celery-alternative,concurrency,cron,dead-letter-queue,esmerald,fastapi,job-scheduler,microservices,mongodb,parallelism,postgresql,rate-limiter,ravyn,redis,retry-policy,task-queue
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AnyIO
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: croniter<7.0.0,>=6.0.0
Requires-Dist: lilya[standard]>=0.27.0
Requires-Dist: redis>=7.0.0
Requires-Dist: sayer>=0.7.4
Provides-Extra: aio-pika
Requires-Dist: aio-pika>=9.5.8; extra == 'aio-pika'
Provides-Extra: all
Requires-Dist: aio-pika>=9.5.8; extra == 'all'
Requires-Dist: asyncpg>=0.30.0; extra == 'all'
Requires-Dist: motor>=3.7.0; extra == 'all'
Provides-Extra: mongo
Requires-Dist: motor>=3.7.0; extra == 'mongo'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
Provides-Extra: testing
Requires-Dist: aio-pika>=9.5.5; extra == 'testing'
Requires-Dist: anyio[trio]<6.0.0,>=4.9.0; extra == 'testing'
Requires-Dist: autoflake<3.0.0,>=2.0.2; extra == 'testing'
Requires-Dist: black<25.0,==24.1.1; extra == 'testing'
Requires-Dist: fastapi; extra == 'testing'
Requires-Dist: httpx; extra == 'testing'
Requires-Dist: ipdb; extra == 'testing'
Requires-Dist: isort<6.0.0,>=5.12.0; extra == 'testing'
Requires-Dist: playwright>=1.49.0; extra == 'testing'
Requires-Dist: pyjwt; extra == 'testing'
Requires-Dist: pytest-asyncio>=0.26.0; extra == 'testing'
Requires-Dist: pytest-codspeed>=4.3.0; extra == 'testing'
Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == 'testing'
Requires-Dist: pytest<9.0.0,>=7.2.2; extra == 'testing'
Requires-Dist: structlog>=25.3.0; extra == 'testing'
Requires-Dist: uvicorn>=0.34.2; extra == 'testing'
Description-Content-Type: text/markdown

# AsyncMQ

<p align="center">
  <a href="https://asyncmq.dymmond.com"><img src="https://res.cloudinary.com/dymmond/image/upload/v1746002620/asyncmq/oq2qhgqdlra7rudxaqhl.png" alt="AsyncMQ Logo"></a>
</p>

<p align="center">
  <strong>Async task queues, workers, retries, scheduling, and operations visibility for Python.</strong>
</p>

<p align="center">
  <a href="https://github.com/dymmond/asyncmq/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" target="_blank">
    <img src="https://github.com/dymmond/asyncmq/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" alt="Test Suite">
  </a>
  <a href="https://pypi.org/project/asyncmq" target="_blank">
    <img src="https://img.shields.io/pypi/v/asyncmq?color=%2334D058&label=pypi%20package" alt="Package version">
  </a>
  <a href="https://img.shields.io/pypi/pyversions/asyncmq.svg?color=%2334D058" target="_blank">
    <img src="https://img.shields.io/pypi/pyversions/asyncmq.svg?color=%2334D058" alt="Supported Python versions">
  </a>
</p>

---

**Documentation**: [https://asyncmq.dymmond.com](https://asyncmq.dymmond.com)

**Source Code**: [https://github.com/dymmond/asyncmq](https://github.com/dymmond/asyncmq)

**Supported Version**: the latest released version is the supported version.

---

AsyncMQ is a background job runtime for Python services built on `asyncio` and
`anyio`. It gives applications a queue API, worker runtime,
retry and dead-letter behavior, repeatable scheduling, flow primitives,
multiple backends, a CLI, and a packaged Lilya/Jinja operations dashboard.

## Why AsyncMQ

- Task registration for Python services with `@task`, `.enqueue()`, `.delay()`, and `.send()`.
- Queue and worker APIs for retries, backoff, delayed jobs, cancellation, pause/resume, cleanup, and DLQ operations.
- Backend options for Redis, PostgreSQL, MongoDB, RabbitMQ, and local memory-backed development.
- A production operations console that is packaged with AsyncMQ and works without Node.js or a frontend build pipeline.
- Clear runtime ownership: workers own execution, backends own durable queue state, and the dashboard consumes that state.

AsyncMQ is not a hosted queue service and does not promise exactly-once
execution. Production task handlers should be idempotent and safe to retry.

## Install

```bash
pip install asyncmq
```

Optional backend extras:

```bash
pip install "asyncmq[postgres]"
pip install "asyncmq[mongo]"
pip install "asyncmq[aio-pika]"
pip install "asyncmq[all]"
```

## Quickstart

Start with the in-memory backend for local development:

```python
# myapp/settings.py
from asyncmq.backends.memory import InMemoryBackend
from asyncmq.conf.global_settings import Settings


class AppSettings(Settings):
    backend = InMemoryBackend()
    worker_concurrency = 1
```

```bash
export ASYNCMQ_SETTINGS_MODULE=myapp.settings.AppSettings
```

Define a task:

```python
# myapp/tasks.py
from asyncmq.tasks import task


@task(queue="emails", retries=2, ttl=300)
async def send_welcome(email: str) -> str:
    return f"sent welcome email to {email}"
```

Enqueue work:

```python
# producer.py
import anyio

from asyncmq.queues import Queue
from myapp.tasks import send_welcome


async def main() -> None:
    queue = Queue("emails")
    job_id = await send_welcome.enqueue("alice@example.com", backend=queue.backend)
    print("enqueued", job_id)


anyio.run(main)
```

Run a worker:

```bash
asyncmq worker start emails --concurrency 1
```

Inspect from the CLI:

```bash
asyncmq queue list
asyncmq queue info emails
asyncmq job list --queue emails --state waiting
asyncmq job list --queue emails --state failed
```

## Production Backend Example

Use a shared backend configuration for producers, workers, and the dashboard.

```python
# myapp/settings.py
from asyncmq.backends.redis import RedisBackend
from asyncmq.conf.global_settings import Settings
from asyncmq.core.utils.dashboard import DashboardConfig


class AppSettings(Settings):
    secret_key = "replace-with-a-secret-from-your-secret-manager"
    backend = RedisBackend("redis://redis:6379/0")
    worker_concurrency = 8
    scan_interval = 1.0

    @property
    def dashboard_config(self) -> DashboardConfig:
        return DashboardConfig(
            secret_key=self.secret_key,
            dashboard_url_prefix="/asyncmq",
            path="/asyncmq",
            https_only=True,
        )
```

Workers and the dashboard can run in different services as long as they use the
same `ASYNCMQ_SETTINGS_MODULE` and backend credentials.

## Operations Dashboard

AsyncMQ includes a native dashboard built with Lilya, Jinja templates rendered
by the server, and packaged static assets.

```python
# myapp/dashboard.py
from lilya.apps import Lilya

from asyncmq.contrib.dashboard.admin import AsyncMQAdmin

app = Lilya()
admin = AsyncMQAdmin(
    enable_login=True,
    backend=auth_backend,  # Provide an AuthBackend implementation.
    url_prefix="/asyncmq",
)
admin.include_in(app)
```

The dashboard supports queue inspection, worker health, job lists, failed job
tracebacks, DLQ actions, repeatables, metrics, runtime events, audit history,
and deployments behind reverse proxies at `/`, `/asyncmq/`, and nested prefixes such as
`/operations/asyncmq/`.

Read the [Dashboard guide](https://asyncmq.dymmond.com/dashboard/dashboard/) for
authentication, separate dashboard/worker services, proxy setup, and Nginx
examples.

## Runtime Shape

```mermaid
flowchart LR
    Producer["Producer service"] --> Task["@task enqueue"]
    Task --> Queue["Queue API"]
    Queue --> Backend["Backend state"]
    Backend --> Worker["Worker runtime"]
    Worker --> Handler["Task handler"]
    Worker --> Backend
    Backend --> Dashboard["Operations dashboard"]
    Backend --> CLI["asyncmq CLI"]
```

## Documentation Map

- [Installation](https://asyncmq.dymmond.com/installation/)
- [Quickstart](https://asyncmq.dymmond.com/features/quickstart/)
- [Core Concepts](https://asyncmq.dymmond.com/features/core-concepts/)
- [Queues](https://asyncmq.dymmond.com/features/queues/)
- [Workers](https://asyncmq.dymmond.com/features/workers/)
- [Jobs](https://asyncmq.dymmond.com/features/jobs/)
- [Schedulers](https://asyncmq.dymmond.com/features/schedulers/)
- [Flows](https://asyncmq.dymmond.com/features/flows/)
- [CLI Reference](https://asyncmq.dymmond.com/reference/cli-reference/)
- [Dashboard](https://asyncmq.dymmond.com/dashboard/dashboard/)
- [Production Operations](https://asyncmq.dymmond.com/learn/production-operations/)
- [Troubleshooting](https://asyncmq.dymmond.com/troubleshooting/)
