Task¶
The Task class is the base for all celery tasks. Use the @app.task decorator
to create tasks.
Task¶
Task ¶
Task base class.
Note:
When called tasks apply the :meth:run method. This method must
be defined by all tasks (that is unless the :meth:__call__ method
is overridden).
apply_async ¶
apply_async(
args=None,
kwargs=None,
task_id=None,
producer=None,
link=None,
link_error=None,
shadow=None,
**options,
)
Apply tasks asynchronously by sending a message.
Arguments: args (Tuple): The positional arguments to pass on to the task.
kwargs (Dict): The keyword arguments to pass on to the task.
countdown (float): Number of seconds into the future that the
task should execute. Defaults to immediate execution.
eta (~datetime.datetime): Absolute time and date of when the task
should be executed. May not be specified if `countdown`
is also supplied.
expires (float, ~datetime.datetime): Datetime or
seconds in the future for the task should expire.
The task won't be executed after the expiration time.
shadow (str): Override task name used in logs/monitoring.
Default is retrieved from :meth:`shadow_name`.
connection (kombu.Connection): Reuse existing broker connection
instead of acquiring one from the connection pool.
retry (bool): If enabled sending of the task message will be
retried in the event of connection loss or failure.
Default is taken from the :setting:`task_publish_retry`
setting. Note that you need to handle the
producer/connection manually for this to work.
retry_policy (Mapping): Override the retry policy used.
See the :setting:`task_publish_retry_policy` setting.
time_limit (int): If set, overrides the default time limit.
soft_time_limit (int): If set, overrides the default soft
time limit.
queue (str, kombu.Queue): The queue to route the task to.
This must be a key present in :setting:`task_queues`, or
:setting:`task_create_missing_queues` must be
enabled. See :ref:`guide-routing` for more
information.
exchange (str, kombu.Exchange): Named custom exchange to send the
task to. Usually not used in combination with the ``queue``
argument.
routing_key (str): Custom routing key used to route the task to a
worker server. If in combination with a ``queue`` argument
only used to specify custom routing keys to topic exchanges.
priority (int): The task priority, a number between 0 and 9.
Defaults to the :attr:`priority` attribute.
serializer (str): Serialization method to use.
Can be `pickle`, `json`, `yaml`, `msgpack` or any custom
serialization method that's been registered
with :mod:`kombu.serialization.registry`.
Defaults to the :attr:`serializer` attribute.
compression (str): Optional compression method
to use. Can be one of ``zlib``, ``bzip2``,
or any custom compression methods registered with
:func:`kombu.compression.register`.
Defaults to the :setting:`task_compression` setting.
link (Signature): A single, or a list of tasks signatures
to apply if the task returns successfully.
link_error (Signature): A single, or a list of task signatures
to apply if an error occurs while executing the task.
producer (kombu.Producer): custom producer to use when publishing
the task.
add_to_parent (bool): If set to True (default) and the task
is applied while executing another task, then the result
will be appended to the parent tasks ``request.children``
attribute. Trailing can also be disabled by default using the
:attr:`trail` attribute
ignore_result (bool): If set to `False` (default) the result
of a task will be stored in the backend. If set to `True`
the result will not be stored. This can also be set
using the :attr:`ignore_result` in the `app.task` decorator.
publisher (kombu.Producer): Deprecated alias to ``producer``.
headers (Dict): Message headers to be included in the message.
The headers can be used as an overlay for custom labeling
using the :ref:`canvas-stamping` feature.
task_id (str): Optional argument to override the default task id.
By default, Celery generates a unique id (UUID4) for every task
submission. You can instead provide your own string identifier.
If supplied, this value will be used as the task’s id instead
of generating one automatically. Be careful to avoid collisions
when overriding task ids.
Returns: celery.result.AsyncResult: Promise of future evaluation.
Raises:
TypeError: If not enough arguments are passed, or too many
arguments are passed. Note that signature checks may
be disabled by specifying @task(typing=False).
ValueError: If soft_time_limit and time_limit both are set
but soft_time_limit is greater than time_limit
kombu.exceptions.OperationalError: If a connection to the
transport cannot be made, or if the connection is lost.
Note:
Also supports all keyword arguments supported by
:meth:kombu.Producer.publish.
delay ¶
Star argument version of :meth:apply_async.
Does not support the extra options enabled by :meth:apply_async.
Arguments: args (Any): Positional arguments passed on to the task. *kwargs (Any): Keyword arguments passed on to the task. Returns: celery.result.AsyncResult: Future promise.
apply ¶
apply(
args=None,
kwargs=None,
link=None,
link_error=None,
task_id=None,
retries=None,
throw=None,
logfile=None,
loglevel=None,
headers=None,
**options,
)
Execute this task locally, by blocking until the task returns.
Arguments:
args (Tuple): positional arguments passed on to the task.
kwargs (Dict): keyword arguments passed on to the task.
throw (bool): Re-raise task exceptions.
Defaults to the :setting:task_eager_propagates setting.
Returns: celery.result.EagerResult: pre-evaluated result.
retry ¶
retry(
args=None,
kwargs=None,
exc=None,
throw=True,
eta=None,
countdown=None,
max_retries=None,
**options,
)
Retry the task, adding it to the back of the queue.
Example: >>> from imaginary_twitter_lib import Twitter >>> from proj.celery import app
>>> @app.task(bind=True)
... def tweet(self, auth, message):
... twitter = Twitter(oauth=auth)
... try:
... twitter.post_status_update(message)
... except twitter.FailWhale as exc:
... # Retry in 5 minutes.
... raise self.retry(countdown=60 * 5, exc=exc)
Note:
Although the task will never return above as retry raises an
exception to notify the worker, we use raise in front of the
retry to convey that the rest of the block won't be executed.
Arguments:
args (Tuple): Positional arguments to retry with.
kwargs (Dict): Keyword arguments to retry with.
exc (Exception): Custom exception to report when the max retry
limit has been exceeded (default:
:exc:~@MaxRetriesExceededError).
If this argument is set and retry is called while
an exception was raised (``sys.exc_info()`` is set)
it will attempt to re-raise the current exception.
If no exception was raised it will raise the ``exc``
argument provided.
countdown (float): Time in seconds to delay the retry for.
eta (~datetime.datetime): Explicit time and date to run the
retry at.
max_retries (int): If set, overrides the default retry limit for
this execution. Changes to this parameter don't propagate to
subsequent task retry attempts. A value of :const:`None`,
means "use the default", so if you want infinite retries you'd
have to set the :attr:`max_retries` attribute of the task to
:const:`None` first.
time_limit (int): If set, overrides the default time limit.
soft_time_limit (int): If set, overrides the default soft
time limit.
throw (bool): If this is :const:`False`, don't raise the
:exc:`~@Retry` exception, that tells the worker to mark
the task as being retried. Note that this means the task
will be marked as failed if the task raises an exception,
or successful if it returns after the retry call.
**options (Any): Extra options to pass on to :meth:`apply_async`.
Raises:
celery.exceptions.Retry:
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 :const:`False`, and is considered
normal operation.
on_success ¶
Success handler.
Run by the worker if the task executes successfully.
Arguments: retval (Any): The return value of the task. task_id (str): Unique id of the executed task. args (Tuple): Original arguments for the executed task. kwargs (Dict): Original keyword arguments for the executed task.
Returns: None: The return value of this handler is ignored.
on_failure ¶
Error handler.
This is run by the worker when the task fails.
Arguments: exc (Exception): The exception raised by the task. task_id (str): Unique id of the failed task. args (Tuple): Original arguments for the task that failed. kwargs (Dict): Original keyword arguments for the task that failed. einfo (ExceptionInfo): Exception information.
Returns: None: The return value of this handler is ignored.
on_retry ¶
Retry handler.
This is run by the worker when the task is to be retried.
Arguments:
exc (Exception): The exception sent to :meth:retry.
task_id (str): Unique id of the retried task.
args (Tuple): Original arguments for the retried task.
kwargs (Dict): Original keyword arguments for the retried task.
einfo (ExceptionInfo): Exception information.
Returns: None: The return value of this handler is ignored.
after_return ¶
Handler called after the task returns.
Arguments: status (str): Current task state. retval (Any): Task return value/exception. task_id (str): Unique id of the task. args (Tuple): Original arguments for the task. kwargs (Dict): Original keyword arguments for the task. einfo (ExceptionInfo): Exception information.
Returns: None: The return value of this handler is ignored.