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/chain.rst

@@ -0,0 +1,105 @@
+.. py:currentmodule:: django_q
+
+Chains
+======
+Sometimes you want to run tasks sequentially. For that you can use the :func:`async_chain` function:
+
+.. code-block:: python
+
+    # Async a chain of tasks
+    from django_q.tasks import async_chain, result_group
+
+    # the chain must be in the format
+    # [(func,(args),{kwargs}),(func,(args),{kwargs}),..]
+    group_id = async_chain([('math.copysign', (1, -1)),
+                            ('math.floor', (1,))])
+
+    # get group result
+    result_group(group_id, count=2)
+
+A slightly more convenient way is to use a :class:`Chain` instance:
+
+.. code-block:: python
+
+    # Chain async
+    from django_q.tasks import Chain
+
+    # create a chain that uses the cache backend
+    chain = Chain(cached=True)
+
+    # add some tasks
+    chain.append('math.copysign', 1, -1)
+    chain.append('math.floor', 1)
+
+    # run it
+    chain.run()
+
+    print(chain.result())
+.. code-block:: python
+
+    [-1.0, 1]
+
+Reference
+---------
+.. py:function:: async_chain(chain, group=None, cached=Conf.CACHED, sync=Conf.SYNC, broker=None)
+
+    Async a chain of tasks. See also the :class:`Chain` class.
+
+    :param list chain: a list of tasks in the format [(func,(args),{kwargs}), (func,(args),{kwargs})]
+    :param str group: an optional group name.
+    :param bool cached: run this against the cache backend
+    :param bool sync: execute this inline instead of asynchronous
+
+.. py:class:: Chain(chain=None, group=None, cached=Conf.CACHED, sync=Conf.SYNC)
+
+    A sequential chain of tasks. Acts as a convenient wrapper for :func:`async_chain`
+    You can pass the task chain at construction or you can append individual tasks before running them.
+
+        :param list chain: a list of task in the format [(func,(args),{kwargs}), (func,(args),{kwargs})]
+        :param str group: an optional group name.
+        :param bool cached: run this against the cache backend
+        :param bool sync: execute this inline instead of asynchronous
+
+
+    .. py:method:: append(func, *args, **kwargs)
+
+    Append a task to the chain. Takes the same arguments as :func:`async`
+
+        :return: the current number of tasks in the chain
+        :rtype: int
+
+
+    .. py:method:: run()
+
+    Start queueing the chain to the worker cluster.
+
+        :return: the chains group id
+
+
+    .. py:method:: result(wait=0)
+
+    return the full list of results from the chain when it finishes. Blocks until timeout or result.
+
+        :param int wait: how many milliseconds to wait for a result
+        :return: an unsorted list of results
+
+
+    .. py:method:: fetch(failures=True, wait=0)
+
+    get the task result objects from the chain when it finishes. Blocks until timeout or result.
+
+        :param failures: include failed tasks
+        :param int wait: how many milliseconds to wait for a result
+        :return: an unsorted list of task objects
+
+    .. py:method:: current()
+
+    get the index of the currently executing chain element
+
+        :return int: current chain index
+
+    .. py:method:: length()
+
+    get the length of the chain
+
+        :return int: length of the chain