Merge lp:~acsone-openerp/openerp-connector/7.0-connector-parameterized-job-desciption into lp:~openerp-connector-core-editors/openerp-connector/7.0

[Laurent Mignon (Acsone)]

Improve Job description
=======================

Jobs are tasks to execute later. While the functionality is really robust and performs well, it is not always easy for the end user to visually distinguish the purpose of a job in the list of jobs. The description displayed in the list is computed from the documentation of the delayed function or from its name and there is no way to particularize this message by job instance.

This proposal aims to address this limitation by adding to the delay function a new optional parameter 'description'. The description given in the call to the delay function is used and displayed for the description of the job instead of the default one.

This proposal is backward compatible.

[Guewen Baconnier @ Camptocamp (gbaconnier-c2c)]

This is a very interesting improvement and well done!
Thanks

review: Approve (code review)

[Laurent Mignon (Acsone) (lmi)]

It's nice to contribute ;-)

On Mon, Nov 18, 2013 at 11:29 AM, Guewen Baconnier @ Camptocamp <
<email address hidden>> wrote:

> Review: Approve code review
>
> This is a very interesting improvement and well done!
> Thanks
> --
>
> https://code.launchpad.net/~acsone-openerp/openerp-connector/7.0-connector-parameterized-job-desciption/+merge/195572
> Your team Acsone OpenErp Team is subscribed to branch
> lp:~acsone-openerp/openerp-connector/7.0-connector-parameterized-job-desciption.
>

--
*Laurent Mignon*
*Senior Software Engineer*

*Tel : [phone]*
*Fax : [phone]*
*Gsm : [phone]*
*Email: <email address hidden> <email address hidden>*

*Acsone SA, Succursale de Luxembourg*
*22, Zone industrielle*
*L-8287 Kehlen, Luxembourg*
*www.acsone.eu <http://www.acsone.eu>*

[David BEAL (ak) (davidbeal)]

Good idea,

But perhaps we may use 'description' argument as complement of self.func.__doc__ or 'Function %s' and not instead of

[Stéphane Bidoul (Acsone) (sbi)]

This is working quite nicely in production already.

Nitpicking:
- * description : a human description of the job
+ * description : a human-readable description of the job,
+ intended to discriminate job instances

review: Approve

[lp:~acsone-openerp/openerp-connector/7.0-connector-parameterized-job-desciption]

600. By Laurent Mignon (Acsone) on 2013-11-18

little doc improvement as suggested by Stéphane Bidoul (Acsone) (sbi)

[Guewen Baconnier @ Camptocamp (gbaconnier-c2c)]

David Beal:
> Good idea,
>
> But perhaps we may use 'description' argument as complement of
> self.func.__doc__ or 'Function %s' and not instead of

Perhaps can you precise what you have in mind with some examples?
Appending them would give somewhat weird results (redundancy, unrelated messages).

We must keep things simple, this proposal stays simple while still allowing to fully customize the job descriptions. That's why a totally support it.

Laurent Mignon
> It's nice to contribute ;-)

Even more when the contribution is scrupulous about details (including tests, docs, ...) :-)

=== modified file 'connector/CHANGES.rst'
--- connector/CHANGES.rst	2013-10-09 18:52:36 +0000
+++ connector/CHANGES.rst	2013-11-18 14:29:22 +0000
@@ -4,6 +4,9 @@
 2.0.1.dev0
 ~~~~~~~~~~
 
+* Add a new optional keyword argument 'description' to the delay function of a job. If given, the description is used as name of the queue.job model stored in OpenErp 
+and displayed in the list of jobs.
+
 2.0.1 (2013-09-12)
 ~~~~~~~~~~~~~~~~~~
 
 
=== modified file 'connector/queue/job.py'
--- connector/queue/job.py	2013-10-28 15:17:17 +0000
+++ connector/queue/job.py	2013-11-18 14:29:22 +0000
@@ -102,9 +102,9 @@
             "Model %s not found" % self._job_model_name)
 
     def enqueue(self, func, model_name=None, args=None, kwargs=None,
-                priority=None, eta=None, max_retries=None):
+                priority=None, eta=None, max_retries=None, description=None):
         job = Job(func=func, model_name=model_name, args=args, kwargs=kwargs,
-                  priority=priority, eta=eta, max_retries=max_retries)
+                  priority=priority, eta=eta, max_retries=max_retries, description=description)
         job.user_id = self.session.uid
         self.store(job)
 
@@ -114,12 +114,14 @@
         eta = kwargs.pop('eta', None)
         model_name = kwargs.pop('model_name', None)
         max_retries = kwargs.pop('max_retries', None)
+        description = kwargs.pop('description', None)
 
         return self.enqueue(func, model_name=model_name,
                             args=args, kwargs=kwargs,
                             priority=priority,
                             max_retries=max_retries,
-                            eta=eta)
+                            eta=eta,
+                            description=description)
 
     def exists(self, job_uuid):
         """Returns if a job still exists in the storage."""
@@ -229,7 +231,7 @@
             eta = datetime.strptime(stored.eta, DEFAULT_SERVER_DATETIME_FORMAT)
 
         job = Job(func=func_name, args=args, kwargs=kwargs,
-                  priority=stored.priority, eta=eta, job_uuid=stored.uuid)
+                  priority=stored.priority, eta=eta, job_uuid=stored.uuid, description=stored.name)
 
         if stored.date_created:
             job.date_created = datetime.strptime(
@@ -360,7 +362,7 @@
 
     def __init__(self, func=None, model_name=None,
                  args=None, kwargs=None, priority=None,
-                 eta=None, job_uuid=None, max_retries=None):
+                 eta=None, job_uuid=None, max_retries=None, description=None):
         """ Create a Job
 
         :param func: function to execute
@@ -379,6 +381,8 @@
         :param job_uuid: UUID of the job
         :param max_retries: maximum number of retries before giving up and set
             the job state to 'failed'. A value of 0 means infinite retries.
+        :param description: human description of the job. If None, description
+            is computed from the function doc or name
         """
         if args is None:
             args = ()
@@ -423,6 +427,7 @@
             self.priority = DEFAULT_PRIORITY
 
         self.date_created = datetime.now()
+        self._description = description
         self.date_enqueued = None
         self.date_started = None
         self.date_done = None
@@ -483,7 +488,7 @@
 
     @property
     def description(self):
-        return self.func.__doc__ or 'Function %s' % self.func.__name__
+        return self._description or self.func.__doc__ or 'Function %s' % self.func.__name__
 
     @property
     def uuid(self):
@@ -597,7 +602,7 @@
      Arguments and keyword arguments which will be given to the called
      function once the job is executed. They should be ``pickle-able``.
 
-     There is 3 special and reserved keyword arguments that you can use:
+     There is 4 special and reserved keyword arguments that you can use:
 
      * priority: priority of the job, the smaller is the higher priority.
                  Default is 10.
@@ -606,6 +611,10 @@
                     infinite retries. Default is 5.
      * eta: the job can be executed only after this datetime
             (or now + timedelta if a timedelta or integer is given)
+     
+     * description : a human description of the job,
+                     intended to discriminate job instances
+                     (Default is the func.__doc__ or 'Function %s' % func.__name__)
 
     Example:
 
 
=== modified file 'connector/tests/test_job.py'
--- connector/tests/test_job.py	2013-03-04 12:22:57 +0000
+++ connector/tests/test_job.py	2013-11-18 14:29:22 +0000
@@ -20,6 +20,8 @@
 
 
 def task_a(session, model_name):
+    """ Task description
+    """
     pass
 
 
@@ -76,6 +78,22 @@
         result = job.perform(self.session)
         self.assertEqual(result, 'ok!')
 
+    def test_description(self):
+        """ If no description is given to the job, it
+        should be computed from the function
+        """
+        # if a doctstring is defined for the function
+        # it's used as description
+        job_a = Job(func=task_a)
+        self.assertEqual(job_a.description, task_a.__doc__)
+        # if no docstring, the description is computed
+        job_b = Job(func=task_b)
+        self.assertEqual(job_b.description, "Function task_b")
+        # case when we explicitly specify the description
+        description = "My description"
+        job_a = Job(func=task_a, description=description)
+        self.assertEqual(job_a.description, description)
+
     def test_retryable_error(self):
         job = Job(func=retryable_error_task,
                   max_retries=3)
@@ -112,7 +130,8 @@
                   args=('o', 'k'),
                   kwargs={'c': '!'},
                   priority=15,
-                  eta=eta)
+                  eta=eta,
+                  description="My description")
         job.user_id = 1
         storage = OpenERPJobStorage(self.session)
         storage.store(job)