Starting the new Extensions userguide

celery/bin/celerybeat.py

@@ -75,13 +75,16 @@ class BeatCommand(Command):
     def get_options(self):
         c = self.app.conf
 
-        return (
-            Option('--detach', action='store_true'),
-            Option('-s', '--schedule', default=c.CELERYBEAT_SCHEDULE_FILENAME),
-            Option('--max-interval', type='float'),
-            Option('-S', '--scheduler', dest='scheduler_cls'),
-            Option('-l', '--loglevel', default=c.CELERYBEAT_LOG_LEVEL),
-        ) + daemon_options(default_pidfile='celerybeat.pid')
+        return ((
+                Option('--detach', action='store_true'),
+                Option('-s', '--schedule',
+                    default=c.CELERYBEAT_SCHEDULE_FILENAME),
+                Option('--max-interval', type='float'),
+                Option('-S', '--scheduler', dest='scheduler_cls'),
+                Option('-l', '--loglevel', default=c.CELERYBEAT_LOG_LEVEL))
+            + daemon_options(default_pidfile='celerybeat.pid')
+            + tuple(self.app.user_options['beat'])
+        )
 
 
 def main():

celery/bin/celeryev.py

@@ -104,14 +104,17 @@ class EvCommand(Command):
         return set_process_title(prog, info=info)
 
     def get_options(self):
-        return (
-            Option('-d', '--dump', action='store_true'),
-            Option('-c', '--camera'),
-            Option('--detach', action='store_true'),
-            Option('-F', '--frequency', '--freq', type='float', default=1.0),
-            Option('-r', '--maxrate'),
-            Option('-l', '--loglevel', default='INFO'),
-        ) + daemon_options(default_pidfile='celeryev.pid')
+        return ((
+                Option('-d', '--dump', action='store_true'),
+                Option('-c', '--camera'),
+                Option('--detach', action='store_true'),
+                Option('-F', '--frequency', '--freq',
+                    type='float', default=1.0),
+                Option('-r', '--maxrate'),
+                Option('-l', '--loglevel', default='INFO'))
+            + daemon_options(default_pidfile='celeryev.pid')
+            + self.app.user_options['events']
+        )
 
 
 def main():

docs/reference/celery.rst

@@ -40,6 +40,16 @@ Application
 
         Current configuration.
 
+    .. attribute:: user_options
+
+        Custom options for command-line programs.
+        See :ref:`extending-commandoptions`
+
+    .. attribute:: steps
+
+        Custom bootsteps to extend and modify the worker.
+        See :ref:`extending-bootsteps`.
+
     .. attribute:: Celery.current_task
 
         The instance of the task that is being executed, or :const:`None`.

docs/userguide/extending.rst

@@ -0,0 +1,109 @@
+.. _guide-extending:
+
+==========================
+ Extensions and Bootsteps
+==========================
+
+.. contents::
+    :local:
+    :depth: 2
+
+.. _extending-bootsteps:
+
+Bootsteps
+=========
+
+.. _extending-programs:
+
+Command-line programs
+=====================
+
+.. _extending-commandoptions:
+
+Adding new command-line options
+-------------------------------
+
+You can add additional command-line options to the ``worker``, ``beat`` and
+``events`` commands by modifying the :attr:`~@Celery.user_options` attribute of the
+application instance.
+
+Celery commands uses the :mod:`optparse` module to parse command-line
+arguments, and so you have to use optparse specific option instances created
+using :func:`optparse.make_option`.  Please see the :mod:`optparse`
+documentation to read about the fields supported.
+
+Example adding a custom option to the :program:`celery worker` command:
+
+.. code-block:: python
+
+    from celery import Celery
+    from optparse import make_option as Option
+
+    celery = Celery(broker='amqp://')
+
+    celery.user_options['worker'].add(
+        Option('--enable-my-option', action='store_true', default=False,
+               help='Enable custom option.'),
+    )
+
+.. _extending-subcommands:
+
+Adding new :program:`celery` sub-commands
+-----------------------------------------
+
+New commands can be added to the :program:`celery` umbrella command by using
+`setuptools entry-points`_.
+
+.. _`setuptools entry-points`:
+    http://reinout.vanrees.org/weblog/2010/01/06/zest-releaser-entry-points.html
+
+
+Entry-points is special metadata that can be added to your packages ``setup.py`` program,
+and then after installation, read from the system using the :mod:`pkg_resources` module.
+
+Celery recognizes ``celery.commands`` entry-points to install additional
+subcommands, where the value of the entry-point must point to a valid subclass
+of :class:`celery.bin.base.Command`.  Sadly there is limited documentation,
+but you can find inspiration from the various commands in the
+:mod:`celery.bin` package.
+
+This is how the `Flower`_ extension adds the :program:`celery flower` command,
+by adding an entry-point in :file:`setup.py`:
+
+.. code-block:: python
+
+    setup(
+        name='flower',
+        entry_points={
+            'celery.commands': [
+               'flower = flower.command.FlowerCommand',
+            ],
+        }
+    )
+
+
+The command definition is in two parts separated by the equal sign, where the
+first part is the name of the subcommand (flower), then the fully qualified
+module path to the class that implements the command
+(``flower.command.FlowerCommand``).
+
+
+In the module :file:`flower/command.py`, the command class is defined
+something like this:
+
+
+    from celery.bin.base import Command, Option
+
+
+    class FlowerCommand(Command):
+
+        def get_options(self):
+            return (
+                Option('--port', default=8888, type='int',
+                    help='Webserver port',
+                ),
+                Option('--debug', action='store_true'),
+            )
+
+        def run(self, port=None, debug=False, **kwargs):
+            print('Running our command')

docs/userguide/index.rst

@@ -23,3 +23,4 @@
     optimizing
     concurrency/index
     signals
+    extending