This document describes Celery 2.4. For development docs, go here.



This module defines the TaskRequest class, which specifies how tasks are executed.

  1. 2009 - 2011 by Ask Solem.

BSD, see LICENSE for more details.

exception celery.worker.job.InvalidTaskError

The task has invalid data or is not properly constructed.

class celery.worker.job.TaskRequest(task_name, task_id, args, kwargs, on_ack=<function noop>, retries=0, delivery_info=None, hostname=None, logger=None, eventer=None, eta=None, expires=None, app=None, taskset_id=None, chord=None, **opts)

A request for task execution.


Acknowledge task.

acknowledged = False

Flag set when the task has been acknowledged.

args = None

List of positional arguments to apply to the task.

chord = None

Body of a chord depending on this task.

delivery_info = None

Additional delivery info, e.g. contains the path from Producer to consumer.

error_msg = ' Task %(name)s[%(id)s] raised exception: %(exc)s\n%(traceback)s\n '

Format string used to log task failure.

eta = None

The tasks eta (for information only).

execute(loglevel=None, logfile=None)

Execute the task in a WorkerTaskTrace.

  • loglevel – The loglevel used by the task.
  • logfile – The logfile used by the task.
execute_using_pool(pool, loglevel=None, logfile=None)

Like execute(), but using the multiprocessing pool.

  • pool – A multiprocessing.Pool instance.
  • loglevel – The loglevel used by the task.
  • logfile – The logfile used by the task.
expires = None

When the task expires.

extend_with_default_kwargs(loglevel, logfile)

Extend the tasks keyword arguments with standard task arguments.

Currently these are logfile, loglevel, task_id, task_name, task_retries, and delivery_info.

See for more information.

Magic keyword arguments are deprecated and will be removed in version 3.0.

classmethod from_message(message, body, on_ack=<function noop>, **kw)

Create request from a task message.

Raises UnknownTaskError:
 if the message does not describe a task, the message is also rejected.
get_instance_attrs(loglevel, logfile)
kwargs = None

Mapping of keyword arguments to apply to the task.


If expired, mark the task as revoked.

message = None

The message object. Used to acknowledge the message.

name = None

Kind of task. Must be a name registered in the task registry.

on_accepted(pid, time_accepted)

Handler called when task is accepted by worker pool.

on_ack = None

Callback called when the task should be acknowledged.


Handler called if the task raised an exception.


Handler called if the task should be retried.


Handler called if the task was successfully processed.

on_timeout(soft, timeout)

Handler called if the task times out.

repr_result(result, maxlen=46)
retries = 0

Number of times the task has been retried.

retry_msg = 'Task %(name)s[%(id)s] retry: %(exc)s'

Format string used to log task retry.


If revoked, skip task and mark state.

send_event(type, **fields)
success_msg = ' Task %(name)s[%(id)s] succeeded in %(runtime)ss: %(return_value)s\n '

Format string used to log task success.

task = None

The task class (set by constructor using task_name).

task_id = None

UUID of the task.

taskset_id = None

UUID of the taskset that this task belongs to.

terminate(pool, signal=None)
time_start = None

Timestamp set when the task is started.

worker_pid = None

Process id of the worker processing this task (if any).

celery.worker.job.WANTED_DELIVERY_INFO = ('exchange', 'routing_key', 'consumer_tag')

Keys to keep from the message delivery info. The values of these keys must be pickleable.

class celery.worker.job.WorkerTaskTrace(*args, **kwargs)

Wraps the task in a jail, catches all exceptions, and saves the status and result of the task execution to the task meta backend.

If the call was successful, it saves the result to the task result backend, and sets the task status to “SUCCESS”.

If the call raises RetryTaskError, it extracts the original exception, uses that as the result and sets the task status to “RETRY”.

If the call results in an exception, it saves the exception as the task result, and sets the task status to “FAILURE”.

  • task_name – The name of the task to execute.
  • task_id – The unique id of the task.
  • args – List of positional args to pass on to the function.
  • kwargs – Keyword arguments mapping to pass on to the function.
  • loader – Custom loader to use, if not specified the current app loader will be used.
  • hostname – Custom hostname to use, if not specified the system hostname will be used.

the evaluated functions return value on success, or the exception instance on failure.


Execute, trace and store the result of the task.

execute_safe(*args, **kwargs)

Same as execute(), but catches errors.

handle_failure(exc, type_, tb, strtb)

Handle exception.

handle_retry(exc, type_, tb, strtb)

Handle retry exception.

handle_success(retval, *args)

Handle successful execution.

hostname = None

Hostname to report as.

loader = None

Current loader.

celery.worker.job.execute_and_trace(task_name, *args, **kwargs)

This is a pickleable method used as a target when applying to pools.

It’s the same as:

>>> WorkerTaskTrace(task_name, *args, **kwargs).execute_safe()