This document describes the current stable version of Celery (5.6). For development docs, go here.

# `celery.result`

Task results/state and results for groups of tasks.

class celery.result.AsyncResult(id, backend=None, task_name=None, app=None, parent=None)

  Query task state.

  Parameters:

    - id (str) – See `id`.

    - backend (Backend) – See `backend`.

  exception TimeoutError

    Error raised for timeouts.

  app = None
  property args
  as_list()

    Return as a list of task IDs.

  as_tuple()
  backend = None

    The task result backend to use.

  build_graph(intermediate=False, formatter=None)
  property children
  collect(intermediate=False, **kwargs)

    Collect results as they return.

    Iterator, like `get()` will wait for the task to complete, but will also follow `AsyncResult` and `ResultSet` 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 in `result.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.

  failed()

    Return `True` if the task failed.

  forget()

    Forget the result of this task and its parents.

  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'}))

    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()` or `forget()` on EVERY `AsyncResult` instance returned after calling a task.

    Parameters:

      - timeout (float) – How long to wait, in seconds, before the operation times out. This is the setting for the publisher (celery client) and is different from timeout parameter of @app.task, which is the setting for the worker. The task isn’t terminated even if timeout occurs.

      - 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.

  get_leaf()
  property graph
  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.

  iterdeps(intermediate=False)
  property kwargs
  maybe_reraise(propagate=True, callback=None)
  maybe_throw(propagate=True, callback=None)
  property name
  property queue
  ready()

    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)

    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.

  revoke_by_stamped_headers(headers, connection=None, terminate=False, signal=None, wait=False, timeout=None)

    Send revoke signal to all workers only for tasks with matching headers values.

    Any worker receiving the task, or having reserved the task, must ignore it. All header fields must match.

    Parameters:

      - headers (dict[str, Union(str, list)]) – Headers to match when revoking tasks.

      - 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.

  successful()

    Return `True` if the task executed successfully.

  property supports_native_join
  property task_id

    Compat. alias to `id`.

  then(callback, on_error=None, weak=False)
  throw(*args, **kwargs)
  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()` or `forget()` on EVERY `AsyncResult` instance returned after calling a task.

    Parameters:

      - timeout (float) – How long to wait, in seconds, before the operation times out. This is the setting for the publisher (celery client) and is different from timeout parameter of @app.task, which is the setting for the worker. The task isn’t terminated even if timeout occurs.

      - 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

class celery.result.EagerResult(id, ret_value, state, traceback=None, name=None)

  Result that we know has already been executed.

  forget()

    Forget the result of this task and its parents.

  get(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()` or `forget()` on EVERY `AsyncResult` instance returned after calling a task.

    Parameters:

      - timeout (float) – How long to wait, in seconds, before the operation times out. This is the setting for the publisher (celery client) and is different from timeout parameter of @app.task, which is the setting for the worker. The task isn’t terminated even if timeout occurs.

      - 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()

    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)

    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
  then(callback, on_error=None, weak=False)
  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()` or `forget()` on EVERY `AsyncResult` instance returned after calling a task.

    Parameters:

      - timeout (float) – How long to wait, in seconds, before the operation times out. This is the setting for the publisher (celery client) and is different from timeout parameter of @app.task, which is the setting for the worker. The task isn’t terminated even if timeout occurs.

      - 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.

class celery.result.GroupResult(id=None, results=None, parent=None, **kwargs)

  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.

  as_tuple()
  property children
  delete(backend=None)

    Remove this result if it was previously saved.

  id = None

    The UUID of the group.

  classmethod restore(id, backend=None, app=None)

    Restore previously saved group result.

  results = None

    List/iterator of results in the group

  save(backend=None)

    Save group-result for later retrieval using `restore()`.

    Example

        >>> def save_and_restore(result):
        ...     result.save()
        ...     result = GroupResult.restore(result.id)

class celery.result.ResultBase

  Base class for results.

  parent = None

    Parent result (if part of a chain)

class celery.result.ResultSet(results, app=None, ready_barrier=None, **kwargs)

  A collection of results.

  Parameters:

    results (Sequence[AsyncResult]) – List of result instances.

  add(result)

    Add `AsyncResult` as a new member of the set.

    Does nothing if the result is already a member.

  property app
  property backend
  clear()

    Remove all results from this set.

  completed_count()

    Task completion count.

    Note that complete means successful in this context. In other words, the return value of this method is the number of `successful` tasks.

    Returns:

      the number of complete (i.e. successful) tasks.

    Return type:

      int

  discard(result)

    Remove result from the set if it is a member.

    Does nothing if it’s not a member.

  failed()

    Return true if any of the tasks failed.

    Returns:

      true if one of the tasks failed.

        (i.e., raised an exception)

    Return type:

      bool

  forget()

    Forget about (and possible remove the result of) all the tasks.

  get(timeout=None, propagate=True, interval=0.5, callback=None, no_ack=True, on_message=None, disable_sync_subtasks=True, on_interval=None)

    See `join()`.

    This is here for API compatibility with `AsyncResult`, in addition it uses `join_native()` if available for the current result backend.

  iter_native(timeout=None, interval=0.5, no_ack=True, on_message=None, on_interval=None)

    Backend optimized version of `iterate()`.

    Added 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.

  join(timeout=None, propagate=True, interval=0.5, callback=None, no_ack=True, on_message=None, disable_sync_subtasks=True, on_interval=None)

    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’t `None` and the operation takes longer than `timeout` 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)

    Backend optimized version of `join()`.

    Added 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)
  maybe_throw(callback=None, propagate=True)
  ready()

    Did all of the tasks complete? (either by success of failure).

    Returns:

      true if all of the tasks have been executed.

    Return type:

      bool

  remove(result)

    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)

    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()

    Return true if all tasks successful.

    Returns:

      true if all of the tasks finished

        successfully (i.e. didn’t raise an exception).

    Return type:

      bool

  property supports_native_join
  then(callback, on_error=None, weak=False)
  update(results)

    Extend from iterable of results.

  waiting()

    Return true if any of the tasks are incomplete.

    Returns:

      true if one of the tasks are still

        waiting for execution.

    Return type:

      bool

celery.result.result_from_tuple(r, app=None)

  Deserialize result from tuple.