rrq 0.4.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

rrq/cli.py

@@ -7,6 +7,9 @@ import os
 import signal
 import subprocess
 import sys
+import time
+
+# import multiprocessing # No longer needed directly, os.cpu_count() is sufficient
 from contextlib import suppress
 
 import click
@@ -30,6 +33,29 @@ logger = logging.getLogger(__name__)
 
 
 # Helper to load settings for commands
+def _resolve_settings_source(
+    settings_object_path: str | None = None,
+) -> tuple[str | None, str]:
+    """Resolve the settings path and its source.
+
+    Returns:
+        A tuple of (settings_path, source_description)
+    """
+    if settings_object_path is not None:
+        return settings_object_path, "--settings parameter"
+
+    env_setting = os.getenv("RRQ_SETTINGS")
+    if env_setting is not None:
+        # Check if a .env file exists to give more specific info
+        if DOTENV_AVAILABLE and find_dotenv(usecwd=True):
+            # We can't definitively know if it came from .env or system env,
+            # but we can indicate both are possible
+            return env_setting, "RRQ_SETTINGS env var (system or .env)"
+        return env_setting, "RRQ_SETTINGS env var"
+
+    return None, "built-in defaults"
+
+
 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.
@@ -142,7 +168,12 @@ async def check_health_async_impl(settings_object_path: str | None = None) -> bo
                 )
         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"ERROR: Redis connection failed during health check: {e}", fg="red"
+            ),
+            err=True,
+        )
         click.echo(
             click.style(
                 f"Worker Health Check: FAIL - Redis connection error: {e}", fg="red"
@@ -150,8 +181,12 @@ async def check_health_async_impl(settings_object_path: str | None = None) -> bo
         )
         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"ERROR: An unexpected error occurred during health check: {e}",
+                fg="red",
+            ),
+            err=True,
         )
         click.echo(
             click.style(f"Worker Health Check: FAIL - Unexpected error: {e}", fg="red")
@@ -169,7 +204,7 @@ def start_rrq_worker_subprocess(
     queues: list[str] | None = None,
 ) -> subprocess.Popen | None:
     """Start an RRQ worker process, optionally for specific queues."""
-    command = ["rrq", "worker", "run"]
+    command = ["rrq", "worker", "run", "--num-workers", "1"]
 
     if settings_object_path:
         command.extend(["--settings", settings_object_path])
@@ -219,15 +254,25 @@ def terminate_worker_process(
             f"Terminating worker process group for PID {process.pid} (PGID {pgid})..."
         )
         os.killpg(pgid, signal.SIGTERM)
-        process.wait(timeout=5)
+        process.wait(timeout=10)
     except subprocess.TimeoutExpired:
-        logger.warning(
-            f"Worker process {process.pid} did not terminate gracefully (SIGTERM timeout), sending SIGKILL."
+        click.echo(
+            click.style(
+                f"WARNING: Worker process {process.pid} did not terminate gracefully (SIGTERM timeout), sending SIGKILL.",
+                fg="yellow",
+            ),
+            err=True,
         )
         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}")
+        click.echo(
+            click.style(
+                f"ERROR: Unexpected error checking worker process {process.pid}: {e}",
+                fg="red",
+            ),
+            err=True,
+        )
 
 
 async def watch_rrq_worker_impl(
@@ -236,9 +281,19 @@ async def watch_rrq_worker_impl(
     queues: list[str] | None = None,
 ) -> None:
     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}...")
+
+    # Load settings and display source
+    click.echo("Loading RRQ Settings... ", nl=False)
+
+    if settings_object_path:
+        click.echo(f"from --settings parameter ({settings_object_path}).")
+    elif os.getenv("RRQ_SETTINGS"):
+        click.echo(f"from RRQ_SETTINGS env var ({os.getenv('RRQ_SETTINGS')}).")
+    elif DOTENV_AVAILABLE and find_dotenv(usecwd=True):
+        click.echo("found in .env file.")
+    else:
+        click.echo("using defaults.")
     worker_process: subprocess.Popen | None = None
     loop = asyncio.get_event_loop()
     shutdown_event = asyncio.Event()
@@ -278,7 +333,9 @@ async def watch_rrq_worker_impl(
                 queues=queues,
             )
     except Exception as e:
-        logger.error(f"Error in watch_rrq_worker: {e}", exc_info=True)
+        click.echo(
+            click.style(f"ERROR: Error in watch_rrq_worker: {e}", fg="red"), err=True
+        )
     finally:
         logger.info("Exiting watch mode. Ensuring worker process is terminated.")
         if not shutdown_event.is_set():
@@ -306,6 +363,38 @@ def rrq():
     pass
 
 
+# Register modular commands
+try:
+    # Import new command classes
+    from .cli_commands.commands.queues import QueueCommands
+    from .cli_commands.commands.jobs import JobCommands
+    from .cli_commands.commands.monitor import MonitorCommands
+    from .cli_commands.commands.debug import DebugCommands
+    from .cli_commands.commands.dlq import DLQCommands
+
+    # Register new commands with existing CLI
+    command_classes = [
+        QueueCommands(),
+        JobCommands(),
+        MonitorCommands(),
+        DebugCommands(),
+        DLQCommands(),
+    ]
+
+    for command_instance in command_classes:
+        try:
+            command_instance.register(rrq)
+        except Exception as e:
+            click.echo(
+                f"Warning: Failed to register command {command_instance.__class__.__name__}: {e}",
+                err=True,
+            )
+
+except ImportError as e:
+    # Fall back to original CLI if new modules aren't available
+    click.echo(f"Warning: Enhanced CLI features not available: {e}", err=True)
+
+
 @rrq.group("worker")
 def worker_cli():
     """Manage RRQ workers (run, watch)."""
@@ -338,28 +427,85 @@ def worker_cli():
         "The specified settings object must include a `job_registry: JobRegistry`."
     ),
 )
+@click.option(
+    "--num-workers",
+    type=int,
+    default=None,
+    help="Number of parallel worker processes to start. Defaults to the number of CPU cores.",
+)
 def worker_run_command(
     burst: bool,
     queues: tuple[str, ...],
     settings_object_path: str,
+    num_workers: int | None,
 ):
-    """Run an RRQ worker process.
+    """Run RRQ worker processes.
     Requires an application-specific settings object.
     """
-    rrq_settings = _load_app_settings(settings_object_path)
+    if num_workers is None:
+        num_workers = (
+            os.cpu_count() or 1
+        )  # Default to CPU cores, or 1 if cpu_count() is None
+        click.echo(
+            f"No --num-workers specified, defaulting to {num_workers} (CPU cores)."
+        )
+    elif num_workers <= 0:
+        click.echo(
+            click.style("ERROR: --num-workers must be a positive integer.", fg="red"),
+            err=True,
+        )
+        sys.exit(1)
 
-    # Determine queues to poll
-    queues_arg = list(queues) if queues else None
-    # Run worker in foreground (burst or continuous mode)
+    # Restrict burst mode with multiple workers
+    if num_workers > 1 and burst:
+        click.echo(
+            click.style(
+                "ERROR: --burst mode is not supported with multiple workers (--num-workers > 1). "
+                "Burst mode cannot coordinate across multiple processes.",
+                fg="red",
+            ),
+            err=True,
+        )
+        sys.exit(1)
+
+    # Display settings source
+    click.echo("Loading RRQ Settings... ", nl=False)
+    if settings_object_path:
+        click.echo(f"from --settings parameter ({settings_object_path}).")
+    elif os.getenv("RRQ_SETTINGS"):
+        click.echo(f"from RRQ_SETTINGS env var ({os.getenv('RRQ_SETTINGS')}).")
+    elif DOTENV_AVAILABLE and find_dotenv(usecwd=True):
+        click.echo("found in .env file.")
+    else:
+        click.echo("using defaults.")
+
+    if num_workers == 1:
+        # Run a single worker in the current process
+        click.echo(f"Starting 1 RRQ worker process (Burst: {burst})")
+        _run_single_worker(
+            burst, list(queues) if queues else None, settings_object_path
+        )
+    else:
+        # Run multiple worker subprocesses
+        click.echo(f"Starting {num_workers} RRQ worker processes")
+        # Burst is guaranteed to be False here
+        _run_multiple_workers(
+            num_workers, list(queues) if queues else None, settings_object_path
+        )
 
-    logger.info(
-        f"Starting RRQ Worker (Burst: {burst}, App Settings: {settings_object_path})"
-    )
+
+def _run_single_worker(
+    burst: bool,
+    queues_arg: list[str] | None,
+    settings_object_path: str | None,
+):
+    """Helper function to run a single RRQ worker instance."""
+    rrq_settings = _load_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.",
+                "ERROR: No 'job_registry'. You must provide a JobRegistry instance in settings.",
                 fg="red",
             ),
             err=True,
@@ -378,22 +524,187 @@ def worker_run_command(
         burst=burst,
     )
 
-    loop = asyncio.get_event_loop()
     try:
-        logger.info("Starting worker run loop...")
-        loop.run_until_complete(worker_instance.run())
+        logger.info("Starting worker run loop for single worker...")
+        asyncio.run(worker_instance.run())
     except KeyboardInterrupt:
         logger.info("RRQ Worker run interrupted by user (KeyboardInterrupt).")
     except Exception as e:
-        logger.error(f"Exception during RRQ Worker run: {e}", exc_info=True)
+        click.echo(
+            click.style(f"ERROR: Exception during RRQ Worker run: {e}", fg="red"),
+            err=True,
+        )
+        # Consider re-raising or sys.exit(1) if the exception means failure
     finally:
-        logger.info("RRQ Worker run finished or exited. Cleaning up event loop.")
-        if loop.is_running():
-            loop.run_until_complete(loop.shutdown_asyncgens())
-            loop.close()
+        # asyncio.run handles loop cleanup.
+        logger.info("RRQ Worker run finished or exited.")
         logger.info("RRQ Worker has shut down.")
 
 
+def _run_multiple_workers(
+    num_workers: int,
+    queues: list[str] | None,
+    settings_object_path: str | None,
+):
+    """Manages multiple worker subprocesses."""
+    processes: list[subprocess.Popen] = []
+    # loop = asyncio.get_event_loop() # Not needed here, this function is synchronous
+
+    original_sigint_handler = signal.getsignal(signal.SIGINT)
+    original_sigterm_handler = signal.getsignal(signal.SIGTERM)
+
+    def sig_handler(signum, frame):
+        click.echo(
+            f"\nSignal {signal.Signals(signum).name} received. Terminating child workers..."
+        )
+        # Send SIGTERM to all processes
+        for i, p in enumerate(processes):
+            if p.poll() is None:  # Process is still running
+                try:
+                    pgid = os.getpgid(p.pid)
+                    click.echo(f"Sending SIGTERM to worker {i + 1} (PID {p.pid})...")
+                    os.killpg(pgid, signal.SIGTERM)
+                except (ProcessLookupError, OSError):
+                    pass  # Process already dead
+        # Restore original handlers before exiting or re-raising
+        signal.signal(signal.SIGINT, original_sigint_handler)
+        signal.signal(signal.SIGTERM, original_sigterm_handler)
+        # Propagate signal to ensure parent exits if it was, e.g., a Ctrl+C
+        # This is a bit tricky; for now, just exit.
+        # A more robust way might involve re-raising the signal if not handled by click/asyncio.
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, sig_handler)
+    signal.signal(signal.SIGTERM, sig_handler)
+
+    try:
+        for i in range(num_workers):
+            # Construct the command for the subprocess.
+            # Each subprocess runs 'rrq worker run' for a single worker.
+            # We pass along relevant flags like --settings, --queue, and --burst.
+            # Crucially, we do *not* pass --num-workers to the child,
+            # or rather, we could conceptually pass --num-workers 1.
+            # Use the rrq executable from the same venv
+            venv_bin_dir = os.path.dirname(sys.executable)
+            rrq_executable = os.path.join(venv_bin_dir, "rrq")
+            cmd = [rrq_executable, "worker", "run", "--num-workers=1"]
+            if settings_object_path:
+                cmd.extend(["--settings", settings_object_path])
+            elif os.getenv("RRQ_SETTINGS"):
+                # Pass the RRQ_SETTINGS env var as explicit parameter to subprocess
+                cmd.extend(["--settings", os.getenv("RRQ_SETTINGS")])
+            else:
+                # Error: No settings provided for multi-worker mode
+                click.echo(
+                    "Error: Multi-worker mode requires explicit settings. "
+                    "Please provide either --settings option or set RRQ_SETTINGS environment variable.",
+                    err=True,
+                )
+                sys.exit(1)
+            if queues:
+                for q_name in queues:
+                    cmd.extend(["--queue", q_name])
+            click.echo(f"Starting worker subprocess {i + 1}/{num_workers}...")
+
+            # Set up environment - add current directory to PYTHONPATH
+            env = os.environ.copy()
+            current_pythonpath = env.get("PYTHONPATH", "")
+            current_dir = os.getcwd()
+            if current_pythonpath:
+                env["PYTHONPATH"] = f"{current_dir}:{current_pythonpath}"
+            else:
+                env["PYTHONPATH"] = current_dir
+
+            # Configure output redirection
+            is_testing = "PYTEST_CURRENT_TEST" in os.environ
+            stdout_dest = None if not is_testing else subprocess.DEVNULL
+            stderr_dest = None if not is_testing else subprocess.DEVNULL
+
+            process = subprocess.Popen(
+                cmd,
+                start_new_session=True,
+                stdout=stdout_dest,
+                stderr=stderr_dest,
+                cwd=os.getcwd(),
+                env=env,
+            )
+            processes.append(process)
+            click.echo(f"Worker subprocess {i + 1} started with PID {process.pid}")
+
+        # Wait for all processes to complete
+        click.echo(f"All {num_workers} workers started. Press Ctrl+C to stop.")
+        exit_codes = []
+
+        try:
+            for p in processes:
+                exit_code = p.wait()
+                exit_codes.append(exit_code)
+        except KeyboardInterrupt:
+            # Signal handler has already sent SIGTERM, now wait with timeout
+            max_wait = 10
+            check_interval = 0.1
+            elapsed = 0
+
+            while elapsed < max_wait:
+                time.sleep(check_interval)
+                elapsed += check_interval
+
+                # Check if all processes have terminated
+                all_terminated = all(p.poll() is not None for p in processes)
+                if all_terminated:
+                    click.echo("All workers terminated gracefully.")
+                    break
+            else:
+                # Timeout reached, force kill remaining processes
+                for i, p in enumerate(processes):
+                    if p.poll() is None:
+                        try:
+                            click.echo(
+                                click.style(
+                                    f"WARNING: Worker {i + 1} did not terminate gracefully, sending SIGKILL.",
+                                    fg="yellow",
+                                ),
+                                err=True,
+                            )
+                            os.killpg(os.getpgid(p.pid), signal.SIGKILL)
+                        except (ProcessLookupError, OSError):
+                            pass
+
+            # Collect exit codes
+            for p in processes:
+                exit_codes.append(p.wait())
+
+        # Report results
+        for i, exit_code in enumerate(exit_codes):
+            click.echo(f"Worker subprocess {i + 1} exited with code {exit_code}")
+            if exit_code != 0:
+                click.echo(
+                    click.style(
+                        f"Worker subprocess {i + 1} failed with exit code {exit_code}",
+                        fg="red",
+                    ),
+                    err=True,
+                )
+
+    except Exception as e:
+        click.echo(
+            click.style(f"ERROR: Error managing worker subprocesses: {e}", fg="red"),
+            err=True,
+        )
+        # Terminate any running processes if an error occurs in the manager
+        for p in processes:
+            if p.poll() is None:  # If process is still running
+                terminate_worker_process(p, logger)
+    finally:
+        logger.info("All worker subprocesses terminated or completed.")
+        # Restore original signal handlers
+        signal.signal(signal.SIGINT, original_sigint_handler)
+        signal.signal(signal.SIGTERM, original_sigterm_handler)
+        # Any other cleanup for the parent process
+        # No loop to check or close here as this part is synchronous
+        logger.info("Parent process for multi-worker management is exiting.")
+
+
 @worker_cli.command("watch")
 @click.option(
     "--path",
@@ -468,65 +779,3 @@ def check_command(settings_object_path: str):
     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}'."
-    )

rrq/cli_commands/__init__.py

@@ -0,0 +1 @@
+"""RRQ CLI module"""

rrq/cli_commands/base.py

@@ -0,0 +1,102 @@
+"""Base classes and utilities for RRQ CLI commands"""
+
+import asyncio
+import importlib
+import os
+import pkgutil
+from abc import ABC, abstractmethod
+from typing import Callable
+
+import click
+
+from ..settings import RRQSettings
+from ..store import JobStore
+
+
+class BaseCommand(ABC):
+    """Base class for all RRQ CLI commands"""
+
+    @abstractmethod
+    def register(self, cli_group: click.Group) -> None:
+        """Register the command with the CLI group"""
+        pass
+
+
+class AsyncCommand(BaseCommand):
+    """Base class for async CLI commands"""
+
+    def make_async(self, func: Callable) -> Callable:
+        """Wrapper to run async functions in click commands"""
+
+        def wrapper(*args, **kwargs):
+            return asyncio.run(func(*args, **kwargs))
+
+        return wrapper
+
+
+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 the environment variable is not set, will create a default settings object.
+    """
+    # Import the original function from cli.py
+    from ..cli import _load_app_settings
+
+    return _load_app_settings(settings_object_path)
+
+
+def resolve_settings_source(
+    settings_object_path: str | None = None,
+) -> tuple[str | None, str]:
+    """Resolve the settings path and its source."""
+    # Import the original function from cli.py
+    from ..cli import _resolve_settings_source
+
+    return _resolve_settings_source(settings_object_path)
+
+
+def auto_discover_commands(package_path: str) -> list[type[BaseCommand]]:
+    """Auto-discover command classes in the given package"""
+    commands = []
+
+    # Get the package module
+    try:
+        package = importlib.import_module(package_path)
+        package_dir = os.path.dirname(package.__file__)
+    except ImportError:
+        # Return empty list for non-existent packages
+        return commands
+
+    # Iterate through all modules in the package
+    for _, module_name, is_pkg in pkgutil.iter_modules([package_dir]):
+        if is_pkg:
+            continue
+
+        # Import the module
+        module_path = f"{package_path}.{module_name}"
+        try:
+            module = importlib.import_module(module_path)
+
+            # Look for BaseCommand subclasses
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                if (
+                    isinstance(attr, type)
+                    and issubclass(attr, BaseCommand)
+                    and attr not in (BaseCommand, AsyncCommand)
+                ):
+                    commands.append(attr)
+        except ImportError:
+            # Skip modules that can't be imported
+            continue
+
+    return commands
+
+
+async def get_job_store(settings: RRQSettings) -> JobStore:
+    """Create and return a JobStore instance"""
+    job_store = JobStore(settings=settings)
+    # Test connection
+    await job_store.redis.ping()
+    return job_store

rrq/cli_commands/commands/__init__.py

@@ -0,0 +1 @@
+"""RRQ CLI commands module"""