django-periodic-tasks 0.1.0a3__py3-none-any.whl

django_periodic_tasks/__init__.py

@@ -0,0 +1,15 @@
+from django_periodic_tasks.decorators import exactly_once
+from django_periodic_tasks.registry import (
+    ScheduleEntry,
+    ScheduleRegistry,
+    schedule_registry,
+    scheduled_task,
+)
+
+__all__ = [
+    "ScheduleEntry",
+    "ScheduleRegistry",
+    "exactly_once",
+    "schedule_registry",
+    "scheduled_task",
+]

django_periodic_tasks/admin.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+from django.contrib import admin
+from django.http import HttpRequest
+
+from django_periodic_tasks.models import ScheduledTask, TaskExecution
+
+# Fields that are always read-only (computed/tracking)
+TRACKING_READONLY = ("source", "last_run_at", "next_run_at", "total_run_count", "created_at", "updated_at")
+
+# All editable model fields
+ALL_FIELDS = (
+    "name",
+    "task_path",
+    "cron_expression",
+    "timezone",
+    "args",
+    "kwargs",
+    "source",
+    "enabled",
+    "queue_name",
+    "priority",
+    "backend",
+    "last_run_at",
+    "next_run_at",
+    "total_run_count",
+    "created_at",
+    "updated_at",
+)
+
+
+@admin.register(ScheduledTask)
+class ScheduledTaskAdmin(admin.ModelAdmin[ScheduledTask]):
+    list_display = (
+        "name",
+        "task_path",
+        "cron_expression",
+        "source",
+        "enabled",
+        "last_run_at",
+        "next_run_at",
+        "total_run_count",
+    )
+    list_filter = ("source", "enabled")
+    search_fields = ("name", "task_path")
+    ordering = ("name",)
+
+    def get_readonly_fields(
+        self,
+        request: HttpRequest,
+        obj: ScheduledTask | None = None,
+    ) -> tuple[str, ...]:
+        if obj is None:
+            # New task being created
+            return TRACKING_READONLY
+        if obj.source == ScheduledTask.Source.CODE:
+            # Code-defined tasks: everything is read-only
+            return ALL_FIELDS
+        # DB-defined tasks: only tracking fields are read-only
+        return TRACKING_READONLY
+
+    def has_delete_permission(
+        self,
+        request: HttpRequest,
+        obj: Any = None,
+    ) -> bool:
+        if obj is not None and obj.source == ScheduledTask.Source.CODE:
+            return False
+        return super().has_delete_permission(request, obj)
+
+
+@admin.register(TaskExecution)
+class TaskExecutionAdmin(admin.ModelAdmin[TaskExecution]):
+    list_display = ("id", "scheduled_task", "status", "created_at", "completed_at")
+    list_filter = ("status",)
+    search_fields = ("scheduled_task__name",)
+    ordering = ("-created_at",)
+
+    def has_add_permission(self, request: HttpRequest) -> bool:
+        return False
+
+    def has_change_permission(self, request: HttpRequest, obj: Any = None) -> bool:
+        return False
+
+    def has_delete_permission(self, request: HttpRequest, obj: Any = None) -> bool:
+        return False

django_periodic_tasks/apps.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+import logging
+
+from django.apps import AppConfig
+from django.conf import settings
+from django.utils.module_loading import autodiscover_modules
+
+if TYPE_CHECKING:
+    from django_periodic_tasks.scheduler import PeriodicTaskScheduler
+
+logger = logging.getLogger(__name__)
+
+_scheduler: PeriodicTaskScheduler | None = None
+
+
+class DjangoPeriodicTasksConfig(AppConfig):
+    name = "django_periodic_tasks"
+    verbose_name = "Django Periodic Tasks"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        autodiscover_modules("tasks")
+
+        global _scheduler  # noqa: PLW0603
+
+        if not getattr(settings, "PERIODIC_TASKS_AUTOSTART", False):
+            return
+
+        if _scheduler is not None:
+            return
+
+        from django_periodic_tasks.scheduler import PeriodicTaskScheduler
+
+        interval: int = getattr(settings, "PERIODIC_TASKS_SCHEDULER_INTERVAL", 15)
+        _scheduler = PeriodicTaskScheduler(interval=interval)
+        _scheduler.start()
+        logger.info("Auto-started periodic task scheduler (interval=%ds)", interval)

django_periodic_tasks/cron.py

@@ -0,0 +1,41 @@
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
+
+from croniter import CroniterBadCronError, croniter
+
+
+def validate_cron_expression(expression: str) -> bool:
+    """Validate a cron expression string."""
+    result: bool = croniter.is_valid(expression)
+    return result
+
+
+def compute_next_run_at(
+    cron_expression: str,
+    timezone_name: str = "UTC",
+    base_time: datetime | None = None,
+) -> datetime:
+    """Compute the next run time from a cron expression.
+
+    The base_time is interpreted in the given timezone for cron matching,
+    but the result is always returned in UTC.
+    """
+    try:
+        tz = ZoneInfo(timezone_name)
+    except (KeyError, ValueError) as e:
+        raise ValueError(f"Invalid timezone: {timezone_name}") from e
+
+    if base_time is None:
+        base_time = datetime.now(tz=timezone.utc)
+
+    # Convert base_time to the target timezone for correct cron matching
+    base_in_tz = base_time.astimezone(tz)
+
+    try:
+        cron = croniter(cron_expression, base_in_tz)
+    except (CroniterBadCronError, KeyError, ValueError) as e:
+        raise ValueError(f"Invalid cron expression: {cron_expression}") from e
+
+    next_time: datetime = cron.get_next(datetime)
+    # croniter returns tz-aware datetime in the same tz as input
+    return next_time.astimezone(timezone.utc)

django_periodic_tasks/decorators.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+import functools
+import logging
+
+from django.db import transaction
+from django.utils import timezone
+
+logger = logging.getLogger(__name__)
+
+
+def exactly_once(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator ensuring a scheduled task runs at most once per invocation.
+
+    When the scheduler creates a ``TaskExecution`` row and passes its ID via
+    the ``_periodic_tasks_execution_id`` keyword argument, this decorator will:
+
+    1. Pop ``_periodic_tasks_execution_id`` from kwargs.
+    2. Lock the ``TaskExecution`` row with ``SELECT FOR UPDATE``.
+    3. Run the wrapped function only if the row's status is ``PENDING``.
+    4. Mark the row ``COMPLETED`` on success.
+
+    If ``_periodic_tasks_execution_id`` is absent (e.g. manual invocation), the wrapped
+    function runs normally without any execution-permit logic.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        execution_id: str | None = kwargs.pop("_periodic_tasks_execution_id", None)
+
+        if execution_id is None:
+            return func(*args, **kwargs)
+
+        from django_periodic_tasks.models import (
+            TaskExecution,  # Avoid AppRegistryNotReady
+        )
+
+        with transaction.atomic():
+            execution = TaskExecution.objects.select_for_update().filter(id=execution_id, status=TaskExecution.Status.PENDING).first()
+
+            if execution is None:
+                logger.warning(
+                    "TaskExecution %s not found or not PENDING, skipping",
+                    execution_id,
+                )
+                return None
+
+            result = func(*args, **kwargs)
+
+            execution.status = TaskExecution.Status.COMPLETED
+            execution.completed_at = timezone.now()
+            execution.save(update_fields=["status", "completed_at"])
+
+        return result
+
+    wrapper._exactly_once = True  # type: ignore[attr-defined]
+    return wrapper

django_periodic_tasks/management/commands/run_scheduler.py

@@ -0,0 +1,60 @@
+from argparse import ArgumentParser
+from types import FrameType
+import logging
+import signal
+
+from django.conf import settings
+from django.core.management.base import BaseCommand
+
+from django_periodic_tasks.scheduler import PeriodicTaskScheduler
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    """Run the periodic task scheduler as a standalone process.
+
+    This command starts the scheduler loop in the main thread (blocking).
+    It syncs code-defined schedules to the database, then repeatedly checks for
+    due tasks and enqueues them. Use this when running the scheduler separately
+    from the task worker, or when using a non-database task backend.
+    """
+
+    help = "Run the periodic task scheduler (without a task worker)"
+
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        default_interval: int = getattr(settings, "PERIODIC_TASKS_SCHEDULER_INTERVAL", 15)
+        parser.add_argument(
+            "--interval",
+            type=int,
+            default=default_interval,
+            help="Interval in seconds between scheduler ticks (default: %(default)s)",
+        )
+
+    def handle(self, *, interval: int, verbosity: int, **options: object) -> None:
+        self._configure_logging(verbosity)
+
+        scheduler = PeriodicTaskScheduler(interval=interval)
+        logger.info("Starting periodic task scheduler (interval=%ds)", interval)
+
+        def shutdown(signum: int, frame: FrameType | None) -> None:
+            logger.info("Received %s, stopping scheduler...", signal.strsignal(signum))
+            scheduler.stop()
+
+        signal.signal(signal.SIGINT, shutdown)
+        signal.signal(signal.SIGTERM, shutdown)
+
+        # Run in the main thread (blocking)
+        scheduler.run()
+
+    def _configure_logging(self, verbosity: int) -> None:
+        pkg_logger = logging.getLogger("django_periodic_tasks")
+        if verbosity == 0:
+            pkg_logger.setLevel(logging.CRITICAL)
+        elif verbosity == 1:
+            pkg_logger.setLevel(logging.INFO)
+        else:
+            pkg_logger.setLevel(logging.DEBUG)
+
+        if not pkg_logger.hasHandlers():
+            pkg_logger.addHandler(logging.StreamHandler(self.stdout))

django_periodic_tasks/migrations/0001_initial.py

@@ -0,0 +1,37 @@
+# Generated by Django 6.0.2 on 2026-02-05 19:03
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="ScheduledTask",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("name", models.CharField(max_length=200, unique=True)),
+                ("task_path", models.CharField(max_length=200)),
+                ("cron_expression", models.CharField(max_length=200)),
+                ("timezone", models.CharField(default="UTC", max_length=63)),
+                ("args", models.JSONField(blank=True, default=list)),
+                ("kwargs", models.JSONField(blank=True, default=dict)),
+                ("source", models.CharField(choices=[("code", "Code"), ("database", "Database")], default="database", max_length=20)),
+                ("enabled", models.BooleanField(default=True)),
+                ("last_run_at", models.DateTimeField(blank=True, null=True)),
+                ("next_run_at", models.DateTimeField(blank=True, db_index=True, null=True)),
+                ("total_run_count", models.PositiveIntegerField(default=0)),
+                ("queue_name", models.CharField(blank=True, default="default", max_length=32)),
+                ("priority", models.IntegerField(default=0)),
+                ("backend", models.CharField(blank=True, default="default", max_length=32)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                "indexes": [models.Index(condition=models.Q(("enabled", True)), fields=["next_run_at"], name="periodic_due_tasks_idx")],
+            },
+        ),
+    ]

django_periodic_tasks/migrations/0002_remove_redundant_next_run_at_db_index.py

@@ -0,0 +1,17 @@
+# Generated by Django 6.0.2 on 2026-02-05 21:05
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_periodic_tasks", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="scheduledtask",
+            name="next_run_at",
+            field=models.DateTimeField(blank=True, null=True),
+        ),
+    ]

django_periodic_tasks/migrations/0003_add_task_execution.py

@@ -0,0 +1,31 @@
+# Generated by Django 6.0.2 on 2026-02-05 21:09
+
+import uuid
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_periodic_tasks", "0002_remove_redundant_next_run_at_db_index"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="TaskExecution",
+            fields=[
+                ("id", models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ("status", models.CharField(choices=[("pending", "Pending"), ("completed", "Completed")], default="pending", max_length=20)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("completed_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "scheduled_task",
+                    models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name="executions", to="django_periodic_tasks.scheduledtask"),
+                ),
+            ],
+            options={
+                "indexes": [models.Index(condition=models.Q(("status", "pending")), fields=["status"], name="periodic_pending_exec_idx")],
+            },
+        ),
+    ]

django_periodic_tasks/models.py

@@ -0,0 +1,146 @@
+from typing import Any
+from zoneinfo import ZoneInfo
+import uuid
+
+from django.core.exceptions import ValidationError
+from django.db import models
+
+from django_periodic_tasks.cron import compute_next_run_at, validate_cron_expression
+
+
+class ScheduledTask(models.Model):
+    """A persistent record of a periodic task and its cron schedule.
+
+    Each row represents one scheduled task. The scheduler queries this table on
+    every tick to find tasks whose ``next_run_at`` has passed, then enqueues
+    them via django-tasks.
+
+    Tasks can originate from two sources (see :class:`Source`):
+
+    * **Code-defined** — registered with :func:`~django_periodic_tasks.registry.scheduled_task`
+      and synced to the database on scheduler startup.
+    * **Database-defined** — created manually through the Django admin.
+    """
+
+    class Source(models.TextChoices):
+        """Where a scheduled task definition comes from.
+
+        ``CODE`` schedules are managed by the codebase and synced automatically.
+        ``DATABASE`` schedules are managed by operators through the Django admin.
+        """
+
+        CODE = "code", "Code"
+        DATABASE = "database", "Database"
+
+    # Identity
+    name = models.CharField(max_length=200, unique=True)
+    task_path = models.CharField(max_length=200)
+
+    # Schedule
+    cron_expression = models.CharField(max_length=200)
+    timezone = models.CharField(max_length=63, default="UTC")
+
+    # Arguments (passed to task.enqueue())
+    args = models.JSONField(default=list, blank=True)
+    kwargs = models.JSONField(default=dict, blank=True)
+
+    # Source & Status
+    source = models.CharField(max_length=20, choices=Source.choices, default=Source.DATABASE)
+    enabled = models.BooleanField(default=True)
+
+    # Execution tracking
+    last_run_at = models.DateTimeField(null=True, blank=True)
+    next_run_at = models.DateTimeField(null=True, blank=True)
+    total_run_count = models.PositiveIntegerField(default=0)
+
+    # Task options (passed to task.using())
+    queue_name = models.CharField(max_length=32, default="default", blank=True)
+    priority = models.IntegerField(default=0)
+    backend = models.CharField(max_length=32, default="default", blank=True)
+
+    # Metadata
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        indexes = [
+            models.Index(
+                fields=["next_run_at"],
+                condition=models.Q(enabled=True),
+                name="periodic_due_tasks_idx",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.name} ({self.cron_expression})"
+
+    def clean(self) -> None:
+        errors: dict[str, str] = {}
+        if not validate_cron_expression(self.cron_expression):
+            errors["cron_expression"] = f"Invalid cron expression: {self.cron_expression}"
+        try:
+            ZoneInfo(self.timezone)
+        except (KeyError, ValueError):
+            errors["timezone"] = f"Invalid timezone: {self.timezone}"
+        if "." not in self.task_path:
+            errors["task_path"] = "task_path must be a dotted module path (e.g. 'myapp.tasks.my_task')"
+        if errors:
+            raise ValidationError(errors)
+
+    def save(self, *args: Any, **kwargs: Any) -> None:
+        original_next_run_at = self.next_run_at
+
+        if not self.enabled:
+            self.next_run_at = None
+        elif self.next_run_at is None:
+            self.next_run_at = compute_next_run_at(self.cron_expression, self.timezone)
+
+        raw_update_fields: list[str] | None = kwargs.get("update_fields")
+        if raw_update_fields is not None:
+            fields = set(raw_update_fields)
+            # Always include updated_at so auto_now fires
+            fields.add("updated_at")
+            # Include next_run_at if save() modified it
+            if self.next_run_at != original_next_run_at:
+                fields.add("next_run_at")
+            kwargs["update_fields"] = list(fields)
+
+        super().save(*args, **kwargs)
+
+
+class TaskExecution(models.Model):
+    """An execution permit for a single scheduled task invocation.
+
+    Used by the ``@exactly_once`` decorator to ensure a task runs at most once
+    per scheduled invocation, even with non-transactional backends (e.g. Redis/RQ).
+    """
+
+    class Status(models.TextChoices):
+        PENDING = "pending", "Pending"
+        COMPLETED = "completed", "Completed"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    scheduled_task = models.ForeignKey(
+        ScheduledTask,
+        on_delete=models.CASCADE,
+        related_name="executions",
+    )
+    status = models.CharField(
+        max_length=20,
+        choices=Status.choices,
+        default=Status.PENDING,
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    completed_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        indexes = [
+            models.Index(
+                fields=["status"],
+                condition=models.Q(status="pending"),
+                name="periodic_pending_exec_idx",
+            ),
+        ]
+
+    def __str__(self) -> str:
+        return f"{self.scheduled_task.name} [{self.status}]"

django_periodic_tasks/registry.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from django_periodic_tasks.cron import validate_cron_expression
+
+
+@dataclass(frozen=True)
+class ScheduleEntry:
+    """An immutable record describing a single scheduled task.
+
+    Each entry holds the task object, its cron schedule, and the options that
+    will be forwarded to ``task.using()`` / ``task.enqueue()`` at execution time.
+
+    Attributes:
+        task: The django-tasks ``Task`` object to enqueue.
+        cron_expression: A standard 5-field cron expression (e.g. ``"*/15 * * * *"``).
+        name: Unique name for this schedule (used as the DB primary key).
+        timezone: IANA timezone name used for cron matching (default ``"UTC"``).
+        args: Positional arguments passed to ``task.enqueue()``.
+        kwargs: Keyword arguments passed to ``task.enqueue()``.
+        queue_name: Task queue name passed to ``task.using()``.
+        priority: Task priority passed to ``task.using()``.
+        backend: Task backend name passed to ``task.using()``.
+    """
+
+    task: Any
+    cron_expression: str
+    name: str
+    timezone: str = "UTC"
+    args: list[Any] = field(default_factory=list)
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    queue_name: str = "default"
+    priority: int = 0
+    backend: str = "default"
+
+
+class ScheduleRegistry:
+    """Singleton registry for code-defined schedules."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, ScheduleEntry] = {}
+
+    def register(
+        self,
+        task: Any,
+        *,
+        cron: str,
+        name: str,
+        timezone: str = "UTC",
+        args: list[Any] | None = None,
+        kwargs: dict[str, Any] | None = None,
+        queue_name: str = "default",
+        priority: int = 0,
+        backend: str = "default",
+    ) -> None:
+        """Register a task with the given cron schedule.
+
+        Args:
+            task: A django-tasks ``Task`` object.
+            cron: A 5-field cron expression (e.g. ``"0 */6 * * *"``).
+            name: Unique name for this schedule.
+            timezone: IANA timezone for cron matching (default ``"UTC"``).
+            args: Positional arguments for ``task.enqueue()``.
+            kwargs: Keyword arguments for ``task.enqueue()``.
+            queue_name: Queue name for ``task.using()``.
+            priority: Priority for ``task.using()``.
+            backend: Backend name for ``task.using()``.
+
+        Raises:
+            ValueError: If the cron expression is invalid or the name is already registered.
+        """
+        if not validate_cron_expression(cron):
+            raise ValueError(f"Invalid cron expression: {cron}")
+        if name in self._entries:
+            raise ValueError(f"Schedule with name '{name}' is already registered")
+        self._entries[name] = ScheduleEntry(
+            task=task,
+            cron_expression=cron,
+            name=name,
+            timezone=timezone,
+            args=args or [],
+            kwargs=kwargs or {},
+            queue_name=queue_name,
+            priority=priority,
+            backend=backend,
+        )
+
+    def get_entries(self) -> dict[str, ScheduleEntry]:
+        """Return a copy of all registered schedule entries, keyed by name."""
+        return dict(self._entries)
+
+
+schedule_registry = ScheduleRegistry()
+
+
+def scheduled_task(
+    *,
+    cron: str,
+    name: str | None = None,
+    registry: ScheduleRegistry | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Decorator that registers a django-tasks ``Task`` with the schedule registry.
+
+    Apply this decorator **after** ``@task()`` to register the task for periodic
+    execution::
+
+        @scheduled_task(cron="*/5 * * * *")
+        @task()
+        def send_digest(user_id: int) -> None:
+            ...
+
+    Args:
+        cron: A 5-field cron expression (e.g. ``"0 8 * * 1-5"``).
+        name: Unique schedule name. Defaults to the task's ``module_path``.
+        registry: An alternate ``ScheduleRegistry`` instance (defaults to the
+            global ``schedule_registry``).
+        **kwargs: Extra options forwarded to
+            :meth:`ScheduleRegistry.register` (``timezone``, ``args``,
+            ``kwargs``, ``queue_name``, ``priority``, ``backend``).
+    """
+    target_registry = registry or schedule_registry
+
+    def decorator(task_obj: Any) -> Any:
+        actual_name = name or task_obj.module_path
+        target_registry.register(task_obj, cron=cron, name=actual_name, **kwargs)
+        return task_obj
+
+    return decorator

django_periodic_tasks/scheduler.py

@@ -0,0 +1,200 @@
+from datetime import timedelta
+import logging
+import threading
+
+from django.db import transaction
+from django.db.models import F
+from django.utils import timezone
+
+from django_periodic_tasks.cron import compute_next_run_at
+from django_periodic_tasks.models import ScheduledTask, TaskExecution
+from django_periodic_tasks.sync import sync_code_schedules
+from django_periodic_tasks.task_resolver import resolve_task
+
+logger = logging.getLogger(__name__)
+
+
+class PeriodicTaskScheduler(threading.Thread):
+    """Daemon thread that periodically enqueues due scheduled tasks.
+
+    On each tick the scheduler:
+
+    1. Queries :class:`~django_periodic_tasks.models.ScheduledTask` for rows
+       whose ``next_run_at ≤ now`` and ``enabled = True``.
+    2. Locks those rows with ``SELECT FOR UPDATE SKIP LOCKED`` so multiple
+       scheduler instances can run safely in parallel.
+    3. Resolves each task path to a django-tasks ``Task`` object and calls
+       ``task.using(...).enqueue(...)``.
+    4. Updates ``last_run_at``, ``next_run_at``, and ``total_run_count``.
+
+    Args:
+        interval: Seconds between scheduler ticks (default ``15``).
+    """
+
+    daemon = True
+
+    def __init__(self, interval: int = 15) -> None:
+        if interval <= 0:
+            raise ValueError(f"interval must be positive, got {interval}")
+        super().__init__(name="periodic-task-scheduler")
+        self.interval = interval
+        self._stop_event = threading.Event()
+
+    def run(self) -> None:
+        """Start the scheduler loop.
+
+        Syncs code-defined schedules to the database, then enters the
+        tick-sleep loop until :meth:`stop` is called.
+        """
+        logger.info("Periodic task scheduler starting (interval=%ds)", self.interval)
+        try:
+            sync_code_schedules()
+        except Exception:
+            logger.exception("Failed to sync code schedules on startup")
+        while not self._stop_event.is_set():
+            try:
+                self.tick()
+            except Exception:
+                logger.exception("Scheduler tick failed")
+            self._stop_event.wait(self.interval)
+        logger.info("Periodic task scheduler stopped")
+
+    def tick(self) -> None:
+        """Single scheduler tick: find and enqueue due tasks.
+
+        All due tasks are locked with ``SELECT FOR UPDATE SKIP LOCKED`` for the
+        duration of the tick so that concurrent scheduler instances never
+        enqueue the same task twice.
+        """
+        try:
+            self._cleanup_stale_executions()
+        except Exception:
+            logger.exception("Stale execution cleanup failed")
+
+        try:
+            self._delete_old_executions()
+        except Exception:
+            logger.exception("Old execution cleanup failed")
+
+        now = timezone.now()
+
+        with transaction.atomic():
+            due_tasks = list(
+                ScheduledTask.objects.filter(
+                    enabled=True,
+                    next_run_at__lte=now,
+                ).select_for_update(skip_locked=True)
+            )
+
+            for st in due_tasks:
+                try:
+                    with transaction.atomic():
+                        self._process_task(st)
+                except Exception:
+                    logger.exception("Failed to enqueue scheduled task id=%s", st.id)
+                    try:
+                        st.next_run_at = compute_next_run_at(st.cron_expression, st.timezone)
+                        st.save(update_fields=["next_run_at"])
+                    except Exception:
+                        logger.exception("Failed to advance next_run_at for task id=%s", st.id)
+
+    def _process_task(self, st: ScheduledTask) -> None:
+        task_obj = resolve_task(st.task_path)
+        configured = task_obj.using(
+            queue_name=st.queue_name,
+            priority=st.priority,
+            backend=st.backend,
+        )
+
+        is_exactly_once = getattr(task_obj.func, "_exactly_once", False)
+
+        if is_exactly_once:
+            execution = TaskExecution.objects.create(scheduled_task=st)
+            enqueue_kwargs = {**st.kwargs, "_periodic_tasks_execution_id": str(execution.id)}
+
+            def _deferred_enqueue() -> None:
+                configured.enqueue(*st.args, **enqueue_kwargs)
+
+            transaction.on_commit(_deferred_enqueue)
+        else:
+            configured.enqueue(*st.args, **st.kwargs)
+
+        st.last_run_at = timezone.now()
+        st.next_run_at = compute_next_run_at(st.cron_expression, st.timezone)
+        st.total_run_count = F("total_run_count") + 1
+        st.save(update_fields=["last_run_at", "next_run_at", "total_run_count"])
+
+        logger.info("Enqueued scheduled task: %s", st.name)
+
+    def _cleanup_stale_executions(self) -> None:
+        """Re-enqueue stale PENDING TaskExecutions that were never delivered.
+
+        A TaskExecution can become stale if the scheduler committed the row but
+        the ``on_commit`` callback that enqueues the task never fired (e.g. the
+        process crashed, the connection was reset, etc.).
+
+        Direct enqueue (not ``on_commit``) is safe here because the
+        TaskExecution row was committed in a prior tick's transaction and is
+        already visible to workers.
+        """
+        threshold = timezone.now() - timedelta(seconds=max(60, 2 * self.interval))
+
+        with transaction.atomic():
+            stale = list(
+                TaskExecution.objects.filter(
+                    status=TaskExecution.Status.PENDING,
+                    created_at__lt=threshold,
+                    scheduled_task__enabled=True,
+                )
+                .select_related("scheduled_task")
+                .select_for_update(skip_locked=True)
+            )
+
+            for execution in stale:
+                try:
+                    st = execution.scheduled_task
+                    task_obj = resolve_task(st.task_path)
+                    configured = task_obj.using(
+                        queue_name=st.queue_name,
+                        priority=st.priority,
+                        backend=st.backend,
+                    )
+                    enqueue_kwargs = {
+                        **st.kwargs,
+                        "_periodic_tasks_execution_id": str(execution.id),
+                    }
+                    configured.enqueue(*st.args, **enqueue_kwargs)
+                    logger.info(
+                        "Re-enqueued stale execution %s for task %s",
+                        execution.id,
+                        st.name,
+                    )
+                except Exception:
+                    logger.exception(
+                        "Failed to re-enqueue stale execution %s",
+                        execution.id,
+                    )
+
+    def _delete_old_executions(self) -> None:
+        """Bulk-delete non-PENDING TaskExecution rows older than 24 hours.
+
+        COMPLETED rows have no ongoing purpose once workers have finished
+        processing them.  PENDING rows are preserved because they may still be
+        awaiting delivery or re-enqueue by stale cleanup.
+        """
+        threshold = timezone.now() - timedelta(hours=24)
+        deleted, _ = (
+            TaskExecution.objects.filter(
+                created_at__lt=threshold,
+            )
+            .exclude(
+                status=TaskExecution.Status.PENDING,
+            )
+            .delete()
+        )
+        if deleted:
+            logger.info("Deleted %d old task execution(s)", deleted)
+
+    def stop(self) -> None:
+        """Signal the scheduler to stop after the current tick completes."""
+        self._stop_event.set()

django_periodic_tasks/sync.py

@@ -0,0 +1,57 @@
+import logging
+
+from django.db import transaction
+
+from django_periodic_tasks.models import ScheduledTask
+from django_periodic_tasks.registry import ScheduleRegistry, schedule_registry
+
+logger = logging.getLogger(__name__)
+
+
+def sync_code_schedules(registry: ScheduleRegistry | None = None) -> None:
+    """Sync in-memory registry to ScheduledTask DB records.
+
+    - Creates new ScheduledTask for new code entries
+    - Updates cron_expression/task_path/options if changed
+    - Disables stale code entries (in registry previously, now removed)
+    - Never touches source=DATABASE records
+    """
+    target_registry = registry or schedule_registry
+    entries = target_registry.get_entries()
+
+    with transaction.atomic():
+        # Create or update code entries
+        seen_names: set[str] = set()
+        for name, entry in entries.items():
+            seen_names.add(name)
+            defaults = {
+                "task_path": entry.task.module_path,
+                "cron_expression": entry.cron_expression,
+                "timezone": entry.timezone,
+                "args": entry.args,
+                "kwargs": entry.kwargs,
+                "queue_name": entry.queue_name,
+                "priority": entry.priority,
+                "backend": entry.backend,
+                "source": ScheduledTask.Source.CODE,
+                "enabled": True,
+                "next_run_at": None,
+            }
+            obj, created = ScheduledTask.objects.update_or_create(
+                name=name,
+                defaults=defaults,
+            )
+            if created:
+                logger.info("Created code schedule: %s", name)
+            else:
+                logger.debug("Updated code schedule: %s", name)
+
+        # Disable code-defined entries that are no longer in the registry
+        stale = ScheduledTask.objects.filter(
+            source=ScheduledTask.Source.CODE,
+            enabled=True,
+        ).exclude(name__in=seen_names)
+
+        stale_count = stale.update(enabled=False, next_run_at=None)
+        if stale_count:
+            logger.info("Disabled %d stale code schedule(s)", stale_count)

django_periodic_tasks/task_resolver.py

@@ -0,0 +1,22 @@
+from importlib import import_module
+from typing import Any
+
+from django_tasks.base import Task
+
+
+def resolve_task(task_path: str) -> Task[..., Any]:
+    """Import and return a django-tasks Task object from its dotted module path.
+
+    The task_path should be a dotted path like "myapp.tasks.my_task".
+    """
+    module_path, _, attr_name = task_path.rpartition(".")
+    if not module_path:
+        raise ImportError(f"Invalid task path: {task_path}")
+
+    module = import_module(module_path)
+    obj = getattr(module, attr_name)
+
+    if not isinstance(obj, Task):
+        raise TypeError(f"{task_path} is not a django-tasks Task instance (got {type(obj).__name__})")
+
+    return obj

django_periodic_tasks-0.1.0a3.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: django-periodic-tasks
+Version: 0.1.0a3
+Summary: Periodic/cron task scheduling for django-tasks. Backend-agnostic replacement for celery-beat.
+Project-URL: Homepage, https://gitlab.com/thelabnyc/django-periodic-tasks
+Project-URL: Repository, https://gitlab.com/thelabnyc/django-periodic-tasks
+Author-email: thelab <thelabdev@thelab.co>
+License: ISC
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: croniter>=1.0
+Requires-Dist: django-tasks>=0.7
+Requires-Dist: django>=5.2
+Provides-Extra: rq
+Requires-Dist: django-rq; extra == 'rq'
+Requires-Dist: django-tasks[rq]; extra == 'rq'
+Description-Content-Type: text/markdown
+
+# django-periodic-tasks
+
+Periodic/cron task scheduling for [django-tasks](https://github.com/RealOrangeOne/django-tasks). Backend-agnostic replacement for celery-beat + django-celery-beat.
+
+## Installation
+
+```bash
+pip install django-periodic-tasks
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_periodic_tasks",
+]
+```
+
+## Usage
+
+### Define scheduled tasks
+
+```python
+from django_tasks import task
+from django_periodic_tasks import scheduled_task
+
+@scheduled_task(cron="0 5 * * *", name="daily-report")
+@task()
+def daily_report() -> None:
+    ...
+```
+
+### Run the scheduler
+
+Enable the autostart setting so the scheduler runs as a daemon thread inside your Django process:
+
+```python
+# settings.py
+PERIODIC_TASKS_AUTOSTART = True
+```
+
+Or run it as a standalone process:
+
+```bash
+python manage.py run_scheduler
+```

django_periodic_tasks-0.1.0a3.dist-info/RECORD

@@ -0,0 +1,21 @@
+django_periodic_tasks/__init__.py,sha256=5cgybxXwf98hZnNAOX6DYHeeYuwzC9jgwJZU0XGUOeQ,316
+django_periodic_tasks/admin.py,sha256=87o6_Z-f79ZhdAoTpFWdVhV9rZQQb-k17FGR_phHPuw,2373
+django_periodic_tasks/apps.py,sha256=KezRzFjYSleKustuoiG0KhFy5N2uUgmi8qrx5bqcN6k,1159
+django_periodic_tasks/cron.py,sha256=PHVlX_YyzALgpYYBqWkKdvEm0uE0lnBTM5TUDcYLfS0,1332
+django_periodic_tasks/decorators.py,sha256=GhkNUqlPubUj6ZhS4Nf1FsTUMZaihNyD8wrTFOzbiKU,2024
+django_periodic_tasks/models.py,sha256=qJEwSnBJ-L54qr0Dl9gvHWZ0h6k2H6x5nMS7f9O2L3k,5199
+django_periodic_tasks/registry.py,sha256=sS897SBu1RP7JVQDNkMZQfahhCU_9ZpV6qHmdwvKiik,4532
+django_periodic_tasks/scheduler.py,sha256=zl-LsAmO9Io2rZG1P4WrG-is3yGxAX0430Dmd0zVEBs,7600
+django_periodic_tasks/sync.py,sha256=EfvcZlP5-199uxIMwJRdCnXzObQohHLYR4W819d5i5k,2118
+django_periodic_tasks/task_resolver.py,sha256=OMlH3s9b4rerLOItm3KdazWLZPiSTbjHTZlWpd9qt_8,684
+django_periodic_tasks/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_periodic_tasks/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_periodic_tasks/management/commands/run_scheduler.py,sha256=kCVBi10KLHb_8iqizT3mlfW_cuQOLpsrF-VowdXkkAM,2194
+django_periodic_tasks/migrations/0001_initial.py,sha256=h_AfdKIG9f-XmDZiqR_zzgtr5Mcy8CdbFrNUQOzSePE,1873
+django_periodic_tasks/migrations/0002_remove_redundant_next_run_at_db_index.py,sha256=RPWdcpU7wkQd-47oLbr14q6JgfyaqfOkys2o8KmocoU,412
+django_periodic_tasks/migrations/0003_add_task_execution.py,sha256=3cZrhQmBR2oIaIkTeMYGoztuPyO6rdh84wOlex5fUzs,1235
+django_periodic_tasks/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_periodic_tasks-0.1.0a3.dist-info/METADATA,sha256=pee1VhsmKl-W0Ani-ynwztXEBkXECXx3ieuh7EIzBtE,1505
+django_periodic_tasks-0.1.0a3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+django_periodic_tasks-0.1.0a3.dist-info/licenses/LICENSE,sha256=XdK5EYewCzTpCGUgHO6aUH6TlvzAdvQrtv1Xacd7OIQ,738
+django_periodic_tasks-0.1.0a3.dist-info/RECORD,,

django_periodic_tasks-0.1.0a3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_periodic_tasks-0.1.0a3.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, thelab
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.