This document describes Celery 2.4. For development docs, go here.
celery.result¶
celery.result¶
Task results/state and groups of results.
copyright: |
|
---|---|
license: | BSD, see LICENSE for more details. |
-
class
celery.result.
AsyncResult
(task_id, backend=None, task_name=None, app=None)¶ Pending task result using the default backend.
Parameters: task_id – The task uuid. -
backend
= None¶ Task result store backend to use.
-
-
class
celery.result.
BaseAsyncResult
(task_id, backend, task_name=None, app=None)¶ Base class for pending result, supports custom task result backend.
Parameters: -
exception
TimeoutError
¶ Error raised for timeouts.
-
BaseAsyncResult.
backend
= None¶ The task result backend to use.
-
BaseAsyncResult.
failed
()¶ Returns
True
if the task failed.
-
BaseAsyncResult.
forget
()¶ Forget about (and possibly remove the result of) this task.
-
BaseAsyncResult.
get
(timeout=None, propagate=True, interval=0.5)¶ 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.
Parameters: - timeout – How long to wait, in seconds, before the operation times out.
- propagate – Re-raise exception if the task failed.
- interval – Time to wait (in seconds) before retrying to retrieve the result. Note that this does not have any effect when using the AMQP result store backend, as it does not use polling.
Raises celery.exceptions.TimeoutError: if timeout is not
None
and the result does not arrive within timeout seconds.If the remote call raised an exception then that exception will be re-raised.
-
BaseAsyncResult.
ready
()¶ Returns
True
if the task has been executed.If the task is still running, pending, or is waiting for retry then
False
is returned.
-
BaseAsyncResult.
result
¶ When the task has been executed, this contains the return value. If the task raised an exception, this will be the exception instance.
-
BaseAsyncResult.
revoke
(connection=None, connect_timeout=None)¶ Send revoke signal to all workers.
Any worker receiving the task, or having reserved the task, must ignore it.
-
BaseAsyncResult.
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. Theresult
attribute then contains the exception raised by the task.SUCCESS
The task executed successfully. Theresult
attribute then contains the tasks return value.
-
BaseAsyncResult.
successful
()¶ Returns
True
if the task executed successfully.
-
BaseAsyncResult.
task_id
= None¶ The task uuid.
-
BaseAsyncResult.
traceback
¶ Get the traceback of a failed task.
-
exception
-
class
celery.result.
EagerResult
(task_id, ret_value, state, traceback=None)¶ Result that we know has already been executed.
-
exception
TimeoutError
¶ The operation timed out.
-
EagerResult.
get
(timeout=None, propagate=True, **kwargs)¶ Wait until the task has been executed and return its result.
-
EagerResult.
ready
()¶ Returns
True
if the task has been executed.
-
EagerResult.
result
¶ The tasks return value
-
EagerResult.
revoke
()¶
-
EagerResult.
state
¶ The tasks state.
-
EagerResult.
successful
()¶ Returns
True
if the task executed without failure.
-
EagerResult.
traceback
¶ The traceback if the task failed.
-
exception
-
class
celery.result.
ResultSet
(results, app=None, **kwargs)¶ Working with more than one result.
Parameters: results – List of result instances. -
add
(result)¶ Add
AsyncResult
as a new member of the set.Does nothing if the result is already a member.
-
clear
()¶ Remove all results from this set.
-
completed_count
()¶ Task completion count.
Returns: the number of tasks completed.
-
discard
(result)¶ Remove result from the set if it is a member.
If it is not a member, do nothing.
-
failed
()¶ Did any of the tasks fail?
Returns: True
if any of the tasks failed. (i.e., raised an exception)
-
forget
()¶ Forget about (and possible remove the result of) all the tasks.
-
iter_native
(timeout=None, interval=None)¶ 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)¶ Iterate over the return values of the tasks as they finish one by one.
Raises: The exception if any of the tasks raised an exception.
-
join
(timeout=None, propagate=True, interval=0.5)¶ Gathers 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 – The number of seconds to wait for results before the operation times out.
- propagate – If any of the tasks raises an exception, the exception will be re-raised.
- interval – 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.
Raises celery.exceptions.TimeoutError: if timeout is not
None
and the operation takes longer than timeout seconds.
-
join_native
(timeout=None, propagate=True, interval=0.5)¶ 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.
-
ready
()¶ Did all of the tasks complete? (either by success of failure).
Returns: True
if all of the tasks been executed.
-
remove
(result)¶ Removes result from the set; it must be a member.
Raises KeyError: if the result is not a member.
-
results
= None¶ List of results in in the set.
-
revoke
(connection=None, connect_timeout=None)¶ Revoke all tasks in the set.
-
successful
()¶ Was all of the tasks successful?
Returns: True
if all of the tasks finished successfully (i.e. did not raise an exception).
-
total
¶ Total number of tasks in the set.
-
update
(results)¶ Update set with the union of itself and an iterable with results.
-
waiting
()¶ Are any of the tasks incomplete?
Returns: True
if any of the tasks is still waiting for execution.
-
-
class
celery.result.
TaskSetResult
(taskset_id, results=None, **kwargs)¶ An instance of this class is returned by TaskSet‘s
apply_async()
method.It enables inspection of the tasks state and return values as a single entity.
Parameters: - taskset_id – The id of the taskset.
- results – List of result instances.
-
delete
(backend=None)¶ Remove this result if it was previously saved.
-
itersubtasks
()¶ Depreacted. Use
iter(self.results)
instead.
-
classmethod
restore
(taskset_id, backend=None)¶ Restore previously saved taskset result.
-
results
= None¶ List/iterator of results in the taskset
-
save
(backend=None)¶ Save taskset result for later retrieval using
restore()
.Example:
>>> result.save() >>> result = TaskSetResult.restore(taskset_id)
-
taskset_id
= None¶ The UUID of the taskset.