Beat: Document django-celery-beat and the new ``-S django`` option

celery/beat.py

@@ -27,7 +27,7 @@ from .five import (
     items, monotonic, python_2_unicode_compatible, reraise, values,
 )
 from .schedules import maybe_schedule, crontab
-from .utils.imports import instantiate
+from .utils.imports import load_extension_class_names, symbol_by_name
 from .utils.timeutils import humanize_seconds
 from .utils.log import get_logger, iter_open_logger_fds
 
@@ -545,14 +545,15 @@ class Service(object):
         self._is_shutdown.set()
         wait and self._is_stopped.wait()  # block until shutdown done.
 
-    def get_scheduler(self, lazy=False):
+    def get_scheduler(self, lazy=False, extensions='celery.beat_schedulers'):
         filename = self.schedule_filename
-        scheduler = instantiate(self.scheduler_cls,
-                                app=self.app,
-                                schedule_filename=filename,
-                                max_interval=self.max_interval,
-                                lazy=lazy)
-        return scheduler
+        aliases = dict(load_extension_class_names(extensions) or {})
+        return symbol_by_name(self.scheduler_cls, aliases=aliases)(
+            app=self.app,
+            schedule_filename=filename,
+            max_interval=self.max_interval,
+            lazy=lazy,
+        )
 
     @cached_property
     def scheduler(self):

celery/bin/beat.py

@@ -83,7 +83,10 @@ class beat(Command):
 
             $ celery beat -l info
             $ celery beat -s /var/run/celery/beat-schedule --detach
-            $ celery beat -S djcelery.schedulers.DatabaseScheduler
+            $ celery beat -S django
+
+    The last example requires the :pypi:`django-celery-beat` extension
+    package found on PyPI.
     """
     doc = __doc__
     enable_config_from_cmdline = True

celery/utils/imports.py

@@ -138,18 +138,24 @@ def gen_task_name(app, name, module_name):
     return '.'.join(p for p in (module_name, name) if p)
 
 
-def load_extension_classes(namespace):
+def load_extension_class_names(namespace):
     try:
         from pkg_resources import iter_entry_points
     except ImportError:  # pragma: no cover
         return
 
     for ep in iter_entry_points(namespace):
-        sym = ':'.join([ep.module_name, ep.attrs[0]])
+        yield ep.name, ':'.join([ep.module_name, ep.attrs[0]])
+
+
+def load_extension_classes(namespace):
+    for name, class_name in load_extension_class_names(namespace):
         try:
-            cls = symbol_by_name(sym)
+            cls = symbol_by_name(class_name)
         except (ImportError, SyntaxError) as exc:
             warnings.warn(
-                'Cannot load extension {0!r}: {1!r}'.format(sym, exc))
+                'Cannot load {0} extension {1!r}: {2!r}'.format(
+                    namespace, class_name, exc))
         else:
-            yield ep.name, cls
+            yield name, cls
+

docs/userguide/periodic-tasks.rst

@@ -419,12 +419,38 @@ The default scheduler is the :class:`celery.beat.PersistentScheduler`,
 that simply keeps track of the last run times in a local :mod:`shelve`
 database file.
 
-:pypi:`django-celery` also ships with a scheduler that stores the schedule in
-the Django database:
+There's also the :pypi:`django-celery-beat` extension that stores the schedule
+in the Django database, and presents a convenient admin interface to manage
+periodic tasks at runtime.
 
-.. code-block:: console
+To install and use this extension:
+
+#. Use :command:`pip` to install the package:
+
+    .. code-block:: console
+
+        $ pip install django-celery-beat
+
+#. Add the ``django_celery_beat`` module to ``INSTALLED_APPS`` in your
+   Django project' :file:`settings.py`::
+
+        INSTALLED_APPS = (
+            ...,
+            'django_celery_beat',
+        )
+
+    Note that there is no dash in the module name, only underscores.
+
+#. Apply Django database migrations so that the necessary tables are created:
+
+    .. code-block:: console
+
+        $ python manage.py migrate
+
+#. Start the :program:`celery beat` service using the ``django`` scheduler:
+
+    .. code-block:: console
 
-    $ celery -A proj beat -S djcelery.schedulers.DatabaseScheduler
+        $ celery -A proj beat -l info -S django
 
-Using :pypi:`django-celery`'s scheduler you can add, modify, and remove
-periodic tasks from the Django Admin.
+#. Visit the Django-Admin interface to set up some periodic tasks.