This document describes an older version of Celery (2.1). For the latest stable version please go here.

Periodic Task Schedule Behaviors - celery.schedules

class celery.schedules.crontab(minute='*', hour='*', day_of_week='*', nowfun=<built-in method now of type object at 0x7f7039be5c40>)

A crontab can be used as the run_every value of a PeriodicTask to add cron-like scheduling.

Like a cron job, you can specify units of time of when you would like the task to execute. It is a reasonably complete implementation of cron’s features, so it should provide a fair degree of scheduling needs.

You can specify a minute, an hour, and/or a day of the week in any of the following formats:

minute
  • A (list of) integers from 0-59 that represent the minutes of an hour of when execution should occur; or
  • A string representing a crontab pattern. This may get pretty advanced, like minute=”*/15” (for every quarter) or minute=”1,13,30-45,50-59/2”.
hour
  • A (list of) integers from 0-23 that represent the hours of a day of when execution should occur; or
  • A string representing a crontab pattern. This may get pretty advanced, like hour=”*/3” (for every three hours) or hour=”0,8-17/2” (at midnight, and every two hours during office hours).
day_of_week
  • A (list of) integers from 0-6, where Sunday = 0 and Saturday = 6, that represent the days of a week that execution should occur.
  • A string representing a crontab pattern. This may get pretty advanced, like day_of_week=”mon-fri” (for weekdays only). (Beware that day_of_week=”*/2” does not literally mean “every two days”, but “every day that is divisible by two”!)
is_due(last_run_at)

Returns tuple of two items (is_due, next_time_to_run), where next time to run is in seconds.

See celery.schedules.schedule.is_due() for more information.

remaining_estimate(last_run_at)

Returns when the periodic task should run next as a timedelta.

class celery.schedules.crontab_parser(max_=60)

Parser for crontab expressions. Any expression of the form ‘groups’ (see BNF grammar below) is accepted and expanded to a set of numbers. These numbers represent the units of time that the crontab needs to run on:

digit   :: '0'..'9'
dow     :: 'a'..'z'
number  :: digit+ | dow+
steps   :: number
range   :: number ( '-' number ) ?
numspec :: '*' | range
expr    :: numspec ( '/' steps ) ?
groups  :: expr ( ',' expr ) *

The parser is a general purpose one, useful for parsing hours, minutes and day_of_week expressions. Example usage:

>>> minutes = crontab_parser(60).parse("*/15")
[0, 15, 30, 45]
>>> hours = crontab_parser(24).parse("*/4")
[0, 4, 8, 12, 16, 20]
>>> day_of_week = crontab_parser(7).parse("*")
[0, 1, 2, 3, 4, 5, 6]
parse(cronspec)
celery.schedules.maybe_schedule(s, relative=False)
class celery.schedules.schedule(run_every=None, relative=False)
is_due(last_run_at)

Returns tuple of two items (is_due, next_time_to_run), where next time to run is in seconds.

e.g.

  • (True, 20), means the task should be run now, and the next

    time to run is in 20 seconds.

  • (False, 12), means the task should be run in 12 seconds.

You can override this to decide the interval at runtime, but keep in mind the value of CELERYBEAT_MAX_LOOP_INTERVAL, which decides the maximum number of seconds celerybeat can sleep between re-checking the periodic task intervals. So if you dynamically change the next run at value, and the max interval is set to 5 minutes, it will take 5 minutes for the change to take effect, so you may consider lowering the value of CELERYBEAT_MAX_LOOP_INTERVAL if responsiveness is of importance to you.

relative = False
remaining_estimate(last_run_at)

Returns when the periodic task should run next as a timedelta.

Previous topic

HTTP Callback Tasks - celery.task.http

Next topic

Signals - celery.signals

This Page