rrq 0.2.5__tar.gz

rrq-0.2.5/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+.git/

rrq-0.2.5/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 Mazdak Rezvani
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

rrq-0.2.5/MANIFEST.in

@@ -0,0 +1,2 @@
+README.md
+LICENSE

rrq-0.2.5/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: rrq
+Version: 0.2.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
+Author-email: Mazdak Rezvani <mazdak@me.com>
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.3
+Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: pydantic>=2.11.4
+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>=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
+
+*   **`RRQClient` (`client.py`)**: Used to enqueue jobs onto specific queues. Supports deferring jobs (by time delta or specific datetime), assigning custom job IDs, and enforcing job uniqueness via keys.
+*   **`RRQWorker` (`worker.py`)**: The process that polls queues, fetches jobs, executes the corresponding handler functions, and manages the job lifecycle based on success, failure, retries, or timeouts. Handles graceful shutdown via signals (SIGINT, SIGTERM).
+*   **`JobRegistry` (`registry.py`)**: A simple registry to map string function names (used when enqueuing) to the actual asynchronous handler functions the worker should execute.
+*   **`JobStore` (`store.py`)**: An abstraction layer handling all direct interactions with Redis. It manages job definitions (Hashes), queues (Sorted Sets), processing locks (Strings with TTL), unique job locks, and worker health checks.
+*   **`Job` (`job.py`)**: A Pydantic model representing a job, containing its ID, handler name, arguments, status, retry counts, timestamps, results, etc.
+*   **`JobStatus` (`job.py`)**: An Enum defining the possible states of a job (`PENDING`, `ACTIVE`, `COMPLETED`, `FAILED`, `RETRYING`).
+*   **`RRQSettings` (`settings.py`)**: A Pydantic `BaseSettings` model for configuring RRQ behavior (Redis DSN, queue names, timeouts, retry policies, concurrency, etc.). Loadable from environment variables (prefix `RRQ_`).
+*   **`constants.py`**: Defines shared constants like Redis key prefixes and default configuration values.
+*   **`exc.py`**: Defines custom exceptions, notably `RetryJob` which handlers can raise to explicitly request a retry, potentially with a custom delay.
+
+## Key Features
+
+*   **At-Least-Once Semantics**: Uses Redis locks to ensure a job is processed by only one worker at a time. If a worker crashes or shuts down mid-processing, the lock expires, and the job *should* be re-processed (though re-queueing on unclean shutdown isn't implemented here yet - graceful shutdown *does* re-queue).
+*   **Automatic Retries with Backoff**: Jobs that fail with standard exceptions are automatically retried based on `max_retries` settings, using exponential backoff for delays.
+*   **Explicit Retries**: Handlers can raise `RetryJob` to control retry attempts and delays.
+*   **Job Timeouts**: Jobs exceeding their configured timeout (`job_timeout_seconds` or `default_job_timeout_seconds`) are terminated and moved to the DLQ.
+*   **Dead Letter Queue (DLQ)**: Jobs that fail permanently (max retries reached, fatal error, timeout) are moved to a DLQ list in Redis for inspection.
+*   **Job Uniqueness**: The `_unique_key` parameter in `enqueue` prevents duplicate jobs based on a custom key within a specified TTL.
+*   **Graceful Shutdown**: Workers listen for SIGINT/SIGTERM and attempt to finish active jobs within a grace period before exiting. Interrupted jobs are re-queued.
+*   **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.*
+
+## Basic Usage
+
+*(See [`rrq_example.py`](examples/rrq_example.py) in the project root for a runnable example)*
+
+**1. Define Handlers:**
+
+```python
+# handlers.py
+import asyncio
+from rrq.exc import RetryJob
+
+async def my_task(ctx, message: str):
+    job_id = ctx['job_id']
+    attempt = ctx['job_try']
+    print(f"Processing job {job_id} (Attempt {attempt}): {message}")
+    await asyncio.sleep(1)
+    if attempt < 3 and message == "retry_me":
+        raise RetryJob("Needs another go!")
+    print(f"Finished job {job_id}")
+    return {"result": f"Processed: {message}"}
+```
+
+**2. Register Handlers:**
+
+```python
+# main_setup.py (or wherever you initialize)
+from rrq.registry import JobRegistry
+from . import handlers # Assuming handlers.py is in the same directory
+
+job_registry = JobRegistry()
+job_registry.register("process_message", handlers.my_task)
+```
+
+**3. Configure Settings:**
+
+```python
+# config.py
+from rrq.settings import RRQSettings
+
+# Loads from environment variables (RRQ_REDIS_DSN, etc.) or uses defaults
+rrq_settings = RRQSettings()
+# Or override directly:
+# rrq_settings = RRQSettings(redis_dsn="redis://localhost:6379/1")
+```
+
+**4. Enqueue Jobs:**
+
+```python
+# enqueue_script.py
+import asyncio
+from rrq.client import RRQClient
+from config import rrq_settings # Import your settings
+
+async def enqueue_jobs():
+    client = RRQClient(settings=rrq_settings)
+    await client.enqueue("process_message", "Hello RRQ!")
+    await client.enqueue("process_message", "retry_me")
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(enqueue_jobs())
+```
+
+**5. Run a Worker:**
+
+```python
+# worker_script.py
+from rrq.worker import RRQWorker
+from config import rrq_settings # Import your settings
+from main_setup import job_registry # Import your registry
+
+# Create worker instance
+worker = RRQWorker(settings=rrq_settings, job_registry=job_registry)
+
+# Run the worker (blocking)
+if __name__ == "__main__":
+    worker.run()
+```
+
+You can run multiple instances of `worker_script.py` for concurrent processing.
+
+## Configuration
+
+RRQ behavior is configured via the `RRQSettings` object, which loads values from environment variables prefixed with `RRQ_` by default. Key settings include:
+
+*   `RRQ_REDIS_DSN`: Connection string for Redis.
+*   `RRQ_DEFAULT_QUEUE_NAME`: Default queue name.
+*   `RRQ_DEFAULT_MAX_RETRIES`: Default retry limit.
+*   `RRQ_DEFAULT_JOB_TIMEOUT_SECONDS`: Default job timeout.
+*   `RRQ_WORKER_CONCURRENCY`: Max concurrent jobs per worker.
+*   ... and others (see `settings.py`).
+
+## RRQ CLI
+
+RRQ provides a command-line interface (CLI) for interacting with the job queue system. The `rrq` CLI allows you to manage workers, check system health, and get statistics about queues and jobs.
+
+### Usage
+
+```bash
+rrq <command> [options]
+```
+
+### Commands
+
+- **`worker run`**: Run an RRQ worker process to process jobs from queues.
+  ```bash
+  rrq worker run [--burst] [--detach] --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.
+  ```bash
+  rrq worker watch [--path <directory>] --settings <settings_path>
+  ```
+  - `--path`: Directory to watch for changes (default: current directory).
+  - `--settings`: Python settings path for application worker settings.
+
+- **`check`**: Perform a health check on active RRQ workers.
+  ```bash
+  rrq check --settings <settings_path>
+  ```
+  - `--settings`: Python settings path for application settings.
+
+
+### Configuration
+
+The CLI uses the same `RRQSettings` as the library, loading configuration from environment variables prefixed with `RRQ_`. You can also specify the settings via the `--settings` option for commands.
+
+```bash
+rrq worker run --settings myapp.worker_config.rrq_settings
+```
+
+### Help
+
+For detailed help on any command, use:
+```bash
+rrq <command> --help
+```

rrq-0.2.5/README.md

@@ -0,0 +1,175 @@
+# 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
+
+*   **`RRQClient` (`client.py`)**: Used to enqueue jobs onto specific queues. Supports deferring jobs (by time delta or specific datetime), assigning custom job IDs, and enforcing job uniqueness via keys.
+*   **`RRQWorker` (`worker.py`)**: The process that polls queues, fetches jobs, executes the corresponding handler functions, and manages the job lifecycle based on success, failure, retries, or timeouts. Handles graceful shutdown via signals (SIGINT, SIGTERM).
+*   **`JobRegistry` (`registry.py`)**: A simple registry to map string function names (used when enqueuing) to the actual asynchronous handler functions the worker should execute.
+*   **`JobStore` (`store.py`)**: An abstraction layer handling all direct interactions with Redis. It manages job definitions (Hashes), queues (Sorted Sets), processing locks (Strings with TTL), unique job locks, and worker health checks.
+*   **`Job` (`job.py`)**: A Pydantic model representing a job, containing its ID, handler name, arguments, status, retry counts, timestamps, results, etc.
+*   **`JobStatus` (`job.py`)**: An Enum defining the possible states of a job (`PENDING`, `ACTIVE`, `COMPLETED`, `FAILED`, `RETRYING`).
+*   **`RRQSettings` (`settings.py`)**: A Pydantic `BaseSettings` model for configuring RRQ behavior (Redis DSN, queue names, timeouts, retry policies, concurrency, etc.). Loadable from environment variables (prefix `RRQ_`).
+*   **`constants.py`**: Defines shared constants like Redis key prefixes and default configuration values.
+*   **`exc.py`**: Defines custom exceptions, notably `RetryJob` which handlers can raise to explicitly request a retry, potentially with a custom delay.
+
+## Key Features
+
+*   **At-Least-Once Semantics**: Uses Redis locks to ensure a job is processed by only one worker at a time. If a worker crashes or shuts down mid-processing, the lock expires, and the job *should* be re-processed (though re-queueing on unclean shutdown isn't implemented here yet - graceful shutdown *does* re-queue).
+*   **Automatic Retries with Backoff**: Jobs that fail with standard exceptions are automatically retried based on `max_retries` settings, using exponential backoff for delays.
+*   **Explicit Retries**: Handlers can raise `RetryJob` to control retry attempts and delays.
+*   **Job Timeouts**: Jobs exceeding their configured timeout (`job_timeout_seconds` or `default_job_timeout_seconds`) are terminated and moved to the DLQ.
+*   **Dead Letter Queue (DLQ)**: Jobs that fail permanently (max retries reached, fatal error, timeout) are moved to a DLQ list in Redis for inspection.
+*   **Job Uniqueness**: The `_unique_key` parameter in `enqueue` prevents duplicate jobs based on a custom key within a specified TTL.
+*   **Graceful Shutdown**: Workers listen for SIGINT/SIGTERM and attempt to finish active jobs within a grace period before exiting. Interrupted jobs are re-queued.
+*   **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.*
+
+## Basic Usage
+
+*(See [`rrq_example.py`](examples/rrq_example.py) in the project root for a runnable example)*
+
+**1. Define Handlers:**
+
+```python
+# handlers.py
+import asyncio
+from rrq.exc import RetryJob
+
+async def my_task(ctx, message: str):
+    job_id = ctx['job_id']
+    attempt = ctx['job_try']
+    print(f"Processing job {job_id} (Attempt {attempt}): {message}")
+    await asyncio.sleep(1)
+    if attempt < 3 and message == "retry_me":
+        raise RetryJob("Needs another go!")
+    print(f"Finished job {job_id}")
+    return {"result": f"Processed: {message}"}
+```
+
+**2. Register Handlers:**
+
+```python
+# main_setup.py (or wherever you initialize)
+from rrq.registry import JobRegistry
+from . import handlers # Assuming handlers.py is in the same directory
+
+job_registry = JobRegistry()
+job_registry.register("process_message", handlers.my_task)
+```
+
+**3. Configure Settings:**
+
+```python
+# config.py
+from rrq.settings import RRQSettings
+
+# Loads from environment variables (RRQ_REDIS_DSN, etc.) or uses defaults
+rrq_settings = RRQSettings()
+# Or override directly:
+# rrq_settings = RRQSettings(redis_dsn="redis://localhost:6379/1")
+```
+
+**4. Enqueue Jobs:**
+
+```python
+# enqueue_script.py
+import asyncio
+from rrq.client import RRQClient
+from config import rrq_settings # Import your settings
+
+async def enqueue_jobs():
+    client = RRQClient(settings=rrq_settings)
+    await client.enqueue("process_message", "Hello RRQ!")
+    await client.enqueue("process_message", "retry_me")
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(enqueue_jobs())
+```
+
+**5. Run a Worker:**
+
+```python
+# worker_script.py
+from rrq.worker import RRQWorker
+from config import rrq_settings # Import your settings
+from main_setup import job_registry # Import your registry
+
+# Create worker instance
+worker = RRQWorker(settings=rrq_settings, job_registry=job_registry)
+
+# Run the worker (blocking)
+if __name__ == "__main__":
+    worker.run()
+```
+
+You can run multiple instances of `worker_script.py` for concurrent processing.
+
+## Configuration
+
+RRQ behavior is configured via the `RRQSettings` object, which loads values from environment variables prefixed with `RRQ_` by default. Key settings include:
+
+*   `RRQ_REDIS_DSN`: Connection string for Redis.
+*   `RRQ_DEFAULT_QUEUE_NAME`: Default queue name.
+*   `RRQ_DEFAULT_MAX_RETRIES`: Default retry limit.
+*   `RRQ_DEFAULT_JOB_TIMEOUT_SECONDS`: Default job timeout.
+*   `RRQ_WORKER_CONCURRENCY`: Max concurrent jobs per worker.
+*   ... and others (see `settings.py`).
+
+## RRQ CLI
+
+RRQ provides a command-line interface (CLI) for interacting with the job queue system. The `rrq` CLI allows you to manage workers, check system health, and get statistics about queues and jobs.
+
+### Usage
+
+```bash
+rrq <command> [options]
+```
+
+### Commands
+
+- **`worker run`**: Run an RRQ worker process to process jobs from queues.
+  ```bash
+  rrq worker run [--burst] [--detach] --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.
+  ```bash
+  rrq worker watch [--path <directory>] --settings <settings_path>
+  ```
+  - `--path`: Directory to watch for changes (default: current directory).
+  - `--settings`: Python settings path for application worker settings.
+
+- **`check`**: Perform a health check on active RRQ workers.
+  ```bash
+  rrq check --settings <settings_path>
+  ```
+  - `--settings`: Python settings path for application settings.
+
+
+### Configuration
+
+The CLI uses the same `RRQSettings` as the library, loading configuration from environment variables prefixed with `RRQ_`. You can also specify the settings via the `--settings` option for commands.
+
+```bash
+rrq worker run --settings myapp.worker_config.rrq_settings
+```
+
+### Help
+
+For detailed help on any command, use:
+```bash
+rrq <command> --help
+```

rrq-0.2.5/example/example_rrq_settings.py

@@ -0,0 +1,38 @@
+'''example_rrq_settings.py: Example RRQ Application Settings'''
+
+import asyncio
+import logging
+
+from rrq.settings import RRQSettings
+
+logger = logging.getLogger("rrq")
+logger.setLevel(logging.DEBUG)
+console_handler = logging.StreamHandler()
+formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+console_handler.setFormatter(formatter)
+logger.addHandler(console_handler)
+
+redis_dsn = "redis://localhost:6379/0"
+
+
+
+
+async def on_startup_hook():
+    logger.info("Executing 'on_startup_hook' (application-specific startup)...")
+    await asyncio.sleep(0.1)
+    logger.info("'on_startup_hook' complete.")
+
+async def on_shutdown_hook():
+    logger.info("Executing 'on_shutdown_hook' (application-specific shutdown)...")
+    await asyncio.sleep(0.1)
+    logger.info("'on_shutdown_hook' complete.")
+
+
+
+# RRQ Settings
+rrq_settings = RRQSettings(
+    redis_dsn=redis_dsn,
+    on_startup=on_startup_hook,
+    on_shutdown=on_shutdown_hook,
+)
+

rrq-0.2.5/example/rrq_example.py

@@ -0,0 +1,212 @@
+"""rrq_example.py: A simple example demonstrating the RRQ system."""
+
+import asyncio
+import logging
+import random
+import signal
+from contextlib import suppress
+from datetime import timedelta
+
+from rrq.client import RRQClient
+from rrq.exc import RetryJob
+from rrq.registry import JobRegistry
+from rrq.settings import RRQSettings
+from rrq.store import JobStore
+from rrq.worker import RRQWorker
+
+# --- Basic Logging Setup ---
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+)
+# Set RRQ internal loggers to DEBUG for more detail in the example
+logging.getLogger("rrq").setLevel(logging.DEBUG)
+logger = logging.getLogger("RRQExample")
+
+
+# --- Example Job Handlers ---
+async def successful_task(ctx, message: str):
+    delay = random.uniform(0.1, 0.5)
+    logger.info(
+        f"SUCCESS_TASK (Job {ctx['job_id']}, Try {ctx['job_try']}): Received '{message}'. Sleeping for {delay:.2f}s..."
+    )
+    await asyncio.sleep(delay)
+    logger.info(f"SUCCESS_TASK (Job {ctx['job_id']}): Finished successfully.")
+    return {"status": "success", "processed_message": message, "slept_for": delay}
+
+
+async def failing_task(ctx, data: dict):
+    attempt = ctx["job_try"]
+    logger.warning(
+        f"FAILING_TASK (Job {ctx['job_id']}, Try {attempt}): Received data {data}. Simulating failure..."
+    )
+    await asyncio.sleep(0.1)
+    # Example: Fail permanently after max retries defined in Job/Settings
+    raise ValueError(f"Simulated failure on attempt {attempt}")
+
+
+async def retry_task(ctx, counter_limit: int):
+    attempt = ctx["job_try"]
+    logger.info(
+        f"RETRY_TASK (Job {ctx['job_id']}, Try {attempt}): Received limit {counter_limit}. Will retry if attempt < {counter_limit}."
+    )
+    await asyncio.sleep(0.2)
+    if attempt < counter_limit:
+        logger.warning(
+            f"RETRY_TASK (Job {ctx['job_id']}, Try {attempt}): Raising RetryJob (defer 1s)."
+        )
+        raise RetryJob(defer_seconds=1.0)  # Request specific retry delay
+    else:
+        logger.info(
+            f"RETRY_TASK (Job {ctx['job_id']}, Try {attempt}): Reached limit {counter_limit}. Finishing."
+        )
+        return {"status": "completed_after_retries", "attempts": attempt}
+
+
+# --- Main Execution ---
+async def main():
+    logger.info("--- Starting RRQ Example ---")
+
+    # 1. Settings - Use a different Redis DB for the example (e.g., DB 2)
+    settings = RRQSettings(
+        redis_dsn="redis://localhost:6379/2",
+        default_max_retries=3,  # Lower retries for example
+        worker_health_check_interval_seconds=5,  # Frequent health check
+        worker_shutdown_grace_period_seconds=5,
+    )
+    logger.info(f"Using Redis DB: {settings.redis_dsn}")
+
+    # Ensure Redis DB is clean before starting (optional, good for examples)
+    try:
+        temp_store = JobStore(settings=settings)
+        await temp_store.redis.flushdb()
+        logger.info(f"Flushed Redis DB {settings.redis_dsn.split('/')[-1]}")
+        await temp_store.aclose()
+    except Exception as e:
+        logger.error(f"Could not flush Redis DB: {e}. Please ensure Redis is running.")
+        return
+
+    # 2. Registry
+    registry = JobRegistry()
+    registry.register("handle_success", successful_task)
+    registry.register("handle_failure", failing_task)
+    registry.register("handle_retry", retry_task)
+    logger.info(f"Registered handlers: {registry.get_registered_functions()}")
+
+    # 3. Client
+    client = RRQClient(settings=settings)
+
+    # 4. Enqueue Jobs
+    logger.info("Enqueueing jobs...")
+    job1 = await client.enqueue("handle_success", "Hello World!")
+    job2 = await client.enqueue("handle_failure", {"id": 123, "value": "abc"})
+    job3 = await client.enqueue(
+        "handle_retry", 3
+    )  # Expect 3 attempts (1 initial + 2 retries)
+    job4 = await client.enqueue(
+        "handle_success", "Deferred Message!", _defer_by=timedelta(seconds=5)
+    )
+    job5 = await client.enqueue(
+        "handle_success",
+        "Another message",
+        _queue_name="high_priority",  # Example custom queue
+    )
+
+    if all([job1, job2, job3, job4, job5]):
+        logger.info("Jobs enqueued successfully.")
+        logger.info(f"  - Job 1 (Success): {job1.id}")
+        logger.info(f"  - Job 2 (Failure): {job2.id}")
+        logger.info(f"  - Job 3 (Retry): {job3.id}")
+        logger.info(f"  - Job 4 (Deferred): {job4.id}")
+        logger.info(f"  - Job 5 (CustomQ): {job5.id}")
+    else:
+        logger.error("Some jobs failed to enqueue.")
+        await client.close()
+        return
+
+    await client.close()  # Close client connection if no longer needed
+
+    # 5. Worker Setup
+    # Run worker polling both default and the custom queue
+    worker = RRQWorker(
+        settings=settings,
+        job_registry=registry,
+        queues=[settings.default_queue_name, "high_priority"],
+    )
+
+    # 6. Run Worker (with graceful shutdown handling)
+    logger.info(f"Starting worker {worker.worker_id}...")
+    worker_task = asyncio.create_task(run_worker_async(worker), name="RRQWorkerRunLoop")
+
+    # Keep the main script running until interrupted (Ctrl+C)
+    stop_event = asyncio.Event()
+    loop = asyncio.get_running_loop()
+
+    def signal_handler():
+        logger.info("Shutdown signal received. Setting stop event.")
+        if not stop_event.is_set():
+            stop_event.set()
+        # Allow worker to handle shutdown via its own signal handlers first
+        # If worker doesn't shutdown gracefully, worker_task might need cancellation
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, signal_handler)
+        except NotImplementedError:
+            logger.warning(
+                f"Signal handler for {sig.name} not supported on this platform."
+            )
+
+    logger.info("Example running. Press Ctrl+C to stop.")
+
+    # Wait for stop event or worker task completion (e.g., if it errors out)
+    done, pending = await asyncio.wait(
+        [worker_task, stop_event.wait()], return_when=asyncio.FIRST_COMPLETED
+    )
+
+    logger.info("Stop event triggered or worker task finished.")
+
+    # Initiate worker shutdown if it hasn't stopped itself
+    if not worker_task.done():
+        logger.info("Requesting worker shutdown...")
+        worker._request_shutdown()  # Ask worker to shutdown gracefully
+        try:
+            await asyncio.wait_for(
+                worker_task, timeout=settings.worker_shutdown_grace_period_seconds + 5
+            )
+            logger.info("Worker task completed after shutdown request.")
+        except TimeoutError:
+            logger.warning(
+                "Worker did not shut down gracefully within extended timeout. Cancelling task."
+            )
+            worker_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await worker_task
+        except Exception as e:
+            logger.error(f"Error waiting for worker shutdown: {e}", exc_info=True)
+            worker_task.cancel()  # Ensure cancellation on other errors
+            with suppress(asyncio.CancelledError):
+                await worker_task
+
+    logger.info("--- RRQ Example Finished ---")
+
+
+async def run_worker_async(worker: RRQWorker):
+    """Helper function to run the worker's main loop asynchronously."""
+    # We don't use worker.run() here because it's synchronous.
+    # Instead, we directly await the async _run_loop method.
+    try:
+        await worker._run_loop()
+    except Exception as e:
+        logger.error(
+            f"Worker {worker.worker_id} _run_loop exited with error: {e}", exc_info=True
+        )
+    finally:
+        # Ensure resources are closed even if _run_loop fails unexpectedly
+        await worker._close_resources()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.info("KeyboardInterrupt caught in __main__. Exiting.")