asyncmq 0.1.0__tar.gz

asyncmq-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# folders
+*.egg-info/
+.hypothesis/
+.idea/
+.mypy_cache/
+.pytest_cache/
+.scannerwork/
+.tox/
+.venv/
+.vscode/
+__pycache__/
+virtualenv/
+build/
+dist/
+node_modules/
+results/
+site/
+site_lang/
+target/
+
+# files
+**/*.so
+**/*.sqlite
+*.iml
+**/*_test*
+.DS_Store
+.coverage
+.coverage.*
+.python-version
+coverage.*
+example.sqlite

asyncmq-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright © 2025, Dymmond Ltd. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
+conditions are met:
+
+  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+  disclaimer in the documentation and/or other materials provided with the distribution.
+
+  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE.

asyncmq-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: asyncmq
+Version: 0.1.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,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: 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.8
+Requires-Dist: anyio<6.0.0,>=4.9.0
+Requires-Dist: click<9.0.0,>=8.1.8
+Requires-Dist: croniter<7.0.0,>=6.0.0
+Requires-Dist: monkay>=0.4.1
+Requires-Dist: redis>=5.2.1
+Requires-Dist: rich<15.0.0,>=14.0.0
+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: 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: esmerald>=3.7.7; extra == 'testing'
+Requires-Dist: isort<6.0.0,>=5.12.0; extra == 'testing'
+Requires-Dist: pytest-asyncio>=0.26.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'
+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">
+  <span>⚡ Supercharge your async applications with tasks so fast, you’ll think you’re bending time itself. ⚡</span>
+</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>
+
+---
+
+Welcome to **AsyncMQ**, the modern task queue that brings **powerful**, **flexible**, and **lightning-fast** background processing to your Python stack. Whether you're building microservices, handling high-throughput data pipelines, or just want reliable delayed jobs, AsyncMQ has your back.
+
+## 🚀 Why Choose AsyncMQ?
+
+1. **Asyncio & AnyIO-Native**
+   No more wrestling with threads or callbacks—AsyncMQ is built on `asyncio` and `anyio`, so your tasks are non-blocking and integrate seamlessly into modern async frameworks like FastAPI and Esmerald.
+
+2. **Multi-Backend Flexibility**
+   From the blistering speed of Redis to the ACID guarantees of Postgres, or the schema-less power of MongoDB, AsyncMQ supports multiple backends out of the box—and you can write your own by implementing `BaseBackend`.
+
+3. **Advanced Scheduling**
+
+   * **Delayed Jobs**: Fire off tasks in the future with precise delays.
+   * **Repeatable & Cron**: Create heartbeat jobs or cron-like schedules with a single line.
+   * **Scan & Scheduler**: Smart polling intervals and cron logic keep your timings accurate without burning CPU cycles.
+
+4. **Robust Error Handling**
+
+   * **Retries & Backoff**: Exponential or custom backoff strategies to gracefully handle failures.
+   * **Dead Letter Queue (DLQ)**: Automatically route permanently failed tasks for later inspection and reprocessing.
+
+5. **Observability & Event Hooks**
+   Tap into lifecycle events (`job:started`, `job:completed`, `job:failed`, `job:progress`) to power real-time dashboards, metrics, or custom alerts.
+
+6. **Rate Limiting & Concurrency Control**
+   Fine-tune throughput with token-bucket rate limiting and capacity limiters. Scale your worker concurrency without overloading downstream systems.
+
+7. **Sandboxed Execution**
+   Run untrusted or CPU-bound tasks in isolated subprocesses with timeouts to protect your main workers from rogue code or infinite loops.
+
+8. **Flow/DAG Orchestration**
+   Create complex task graphs with dependencies using `FlowProducer`. Enqueue entire pipelines atomically or fall back to safe sequential logic.
+
+9. **CLI & Dev Experience**
+   A feature-rich CLI for managing queues, jobs, and workers—intuitive commands, JSON output support, and built-in help for every scenario.
+
+10. **Seamless ASGI Integration**
+    Out-of-the-box compatibility with FastAPI, Esmerald, or any ASGI application. Manage workers within your app’s lifecycle events.
+
+---
+
+## Comparison with Other Python Task Queues
+
+| Feature                    | **AsyncMQ**                      | Celery        | RQ         | Dramatiq     | Huey       |
+| -------------------------- | -------------------------------- | ------------- | ---------- | ------------ | ---------- |
+| **AsyncIO Native**         | ✅                                | ❌             | ❌          | ✅            | ❌          |
+| **Pluggable Backends**     | ✅ Redis, Postgres, Mongo, In-Mem | RabbitMQ only | Redis only | Redis only   | Redis only |
+| **Rate Limiting**          | ✅ built-in                       | ❌             | ❌          | ✅ via addon  | ❌          |
+| **Cron & Repeatable Jobs** | ✅ interval & cron expressions    | ✅             | ✅          | ✅            | ✅          |
+| **Progress Reporting**     | ✅ event hooks                    | ✅ callbacks   | ❌          | ✅ hooks      | ❌          |
+| **Dead Letter Queue**      | ✅                                | ✅             | ❌          | ✅            | ✅          |
+| **Flow / DAG Support**     | ✅ `FlowProducer`                 | ✅ chords      | ❌          | ✅ extensions | ❌          |
+| **ASGI-Friendly**          | ✅ FastAPI/Esmerald integration   | ❌             | ❌          | ❌            | ❌          |
+| **CLI Management**         | ✅ rich, JSON-friendly            | ✅             | ✅          | ✅            | ✅          |
+
+---
+
+### Where **AsyncMQ** Shines
+
+* **True AsyncIO & AnyIO integration**: zero thread hacks, full non-blocking background tasks.
+* **Backend flexibility**: swap Redis, Postgres, MongoDB, or In-Memory with a single setting.
+* **Built-in rate limiting & concurrency control**: protect downstream services out-of-the-box.
+* **Event-driven hooks**: subscribe to `job:started`, `completed`, `failed`, `progress`, etc., for metrics and alerts.
+* **ASGI integration**: manage workers within FastAPI or Esmerald lifecycles—no extra wrappers needed.
+
+---
+
+## ⚡ Core Features at a Glance
+
+| Category               | Highlights                                                                                |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| **Task Definition**    | `@task` decorator, `.enqueue()`, progress callbacks, TTL, retries, dependencies, repeats  |
+| **Queue API**          | `add()`, `add_bulk()`, `add_repeatable()`, `pause()`, `resume()`, `clean()`, stats        |
+| **Worker Engine**      | `process_job()`, capacity & rate limiters, sandbox, event emitter, DLQ handling           |
+| **Scheduling**         | `delayed_job_scanner`, `repeatable_scheduler`, cron vs interval support                   |
+| **Flow Orchestration** | `FlowProducer.add_flow()`, atomic backend support, fallback mode for dependency wiring    |
+| **Configuration**      | Central `Settings` dataclass, env var override, dynamic tuning of concurrency & intervals |
+| **Observability**      | LoggingConfig protocol, structured logs, event subscriptions, metrics integration         |
+| **CLI Management**     | `asyncmq queue`, `asyncmq job`, `asyncmq worker`, `asyncmq info` commands                 |
+
+---
+
+## 🎬 Quickstart
+
+1. **Install**
+
+   ```bash
+   pip install asyncmq
+   ```
+2. **Configure**
+
+   Override the default settings `from asyncmq.conf import Settings` and create your own, then make it global.
+
+   ```bash
+   export ASYNCMQ_SETTINGS_MODULE=myapp.settings.Settings
+   ```
+3. **Define a Task**
+
+   ```python
+   from asyncmq.tasks import task
+
+   @task(queue="emails", retries=2, ttl=120)
+   async def send_welcome(email: str):
+       # Imagine real email-sending logic here
+       print(f"📧 Sent welcome to {email}")
+   ```
+4. **Enqueue & Run**
+
+   ```python
+   import anyio
+   from asyncmq.queues import Queue
+
+   async def main():
+       q = Queue("emails")
+       await send_welcome.enqueue(q.backend, "alice@example.com", delay=10)
+   anyio.run(main)
+   ```
+5. **Start Workers**
+
+   ```bash
+   asyncmq worker start emails --concurrency 5
+   ```
+
+---
+
+AsyncMQ is more than just a task queue, it’s the swiss army knife of async background processing.
+Dive into the **Learn** section to master every feature, or jump into the **Features** docs for quick reference.
+
+Ready to bend time?
+
+**Get started today** and experience async tasking at warp speed! 🎉

asyncmq-0.1.0/README.md

@@ -0,0 +1,155 @@
+# 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">
+  <span>⚡ Supercharge your async applications with tasks so fast, you’ll think you’re bending time itself. ⚡</span>
+</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>
+
+---
+
+Welcome to **AsyncMQ**, the modern task queue that brings **powerful**, **flexible**, and **lightning-fast** background processing to your Python stack. Whether you're building microservices, handling high-throughput data pipelines, or just want reliable delayed jobs, AsyncMQ has your back.
+
+## 🚀 Why Choose AsyncMQ?
+
+1. **Asyncio & AnyIO-Native**
+   No more wrestling with threads or callbacks—AsyncMQ is built on `asyncio` and `anyio`, so your tasks are non-blocking and integrate seamlessly into modern async frameworks like FastAPI and Esmerald.
+
+2. **Multi-Backend Flexibility**
+   From the blistering speed of Redis to the ACID guarantees of Postgres, or the schema-less power of MongoDB, AsyncMQ supports multiple backends out of the box—and you can write your own by implementing `BaseBackend`.
+
+3. **Advanced Scheduling**
+
+   * **Delayed Jobs**: Fire off tasks in the future with precise delays.
+   * **Repeatable & Cron**: Create heartbeat jobs or cron-like schedules with a single line.
+   * **Scan & Scheduler**: Smart polling intervals and cron logic keep your timings accurate without burning CPU cycles.
+
+4. **Robust Error Handling**
+
+   * **Retries & Backoff**: Exponential or custom backoff strategies to gracefully handle failures.
+   * **Dead Letter Queue (DLQ)**: Automatically route permanently failed tasks for later inspection and reprocessing.
+
+5. **Observability & Event Hooks**
+   Tap into lifecycle events (`job:started`, `job:completed`, `job:failed`, `job:progress`) to power real-time dashboards, metrics, or custom alerts.
+
+6. **Rate Limiting & Concurrency Control**
+   Fine-tune throughput with token-bucket rate limiting and capacity limiters. Scale your worker concurrency without overloading downstream systems.
+
+7. **Sandboxed Execution**
+   Run untrusted or CPU-bound tasks in isolated subprocesses with timeouts to protect your main workers from rogue code or infinite loops.
+
+8. **Flow/DAG Orchestration**
+   Create complex task graphs with dependencies using `FlowProducer`. Enqueue entire pipelines atomically or fall back to safe sequential logic.
+
+9. **CLI & Dev Experience**
+   A feature-rich CLI for managing queues, jobs, and workers—intuitive commands, JSON output support, and built-in help for every scenario.
+
+10. **Seamless ASGI Integration**
+    Out-of-the-box compatibility with FastAPI, Esmerald, or any ASGI application. Manage workers within your app’s lifecycle events.
+
+---
+
+## Comparison with Other Python Task Queues
+
+| Feature                    | **AsyncMQ**                      | Celery        | RQ         | Dramatiq     | Huey       |
+| -------------------------- | -------------------------------- | ------------- | ---------- | ------------ | ---------- |
+| **AsyncIO Native**         | ✅                                | ❌             | ❌          | ✅            | ❌          |
+| **Pluggable Backends**     | ✅ Redis, Postgres, Mongo, In-Mem | RabbitMQ only | Redis only | Redis only   | Redis only |
+| **Rate Limiting**          | ✅ built-in                       | ❌             | ❌          | ✅ via addon  | ❌          |
+| **Cron & Repeatable Jobs** | ✅ interval & cron expressions    | ✅             | ✅          | ✅            | ✅          |
+| **Progress Reporting**     | ✅ event hooks                    | ✅ callbacks   | ❌          | ✅ hooks      | ❌          |
+| **Dead Letter Queue**      | ✅                                | ✅             | ❌          | ✅            | ✅          |
+| **Flow / DAG Support**     | ✅ `FlowProducer`                 | ✅ chords      | ❌          | ✅ extensions | ❌          |
+| **ASGI-Friendly**          | ✅ FastAPI/Esmerald integration   | ❌             | ❌          | ❌            | ❌          |
+| **CLI Management**         | ✅ rich, JSON-friendly            | ✅             | ✅          | ✅            | ✅          |
+
+---
+
+### Where **AsyncMQ** Shines
+
+* **True AsyncIO & AnyIO integration**: zero thread hacks, full non-blocking background tasks.
+* **Backend flexibility**: swap Redis, Postgres, MongoDB, or In-Memory with a single setting.
+* **Built-in rate limiting & concurrency control**: protect downstream services out-of-the-box.
+* **Event-driven hooks**: subscribe to `job:started`, `completed`, `failed`, `progress`, etc., for metrics and alerts.
+* **ASGI integration**: manage workers within FastAPI or Esmerald lifecycles—no extra wrappers needed.
+
+---
+
+## ⚡ Core Features at a Glance
+
+| Category               | Highlights                                                                                |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| **Task Definition**    | `@task` decorator, `.enqueue()`, progress callbacks, TTL, retries, dependencies, repeats  |
+| **Queue API**          | `add()`, `add_bulk()`, `add_repeatable()`, `pause()`, `resume()`, `clean()`, stats        |
+| **Worker Engine**      | `process_job()`, capacity & rate limiters, sandbox, event emitter, DLQ handling           |
+| **Scheduling**         | `delayed_job_scanner`, `repeatable_scheduler`, cron vs interval support                   |
+| **Flow Orchestration** | `FlowProducer.add_flow()`, atomic backend support, fallback mode for dependency wiring    |
+| **Configuration**      | Central `Settings` dataclass, env var override, dynamic tuning of concurrency & intervals |
+| **Observability**      | LoggingConfig protocol, structured logs, event subscriptions, metrics integration         |
+| **CLI Management**     | `asyncmq queue`, `asyncmq job`, `asyncmq worker`, `asyncmq info` commands                 |
+
+---
+
+## 🎬 Quickstart
+
+1. **Install**
+
+   ```bash
+   pip install asyncmq
+   ```
+2. **Configure**
+
+   Override the default settings `from asyncmq.conf import Settings` and create your own, then make it global.
+
+   ```bash
+   export ASYNCMQ_SETTINGS_MODULE=myapp.settings.Settings
+   ```
+3. **Define a Task**
+
+   ```python
+   from asyncmq.tasks import task
+
+   @task(queue="emails", retries=2, ttl=120)
+   async def send_welcome(email: str):
+       # Imagine real email-sending logic here
+       print(f"📧 Sent welcome to {email}")
+   ```
+4. **Enqueue & Run**
+
+   ```python
+   import anyio
+   from asyncmq.queues import Queue
+
+   async def main():
+       q = Queue("emails")
+       await send_welcome.enqueue(q.backend, "alice@example.com", delay=10)
+   anyio.run(main)
+   ```
+5. **Start Workers**
+
+   ```bash
+   asyncmq worker start emails --concurrency 5
+   ```
+
+---
+
+AsyncMQ is more than just a task queue, it’s the swiss army knife of async background processing.
+Dive into the **Learn** section to master every feature, or jump into the **Features** docs for quick reference.
+
+Ready to bend time?
+
+**Get started today** and experience async tasking at warp speed! 🎉

asyncmq-0.1.0/asyncmq/__init__.py

@@ -0,0 +1,46 @@
+from typing import TYPE_CHECKING
+
+from monkay import Monkay
+
+__version__ = "0.1.0"
+
+if TYPE_CHECKING:
+    from .backends.memory import InMemoryBackend
+    from .backends.redis import RedisBackend
+    from .conf import settings
+    from .conf.global_settings import Settings
+    from .jobs import Job
+    from .queues import Queue
+    from .stores.base import BaseJobStore
+    from .tasks import task
+    from .workers import Worker
+
+_monkay: Monkay = Monkay(
+    globals(),
+    lazy_imports={
+        "BaseJobStore": ".stores.base.BaseJobStore",
+        "InMemoryBackend": ".backends.memory.InMemoryBackend",
+        "Job": ".jobs.Job",
+        "Queue": ".queues.Queue",
+        "RedisBackend": ".backends.redis.RedisBackend",
+        "Worker": ".workers.Worker",
+        "settings": ".conf.settings",
+        "Settings": ".conf.global_settings.Settings",
+    },
+    skip_all_update=True,
+    package="asyncmq",
+)
+
+__all__ = [
+    "BaseJobStore",
+    "InMemoryBackend",
+    "Job",
+    "Queue",
+    "RedisBackend",
+    "Settings",
+    "settings",
+    "task",
+    "Worker",
+]
+
+_monkay.add_lazy_import("task", ".tasks.task")

asyncmq-0.1.0/asyncmq/__main__.py

@@ -0,0 +1,4 @@
+from .cli.__main__ import main
+
+if __name__ == "__main__":
+    main()