Add API docs for the scheduler

1 files changed, 70 insertions, 78 deletions

diff --git a/sleekxmpp/xmlstream/scheduler.py b/sleekxmpp/xmlstream/scheduler.py
index 45d24272..4a6f073f 100644
--- a/sleekxmpp/xmlstream/scheduler.py
+++ b/sleekxmpp/xmlstream/scheduler.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.xmlstream.scheduler
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module provides a task scheduler that works better
+    with SleekXMPP's threading usage than the stock version.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 import time
@@ -24,50 +30,47 @@ class Task(object):
     A scheduled task that will be executed by the scheduler
     after a given time interval has passed.
 
-    Attributes:
-        name     -- The name of the task.
-        seconds  -- The number of seconds to wait before executing.
-        callback -- The function to execute.
-        args     -- The arguments to pass to the callback.
-        kwargs   -- The keyword arguments to pass to the callback.
-        repeat   -- Indicates if the task should repeat.
-                    Defaults to False.
-        qpointer -- A pointer to an event queue for queuing callback
+    :param string name: The name of the task.
+    :param int seconds: The number of seconds to wait before executing.
+    :param callback: The function to execute.
+    :param tuple args: The arguments to pass to the callback.
+    :param dict kwargs: The keyword arguments to pass to the callback.
+    :param bool repeat: Indicates if the task should repeat.
+                        Defaults to ``False``.
+    :param pointer: A pointer to an event queue for queuing callback
                     execution instead of executing immediately.
-
-    Methods:
-        run   -- Either queue or execute the callback.
-        reset -- Reset the task's timer.
     """
 
     def __init__(self, name, seconds, callback, args=None,
                  kwargs=None, repeat=False, qpointer=None):
-        """
-        Create a new task.
-
-        Arguments:
-            name     -- The name of the task.
-            seconds  -- The number of seconds to wait before executing.
-            callback -- The function to execute.
-            args     -- The arguments to pass to the callback.
-            kwargs   -- The keyword arguments to pass to the callback.
-            repeat   -- Indicates if the task should repeat.
-                        Defaults to False.
-            qpointer -- A pointer to an event queue for queuing callback
-                        execution instead of executing immediately.
-        """
+        #: The name of the task.
         self.name = name
+
+        #: The number of seconds to wait before executing.
         self.seconds = seconds
+
+        #: The function to execute once enough time has passed.
         self.callback = callback
+
+        #: The arguments to pass to :attr:`callback`.
         self.args = args or tuple()
+
+        #: The keyword arguments to pass to :attr:`callback`.
         self.kwargs = kwargs or {}
+        
+        #: Indicates if the task should repeat after executing,
+        #: using the same :attr:`seconds` delay.
         self.repeat = repeat
+
+        #: The time when the task should execute next.
         self.next = time.time() + self.seconds
+
+        #: The main event queue, which allows for callbacks to
+        #: be queued for execution instead of executing immediately.
         self.qpointer = qpointer
 
     def run(self):
-        """
-        Execute the task's callback.
+        """Execute the task's callback.
 
         If an event queue was supplied, place the callback in the queue;
         otherwise, execute the callback immediately.
@@ -81,9 +84,7 @@ class Task(object):
         return self.repeat
 
     def reset(self):
-        """
-        Reset the task's timer so that it will repeat.
-        """
+        """Reset the task's timer so that it will repeat."""
         self.next = time.time() + self.seconds
 
 
@@ -93,46 +94,41 @@ class Scheduler(object):
     A threaded scheduler that allows for updates mid-execution unlike the
     scheduler in the standard library.
 
-    http://docs.python.org/library/sched.html#module-sched
-
-    Attributes:
-        addq     -- A queue storing added tasks.
-        schedule -- A list of tasks in order of execution times.
-        thread   -- If threaded, the thread processing the schedule.
-        run      -- Indicates if the scheduler is running.
-        stop     -- Threading event indicating if the main process
-                    has been stopped.
-    Methods:
-        add     -- Add a new task to the schedule.
-        process -- Process and schedule tasks.
-        quit    -- Stop the scheduler.
+    Based on: http://docs.python.org/library/sched.html#module-sched
+
+    :param parentstop: An :class:`~threading.Event` to signal stopping
+                       the scheduler.
     """
 
     def __init__(self, parentstop=None):
-        """
-        Create a new scheduler.
-
-        Arguments:
-            parentstop -- A threading event indicating if the main process has
-                          been stopped.
-        """
+        #: A queue for storing tasks
         self.addq = queue.Queue()
+        
+        #: A list of tasks in order of execution time.
         self.schedule = []
+
+        #: If running in threaded mode, this will be the thread processing
+        #: the schedule.
         self.thread = None
+
+        #: A flag indicating that the scheduler is running.
         self.run = False
+
+        #: An :class:`~threading.Event` instance for signalling to stop
+        #: the scheduler.
         self.stop = parentstop
+
+        #: Lock for accessing the task queue.
         self.schedule_lock = threading.RLock()
 
     def process(self, threaded=True):
-        """
-        Begin accepting and processing scheduled tasks.
+        """Begin accepting and processing scheduled tasks.
 
-        Arguments:
-            threaded -- Indicates if the scheduler should execute in its own
-                        thread. Defaults to True.
+        :param bool threaded: Indicates if the scheduler should execute
+                              in its own thread. Defaults to ``True``.
         """
         if threaded:
-            self.thread = threading.Thread(name='sheduler_process',
+            self.thread = threading.Thread(name='scheduler_process',
                                            target=self._process)
             self.thread.start()
         else:
@@ -183,18 +179,16 @@ class Scheduler(object):
 
     def add(self, name, seconds, callback, args=None,
             kwargs=None, repeat=False, qpointer=None):
-        """
-        Schedule a new task.
-
-        Arguments:
-            name     -- The name of the task.
-            seconds  -- The number of seconds to wait before executing.
-            callback -- The function to execute.
-            args     -- The arguments to pass to the callback.
-            kwargs   -- The keyword arguments to pass to the callback.
-            repeat   -- Indicates if the task should repeat.
-                        Defaults to False.
-            qpointer -- A pointer to an event queue for queuing callback
+        """Schedule a new task.
+
+        :param string name: The name of the task.
+        :param int seconds: The number of seconds to wait before executing.
+        :param callback: The function to execute.
+        :param tuple args: The arguments to pass to the callback.
+        :param dict kwargs: The keyword arguments to pass to the callback.
+        :param bool repeat: Indicates if the task should repeat.
+                            Defaults to ``False``.
+        :param pointer: A pointer to an event queue for queuing callback
                         execution instead of executing immediately.
         """
         try:
@@ -211,12 +205,10 @@ class Scheduler(object):
             self.schedule_lock.release()
 
     def remove(self, name):
-        """
-        Remove a scheduled task ahead of schedule, and without
+        """Remove a scheduled task ahead of schedule, and without
         executing it.
 
-        Arguments:
-            name -- The name of the task to remove.
+        :param string name: The name of the task to remove.
         """
         try:
             self.schedule_lock.acquire()