docs: added Async class

Also moved Group, Iterable and Chain to their own pages because the Task page was getting too big.

v0.7.11

docs/group.rst

@@ -0,0 +1,125 @@
+.. py:currentmodule:: django_q
+
+Groups
+======
+You can group together results by passing :func:`async` the optional ``group`` keyword:
+
+.. code-block:: python
+
+    # result group example
+    from django_q.tasks import async, result_group
+
+    for i in range(4):
+        async('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:`Async` object:
+
+.. code-block:: python
+
+    from django_q.tasks import Async
+
+    # add a task to the math group and run it cached
+    a = Async('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