rrq 0.3.7__py3-none-any.whl → 0.5.0__py3-none-any.whl

{rrq-0.3.7.dist-info → rrq-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrq
-Version: 0.3.7
+Version: 0.5.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
@@ -20,7 +20,7 @@ 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-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
@@ -40,6 +40,7 @@ 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`.
+*   **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.
 
@@ -138,6 +139,125 @@ if __name__ == "__main__":
 
 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:
@@ -145,7 +265,8 @@ RRQ provides a command-line interface (CLI) for managing workers and performing
 - **`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.
+  - `--burst` (flag): Run the worker in burst mode to process one job or batch and then exit. Cannot be used with `--num-workers > 1`.
+  - `--num-workers` (optional, integer): Number of parallel worker processes to start. Defaults to the number of CPU cores available on the machine. Cannot be used with `--burst` mode.
 - **`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.
@@ -178,7 +299,4 @@ RRQ can be configured in several ways, with the following precedence:
 *   **`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.
+*   **`JobStatus` (`job.py`)**: An Enum defining the possible states of a job (`PENDING`, `ACTIVE`, `COMPLETED`, `FAILED`, `

rrq-0.5.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+rrq/__init__.py,sha256=3WYv9UkvnCbjKXrvmqiLm7yuVVQiLclbVCOXq5wb6ZM,290
+rrq/cli.py,sha256=7wLO0gRl8Qe1Tf6dyELJnVfJc6rr5pw6m6Mj7qMl3bk,27550
+rrq/client.py,sha256=5_bmZ05LKIfY9WFSKU-nYawEupsnrnHT2HewXfC2Ahg,7831
+rrq/constants.py,sha256=F_uZgBI3h00MctnEjBjiCGMrg5jUaz5Bz9I1vkyqNrs,1654
+rrq/cron.py,sha256=etDwnOXr5Ys1Vt08oYQsMjtLbPsjMWMvbund4bWOlCA,5237
+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=TrtVojnT7wJNV1jaXsjHXQa3IDeQJ4-0PKDCEjZuDi0,29537
+rrq/worker.py,sha256=1bbZkUCSHwFzpsxcsc84RU_7h8dCnFItJCZ4SG4zASc,44940
+rrq-0.5.0.dist-info/METADATA,sha256=vud54ZneWCUMJ0pjg_FmUHaBo1oxqOBbw2yC63gMKy0,13140
+rrq-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rrq-0.5.0.dist-info/entry_points.txt,sha256=f8eFjk2ygDSyu9USwXGj5IM8xeyQqZgDa1rSrCj4Mis,36
+rrq-0.5.0.dist-info/licenses/LICENSE,sha256=XDvu5hKdS2-_ByiSj3tiu_3zSsrXXoJsgbILGoMpKCw,554
+rrq-0.5.0.dist-info/RECORD,,

rrq-0.3.7.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.7.dist-info/METADATA,sha256=fqMod1pTxebf7d4fCh5vRK0o9gkD4OAYg-02TNHJfN4,10193
-rrq-0.3.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-rrq-0.3.7.dist-info/entry_points.txt,sha256=f8eFjk2ygDSyu9USwXGj5IM8xeyQqZgDa1rSrCj4Mis,36
-rrq-0.3.7.dist-info/licenses/LICENSE,sha256=XDvu5hKdS2-_ByiSj3tiu_3zSsrXXoJsgbILGoMpKCw,554
-rrq-0.3.7.dist-info/RECORD,,