more documentation

Author: yashh

docs/source/class.rst

@@ -4,3 +4,17 @@ ResQ Classes
 ==========================================
 
 .. autoclass:: pyres.ResQ
+   :members:
+
+
+Job Classes
+=================
+
+.. autoclass:: pyres.job.Job
+   :members:
+
+Worker Classes
+=================
+
+.. autoclass:: pyres.worker.Worker
+   :members:

docs/source/example.rst

@@ -4,7 +4,10 @@
 
 Let's take a real wold example of a blog where comments need to be checked for
 spam check. When the comment is saved in the database, we create a job in the
-queue with comment data. Let's take a django model in this case.::
+queue with comment data. Let's take a django model in this case.
+
+.. code-block:: python
+   :linenos:
 
     class Comment(models.Model):
         name = Model.CharField()

docs/source/install.rst

@@ -3,10 +3,10 @@ Installation
 
 Requirements:
 --------------
-simplejson>=2.0.9  
-itty>=0.6.2   
-redis>=0.6.0   
-pystache>=0.1.0  
+simplejson>=2.0.9
+itty>=0.6.2
+redis>=0.6.0
+pystache>=0.1.0
 
 Make sure you install these requirements before proceeding. 
 

docs/source/intro.rst

@@ -6,11 +6,7 @@ message queue. Read_ the blog post from github about how they use resque in
 production. 
 
 :synopsis: Any job which takes a little while to run can be put on a message 
-queue. Read our :doc:`Example </example>` implementation of how a PyRes can be used to spam 
-check comments.
-
-
-
+queue. Read our :doc:`Example </example>` implementation of how a PyRes can be used to spam check comments.
 
 
 .. _resque: http://github.com/defunkt/resque#readme

pyres/__init__.py

@@ -50,7 +50,12 @@ class ResQ(object):
         >>> r = ResQ(server="192.168.1.10:6379", password="some_pwd")
             # Assuming redis is running on default port with no password
     
-    
+    **r** is a resque object on which we can enqueue tasks.::
+
+        >>>> r.enqueue(SomeClass, args)
+
+    SomeClass can be any python class with *perform* method and a *queue* 
+    attribute on it.
     """
     def __init__(self, server="localhost:6379", password=None, 
                  timeout=None, retry_connection=True):
@@ -109,6 +114,10 @@ def _set_redis(self, server):
     redis = property(_get_redis, _set_redis)
 
     def enqueue(self, klass, *args):
+        """
+        Enqueue a job into a specific queue. Make sure the class you are passing
+        has **queue** attribute and a **perform** method on it.
+        """
         queue = getattr(klass,'queue', None)
         #print cls._res
         if queue:
@@ -123,6 +132,10 @@ def queues(self):
         return self.redis.smembers("resque:queues")
 
     def info(self):
+        """
+        Returns a dictionary of the current status of the pending jobs, 
+        processed, no. of queues, no. of workers, no. of failed jobs.
+        """
         pending = 0
         for q in self.queues():
              pending += self.size(q)
@@ -183,6 +196,9 @@ def _enqueue(cls, klass, *args):
             #Job.create(queue, klass,*args)
 
 class Stat(object):
+    """
+    A Stat class which shows the current status of the queue.
+    """
     def __init__(self, name, resq):
         self.name = name
         self.key = "resque:stat:%s" % self.name

pyres/job.py

@@ -1,13 +1,20 @@
 from pyres import ResQ, str_to_class, safe_str_to_class
 from pyres import failure
 class Job(object):
+    """
+    Every job on the ResQ is a *Job* object which has queue and payload(all the
+    args data and when its created etc).
+    """
     def __init__(self, queue, payload, resq, worker=None):
         self._queue = queue
         self._payload = payload
         self.resq = resq
         self._worker = worker
 
     def perform(self):
+        """This method converts payload into args and calls the **perform** method
+        on the payload class.
+        """
         payload_class_str = self._payload["class"]
         payload_class = safe_str_to_class(payload_class_str)
         args = self._payload.get("args", None)
@@ -24,6 +31,8 @@ def fail(self, exception):
 
     @classmethod
     def reserve(cls, queue, res, worker=None):
+        """Reserve a job on the queue. In simple marking this job so that other worker
+        will not pick it up"""
         payload = res.pop(queue)
         if payload:
             return cls(queue, payload, res, worker)

pyres/worker.py

@@ -8,6 +8,13 @@
 import simplejson
 
 class Worker(object):
+    """
+    Defines a worker. The *pyres_worker* script instantiates this Worker class and
+    pass a comma seperate list of queues to listen on.::
+    
+       >>> from pyres.worker import Worker
+       >>> Worker.run([queue1, queue2], server="localhost:6379")
+    """
     def __init__(self, queues=[], server="localhost:6379", password=None):
         self.queues = queues
         self.validate_queues()
@@ -23,6 +30,7 @@ def __init__(self, queues=[], server="localhost:6379", password=None):
 
 
     def validate_queues(self):
+        "Checks if a worker is given atleast one queue to work on."
         if not self.queues:
             raise NoQueueError("Please give each worker at least one queue.")
 
@@ -82,6 +90,17 @@ def __str__(self):
         return '%s:%s:%s' % (hostname, self.pid, ','.join(self.queues))
 
     def work(self, interval=5):
+        """Invoked by run() method. work() listens on a list of queues and sleeps
+        for *interval* time. 
+        
+        default  --  5 secs
+        
+        Whenever a worker finds a job on the queue it first calls ``reserve`` on
+        that job to make sure other worker won't run it, then *Forks* itself to 
+        work on that job.
+        
+        Finally process() method actually processes the job.
+        """
         self.startup()
         while True:
             if self._shutdown: