From f7d30561a27759cec3b14afe07deea50c91a97eb Mon Sep 17 00:00:00 2001
From: Ilan Steemers <koed00@gmail.com>
Date: Wed, 16 Sep 2015 17:01:23 +0200
Subject: [PATCH] docs: group functions for task instances

updated group example to reflect easier syntax.
---
 docs/examples.rst |  4 ++--
 docs/tasks.rst    | 31 +++++++++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/examples.rst b/docs/examples.rst
index 4b9038d..9783d73 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -220,8 +220,8 @@ Adapted from `Sebastian Raschka's blog <http://sebastianraschka.com/Articles/201
 
     # wait for 100 results to return and print it.
     def parzen_hook(task):
-        if count_group('parzen') == 100:
-            print(result_group('parzen'))
+        if task.group_count() == 100:
+            print(task.group_result())
 
 
 Django Q is not optimized for distributed computing, but this example will give you an idea of what you can do with task :ref:`groups`.
diff --git a/docs/tasks.rst b/docs/tasks.rst
index 73dddf5..178cc77 100644
--- a/docs/tasks.rst
+++ b/docs/tasks.rst
@@ -127,8 +127,20 @@ Getting results by using :func:`result_group` is of course much faster than usin
 
 .. note::
 
-   Although :func:`fetch_group` returns a queryset, due to the nature of the PickleField , calling ``Queryset.values`` on it will return a list of encoded results.
-   Use list comprehension or an iterator instead.
+   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 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))
 
 Synchronous testing
 -------------------
@@ -318,6 +330,21 @@ Reference
 
             Time taken represents the time a task spends in the cluster, this includes any time it may have waited in the queue.
 
+    .. py:method:: group_result(failures=False)
+
+    Returns a list of results from this task's group.
+    Set failures to ``True`` to include failed results.
+
+    .. py:method:: group_count(failures=False)
+
+    Returns a count of the number of task results in this task's group.
+    Returns the number of failures when ``failures=True``
+
+    .. py:method:: group_delete(tasks=False)
+
+    Resets the group label on all the tasks in this task's group.
+    If ``tasks=True`` it will also delete the tasks in this group from the database, including itself.
+
     .. py:classmethod:: get_result(task_id)
 
     Gets a result directly by task uuid or name.