This document describes the current stable version of Celery (5.7). For development docs, go here.

celery.beat

The periodic task scheduler.

class celery.beat.BeatPidbox(service)

Remote-control mailbox node for beat.

Binds a celerybeat@hostname node to the same celery.pidbox fanout exchange the workers use, so that celery inspect ping (optionally with --destination) also reaches beat.

Only the ping command is implemented; any other broadcast command is ignored silently, since replying with an error would pollute the output of worker-only commands like inspect active.

The node stops answering once the scheduler has not ticked for max_tick_age seconds. Staying silent is the only signal a probe can act on: celery inspect exits non-zero when no node replies, but an error reply still counts as a reply and leaves the exit status at zero.

fanout_support()

Return (supported, transport_name) for the read transport.

Reads the transport’s declared capabilities, so no connection is opened and this is safe to call before starting the thread. The name comes back with the answer rather than from a second throwaway connection built to format the warning.

first_connection_attempt

the first attempt is governed by broker_connection_retry_on_startup, later ones by broker_connection_retry.

Type:

mirrors the worker

is_stale()

join_timeout = 3.0

seconds to wait for the thread to terminate in stop().

property max_tick_age

Seconds a tick may be overdue before beat stops replying.

Falls back to twice the interval the scheduler actually settled on – which a scheduler class may choose itself, so it is not always beat_max_loop_interval – with min_tick_age as a floor. 0 disables the check.

The service records that interval on the main thread once the scheduler exists, because the scheduler is a lazy attribute and this runs on the consumer thread, which must not build it.

min_tick_age = 60.0

floor for the derived max_tick_age. A scheduler with a short loop interval (django-celery-beat’s is five seconds) would otherwise get a window so tight that one slow pass looks like a stall, and on a liveness probe that means restart loops.

on_message(body, message)

retry_interval = 5.0

seconds to pause before reconnecting after an established connection is lost. Establishing a connection is governed by broker_connection_retry and broker_connection_max_retries instead.

start()

stop()

tick_age()

celery.beat.EmbeddedService(app, max_interval=None, **kwargs)

Return embedded clock service.

Parameters:

thread (bool) – Run threaded instead of as a separate process. Uses multiprocessing by default, if available.

class celery.beat.PersistentScheduler(*args, **kwargs)

Scheduler backed by shelve database.

close()

get_schedule()

property info

known_suffixes = ('', '.db', '.dat', '.bak', '.dir')

persistence = <module 'shelve' from '/home/docs/.asdf/installs/python/3.11.15/lib/python3.11/shelve.py'>

property schedule

set_schedule(schedule)

setup_schedule()

sync()

class celery.beat.ScheduleEntry(name=None, task=None, last_run_at=None, total_run_count=None, schedule=None, args=(), kwargs=None, options=None, relative=False, app=None)

An entry in the scheduler.

Parameters:

• name (str) – see name.

• schedule (schedule) – see schedule.

• args (Tuple) – see args.

• kwargs (Dict) – see kwargs.

• options (Dict) – see options.

• last_run_at (datetime) – see last_run_at.

• total_run_count (int) – see total_run_count.

• relative (bool) – Is the time relative to when the server starts?

args = None

Positional arguments to apply.

default_now()

editable_fields_equal(other)

is_due()

See is_due().

kwargs = None

Keyword arguments to apply.

last_run_at = None

The time and date of when this task was last scheduled.

name = None

The task name

next(last_run_at=None)

Return new instance, with date and count fields updated.

options = None

Task execution options.

schedule = None

The schedule (schedule)

total_run_count = 0

Total number of times this task has been scheduled.

update(other)

Update values from another entry.

Will only update “editable” fields:

task, schedule, args, kwargs, options.

class celery.beat.Scheduler(app, schedule=None, max_interval=None, Producer=None, lazy=False, sync_every_tasks=None, **kwargs)

Scheduler for periodic tasks.

The celery beat program may instantiate this class multiple times for introspection purposes, but then with the lazy argument set. It’s important for subclasses to be idempotent when this argument is set.

Parameters:

• schedule (schedule) – see schedule.

• max_interval (int) – see max_interval.

• lazy (bool) – Don’t set up the schedule.

Entry

alias of ScheduleEntry

add(**kwargs)

adjust(n, drift=-0.01)

apply_async(entry, producer=None, advance=True, **kwargs)

apply_entry(entry, producer=None)

close()

property connection

get_schedule()

property info

install_default_entries(data)

is_due(entry)

logger = <Logger celery.beat (WARNING)>

max_interval = 300

Maximum time to sleep between re-checking the schedule.

merge_inplace(b)

populate_heap(event_t=<class 'celery.beat.event_t'>, heapify=<built-in function heapify>)

Populate the heap with the data contained in the schedule.

property producer

reserve(entry)

property schedule

The schedule dict/shelve.

schedules_equal(old_schedules, new_schedules)

send_task(*args, **kwargs)

set_schedule(schedule)

setup_schedule()

should_sync()

sync()

sync_every = 180

How often to sync the schedule (3 minutes by default)

sync_every_tasks = None

How many tasks can be called before a sync is forced.

tick(event_t=<class 'celery.beat.event_t'>, min=<built-in function min>, heappop=<built-in function heappop>, heappush=<built-in function heappush>)

Run a tick - one iteration of the scheduler.

Executes one due task per call.

Returns:

preferred delay in seconds for next call.

Return type:

float

update_from_dict(dict_)

exception celery.beat.SchedulingError

An error occurred while scheduling a task.

class celery.beat.Service(app, max_interval=None, schedule_filename=None, scheduler_cls=None, remote_control=None, hostname=None)

Celery periodic task service.

effective_max_interval

interval the scheduler settled on, recorded once it exists so the pidbox thread never has to build the lazy attribute.

get_scheduler(lazy=False, extension_namespace='celery.beat_schedulers')

property scheduler

scheduler_cls

alias of PersistentScheduler

start(embedded_process=False)

stop(wait=False)

sync()