[#2977] Add ckan.plugins.toolkit.enqueue_job.

ckan/plugins/toolkit.py

@@ -96,6 +96,8 @@ class _Toolkit(object):
         'auth_disallow_anonymous_access',
         # Helper not found error.
         'HelperError',
+        # Enqueue background job
+        'enqueue_job',
 
         # Fully defined in this file ##
         'add_template_directory',
@@ -134,6 +136,7 @@ def _initialize(self):
             CkanVersionException,
             HelperError
         )
+        from ckan.lib.jobs import enqueue as enqueue_job
 
         from paste.deploy import converters
         import pylons
@@ -271,6 +274,7 @@ def _initialize(self):
         t['check_ckan_version'] = self._check_ckan_version
         t['CkanVersionException'] = CkanVersionException
         t['HelperError'] = HelperError
+        t['enqueue_job'] = enqueue_job
 
         # check contents list correct
         errors = set(t).symmetric_difference(set(self.contents))

doc/extensions/best-practices.rst

@@ -10,6 +10,8 @@ Follow CKAN's coding standards
 See :doc:`/contributing/index`.
 
 
+.. _use the plugins toolkit:
+
 -------------------------------------------------
 Use the plugins toolkit instead of importing CKAN
 -------------------------------------------------

doc/extensions/plugins-toolkit.rst

@@ -1,3 +1,5 @@
+.. py:module:: ckan.plugins.toolkit
+
 -------------------------
 Plugins toolkit reference
 -------------------------

doc/maintaining/background-tasks.rst

@@ -80,6 +80,13 @@ Once you have a job function, all you need to do is to use
 This will place a job on the :ref:`job queue <background jobs queues>` where it
 can be picked up and executed by a worker.
 
+.. note::
+
+    Extensions should use :py:func:`ckan.plugins.toolkit.enqueue_job` instead.
+    It's the same function but accessing it via :py:mod:`ckan.plugins.toolkit`
+    :ref:`decouples your code from CKAN's internal structure <use the plugins
+    toolkit>`.
+
 The first argument to ``enqueue`` is the job function to use. The second is a
 list of the arguments which should be passed to the function. You can omit it
 in which case no arguments will be passed. You can also pass keyword arguments