This document describes an older version of Celery (2.1). For the latest stable version please go here.
A celery task.
All subclasses of Task must define the run() method, which is the actual method the celery daemon executes.
The run() method can take use of the default keyword arguments, as listed in the run() documentation.
The resulting class is callable, which if called will apply the run() method.
Name of the task.
If True the task is an abstract base class.
The type of task, currently this can be regular, or periodic, however if you want a periodic task, you should subclass PeriodicTask instead.
Select a destination queue for this task. The queue needs to exist in CELERY_QUEUES. The routing_key, exchange and exchange_type attributes will be ignored if this is set.
Override the global default routing_key for this task.
Override the global default exchange for this task.
Override the global default exchange type for this task.
Override the global default delivery mode for this task. By default this is set to 2 (persistent). You can change this to 1 to get non-persistent behavior, which means the messages are lost if the broker is restarted.
Mandatory message routing. An exception will be raised if the task can’t be routed to a queue.
Request immediate delivery. An exception will be raised if the task can’t be routed to a worker immediately.
The message priority. A number from 0 to 9, where 0 is the highest. Note that RabbitMQ doesn’t support priorities yet.
Maximum number of retries before giving up. If set to None, it will never stop retrying.
Default time in seconds before a retry of the task should be executed. Default is a 3 minute delay.
Set the rate limit for this task type, Examples: None (no rate limit), "100/s" (hundred tasks a second), "100/m" (hundred tasks a minute), "100/h" (hundred tasks an hour)
Don’t store the return value of this task.
If true, errors will be stored even if the task is configured to ignore results.
If true, an e-mail will be sent to the admins whenever a task of this type raises an exception.
List of exception types to send error e-mails for.
The name of a serializer that has been registered with carrot.serialization.registry. Example: "json".
The result store backend used for this task.
If True the task is automatically registered in the task registry, which is the default behaviour.
If True the task will report its status as “started” when the task is executed by a worker. The default value is False as the normal behaviour is to not report that level of granularity. Tasks are either pending, finished, or waiting to be retried. Having a “started” status can be useful for when there are long running tasks and there is a need to report which task is currently running.
The global default can be overridden by the CELERY_TRACK_STARTED setting.
If set to True messages for this task will be acknowledged after the task has been executed, not just before, which is the default behavior.
Note that this means the task may be executed twice if the worker crashes in the middle of execution, which may be acceptable for some applications.
The global default can be overriden by the CELERY_ACKS_LATE setting.
Default task expiry time in seconds or a datetime.
Get AsyncResult instance for this kind of task.
Parameters: | task_id – Task id to get result for. |
---|
The tasks max restart limit has been exceeded.
Handler called after the task returns.
Parameters: |
|
---|
The return value of this handler is ignored.
Execute this task locally, by blocking until the task has finished executing.
Parameters: |
|
---|
:rtype celery.result.EagerResult:
Delay this task for execution by the celery daemon(s).
Parameters: |
|
---|
See celery.execute.apply_async() for more information.
:returns celery.result.AsyncResult:
Shortcut to apply_async(), with star arguments, but doesn’t support the extra options.
Parameters: |
|
---|
:returns celery.result.AsyncResult:
Establish a connection to the message broker.
The method the worker calls to execute the task.
Parameters: |
|
---|
Get a celery task message consumer.
:rtype celery.messaging.TaskConsumer:
Please be sure to close the AMQP connection when you’re done with this object. i.e.:
>>> consumer = self.get_consumer()
>>> # do something with consumer
>>> consumer.connection.close()
Get task-aware logger object.
Get a celery task message publisher.
:rtype celery.messaging.TaskPublisher:
Please be sure to close the AMQP connection when you’re done with this object, i.e.:
>>> publisher = self.get_publisher()
>>> # do something with publisher
>>> publisher.connection.close()
Error handler.
This is run by the worker when the task fails.
Parameters: |
|
---|
The return value of this handler is ignored.
Retry handler.
This is run by the worker when the task is to be retried.
Parameters: |
|
---|
The return value of this handler is ignored.
Success handler.
Run by the worker if the task executes successfully.
Parameters: |
|
---|
The return value of this handler is ignored.
Retry the task.
Parameters: |
|
---|---|
Raises celery.exceptions.RetryTaskError: | |
To tell the worker that the task has been re-sent for retry. This always happens, unless the throw keyword argument has been explicitly set to False, and is considered normal operation. |
Example
>>> class TwitterPostStatusTask(Task):
...
... def run(self, username, password, message, **kwargs):
... twitter = Twitter(username, password)
... try:
... twitter.post_status(message)
... except twitter.FailWhale, exc:
... # Retry in 5 minutes.
... self.retry([username, password, message], kwargs,
... countdown=60 * 5, exc=exc)
The body of the task executed by the worker.
The following standard keyword arguments are reserved and is passed by the worker if the function/method supports them:
- task_id
- task_name
- task_retries
- task_is_eager
- logfile
- loglevel
- delivery_info
Additional standard keyword arguments may be added in the future. To take these default arguments, the task can either list the ones it wants explicitly or just take an arbitrary list of keyword arguments (**kwargs).
Returns a subtask object for this task that wraps arguments and execution options for a single task invocation.
Update task state.
Parameters: |
|
---|
A periodic task is a task that behaves like a cron job.
Results of periodic tasks are not stored by default.
REQUIRED Defines how often the task is run (its interval), it can be a timedelta object, a crontab object or an integer specifying the time in seconds.
If set to True, run times are relative to the time when the server was started. This was the previous behaviour, periodic tasks are now scheduled by the clock.
Raises NotImplementedError: | |
---|---|
if the run_every attribute is not defined. |
Example
>>> from celery.task import tasks, PeriodicTask
>>> from datetime import timedelta
>>> class EveryThirtySecondsTask(PeriodicTask):
... run_every = timedelta(seconds=30)
...
... def run(self, **kwargs):
... logger = self.get_logger(**kwargs)
... logger.info("Execute every 30 seconds")
>>> from celery.task import PeriodicTask
>>> from celery.task.schedules import crontab
>>> class EveryMondayMorningTask(PeriodicTask):
... run_every = crontab(hour=7, minute=30, day_of_week=1)
...
... def run(self, **kwargs):
... logger = self.get_logger(**kwargs)
... logger.info("Execute every Monday at 7:30AM.")
>>> class EveryMorningTask(PeriodicTask):
... run_every = crontab(hours=7, minute=30)
...
... def run(self, **kwargs):
... logger = self.get_logger(**kwargs)
... logger.info("Execute every day at 7:30AM.")
>>> class EveryQuarterPastTheHourTask(PeriodicTask):
... run_every = crontab(minute=15)
...
... def run(self, **kwargs):
... logger = self.get_logger(**kwargs)
... logger.info("Execute every 0:15 past the hour every day.")
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.
Returns when the periodic task should run next as a timedelta.
Convert timedelta to seconds.
Doesn’t account for negative timedeltas.
Metaclass for tasks.
Automatically registers the task in the task registry, except if the abstract attribute is set.
If no name attribute is provided, the name is automatically set to the name of the module it was defined in, and the class name.