django-periodic-tasks 0.1.0a3__tar.gz → 0.1.0a5__tar.gz

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.1.0a5 (2026-02-05)
+
+### Fix
+
+- replace all Any usage with proper generics and protocols
+
+## v0.1.0a4 (2026-02-05)
+
+### Fix
+
+- add missing py.typed file
+
 ## v0.1.0a3 (2026-02-05)
 
 ## v0.1.0a2 (2026-02-05)

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-periodic-tasks
-Version: 0.1.0a3
+Version: 0.1.0a5
 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

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/django_periodic_tasks/admin.py

@@ -1,5 +1,3 @@
-from typing import Any
-
 from django.contrib import admin
 from django.http import HttpRequest
 
@@ -62,7 +60,7 @@ class ScheduledTaskAdmin(admin.ModelAdmin[ScheduledTask]):
     def has_delete_permission(
         self,
         request: HttpRequest,
-        obj: Any = None,
+        obj: ScheduledTask | None = None,
     ) -> bool:
         if obj is not None and obj.source == ScheduledTask.Source.CODE:
             return False
@@ -79,8 +77,8 @@ class TaskExecutionAdmin(admin.ModelAdmin[TaskExecution]):
     def has_add_permission(self, request: HttpRequest) -> bool:
         return False
 
-    def has_change_permission(self, request: HttpRequest, obj: Any = None) -> bool:
+    def has_change_permission(self, request: HttpRequest, obj: TaskExecution | None = None) -> bool:
         return False
 
-    def has_delete_permission(self, request: HttpRequest, obj: Any = None) -> bool:
+    def has_delete_permission(self, request: HttpRequest, obj: TaskExecution | None = None) -> bool:
         return False

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/django_periodic_tasks/decorators.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Any
 import functools
 import logging
 
@@ -10,8 +9,15 @@ from django.utils import timezone
 
 logger = logging.getLogger(__name__)
 
+_exactly_once_funcs: set[Callable[..., object]] = set()
 
-def exactly_once(func: Callable[..., Any]) -> Callable[..., Any]:
+
+def is_exactly_once(func: object) -> bool:
+    """Check whether a function was decorated with ``@exactly_once``."""
+    return func in _exactly_once_funcs
+
+
+def exactly_once[R](func: Callable[..., R]) -> Callable[..., R | None]:
     """Decorator ensuring a scheduled task runs at most once per invocation.
 
     When the scheduler creates a ``TaskExecution`` row and passes its ID via
@@ -27,12 +33,14 @@ def exactly_once(func: Callable[..., Any]) -> Callable[..., Any]:
     """
 
     @functools.wraps(func)
-    def wrapper(*args: Any, **kwargs: Any) -> Any:
-        execution_id: str | None = kwargs.pop("_periodic_tasks_execution_id", None)
+    def wrapper(*args: object, **kwargs: object) -> R | None:
+        raw_execution_id = kwargs.pop("_periodic_tasks_execution_id", None)
 
-        if execution_id is None:
+        if raw_execution_id is None:
             return func(*args, **kwargs)
 
+        execution_id = str(raw_execution_id)
+
         from django_periodic_tasks.models import (
             TaskExecution,  # Avoid AppRegistryNotReady
         )
@@ -55,5 +63,5 @@ def exactly_once(func: Callable[..., Any]) -> Callable[..., Any]:
 
         return result
 
-    wrapper._exactly_once = True  # type: ignore[attr-defined]
+    _exactly_once_funcs.add(wrapper)
     return wrapper

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/django_periodic_tasks/models.py

@@ -1,9 +1,10 @@
-from typing import Any
+from collections.abc import Iterable
 from zoneinfo import ZoneInfo
 import uuid
 
 from django.core.exceptions import ValidationError
 from django.db import models
+from django.db.models.base import ModelBase
 
 from django_periodic_tasks.cron import compute_next_run_at, validate_cron_expression
 
@@ -87,7 +88,14 @@ class ScheduledTask(models.Model):
         if errors:
             raise ValidationError(errors)
 
-    def save(self, *args: Any, **kwargs: Any) -> None:
+    def save(
+        self,
+        *,
+        force_insert: bool | tuple[ModelBase, ...] = False,
+        force_update: bool = False,
+        using: str | None = None,
+        update_fields: Iterable[str] | None = None,
+    ) -> None:
         original_next_run_at = self.next_run_at
 
         if not self.enabled:
@@ -95,17 +103,22 @@ class ScheduledTask(models.Model):
         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)
+        effective_update_fields: list[str] | None = None
+        if update_fields is not None:
+            fields = set(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)
+            effective_update_fields = list(fields)
+
+        super().save(
+            force_insert=force_insert,
+            force_update=force_update,
+            using=using,
+            update_fields=effective_update_fields,
+        )
 
 
 class TaskExecution(models.Model):

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/django_periodic_tasks/registry.py

@@ -1,11 +1,26 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Protocol
 
 from django_periodic_tasks.cron import validate_cron_expression
 
 
+class TaskLike(Protocol):
+    """Structural type describing the django-tasks ``Task`` interface.
+
+    Used instead of ``Task[..., object]`` because ``Task`` is invariant in its
+    type parameters — a concrete ``Task[[str], None]`` would not satisfy
+    ``Task[..., object]``.  This protocol captures just the attributes the
+    registry needs, so any ``Task[P, T]`` matches regardless of its concrete
+    parameter and return types.
+    """
+
+    @property
+    def module_path(self) -> str: ...
+
+
 @dataclass(frozen=True)
 class ScheduleEntry:
     """An immutable record describing a single scheduled task.
@@ -25,12 +40,12 @@ class ScheduleEntry:
         backend: Task backend name passed to ``task.using()``.
     """
 
-    task: Any
+    task: TaskLike
     cron_expression: str
     name: str
     timezone: str = "UTC"
-    args: list[Any] = field(default_factory=list)
-    kwargs: dict[str, Any] = field(default_factory=dict)
+    args: list[object] = field(default_factory=list)
+    kwargs: dict[str, object] = field(default_factory=dict)
     queue_name: str = "default"
     priority: int = 0
     backend: str = "default"
@@ -44,13 +59,13 @@ class ScheduleRegistry:
 
     def register(
         self,
-        task: Any,
+        task: TaskLike,
         *,
         cron: str,
         name: str,
         timezone: str = "UTC",
-        args: list[Any] | None = None,
-        kwargs: dict[str, Any] | None = None,
+        args: list[object] | None = None,
+        kwargs: dict[str, object] | None = None,
         queue_name: str = "default",
         priority: int = 0,
         backend: str = "default",
@@ -95,13 +110,18 @@ class ScheduleRegistry:
 schedule_registry = ScheduleRegistry()
 
 
-def scheduled_task(
+def scheduled_task[T: TaskLike](
     *,
     cron: str,
     name: str | None = None,
     registry: ScheduleRegistry | None = None,
-    **kwargs: Any,
-) -> Any:
+    timezone: str = "UTC",
+    args: list[object] | None = None,
+    kwargs: dict[str, object] | None = None,
+    queue_name: str = "default",
+    priority: int = 0,
+    backend: str = "default",
+) -> Callable[[T], T]:
     """Decorator that registers a django-tasks ``Task`` with the schedule registry.
 
     Apply this decorator **after** ``@task()`` to register the task for periodic
@@ -117,15 +137,28 @@ def scheduled_task(
         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``).
+        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()``.
     """
     target_registry = registry or schedule_registry
 
-    def decorator(task_obj: Any) -> Any:
+    def decorator(task_obj: T) -> T:
         actual_name = name or task_obj.module_path
-        target_registry.register(task_obj, cron=cron, name=actual_name, **kwargs)
+        target_registry.register(
+            task_obj,
+            cron=cron,
+            name=actual_name,
+            timezone=timezone,
+            args=args,
+            kwargs=kwargs,
+            queue_name=queue_name,
+            priority=priority,
+            backend=backend,
+        )
         return task_obj
 
     return decorator

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/django_periodic_tasks/scheduler.py

@@ -7,6 +7,7 @@ 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.decorators import is_exactly_once
 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
@@ -106,9 +107,7 @@ class PeriodicTaskScheduler(threading.Thread):
             backend=st.backend,
         )
 
-        is_exactly_once = getattr(task_obj.func, "_exactly_once", False)
-
-        if is_exactly_once:
+        if is_exactly_once(task_obj.func):
             execution = TaskExecution.objects.create(scheduled_task=st)
             enqueue_kwargs = {**st.kwargs, "_periodic_tasks_execution_id": str(execution.id)}
 

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/django_periodic_tasks/task_resolver.py

@@ -1,10 +1,9 @@
 from importlib import import_module
-from typing import Any
 
 from django_tasks.base import Task
 
 
-def resolve_task(task_path: str) -> Task[..., Any]:
+def resolve_task(task_path: str) -> Task[..., object]:
     """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".

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/public/api/registry.html

@@ -831,7 +831,7 @@
 <h1 id="registry">Registry<a class="headerlink" href="#registry" title="Permanent link">&para;</a></h1>
 <h2 id="scheduled_task">scheduled_task<a class="headerlink" href="#scheduled_task" title="Permanent link">&para;</a></h2>
 <div class="autodoc">
-<div class="autodoc-signature"><code>django_periodic_tasks.registry.<strong>scheduled_task</strong></code><span class="autodoc-punctuation">(</span><em class="autodoc-param">*</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">cron</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">name=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">registry=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">**kwargs</em><span class="autodoc-punctuation">)</span></div>
+<div class="autodoc-signature"><code>django_periodic_tasks.registry.<strong>scheduled_task</strong></code><span class="autodoc-punctuation">(</span><em class="autodoc-param">*</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">cron</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">name=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">registry=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">timezone=&rsquo;UTC&rsquo;</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">args=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">kwargs=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">queue_name=&rsquo;default&rsquo;</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">priority=0</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">backend=&rsquo;default&rsquo;</em><span class="autodoc-punctuation">)</span></div>
 <div class="autodoc-docstring"><p>Decorator that registers a django-tasks <code>Task</code> with the schedule registry.</p>
 <p>Apply this decorator <strong>after</strong> <code>@task()</code> to register the task for periodic
 execution::</p>
@@ -846,9 +846,12 @@ execution::</p>
     name: Unique schedule name. Defaults to the task&rsquo;s <code>module_path</code>.
     registry: An alternate <code>ScheduleRegistry</code> instance (defaults to the
         global <code>schedule_registry</code>).
-    **kwargs: Extra options forwarded to
-        :meth:<code>ScheduleRegistry.register</code> (<code>timezone</code>, <code>args</code>,
-        <code>kwargs</code>, <code>queue_name</code>, <code>priority</code>, <code>backend</code>).</p></div>
+    timezone: IANA timezone for cron matching (default <code>&ldquo;UTC&rdquo;</code>).
+    args: Positional arguments for <code>task.enqueue()</code>.
+    kwargs: Keyword arguments for <code>task.enqueue()</code>.
+    queue_name: Queue name for <code>task.using()</code>.
+    priority: Priority for <code>task.using()</code>.
+    backend: Backend name for <code>task.using()</code>.</p></div>
 </div>
 <h2 id="scheduleentry">ScheduleEntry<a class="headerlink" href="#scheduleentry" title="Permanent link">&para;</a></h2>
 <div class="autodoc">

django_periodic_tasks-0.1.0a5/public/search/search_index.json

@@ -0,0 +1 @@
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"index.html","title":"django-periodic-tasks","text":"<p>Periodic/cron task scheduling for django-tasks. A backend-agnostic replacement for celery-beat.</p>"},{"location":"index.html#features","title":"Features","text":"<ul> <li>Cron-based scheduling \u2014 Standard 5-field cron expressions with timezone support.</li> <li>Code-defined schedules \u2014 Declare schedules in Python with the <code>@scheduled_task</code> decorator; they sync to the database automatically.</li> <li>Database-defined schedules \u2014 Create and manage schedules through the Django admin for runtime flexibility.</li> <li>Exactly-once execution \u2014 Optional <code>@exactly_once</code> decorator guarantees a task runs at most once per scheduled invocation, even with non-transactional backends.</li> <li>Multi-worker safe \u2014 Uses <code>SELECT FOR UPDATE SKIP LOCKED</code> so multiple scheduler processes never double-enqueue the same task.</li> <li>Backend-agnostic \u2014 Works with any django-tasks backend (database, RQ, etc.).</li> </ul>"},{"location":"index.html#installation","title":"Installation","text":"<pre><code>pip install django-periodic-tasks\n</code></pre> <p>Add to your <code>INSTALLED_APPS</code> and run migrations:</p> <pre><code>INSTALLED_APPS = [\n    # ...\n    \"django_tasks\",\n    \"django_periodic_tasks\",\n    # ...\n]\n</code></pre> <pre><code>python manage.py migrate\n</code></pre>"},{"location":"index.html#next-steps","title":"Next Steps","text":"<p>{nav}</p> <code>sandbox.settings_docgen.setup</code>"},{"location":"api/index.html","title":"API Reference","text":"<p>{nav}</p>"},{"location":"api/decorators.html","title":"Decorators","text":""},{"location":"api/decorators.html#exactly_once","title":"exactly_once","text":"<code>django_periodic_tasks.decorators.exactly_once</code>(func) <p>Decorator ensuring a scheduled task runs at most once per invocation.</p> <p>When the scheduler creates a <code>TaskExecution</code> row and passes its ID via the <code>_periodic_tasks_execution_id</code> keyword argument, this decorator will:</p> <ol> <li>Pop <code>_periodic_tasks_execution_id</code> from kwargs.</li> <li>Lock the <code>TaskExecution</code> row with <code>SELECT FOR UPDATE</code>.</li> <li>Run the wrapped function only if the row\u2019s status is <code>PENDING</code>.</li> <li>Mark the row <code>COMPLETED</code> on success.</li> </ol> <p>If <code>_periodic_tasks_execution_id</code> is absent (e.g. manual invocation), the wrapped function runs normally without any execution-permit logic.</p>"},{"location":"api/models.html","title":"Models","text":""},{"location":"api/models.html#scheduledtask","title":"ScheduledTask","text":"class <code>django_periodic_tasks.models.ScheduledTask</code>(*args, **kwargs) <p>A persistent record of a periodic task and its cron schedule.</p> <p>Each row represents one scheduled task. The scheduler queries this table on every tick to find tasks whose <code>next_run_at</code> has passed, then enqueues them via django-tasks.</p> <p>Tasks can originate from two sources (see :class:<code>Source</code>):</p> <ul> <li>Code-defined \u2014 registered with :func:<code>~django_periodic_tasks.registry.scheduled_task</code>   and synced to the database on scheduler startup.</li> <li>Database-defined \u2014 created manually through the Django admin.</li> </ul>"},{"location":"api/models.html#scheduledtasksource","title":"ScheduledTask.Source","text":"<p>Where a scheduled task definition comes from.</p> <ul> <li><code>CODE</code> \u2014 Managed by the codebase and synced automatically on scheduler startup.</li> <li><code>DATABASE</code> \u2014 Managed by operators through the Django admin.</li> </ul>"},{"location":"api/models.html#taskexecution","title":"TaskExecution","text":"class <code>django_periodic_tasks.models.TaskExecution</code>(*args, **kwargs) <p>An execution permit for a single scheduled task invocation.</p> <p>Used by the <code>@exactly_once</code> decorator to ensure a task runs at most once per scheduled invocation, even with non-transactional backends (e.g. Redis/RQ).</p>"},{"location":"api/models.html#taskexecutionstatus","title":"TaskExecution.Status","text":"<p>The lifecycle status of an execution permit.</p> <ul> <li><code>PENDING</code> \u2014 Created by the scheduler, awaiting worker pickup.</li> <li><code>COMPLETED</code> \u2014 The <code>@exactly_once</code> decorator ran the task successfully.</li> </ul>"},{"location":"api/registry.html","title":"Registry","text":""},{"location":"api/registry.html#scheduled_task","title":"scheduled_task","text":"<code>django_periodic_tasks.registry.scheduled_task</code>(*, cron, name=None, registry=None, timezone=\u2019UTC\u2019, args=None, kwargs=None, queue_name=\u2019default\u2019, priority=0, backend=\u2019default\u2019) <p>Decorator that registers a django-tasks <code>Task</code> with the schedule registry.</p> <p>Apply this decorator after <code>@task()</code> to register the task for periodic execution::</p> <pre><code>@scheduled_task(cron=\"/5 * * * \")\n@task()\ndef send_digest(user_id: int) -&gt; None:\n    \u2026\n</code></pre> <p>Args:     cron: A 5-field cron expression (e.g. <code>\u201c0 8 * * 1-5\u201d</code>).     name: Unique schedule name. Defaults to the task\u2019s <code>module_path</code>.     registry: An alternate <code>ScheduleRegistry</code> instance (defaults to the         global <code>schedule_registry</code>).     timezone: IANA timezone for cron matching (default <code>\u201cUTC\u201d</code>).     args: Positional arguments for <code>task.enqueue()</code>.     kwargs: Keyword arguments for <code>task.enqueue()</code>.     queue_name: Queue name for <code>task.using()</code>.     priority: Priority for <code>task.using()</code>.     backend: Backend name for <code>task.using()</code>.</p>"},{"location":"api/registry.html#scheduleentry","title":"ScheduleEntry","text":"class <code>django_periodic_tasks.registry.ScheduleEntry</code>(task, cron_expression, name, timezone=\u2019UTC\u2019, args=, kwargs=, queue_name=\u2019default\u2019, priority=0, backend=\u2019default\u2019) <p>An immutable record describing a single scheduled task.</p> <p>Each entry holds the task object, its cron schedule, and the options that will be forwarded to <code>task.using()</code> / <code>task.enqueue()</code> at execution time.</p> <p>Attributes:     task: The django-tasks <code>Task</code> object to enqueue.     cron_expression: A standard 5-field cron expression (e.g. <code>\u201c/15 * * * \u201c</code>).     name: Unique name for this schedule (used as the DB primary key).     timezone: IANA timezone name used for cron matching (default <code>\u201cUTC\u201d</code>).     args: Positional arguments passed to <code>task.enqueue()</code>.     kwargs: Keyword arguments passed to <code>task.enqueue()</code>.     queue_name: Task queue name passed to <code>task.using()</code>.     priority: Task priority passed to <code>task.using()</code>.     backend: Task backend name passed to <code>task.using()</code>.</p>"},{"location":"api/registry.html#scheduleregistry","title":"ScheduleRegistry","text":"class <code>django_periodic_tasks.registry.ScheduleRegistry</code>() <p>Singleton registry for code-defined schedules.</p> <code>get_entries</code>(self) <p>Return a copy of all registered schedule entries, keyed by name.</p> <code>register</code>(self, task, *, cron, name, timezone=\u2019UTC\u2019, args=None, kwargs=None, queue_name=\u2019default\u2019, priority=0, backend=\u2019default\u2019) <p>Register a task with the given cron schedule.</p> <p>Args:     task: A django-tasks <code>Task</code> object.     cron: A 5-field cron expression (e.g. <code>\u201c0 /6 * * \u201c</code>).     name: Unique name for this schedule.     timezone: IANA timezone for cron matching (default <code>\u201cUTC\u201d</code>).     args: Positional arguments for <code>task.enqueue()</code>.     kwargs: Keyword arguments for <code>task.enqueue()</code>.     queue_name: Queue name for <code>task.using()</code>.     priority: Priority for <code>task.using()</code>.     backend: Backend name for <code>task.using()</code>.</p> <p>Raises:     ValueError: If the cron expression is invalid or the name is already registered.</p>"},{"location":"api/settings.html","title":"Settings","text":"<p>django-periodic-tasks is configured through Django settings.</p>"},{"location":"api/settings.html#periodic_tasks_autostart","title":"PERIODIC_TASKS_AUTOSTART","text":"Type <code>bool</code> Default <code>False</code> <p>When <code>True</code>, the scheduler starts automatically as a daemon thread during <code>AppConfig.ready()</code>. Useful for development and simple single-process deployments.</p> <pre><code>PERIODIC_TASKS_AUTOSTART = True\n</code></pre>"},{"location":"api/settings.html#periodic_tasks_scheduler_interval","title":"PERIODIC_TASKS_SCHEDULER_INTERVAL","text":"Type <code>int</code> Default <code>15</code> <p>Seconds between scheduler ticks. On each tick the scheduler queries the database for due tasks and enqueues them.</p> <pre><code>PERIODIC_TASKS_SCHEDULER_INTERVAL = 30  # check every 30 seconds\n</code></pre> <p>Lower values mean tasks are enqueued closer to their scheduled time, but increase database load. The default of 15 seconds is a good balance for most applications.</p>"},{"location":"guides/index.html","title":"Guides","text":"<p>{nav}</p>"},{"location":"guides/defining-schedules.html","title":"Defining Schedules","text":"<p>django-periodic-tasks supports two ways to define scheduled tasks: in code (version-controlled, deployed with your app) and in the database (managed at runtime through the Django admin).</p>"},{"location":"guides/defining-schedules.html#code-defined-schedules","title":"Code-Defined Schedules","text":"<p>Use the <code>@scheduled_task</code> decorator to register a django-tasks <code>Task</code> for periodic execution. Place your tasks in a <code>tasks.py</code> module inside any installed app \u2014 django-periodic-tasks automatically discovers these modules at startup using Django\u2019s <code>autodiscover_modules</code>, similar to how <code>admin.py</code> files are discovered:</p> <pre><code># myapp/tasks.py\nfrom django_tasks import task\nfrom django_periodic_tasks.registry import scheduled_task\n\n\n@scheduled_task(cron=\"0 8 * * 1-5\")  # Weekdays at 8:00 AM UTC\n@task()\ndef morning_report() -&gt; None:\n    ...\n</code></pre> <p>Note</p> <p>You can define tasks in any module, but <code>tasks.py</code> is auto-discovered. If you use a different module name, make sure it gets imported somewhere (e.g. in your app\u2019s <code>AppConfig.ready()</code>).</p>"},{"location":"guides/defining-schedules.html#decorator-parameters","title":"Decorator Parameters","text":"Parameter Type Default Description <code>cron</code> <code>str</code> (required) 5-field cron expression <code>name</code> <code>str</code> task\u2019s <code>module_path</code> Unique schedule name <code>timezone</code> <code>str</code> <code>\"UTC\"</code> IANA timezone for cron matching <code>args</code> <code>list</code> <code>[]</code> Positional arguments for <code>task.enqueue()</code> <code>kwargs</code> <code>dict</code> <code>{}</code> Keyword arguments for <code>task.enqueue()</code> <code>queue_name</code> <code>str</code> <code>\"default\"</code> Queue name for <code>task.using()</code> <code>priority</code> <code>int</code> <code>0</code> Priority for <code>task.using()</code> <code>backend</code> <code>str</code> <code>\"default\"</code> Backend name for <code>task.using()</code>"},{"location":"guides/defining-schedules.html#task-arguments","title":"Task Arguments","text":"<p>Pass arguments that will be forwarded to <code>task.enqueue()</code> on each execution:</p> <pre><code>@scheduled_task(\n    cron=\"0 0 * * 0\",\n    args=[42],\n    kwargs={\"full\": True},\n)\n@task()\ndef weekly_sync(tenant_id: int, full: bool = False) -&gt; None:\n    ...\n</code></pre>"},{"location":"guides/defining-schedules.html#task-options","title":"Task Options","text":"<p>Control which queue, priority, and backend the task uses:</p> <pre><code>@scheduled_task(\n    cron=\"*/10 * * * *\",\n    queue_name=\"high-priority\",\n    priority=10,\n    backend=\"default\",\n)\n@task()\ndef health_check() -&gt; None:\n    ...\n</code></pre>"},{"location":"guides/defining-schedules.html#cron-expression-syntax","title":"Cron Expression Syntax","text":"<p>django-periodic-tasks uses standard 5-field cron expressions:</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 minute (0\u201359)\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 hour (0\u201323)\n\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 day of month (1\u201331)\n\u2502 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 month (1\u201312)\n\u2502 \u2502 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 day of week (0\u20136, Sun=0)\n\u2502 \u2502 \u2502 \u2502 \u2502\n* * * * *\n</code></pre> <p>Examples:</p> Expression Meaning <code>* * * * *</code> Every minute <code>*/15 * * * *</code> Every 15 minutes <code>0 * * * *</code> Every hour <code>0 8 * * *</code> Daily at 8:00 AM <code>0 8 * * 1-5</code> Weekdays at 8:00 AM <code>0 0 1 * *</code> First of every month at midnight <code>30 2 * * 0</code> Sundays at 2:30 AM"},{"location":"guides/defining-schedules.html#using-fluentcron","title":"Using fluentcron","text":"<p>If you prefer a type-safe, self-documenting API over raw cron strings, use the fluentcron library:</p> <pre><code>pip install fluentcron\n</code></pre> <p>fluentcron provides a fluent builder and shortcut functions that produce standard cron expression strings:</p> <pre><code>from django_tasks import task\nfrom django_periodic_tasks import scheduled_task\nfrom fluentcron import CronSchedule, daily_at, every_n_minutes\n\n# Shortcut function \u2014 returns a cron string directly\n@scheduled_task(cron=every_n_minutes(15))  # \"*/15 * * * *\"\n@task()\ndef health_check() -&gt; None:\n    ...\n\n\n# Shortcut function\n@scheduled_task(cron=daily_at(8))  # \"0 8 * * *\"\n@task()\ndef morning_report() -&gt; None:\n    ...\n\n\n# Fluent builder \u2014 call str() or .to_str() for the cron string\n@scheduled_task(\n    cron=str(CronSchedule().weekly().on_monday().at(9, 30)),  # \"30 9 * * 1\"\n)\n@task()\ndef weekly_digest() -&gt; None:\n    ...\n</code></pre> <p>fluentcron also ships with <code>CommonSchedules</code> presets for frequently used expressions:</p> <pre><code>from fluentcron import CommonSchedules\n\n@scheduled_task(cron=CommonSchedules.EVERY_HOUR)  # \"0 * * * *\"\n@task()\ndef sync_data() -&gt; None:\n    ...\n</code></pre>"},{"location":"guides/defining-schedules.html#timezone-support","title":"Timezone Support","text":"<p>By default, cron expressions are evaluated in UTC. Specify a timezone to match against local time:</p> <pre><code>@scheduled_task(\n    cron=\"0 9 * * *\",       # 9:00 AM\n    timezone=\"US/Eastern\",   # in Eastern time\n)\n@task()\ndef east_coast_morning() -&gt; None:\n    ...\n</code></pre> <p>The <code>timezone</code> parameter accepts any IANA timezone name (e.g. <code>\"US/Pacific\"</code>, <code>\"Europe/London\"</code>, <code>\"Asia/Tokyo\"</code>).</p>"},{"location":"guides/defining-schedules.html#database-defined-schedules","title":"Database-Defined Schedules","text":"<p>For schedules that need to be managed at runtime without a code deployment, create them through the Django admin:</p> <ol> <li>Navigate to Django Periodic Tasks &gt; Scheduled tasks in the admin.</li> <li>Click Add scheduled task.</li> <li>Fill in the task path (e.g. <code>myapp.tasks.morning_report</code>), cron expression, and any arguments.</li> <li>The schedule takes effect on the next scheduler tick.</li> </ol> <p>Database-defined schedules have <code>source = Database</code> and can be freely edited or disabled through the admin.</p>"},{"location":"guides/defining-schedules.html#schedule-sync","title":"Schedule Sync","text":"<p>When the scheduler starts, it syncs code-defined schedules to the database:</p> <ul> <li>New code schedules are created as <code>ScheduledTask</code> rows with <code>source = Code</code>.</li> <li>Changed code schedules (cron expression, task path, options) are updated in place.</li> <li>Removed code schedules (present in DB but no longer in the registry) are disabled.</li> <li>Database-defined schedules are never modified by the sync process.</li> </ul> <p>Code-defined schedules appear as read-only in the Django admin.</p>"},{"location":"guides/exactly-once.html","title":"Exactly-Once Execution","text":"<p>By default, the scheduler enqueues a task on each tick and trusts the worker to execute it. With non-transactional backends (e.g. Redis/RQ), there is a small window where a crash or retry could cause the same invocation to run more than once.</p> <p>The <code>@exactly_once</code> decorator closes that window. It guarantees that each scheduled invocation runs at most once, regardless of the backend.</p>"},{"location":"guides/exactly-once.html#how-it-works","title":"How It Works","text":"<p>When a task is decorated with <code>@exactly_once</code>, the scheduler and worker cooperate through a <code>TaskExecution</code> row in the database:</p> sequenceDiagram     participant S as Scheduler     participant DB as Database     participant W as Worker      S-&gt;&gt;DB: INSERT TaskExecution (status=PENDING)     S-&gt;&gt;W: enqueue task with execution ID     W-&gt;&gt;DB: SELECT FOR UPDATE TaskExecution     alt status is PENDING         W-&gt;&gt;W: run task function         W-&gt;&gt;DB: UPDATE status=COMPLETED     else already COMPLETED or missing         W-&gt;&gt;W: skip (no-op)     end <ol> <li>Scheduler tick \u2014 Creates a <code>TaskExecution</code> row with <code>status=PENDING</code> and passes its ID to the task as a keyword argument.</li> <li>Worker picks up the task \u2014 The <code>@exactly_once</code> wrapper locks the <code>TaskExecution</code> row with <code>SELECT FOR UPDATE</code>.</li> <li>If PENDING \u2014 Runs the wrapped function and marks the row <code>COMPLETED</code>.</li> <li>If not PENDING (already completed, or row missing) \u2014 Skips execution entirely.</li> </ol> <p>Because the row lock is held for the duration of the function call, even if two workers receive the same task, only one will find the row in <code>PENDING</code> status.</p>"},{"location":"guides/exactly-once.html#usage","title":"Usage","text":"<p>Apply <code>@exactly_once</code> below <code>@task()</code> so it wraps the raw function before django-tasks wraps it as a <code>Task</code>:</p> <pre><code>from django_tasks import task\nfrom django_periodic_tasks import scheduled_task, exactly_once\n\n\n@scheduled_task(cron=\"0 2 * * *\")\n@task()\n@exactly_once\ndef nightly_billing() -&gt; None:\n    \"\"\"Charge customers \u2014 must not run twice.\"\"\"\n    ...\n</code></pre> <p>Decorator order matters</p> <p><code>@exactly_once</code> must be below <code>@task()</code>. If placed above, the scheduler won\u2019t detect the <code>_exactly_once</code> marker and will skip creating the <code>TaskExecution</code> row.</p>"},{"location":"guides/exactly-once.html#manual-invocation","title":"Manual Invocation","text":"<p>When a task decorated with <code>@exactly_once</code> is called without the special <code>_periodic_tasks_execution_id</code> keyword argument (e.g. enqueued manually or called directly), the decorator is a no-op and the function runs normally:</p> <pre><code># These both work \u2014 exactly_once is bypassed\nnightly_billing.enqueue()\nnightly_billing()\n</code></pre>"},{"location":"guides/exactly-once.html#stale-execution-recovery","title":"Stale Execution Recovery","text":"<p>If the scheduler creates a <code>TaskExecution</code> row but the <code>on_commit</code> callback that enqueues the task never fires (e.g. process crash, connection reset), the row becomes stale.</p> <p>The scheduler automatically detects stale <code>PENDING</code> executions older than <code>max(60s, 2 \u00d7 interval)</code> and re-enqueues them on the next tick. This ensures tasks are not silently lost.</p>"},{"location":"guides/exactly-once.html#automatic-cleanup","title":"Automatic Cleanup","text":"<p>Completed <code>TaskExecution</code> rows are automatically deleted after 24 hours. <code>PENDING</code> rows are preserved until they are delivered or re-enqueued by the stale execution recovery process.</p>"},{"location":"guides/exactly-once.html#when-to-use-it","title":"When to Use It","text":"<p>Use <code>@exactly_once</code> when:</p> <ul> <li>The task has side effects that must not be duplicated (billing, sending emails, external API calls).</li> <li>You\u2019re using a non-transactional backend where at-least-once delivery is the default.</li> <li>You need a database-backed audit trail of each invocation.</li> </ul> <p>You can skip it when:</p> <ul> <li>The task is idempotent (safe to run multiple times with the same result).</li> <li>You\u2019re using the database backend with transactional enqueue, which already provides strong delivery guarantees.</li> <li>Performance is critical and the extra <code>SELECT FOR UPDATE</code> round-trip is not acceptable.</li> </ul>"},{"location":"guides/getting-started.html","title":"Getting Started","text":"<p>This guide walks you through installing django-periodic-tasks, defining your first scheduled task, and running the scheduler.</p>"},{"location":"guides/getting-started.html#prerequisites","title":"Prerequisites","text":"<ul> <li>Python 3.13+</li> <li>Django 5.2+</li> <li>django-tasks installed and configured with at least one backend</li> </ul>"},{"location":"guides/getting-started.html#installation","title":"Installation","text":"<p>Install the package:</p> <pre><code>pip install django-periodic-tasks\n</code></pre> <p>Add both <code>django_tasks</code> and <code>django_periodic_tasks</code> to your <code>INSTALLED_APPS</code>:</p> <pre><code>INSTALLED_APPS = [\n    # ...\n    \"django_tasks\",\n    \"django_tasks.backends.database\",  # if using the database backend\n    \"django_periodic_tasks\",\n    # ...\n]\n</code></pre> <p>Run migrations to create the <code>ScheduledTask</code> table:</p> <pre><code>python manage.py migrate\n</code></pre>"},{"location":"guides/getting-started.html#define-your-first-scheduled-task","title":"Define Your First Scheduled Task","text":"<p>Create a task using django-tasks\u2019 <code>@task()</code> decorator, then register it for periodic execution with <code>@scheduled_task()</code>. Place your tasks in a <code>tasks.py</code> module inside any installed app \u2014 django-periodic-tasks automatically discovers these modules at startup (similar to how Django discovers <code>admin.py</code> files):</p> <pre><code># myapp/tasks.py\nfrom django_tasks import task\nfrom django_periodic_tasks.registry import scheduled_task\n\n\n@scheduled_task(cron=\"*/5 * * * *\")  # Every 5 minutes\n@task()\ndef send_digest() -&gt; None:\n    \"\"\"Send the email digest.\"\"\"\n    ...\n</code></pre> <p>The <code>@scheduled_task</code> decorator must be applied above <code>@task()</code>. The <code>cron</code> parameter accepts any standard 5-field cron expression.</p>"},{"location":"guides/getting-started.html#run-the-scheduler","title":"Run the Scheduler","text":"<p>Enable the scheduler by adding this to your settings:</p> <pre><code># settings.py\nPERIODIC_TASKS_AUTOSTART = True\n</code></pre> <p>The scheduler starts automatically as a daemon thread when Django starts. It checks for due tasks every 15 seconds (configurable via <code>PERIODIC_TASKS_SCHEDULER_INTERVAL</code>).</p> <p>Run your task worker as usual (e.g. <code>python manage.py db_worker</code> for the database backend). The scheduler thread enqueues tasks; the worker executes them.</p>"},{"location":"guides/getting-started.html#verify-it-works","title":"Verify It Works","text":"<ol> <li>Open the Django admin at <code>/admin/django_periodic_tasks/scheduledtask/</code>.</li> <li>You should see your task listed with <code>source = Code</code>.</li> <li>The <code>next_run_at</code> field shows when the task will next be enqueued.</li> <li>After the scheduled time passes, <code>last_run_at</code> and <code>total_run_count</code> will update.</li> </ol>"},{"location":"guides/running.html","title":"Running the Scheduler","text":"<p>django-periodic-tasks runs as a daemon thread inside your Django process. Enable it with a single setting and the scheduler starts automatically alongside your application.</p>"},{"location":"guides/running.html#autostart-recommended","title":"Autostart (Recommended)","text":"<p>Add the following to your Django settings:</p> <pre><code># settings.py\nPERIODIC_TASKS_AUTOSTART = True\n</code></pre> <p>When Django starts, <code>AppConfig.ready()</code> launches the scheduler as a daemon thread. It syncs code-defined schedules to the database, then enters a tick-sleep loop that checks for due tasks every <code>PERIODIC_TASKS_SCHEDULER_INTERVAL</code> seconds (default: 15).</p> <p>The daemon thread exits automatically when the main process shuts down \u2014 no signal handling or cleanup is needed on your part.</p>"},{"location":"guides/running.html#tuning-the-interval","title":"Tuning the Interval","text":"<pre><code>PERIODIC_TASKS_SCHEDULER_INTERVAL = 30  # check every 30 seconds\n</code></pre> <p>Lower values mean tasks are enqueued closer to their scheduled time but increase database load. The default of 15 seconds is a good balance for most applications.</p>"},{"location":"guides/running.html#standalone-scheduler","title":"Standalone Scheduler","text":"<p>For cases where you want the scheduler in its own dedicated process (e.g. separating scheduling from request serving), use the <code>run_scheduler</code> management command:</p> <pre><code>python manage.py run_scheduler\n</code></pre> <p>This runs the scheduler loop in the main thread (blocking). You\u2019ll need to run your task worker separately.</p>"},{"location":"guides/running.html#options","title":"Options","text":"Flag Default Description <code>--interval</code> <code>15</code> Seconds between scheduler ticks <code>-v 0</code> \u2014 Suppress all output <code>-v 2</code> \u2014 Enable debug logging"},{"location":"guides/running.html#multi-worker-deployment","title":"Multi-Worker Deployment","text":"<p>The scheduler is safe to run across multiple processes. Each scheduler tick uses <code>SELECT FOR UPDATE SKIP LOCKED</code> to claim due tasks, so even if multiple scheduler instances run simultaneously, each task is enqueued exactly once.</p> <p>A typical production setup with two web/worker processes:</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   gunicorn / daphne     \u2502  \u2502   gunicorn / daphne     \u2502\n\u2502   (autostart=True)      \u2502  \u2502   (autostart=True)      \u2502\n\u2502   scheduler + app       \u2502  \u2502   scheduler + app       \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n         \u2502                            \u2502\n         \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                    \u2502\n           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n           \u2502   PostgreSQL    \u2502\n           \u2502  (shared DB)    \u2502\n           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> <p>Both instances run the scheduler, but <code>SKIP LOCKED</code> ensures no duplicate enqueues. Scale horizontally by adding more processes.</p>"},{"location":"guides/running.html#graceful-shutdown","title":"Graceful Shutdown","text":"<p>The <code>run_scheduler</code> command handles <code>SIGINT</code> and <code>SIGTERM</code> for graceful shutdown:</p> <ul> <li>The current scheduler tick completes.</li> <li>The stop event is set, and the scheduler thread exits.</li> <li>The process terminates cleanly.</li> </ul> <p>When using autostart, the scheduler thread is a daemon thread and exits automatically when the main process terminates. In container environments (Docker, Kubernetes), this means <code>docker stop</code> and Kubernetes pod termination work correctly out of the box.</p>"}]}

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "django-periodic-tasks"
-version = "0.1.0a3"
+version = "0.1.0a5"
 description = "Periodic/cron task scheduling for django-tasks. Backend-agnostic replacement for celery-beat."
 authors = [
     {name = "thelab", email = "thelabdev@thelab.co"}

django_periodic_tasks-0.1.0a5/sandbox/type_checking.py

@@ -0,0 +1,76 @@
+"""Type-checking assertions for django_periodic_tasks.
+
+This file is analyzed by mypy (via ``mypy sandbox/``) but never imported at
+runtime.  It verifies that our generic type annotations actually work:
+
+* **Positive cases** — valid code that must type-check without errors.
+* **Negative cases** — invalid code with ``# type: ignore[error-code]``.
+  If a ``type: ignore`` becomes unused (the error disappears), mypy's
+  ``warn_unused_ignores`` setting will flag the regression.
+"""
+
+from django_tasks import task
+
+from django_periodic_tasks.decorators import exactly_once, is_exactly_once
+from django_periodic_tasks.registry import ScheduleRegistry, scheduled_task
+
+# ---------------------------------------------------------------------------
+# Positive: valid usage (must type-check cleanly)
+# ---------------------------------------------------------------------------
+
+
+@scheduled_task(cron="* * * * *")
+@task()
+def my_task(foo: str, bar: int = 0) -> None:
+    pass
+
+
+@task()
+@exactly_once
+def my_once_task() -> str:
+    return "done"
+
+
+# Correct param types — must not error
+my_task.enqueue(foo="hello", bar=1)
+my_task.enqueue(foo="hello")  # bar is optional
+
+# is_exactly_once returns bool
+check: bool = is_exactly_once(lambda: None)
+
+# Valid registry with explicit params
+_registry = ScheduleRegistry()
+
+# scheduled_task with all explicit options
+scheduled_task(
+    cron="0 * * * *",
+    name="my-schedule",
+    timezone="America/New_York",
+    args=[1, "two"],
+    kwargs={"key": "value"},
+    queue_name="low",
+    priority=5,
+    backend="default",
+)
+
+# ---------------------------------------------------------------------------
+# Negative: wrong types (each MUST trigger the marked mypy error)
+# ---------------------------------------------------------------------------
+
+# cron must be str, not int
+scheduled_task(cron=123)  # type: ignore[arg-type]
+
+# priority must be int, not str
+scheduled_task(cron="* * * * *", priority="high")  # type: ignore[arg-type]
+
+# timezone must be str, not int
+scheduled_task(cron="* * * * *", timezone=0)  # type: ignore[arg-type]
+
+# exactly_once requires a callable, not a string
+exactly_once("not a function")  # type: ignore[arg-type]
+
+# foo expects str, not int — param types must flow through @task + @scheduled_task
+my_task.enqueue(foo=123)  # type: ignore[arg-type]
+
+# bar expects int, not str
+my_task.enqueue(foo="ok", bar="wrong")  # type: ignore[arg-type]

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/tests/test_decorators.py

@@ -3,7 +3,7 @@ import uuid
 from django.test import TestCase
 from django.utils import timezone
 
-from django_periodic_tasks.decorators import exactly_once
+from django_periodic_tasks.decorators import exactly_once, is_exactly_once
 from django_periodic_tasks.models import ScheduledTask, TaskExecution
 
 
@@ -80,13 +80,13 @@ class TestExactlyOnceDecorator(TestCase):
         self.assertEqual(call_log, [])
 
     def test_exactly_once_marker_attribute(self) -> None:
-        """The decorator should set _exactly_once = True on the wrapper."""
+        """The decorator should register the wrapper in the exactly_once registry."""
 
         @exactly_once
         def my_func() -> None:
             pass
 
-        self.assertTrue(getattr(my_func, "_exactly_once", False))
+        self.assertTrue(is_exactly_once(my_func))
 
     def test_preserves_function_metadata(self) -> None:
         """The decorator should use functools.wraps to preserve __qualname__ etc."""

django_periodic_tasks-0.1.0a5/tests/test_type_checking.py

@@ -0,0 +1,29 @@
+import subprocess
+import sys
+
+from django.test import SimpleTestCase
+
+
+class TestTypeAnnotations(SimpleTestCase):
+    def test_mypy_type_checking(self) -> None:
+        """Verify mypy catches type errors in our decorators and registry.
+
+        ``sandbox/type_checking.py`` contains:
+
+        - **Positive assertions**: valid code that must type-check cleanly.
+        - **Negative assertions**: invalid code with ``# type: ignore[error-code]``.
+
+        If a negative assertion's ``# type: ignore`` becomes unused (the
+        expected error disappears), mypy's ``warn_unused_ignores`` setting
+        reports it — meaning our types have regressed.
+        """
+        result = subprocess.run(
+            [sys.executable, "-m", "mypy", "sandbox/type_checking.py"],
+            capture_output=True,
+            text=True,
+        )
+        self.assertEqual(
+            result.returncode,
+            0,
+            f"mypy found unexpected type errors:\n{result.stdout}{result.stderr}",
+        )

{django_periodic_tasks-0.1.0a3 → django_periodic_tasks-0.1.0a5}/uv.lock

@@ -237,7 +237,7 @@ wheels = [
 
 [[package]]
 name = "django-periodic-tasks"
-version = "0.1.0"
+version = "0.1.0a4"
 source = { editable = "." }
 dependencies = [
     { name = "croniter" },

django_periodic_tasks-0.1.0a3/public/search/search_index.json

@@ -1 +0,0 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"index.html","title":"django-periodic-tasks","text":"<p>Periodic/cron task scheduling for django-tasks. A backend-agnostic replacement for celery-beat.</p>"},{"location":"index.html#features","title":"Features","text":"<ul> <li>Cron-based scheduling \u2014 Standard 5-field cron expressions with timezone support.</li> <li>Code-defined schedules \u2014 Declare schedules in Python with the <code>@scheduled_task</code> decorator; they sync to the database automatically.</li> <li>Database-defined schedules \u2014 Create and manage schedules through the Django admin for runtime flexibility.</li> <li>Exactly-once execution \u2014 Optional <code>@exactly_once</code> decorator guarantees a task runs at most once per scheduled invocation, even with non-transactional backends.</li> <li>Multi-worker safe \u2014 Uses <code>SELECT FOR UPDATE SKIP LOCKED</code> so multiple scheduler processes never double-enqueue the same task.</li> <li>Backend-agnostic \u2014 Works with any django-tasks backend (database, RQ, etc.).</li> </ul>"},{"location":"index.html#installation","title":"Installation","text":"<pre><code>pip install django-periodic-tasks\n</code></pre> <p>Add to your <code>INSTALLED_APPS</code> and run migrations:</p> <pre><code>INSTALLED_APPS = [\n    # ...\n    \"django_tasks\",\n    \"django_periodic_tasks\",\n    # ...\n]\n</code></pre> <pre><code>python manage.py migrate\n</code></pre>"},{"location":"index.html#next-steps","title":"Next Steps","text":"<p>{nav}</p> <code>sandbox.settings_docgen.setup</code>"},{"location":"api/index.html","title":"API Reference","text":"<p>{nav}</p>"},{"location":"api/decorators.html","title":"Decorators","text":""},{"location":"api/decorators.html#exactly_once","title":"exactly_once","text":"<code>django_periodic_tasks.decorators.exactly_once</code>(func) <p>Decorator ensuring a scheduled task runs at most once per invocation.</p> <p>When the scheduler creates a <code>TaskExecution</code> row and passes its ID via the <code>_periodic_tasks_execution_id</code> keyword argument, this decorator will:</p> <ol> <li>Pop <code>_periodic_tasks_execution_id</code> from kwargs.</li> <li>Lock the <code>TaskExecution</code> row with <code>SELECT FOR UPDATE</code>.</li> <li>Run the wrapped function only if the row\u2019s status is <code>PENDING</code>.</li> <li>Mark the row <code>COMPLETED</code> on success.</li> </ol> <p>If <code>_periodic_tasks_execution_id</code> is absent (e.g. manual invocation), the wrapped function runs normally without any execution-permit logic.</p>"},{"location":"api/models.html","title":"Models","text":""},{"location":"api/models.html#scheduledtask","title":"ScheduledTask","text":"class <code>django_periodic_tasks.models.ScheduledTask</code>(*args, **kwargs) <p>A persistent record of a periodic task and its cron schedule.</p> <p>Each row represents one scheduled task. The scheduler queries this table on every tick to find tasks whose <code>next_run_at</code> has passed, then enqueues them via django-tasks.</p> <p>Tasks can originate from two sources (see :class:<code>Source</code>):</p> <ul> <li>Code-defined \u2014 registered with :func:<code>~django_periodic_tasks.registry.scheduled_task</code>   and synced to the database on scheduler startup.</li> <li>Database-defined \u2014 created manually through the Django admin.</li> </ul>"},{"location":"api/models.html#scheduledtasksource","title":"ScheduledTask.Source","text":"<p>Where a scheduled task definition comes from.</p> <ul> <li><code>CODE</code> \u2014 Managed by the codebase and synced automatically on scheduler startup.</li> <li><code>DATABASE</code> \u2014 Managed by operators through the Django admin.</li> </ul>"},{"location":"api/models.html#taskexecution","title":"TaskExecution","text":"class <code>django_periodic_tasks.models.TaskExecution</code>(*args, **kwargs) <p>An execution permit for a single scheduled task invocation.</p> <p>Used by the <code>@exactly_once</code> decorator to ensure a task runs at most once per scheduled invocation, even with non-transactional backends (e.g. Redis/RQ).</p>"},{"location":"api/models.html#taskexecutionstatus","title":"TaskExecution.Status","text":"<p>The lifecycle status of an execution permit.</p> <ul> <li><code>PENDING</code> \u2014 Created by the scheduler, awaiting worker pickup.</li> <li><code>COMPLETED</code> \u2014 The <code>@exactly_once</code> decorator ran the task successfully.</li> </ul>"},{"location":"api/registry.html","title":"Registry","text":""},{"location":"api/registry.html#scheduled_task","title":"scheduled_task","text":"<code>django_periodic_tasks.registry.scheduled_task</code>(*, cron, name=None, registry=None, **kwargs) <p>Decorator that registers a django-tasks <code>Task</code> with the schedule registry.</p> <p>Apply this decorator after <code>@task()</code> to register the task for periodic execution::</p> <pre><code>@scheduled_task(cron=\"/5 * * * \")\n@task()\ndef send_digest(user_id: int) -&gt; None:\n    \u2026\n</code></pre> <p>Args:     cron: A 5-field cron expression (e.g. <code>\u201c0 8 * * 1-5\u201d</code>).     name: Unique schedule name. Defaults to the task\u2019s <code>module_path</code>.     registry: An alternate <code>ScheduleRegistry</code> instance (defaults to the         global <code>schedule_registry</code>).     **kwargs: Extra options forwarded to         :meth:<code>ScheduleRegistry.register</code> (<code>timezone</code>, <code>args</code>,         <code>kwargs</code>, <code>queue_name</code>, <code>priority</code>, <code>backend</code>).</p>"},{"location":"api/registry.html#scheduleentry","title":"ScheduleEntry","text":"class <code>django_periodic_tasks.registry.ScheduleEntry</code>(task, cron_expression, name, timezone=\u2019UTC\u2019, args=, kwargs=, queue_name=\u2019default\u2019, priority=0, backend=\u2019default\u2019) <p>An immutable record describing a single scheduled task.</p> <p>Each entry holds the task object, its cron schedule, and the options that will be forwarded to <code>task.using()</code> / <code>task.enqueue()</code> at execution time.</p> <p>Attributes:     task: The django-tasks <code>Task</code> object to enqueue.     cron_expression: A standard 5-field cron expression (e.g. <code>\u201c/15 * * * \u201c</code>).     name: Unique name for this schedule (used as the DB primary key).     timezone: IANA timezone name used for cron matching (default <code>\u201cUTC\u201d</code>).     args: Positional arguments passed to <code>task.enqueue()</code>.     kwargs: Keyword arguments passed to <code>task.enqueue()</code>.     queue_name: Task queue name passed to <code>task.using()</code>.     priority: Task priority passed to <code>task.using()</code>.     backend: Task backend name passed to <code>task.using()</code>.</p>"},{"location":"api/registry.html#scheduleregistry","title":"ScheduleRegistry","text":"class <code>django_periodic_tasks.registry.ScheduleRegistry</code>() <p>Singleton registry for code-defined schedules.</p> <code>get_entries</code>(self) <p>Return a copy of all registered schedule entries, keyed by name.</p> <code>register</code>(self, task, *, cron, name, timezone=\u2019UTC\u2019, args=None, kwargs=None, queue_name=\u2019default\u2019, priority=0, backend=\u2019default\u2019) <p>Register a task with the given cron schedule.</p> <p>Args:     task: A django-tasks <code>Task</code> object.     cron: A 5-field cron expression (e.g. <code>\u201c0 /6 * * \u201c</code>).     name: Unique name for this schedule.     timezone: IANA timezone for cron matching (default <code>\u201cUTC\u201d</code>).     args: Positional arguments for <code>task.enqueue()</code>.     kwargs: Keyword arguments for <code>task.enqueue()</code>.     queue_name: Queue name for <code>task.using()</code>.     priority: Priority for <code>task.using()</code>.     backend: Backend name for <code>task.using()</code>.</p> <p>Raises:     ValueError: If the cron expression is invalid or the name is already registered.</p>"},{"location":"api/settings.html","title":"Settings","text":"<p>django-periodic-tasks is configured through Django settings.</p>"},{"location":"api/settings.html#periodic_tasks_autostart","title":"PERIODIC_TASKS_AUTOSTART","text":"Type <code>bool</code> Default <code>False</code> <p>When <code>True</code>, the scheduler starts automatically as a daemon thread during <code>AppConfig.ready()</code>. Useful for development and simple single-process deployments.</p> <pre><code>PERIODIC_TASKS_AUTOSTART = True\n</code></pre>"},{"location":"api/settings.html#periodic_tasks_scheduler_interval","title":"PERIODIC_TASKS_SCHEDULER_INTERVAL","text":"Type <code>int</code> Default <code>15</code> <p>Seconds between scheduler ticks. On each tick the scheduler queries the database for due tasks and enqueues them.</p> <pre><code>PERIODIC_TASKS_SCHEDULER_INTERVAL = 30  # check every 30 seconds\n</code></pre> <p>Lower values mean tasks are enqueued closer to their scheduled time, but increase database load. The default of 15 seconds is a good balance for most applications.</p>"},{"location":"guides/index.html","title":"Guides","text":"<p>{nav}</p>"},{"location":"guides/defining-schedules.html","title":"Defining Schedules","text":"<p>django-periodic-tasks supports two ways to define scheduled tasks: in code (version-controlled, deployed with your app) and in the database (managed at runtime through the Django admin).</p>"},{"location":"guides/defining-schedules.html#code-defined-schedules","title":"Code-Defined Schedules","text":"<p>Use the <code>@scheduled_task</code> decorator to register a django-tasks <code>Task</code> for periodic execution. Place your tasks in a <code>tasks.py</code> module inside any installed app \u2014 django-periodic-tasks automatically discovers these modules at startup using Django\u2019s <code>autodiscover_modules</code>, similar to how <code>admin.py</code> files are discovered:</p> <pre><code># myapp/tasks.py\nfrom django_tasks import task\nfrom django_periodic_tasks.registry import scheduled_task\n\n\n@scheduled_task(cron=\"0 8 * * 1-5\")  # Weekdays at 8:00 AM UTC\n@task()\ndef morning_report() -&gt; None:\n    ...\n</code></pre> <p>Note</p> <p>You can define tasks in any module, but <code>tasks.py</code> is auto-discovered. If you use a different module name, make sure it gets imported somewhere (e.g. in your app\u2019s <code>AppConfig.ready()</code>).</p>"},{"location":"guides/defining-schedules.html#decorator-parameters","title":"Decorator Parameters","text":"Parameter Type Default Description <code>cron</code> <code>str</code> (required) 5-field cron expression <code>name</code> <code>str</code> task\u2019s <code>module_path</code> Unique schedule name <code>timezone</code> <code>str</code> <code>\"UTC\"</code> IANA timezone for cron matching <code>args</code> <code>list</code> <code>[]</code> Positional arguments for <code>task.enqueue()</code> <code>kwargs</code> <code>dict</code> <code>{}</code> Keyword arguments for <code>task.enqueue()</code> <code>queue_name</code> <code>str</code> <code>\"default\"</code> Queue name for <code>task.using()</code> <code>priority</code> <code>int</code> <code>0</code> Priority for <code>task.using()</code> <code>backend</code> <code>str</code> <code>\"default\"</code> Backend name for <code>task.using()</code>"},{"location":"guides/defining-schedules.html#task-arguments","title":"Task Arguments","text":"<p>Pass arguments that will be forwarded to <code>task.enqueue()</code> on each execution:</p> <pre><code>@scheduled_task(\n    cron=\"0 0 * * 0\",\n    args=[42],\n    kwargs={\"full\": True},\n)\n@task()\ndef weekly_sync(tenant_id: int, full: bool = False) -&gt; None:\n    ...\n</code></pre>"},{"location":"guides/defining-schedules.html#task-options","title":"Task Options","text":"<p>Control which queue, priority, and backend the task uses:</p> <pre><code>@scheduled_task(\n    cron=\"*/10 * * * *\",\n    queue_name=\"high-priority\",\n    priority=10,\n    backend=\"default\",\n)\n@task()\ndef health_check() -&gt; None:\n    ...\n</code></pre>"},{"location":"guides/defining-schedules.html#cron-expression-syntax","title":"Cron Expression Syntax","text":"<p>django-periodic-tasks uses standard 5-field cron expressions:</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 minute (0\u201359)\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 hour (0\u201323)\n\u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 day of month (1\u201331)\n\u2502 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 month (1\u201312)\n\u2502 \u2502 \u2502 \u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 day of week (0\u20136, Sun=0)\n\u2502 \u2502 \u2502 \u2502 \u2502\n* * * * *\n</code></pre> <p>Examples:</p> Expression Meaning <code>* * * * *</code> Every minute <code>*/15 * * * *</code> Every 15 minutes <code>0 * * * *</code> Every hour <code>0 8 * * *</code> Daily at 8:00 AM <code>0 8 * * 1-5</code> Weekdays at 8:00 AM <code>0 0 1 * *</code> First of every month at midnight <code>30 2 * * 0</code> Sundays at 2:30 AM"},{"location":"guides/defining-schedules.html#using-fluentcron","title":"Using fluentcron","text":"<p>If you prefer a type-safe, self-documenting API over raw cron strings, use the fluentcron library:</p> <pre><code>pip install fluentcron\n</code></pre> <p>fluentcron provides a fluent builder and shortcut functions that produce standard cron expression strings:</p> <pre><code>from django_tasks import task\nfrom django_periodic_tasks import scheduled_task\nfrom fluentcron import CronSchedule, daily_at, every_n_minutes\n\n# Shortcut function \u2014 returns a cron string directly\n@scheduled_task(cron=every_n_minutes(15))  # \"*/15 * * * *\"\n@task()\ndef health_check() -&gt; None:\n    ...\n\n\n# Shortcut function\n@scheduled_task(cron=daily_at(8))  # \"0 8 * * *\"\n@task()\ndef morning_report() -&gt; None:\n    ...\n\n\n# Fluent builder \u2014 call str() or .to_str() for the cron string\n@scheduled_task(\n    cron=str(CronSchedule().weekly().on_monday().at(9, 30)),  # \"30 9 * * 1\"\n)\n@task()\ndef weekly_digest() -&gt; None:\n    ...\n</code></pre> <p>fluentcron also ships with <code>CommonSchedules</code> presets for frequently used expressions:</p> <pre><code>from fluentcron import CommonSchedules\n\n@scheduled_task(cron=CommonSchedules.EVERY_HOUR)  # \"0 * * * *\"\n@task()\ndef sync_data() -&gt; None:\n    ...\n</code></pre>"},{"location":"guides/defining-schedules.html#timezone-support","title":"Timezone Support","text":"<p>By default, cron expressions are evaluated in UTC. Specify a timezone to match against local time:</p> <pre><code>@scheduled_task(\n    cron=\"0 9 * * *\",       # 9:00 AM\n    timezone=\"US/Eastern\",   # in Eastern time\n)\n@task()\ndef east_coast_morning() -&gt; None:\n    ...\n</code></pre> <p>The <code>timezone</code> parameter accepts any IANA timezone name (e.g. <code>\"US/Pacific\"</code>, <code>\"Europe/London\"</code>, <code>\"Asia/Tokyo\"</code>).</p>"},{"location":"guides/defining-schedules.html#database-defined-schedules","title":"Database-Defined Schedules","text":"<p>For schedules that need to be managed at runtime without a code deployment, create them through the Django admin:</p> <ol> <li>Navigate to Django Periodic Tasks &gt; Scheduled tasks in the admin.</li> <li>Click Add scheduled task.</li> <li>Fill in the task path (e.g. <code>myapp.tasks.morning_report</code>), cron expression, and any arguments.</li> <li>The schedule takes effect on the next scheduler tick.</li> </ol> <p>Database-defined schedules have <code>source = Database</code> and can be freely edited or disabled through the admin.</p>"},{"location":"guides/defining-schedules.html#schedule-sync","title":"Schedule Sync","text":"<p>When the scheduler starts, it syncs code-defined schedules to the database:</p> <ul> <li>New code schedules are created as <code>ScheduledTask</code> rows with <code>source = Code</code>.</li> <li>Changed code schedules (cron expression, task path, options) are updated in place.</li> <li>Removed code schedules (present in DB but no longer in the registry) are disabled.</li> <li>Database-defined schedules are never modified by the sync process.</li> </ul> <p>Code-defined schedules appear as read-only in the Django admin.</p>"},{"location":"guides/exactly-once.html","title":"Exactly-Once Execution","text":"<p>By default, the scheduler enqueues a task on each tick and trusts the worker to execute it. With non-transactional backends (e.g. Redis/RQ), there is a small window where a crash or retry could cause the same invocation to run more than once.</p> <p>The <code>@exactly_once</code> decorator closes that window. It guarantees that each scheduled invocation runs at most once, regardless of the backend.</p>"},{"location":"guides/exactly-once.html#how-it-works","title":"How It Works","text":"<p>When a task is decorated with <code>@exactly_once</code>, the scheduler and worker cooperate through a <code>TaskExecution</code> row in the database:</p> sequenceDiagram     participant S as Scheduler     participant DB as Database     participant W as Worker      S-&gt;&gt;DB: INSERT TaskExecution (status=PENDING)     S-&gt;&gt;W: enqueue task with execution ID     W-&gt;&gt;DB: SELECT FOR UPDATE TaskExecution     alt status is PENDING         W-&gt;&gt;W: run task function         W-&gt;&gt;DB: UPDATE status=COMPLETED     else already COMPLETED or missing         W-&gt;&gt;W: skip (no-op)     end <ol> <li>Scheduler tick \u2014 Creates a <code>TaskExecution</code> row with <code>status=PENDING</code> and passes its ID to the task as a keyword argument.</li> <li>Worker picks up the task \u2014 The <code>@exactly_once</code> wrapper locks the <code>TaskExecution</code> row with <code>SELECT FOR UPDATE</code>.</li> <li>If PENDING \u2014 Runs the wrapped function and marks the row <code>COMPLETED</code>.</li> <li>If not PENDING (already completed, or row missing) \u2014 Skips execution entirely.</li> </ol> <p>Because the row lock is held for the duration of the function call, even if two workers receive the same task, only one will find the row in <code>PENDING</code> status.</p>"},{"location":"guides/exactly-once.html#usage","title":"Usage","text":"<p>Apply <code>@exactly_once</code> below <code>@task()</code> so it wraps the raw function before django-tasks wraps it as a <code>Task</code>:</p> <pre><code>from django_tasks import task\nfrom django_periodic_tasks import scheduled_task, exactly_once\n\n\n@scheduled_task(cron=\"0 2 * * *\")\n@task()\n@exactly_once\ndef nightly_billing() -&gt; None:\n    \"\"\"Charge customers \u2014 must not run twice.\"\"\"\n    ...\n</code></pre> <p>Decorator order matters</p> <p><code>@exactly_once</code> must be below <code>@task()</code>. If placed above, the scheduler won\u2019t detect the <code>_exactly_once</code> marker and will skip creating the <code>TaskExecution</code> row.</p>"},{"location":"guides/exactly-once.html#manual-invocation","title":"Manual Invocation","text":"<p>When a task decorated with <code>@exactly_once</code> is called without the special <code>_periodic_tasks_execution_id</code> keyword argument (e.g. enqueued manually or called directly), the decorator is a no-op and the function runs normally:</p> <pre><code># These both work \u2014 exactly_once is bypassed\nnightly_billing.enqueue()\nnightly_billing()\n</code></pre>"},{"location":"guides/exactly-once.html#stale-execution-recovery","title":"Stale Execution Recovery","text":"<p>If the scheduler creates a <code>TaskExecution</code> row but the <code>on_commit</code> callback that enqueues the task never fires (e.g. process crash, connection reset), the row becomes stale.</p> <p>The scheduler automatically detects stale <code>PENDING</code> executions older than <code>max(60s, 2 \u00d7 interval)</code> and re-enqueues them on the next tick. This ensures tasks are not silently lost.</p>"},{"location":"guides/exactly-once.html#automatic-cleanup","title":"Automatic Cleanup","text":"<p>Completed <code>TaskExecution</code> rows are automatically deleted after 24 hours. <code>PENDING</code> rows are preserved until they are delivered or re-enqueued by the stale execution recovery process.</p>"},{"location":"guides/exactly-once.html#when-to-use-it","title":"When to Use It","text":"<p>Use <code>@exactly_once</code> when:</p> <ul> <li>The task has side effects that must not be duplicated (billing, sending emails, external API calls).</li> <li>You\u2019re using a non-transactional backend where at-least-once delivery is the default.</li> <li>You need a database-backed audit trail of each invocation.</li> </ul> <p>You can skip it when:</p> <ul> <li>The task is idempotent (safe to run multiple times with the same result).</li> <li>You\u2019re using the database backend with transactional enqueue, which already provides strong delivery guarantees.</li> <li>Performance is critical and the extra <code>SELECT FOR UPDATE</code> round-trip is not acceptable.</li> </ul>"},{"location":"guides/getting-started.html","title":"Getting Started","text":"<p>This guide walks you through installing django-periodic-tasks, defining your first scheduled task, and running the scheduler.</p>"},{"location":"guides/getting-started.html#prerequisites","title":"Prerequisites","text":"<ul> <li>Python 3.13+</li> <li>Django 5.2+</li> <li>django-tasks installed and configured with at least one backend</li> </ul>"},{"location":"guides/getting-started.html#installation","title":"Installation","text":"<p>Install the package:</p> <pre><code>pip install django-periodic-tasks\n</code></pre> <p>Add both <code>django_tasks</code> and <code>django_periodic_tasks</code> to your <code>INSTALLED_APPS</code>:</p> <pre><code>INSTALLED_APPS = [\n    # ...\n    \"django_tasks\",\n    \"django_tasks.backends.database\",  # if using the database backend\n    \"django_periodic_tasks\",\n    # ...\n]\n</code></pre> <p>Run migrations to create the <code>ScheduledTask</code> table:</p> <pre><code>python manage.py migrate\n</code></pre>"},{"location":"guides/getting-started.html#define-your-first-scheduled-task","title":"Define Your First Scheduled Task","text":"<p>Create a task using django-tasks\u2019 <code>@task()</code> decorator, then register it for periodic execution with <code>@scheduled_task()</code>. Place your tasks in a <code>tasks.py</code> module inside any installed app \u2014 django-periodic-tasks automatically discovers these modules at startup (similar to how Django discovers <code>admin.py</code> files):</p> <pre><code># myapp/tasks.py\nfrom django_tasks import task\nfrom django_periodic_tasks.registry import scheduled_task\n\n\n@scheduled_task(cron=\"*/5 * * * *\")  # Every 5 minutes\n@task()\ndef send_digest() -&gt; None:\n    \"\"\"Send the email digest.\"\"\"\n    ...\n</code></pre> <p>The <code>@scheduled_task</code> decorator must be applied above <code>@task()</code>. The <code>cron</code> parameter accepts any standard 5-field cron expression.</p>"},{"location":"guides/getting-started.html#run-the-scheduler","title":"Run the Scheduler","text":"<p>Enable the scheduler by adding this to your settings:</p> <pre><code># settings.py\nPERIODIC_TASKS_AUTOSTART = True\n</code></pre> <p>The scheduler starts automatically as a daemon thread when Django starts. It checks for due tasks every 15 seconds (configurable via <code>PERIODIC_TASKS_SCHEDULER_INTERVAL</code>).</p> <p>Run your task worker as usual (e.g. <code>python manage.py db_worker</code> for the database backend). The scheduler thread enqueues tasks; the worker executes them.</p>"},{"location":"guides/getting-started.html#verify-it-works","title":"Verify It Works","text":"<ol> <li>Open the Django admin at <code>/admin/django_periodic_tasks/scheduledtask/</code>.</li> <li>You should see your task listed with <code>source = Code</code>.</li> <li>The <code>next_run_at</code> field shows when the task will next be enqueued.</li> <li>After the scheduled time passes, <code>last_run_at</code> and <code>total_run_count</code> will update.</li> </ol>"},{"location":"guides/running.html","title":"Running the Scheduler","text":"<p>django-periodic-tasks runs as a daemon thread inside your Django process. Enable it with a single setting and the scheduler starts automatically alongside your application.</p>"},{"location":"guides/running.html#autostart-recommended","title":"Autostart (Recommended)","text":"<p>Add the following to your Django settings:</p> <pre><code># settings.py\nPERIODIC_TASKS_AUTOSTART = True\n</code></pre> <p>When Django starts, <code>AppConfig.ready()</code> launches the scheduler as a daemon thread. It syncs code-defined schedules to the database, then enters a tick-sleep loop that checks for due tasks every <code>PERIODIC_TASKS_SCHEDULER_INTERVAL</code> seconds (default: 15).</p> <p>The daemon thread exits automatically when the main process shuts down \u2014 no signal handling or cleanup is needed on your part.</p>"},{"location":"guides/running.html#tuning-the-interval","title":"Tuning the Interval","text":"<pre><code>PERIODIC_TASKS_SCHEDULER_INTERVAL = 30  # check every 30 seconds\n</code></pre> <p>Lower values mean tasks are enqueued closer to their scheduled time but increase database load. The default of 15 seconds is a good balance for most applications.</p>"},{"location":"guides/running.html#standalone-scheduler","title":"Standalone Scheduler","text":"<p>For cases where you want the scheduler in its own dedicated process (e.g. separating scheduling from request serving), use the <code>run_scheduler</code> management command:</p> <pre><code>python manage.py run_scheduler\n</code></pre> <p>This runs the scheduler loop in the main thread (blocking). You\u2019ll need to run your task worker separately.</p>"},{"location":"guides/running.html#options","title":"Options","text":"Flag Default Description <code>--interval</code> <code>15</code> Seconds between scheduler ticks <code>-v 0</code> \u2014 Suppress all output <code>-v 2</code> \u2014 Enable debug logging"},{"location":"guides/running.html#multi-worker-deployment","title":"Multi-Worker Deployment","text":"<p>The scheduler is safe to run across multiple processes. Each scheduler tick uses <code>SELECT FOR UPDATE SKIP LOCKED</code> to claim due tasks, so even if multiple scheduler instances run simultaneously, each task is enqueued exactly once.</p> <p>A typical production setup with two web/worker processes:</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502   gunicorn / daphne     \u2502  \u2502   gunicorn / daphne     \u2502\n\u2502   (autostart=True)      \u2502  \u2502   (autostart=True)      \u2502\n\u2502   scheduler + app       \u2502  \u2502   scheduler + app       \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n         \u2502                            \u2502\n         \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                    \u2502\n           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n           \u2502   PostgreSQL    \u2502\n           \u2502  (shared DB)    \u2502\n           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n</code></pre> <p>Both instances run the scheduler, but <code>SKIP LOCKED</code> ensures no duplicate enqueues. Scale horizontally by adding more processes.</p>"},{"location":"guides/running.html#graceful-shutdown","title":"Graceful Shutdown","text":"<p>The <code>run_scheduler</code> command handles <code>SIGINT</code> and <code>SIGTERM</code> for graceful shutdown:</p> <ul> <li>The current scheduler tick completes.</li> <li>The stop event is set, and the scheduler thread exits.</li> <li>The process terminates cleanly.</li> </ul> <p>When using autostart, the scheduler thread is a daemon thread and exits automatically when the main process terminates. In container environments (Docker, Kubernetes), this means <code>docker stop</code> and Kubernetes pod termination work correctly out of the box.</p>"}]}