rrq 0.3.7__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rrq
-Version: 0.3.7
+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
@@ -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:
@@ -178,7 +298,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.3.7 → rrq-0.4.0}/README.md

@@ -13,6 +13,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.
 
@@ -111,6 +112,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:
@@ -151,7 +271,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.3.7 → rrq-0.4.0}/example/example_rrq_settings.py

@@ -3,6 +3,7 @@
 import asyncio
 import logging
 
+from rrq.cron import CronJob
 from rrq.settings import RRQSettings
 
 logger = logging.getLogger("rrq")
@@ -34,5 +35,27 @@ rrq_settings = RRQSettings(
     redis_dsn=redis_dsn,
     on_startup=on_startup_hook,
     on_shutdown=on_shutdown_hook,
+    # Example cron jobs - these would run periodically when a worker is running
+    cron_jobs=[
+        # Run a cleanup task every day at 2 AM
+        CronJob(
+            function_name="daily_cleanup",
+            schedule="0 2 * * *",
+            args=["cleanup_logs"],
+            kwargs={"max_age_days": 30}
+        ),
+        # Send a status report every Monday at 9 AM
+        CronJob(
+            function_name="send_status_report",
+            schedule="0 9 * * mon",
+            unique=True  # Prevent duplicate reports if worker restarts
+        ),
+        # Health check every 15 minutes
+        CronJob(
+            function_name="health_check",
+            schedule="*/15 * * * *",
+            queue_name="monitoring"  # Use a specific queue for monitoring tasks
+        ),
+    ]
 )
 

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

@@ -8,6 +8,7 @@ from contextlib import suppress
 from datetime import timedelta
 
 from rrq.client import RRQClient
+from rrq.cron import CronJob
 from rrq.exc import RetryJob
 from rrq.registry import JobRegistry
 from rrq.settings import RRQSettings
@@ -62,6 +63,33 @@ async def retry_task(ctx, counter_limit: int):
         return {"status": "completed_after_retries", "attempts": attempt}
 
 
+# --- Example Cron Job Handlers ---
+async def daily_cleanup(ctx, task_type: str, max_age_days: int = 30):
+    """Example cron job handler for daily cleanup tasks."""
+    logger.info(
+        f"DAILY_CLEANUP (Job {ctx['job_id']}): Running {task_type} cleanup, max age: {max_age_days} days"
+    )
+    await asyncio.sleep(0.5)  # Simulate cleanup work
+    logger.info(f"DAILY_CLEANUP (Job {ctx['job_id']}): Cleanup completed")
+    return {"task_type": task_type, "max_age_days": max_age_days, "status": "completed"}
+
+
+async def send_status_report(ctx):
+    """Example cron job handler for sending status reports."""
+    logger.info(f"STATUS_REPORT (Job {ctx['job_id']}): Generating and sending status report")
+    await asyncio.sleep(0.3)  # Simulate report generation
+    logger.info(f"STATUS_REPORT (Job {ctx['job_id']}): Status report sent")
+    return {"report_type": "weekly", "status": "sent"}
+
+
+async def health_check(ctx):
+    """Example cron job handler for health checks."""
+    logger.info(f"HEALTH_CHECK (Job {ctx['job_id']}): Running system health check")
+    await asyncio.sleep(0.1)  # Simulate health check
+    logger.info(f"HEALTH_CHECK (Job {ctx['job_id']}): Health check completed - all systems OK")
+    return {"status": "healthy", "timestamp": ctx.get("job_start_time")}
+
+
 # --- Main Execution ---
 async def main():
     logger.info("--- Starting RRQ Example ---")
@@ -72,8 +100,24 @@ async def main():
         default_max_retries=3,  # Lower retries for example
         worker_health_check_interval_seconds=5,  # Frequent health check
         worker_shutdown_grace_period_seconds=5,
+        # Example cron jobs - these will run periodically when the worker is running
+        cron_jobs=[
+            # Run a health check every 2 minutes (for demo purposes)
+            CronJob(
+                function_name="health_check",
+                schedule="*/2 * * * *",  # Every 2 minutes
+                queue_name="monitoring"
+            ),
+            # Send a status report every 5 minutes (for demo purposes)
+            CronJob(
+                function_name="send_status_report",
+                schedule="*/5 * * * *",  # Every 5 minutes
+                unique=True  # Prevent duplicate reports
+            ),
+        ]
     )
     logger.info(f"Using Redis DB: {settings.redis_dsn}")
+    logger.info(f"Configured {len(settings.cron_jobs)} cron jobs")
 
     # Ensure Redis DB is clean before starting (optional, good for examples)
     try:
@@ -90,6 +134,10 @@ async def main():
     registry.register("handle_success", successful_task)
     registry.register("handle_failure", failing_task)
     registry.register("handle_retry", retry_task)
+    # Register cron job handlers
+    registry.register("daily_cleanup", daily_cleanup)
+    registry.register("send_status_report", send_status_report)
+    registry.register("health_check", health_check)
     logger.info(f"Registered handlers: {registry.get_registered_functions()}")
 
     # 3. Client
@@ -131,7 +179,7 @@ async def main():
     worker = RRQWorker(
         settings=settings,
         job_registry=registry,
-        queues=[settings.default_queue_name, "high_priority"],
+        queues=[settings.default_queue_name, "high_priority", "monitoring"],
     )
 
     # 6. Run Worker (with graceful shutdown handling)

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

@@ -4,10 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rrq"
-version = "0.3.7"
-authors = [
-    { name = "Mazdak Rezvani", email = "mazdak@me.com" },
-]
+version = "0.4.0"
+authors = [{ name = "Mazdak Rezvani", email = "mazdak@me.com" }]
 description = "RRQ is a Python library for creating reliable job queues using Redis and asyncio"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,11 +28,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = [
-    "pytest>=8.3.5",
-    "pytest-asyncio>=0.26.0",
-    "pytest-cov>=6.0.0",
-]
+dev = ["pytest>=8.3.5", "pytest-asyncio>=1.0.0", "pytest-cov>=6.0.0"]
 
 [project.urls]
 "Homepage" = "https://github.com/getresq/rrq"
@@ -44,4 +38,8 @@ dev = [
 rrq = "rrq.cli:rrq"
 
 [tool.pytest.ini_options]
+asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"
+
+[tool.pyrefly]
+python_interpreter = ".venv/bin/python"

rrq-0.4.0/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-0.4.0/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-0.3.7 → rrq-0.4.0}/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",