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

celery

Application

class celery.Celery(main='__main__', broker='amqp://localhost//', ...)

Parameters:

• main – Name of the main module if running as __main__.
• broker – URL of the default broker used.
• loader – The loader class, or the name of the loader class to use. Default is celery.loaders.app.AppLoader.
• backend – The result store backend class, or the name of the backend class to use. Default is the value of the CELERY_RESULT_BACKEND setting.
• amqp – AMQP object or class name.
• events – Events object or class name.
• log – Log object or class name.
• control – Control object or class name.
• set_as_current – Make this the global current app.
• tasks – A task registry or the name of a registry class.

main

Name of the __main__ module. Required for standalone scripts.

If set this will be used instead of __main__ when automatically generating task names.

conf

Current configuration.

current_task

The instance of the task that is being executed, or None.

amqp

AMQP related functionality: amqp.

backend

Current backend instance.

loader

Current loader instance.

control

Remote control: control.

events

Consuming and sending events: events.

log

Logging: log.

tasks

Task registry.

Accessing this attribute will also finalize the app.

pool

Broker connection pool: pool. This attribute is not related to the workers concurrency pool.

Task

Base task class for this app.

close()

Cleans-up after application, like closing any pool connections. Only necessary for dynamically created apps for which you can use the with statement:

with Celery(set_as_current=False) as app:
    with app.connection() as conn:
        pass

bugreport()

Returns a string with information useful for the Celery core developers when reporting a bug.

config_from_object(obj, silent=False)

Reads configuration from object, where object is either an object or the name of a module to import.

Parameters:silent – If true then import errors will be ignored.

>>> celery.config_from_object("myapp.celeryconfig")

>>> from myapp import celeryconfig
>>> celery.config_from_object(celeryconfig)

config_from_envvar(variable_name, silent=False)

Read configuration from environment variable.

The value of the environment variable must be the name of a module to import.

>>> os.environ["CELERY_CONFIG_MODULE"] = "myapp.celeryconfig"
>>> celery.config_from_envvar("CELERY_CONFIG_MODULE")

add_defaults(d)

Add default configuration from dict d.

If the argument is a callable function then it will be regarded as a promise, and it won’t be loaded until the configuration is actually needed.

This method can be compared to:

>>> celery.conf.update(d)

with a difference that 1) no copy will be made and 2) the dict will not be transferred when the worker spawns child processes, so it’s important that the same configuration happens at import time when pickle restores the object on the other side.

start(argv=None)

Run celery using argv.

Uses sys.argv if argv is not specified.

task(fun, ...)

Decorator to create a task class out of any callable.

Examples:

@celery.task
def refresh_feed(url):
    return ...

with setting extra options:

@celery.task(exchange="feeds")
def refresh_feed(url):
    return ...

App Binding

For custom apps the task decorator returns proxy objects, so that the act of creating the task is not performed until the task is used or the task registry is accessed.

If you are depending on binding to be deferred, then you must not access any attributes on the returned object until the application is fully set up (finalized).

send_task(name[, args[, kwargs[, ...]]])

Send task by name.

Parameters:

• name – Name of task to call (e.g. “tasks.add”).
• result_cls – Specify custom result class. Default is using AsyncResult().

Otherwise supports the same arguments as Task.apply_async().

AsyncResult

Create new result instance. See AsyncResult.

GroupResult

Create new taskset result instance. See GroupResult.

worker_main(argv=None)

Run celeryd using argv.

Uses sys.argv if argv is not specified.”“”

Worker

Worker application. See Worker.

WorkController

Embeddable worker. See WorkController.

Beat

Celerybeat scheduler application. See Beat.

connection(url=default[, ssl[, transport_options={}]])

Establish a connection to the message broker.

Parameters:

• url – Either the URL or the hostname of the broker to use.
• hostname – URL, Hostname/IP-address of the broker. If an URL is used, then the other argument below will be taken from the URL instead.
• userid – Username to authenticate as.
• password – Password to authenticate with
• virtual_host – Virtual host to use (domain).
• port – Port to connect to.
• ssl – Defaults to the BROKER_USE_SSL setting.
• transport – defaults to the BROKER_TRANSPORT setting.

:returns kombu.connection.Connection:

connection_or_acquire(connection=None)

For use within a with-statement to get a connection from the pool if one is not already provided.

Parameters:connection – If not provided, then a connection will be acquired from the connection pool.

producer_or_acquire(producer=None)

For use within a with-statement to get a producer from the pool if one is not already provided

Parameters:producer – If not provided, then a producer will be acquired from the producer pool.

mail_admins(subject, body, fail_silently=False)

Sends an email to the admins in the ADMINS setting.

select_queues(queues=[])

Select a subset of queues, where queues must be a list of queue names to keep.

now()

Returns the current time and date as a datetime object.

set_current()

Makes this the current app for this thread.

finalize()

Finalizes the app by loading built-in tasks, and evaluating pending task decorators

Pickler

Helper class used to pickle this application.

Grouping Tasks

class celery.group(task1[, task2[, task3[, ... taskN]]])

Creates a group of tasks to be executed in parallel.

Example:

>>> res = group([add.s(2, 2), add.s(4, 4)]).apply_async()
>>> res.get()
[4, 8]

The apply_async method returns GroupResult.

class celery.chain(task1[, task2[, task3[, ... taskN]]])

Chains tasks together, so that each tasks follows each other by being applied as a callback of the previous task.

If called with only one argument, then that argument must be an iterable of tasks to chain.

Example:

>>> res = chain(add.s(2, 2), add.s(4)).apply_async()

is effectively :

>>> res.get()
8

Calling a chain will return the result of the last task in the chain. You can get to the other tasks by following the result.parent‘s:

>>> res.parent.get()
4

class celery.chord(header[, body])

A chord consists of a header and a body. The header is a group of tasks that must complete before the callback is called. A chord is essentially a callback for a group of tasks.

Example:

>>> res = chord([add.s(2, 2), add.s(4, 4)])(sum_task.s())

is effectively :

>>> res.get()
12

The body is applied with the return values of all the header tasks as a list.

class celery.subtask(task=None, args=(), kwargs={}, options={})

Describes the arguments and execution options for a single task invocation.

Used as the parts in a group or to safely pass tasks around as callbacks.

Subtasks can also be created from tasks:

>>> add.subtask(args=(), kwargs={}, options={})

or the .s() shortcut:

>>> add.s(*args, **kwargs)

Parameters:

• task – Either a task class/instance, or the name of a task.
• args – Positional arguments to apply.
• kwargs – Keyword arguments to apply.
• options – Additional options to Task.apply_async().

Note that if the first argument is a dict, the other arguments will be ignored and the values in the dict will be used instead.

>>> s = subtask("tasks.add", args=(2, 2))
>>> subtask(s)
{"task": "tasks.add", args=(2, 2), kwargs={}, options={}}

delay(*args, **kwargs)

Shortcut to apply_async().

apply_async(args=(), kwargs={}, ...)

Apply this task asynchronously.

Parameters:

• args – Partial args to be prepended to the existing args.
• kwargs – Partial kwargs to be merged with the existing kwargs.
• options – Partial options to be merged with the existing options.

See apply_async().

apply(args=(), kwargs={}, ...)

Same as apply_async() but executed the task inline instead of sending a task message.

clone(args=(), kwargs={}, ...)

Returns a copy of this subtask.

Parameters:

• args – Partial args to be prepended to the existing args.
• kwargs – Partial kwargs to be merged with the existing kwargs.
• options – Partial options to be merged with the existing options.

replace(args=None, kwargs=None, options=None)

Replace the args, kwargs or options set for this subtask. These are only replaced if the selected is not None.

link(other_subtask)

Add a callback task to be applied if this task executes successfully.

Returns:other_subtask (to work with reduce()).

link_error(other_subtask)

Add a callback task to be applied if an error occurs while executing this task.

Returns:other_subtask (to work with reduce())

set(...)

Set arbitrary options (same as .options.update(...)).

This is a chaining method call (i.e. it returns itself).

flatten_links()

Gives a recursive list of dependencies (unchain if you will, but with links intact).

Proxies

celery.current_app

The currently set app for this thread.

celery.current_task

The task currently being executed (only set in the worker, or when eager/apply is used).