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

rrq/__init__.py

@@ -0,0 +1,14 @@
+from .cron import CronJob, CronSchedule
+from .worker import RRQWorker
+from .client import RRQClient
+from .registry import JobRegistry
+from .settings import RRQSettings
+
+__all__ = [
+    "CronJob",
+    "CronSchedule",
+    "RRQWorker",
+    "RRQClient",
+    "JobRegistry",
+    "RRQSettings",
+]

rrq/cron.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any, Optional, Sequence
+
+from pydantic import BaseModel, Field, PrivateAttr
+
+MONTH_NAMES = {
+    "jan": 1,
+    "feb": 2,
+    "mar": 3,
+    "apr": 4,
+    "may": 5,
+    "jun": 6,
+    "jul": 7,
+    "aug": 8,
+    "sep": 9,
+    "oct": 10,
+    "nov": 11,
+    "dec": 12,
+}
+
+WEEKDAY_NAMES = {
+    "sun": 0,
+    "mon": 1,
+    "tue": 2,
+    "wed": 3,
+    "thu": 4,
+    "fri": 5,
+    "sat": 6,
+}
+
+
+def _parse_value(value: str, names: dict[str, int], min_val: int, max_val: int) -> int:
+    if value.lower() in names:
+        return names[value.lower()]
+    num = int(value)
+    if names is WEEKDAY_NAMES and num == 7:
+        num = 0
+    if not (min_val <= num <= max_val):
+        raise ValueError(f"value {num} out of range {min_val}-{max_val}")
+    return num
+
+
+def _parse_field(field: str, *, names: dict[str, int] | None, min_val: int, max_val: int) -> Sequence[int]:
+    names = names or {}
+    if field == "*":
+        return list(range(min_val, max_val + 1))
+    values: set[int] = set()
+    for part in field.split(','):
+        step = 1
+        if '/' in part:
+            base, step_str = part.split('/', 1)
+            step = int(step_str)
+        else:
+            base = part
+        if base == "*":
+            start, end = min_val, max_val
+        elif '-' in base:
+            a, b = base.split('-', 1)
+            start = _parse_value(a, names, min_val, max_val)
+            end = _parse_value(b, names, min_val, max_val)
+        else:
+            val = _parse_value(base, names, min_val, max_val)
+            start = end = val
+        if start > end:
+            raise ValueError(f"invalid range {base}")
+        for v in range(start, end + 1, step):
+            values.add(v)
+    return sorted(values)
+
+
+class CronSchedule:
+    """Represents a cron schedule expression."""
+
+    def __init__(self, expression: str) -> None:
+        fields = expression.split()
+        if len(fields) != 5:
+            raise ValueError("Cron expression must have 5 fields")
+        minute, hour, dom, month, dow = fields
+        self.minutes = _parse_field(minute, names=None, min_val=0, max_val=59)
+        self.hours = _parse_field(hour, names=None, min_val=0, max_val=23)
+        self.dom = _parse_field(dom, names=None, min_val=1, max_val=31)
+        self.months = _parse_field(month, names=MONTH_NAMES, min_val=1, max_val=12)
+        self.dow = _parse_field(dow, names=WEEKDAY_NAMES, min_val=0, max_val=6)
+        self.dom_all = dom == "*"
+        self.dow_all = dow == "*"
+
+    def next_after(self, dt: datetime) -> datetime:
+        dt = dt.replace(second=0, microsecond=0) + timedelta(minutes=1)
+        while True:
+            if dt.month not in self.months:
+                dt += timedelta(minutes=1)
+                continue
+            if dt.hour not in self.hours or dt.minute not in self.minutes:
+                dt += timedelta(minutes=1)
+                continue
+            dom_match = dt.day in self.dom
+            # Convert Python weekday (Monday=0) to cron weekday (Sunday=0)
+            # Python: Mon=0, Tue=1, Wed=2, Thu=3, Fri=4, Sat=5, Sun=6
+            # Cron:   Sun=0, Mon=1, Tue=2, Wed=3, Thu=4, Fri=5, Sat=6
+            python_weekday = dt.weekday()
+            cron_weekday = (python_weekday + 1) % 7
+            dow_match = cron_weekday in self.dow
+            
+            if self.dom_all and self.dow_all:
+                condition = True
+            elif self.dom_all:
+                # Only day-of-week constraint
+                condition = dow_match
+            elif self.dow_all:
+                # Only day-of-month constraint
+                condition = dom_match
+            else:
+                # Both constraints specified - use OR logic (standard cron behavior)
+                condition = dom_match or dow_match
+            if condition:
+                return dt
+            dt += timedelta(minutes=1)
+
+
+
+class CronJob(BaseModel):
+    """Simple cron job specification based on a cron schedule."""
+
+    function_name: str
+    schedule: str = Field(
+        description="Cron expression 'm h dom mon dow'. Resolution is one minute."
+    )
+    args: list[Any] = Field(default_factory=list)
+    kwargs: dict[str, Any] = Field(default_factory=dict)
+    queue_name: Optional[str] = None
+    unique: bool = False
+
+    # Next run time and parsed schedule are maintained at runtime
+    next_run_time: Optional[datetime] = Field(default=None, exclude=True)
+    _cron: CronSchedule | None = PrivateAttr(default=None)
+
+    def model_post_init(self, __context: Any) -> None:  # type: ignore[override]
+        self._cron = CronSchedule(self.schedule)
+
+    def schedule_next(self, now: Optional[datetime] = None) -> None:
+        """Compute the next run time strictly after *now*."""
+        now = (now or datetime.now(UTC)).replace(second=0, microsecond=0)
+        if self._cron is None:
+            self._cron = CronSchedule(self.schedule)
+        self.next_run_time = self._cron.next_after(now)
+
+    def due(self, now: Optional[datetime] = None) -> bool:
+        now = now or datetime.now(UTC)
+        if self.next_run_time is None:
+            self.schedule_next(now)
+        return now >= (self.next_run_time or now)

rrq/settings.py

@@ -21,6 +21,7 @@ from .constants import (
     DEFAULT_UNIQUE_JOB_LOCK_TTL_SECONDS,
 )
 from .registry import JobRegistry
+from .cron import CronJob
 
 
 class RRQSettings(BaseSettings):
@@ -97,6 +98,10 @@ class RRQSettings(BaseSettings):
         default=None,
         description="Job registry instance, typically provided by the application.",
     )
+    cron_jobs: list[CronJob] = Field(
+        default_factory=list,
+        description="Optional list of cron job specifications to run periodically.",
+    )
     model_config = SettingsConfigDict(
         env_prefix="RRQ_",
         extra="ignore",

rrq/worker.py

@@ -28,6 +28,7 @@ from .job import Job, JobStatus
 from .registry import JobRegistry
 from .settings import RRQSettings
 from .store import JobStore
+from .cron import CronJob
 
 logger = logging.getLogger(__name__)
 
@@ -77,11 +78,14 @@ class RRQWorker:
         # Burst mode: process existing jobs then exit
         self.burst = burst
 
+        self.cron_jobs: list[CronJob] = list(self.settings.cron_jobs)
+
         self._semaphore = asyncio.Semaphore(self.settings.worker_concurrency)
         self._running_tasks: set[asyncio.Task] = set()
         self._shutdown_event = asyncio.Event()
         self._loop = None  # Will be set in run()
         self._health_check_task: Optional[asyncio.Task] = None
+        self._cron_task: Optional[asyncio.Task] = None
         self.status: str = "initializing"  # Worker status (e.g., initializing, running, polling, idle, stopped)
         logger.info(
             f"Initializing RRQWorker {self.worker_id} for queues: {self.queues}"
@@ -135,6 +139,10 @@ class RRQWorker:
         """
         logger.info(f"Worker {self.worker_id} starting run loop.")
         self._health_check_task = self._loop.create_task(self._heartbeat_loop())
+        if self.cron_jobs:
+            for cj in self.cron_jobs:
+                cj.schedule_next()
+            self._cron_task = self._loop.create_task(self._cron_loop())
 
         while not self._shutdown_event.is_set():
             try:
@@ -181,6 +189,10 @@ class RRQWorker:
             self._health_check_task.cancel()
             with suppress(asyncio.CancelledError):
                 await self._health_check_task
+        if self._cron_task:
+            self._cron_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._cron_task
 
     async def _poll_for_jobs(self, count: int) -> None:
         """Polls configured queues round-robin and attempts to start processing jobs.
@@ -781,6 +793,39 @@ class RRQWorker:
 
         logger.debug(f"Worker {self.worker_id} heartbeat loop finished.")
 
+    async def _maybe_enqueue_cron_jobs(self) -> None:
+        """Enqueue cron jobs that are due to run."""
+        now = datetime.now(UTC)
+        for cj in self.cron_jobs:
+            if cj.due(now):
+                unique_key = f"cron:{cj.function_name}" if cj.unique else None
+                try:
+                    await self.client.enqueue(
+                        cj.function_name,
+                        *cj.args,
+                        _queue_name=cj.queue_name,
+                        _unique_key=unique_key,
+                        **cj.kwargs,
+                    )
+                finally:
+                    cj.schedule_next(now)
+
+    async def _cron_loop(self) -> None:
+        logger.debug(f"Worker {self.worker_id} starting cron loop.")
+        while not self._shutdown_event.is_set():
+            try:
+                await self._maybe_enqueue_cron_jobs()
+            except Exception as e:
+                logger.error(
+                    f"Worker {self.worker_id} error running cron jobs: {e}",
+                    exc_info=True,
+                )
+            try:
+                await asyncio.wait_for(self._shutdown_event.wait(), timeout=30)
+            except TimeoutError:
+                pass
+        logger.debug(f"Worker {self.worker_id} cron loop finished.")
+
     async def _close_resources(self) -> None:
         """Closes the worker's resources, primarily the JobStore connection."""
         logger.info(f"Worker {self.worker_id} closing resources...")

rrq-0.4.0.dist-info/METADATA

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: rrq
+Version: 0.4.0
+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>=1.0.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.
+
+## 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`.
+*   **Cron Jobs**: Periodic jobs can be defined in `RRQSettings.cron_jobs` using a simple cron syntax.
+
+    - 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`](https://github.com/GetResQ/rrq/tree/master/example) 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:**
+
+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
+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.
+
+## Cron Jobs
+
+Add instances of `CronJob` to `RRQSettings.cron_jobs` to run periodic jobs. The
+`schedule` string follows the typical five-field cron format `minute hour day-of-month month day-of-week`.
+It supports the most common features from Unix cron:
+
+- numeric values
+- ranges (e.g. `8-11`)
+- lists separated by commas (e.g. `mon,wed,fri`)
+- step values using `/` (e.g. `*/15`)
+- names for months and days (`jan-dec`, `sun-sat`)
+
+Jobs are evaluated in the server's timezone and run with minute resolution.
+
+### Cron Schedule Examples
+
+```python
+# Every minute
+"* * * * *"
+
+# Every hour at minute 30
+"30 * * * *"
+
+# Every day at 2:30 AM
+"30 2 * * *"
+
+# Every Monday at 9:00 AM
+"0 9 * * mon"
+
+# Every 15 minutes
+"*/15 * * * *"
+
+# Every weekday at 6:00 PM
+"0 18 * * mon-fri"
+
+# First day of every month at midnight
+"0 0 1 * *"
+
+# Every 2 hours during business hours on weekdays
+"0 9-17/2 * * mon-fri"
+```
+
+### Defining Cron Jobs
+
+```python
+from rrq.settings import RRQSettings
+from rrq.cron import CronJob
+
+# Define your cron jobs
+cron_jobs = [
+    # Daily cleanup at 2 AM
+    CronJob(
+        function_name="daily_cleanup",
+        schedule="0 2 * * *",
+        args=["temp_files"],
+        kwargs={"max_age_days": 7}
+    ),
+    
+    # Weekly report every Monday at 9 AM
+    CronJob(
+        function_name="generate_weekly_report",
+        schedule="0 9 * * mon",
+        unique=True  # Prevent duplicate reports if worker restarts
+    ),
+    
+    # Health check every 15 minutes on a specific queue
+    CronJob(
+        function_name="system_health_check",
+        schedule="*/15 * * * *",
+        queue_name="monitoring"
+    ),
+    
+    # Backup database every night at 1 AM
+    CronJob(
+        function_name="backup_database",
+        schedule="0 1 * * *",
+        kwargs={"backup_type": "incremental"}
+    ),
+]
+
+# Add to your settings
+rrq_settings = RRQSettings(
+    redis_dsn="redis://localhost:6379/0",
+    cron_jobs=cron_jobs
+)
+```
+
+### Cron Job Handlers
+
+Your cron job handlers are regular async functions, just like other job handlers:
+
+```python
+async def daily_cleanup(ctx, file_type: str, max_age_days: int = 7):
+    """Clean up old files."""
+    job_id = ctx['job_id']
+    print(f"Job {job_id}: Cleaning up {file_type} files older than {max_age_days} days")
+    # Your cleanup logic here
+    return {"cleaned_files": 42, "status": "completed"}
+
+async def generate_weekly_report(ctx):
+    """Generate and send weekly report."""
+    job_id = ctx['job_id']
+    print(f"Job {job_id}: Generating weekly report")
+    # Your report generation logic here
+    return {"report_id": "weekly_2024_01", "status": "sent"}
+
+# Register your handlers
+from rrq.registry import JobRegistry
+
+job_registry = JobRegistry()
+job_registry.register("daily_cleanup", daily_cleanup)
+job_registry.register("generate_weekly_report", generate_weekly_report)
+
+# Add the registry to your settings
+rrq_settings.job_registry = job_registry
+```
+
+**Note:** Cron jobs are automatically enqueued by the worker when they become due. The worker checks for due cron jobs every 30 seconds and enqueues them as regular jobs to be processed.
+
+## 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.
+
+## Configuration
+
+RRQ can be configured in several ways, with the following precedence:
+
+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.
+
+**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.
+
+
+## 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`, `

rrq-0.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+rrq/__init__.py,sha256=3WYv9UkvnCbjKXrvmqiLm7yuVVQiLclbVCOXq5wb6ZM,290
+rrq/cli.py,sha256=_LbaAH_w2a0VNRR0EctuE4afl-wccvMY2w2VbehFDEQ,16980
+rrq/client.py,sha256=5_bmZ05LKIfY9WFSKU-nYawEupsnrnHT2HewXfC2Ahg,7831
+rrq/constants.py,sha256=F_uZgBI3h00MctnEjBjiCGMrg5jUaz5Bz9I1vkyqNrs,1654
+rrq/cron.py,sha256=9lxJ1OnrTbavJvbIdPp6u5ncYgyD35vRPsSulpVrQko,5244
+rrq/exc.py,sha256=NJq3C7pUfcd47AB8kghIN8vdY0l90UrsHQEg4McBHP8,1281
+rrq/job.py,sha256=eUbl33QDqDMXPKpo-0dl0Mp29LWWmtbBgRw0sclcwJ4,4011
+rrq/registry.py,sha256=E9W_zx3QiKTBwMOGearaNpDKBDB87JIn0RlMQ3sAcP0,2925
+rrq/settings.py,sha256=AxzSe_rw7-yduKST2c9mPunQWqPE2537XcC_XlMoHWM,4535
+rrq/store.py,sha256=teO0Af8hzBiu7-dFn6_2lz5X90LAZXmtg0VDZuQoAwk,24972
+rrq/worker.py,sha256=KspmZOL6i_dfIypcBi0UpQDpz2NrCj3vEl6CwTNlLKo,42479
+rrq-0.4.0.dist-info/METADATA,sha256=2SFZJlfgwFSpmWfylQ6rSV072HGXlA2MBcECJppV_DY,12914
+rrq-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rrq-0.4.0.dist-info/entry_points.txt,sha256=f8eFjk2ygDSyu9USwXGj5IM8xeyQqZgDa1rSrCj4Mis,36
+rrq-0.4.0.dist-info/licenses/LICENSE,sha256=XDvu5hKdS2-_ByiSj3tiu_3zSsrXXoJsgbILGoMpKCw,554
+rrq-0.4.0.dist-info/RECORD,,

rrq-0.3.6.dist-info/METADATA

@@ -1,205 +0,0 @@
-Metadata-Version: 2.4
-Name: rrq
-Version: 0.3.6
-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-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
-
-*   **`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.*
-    *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`](https://github.com/GetResQ/rrq/tree/master/example) 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] --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
-
-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.3.6.dist-info/RECORD

@@ -1,15 +0,0 @@
-rrq/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rrq/cli.py,sha256=_LbaAH_w2a0VNRR0EctuE4afl-wccvMY2w2VbehFDEQ,16980
-rrq/client.py,sha256=5_bmZ05LKIfY9WFSKU-nYawEupsnrnHT2HewXfC2Ahg,7831
-rrq/constants.py,sha256=F_uZgBI3h00MctnEjBjiCGMrg5jUaz5Bz9I1vkyqNrs,1654
-rrq/exc.py,sha256=NJq3C7pUfcd47AB8kghIN8vdY0l90UrsHQEg4McBHP8,1281
-rrq/job.py,sha256=eUbl33QDqDMXPKpo-0dl0Mp29LWWmtbBgRw0sclcwJ4,4011
-rrq/registry.py,sha256=E9W_zx3QiKTBwMOGearaNpDKBDB87JIn0RlMQ3sAcP0,2925
-rrq/settings.py,sha256=BPKP4XjG7z475gqRgHZt4-IvvOs8uZefq4fPfD2Bepk,4350
-rrq/store.py,sha256=teO0Af8hzBiu7-dFn6_2lz5X90LAZXmtg0VDZuQoAwk,24972
-rrq/worker.py,sha256=y0UTziZVh4QbOPv24b8cqbm_xDBM0HtJLwPNYsJPWnE,40706
-rrq-0.3.6.dist-info/METADATA,sha256=MKJ-uoveQQVVI4p_RhRA1Kk-KN9_J348gGYY572HUY0,9224
-rrq-0.3.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-rrq-0.3.6.dist-info/entry_points.txt,sha256=f8eFjk2ygDSyu9USwXGj5IM8xeyQqZgDa1rSrCj4Mis,36
-rrq-0.3.6.dist-info/licenses/LICENSE,sha256=XDvu5hKdS2-_ByiSj3tiu_3zSsrXXoJsgbILGoMpKCw,554
-rrq-0.3.6.dist-info/RECORD,,