Doc improvements

celery/schedules.py

@@ -66,9 +66,9 @@ class schedule(object):
 
         .. admonition:: Scheduler max interval variance
 
-        The default max loop interval may vary for different schedulers.
-        For the default scheduler the value is 5 minutes, but for e.g.
-        the django-celery database scheduler the value is 5 seconds.
+            The default max loop interval may vary for different schedulers.
+            For the default scheduler the value is 5 minutes, but for e.g.
+            the django-celery database scheduler the value is 5 seconds.
 
         """
         rem_delta = self.remaining_estimate(last_run_at)

docs/index.rst

@@ -14,7 +14,7 @@ Contents:
     :maxdepth: 1
 
     configuration
-    django
+    django/index
     cookbook/index
     django/index
     contributing

docs/internals/reference/celery.utils.patch.rst

@@ -1,11 +0,0 @@
-============================================
- celery.utils.patch
-============================================
-
-.. contents::
-    :local:
-.. currentmodule:: celery.utils.patch
-
-.. automodule:: celery.utils.patch
-    :members:
-    :undoc-members:

docs/internals/reference/index.rst

@@ -56,7 +56,6 @@
     celery.utils.term
     celery.utils.timeutils
     celery.utils.compat
-    celery.utils.patch
     celery.utils.serialization
     celery.utils.threads
     celery.utils.timer2

docs/reference/celery.rst

@@ -1,270 +1,395 @@
-.. currentmodule:: celery
+========
+ celery
+========
 
-.. automodule:: celery
+.. contents::
+    :local:
 
-    .. contents::
-        :local:
+Application
+-----------
 
-    Application
-    -----------
+.. class:: Celery(main=None, broker="amqp://guest:guest@localhost:5672//",
+                  loader="app", backend=None)
 
-    .. class:: Celery(main=None, broker="amqp://guest:guest@localhost:5672//",
-                      loader="app", backend=None)
+    :param main: Name of the main module if running as `__main__`.
+    :keyword broker: URL of the default broker used.
+    :keyword loader: The loader class, or the name of the loader class to use.
+                     Default is :class:`celery.loaders.app.AppLoader`.
+    :keyword backend: The result store backend class, or the name of the
+                      backend class to use. Default is the value of the
+                      :setting:`CELERY_RESULT_BACKEND` setting.
+    :keyword amqp: AMQP object or class name.
+    :keyword events: Events object or class name.
+    :keyword log: Log object or class name.
+    :keyword control: Control object or class name.
+    :keyword set_as_current:  Make this the global current app.
+    :keyword tasks: A task registry or the name of a registry class.
 
-        :param main: Name of the main module if running as `__main__`.
-        :keyword broker: URL of the default broker used.
-        :keyword loader: The loader class, or the name of the loader class to use.
-                         Default is :class:`celery.loaders.app.AppLoader`.
-        :keyword backend: The result store backend class, or the name of the
-                         backend class to use. Default is the value of the
-                        :setting:`CELERY_RESULT_BACKEND` setting.
-        :keyword amqp: AMQP object or class name.
-        :keyword events: Events object or class name.
-        :keyword log: Log object or class name.
-        :keyword control: Control object or class name.
-        :keyword set_as_current:  Make this the global current app.
-        :keyword tasks: A task registry or the name of a registry class.
+    .. attribute:: main
 
-        .. attribute:: main
+        Name of the `__main__` module.  Required for standalone scripts.
 
-            Name of the `__main__` module.  Required for standalone scripts.
+        If set this will be used instead of `__main__` when automatically
+        generating task names.
 
-            If set this will be used instead of `__main__` when automatically
-            generating task names.
+    .. attribute:: conf
 
-        .. attribute:: conf
+        Current configuration.
 
-            Current configuration.
+    .. attribute:: amqp
 
-        .. attribute:: amqp
+        AMQP related functionality: :class:`~@amqp`.
 
-            AMQP related functionality: :class:`~@amqp`.
+    .. attribute:: backend
 
-        .. attribute:: backend
+        Current backend instance.
 
-            Current backend instance.
+    .. attribute:: loader
 
-        .. attribute:: loader
+        Current loader instance.
 
-            Current loader instance.
-        .. attribute:: control
+    .. attribute:: control
 
-            Remote control: :class:`~@control`.
+        Remote control: :class:`~@control`.
 
-        .. attribute:: events
+    .. attribute:: events
 
-            Consuming and sending events: :class:`~@events`.
+        Consuming and sending events: :class:`~@events`.
 
-        .. attribute:: log
+    .. attribute:: log
 
-            Logging: :class:`~@log`.
+        Logging: :class:`~@log`.
 
-        .. attribute:: tasks
+    .. attribute:: tasks
 
-            Task registry.
+        Task registry.
 
-        .. attribute:: pool
+    .. attribute:: pool
 
-            Broker connection pool: :class:`~@pool`.
+        Broker connection pool: :class:`~@pool`.
 
-        .. attribute:: Task
+    .. attribute:: Task
 
-            Base task class for this app.
+        Base task class for this app.
 
+    .. method:: bugreport
 
-        .. method:: bugreport
+        Returns a string with information useful for the Celery core
+        developers when reporting a bug.
 
-            Returns a string with information useful for the Celery core
-            developers when reporting a bug.
+    .. method:: config_from_object(obj, silent=False)
 
-        .. method:: config_from_object(obj, silent=False)
+        Reads configuration from object, where object is either
+        an object or the name of a module to import.
 
-            Reads configuration from object, where object is either
-            an object or the name of a module to import.
+        :keyword silent: If true then import errors will be ignored.
 
-            :keyword silent: If true then import errors will be ignored.
+        .. code-block:: python
 
-            .. code-block:: python
+            >>> celery.config_from_object("myapp.celeryconfig")
 
-                >>> celery.config_from_object("myapp.celeryconfig")
+            >>> from myapp import celeryconfig
+            >>> celery.config_from_object(celeryconfig)
 
-                >>> from myapp import celeryconfig
-                >>> celery.config_from_object(celeryconfig)
+    .. method:: config_from_envvar(variable_name, silent=False)
 
-        .. method:: config_from_envvar(variable_name, silent=False)
+        Read configuration from environment variable.
 
-            Read configuration from environment variable.
+        The value of the environment variable must be the name
+        of a module to import.
 
-            The value of the environment variable must be the name
-            of a module to import.
+        .. code-block:: python
 
-            .. code-block:: python
+            >>> os.environ["CELERY_CONFIG_MODULE"] = "myapp.celeryconfig"
+            >>> celery.config_from_envvar("CELERY_CONFIG_MODULE")
 
-                >>> os.environ["CELERY_CONFIG_MODULE"] = "myapp.celeryconfig"
-                >>> celery.config_from_envvar("CELERY_CONFIG_MODULE")
+    .. method:: config_from_cmdline(argv, namespace="celery")
 
-        .. method:: config_from_cmdline(argv, namespace="celery")
+        Parses argv for configuration strings.
 
-            Parses argv for configuration strings.
+        Configuration strings must be located after a '--' sequence,
+        e.g.::
 
-            Configuration strings must be located after a '--' sequence,
-            e.g.::
+            program arg1 arg2 -- celeryd.concurrency=10
 
-                program arg1 arg2 -- celeryd.concurrency=10
+        :keyword namespace: Default namespace if omitted.
 
-            :keyword namespace: Default namespace if omitted.
+    .. method:: start(argv=None)
 
-        .. method:: start(argv=None)
-            Run :program:`celery` using `argv`.
+        Run :program:`celery` using `argv`.
 
-            Uses :data:`sys.argv` if `argv` is not specified.
+        Uses :data:`sys.argv` if `argv` is not specified.
 
-        .. method:: task(fun, **options)
-            Decorator to create a task class out of any callable.
+    .. method:: task(fun, **options)
 
-            **Examples:**
+        Decorator to create a task class out of any callable.
 
-            .. code-block:: python
+        **Examples:**
 
-                @task
-                def refresh_feed(url):
-                    return ...
+        .. code-block:: python
 
-            with setting extra options:
+            @task
+            def refresh_feed(url):
+                return ...
 
-            .. code-block:: python
+        with setting extra options:
 
-                @task(exchange="feeds")
-                def refresh_feed(url):
-                    return ...
+        .. code-block:: python
 
-            .. admonition:: App Binding
+            @task(exchange="feeds")
+            def refresh_feed(url):
+                return ...
 
-                For custom apps the task decorator returns proxy
-                objects, so that the act of creating the task is not performed
-                until the task is used or the task registry is accessed.
+        .. admonition:: App Binding
 
-                If you are depending on binding to be deferred, then you must
-                not access any attributes on the returned object until the
-                application is fully set up (finalized).
+            For custom apps the task decorator returns proxy
+            objects, so that the act of creating the task is not performed
+            until the task is used or the task registry is accessed.
 
+            If you are depending on binding to be deferred, then you must
+            not access any attributes on the returned object until the
+            application is fully set up (finalized).
 
-        .. method:: send_task(name, args=(), kwargs={}, countdown=None,
-                eta=None, task_id=None, publisher=None, connection=None,
-                result_cls=AsyncResult, expires=None, queues=None, **options)
 
-            Send task by **name**.
+    .. method:: send_task(name, args=(), kwargs={}, countdown=None,
+            eta=None, task_id=None, publisher=None, connection=None,
+            result_cls=AsyncResult, expires=None, queues=None, **options)
 
-            :param name: Name of task to execute (e.g. `"tasks.add"`).
-            :keyword result_cls: Specify custom result class. Default is
-                using :meth:`AsyncResult`.
+        Send task by **name**.
 
-            Otherwise supports the same arguments as :meth:`~@Task.apply_async`.
+        :param name: Name of task to execute (e.g. `"tasks.add"`).
+        :keyword result_cls: Specify custom result class. Default is
+            using :meth:`AsyncResult`.
 
-        .. attribute:: AsyncResult
+        Otherwise supports the same arguments as :meth:`~@Task.apply_async`.
 
-            Create new result instance. See :class:`~celery.result.AsyncResult`.
+    .. attribute:: AsyncResult
 
-        .. attribute:: TaskSetResult
+        Create new result instance. See :class:`~celery.result.AsyncResult`.
 
-            Create new taskset result instance.
-            See :class:`~celery.result.TaskSetResult`.
+    .. attribute:: TaskSetResult
 
-        .. method:: worker_main(argv=None)
+        Create new taskset result instance.
+        See :class:`~celery.result.TaskSetResult`.
 
-            Run :program:`celeryd` using `argv`.
+    .. method:: worker_main(argv=None)
 
-            Uses :data:`sys.argv` if `argv` is not specified."""
+        Run :program:`celeryd` using `argv`.
 
-        .. attribute:: Worker
+        Uses :data:`sys.argv` if `argv` is not specified."""
 
-            Worker application. See :class:`~@Worker`.
+    .. attribute:: Worker
 
-        .. attribute:: WorkController
+        Worker application. See :class:`~@Worker`.
 
-            Embeddable worker. See :class:`~@WorkController`.
+    .. attribute:: WorkController
 
-        .. attribute:: Beat
+        Embeddable worker. See :class:`~@WorkController`.
 
-            Celerybeat scheduler application.
-            See :class:`~@Beat`.
+    .. attribute:: Beat
 
-        .. method:: broker_connection(url="amqp://guest:guest@localhost:5672//",
-               ssl=False, transport_options={})
+        Celerybeat scheduler application.
+        See :class:`~@Beat`.
 
-            Establish a connection to the message broker.
+    .. method:: broker_connection(url="amqp://guest:guest@localhost:5672//",
+            ssl=False, transport_options={})
 
-            :param url: Either the URL or the hostname of the broker to use.
+        Establish a connection to the message broker.
 
-            :keyword hostname: defaults to the :setting:`BROKER_HOST` setting.
-            :keyword userid: defaults to the :setting:`BROKER_USER` setting.
-            :keyword password: defaults to the :setting:`BROKER_PASSWORD` setting.
-            :keyword virtual_host: defaults to the :setting:`BROKER_VHOST` setting.
-            :keyword port: defaults to the :setting:`BROKER_PORT` setting.
-            :keyword ssl: defaults to the :setting:`BROKER_USE_SSL` setting.
-            :keyword insist: defaults to the :setting:`BROKER_INSIST` setting.
-            :keyword backend_cls: defaults to the :setting:`BROKER_TRANSPORT`
-                setting.
+        :param url: Either the URL or the hostname of the broker to use.
 
-            :returns :class:`kombu.connection.BrokerConnection`:
+        :keyword hostname: defaults to the :setting:`BROKER_HOST` setting.
+        :keyword userid: defaults to the :setting:`BROKER_USER` setting.
+        :keyword password: defaults to the :setting:`BROKER_PASSWORD` setting.
+        :keyword virtual_host: defaults to the :setting:`BROKER_VHOST` setting.
+        :keyword port: defaults to the :setting:`BROKER_PORT` setting.
+        :keyword ssl: defaults to the :setting:`BROKER_USE_SSL` setting.
+        :keyword insist: defaults to the :setting:`BROKER_INSIST` setting.
+        :keyword backend_cls: defaults to the :setting:`BROKER_TRANSPORT`
+                 setting.
 
-        """
-        .. method:: default_connection(connection=None)
+        :returns :class:`kombu.connection.BrokerConnection`:
 
-            For use within a with-statement to get a connection from the pool
-            if one is not already provided.
+    .. method:: default_connection(connection=None)
 
-            :keyword connection: If not provided, then a connection will be
-                                 acquired from the connection pool.
+        For use within a with-statement to get a connection from the pool
+        if one is not already provided.
 
+        :keyword connection: If not provided, then a connection will be
+                             acquired from the connection pool.
 
-        .. method:: mail_admins(subject, body, fail_silently=False)
 
-            Sends an email to the admins in the :setting:`ADMINS` setting.
+    .. method:: mail_admins(subject, body, fail_silently=False)
 
-        .. method:: select_queues(queues=[])
+        Sends an email to the admins in the :setting:`ADMINS` setting.
 
-            Select a subset of queues, where queues must be a list of queue
-            names to keep.
+    .. method:: select_queues(queues=[])
 
-        .. method:: now()
+        Select a subset of queues, where queues must be a list of queue
+        names to keep.
 
-            Returns the current time and date as a :class:`~datetime.datetime`
-            object.
+    .. method:: now()
 
-        .. method:: set_current()
+        Returns the current time and date as a :class:`~datetime.datetime`
+        object.
 
-            Makes this the current app for this thread.
+    .. method:: set_current()
 
-        .. method:: finalize()
+        Makes this the current app for this thread.
 
-            Finalizes the app by loading built-in tasks,
-            and evaluating pending task decorators
+    .. method:: finalize()
 
-        .. attribute:: Pickler
+        Finalizes the app by loading built-in tasks,
+        and evaluating pending task decorators
 
-            Helper class used to pickle this application.
+    .. attribute:: Pickler
 
-    Grouping Tasks
-    --------------
+        Helper class used to pickle this application.
 
-    .. autofunction:: group
+Grouping Tasks
+--------------
 
-    .. autofunction:: chain
+.. class:: group(tasks=[])
 
-    .. autofunction:: chord
+    Creates a group of tasks to be executed in parallel.
 
-    .. autofunction:: subtask
+    Example::
 
-    Proxies
-    -------
+        >>> res = group([add.s(2, 2), add.s(4, 4)]).apply_async()
+        >>> res.get()
+        [4, 8]
 
-    .. data:: current_app
+    The ``apply_async`` method returns :class:`~@TaskSetResult`.
 
-        The currently set app for this thread.
+.. class:: chain(*tasks)
 
-    .. data:: current_task
+    Chains tasks together, so that each tasks follows each other
+    by being applied as a callback of the previous task.
 
-        The task currently being executed
-        (only set in the worker, or when eager/apply is used).
+    Example::
 
+        >>> res = chain(add.s(2, 2), add.s(4)).apply_async()
+
+    is effectively :math:`(2 + 2) + 4)`::
+
+        >>> res.get()
+        8
+
+    Applying a chain will return the result of the last task in the chain.
+    You can get to the other tasks by following the ``result.parent``'s::
+
+        >>> res.parent.get()
+        4
+
+.. class:: chord(header)(body)
+
+    A chord consists of a header and a body.
+    The header is a group of tasks that must complete before the callback is
+    called.  A chord is essentially a callback for a group of tasks.
+
+    Example::
+
+        >>> res = chord([add.s(2, 2), add.s(4, 4)])(sum_task.s())
+
+    is effectively :math:`\Sigma ((2 + 2) + (4 + 4))`::
+
+        >>> res.get()
+        12
+
+    The body is applied with the return values of all the header
+    tasks as a list.
+
+.. class:: subtask(task=None, args=(), kwargs={}, options={})
+
+    Describes the arguments and execution options for a single task invocation.
+
+    Used as the parts in a :class:`group` or to safely pass
+    tasks around as callbacks.
+
+    Subtasks can also be created from tasks::
+
+        >>> add.subtask(args=(), kwargs={}, options={})
+
+    or the ``.s()`` shortcut::
+
+        >>> add.s(*args, **kwargs)
+
+    :param task: Either a task class/instance, or the name of a task.
+    :keyword args: Positional arguments to apply.
+    :keyword kwargs: Keyword arguments to apply.
+    :keyword options: Additional options to :meth:`Task.apply_async`.
+
+    Note that if the first argument is a :class:`dict`, the other
+    arguments will be ignored and the values in the dict will be used
+    instead.
+
+        >>> s = subtask("tasks.add", args=(2, 2))
+        >>> subtask(s)
+        {"task": "tasks.add", args=(2, 2), kwargs={}, options={}}
+
+    .. method:: delay(*args, **kwargs)
+
+        Shortcut to :meth:`apply_async`.
+
+    .. method:: apply_async(args=(), kwargs={}, **options)
+
+        Apply this task asynchronously.
+
+        :keyword args: Partial args to be prepended to the existing args.
+        :keyword kwargs: Partial kwargs to be merged with the existing kwargs.
+        :keyword options: Partial options to be merged with the existing
+                          options.
+
+        See :meth:`~@Task.apply_async`.
+
+    .. method:: apply(args=(), kwargs={}, **options)
+
+        Same as :meth:`apply_async` but executes inline instead
+        of sending a task message.
+
+    .. method:: clone(args=(), kwargs={}, **options)
+
+        Returns a copy of this subtask.
+
+        :keyword args: Partial args to be prepended to the existing args.
+        :keyword kwargs: Partial kwargs to be merged with the existing kwargs.
+        :keyword options: Partial options to be merged with the existing
+                          options.
+
+    .. method:: replace(args=None, kwargs=None, options=None)
+
+        Replace the args, kwargs or options set for this subtask.
+        These are only replaced if the selected is not :const:`None`.
+
+    .. method:: link(other_subtask)
+
+        Add a callback task to be applied if this task
+        executes successfully.
+
+    .. method:: link_error(other_subtask)
+
+        Add a callback task to be applied if an error occurs
+        while executing this task.
+
+    .. method:: set(**options)
+
+        Set arbitrary options (same as ``.options.update(...)``).
+
+        This is a chaining method call (i.e. it returns itself).
+
+    .. method:: flatten_links()
+
+        Gives a recursive list of dependencies (unchain if you will,
+        but with links intact).
+
+Proxies
+-------
+
+.. data:: current_app
+
+    The currently set app for this thread.
+
+.. data:: current_task
+
+    The task currently being executed
+    (only set in the worker, or when eager/apply is used).

docs/userguide/tasks.rst

@@ -35,17 +35,17 @@ Task options can be specified as arguments to the decorator:
 
 .. admonition:: How do I import the task decorator?
 
-The task decorator is available on your Celery instance,
-if you don't know what that is then please read :ref:`first-steps`.
+    The task decorator is available on your Celery instance,
+    if you don't know what that is then please read :ref:`first-steps`.
 
-If you're using Django or are still using the "old" module based celery API,
-then you can import the task decorator like this::
+    If you're using Django or are still using the "old" module based celery API,
+    then you can import the task decorator like this::
 
-    from celery import task
+        from celery import task
 
-    @task
-    def add(x, y):
-        return x + y
+        @task
+        def add(x, y):
+            return x + y
 
 .. _task-request-info:
 

docs/whatsnew-2.6.rst

@@ -26,7 +26,7 @@ as well as PyPy and Jython.
 
 .. _`website`: http://celeryproject.org/
 .. _`django-celery changelog`: http://bit.ly/djcelery-26-changelog
-.. _`django-celery 2.5`: http://pypi.python.org/pypi/django-celery/
+.. _`django-celery 2.6`: http://pypi.python.org/pypi/django-celery/
 
 .. contents::
     :local: