API Reference

This page documents the main classes and functions available for programmatic interaction with RedBeat.

redbeat.RedBeatSchedulerEntry

This is the primary class for creating and manipulating schedule entries dynamically.

from redbeat import RedBeatSchedulerEntry

Constructor

RedBeatSchedulerEntry(name, task, schedule, args=None, kwargs=None, options=None, enabled=True, app=None)

  • name (str): A unique name for the task.
  • task (str): The name of the Celery task to execute (e.g., 'myapp.tasks.add').
  • schedule (celery.schedules.schedule): A Celery schedule object (schedule, crontab, or redbeat.schedules.rrule).
  • args (list): Positional arguments for the task.
  • kwargs (dict): Keyword arguments for the task.
  • options (dict): Task execution options (e.g., {'queue': 'high_priority'}).
  • enabled (bool): Whether the task is currently enabled.
  • app (Celery): The Celery application instance. This is required for database operations.

Methods

  • .save(): Persists the entry to Redis. This creates or updates the task definition and adds it to the schedule.

  • .delete(): Removes the entry from Redis, including its definition and its place in the schedule.

  • .next(): Advances the entry to its next scheduled run time. It updates last_run_at and total_run_count and reschedules the task in Redis. This is typically called internally by the scheduler but can be used manually.

  • .reschedule(): Updates the entry's position in the schedule based on its current last_run_at time. Useful if you manually alter last_run_at.

Class Methods

  • RedBeatSchedulerEntry.from_key(key, app): Loads a schedule entry from Redis using its full key (e.g., 'redbeat:my-task'). Raises KeyError if not found.

Properties

  • .key: The full Redis key for the entry (e.g., 'redbeat:my-task').
  • .score: The UNIX timestamp (UTC) of the next scheduled run time. This is the value used to sort the entry in the schedule.
  • .due_at: A timezone-aware datetime object for the next scheduled run.

redbeat.RedBeatScheduler

This is the main scheduler class. You typically only interact with it by setting it in your Celery configuration.

# celeryconfig.py
CELERYBEAT_SCHEDULER = 'redbeat.RedBeatScheduler'

redbeat.schedules.rrule

A custom Celery schedule class that implements recurrence rules based on dateutil.rrule.

from redbeat.schedules import rrule

# Schedule a task to run every other day
schedule = rrule('DAILY', interval=2)

# Schedule a task for the last Friday of every month
schedule = rrule('MONTHLY', byweekday='FR(-1)')

It accepts the same parameters as dateutil.rrule, such as:

  • freq: The frequency ('YEARLY', 'MONTHLY', 'WEEKLY', 'DAILY', 'HOURLY', 'MINUTELY', 'SECONDLY').
  • dtstart: A datetime object for the first occurrence.
  • interval: The interval between occurrences.
  • count: The total number of occurrences.
  • until: A datetime object marking the last possible occurrence.
  • byweekday, bymonth, bymonthday, etc. for complex rules.