This document describes an older version of Celery (2.5). For the latest stable version please go here.
The task implementation has been moved to celery.app.task.
copyright: |
|
---|---|
license: | BSD, see LICENSE for more details. |
Task base class.
When called tasks apply the run() method. This method must be defined by all tasks (that is unless the __call__() method is overridden).
Get AsyncResult instance for this kind of task.
Parameters: | task_id – Task id to get result for. |
---|
Defines how and when task error e-mails should be sent.
Parameters: | task – The task instance that raised the error. |
---|
subject and body are format strings which are passed a context containing the following keys:
name
Name of the task.
id
UUID of the task.
exc
String representation of the exception.
args
Positional arguments.
kwargs
Keyword arguments.
traceback
String representation of the traceback.
hostname
Worker hostname.
Returns true or false depending on if a task error mail should be sent for this type of error.
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 returns.
Parameters: |
|
---|
:rtype celery.result.EagerResult:
Apply tasks asynchronously by sending a message.
Parameters: |
|
---|
Note
If the CELERY_ALWAYS_EAGER setting is set, it will be replaced by a local apply() call instead.
Star argument version of apply_async().
Does not support the extra options enabled by apply_async().
Parameters: |
|
---|
:returns celery.result.AsyncResult:
Establish a connection to the message broker.
The method the worker calls to execute the task.
Parameters: |
---|
Get message consumer.
:rtype kombu.messaging.Consumer:
Warning
If you don’t specify a connection, one will automatically be established for you, in that case you need to close this connection after use:
>>> consumer = self.get_consumer()
>>> # do something with consumer
>>> consumer.close()
>>> consumer.connection.close()
Get task-aware logger object.
Get a celery task message publisher.
:rtype TaskPublisher:
Warning
If you don’t specify a connection, one will automatically be established for you, in that case you need to close this connection after use:
>>> publisher = self.get_publisher()
>>> # ... do something with publisher
>>> publisher.connection.close()
or used as a context:
>>> with self.get_publisher() as publisher:
... # ... do something with publisher
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
>>> @task
>>> def tweet(auth, message):
... twitter = Twitter(oauth=auth)
... try:
... twitter.post_status_update(message)
... except twitter.FailWhale, exc:
... # Retry in 5 minutes.
... return tweet.retry(countdown=60 * 5, exc=exc)
Although the task will never return above as retry raises an exception to notify the worker, we use return in front of the retry to convey that the rest of the block will not be executed.
The body of the task executed by workers.
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.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.
Meta class for tasks.
Automatically registers the task in the task registry, except if the abstract attribute is set.
If no name attribute is provided, then no name is automatically set to the name of the module it was defined in, and the class name.