This document describes the current stable version of Celery (4.4). For development docs, go here.
celery.result
¶
Task results/state and results for groups of tasks.
-
class
celery.result.
ResultBase
[source]¶ Base class for results.
-
parent
= None¶ Parent result (if part of a chain)
-
-
class
celery.result.
AsyncResult
(id, backend=None, task_name=None, app=None, parent=None)[source]¶ Query task state.
-
exception
TimeoutError
¶ The operation timed out.
-
app
= None¶
-
property
args
¶
-
backend
= None¶ The task result backend to use.
-
property
children
¶
-
collect
(intermediate=False, **kwargs)[source]¶ Collect results as they return.
Iterator, like
get()
will wait for the task to complete, but will also followAsyncResult
andResultSet
returned by the task, yielding(result, value)
tuples for each result in the tree.An example would be having the following tasks:
from celery import group from proj.celery import app @app.task(trail=True) def A(how_many): return group(B.s(i) for i in range(how_many))() @app.task(trail=True) def B(i): return pow2.delay(i) @app.task(trail=True) def pow2(i): return i ** 2
>>> from celery.result import ResultBase >>> from proj.tasks import A >>> result = A.delay(10) >>> [v for v in result.collect() ... if not isinstance(v, (ResultBase, tuple))] [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
Note
The
Task.trail
option must be enabled so that the list of children is stored inresult.children
. This is the default but enabled explicitly for illustration.- Yields
Tuple[AsyncResult, Any] – tuples containing the result instance of the child task, and the return value of that task.
-
property
date_done
¶ UTC date and time.
-
get
(timeout=None, propagate=True, interval=0.5, no_ack=True, follow_parents=True, callback=None, on_message=None, on_interval=None, disable_sync_subtasks=True, EXCEPTION_STATES=frozenset({'FAILURE', 'RETRY', 'REVOKED'}), PROPAGATE_STATES=frozenset({'FAILURE', 'REVOKED'}))[source]¶ Wait until task is ready, and return its result.
Warning
Waiting for tasks within a task may lead to deadlocks. Please read Avoid launching synchronous subtasks.
Warning
Backends use resources to store and transmit results. To ensure that resources are released, you must eventually call
get()
orforget()
on EVERYAsyncResult
instance returned after calling a task.- Parameters
timeout (float) – How long to wait, in seconds, before the operation times out.
propagate (bool) – Re-raise exception if the task failed.
interval (float) – Time to wait (in seconds) before retrying to retrieve the result. Note that this does not have any effect when using the RPC/redis result store backends, as they don’t use polling.
no_ack (bool) – Enable amqp no ack (automatically acknowledge message). If this is
False
then the message will not be acked.follow_parents (bool) – Re-raise any exception raised by parent tasks.
disable_sync_subtasks (bool) – Disable tasks to wait for sub tasks this is the default configuration. CAUTION do not enable this unless you must.
- Raises
celery.exceptions.TimeoutError – if timeout isn’t
None
and the result does not arrive within timeout seconds.Exception – If the remote call raised an exception then that exception will be re-raised in the caller process.
-
id
= None¶ The task’s UUID.
-
property
ignored
¶ If True, task result retrieval is disabled.
-
property
info
¶ Task return value.
Note
When the task has been executed, this contains the return value. If the task raised an exception, this will be the exception instance.
-
property
kwargs
¶
-
maybe_reraise
(propagate=True, callback=None)¶
-
property
name
¶
-
property
queue
¶
-
ready
()[source]¶ Return
True
if the task has executed.If the task is still running, pending, or is waiting for retry then
False
is returned.
-
property
result
¶ Task return value.
Note
When the task has been executed, this contains the return value. If the task raised an exception, this will be the exception instance.
-
property
retries
¶
-
revoke
(connection=None, terminate=False, signal=None, wait=False, timeout=None)[source]¶ Send revoke signal to all workers.
Any worker receiving the task, or having reserved the task, must ignore it.
- Parameters
terminate (bool) – Also terminate the process currently working on the task (if any).
signal (str) – Name of signal to send to process if terminate. Default is TERM.
wait (bool) – Wait for replies from workers. The
timeout
argument specifies the seconds to wait. Disabled by default.timeout (float) – Time in seconds to wait for replies when
wait
is enabled.
-
property
state
¶ The tasks current state.
Possible values includes:
PENDING
The task is waiting for execution.
STARTED
The task has been started.
RETRY
The task is to be retried, possibly because of failure.
FAILURE
The task raised an exception, or has exceeded the retry limit. The
result
attribute then contains the exception raised by the task.SUCCESS
The task executed successfully. The
result
attribute then contains the tasks return value.
-
property
status
¶ The tasks current state.
Possible values includes:
PENDING
The task is waiting for execution.
STARTED
The task has been started.
RETRY
The task is to be retried, possibly because of failure.
FAILURE
The task raised an exception, or has exceeded the retry limit. The
result
attribute then contains the exception raised by the task.SUCCESS
The task executed successfully. The
result
attribute then contains the tasks return value.
-
property
supports_native_join
¶
-
property
traceback
¶ Get the traceback of a failed task.
-
wait
(timeout=None, propagate=True, interval=0.5, no_ack=True, follow_parents=True, callback=None, on_message=None, on_interval=None, disable_sync_subtasks=True, EXCEPTION_STATES=frozenset({'FAILURE', 'RETRY', 'REVOKED'}), PROPAGATE_STATES=frozenset({'FAILURE', 'REVOKED'}))¶ Wait until task is ready, and return its result.
Warning
Waiting for tasks within a task may lead to deadlocks. Please read Avoid launching synchronous subtasks.
Warning
Backends use resources to store and transmit results. To ensure that resources are released, you must eventually call
get()
orforget()
on EVERYAsyncResult
instance returned after calling a task.- Parameters
timeout (float) – How long to wait, in seconds, before the operation times out.
propagate (bool) – Re-raise exception if the task failed.
interval (float) – Time to wait (in seconds) before retrying to retrieve the result. Note that this does not have any effect when using the RPC/redis result store backends, as they don’t use polling.
no_ack (bool) – Enable amqp no ack (automatically acknowledge message). If this is
False
then the message will not be acked.follow_parents (bool) – Re-raise any exception raised by parent tasks.
disable_sync_subtasks (bool) – Disable tasks to wait for sub tasks this is the default configuration. CAUTION do not enable this unless you must.
- Raises
celery.exceptions.TimeoutError – if timeout isn’t
None
and the result does not arrive within timeout seconds.Exception – If the remote call raised an exception then that exception will be re-raised in the caller process.
-
property
worker
¶
-
exception
-
class
celery.result.
ResultSet
(results, app=None, ready_barrier=None, **kwargs)[source]¶ A collection of results.
- Parameters
results (Sequence[AsyncResult]) – List of result instances.
-
add
(result)[source]¶ Add
AsyncResult
as a new member of the set.Does nothing if the result is already a member.
-
property
app
¶
-
property
backend
¶
-
completed_count
()[source]¶ Task completion count.
- Returns
the number of tasks completed.
- Return type
-
discard
(result)[source]¶ Remove result from the set if it is a member.
Does nothing if it’s not a member.
-
failed
()[source]¶ Return true if any of the tasks failed.
- Returns
- true if one of the tasks failed.
(i.e., raised an exception)
- Return type
-
get
(timeout=None, propagate=True, interval=0.5, callback=None, no_ack=True, on_message=None, disable_sync_subtasks=True, on_interval=None)[source]¶ See
join()
.This is here for API compatibility with
AsyncResult
, in addition it usesjoin_native()
if available for the current result backend.
-
iter_native
(timeout=None, interval=0.5, no_ack=True, on_message=None, on_interval=None)[source]¶ Backend optimized version of
iterate()
.New in version 2.2.
Note that this does not support collecting the results for different task types using different backends.
This is currently only supported by the amqp, Redis and cache result backends.
-
iterate
(timeout=None, propagate=True, interval=0.5)[source]¶ Deprecated method, use
get()
with a callback argument.
-
join
(timeout=None, propagate=True, interval=0.5, callback=None, no_ack=True, on_message=None, disable_sync_subtasks=True, on_interval=None)[source]¶ Gather the results of all tasks as a list in order.
Note
This can be an expensive operation for result store backends that must resort to polling (e.g., database).
You should consider using
join_native()
if your backend supports it.Warning
Waiting for tasks within a task may lead to deadlocks. Please see Avoid launching synchronous subtasks.
- Parameters
timeout (float) – The number of seconds to wait for results before the operation times out.
propagate (bool) – If any of the tasks raises an exception, the exception will be re-raised when this flag is set.
interval (float) – Time to wait (in seconds) before retrying to retrieve a result from the set. Note that this does not have any effect when using the amqp result store backend, as it does not use polling.
callback (Callable) – Optional callback to be called for every result received. Must have signature
(task_id, value)
No results will be returned by this function if a callback is specified. The order of results is also arbitrary when a callback is used. To get access to the result object for a particular id you’ll have to generate an index first:index = {r.id: r for r in gres.results.values()}
Or you can create new result objects on the fly:result = app.AsyncResult(task_id)
(both will take advantage of the backend cache anyway).no_ack (bool) – Automatic message acknowledgment (Note that if this is set to
False
then the messages will not be acknowledged).disable_sync_subtasks (bool) – Disable tasks to wait for sub tasks this is the default configuration. CAUTION do not enable this unless you must.
- Raises
celery.exceptions.TimeoutError – if
timeout
isn’tNone
and the operation takes longer thantimeout
seconds.
-
join_native
(timeout=None, propagate=True, interval=0.5, callback=None, no_ack=True, on_message=None, on_interval=None, disable_sync_subtasks=True)[source]¶ Backend optimized version of
join()
.New in version 2.2.
Note that this does not support collecting the results for different task types using different backends.
This is currently only supported by the amqp, Redis and cache result backends.
-
maybe_reraise
(callback=None, propagate=True)¶
-
ready
()[source]¶ Did all of the tasks complete? (either by success of failure).
- Returns
true if all of the tasks have been executed.
- Return type
-
remove
(result)[source]¶ Remove result from the set; it must be a member.
- Raises
KeyError – if the result isn’t a member.
-
results
= None¶ List of results in in the set.
-
revoke
(connection=None, terminate=False, signal=None, wait=False, timeout=None)[source]¶ Send revoke signal to all workers for all tasks in the set.
- Parameters
terminate (bool) – Also terminate the process currently working on the task (if any).
signal (str) – Name of signal to send to process if terminate. Default is TERM.
wait (bool) – Wait for replies from worker. The
timeout
argument specifies the number of seconds to wait. Disabled by default.timeout (float) – Time in seconds to wait for replies when the
wait
argument is enabled.
-
successful
()[source]¶ Return true if all tasks successful.
- Returns
- true if all of the tasks finished
successfully (i.e. didn’t raise an exception).
- Return type
-
property
supports_native_join
¶
-
class
celery.result.
GroupResult
(id=None, results=None, parent=None, **kwargs)[source]¶ Like
ResultSet
, but with an associated id.This type is returned by
group
.It enables inspection of the tasks state and return values as a single entity.
- Parameters
id (str) – The id of the group.
results (Sequence[AsyncResult]) – List of result instances.
parent (ResultBase) – Parent result of this group.
-
property
children
¶
-
id
= None¶ The UUID of the group.
-
results
= None¶ List/iterator of results in the group
-
class
celery.result.
EagerResult
(id, ret_value, state, traceback=None)[source]¶ Result that we know has already been executed.
-
get
(timeout=None, propagate=True, disable_sync_subtasks=True, **kwargs)[source]¶ Wait until task is ready, and return its result.
Warning
Waiting for tasks within a task may lead to deadlocks. Please read Avoid launching synchronous subtasks.
Warning
Backends use resources to store and transmit results. To ensure that resources are released, you must eventually call
get()
orforget()
on EVERYAsyncResult
instance returned after calling a task.- Parameters
timeout (float) – How long to wait, in seconds, before the operation times out.
propagate (bool) – Re-raise exception if the task failed.
interval (float) – Time to wait (in seconds) before retrying to retrieve the result. Note that this does not have any effect when using the RPC/redis result store backends, as they don’t use polling.
no_ack (bool) – Enable amqp no ack (automatically acknowledge message). If this is
False
then the message will not be acked.follow_parents (bool) – Re-raise any exception raised by parent tasks.
disable_sync_subtasks (bool) – Disable tasks to wait for sub tasks this is the default configuration. CAUTION do not enable this unless you must.
- Raises
celery.exceptions.TimeoutError – if timeout isn’t
None
and the result does not arrive within timeout seconds.Exception – If the remote call raised an exception then that exception will be re-raised in the caller process.
-
ready
()[source]¶ Return
True
if the task has executed.If the task is still running, pending, or is waiting for retry then
False
is returned.
-
property
result
¶ The tasks return value.
-
revoke
(*args, **kwargs)[source]¶ Send revoke signal to all workers.
Any worker receiving the task, or having reserved the task, must ignore it.
- Parameters
terminate (bool) – Also terminate the process currently working on the task (if any).
signal (str) – Name of signal to send to process if terminate. Default is TERM.
wait (bool) – Wait for replies from workers. The
timeout
argument specifies the seconds to wait. Disabled by default.timeout (float) – Time in seconds to wait for replies when
wait
is enabled.
-
property
state
¶ The tasks state.
-
property
status
¶ The tasks state.
-
property
supports_native_join
¶
-
property
traceback
¶ The traceback if the task failed.
-
wait
(timeout=None, propagate=True, disable_sync_subtasks=True, **kwargs)¶ Wait until task is ready, and return its result.
Warning
Waiting for tasks within a task may lead to deadlocks. Please read Avoid launching synchronous subtasks.
Warning
Backends use resources to store and transmit results. To ensure that resources are released, you must eventually call
get()
orforget()
on EVERYAsyncResult
instance returned after calling a task.- Parameters
timeout (float) – How long to wait, in seconds, before the operation times out.
propagate (bool) – Re-raise exception if the task failed.
interval (float) – Time to wait (in seconds) before retrying to retrieve the result. Note that this does not have any effect when using the RPC/redis result store backends, as they don’t use polling.
no_ack (bool) – Enable amqp no ack (automatically acknowledge message). If this is
False
then the message will not be acked.follow_parents (bool) – Re-raise any exception raised by parent tasks.
disable_sync_subtasks (bool) – Disable tasks to wait for sub tasks this is the default configuration. CAUTION do not enable this unless you must.
- Raises
celery.exceptions.TimeoutError – if timeout isn’t
None
and the result does not arrive within timeout seconds.Exception – If the remote call raised an exception then that exception will be re-raised in the caller process.
-