.. py:currentmodule:: django_q

Groups

You can group together results by passing :func:async_task the optional group keyword:

.. code-block:: python

# result group example
from django_q.tasks import async_task, result_group

for i in range(4):
    async_task('math.modf', i, group='modf')

# wait until the group has 4 results
result = result_group('modf', count=4)
print(result)

.. code-block:: python

[(0.0, 0.0), (0.0, 1.0), (0.0, 2.0), (0.0, 3.0)]

Note that this particular example can be achieved much faster with :doc:iterable

Take care to not limit your results database too much and call :func:delete_group before each run, unless you want your results to keep adding up. Instead of :func:result_group you can also use :func:fetch_group to return a queryset of :class:Task objects.:

.. code-block:: python

# fetch group example
from django_q.tasks import fetch_group, count_group, result_group

# count the number of failures
failure_count = count_group('modf', failures=True)

# only use the successes
results = fetch_group('modf')
if failure_count:
    results = results.exclude(success=False)
results =  [task.result for task in successes]

# this is the same as
results = fetch_group('modf', failures=False)
results =  [task.result for task in successes]

# and the same as
results = result_group('modf') # filters failures by default

Getting results by using :func:result_group is of course much faster than using :func:fetch_group, but it doesn't offer the benefits of Django's queryset functions.

.. note::

Calling Queryset.values for the result on Django 1.7 or lower will return a list of encoded results. If you can't upgrade to Django 1.8, use list comprehension or an iterator to return decoded results.

You can also access group functions from a task result instance:

.. code-block:: python

from django_q.tasks import fetch

task = fetch('winter-speaker-alpha-ceiling')
if  task.group_count() > 100:
    print(task.group_result())
    task.group_delete()
    print('Deleted group {}'.format(task.group))

or call them directly on :class:AsyncTask object:

.. code-block:: python

from django_q.tasks import AsyncTask

# add a task to the math group and run it cached
a = AsyncTask('math.floor', 2.5, group='math', cached=True)

# wait until this tasks group has 10 results
result = a.result_group(count=10)

Reference

.. py:function:: result_group(group_id, failures=False, wait=0, count=None, cached=False)

Returns the results of a task group

:param str group_id: the group identifier
:param bool failures: set this to ``True`` to include failed results
:param int wait: optional milliseconds to wait for a result or count. -1 for indefinite
:param int count: block until there are this many results in the group
:param bool cached: run this against the cache backend
:returns: a list of results
:rtype: list

.. py:function:: fetch_group(group_id, failures=True, wait=0, count=None, cached=False)

Returns a list of tasks in a group

:param str group_id: the group identifier
:param bool failures: set this to ``False`` to exclude failed tasks
:param int wait: optional milliseconds to wait for a task or count. -1 for indefinite
:param int count: block until there are this many tasks in the group
:param bool cached: run this against the cache backend.
:returns: a list of :class:`Task`
:rtype: list

.. py:function:: count_group(group_id, failures=False, cached=False)

Counts the number of task results in a group.

:param str group_id: the group identifier
:param bool failures: counts the number of failures if ``True``
:param bool cached: run this against the cache backend.
:returns: the number of tasks or failures in a group
:rtype: int

.. py:function:: delete_group(group_id, tasks=False, cached=False)

Deletes a group label from the database.

:param str group_id: the group identifier
:param bool tasks: also deletes the associated tasks if ``True``
:param bool cached: run this against the cache backend.
:returns: the numbers of tasks affected
:rtype: int