feat: add clocked schedule (#226)

* feat: add clocked schedule

* fix: rebase master and regen migration

* fix: make ci happy

* style(clocked): change clocked schedule verbose name and help text

* fix: regen migration

Author: yywing

django_celery_beat/admin.py

@@ -16,7 +16,7 @@
 from .models import (
     PeriodicTask, PeriodicTasks,
     IntervalSchedule, CrontabSchedule,
-    SolarSchedule
+    SolarSchedule, ClockedSchedule
 )
 from .utils import is_database_scheduler
 
@@ -128,7 +128,7 @@ class PeriodicTaskAdmin(admin.ModelAdmin):
             'classes': ('extrapretty', 'wide'),
         }),
         ('Schedule', {
-            'fields': ('interval', 'crontab', 'solar',
+            'fields': ('interval', 'crontab', 'solar', 'clocked',
                        'start_time', 'one_off'),
             'classes': ('extrapretty', 'wide'),
         }),
@@ -152,7 +152,7 @@ def changelist_view(self, request, extra_context=None):
 
     def get_queryset(self, request):
         qs = super(PeriodicTaskAdmin, self).get_queryset(request)
-        return qs.select_related('interval', 'crontab', 'solar')
+        return qs.select_related('interval', 'crontab', 'solar', 'clocked')
 
     def _message_user_about_update(self, request, rows_updated, verb):
         """Send message about action to user.
@@ -236,4 +236,5 @@ def run_tasks(self, request, queryset):
 admin.site.register(IntervalSchedule)
 admin.site.register(CrontabSchedule)
 admin.site.register(SolarSchedule)
+admin.site.register(ClockedSchedule)
 admin.site.register(PeriodicTask, PeriodicTaskAdmin)

django_celery_beat/clockedschedule.py

@@ -0,0 +1,57 @@
+"""Clocked schedule Implementation."""
+from __future__ import absolute_import, unicode_literals
+
+
+from celery import schedules
+from celery.utils.time import maybe_make_aware
+from collections import namedtuple
+
+
+schedstate = namedtuple('schedstate', ('is_due', 'next'))
+
+
+class clocked(schedules.BaseSchedule):
+    """clocked schedule.
+
+    It depend on PeriodicTask once_off
+    """
+
+    def __init__(self, clocked_time, enabled=True,
+                 model=None, nowfun=None, app=None):
+        """Initialize clocked."""
+        self.clocked_time = maybe_make_aware(clocked_time)
+        self.enabled = enabled
+        self.model = model
+        super(clocked, self).__init__(nowfun=nowfun, app=app)
+
+    def remaining_estimate(self, last_run_at):
+        return self.clocked_time - self.now()
+
+    def is_due(self, last_run_at):
+        # actually last run at is useless
+        last_run_at = maybe_make_aware(last_run_at)
+        rem_delta = self.remaining_estimate(last_run_at)
+        remaining_s = max(rem_delta.total_seconds(), 0)
+        if not self.enabled:
+            return schedstate(is_due=False, next=None)
+        if remaining_s == 0:
+            if self.model:
+                self.model.enabled = False
+                self.model.save()
+            return schedstate(is_due=True, next=None)
+        return schedstate(is_due=False, next=remaining_s)
+
+    def __repr__(self):
+        return '<clocked: {} {}>'.format(self.clocked_time, self.enabled)
+
+    def __eq__(self, other):
+        if isinstance(other, clocked):
+            return self.clocked_time == other.clocked_time and \
+                self.enabled == other.enabled
+        return False
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __reduce__(self):
+        return self.__class__, (self.clocked_time, self.nowfun)

django_celery_beat/migrations/0011_auto_20190508_0153.py

@@ -0,0 +1,34 @@
+# Generated by Django 2.2 on 2019-05-08 01:53
+# flake8: noqa
+from __future__ import absolute_import, unicode_literals
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('django_celery_beat', '0010_auto_20190429_0326'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ClockedSchedule',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('clocked_time', models.DateTimeField(help_text='Run the task at clocked time', verbose_name='Clock Time')),
+                ('enabled', models.BooleanField(default=True, editable=False, help_text='Set to False to disable the schedule', verbose_name='Enabled')),
+            ],
+            options={
+                'verbose_name': 'clocked',
+                'verbose_name_plural': 'clocked',
+                'ordering': ['clocked_time'],
+            },
+        ),
+        migrations.AddField(
+            model_name='periodictask',
+            name='clocked',
+            field=models.ForeignKey(blank=True, help_text='Clocked Schedule to run the task on.  Set only one schedule type, leave the others null.', null=True, on_delete=django.db.models.deletion.CASCADE, to='django_celery_beat.ClockedSchedule', verbose_name='Clocked Schedule'),
+        ),
+    ]

django_celery_beat/models.py

@@ -16,6 +16,7 @@
 from . import managers, validators
 from .tzcrontab import TzAwareCrontab
 from .utils import make_aware, now
+from .clockedschedule import clocked
 
 
 DAYS = 'days'
@@ -166,6 +167,50 @@ def period_singular(self):
         return self.period[:-1]
 
 
+@python_2_unicode_compatible
+class ClockedSchedule(models.Model):
+    """clocked schedule."""
+
+    clocked_time = models.DateTimeField(
+        verbose_name=_('Clock Time'),
+        help_text=_('Run the task at clocked time'),
+    )
+    enabled = models.BooleanField(
+        default=True,
+        editable=False,
+        verbose_name=_('Enabled'),
+        help_text=_('Set to False to disable the schedule'),
+    )
+
+    class Meta:
+        """Table information."""
+
+        verbose_name = _('clocked')
+        verbose_name_plural = _('clocked')
+        ordering = ['clocked_time']
+
+    def __str__(self):
+        return '{} {}'.format(self.clocked_time, self.enabled)
+
+    @property
+    def schedule(self):
+        c = clocked(clocked_time=self.clocked_time,
+                    enabled=self.enabled, model=self)
+        return c
+
+    @classmethod
+    def from_schedule(cls, schedule):
+        spec = {'clocked_time': schedule.clocked_time,
+                'enabled': schedule.enabled}
+        try:
+            return cls.objects.get(**spec)
+        except cls.DoesNotExist:
+            return cls(**spec)
+        except MultipleObjectsReturned:
+            cls.objects.filter(**spec).delete()
+            return cls(**spec)
+
+
 @python_2_unicode_compatible
 class CrontabSchedule(models.Model):
     """Timezone Aware Crontab-like schedule.
@@ -348,7 +393,12 @@ class PeriodicTask(models.Model):
         help_text=_('Solar Schedule to run the task on.  '
                     'Set only one schedule type, leave the others null.'),
     )
-
+    clocked = models.ForeignKey(
+        ClockedSchedule, on_delete=models.CASCADE, null=True, blank=True,
+        verbose_name=_('Clocked Schedule'),
+        help_text=_('Clocked Schedule to run the task on.  '
+                    'Set only one schedule type, leave the others null.'),
+    )
     # TODO: use django's JsonField
     args = models.TextField(
         blank=True, default='[]',
@@ -464,24 +514,30 @@ class Meta:
     def validate_unique(self, *args, **kwargs):
         super(PeriodicTask, self).validate_unique(*args, **kwargs)
 
-        schedule_types = ['interval', 'crontab', 'solar']
+        schedule_types = ['interval', 'crontab', 'solar', 'clocked']
         selected_schedule_types = [s for s in schedule_types
                                    if getattr(self, s)]
 
         if len(selected_schedule_types) == 0:
             raise ValidationError({
                 'interval': [
-                    'One of interval, crontab, or solar must be set.'
+                    'One of clocked, interval, crontab, or solar must be set.'
                 ]
             })
 
-        err_msg = 'Only one of interval, crontab, or solar must be set'
+        err_msg = 'Only one of clocked, interval, crontab, '\
+            'or solar must be set'
         if len(selected_schedule_types) > 1:
             error_info = {}
             for selected_schedule_type in selected_schedule_types:
                 error_info[selected_schedule_type] = [err_msg]
             raise ValidationError(error_info)
 
+        # clocked must be one off task
+        if self.clocked and not self.one_off:
+            err_msg = 'clocked must be one off, one_off must set True'
+            raise ValidationError(err_msg)
+
     def save(self, *args, **kwargs):
         self.exchange = self.exchange or None
         self.routing_key = self.routing_key or None
@@ -499,6 +555,8 @@ def __str__(self):
             fmt = '{0.name}: {0.crontab}'
         if self.solar:
             fmt = '{0.name}: {0.solar}'
+        if self.clocked:
+            fmt = '{0.name}: {0.clocked}'
         return fmt.format(self)
 
     @property
@@ -509,6 +567,8 @@ def schedule(self):
             return self.crontab.schedule
         if self.solar:
             return self.solar.schedule
+        if self.clocked:
+            return self.clocked.schedule
 
 
 signals.pre_delete.connect(PeriodicTasks.changed, sender=PeriodicTask)
@@ -525,3 +585,7 @@ def schedule(self):
     PeriodicTasks.update_changed, sender=SolarSchedule)
 signals.post_save.connect(
     PeriodicTasks.update_changed, sender=SolarSchedule)
+signals.post_delete.connect(
+    PeriodicTasks.update_changed, sender=ClockedSchedule)
+signals.post_save.connect(
+    PeriodicTasks.update_changed, sender=ClockedSchedule)

django_celery_beat/schedulers.py

@@ -24,9 +24,10 @@
 from .models import (
     PeriodicTask, PeriodicTasks,
     CrontabSchedule, IntervalSchedule,
-    SolarSchedule,
+    SolarSchedule, ClockedSchedule
 )
 from .utils import make_aware
+from .clockedschedule import clocked
 
 try:
     from celery.utils.time import is_naive
@@ -53,6 +54,7 @@ class ModelEntry(ScheduleEntry):
         (schedules.crontab, CrontabSchedule, 'crontab'),
         (schedules.schedule, IntervalSchedule, 'interval'),
         (schedules.solar, SolarSchedule, 'solar'),
+        (clocked, ClockedSchedule, 'clocked')
     )
     save_fields = ['last_run_at', 'total_run_count', 'no_changes']
 

t/unit/test_admin.py

@@ -8,7 +8,8 @@
     PeriodicTask, \
     CrontabSchedule, \
     IntervalSchedule, \
-    SolarSchedule
+    SolarSchedule, \
+    ClockedSchedule
 from django.core.exceptions import ValidationError
 
 
@@ -67,6 +68,7 @@ def test_validate_unique_raises_for_multiple_schedules(self):
             ('crontab', CrontabSchedule()),
             ('interval', IntervalSchedule()),
             ('solar', SolarSchedule()),
+            ('clocked', ClockedSchedule())
         ]
         for options in combinations(schedules, 2):
             with self.assertRaises(ValidationError):
@@ -76,3 +78,4 @@ def test_validate_unique_not_raises(self):
         PeriodicTask(crontab=CrontabSchedule()).validate_unique()
         PeriodicTask(interval=IntervalSchedule()).validate_unique()
         PeriodicTask(solar=SolarSchedule()).validate_unique()
+        PeriodicTask(clocked=ClockedSchedule(), one_off=True).validate_unique()