Cleanup of some docstrings. Added a Failures page.

Fixed some formatting and included failure classes in the docs.

Author: aezell

docs/source/class.rst

@@ -4,17 +4,25 @@ ResQ Classes
 ==========================================
 
 .. autoclass:: pyres.ResQ
-   :members:
-
+	:members:
 
 Job Classes
 =================
 
 .. autoclass:: pyres.job.Job
-   :members:
+	:members:
 
 Worker Classes
 =================
 
 .. autoclass:: pyres.worker.Worker
-   :members:
+	:members:
+
+Failure Classes
+=================
+
+.. autoclass:: pyres.failure.base.BaseBackend
+	:members:
+	
+.. autoclass:: pyres.failure.RedisBackend
+	:members:

docs/source/example.rst

@@ -34,9 +34,9 @@ to do is add a :attr:`queue` attribute and define a :meth:`perform` method on th
 
 To insert a job into the queue you need to do something like this::
 
-    from pyres import ResQ
-    r = Resq()
-    r.enqueue(Spam, 23)   # Passing the comment id 23
+    >>> from pyres import ResQ
+    >>> r = Resq()
+    >>> r.enqueue(Spam, 23)   # Passing the comment id 23
 
 This puts a job into the queue **Spam**. Now we need to fire off our workers. 
 In the **scripts** folder there is an executable::

docs/source/index.rst

@@ -9,13 +9,15 @@ Welcome to pyres's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+	:maxdepth: 2
+
+	intro
+	install
+	example
+	class
+	tests
+	failures
 
-   intro
-   install
-   example
-   class
-   tests
 
 Indices and tables
 ==================

pyres/__init__.py

@@ -4,13 +4,15 @@
 import pyres.json_parser as json
 
 def my_import(name):
+    """Helper function for walking import calls when searching for classes by string names."""
     mod = __import__(name)    
     components = name.split('.')    
     for comp in components[1:]:        
         mod = getattr(mod, comp)    
     return mod
 
 def safe_str_to_class(s):
+    """Helper function to map string class names to module classes."""
     lst = s.split(".")
     klass = lst[-1]
     mod_list = lst[:-1]
@@ -25,6 +27,7 @@ def safe_str_to_class(s):
         return None
 
 def str_to_class(s):
+    """Alternate helper function to map string class names to module classes."""
     lst = s.split(".")
     klass = lst[-1]
     mod_list = lst[:-1]
@@ -39,8 +42,22 @@ def str_to_class(s):
         return None
 
 class ResQ(object):
-    """ResQ class which defines the Queue object to enqueue jobs into various
-    queues.
+    """The ResQ class defines the Redis server object to which we will
+    enqueue jobs into various queues.
+    
+    The ``__init__`` takes these keyword arguments:
+    
+        ``server`` -- IP address and port of the Redis server to which you want to connect. Default is `localhost:6379`.
+    
+        ``password`` -- The password, if required, of your Redis server. Default is "None".
+    
+        ``timeout`` -- The timeout keyword is in the signature, but is unused. Default is "None".
+    
+        ``retry_connection`` -- This keyword is in the signature but is deprecated. Default is "True".
+    
+    
+    Both ``timeout`` and ``retry_connection`` will be removed as the python-redis client
+    no longer uses them. 
     
     Example usage::
 
@@ -52,8 +69,9 @@ class ResQ(object):
 
         >>>> r.enqueue(SomeClass, args)
 
-    SomeClass can be any python class with *perform* method and a *queue* 
+    SomeClass can be any python class with a *perform* method and a *queue* 
     attribute on it.
+    
     """
     def __init__(self, server="localhost:6379", password=None, 
                  timeout=None, retry_connection=True):
@@ -110,9 +128,9 @@ 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
+        """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
@@ -128,9 +146,9 @@ def queues(self):
         return self.redis.smembers("resque:queues") or []
 
     def info(self):
-        """
-        Returns a dictionary of the current status of the pending jobs, 
+        """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():
@@ -170,8 +188,8 @@ def remove_queue(self, queue):
         del self.redis['resque:queue:%s' % queue]
 
     def close(self):
-        """
-        close the underlying redis connection
+        """Close the underlying redis connection.
+        
         """
         self.redis.disconnect()
 
@@ -198,8 +216,8 @@ def _enqueue(cls, klass, *args):
             #Job.create(queue, klass,*args)
 
 class Stat(object):
-    """
-    A Stat class which shows the current status of the queue.
+    """A Stat class which shows the current status of the queue.
+    
     """
     def __init__(self, name, resq):
         self.name = name

pyres/extensions.py

@@ -8,6 +8,7 @@
 
 from pyres.exceptions import NoQueueError
 from pyres.worker import Worker
+
 class JuniorWorker(Worker):
     def work(self, interval=5):
         self.startup()

pyres/failure/__init__.py

@@ -2,7 +2,9 @@
 from pyres import ResQ 
 import sys, traceback
 from pyres.failure.redis import RedisBackend
+
 _backend = RedisBackend
+
 def create(*args, **kwargs):
     return _backend(*args, **kwargs)
 

pyres/failure/base.py

@@ -2,6 +2,20 @@
 import traceback
 
 class BaseBackend(object):
+    """Provides a base class that custom backends can subclass. Also provides basic
+    traceback and message parsing.
+    
+    The ``__init__`` takes these keyword arguments:
+    
+        ``exp`` -- The exception generated by your failure.
+        
+        ``queue`` -- The queue in which the ``Job`` was enqueued when it failed.
+        
+        ``payload`` -- The payload that was passed to the ``Job``.
+        
+        ``worker`` -- The worker that was processing the ``Job`` when it failed.
+    
+    """
     def __init__(self, exp, queue, payload, worker=None):
         excc, _, tb = sys.exc_info()
 

pyres/failure/redis.py

@@ -1,8 +1,12 @@
 import datetime
 from base import BaseBackend
 from pyres import ResQ
+
 class RedisBackend(BaseBackend):
+    """Extends the ``BaseBackend`` to provide a Redis backend for failed jobs."""
+    
     def save(self, resq=None):
+        """Saves the failed Job into a "failed" Redis queue preserving all its original enqueud info."""
         if not resq:
             resq = ResQ()
         data = {

pyres/job.py

@@ -1,9 +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).
+    """Every job on the ResQ is an instance of the *Job* class.
+    
+    The ``__init__`` takes these keyword arguments:
+    
+        ``queue`` -- A string defining the queue to which this Job will be added.
+    
+        ``payload`` -- A dictionary which contains the string name of a class which extends this Job and
+        a list of args which will be passed to that class.
+        
+        ``resq`` -- An instance of the ResQ class.
+    
+        ``worker`` -- The name of a specific worker if you'd like this Job to be done by that worker. Default is "None".
+    
     """
     def __init__(self, queue, payload, resq, worker=None):
         self._queue = queue
@@ -12,8 +23,9 @@ def __init__(self, queue, payload, resq, worker=None):
         self._worker = worker
 
     def perform(self):
-        """This method converts payload into args and calls the **perform** method
+        """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)
@@ -25,15 +37,20 @@ def perform(self):
             return payload_class.perform()
 
     def fail(self, exception):
-        #Failure.create(exception)
+        """This method provides a way to fail a job and will use whatever failure backend
+        you've provided. The default is the ``RedisBackend``.
+        
+        """
         fail = failure.create(exception, self._queue, self._payload, self._worker)
         fail.save(self.resq)
         return fail
 
     @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"""
+        """Reserve a job on the queue. This marks this job so that other workers
+        will not pick it up.
+        
+        """
         payload = res.pop(queue)
         if payload:
             return cls(queue, payload, res, worker)

pyres/worker.py

@@ -8,12 +8,12 @@
 import json_parser as json
 
 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.::
+    """Defines a worker. The ``pyres_worker`` script instantiates this Worker class and
+    passes a comma-separated 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
@@ -30,7 +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."
+        """Checks if a worker is given at least one queue to work on."""
         if not self.queues:
             raise NoQueueError("Please give each worker at least one queue.")
 
@@ -90,16 +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. 
+        """Invoked by ``run`` method. ``work`` listens on a list of queues and sleeps
+        for ``interval`` time. 
         
-        default  --  5 secs
+        ``interval`` -- Number of seconds the worker will wait until processing the next job. Default is "5".
         
         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 
+        that job to make sure another worker won't run it, then *forks* itself to 
         work on that job.
         
-        Finally process() method actually processes the job.
+        Finally, the ``process`` method actually processes the job by eventually calling the Job instance's ``perform`` method.
+        
         """
         self.startup()
         while True: