rrq 0.2.5__tar.gz → 0.3.5__tar.gz

{rrq-0.2.5 → rrq-0.3.5}/.gitignore

@@ -1,3 +1,4 @@
 .venv/
 __pycache__/
-.git/
+.git/
+.vscode/

rrq-0.3.5/FUTURE.md

@@ -0,0 +1,33 @@
+# RRQ Multi-Worker Safety
+
+The core coordination primitives in RRQ are already designed for safe fan-out over multiple worker processes:
+
+- Jobs live in a Redis ZSET, with workers atomically acquiring a per-job lock (`SET NX PX`) before removing (`ZREM`) the job ID and executing it
+- The lock ensures that even if two workers race on the same job, only one proceeds past the `SET NX`
+- Once removed from the ZSET, the job can't re-appear until a retry or DLQ–requeue
+- Heartbeats and health keys are namespaced by worker ID (PID+UUID), so many workers can register themselves independently
+
+## Areas to Watch in Large Worker Fleets
+
+### 1. Two-step Lock+Pop Isn't Fully Atomic
+- If a worker acquires the lock but crashes before `ZREM`, the job stays in the queue until the lock TTL expires, and then another worker can grab it
+- In practice it's rare (must crash in that tiny window), but you can eliminate it by bundling "pop from ZSET + set lock" in a single Lua script
+
+### 2. Lock TTL vs. Job Duration
+- We set the lock TTL = `job_timeout + default_lock_timeout_extension_seconds`. If your handlers sometimes exceed that window, the lock can expire mid-run (though the job isn't in the queue anymore)
+- Consider increasing the extension, or implementing a "lock refresher" for very long tasks
+
+### 3. Graceful Shutdown & Task Drain
+- Workers will stop polling in burst mode or on a shutdown signal, then "drain" in-flight tasks up to `worker_shutdown_grace_period_seconds`
+- Beyond that they cancel. Make sure your handlers handle `CancelledError` gracefully
+
+### 4. Logging & Observability
+- If you're tailing stdout/stderr from many workers, add the worker ID (and queue list) to your log formatter to keep things straight
+
+### 5. Health-Check TTLs
+- The heartbeat loop writes a Redis key with a buffer TTL
+- If your network is flaky or your workers get paused (e.g. in a debugger), you may see transient "missing" health keys
+
+## Summary
+
+With these caveats in mind, you can absolutely spin up dozens (or hundreds) of RRQ worker processes against the same Redis instance, each pulling from the same or different queue names. The locking, queueing, and retry/DLQ logic will keep them from stepping on each other.

{rrq-0.2.5 → rrq-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrq
-Version: 0.2.5
+Version: 0.3.5
 Summary: RRQ is a Python library for creating reliable job queues using Redis and asyncio
 Project-URL: Homepage, https://github.com/getresq/rrq
 Project-URL: Bug Tracker, https://github.com/getresq/rrq/issues
@@ -21,17 +21,12 @@ Requires-Dist: redis[hiredis]<6,>=4.2.0
 Requires-Dist: watchfiles>=0.19.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.3.5; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # RRQ: Reliable Redis Queue
 
- ____    ____     ___
-|  _ \  |  _ \   / _ \
-| |_) | | |_) | | | | |
-|  _ <  |  _ <  | |_| |
-|_| \_\ |_| \_\  \__\_\
-
 RRQ is a Python library for creating reliable job queues using Redis and `asyncio`, inspired by [ARQ (Async Redis Queue)](https://github.com/samuelcolvin/arq). It focuses on providing at-least-once job processing semantics with features like automatic retries, job timeouts, dead-letter queues, and graceful worker shutdown.
 
 ## Core Components
@@ -58,10 +53,20 @@ RRQ is a Python library for creating reliable job queues using Redis and `asynci
 *   **Worker Health Checks**: Workers periodically update a health key in Redis with a TTL, allowing monitoring systems to track active workers.
 *   **Deferred Execution**: Jobs can be scheduled to run at a future time using `_defer_by` or `_defer_until`.
     *Note: Using deferral with a specific `_job_id` will effectively reschedule the job associated with that ID to the new time, overwriting its previous definition and score. It does not create multiple distinct scheduled jobs with the same ID.*
+    *To batch multiple enqueue calls into a single deferred job (and prevent duplicates within the defer window), combine `_unique_key` with `_defer_by`. For example:*
+
+      ```python
+      await client.enqueue(
+          "process_updates",
+          item_id=123,
+          _unique_key="update:123",
+          _defer_by=10,
+      )
+      ```
 
 ## Basic Usage
 
-*(See [`rrq_example.py`](examples/rrq_example.py) in the project root for a runnable example)*
+*(See [`rrq_example.py`](https://github.com/GetResQ/rrq/tree/master/example) in the project root for a runnable example)*
 
 **1. Define Handlers:**
 
@@ -165,10 +170,9 @@ rrq <command> [options]
 
 - **`worker run`**: Run an RRQ worker process to process jobs from queues.
   ```bash
-  rrq worker run [--burst] [--detach] --settings <settings_path>
+  rrq worker run [--burst] --settings <settings_path>
   ```
   - `--burst`: Run in burst mode (process one job/batch then exit).
-  - `--detach`: Run the worker in the background.
   - `--settings`: Python settings path for application worker settings (e.g., `myapp.worker_config.rrq_settings`).
 
 - **`worker watch`**: Run an RRQ worker with auto-restart on file changes in a specified directory.

{rrq-0.2.5 → rrq-0.3.5}/README.md

@@ -1,11 +1,5 @@
 # RRQ: Reliable Redis Queue
 
- ____    ____     ___
-|  _ \  |  _ \   / _ \
-| |_) | | |_) | | | | |
-|  _ <  |  _ <  | |_| |
-|_| \_\ |_| \_\  \__\_\
-
 RRQ is a Python library for creating reliable job queues using Redis and `asyncio`, inspired by [ARQ (Async Redis Queue)](https://github.com/samuelcolvin/arq). It focuses on providing at-least-once job processing semantics with features like automatic retries, job timeouts, dead-letter queues, and graceful worker shutdown.
 
 ## Core Components
@@ -32,10 +26,20 @@ RRQ is a Python library for creating reliable job queues using Redis and `asynci
 *   **Worker Health Checks**: Workers periodically update a health key in Redis with a TTL, allowing monitoring systems to track active workers.
 *   **Deferred Execution**: Jobs can be scheduled to run at a future time using `_defer_by` or `_defer_until`.
     *Note: Using deferral with a specific `_job_id` will effectively reschedule the job associated with that ID to the new time, overwriting its previous definition and score. It does not create multiple distinct scheduled jobs with the same ID.*
+    *To batch multiple enqueue calls into a single deferred job (and prevent duplicates within the defer window), combine `_unique_key` with `_defer_by`. For example:*
+
+      ```python
+      await client.enqueue(
+          "process_updates",
+          item_id=123,
+          _unique_key="update:123",
+          _defer_by=10,
+      )
+      ```
 
 ## Basic Usage
 
-*(See [`rrq_example.py`](examples/rrq_example.py) in the project root for a runnable example)*
+*(See [`rrq_example.py`](https://github.com/GetResQ/rrq/tree/master/example) in the project root for a runnable example)*
 
 **1. Define Handlers:**
 
@@ -139,10 +143,9 @@ rrq <command> [options]
 
 - **`worker run`**: Run an RRQ worker process to process jobs from queues.
   ```bash
-  rrq worker run [--burst] [--detach] --settings <settings_path>
+  rrq worker run [--burst] --settings <settings_path>
   ```
   - `--burst`: Run in burst mode (process one job/batch then exit).
-  - `--detach`: Run the worker in the background.
   - `--settings`: Python settings path for application worker settings (e.g., `myapp.worker_config.rrq_settings`).
 
 - **`worker watch`**: Run an RRQ worker with auto-restart on file changes in a specified directory.

{rrq-0.2.5 → rrq-0.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rrq"
-version = "0.2.5"
+version = "0.3.5"
 authors = [
     { name = "Mazdak Rezvani", email = "mazdak@me.com" },
 ]
@@ -33,6 +33,7 @@ dependencies = [
 dev = [
     "pytest>=8.3.5",
     "pytest-asyncio>=0.26.0",
+    "pytest-cov>=6.0.0",
 ]
 
 [project.urls]
@@ -40,7 +41,7 @@ dev = [
 "Bug Tracker" = "https://github.com/getresq/rrq/issues"
 
 [project.scripts]
-rrq = "rrq.rrq:rrq" # Assumes rrq.py is at the root of your source directory
+rrq = "rrq.cli:rrq"
 
 [tool.pytest.ini_options]
-asyncio_default_fixture_loop_scope = "function"
+asyncio_default_fixture_loop_scope = "function"

rrq-0.2.5/rrq/rrq.py → rrq-0.3.5/rrq/cli.py

@@ -20,10 +20,11 @@ from .worker import RRQWorker
 
 logger = logging.getLogger(__name__)
 
+
 # Helper to load settings for commands
 def _load_app_settings(settings_object_path: str | None = None) -> RRQSettings:
     """Load the settings object from the given path.
-    If not provided, the RRQ_SETTINGS environment variable will be used. 
+    If not provided, the RRQ_SETTINGS environment variable will be used.
     If the environment variable is not set, will create a default settings object.
     RRQ Setting objects, automatically pick up ENVIRONMENT variables starting with RRQ_.
 
@@ -53,10 +54,22 @@ def _load_app_settings(settings_object_path: str | None = None) -> RRQSettings:
 
         return settings_object
     except ImportError:
-        click.echo(click.style(f"ERROR: Could not import settings object '{settings_object_path}'. Make sure it is in PYTHONPATH.", fg="red"), err=True)
+        click.echo(
+            click.style(
+                f"ERROR: Could not import settings object '{settings_object_path}'. Make sure it is in PYTHONPATH.",
+                fg="red",
+            ),
+            err=True,
+        )
         sys.exit(1)
     except Exception as e:
-        click.echo(click.style(f"ERROR: Unexpected error processing settings object '{settings_object_path}': {e}", fg="red"), err=True)
+        click.echo(
+            click.style(
+                f"ERROR: Unexpected error processing settings object '{settings_object_path}': {e}",
+                fg="red",
+            ),
+            err=True,
+        )
         sys.exit(1)
 
 
@@ -73,13 +86,25 @@ async def check_health_async_impl(settings_object_path: str | None = None) -> bo
         logger.debug(f"Successfully connected to Redis: {rrq_settings.redis_dsn}")
 
         health_key_pattern = f"{HEALTH_KEY_PREFIX}*"
-        worker_keys = [key_bytes.decode("utf-8") async for key_bytes in job_store.redis.scan_iter(match=health_key_pattern)]
+        worker_keys = [
+            key_bytes.decode("utf-8")
+            async for key_bytes in job_store.redis.scan_iter(match=health_key_pattern)
+        ]
 
         if not worker_keys:
-            click.echo(click.style("Worker Health Check: FAIL (No active workers found)", fg="red"))
+            click.echo(
+                click.style(
+                    "Worker Health Check: FAIL (No active workers found)", fg="red"
+                )
+            )
             return False
 
-        click.echo(click.style(f"Worker Health Check: Found {len(worker_keys)} active worker(s):", fg="green"))
+        click.echo(
+            click.style(
+                f"Worker Health Check: Found {len(worker_keys)} active worker(s):",
+                fg="green",
+            )
+        )
         for key in worker_keys:
             worker_id = key.split(HEALTH_KEY_PREFIX)[1]
             health_data, ttl = await job_store.get_worker_health(worker_id)
@@ -95,28 +120,49 @@ async def check_health_async_impl(settings_object_path: str | None = None) -> bo
                     f"    TTL: {ttl if ttl is not None else 'N/A'} seconds"
                 )
             else:
-                click.echo(f"  - Worker ID: {click.style(worker_id, bold=True)} - Health data missing/invalid. TTL: {ttl if ttl is not None else 'N/A'}s")
+                click.echo(
+                    f"  - Worker ID: {click.style(worker_id, bold=True)} - Health data missing/invalid. TTL: {ttl if ttl is not None else 'N/A'}s"
+                )
         return True
     except redis.exceptions.ConnectionError as e:
         logger.error(f"Redis connection failed during health check: {e}", exc_info=True)
-        click.echo(click.style(f"Worker Health Check: FAIL - Redis connection error: {e}", fg="red"))
+        click.echo(
+            click.style(
+                f"Worker Health Check: FAIL - Redis connection error: {e}", fg="red"
+            )
+        )
         return False
     except Exception as e:
-        logger.error(f"An unexpected error occurred during health check: {e}", exc_info=True)
-        click.echo(click.style(f"Worker Health Check: FAIL - Unexpected error: {e}", fg="red"))
+        logger.error(
+            f"An unexpected error occurred during health check: {e}", exc_info=True
+        )
+        click.echo(
+            click.style(f"Worker Health Check: FAIL - Unexpected error: {e}", fg="red")
+        )
         return False
     finally:
         if job_store:
             await job_store.aclose()
 
+
 # --- Process Management ---
-def start_rrq_worker_subprocess(is_detached: bool = False, settings_object_path: str | None = None) -> subprocess.Popen | None:
-    """Start an RRQ worker process."""
+def start_rrq_worker_subprocess(
+    is_detached: bool = False,
+    settings_object_path: str | None = None,
+    queues: list[str] | None = None,
+) -> subprocess.Popen | None:
+    """Start an RRQ worker process, optionally for specific queues."""
     command = ["rrq", "worker", "run"]
     if settings_object_path:
         command.extend(["--settings", settings_object_path])
     else:
-        raise ValueError("start_rrq_worker_subprocess called without settings_object_path!")
+        raise ValueError(
+            "start_rrq_worker_subprocess called without settings_object_path!"
+        )
+    # Add queue filters if specified
+    if queues:
+        for q in queues:
+            command.extend(["--queue", q])
 
     logger.info(f"Starting worker subprocess with command: {' '.join(command)}")
     if is_detached:
@@ -139,35 +185,55 @@ def start_rrq_worker_subprocess(is_detached: bool = False, settings_object_path:
     return process
 
 
-def terminate_worker_process(process: subprocess.Popen | None, logger: logging.Logger) -> None:
+def terminate_worker_process(
+    process: subprocess.Popen | None, logger: logging.Logger
+) -> None:
     if not process or process.pid is None:
         logger.debug("No active worker process to terminate.")
         return
 
     try:
         if process.poll() is not None:
-            logger.debug(f"Worker process {process.pid} already terminated (poll returned exit code: {process.returncode}).")
+            logger.debug(
+                f"Worker process {process.pid} already terminated (poll returned exit code: {process.returncode})."
+            )
             return
 
         pgid = os.getpgid(process.pid)
-        logger.info(f"Terminating worker process group for PID {process.pid} (PGID {pgid})...")
+        logger.info(
+            f"Terminating worker process group for PID {process.pid} (PGID {pgid})..."
+        )
         os.killpg(pgid, signal.SIGTERM)
         process.wait(timeout=5)
     except subprocess.TimeoutExpired:
-        logger.warning(f"Worker process {process.pid} did not terminate gracefully (SIGTERM timeout), sending SIGKILL.")
+        logger.warning(
+            f"Worker process {process.pid} did not terminate gracefully (SIGTERM timeout), sending SIGKILL."
+        )
         with suppress(ProcessLookupError):
             os.killpg(os.getpgid(process.pid), signal.SIGKILL)
     except Exception as e:
         logger.error(f"Unexpected error checking worker process {process.pid}: {e}")
 
 
-async def watch_rrq_worker_impl(watch_path: str, settings_object_path: str | None = None) -> None:
+async def watch_rrq_worker_impl(
+    watch_path: str,
+    settings_object_path: str | None = None,
+    queues: list[str] | None = None,
+) -> None:
     if not settings_object_path:
-        click.echo(click.style("ERROR: 'rrq worker watch' requires --settings to be specified.", fg="red"), err=True)
+        click.echo(
+            click.style(
+                "ERROR: 'rrq worker watch' requires --settings to be specified.",
+                fg="red",
+            ),
+            err=True,
+        )
         sys.exit(1)
 
     abs_watch_path = os.path.abspath(watch_path)
-    click.echo(f"Watching for file changes in {abs_watch_path} to restart RRQ worker (app settings: {settings_object_path})...")
+    click.echo(
+        f"Watching for file changes in {abs_watch_path} to restart RRQ worker (app settings: {settings_object_path})..."
+    )
     worker_process: subprocess.Popen | None = None
     loop = asyncio.get_event_loop()
     shutdown_event = asyncio.Event()
@@ -184,20 +250,28 @@ async def watch_rrq_worker_impl(watch_path: str, settings_object_path: str | Non
     signal.signal(signal.SIGTERM, sig_handler)
 
     try:
-        worker_process = start_rrq_worker_subprocess(is_detached=False, settings_object_path=settings_object_path)
+        worker_process = start_rrq_worker_subprocess(
+            is_detached=False,
+            settings_object_path=settings_object_path,
+            queues=queues,
+        )
         async for changes in awatch(abs_watch_path, stop_event=shutdown_event):
-            if shutdown_event.is_set(): 
+            if shutdown_event.is_set():
                 break
-            if not changes: 
+            if not changes:
                 continue
 
             logger.info(f"File changes detected: {changes}. Restarting RRQ worker...")
             if worker_process is not None:
                 terminate_worker_process(worker_process, logger)
             await asyncio.sleep(1)
-            if shutdown_event.is_set(): 
+            if shutdown_event.is_set():
                 break
-            worker_process = start_rrq_worker_subprocess(is_detached=False, settings_object_path=settings_object_path)
+            worker_process = start_rrq_worker_subprocess(
+                is_detached=False,
+                settings_object_path=settings_object_path,
+                queues=queues,
+            )
     except Exception as e:
         logger.error(f"Error in watch_rrq_worker: {e}", exc_info=True)
     finally:
@@ -213,7 +287,8 @@ async def watch_rrq_worker_impl(watch_path: str, settings_object_path: str | Non
 
 # --- Click CLI Definitions ---
 
-CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
+
 
 @click.group(context_settings=CONTEXT_SETTINGS)
 def rrq():
@@ -226,7 +301,6 @@ def rrq():
     pass
 
 
-
 @rrq.group("worker")
 def worker_cli():
     """Manage RRQ workers (run, watch)."""
@@ -234,41 +308,66 @@ def worker_cli():
 
 
 @worker_cli.command("run")
-@click.option("--burst", is_flag=True, help="Run worker in burst mode (process one job/batch then exit). Not Implemented yet.")
-@click.option("--detach", is_flag=True, help="Run the worker in the background (detached).")
 @click.option(
-    "--settings", 
-    "settings_object_path", 
-    type=str, 
-    required=False, 
-    default=None, 
-    help="Python settings path for application worker settings (e.g., myapp.worker_config.rrq_settings)."
+    "--burst",
+    is_flag=True,
+    help="Run worker in burst mode (process one job/batch then exit).",
 )
-def worker_run_command(burst: bool, detach: bool, settings_object_path: str):
+@click.option(
+    "--queue",
+    "queues",
+    type=str,
+    multiple=True,
+    help="Queue(s) to poll. Defaults to settings.default_queue_name.",
+)
+@click.option(
+    "--settings",
+    "settings_object_path",
+    type=str,
+    required=False,
+    default=None,
+    help=(
+        "Python settings path for application worker settings "
+        "(e.g., myapp.worker_config.rrq_settings). "
+        "The specified settings object must include a `job_registry: JobRegistry`."
+    ),
+)
+def worker_run_command(
+    burst: bool,
+    queues: tuple[str, ...],
+    settings_object_path: str,
+):
     """Run an RRQ worker process. Requires --settings."""
     rrq_settings = _load_app_settings(settings_object_path)
 
-    if detach:
-        logger.info("Attempting to start worker in detached (background) mode...")
-        process = start_rrq_worker_subprocess(is_detached=True, settings_object_path=settings_object_path)
-        click.echo(f"Worker initiated in background (PID: {process.pid}). Check logs for status.")
-        return
-
-    if burst:
-        raise NotImplementedError("Burst mode is not implemented yet.")
+    # Determine queues to poll
+    queues_arg = list(queues) if queues else None
+    # Run worker in foreground (burst or continuous mode)
 
-    logger.info(f"Starting RRQ Worker (Burst: {burst}, App Settings: {settings_object_path})")
+    logger.info(
+        f"Starting RRQ Worker (Burst: {burst}, App Settings: {settings_object_path})"
+    )
 
     if not rrq_settings.job_registry:
-        click.echo(click.style("ERROR: No 'job_registry_app'. You must provide a JobRegistry instance in settings.", fg="red"), err=True)
+        click.echo(
+            click.style(
+                "ERROR: No 'job_registry_app'. You must provide a JobRegistry instance in settings.",
+                fg="red",
+            ),
+            err=True,
+        )
         sys.exit(1)
 
-    logger.debug(f"Registered handlers (from effective registry): {rrq_settings.job_registry.get_registered_functions()}")
+    logger.debug(
+        f"Registered handlers (from effective registry): {rrq_settings.job_registry.get_registered_functions()}"
+    )
     logger.debug(f"Effective RRQ settings for worker: {rrq_settings}")
 
     worker_instance = RRQWorker(
         settings=rrq_settings,
         job_registry=rrq_settings.job_registry,
+        queues=queues_arg,
+        burst=burst,
     )
 
     loop = asyncio.get_event_loop()
@@ -296,33 +395,126 @@ def worker_run_command(burst: bool, detach: bool, settings_object_path: str):
     show_default=True,
 )
 @click.option(
-    "--settings", 
-    "settings_object_path", 
-    type=str, 
-    required=False, 
-    default=None, 
-    help="Python settings path for application worker settings (e.g., myapp.worker_config.rrq_settings)."
+    "--settings",
+    "settings_object_path",
+    type=str,
+    required=False,
+    default=None,
+    help=(
+        "Python settings path for application worker settings "
+        "(e.g., myapp.worker_config.rrq_settings). "
+        "The specified settings object must define a `job_registry: JobRegistry`."
+    ),
+)
+@click.option(
+    "--queue",
+    "queues",
+    type=str,
+    multiple=True,
+    help="Queue(s) to poll when restarting worker. Defaults to settings.default_queue_name.",
 )
-def worker_watch_command(path: str, settings_object_path: str):
+def worker_watch_command(
+    path: str,
+    settings_object_path: str,
+    queues: tuple[str, ...],
+):
     """Run the RRQ worker with auto-restart on file changes in PATH. Requires --settings."""
-    asyncio.run(watch_rrq_worker_impl(path, settings_object_path=settings_object_path))
+    # Run watch with optional queue filters
+    asyncio.run(
+        watch_rrq_worker_impl(
+            path,
+            settings_object_path=settings_object_path,
+            queues=list(queues) if queues else None,
+        )
+    )
+
+
+# --- DLQ Requeue CLI Command (delegates to JobStore) ---
 
 
 @rrq.command("check")
 @click.option(
-    "--settings", 
-    "settings_object_path", 
-    type=str, 
-    required=False, 
-    default=None, 
-    help="Python settings path for application worker settings (e.g., myapp.worker_config.rrq_settings)."
+    "--settings",
+    "settings_object_path",
+    type=str,
+    required=False,
+    default=None,
+    help=(
+        "Python settings path for application worker settings "
+        "(e.g., myapp.worker_config.rrq_settings). "
+        "Must include `job_registry: JobRegistry` to identify workers."
+    ),
 )
 def check_command(settings_object_path: str):
     """Perform a health check on active RRQ worker(s). Requires --settings."""
     click.echo("Performing RRQ health check...")
-    healthy = asyncio.run(check_health_async_impl(settings_object_path=settings_object_path))
+    healthy = asyncio.run(
+        check_health_async_impl(settings_object_path=settings_object_path)
+    )
     if healthy:
         click.echo(click.style("Health check PASSED.", fg="green"))
     else:
         click.echo(click.style("Health check FAILED.", fg="red"))
         sys.exit(1)
+
+
+@rrq.group("dlq")
+def dlq_cli():
+    """Manage the Dead Letter Queue (DLQ)."""
+    pass
+
+
+@dlq_cli.command("requeue")
+@click.option(
+    "--settings",
+    "settings_object_path",
+    type=str,
+    required=False,
+    default=None,
+    help=(
+        "Python settings path for application worker settings "
+        "(e.g., myapp.worker_config.rrq_settings). "
+        "Must include `job_registry: JobRegistry` if requeueing requires handler resolution."
+    ),
+)
+@click.option(
+    "--dlq-name",
+    "dlq_name",
+    type=str,
+    required=False,
+    default=None,
+    help="Name of the DLQ (without prefix). Defaults to settings.default_dlq_name.",
+)
+@click.option(
+    "--queue",
+    "target_queue",
+    type=str,
+    required=False,
+    default=None,
+    help="Name of the target queue (without prefix). Defaults to settings.default_queue_name.",
+)
+@click.option(
+    "--limit",
+    type=int,
+    required=False,
+    default=None,
+    help="Maximum number of DLQ jobs to requeue; all if not set.",
+)
+def dlq_requeue_command(
+    settings_object_path: str,
+    dlq_name: str,
+    target_queue: str,
+    limit: int,
+):
+    """Requeue jobs from the dead letter queue back into a live queue."""
+    rrq_settings = _load_app_settings(settings_object_path)
+    dlq_to_use = dlq_name or rrq_settings.default_dlq_name
+    queue_to_use = target_queue or rrq_settings.default_queue_name
+    job_store = JobStore(settings=rrq_settings)
+    click.echo(
+        f"Requeuing jobs from DLQ '{dlq_to_use}' to queue '{queue_to_use}' (limit: {limit or 'all'})..."
+    )
+    count = asyncio.run(job_store.requeue_dlq(dlq_to_use, queue_to_use, limit))
+    click.echo(
+        f"Requeued {count} job(s) from DLQ '{dlq_to_use}' to queue '{queue_to_use}'."
+    )