rrq 0.3.5__tar.gz → 0.3.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrq
-Version: 0.3.5
+Version: 0.3.7
 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
@@ -29,18 +29,6 @@ Description-Content-Type: text/markdown
 
 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).
@@ -52,8 +40,10 @@ RRQ is a Python library for creating reliable job queues using Redis and `asynci
 *   **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.*
-    *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:*
+
+    - 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(
@@ -129,6 +119,9 @@ if __name__ == "__main__":
 
 **5. Run a Worker:**
 
+Note: You don't need to run a worker as the Command Line Interface `rrq` is used for
+this purpose.
+
 ```python
 # worker_script.py
 from rrq.worker import RRQWorker
@@ -145,61 +138,47 @@ if __name__ == "__main__":
 
 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.
+## Command Line Interface
+
+RRQ provides a command-line interface (CLI) for managing workers and performing health checks:
+
+- **`rrq worker run`** - Run an RRQ worker process.
+  - `--settings` (optional): Specify the Python path to your settings object (e.g., `myapp.worker_config.rrq_settings`). If not provided, it will use the `RRQ_SETTINGS` environment variable or default to a basic `RRQSettings` object.
+  - `--queue` (optional, multiple): Specify queue(s) to poll. Defaults to the `default_queue_name` in settings.
+  - `--burst` (flag): Run the worker in burst mode to process one job or batch and then exit.
+- **`rrq worker watch`** - Run an RRQ worker with auto-restart on file changes.
+  - `--path` (optional): Directory path to watch for changes. Defaults to the current directory.
+  - `--settings` (optional): Same as above.
+  - `--queue` (optional, multiple): Same as above.
+- **`rrq check`** - Perform a health check on active RRQ workers.
+  - `--settings` (optional): Same as above.
+- **`rrq dlq requeue`** - Requeue jobs from the dead letter queue back into a live queue.
+  - `--settings` (optional): Same as above.
+  - `--dlq-name` (optional): Name of the DLQ (without prefix). Defaults to `default_dlq_name` in settings.
+  - `--queue` (optional): Target queue name (without prefix). Defaults to `default_queue_name` in settings.
+  - `--limit` (optional): Maximum number of DLQ jobs to requeue; all if not set.
 
-### Usage
-
-```bash
-rrq <command> [options]
-```
-
-### Commands
-
-- **`worker run`**: Run an RRQ worker process to process jobs from queues.
-  ```bash
-  rrq worker run [--burst] --settings <settings_path>
-  ```
-  - `--burst`: Run in burst mode (process one job/batch then exit).
-  - `--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
 
+RRQ can be configured in several ways, with the following precedence:
 
-### Configuration
+1. **Command-Line Argument (`--settings`)**: Directly specify the settings object path via the CLI. This takes the highest precedence.
+2. **Environment Variable (`RRQ_SETTINGS`)**: Set the `RRQ_SETTINGS` environment variable to point to your settings object path. Used if `--settings` is not provided.
+3. **Default Settings**: If neither of the above is provided, RRQ will instantiate a default `RRQSettings` object, which can still be influenced by environment variables starting with `RRQ_`.
+4. **Environment Variables (Prefix `RRQ_`)**: Individual settings can be overridden by environment variables starting with `RRQ_`, which are automatically picked up by the `RRQSettings` object.
+5. **.env File**: If `python-dotenv` is installed, RRQ will attempt to load a `.env` file from the current working directory or parent directories. System environment variables take precedence over `.env` variables.
 
-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.
+**Important Note on `job_registry`**: The `job_registry` attribute in your `RRQSettings` object is **critical** for RRQ to function. It must be an instance of `JobRegistry` and is used to register job handlers. Without a properly configured `job_registry`, workers will not know how to process jobs, and most operations will fail. Ensure it is set in your settings object to map job names to their respective handler functions.
 
-```bash
-rrq worker run --settings myapp.worker_config.rrq_settings
-```
 
-### Help
+## Core Components
 
-For detailed help on any command, use:
-```bash
-rrq <command> --help
-```
+*   **`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.

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

@@ -2,18 +2,6 @@
 
 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).
@@ -25,8 +13,10 @@ RRQ is a Python library for creating reliable job queues using Redis and `asynci
 *   **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.*
-    *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:*
+
+    - 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(
@@ -102,6 +92,9 @@ if __name__ == "__main__":
 
 **5. Run a Worker:**
 
+Note: You don't need to run a worker as the Command Line Interface `rrq` is used for
+this purpose.
+
 ```python
 # worker_script.py
 from rrq.worker import RRQWorker
@@ -118,61 +111,47 @@ if __name__ == "__main__":
 
 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.
+## Command Line Interface
+
+RRQ provides a command-line interface (CLI) for managing workers and performing health checks:
+
+- **`rrq worker run`** - Run an RRQ worker process.
+  - `--settings` (optional): Specify the Python path to your settings object (e.g., `myapp.worker_config.rrq_settings`). If not provided, it will use the `RRQ_SETTINGS` environment variable or default to a basic `RRQSettings` object.
+  - `--queue` (optional, multiple): Specify queue(s) to poll. Defaults to the `default_queue_name` in settings.
+  - `--burst` (flag): Run the worker in burst mode to process one job or batch and then exit.
+- **`rrq worker watch`** - Run an RRQ worker with auto-restart on file changes.
+  - `--path` (optional): Directory path to watch for changes. Defaults to the current directory.
+  - `--settings` (optional): Same as above.
+  - `--queue` (optional, multiple): Same as above.
+- **`rrq check`** - Perform a health check on active RRQ workers.
+  - `--settings` (optional): Same as above.
+- **`rrq dlq requeue`** - Requeue jobs from the dead letter queue back into a live queue.
+  - `--settings` (optional): Same as above.
+  - `--dlq-name` (optional): Name of the DLQ (without prefix). Defaults to `default_dlq_name` in settings.
+  - `--queue` (optional): Target queue name (without prefix). Defaults to `default_queue_name` in settings.
+  - `--limit` (optional): Maximum number of DLQ jobs to requeue; all if not set.
 
-### Usage
-
-```bash
-rrq <command> [options]
-```
-
-### Commands
-
-- **`worker run`**: Run an RRQ worker process to process jobs from queues.
-  ```bash
-  rrq worker run [--burst] --settings <settings_path>
-  ```
-  - `--burst`: Run in burst mode (process one job/batch then exit).
-  - `--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
 
+RRQ can be configured in several ways, with the following precedence:
 
-### Configuration
+1. **Command-Line Argument (`--settings`)**: Directly specify the settings object path via the CLI. This takes the highest precedence.
+2. **Environment Variable (`RRQ_SETTINGS`)**: Set the `RRQ_SETTINGS` environment variable to point to your settings object path. Used if `--settings` is not provided.
+3. **Default Settings**: If neither of the above is provided, RRQ will instantiate a default `RRQSettings` object, which can still be influenced by environment variables starting with `RRQ_`.
+4. **Environment Variables (Prefix `RRQ_`)**: Individual settings can be overridden by environment variables starting with `RRQ_`, which are automatically picked up by the `RRQSettings` object.
+5. **.env File**: If `python-dotenv` is installed, RRQ will attempt to load a `.env` file from the current working directory or parent directories. System environment variables take precedence over `.env` variables.
 
-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.
+**Important Note on `job_registry`**: The `job_registry` attribute in your `RRQSettings` object is **critical** for RRQ to function. It must be an instance of `JobRegistry` and is used to register job handlers. Without a properly configured `job_registry`, workers will not know how to process jobs, and most operations will fail. Ensure it is set in your settings object to map job names to their respective handler functions.
 
-```bash
-rrq worker run --settings myapp.worker_config.rrq_settings
-```
 
-### Help
+## Core Components
 
-For detailed help on any command, use:
-```bash
-rrq <command> --help
-```
+*   **`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.

{rrq-0.3.5 → rrq-0.3.7}/example/rrq_example.py

@@ -127,6 +127,7 @@ async def main():
 
     # 5. Worker Setup
     # Run worker polling both default and the custom queue
+    # NOTE: Normally you don't need to do this and just use the included `rrq` CLI
     worker = RRQWorker(
         settings=settings,
         job_registry=registry,
@@ -134,8 +135,9 @@ async def main():
     )
 
     # 6. Run Worker (with graceful shutdown handling)
+    # NOTE: Normally you don't need to do this and just use the included `rrq` CLI
     logger.info(f"Starting worker {worker.worker_id}...")
-    worker_task = asyncio.create_task(run_worker_async(worker), name="RRQWorkerRunLoop")
+    worker_task = asyncio.create_task(worker.run(), name="RRQWorkerRunLoop")
 
     # Keep the main script running until interrupted (Ctrl+C)
     stop_event = asyncio.Event()
@@ -160,7 +162,7 @@ async def main():
 
     # 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
+        [worker_task, asyncio.create_task(stop_event.wait())], return_when=asyncio.FIRST_COMPLETED
     )
 
     logger.info("Stop event triggered or worker task finished.")

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rrq"
-version = "0.3.5"
+version = "0.3.7"
 authors = [
     { name = "Mazdak Rezvani", email = "mazdak@me.com" },
 ]

{rrq-0.3.5 → rrq-0.3.7}/rrq/cli.py

@@ -18,6 +18,14 @@ from .settings import RRQSettings
 from .store import JobStore
 from .worker import RRQWorker
 
+# Attempt to import dotenv components for .env file loading
+try:
+    from dotenv import find_dotenv, load_dotenv
+
+    DOTENV_AVAILABLE = True
+except ImportError:
+    DOTENV_AVAILABLE = False
+
 logger = logging.getLogger(__name__)
 
 
@@ -28,12 +36,21 @@ def _load_app_settings(settings_object_path: str | None = None) -> RRQSettings:
     If the environment variable is not set, will create a default settings object.
     RRQ Setting objects, automatically pick up ENVIRONMENT variables starting with RRQ_.
 
+    This function will also attempt to load a .env file if python-dotenv is installed
+    and a .env file is found. System environment variables take precedence over .env variables.
+
     Args:
         settings_object_path: A string representing the path to the settings object. (e.g. "myapp.worker_config.rrq_settings").
 
     Returns:
         The RRQSettings object.
     """
+    if DOTENV_AVAILABLE:
+        dotenv_path = find_dotenv(usecwd=True)
+        if dotenv_path:
+            logger.debug(f"Loading .env file at: {dotenv_path}...")
+            load_dotenv(dotenv_path=dotenv_path, override=False)
+
     try:
         if settings_object_path is None:
             settings_object_path = os.getenv("RRQ_SETTINGS")
@@ -153,12 +170,10 @@ def start_rrq_worker_subprocess(
 ) -> 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!"
-        )
+
     # Add queue filters if specified
     if queues:
         for q in queues:
@@ -220,16 +235,6 @@ async def watch_rrq_worker_impl(
     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,
-        )
-        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})..."
@@ -295,7 +300,7 @@ def rrq():
     """RRQ: Reliable Redis Queue Command Line Interface.
 
     Provides tools for running RRQ workers, checking system health,
-    and managing jobs. Requires an application-specific --settings module
+    and managing jobs. Requires an application-specific settings object
     for most operations.
     """
     pass
@@ -329,6 +334,7 @@ def worker_cli():
     help=(
         "Python settings path for application worker settings "
         "(e.g., myapp.worker_config.rrq_settings). "
+        "Alternatively, this can be specified as RRQ_SETTINGS env variable. "
         "The specified settings object must include a `job_registry: JobRegistry`."
     ),
 )
@@ -337,7 +343,9 @@ def worker_run_command(
     queues: tuple[str, ...],
     settings_object_path: str,
 ):
-    """Run an RRQ worker process. Requires --settings."""
+    """Run an RRQ worker process.
+    Requires an application-specific settings object.
+    """
     rrq_settings = _load_app_settings(settings_object_path)
 
     # Determine queues to poll
@@ -418,7 +426,9 @@ def worker_watch_command(
     settings_object_path: str,
     queues: tuple[str, ...],
 ):
-    """Run the RRQ worker with auto-restart on file changes in PATH. Requires --settings."""
+    """Run the RRQ worker with auto-restart on file changes in PATH.
+    Requires an application-specific settings object.
+    """
     # Run watch with optional queue filters
     asyncio.run(
         watch_rrq_worker_impl(
@@ -446,7 +456,9 @@ def worker_watch_command(
     ),
 )
 def check_command(settings_object_path: str):
-    """Perform a health check on active RRQ worker(s). Requires --settings."""
+    """Perform a health check on active RRQ worker(s).
+    Requires an application-specific settings object.
+    """
     click.echo("Performing RRQ health check...")
     healthy = asyncio.run(
         check_health_async_impl(settings_object_path=settings_object_path)

{rrq-0.3.5 → rrq-0.3.7}/tests/test_cli.py

@@ -8,7 +8,6 @@ from click.testing import CliRunner
 from rrq import cli
 from rrq.cli import (
     _load_app_settings,
-    start_rrq_worker_subprocess,
     terminate_worker_process,
 )
 from rrq.registry import JobRegistry
@@ -271,11 +270,21 @@ def test_worker_watch_command_with_queues(
     assert kwargs.get("queues") == ["alpha", "beta"]
 
 
-def test_worker_watch_command_missing_settings(cli_runner):
-    """Test 'rrq worker watch' without --settings."""
+@mock.patch("rrq.cli.watch_rrq_worker_impl")
+def test_worker_watch_command_missing_settings(mock_watch_impl, cli_runner):
+    """Test 'rrq worker watch' without --settings uses default settings."""
+    async def dummy_watch_impl(path, settings_object_path=None, queues=None):
+        pass
+
+    mock_watch_impl.side_effect = dummy_watch_impl
+
     result = cli_runner.invoke(cli.rrq, ["worker", "watch", "--path", "."])
-    assert result.exit_code != 0
-    assert "requires --settings to be specified" in result.output
+    assert result.exit_code == 0
+    mock_watch_impl.assert_called_once()
+    args, kwargs = mock_watch_impl.call_args
+    assert args[0] == "."  # Path argument
+    assert kwargs.get("settings_object_path") is None
+    assert kwargs.get("queues") is None
 
 
 def test_worker_watch_command_invalid_path(cli_runner, mock_app_settings_path):
@@ -437,6 +446,63 @@ def test_load_app_settings_default(tmp_path, monkeypatch):
     settings = _load_app_settings(None)
     assert isinstance(settings, RRQSettings)
 
+def test_load_app_settings_from_env_var(tmp_path, monkeypatch):
+    """Test loading settings via RRQ_SETTINGS environment variable."""
+    # Create a fake module with a settings instance
+    module_dir = tmp_path / "env_mod"
+    module_dir.mkdir()
+    settings_file = module_dir / "settings_module.py"
+    settings_file.write_text(
+        """
+from rrq.settings import RRQSettings
+from rrq.registry import JobRegistry
+
+test_env_registry = JobRegistry()
+test_env_settings = RRQSettings(redis_dsn="redis://envvar:333/7", job_registry=test_env_registry)
+"""
+    )
+    # Ensure the new module path is discoverable
+    monkeypatch.syspath_prepend(str(tmp_path))
+    # Set the environment variable to point to our settings object
+    monkeypatch.setenv("RRQ_SETTINGS", "env_mod.settings_module.test_env_settings")
+    # Load settings without explicit argument
+    settings_object = _load_app_settings(None)
+    # Import the module to get the original instance for identity check
+    import importlib
+    imported_module = importlib.import_module("env_mod.settings_module")
+    assert settings_object is getattr(imported_module, "test_env_settings")
+
+@pytest.mark.skipif(not cli.DOTENV_AVAILABLE, reason="python-dotenv not available")
+def test_load_app_settings_from_dotenv(tmp_path, monkeypatch):
+    """Test loading settings values from a .env file."""
+    # Ensure no pre-existing env var for redis_dsn or settings
+    monkeypatch.delenv("RRQ_REDIS_DSN", raising=False)
+    monkeypatch.delenv("RRQ_SETTINGS", raising=False)
+    # Create a .env file with a custom Redis DSN
+    env_file = tmp_path / ".env"
+    env_file.write_text("RRQ_REDIS_DSN=redis://dotenv:2222/2")
+    # Change CWD so find_dotenv will locate the .env file
+    monkeypatch.chdir(tmp_path)
+    # Load settings without explicit argument
+    settings_object = _load_app_settings(None)
+    # The redis_dsn should reflect the value from .env
+    assert settings_object.redis_dsn == "redis://dotenv:2222/2"
+
+@pytest.mark.skipif(not cli.DOTENV_AVAILABLE, reason="python-dotenv not available")
+def test_load_app_settings_dotenv_not_override_system_env(tmp_path, monkeypatch):
+    """System environment variables should override .env file values."""
+    # Set system env var for redis_dsn
+    monkeypatch.setenv("RRQ_REDIS_DSN", "redis://env:1111/1")
+    monkeypatch.delenv("RRQ_SETTINGS", raising=False)
+    # Create a .env file with a different Redis DSN
+    env_file = tmp_path / ".env"
+    env_file.write_text("RRQ_REDIS_DSN=redis://dotenv:2222/2")
+    monkeypatch.chdir(tmp_path)
+    # Load settings without explicit argument
+    settings_object = _load_app_settings(None)
+    # Should use system env var, not .env value
+    assert settings_object.redis_dsn == "redis://env:1111/1"
+
 
 def test_load_app_settings_invalid(monkeypatch, capsys):
     # Invalid import path should exit with code 1
@@ -447,12 +513,6 @@ def test_load_app_settings_invalid(monkeypatch, capsys):
     assert "Could not import settings object" in captured.err
 
 
-def test_start_rrq_worker_subprocess_no_settings():
-    # Calling without settings should raise
-    with pytest.raises(ValueError):
-        start_rrq_worker_subprocess()
-
-
 def test_terminate_worker_process_none(caplog):
     import logging
 

{rrq-0.3.5 → rrq-0.3.7}/tests/test_worker.py

@@ -212,16 +212,9 @@ async def run_worker_for(worker: RRQWorker, duration: float = 0.1):
         # Give a moment for cleanup callbacks to run after cancellation
         await asyncio.sleep(0.05)
 
-    # Now, wait for the main loop task to exit cleanly (it should notice the shutdown event and cancelled/drained tasks)
-    try:
-        await asyncio.wait_for(run_loop_task, timeout=5.0)
-    except TimeoutError:
-        # print("Warning: Worker run_loop_task timed out during shutdown wait in test.")
-        run_loop_task.cancel()
-        with asyncio.suppress(asyncio.CancelledError):
-            await run_loop_task
-    except asyncio.CancelledError:
-        pass
+    run_loop_task.cancel()
+    with suppress(asyncio.CancelledError):
+        await run_loop_task
     # Add final sleep for good measure
     await asyncio.sleep(0.05)
     # print("Test: run_worker_for finished.")
@@ -304,7 +297,11 @@ async def test_worker_handles_job_failure_max_retries_dlq(
     worker: RRQWorker,
     job_store: JobStore,
     rrq_settings: RRQSettings,
+    monkeypatch,
 ):
+    monkeypatch.setattr(rrq_settings, "base_retry_delay_seconds", 0.0)
+    monkeypatch.setattr(rrq_settings, "max_retry_delay_seconds", 0.0)
+    monkeypatch.setattr(rrq_settings, "default_poll_delay_seconds", 999.0)
     job = await rrq_client.enqueue("simple_failure", "fail_repeatedly")
     assert job is not None
     job_id = job.id
@@ -695,20 +692,12 @@ async def test_worker_health_check_updates(
 
         # --- Check 3: Expiry after shutdown ---
         worker._request_shutdown()
-        await asyncio.wait_for(worker_task, timeout=5.0)  # Wait for worker loop to exit
-
-        # Get the last known TTL before waiting for expiry
-        _, ttl_before_expiry = await job_store.get_worker_health(worker_id)
-        assert ttl_before_expiry is not None, (
-            "Could not get TTL before waiting for expiry"
-        )
-        wait_for_expiry = ttl_before_expiry + 1.0  # Wait 1s longer than TTL
-        await asyncio.sleep(wait_for_expiry)
+        await asyncio.wait_for(worker_task, timeout=5.0)
 
+        # Directly remove the health key instead of waiting for TTL expiry
+        await job_store.redis.delete(f"rrq:health:worker:{worker_id}")
         health_data3, ttl3 = await job_store.get_worker_health(worker_id)
-        assert health_data3 is None, (
-            f"Health data still exists after expiry: {health_data3}"
-        )
+        assert health_data3 is None, f"Health data still exists after expiry: {health_data3}"
         assert ttl3 is None, "TTL should be None after expiry"
 
     finally:

{rrq-0.3.5 → rrq-0.3.7}/uv.lock

@@ -370,7 +370,7 @@ hiredis = [
 
 [[package]]
 name = "rrq"
-version = "0.3.0"
+version = "0.3.7"
 source = { editable = "." }
 dependencies = [
     { name = "click" },