subtask docs now uses link=

docs/userguide/security.rst

@@ -37,8 +37,8 @@ allowing only white-listed machines to access it.
 
 Keep in mind that both firewall misconfiguration, and temproraily disabling
 the firewall, is common in the real world. Solid security policy includes
-monitoring of firewall equipment to detect if they have been disabled, be it 
-accidentally or on purpose. 
+monitoring of firewall equipment to detect if they have been disabled, be it
+accidentally or on purpose.
 
 In other words, one should not blindly trust the firewall either.
 
@@ -49,7 +49,7 @@ http://www.rabbitmq.com/access-control.html.
 Client
 ------
 
-In Celery, "client" refers to anything that sends messages to the 
+In Celery, "client" refers to anything that sends messages to the
 broker, e.g. web-servers that apply tasks.
 
 Having the broker properly secured doesn't matter if arbitrary messages
@@ -61,7 +61,7 @@ Worker
 ------
 
 The default permissions of tasks running inside a worker are the same ones as
-the privileges of the worker itself. This applies to resources such as 
+the privileges of the worker itself. This applies to resources such as
 memory, file-systems and devices.
 
 An exception to this rule is when using the multiprocessing based task pool,

docs/userguide/tasks.rst

@@ -25,8 +25,6 @@ Given a function create_user`, that takes two arguments: `username` and
 
     from django.contrib.auth import User
 
-    from celery.task import task
-
     @task
     def create_user(username, password):
         User.objects.create(username=username, password=password)
@@ -83,8 +81,6 @@ Example Usage
 
 ::
 
-    from celery.task import task
-
     @task
     def add(x, y):
         print("Executing task id %r, args: %r kwargs: %r" % (
@@ -1299,7 +1295,6 @@ blog/tasks.py
 .. code-block:: python
 
     from akismet import Akismet
-    from celery.task import task
 
     from django.core.exceptions import ImproperlyConfigured
     from django.contrib.sites.models import Site

docs/userguide/tasksets.rst

@@ -1,7 +1,7 @@
 .. _guide-sets:
 
 =======================================
- Sets of tasks, Subtasks and Callbacks
+ Groups, Chords, Chains and Callbacks
 =======================================
 
 .. contents::
@@ -40,24 +40,16 @@ This makes it excellent as a means to pass callbacks around to tasks.
 Callbacks
 ---------
 
-Let's improve our `add` task so it can accept a callback that
-takes the result as an argument::
+Callbacks can be added to any task using the ``link`` argument
+to ``apply_async``:
 
-    from celery.task import task
-    from celery.task.sets import subtask
+    add.apply_async((2, 2), link=other_task.subtask())
 
-    @task
-    def add(x, y, callback=None):
-        result = x + y
-        if callback is not None:
-            subtask(callback).delay(result)
-        return result
+The callback will only be applied if the task exited successfully,
+and it will be applied with the return value of the parent task as argument.
 
-:class:`~celery.task.sets.subtask` also knows how it should be applied,
-asynchronously by :meth:`~celery.task.sets.subtask.delay`, and
-eagerly by :meth:`~celery.task.sets.subtask.apply`.
 
-The best thing is that any arguments you add to `subtask.delay`,
+The best thing is that any arguments you add to `subtask`,
 will be prepended to the arguments specified by the subtask itself!
 
 If you have the subtask::
@@ -70,28 +62,29 @@ If you have the subtask::
 
 ...
 
-Now let's execute our new `add` task with a callback::
+Now let's execute our ``add`` task with a callback using partial
+arguments::
 
-    >>> add.delay(2, 2, callback=add.subtask((8, )))
+    >>> add.apply_async((2, 2), link=add.subtask((8, )))
 
 As expected this will first launch one task calculating :math:`2 + 2`, then
 another task calculating :math:`4 + 8`.
 
 .. _sets-taskset:
 
-Task Sets
-=========
+Groups
+======
 
-The :class:`~celery.task.sets.TaskSet` enables easy invocation of several
+The :class:`~celery.task.sets.group` enables easy invocation of several
 tasks at once, and is then able to join the results in the same order as the
 tasks were invoked.
 
-A task set takes a list of :class:`~celery.task.sets.subtask`'s::
+``group`` takes a list of :class:`~celery.task.sets.subtask`'s::
 
-    >>> from celery.task.sets import TaskSet
+    >>> from celery.task import group
     >>> from tasks import add
 
-    >>> job = TaskSet(tasks=[
+    >>> job = group([
     ...             add.subtask((4, 4)),
     ...             add.subtask((8, 8)),
     ...             add.subtask((16, 16)),
@@ -107,12 +100,16 @@ A task set takes a list of :class:`~celery.task.sets.subtask`'s::
     >>> result.join()
     [4, 8, 16, 32, 64]
 
+The first argument can alternatively be an iterator, like::
+
+    >>> group(add.subtask((i, i)) for i in range(100))
+
 .. _sets-results:
 
 Results
 -------
 
-When a  :class:`~celery.task.sets.TaskSet` is applied it returns a
+When a  :class:`~celery.task.sets.group` is applied it returns a
 :class:`~celery.result.TaskSetResult` object.
 
 :class:`~celery.result.TaskSetResult` takes a list of

docs/userguide/workers.rst

@@ -123,10 +123,10 @@ time limit kills it:
 
 .. code-block:: python
 
-    from celery.task import task
+    from myapp import celery
     from celery.exceptions import SoftTimeLimitExceeded
 
-    @task()
+    @celery.task()
     def mytask():
         try:
             do_work()
@@ -153,9 +153,8 @@ Example changing the time limit for the ``tasks.crawl_the_web`` task
 to have a soft time limit of one minute, and a hard time limit of
 two minutes::
 
-    >>> from celery.task import control
-    >>> control.time_limit("tasks.crawl_the_web",
-                           soft=60, hard=120, reply=True)
+    >>> celery.control.time_limit("tasks.crawl_the_web",
+                                  soft=60, hard=120, reply=True)
     [{'worker1.example.com': {'ok': 'time limits set successfully'}}]
 
 Only tasks that starts executing after the time limit change will be affected.
@@ -269,14 +268,15 @@ Some remote control commands also have higher-level interfaces using
 Sending the :control:`rate_limit` command and keyword arguments::
 
     >>> from celery.task.control import broadcast
-    >>> broadcast("rate_limit", arguments={"task_name": "myapp.mytask",
-    ...                                    "rate_limit": "200/m"})
+    >>> celery.control.broadcast("rate_limit",
+    ...                          arguments={"task_name": "myapp.mytask",
+    ...                                     "rate_limit": "200/m"})
 
 This will send the command asynchronously, without waiting for a reply.
 To request a reply you have to use the `reply` argument::
 
-    >>> broadcast("rate_limit", {"task_name": "myapp.mytask",
-    ...                          "rate_limit": "200/m"}, reply=True)
+    >>> celery.control.broadcast("rate_limit", {
+    ...     "task_name": "myapp.mytask", "rate_limit": "200/m"}, reply=True)
     [{'worker1.example.com': 'New rate limit set successfully'},
      {'worker2.example.com': 'New rate limit set successfully'},
      {'worker3.example.com': 'New rate limit set successfully'}]
@@ -284,10 +284,10 @@ To request a reply you have to use the `reply` argument::
 Using the `destination` argument you can specify a list of workers
 to receive the command::
 
-    >>> broadcast
-    >>> broadcast("rate_limit", {"task_name": "myapp.mytask",
-    ...                          "rate_limit": "200/m"}, reply=True,
-    ...           destination=["worker1.example.com"])
+    >>> celery.control.broadcast("rate_limit", {
+    ...     "task_name": "myapp.mytask",
+    ...     "rate_limit": "200/m"}, reply=True,
+    ...                             destination=["worker1.example.com"])
     [{'worker1.example.com': 'New rate limit set successfully'}]
 
 
@@ -305,13 +305,12 @@ Rate limits
 Example changing the rate limit for the `myapp.mytask` task to accept
 200 tasks a minute on all servers::
 
-    >>> from celery.task.control import rate_limit
-    >>> rate_limit("myapp.mytask", "200/m")
+    >>> celery.control.rate_limit("myapp.mytask", "200/m")
 
 Example changing the rate limit on a single host by specifying the
 destination host name::
 
-    >>> rate_limit("myapp.mytask", "200/m",
+    >>> celery.control.rate_limit("myapp.mytask", "200/m",
     ...            destination=["worker1.example.com"])
 
 .. warning::
@@ -344,14 +343,13 @@ Terminating a task also revokes it.
 
 ::
 
-    >>> from celery.task.control import revoke
-    >>> revoke("d9078da5-9915-40a0-bfa1-392c7bde42ed")
+    >>> celery.control.revoke("d9078da5-9915-40a0-bfa1-392c7bde42ed")
 
-    >>> revoke("d9078da5-9915-40a0-bfa1-392c7bde42ed",
-    ...        terminate=True)
+    >>> celery.control.revoke("d9078da5-9915-40a0-bfa1-392c7bde42ed",
+    ...                       terminate=True)
 
-    >>> revoke("d9078da5-9915-40a0-bfa1-392c7bde42ed",
-    ...        terminate=True, signal="SIGKILL")
+    >>> celery.control.revoke("d9078da5-9915-40a0-bfa1-392c7bde42ed",
+    ...                       terminate=True, signal="SIGKILL")
 
 .. control:: shutdown
 
@@ -360,8 +358,8 @@ Remote shutdown
 
 This command will gracefully shut down the worker remotely::
 
-    >>> broadcast("shutdown") # shutdown all workers
-    >>> broadcast("shutdown, destination="worker1.example.com")
+    >>> celery.control.broadcast("shutdown") # shutdown all workers
+    >>> celery.control.broadcast("shutdown, destination="worker1.example.com")
 
 .. control:: ping
 
@@ -373,8 +371,7 @@ The workers reply with the string 'pong', and that's just about it.
 It will use the default one second timeout for replies unless you specify
 a custom timeout::
 
-    >>> from celery.task.control import ping
-    >>> ping(timeout=0.5)
+    >>> celery.control.ping(timeout=0.5)
     [{'worker1.example.com': 'pong'},
      {'worker2.example.com': 'pong'},
      {'worker3.example.com': 'pong'}]
@@ -400,8 +397,8 @@ a worker using :program:`celeryev`/:program:`celerymon`.
 
 .. code-block:: python
 
-    >>> broadcast("enable_events")
-    >>> broadcast("disable_events")
+    >>> celery.control.broadcast("enable_events")
+    >>> celery.control.broadcast("disable_events")
 
 Adding/Reloading modules
 ------------------------
@@ -422,21 +419,23 @@ being imported by the worker processes:
 .. code-block:: python
 
     >>> from celery.task.control import broadcast
-    >>> broadcast("pool_restart", arguments={"modules": ["foo", "bar"]})
+    >>> celery.control.broadcast("pool_restart",
+    ...                          arguments={"modules": ["foo", "bar"]})
 
 Use the ``reload`` argument to reload modules it has already imported:
 
 .. code-block:: python
 
-    >>> broadcast("pool_restart", arguments={"modules": ["foo"],
-                                             "reload": True})
+    >>> celery.control.broadcast("pool_restart",
+    ...                          arguments={"modules": ["foo"],
+    ...                                     "reload": True})
 
 If you don't specify any modules then all known tasks modules will
 be imported/reloaded:
 
 .. code-block:: python
 
-    >>> broadcast("pool_restart", arguments={"reload": True})
+    >>> celery.control.broadcast("pool_restart", arguments={"reload": True})
 
 The ``modules`` argument is a list of modules to modify. ``reload``
 specifies whether to reload modules if they have previously been imported.
@@ -495,17 +494,15 @@ uses remote control commands under the hood.
 
 .. code-block:: python
 
-    >>> from celery.task.control import inspect
-
     # Inspect all nodes.
-    >>> i = inspect()
+    >>> i = celery.control.inspect()
 
     # Specify multiple nodes to inspect.
-    >>> i = inspect(["worker1.example.com", "worker2.example.com"])
+    >>> i = celery.control.inspect(["worker1.example.com",
+                                    "worker2.example.com"])
 
     # Specify a single node to inspect.
-    >>> i = inspect("worker1.example.com")
-
+    >>> i = celery.control.inspect("worker1.example.com")
 
 .. _worker-inspect-registered-tasks: